Import of man-pages 1.70man-pages-1.70

1 files changed, 240 insertions, 0 deletions

diff --git a/man1p/trap.1p b/man1p/trap.1p
new file mode 100644
index 000000000..18bcefb93
--- /dev/null
+++ b/man1p/trap.1p
@@ -0,0 +1,240 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "TRAP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" trap 
+.SH NAME
+trap \- trap signals
+.SH SYNOPSIS
+.LP
+\fBtrap\fP \fB[\fP\fIaction condition\fP \fB...\fP\fB]\fP
+.SH DESCRIPTION
+.LP
+If \fIaction\fP is \fB'-'\fP , the shell shall reset each \fIcondition\fP
+to the default value. If \fIaction\fP is null (
+\fB""\fP ), the shell shall ignore each specified \fIcondition\fP
+if it arises. Otherwise, the argument \fIaction\fP shall be
+read and executed by the shell when one of the corresponding conditions
+arises. The action of \fItrap\fP shall override a previous
+action (either default action or one explicitly set). The value of
+\fB"$?"\fP after the \fItrap\fP action completes shall be
+the value it had before \fItrap\fP was invoked.
+.LP
+The condition can be EXIT, 0 (equivalent to EXIT), or a signal specified
+using a symbolic name, without the SIG prefix, as
+listed in the tables of signal names in the \fI<signal.h>\fP header
+defined in the
+Base Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 13, Headers;
+for example, HUP, INT, QUIT, TERM. Implementations may permit names
+with the SIG prefix or ignore case in signal names as an
+extension. Setting a trap for SIGKILL or SIGSTOP produces undefined
+results.
+.LP
+The environment in which the shell executes a \fItrap\fP on EXIT shall
+be identical to the environment immediately after the
+last command executed before the \fItrap\fP on EXIT was taken.
+.LP
+Each time \fItrap\fP is invoked, the \fIaction\fP argument shall be
+processed in a manner equivalent to:
+.sp
+.RS
+.nf
+
+\fBeval\fP \fIaction\fP
+.fi
+.RE
+.LP
+Signals that were ignored on entry to a non-interactive shell cannot
+be trapped or reset, although no error need be reported
+when attempting to do so. An interactive shell may reset or catch
+signals ignored on entry. Traps shall remain in place for a given
+shell until explicitly changed with another \fItrap\fP command.
+.LP
+When a subshell is entered, traps that are not being ignored are set
+to the default actions. This does not imply that the
+\fItrap\fP command cannot be used within the subshell to set new traps.
+.LP
+The \fItrap\fP command with no arguments shall write to standard output
+a list of commands associated with each condition. The
+format shall be:
+.sp
+.RS
+.nf
+
+\fB"trap -- %s %s ...\\n", <\fP\fIaction\fP\fB>, <\fP\fIcondition\fP\fB> ...
+\fP
+.fi
+.RE
+.LP
+The shell shall format the output, including the proper use of quoting,
+so that it is suitable for reinput to the shell as
+commands that achieve the same trapping results. For example:
+.sp
+.RS
+.nf
+
+\fBsave_traps=$(trap)
+\&...
+eval "$save_traps"
+\fP
+.fi
+.RE
+.LP
+XSI-conformant systems also allow numeric signal numbers for the conditions
+corresponding to the following signal names: 
+.TS C
+center; l l.
+\fBSignal Number\fP	\fBSignal Name\fP
+1	SIGHUP
+2	SIGINT
+3	SIGQUIT
+6	SIGABRT
+9	SIGKILL
+14	SIGALRM
+15	SIGTERM
+.TE
+.LP
+The \fItrap\fP special built-in shall conform to the Base Definitions
+volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
+.SH OPTIONS
+.LP
+None.
+.SH OPERANDS
+.LP
+See the DESCRIPTION.
+.SH STDIN
+.LP
+Not used.
+.SH INPUT FILES
+.LP
+None.
+.SH ENVIRONMENT VARIABLES
+.LP
+None.
+.SH ASYNCHRONOUS EVENTS
+.LP
+Default.
+.SH STDOUT
+.LP
+See the DESCRIPTION.
+.SH STDERR
+.LP
+The standard error shall be used only for diagnostic messages.
+.SH OUTPUT FILES
+.LP
+None.
+.SH EXTENDED DESCRIPTION
+.LP
+None.
+.SH EXIT STATUS
+.LP
+If the trap name   \ or number  is invalid, a non-zero
+exit status shall be returned; otherwise, zero shall be returned.
+For both interactive and non-interactive shells, invalid signal
+names   \ or numbers  shall not be considered a syntax error and do
+not cause the shell to abort.
+.SH CONSEQUENCES OF ERRORS
+.LP
+Default.
+.LP
+\fIThe following sections are informative.\fP
+.SH APPLICATION USAGE
+.LP
+None.
+.SH EXAMPLES
+.LP
+Write out a list of all traps and actions:
+.sp
+.RS
+.nf
+
+\fBtrap
+\fP
+.fi
+.RE
+.LP
+Set a trap so the \fIlogout\fP utility in the directory referred to
+by the \fIHOME\fP
+environment variable executes when the shell terminates:
+.sp
+.RS
+.nf
+
+\fBtrap '$HOME/logout' EXIT
+\fP
+.fi
+.RE
+.LP
+or:
+.sp
+.RS
+.nf
+
+\fBtrap '$HOME/logout' 0
+\fP
+.fi
+.RE
+.LP
+Unset traps on INT, QUIT, TERM, and EXIT:
+.sp
+.RS
+.nf
+
+\fBtrap - INT QUIT TERM EXIT
+\fP
+.fi
+.RE
+.SH RATIONALE
+.LP
+Implementations may permit lowercase signal names as an extension.
+Implementations may also accept the names with the SIG
+prefix; no known historical shell does so. The \fItrap\fP and \fIkill\fP
+utilities in this
+volume of IEEE\ Std\ 1003.1-2001 are now consistent in their omission
+of the SIG prefix for signal names. Some \fIkill\fP implementations
+do not allow the prefix, and \fIkill\fP \fB-l\fP lists the signals
+without prefixes.
+.LP
+Trapping SIGKILL or SIGSTOP is syntactically accepted by some historical
+implementations, but it has no effect. Portable POSIX
+applications cannot attempt to trap these signals.
+.LP
+The output format is not historical practice. Since the output of
+historical \fItrap\fP commands is not portable (because
+numeric signal values are not portable) and had to change to become
+so, an opportunity was taken to format the output in a way that
+a shell script could use to save and then later reuse a trap if it
+wanted.
+.LP
+The KornShell uses an \fBERR\fP trap that is triggered whenever \fIset\fP
+\fB-e\fP would
+cause an exit. This is allowable as an extension, but was not mandated,
+as other shells have not used it.
+.LP
+The text about the environment for the EXIT trap invalidates the behavior
+of some historical versions of interactive shells
+which, for example, close the standard input before executing a trap
+on 0. For example, in some historical interactive shell
+sessions the following trap on 0 would always print \fB"--"\fP :
+.sp
+.RS
+.nf
+
+\fBtrap 'read foo; echo "-$foo-"' 0
+\fP
+.fi
+.RE
+.SH FUTURE DIRECTIONS
+.LP
+None.
+.SH SEE ALSO
+.LP
+\fISpecial Built-In Utilities\fP
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group. In the
+event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .