|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH TRAP "1P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
trap
|
|
Packit |
7cfc04 |
\(em trap signals
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
trap \fIn \fB[\fIcondition\fR...\fB]\fR
|
|
Packit |
7cfc04 |
trap \fB[\fIaction condition\fR...\fB]\fR
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
If the first operand is an unsigned decimal integer, the shell shall
|
|
Packit |
7cfc04 |
treat all operands as conditions, and shall reset each condition to
|
|
Packit |
7cfc04 |
the default value. Otherwise, if there are operands, the first is
|
|
Packit |
7cfc04 |
treated as an action and the remaining as conditions.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR action
|
|
Packit |
7cfc04 |
is
|
|
Packit |
7cfc04 |
.BR '\(mi' ,
|
|
Packit |
7cfc04 |
the shell shall reset each
|
|
Packit |
7cfc04 |
.IR condition
|
|
Packit |
7cfc04 |
to the default value. If
|
|
Packit |
7cfc04 |
.IR action
|
|
Packit |
7cfc04 |
is null (\c
|
|
Packit |
7cfc04 |
.BR \(dq\^\(dq ),
|
|
Packit |
7cfc04 |
the shell shall ignore each specified
|
|
Packit |
7cfc04 |
.IR condition
|
|
Packit |
7cfc04 |
if it arises. Otherwise, the argument
|
|
Packit |
7cfc04 |
.IR action
|
|
Packit |
7cfc04 |
shall be read and executed by the shell when one of the corresponding
|
|
Packit |
7cfc04 |
conditions arises. The action of
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
shall override a previous action (either default action or one
|
|
Packit |
7cfc04 |
explicitly set). The value of
|
|
Packit |
7cfc04 |
.BR \(dq$?\(dq
|
|
Packit |
7cfc04 |
after the
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
action completes shall be the value it had before
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
was invoked.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The condition can be EXIT, 0 (equivalent to EXIT), or a signal
|
|
Packit |
7cfc04 |
specified using a symbolic name, without the SIG prefix, as listed in
|
|
Packit |
7cfc04 |
the tables of signal names in the
|
|
Packit |
7cfc04 |
.IR <signal.h>
|
|
Packit |
7cfc04 |
header defined in the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Chapter 13" ", " "Headers";
|
|
Packit |
7cfc04 |
for example, HUP, INT, QUIT, TERM. Implementations may permit names with
|
|
Packit |
7cfc04 |
the SIG prefix or ignore case in signal names as an extension. Setting
|
|
Packit |
7cfc04 |
a trap for SIGKILL or SIGSTOP produces undefined results.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The environment in which the shell executes a
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
on EXIT shall be identical to the environment immediately after the
|
|
Packit |
7cfc04 |
last command executed before the
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
on EXIT was taken.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Each time
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
is invoked, the
|
|
Packit |
7cfc04 |
.IR action
|
|
Packit |
7cfc04 |
argument shall be processed in a manner equivalent to:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
eval \fIaction\fR
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Signals that were ignored on entry to a non-interactive shell cannot be
|
|
Packit |
7cfc04 |
trapped or reset, although no error need be reported when attempting to
|
|
Packit |
7cfc04 |
do so. An interactive shell may reset or catch signals ignored on
|
|
Packit |
7cfc04 |
entry. Traps shall remain in place for a given shell until explicitly
|
|
Packit |
7cfc04 |
changed with another
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
command.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
When a subshell is entered, traps that are not being ignored shall be
|
|
Packit |
7cfc04 |
set to the default actions, except in the case of a command substitution
|
|
Packit |
7cfc04 |
containing only a single
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
command, when the traps need not be altered. Implementations may check
|
|
Packit |
7cfc04 |
for this case using only lexical analysis; for example, if
|
|
Packit |
7cfc04 |
.IR `trap`
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR "$( trap -- )"
|
|
Packit |
7cfc04 |
do not alter the traps in the subshell, cases such as assigning
|
|
Packit |
7cfc04 |
.IR var=trap
|
|
Packit |
7cfc04 |
and then using
|
|
Packit |
7cfc04 |
.IR $($var)
|
|
Packit |
7cfc04 |
may still alter them. This does not imply that the
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
command cannot be used within the subshell to set new traps.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
command with no operands shall write to standard output a list of commands
|
|
Packit |
7cfc04 |
associated with each condition. If the command is executed in a subshell,
|
|
Packit |
7cfc04 |
the implementation does not perform the optional check described above
|
|
Packit |
7cfc04 |
for a command substitution containing only a single
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
command, and no
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
commands with operands have been executed since entry to the subshell,
|
|
Packit |
7cfc04 |
the list shall contain the commands that were associated with each
|
|
Packit |
7cfc04 |
condition immediately before the subshell environment was entered.
|
|
Packit |
7cfc04 |
Otherwise, the list shall contain the commands currently associated with
|
|
Packit |
7cfc04 |
each condition. The format shall be:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
"trap \(mi\|\(mi %s %s ...\en", <\fIaction\fR>, <\fIcondition\fR> ...
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The shell shall format the output, including the proper use of quoting,
|
|
Packit |
7cfc04 |
so that it is suitable for reinput to the shell as commands that
|
|
Packit |
7cfc04 |
achieve the same trapping results. For example:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
save_traps=$(trap)
|
|
Packit |
7cfc04 |
\&...
|
|
Packit |
7cfc04 |
eval "$save_traps"
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
XSI-conformant systems also allow numeric signal numbers for the
|
|
Packit |
7cfc04 |
conditions corresponding to the following signal names:
|
|
Packit |
7cfc04 |
.IP 1 6
|
|
Packit |
7cfc04 |
SIGHUP
|
|
Packit |
7cfc04 |
.IP 2 6
|
|
Packit |
7cfc04 |
SIGINT
|
|
Packit |
7cfc04 |
.IP 3 6
|
|
Packit |
7cfc04 |
SIGQUIT
|
|
Packit |
7cfc04 |
.IP 6 6
|
|
Packit |
7cfc04 |
SIGABRT
|
|
Packit |
7cfc04 |
.IP 9 6
|
|
Packit |
7cfc04 |
SIGKILL
|
|
Packit |
7cfc04 |
.IP 14 6
|
|
Packit |
7cfc04 |
SIGALRM
|
|
Packit |
7cfc04 |
.IP 15 6
|
|
Packit |
7cfc04 |
SIGTERM
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
special built-in shall conform to the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
|
|
Packit |
7cfc04 |
.SH OPTIONS
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH OPERANDS
|
|
Packit |
7cfc04 |
See the DESCRIPTION.
|
|
Packit |
7cfc04 |
.SH STDIN
|
|
Packit |
7cfc04 |
Not used.
|
|
Packit |
7cfc04 |
.SH "INPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "ASYNCHRONOUS EVENTS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.SH STDOUT
|
|
Packit |
7cfc04 |
See the DESCRIPTION.
|
|
Packit |
7cfc04 |
.SH STDERR
|
|
Packit |
7cfc04 |
The standard error shall be used only for diagnostic messages.
|
|
Packit |
7cfc04 |
.SH "OUTPUT FILES"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXTENDED DESCRIPTION"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "EXIT STATUS"
|
|
Packit |
7cfc04 |
If the trap name
|
|
Packit |
7cfc04 |
or number
|
|
Packit |
7cfc04 |
is invalid, a non-zero exit status shall be returned; otherwise, zero
|
|
Packit |
7cfc04 |
shall be returned. For both interactive and non-interactive shells,
|
|
Packit |
7cfc04 |
invalid signal names
|
|
Packit |
7cfc04 |
or numbers
|
|
Packit |
7cfc04 |
shall not be considered a syntax error and do not cause the shell to
|
|
Packit |
7cfc04 |
abort.
|
|
Packit |
7cfc04 |
.SH "CONSEQUENCES OF ERRORS"
|
|
Packit |
7cfc04 |
Default.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
Write out a list of all traps and actions:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Set a trap so the
|
|
Packit |
7cfc04 |
.IR logout
|
|
Packit |
7cfc04 |
utility in the directory referred to by the
|
|
Packit |
7cfc04 |
.IR HOME
|
|
Packit |
7cfc04 |
environment variable executes when the shell terminates:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap '"$HOME"/logout' EXIT
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
or:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap '"$HOME"/logout' 0
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Unset traps on INT, QUIT, TERM, and EXIT:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap \(mi INT QUIT TERM EXIT
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.SH "RATIONALE"
|
|
Packit |
7cfc04 |
Implementations may permit lowercase signal names as an extension.
|
|
Packit |
7cfc04 |
Implementations may also accept the names with the SIG prefix; no known
|
|
Packit |
7cfc04 |
historical shell does so. The
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR kill
|
|
Packit |
7cfc04 |
utilities in this volume of POSIX.1\(hy2008 are now consistent in their omission of the SIG
|
|
Packit |
7cfc04 |
prefix for signal names. Some
|
|
Packit |
7cfc04 |
.IR kill
|
|
Packit |
7cfc04 |
implementations do not allow the prefix, and
|
|
Packit |
7cfc04 |
.IR kill
|
|
Packit |
7cfc04 |
.BR \(mil
|
|
Packit |
7cfc04 |
lists the signals without prefixes.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Trapping SIGKILL or SIGSTOP is syntactically accepted by some
|
|
Packit |
7cfc04 |
historical implementations, but it has no effect. Portable POSIX
|
|
Packit |
7cfc04 |
applications cannot attempt to trap these signals.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The output format is not historical practice. Since the output of
|
|
Packit |
7cfc04 |
historical
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
commands is not portable (because numeric signal values are not
|
|
Packit |
7cfc04 |
portable) and had to change to become so, an opportunity was taken to
|
|
Packit |
7cfc04 |
format the output in a way that a shell script could use to save and
|
|
Packit |
7cfc04 |
then later reuse a trap if it wanted.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The KornShell uses an
|
|
Packit |
7cfc04 |
.BR ERR
|
|
Packit |
7cfc04 |
trap that is triggered whenever
|
|
Packit |
7cfc04 |
.IR set
|
|
Packit |
7cfc04 |
.BR \(mie
|
|
Packit |
7cfc04 |
would cause an exit. This is allowable as an extension, but was not
|
|
Packit |
7cfc04 |
mandated, as other shells have not used it.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The text about the environment for the EXIT trap invalidates the
|
|
Packit |
7cfc04 |
behavior of some historical versions of interactive shells which, for
|
|
Packit |
7cfc04 |
example, close the standard input before executing a trap on 0. For
|
|
Packit |
7cfc04 |
example, in some historical interactive shell sessions the following
|
|
Packit |
7cfc04 |
trap on 0 would always print
|
|
Packit |
7cfc04 |
.BR \(dq\(mi\|\(mi\(dq :
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap 'read foo; echo "\(mi$foo\(mi"' 0
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The command:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap 'eval " $cmd"' 0
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
causes the contents of the shell variable
|
|
Packit |
7cfc04 |
.IR cmd
|
|
Packit |
7cfc04 |
to be executed as a command when the shell exits. Using:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap '$cmd' 0
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
does not work correctly if
|
|
Packit |
7cfc04 |
.IR cmd
|
|
Packit |
7cfc04 |
contains any special characters such as quoting or redirections. Using:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
trap " $cmd" 0
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
also works (the leading
|
|
Packit |
7cfc04 |
<space>
|
|
Packit |
7cfc04 |
character protects against unlikely cases where
|
|
Packit |
7cfc04 |
.IR cmd
|
|
Packit |
7cfc04 |
is a decimal integer or begins with
|
|
Packit |
7cfc04 |
.BR '\(mi' ),
|
|
Packit |
7cfc04 |
but it expands the
|
|
Packit |
7cfc04 |
.IR cmd
|
|
Packit |
7cfc04 |
variable when the
|
|
Packit |
7cfc04 |
.IR trap
|
|
Packit |
7cfc04 |
command is executed, not when the exit action is executed.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "Section 2.14" ", " "Special Built-In Utilities"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 12.2" ", " "Utility Syntax Guidelines",
|
|
Packit |
7cfc04 |
.IR "\fB<signal.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|