1TRAP(1P)                   POSIX Programmer's Manual                  TRAP(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       trap - trap signals
13

SYNOPSIS

15       trap [action condition ...]
16

DESCRIPTION

18       If action is '-', the shell shall reset each condition to  the  default
19       value.  If action is null ( "" ), the shell shall ignore each specified
20       condition if it arises. Otherwise, the argument action  shall  be  read
21       and  executed  by  the  shell  when one of the corresponding conditions
22       arises. The action of trap shall override  a  previous  action  (either
23       default action or one explicitly set). The value of "$?" after the trap
24       action completes shall be the value it had before trap was invoked.
25
26       The condition can be EXIT, 0 (equivalent to EXIT), or a  signal  speci‐
27       fied  using  a  symbolic name, without the SIG prefix, as listed in the
28       tables of signal names in the <signal.h> header  defined  in  the  Base
29       Definitions  volume  of  IEEE Std 1003.1-2001, Chapter 13, Headers; for
30       example, HUP, INT, QUIT, TERM. Implementations may  permit  names  with
31       the  SIG prefix or ignore case in signal names as an extension. Setting
32       a trap for SIGKILL or SIGSTOP produces undefined results.
33
34       The environment in which the shell executes a trap  on  EXIT  shall  be
35       identical  to  the  environment immediately after the last command exe‐
36       cuted before the trap on EXIT was taken.
37
38       Each time trap is invoked, the action argument shall be processed in  a
39       manner equivalent to:
40
41
42              eval action
43
44       Signals that were ignored on entry to a non-interactive shell cannot be
45       trapped or reset, although no error need be reported when attempting to
46       do  so.  An  interactive  shell  may  reset or catch signals ignored on
47       entry. Traps shall remain in place for a given shell  until  explicitly
48       changed with another trap command.
49
50       When a subshell is entered, traps that are not being ignored are set to
51       the default actions. This does not imply that the trap  command  cannot
52       be used within the subshell to set new traps.
53
54       The  trap  command  with  no arguments shall write to standard output a
55       list of commands associated with each condition. The format shall be:
56
57
58              "trap -- %s %s ...\n", <action>, <condition> ...
59
60       The shell shall format the output, including the proper use of quoting,
61       so  that  it  is  suitable  for  reinput  to the shell as commands that
62       achieve the same trapping results. For example:
63
64
65              save_traps=$(trap)
66              ...
67              eval "$save_traps"
68
69       XSI-conformant systems also allow numeric signal numbers for the condi‐
70       tions corresponding to the following signal names:
71
72                             Signal Number   Signal Name
73                             1               SIGHUP
74                             2               SIGINT
75                             3               SIGQUIT
76                             6               SIGABRT
77                             9               SIGKILL
78                             14              SIGALRM
79                             15              SIGTERM
80
81       The  trap special built-in shall conform to the Base Definitions volume
82       of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
83

OPTIONS

85       None.
86

OPERANDS

88       See the DESCRIPTION.
89

STDIN

91       Not used.
92

INPUT FILES

94       None.
95

ENVIRONMENT VARIABLES

97       None.
98

ASYNCHRONOUS EVENTS

100       Default.
101

STDOUT

103       See the DESCRIPTION.
104

STDERR

106       The standard error shall be used only for diagnostic messages.
107

OUTPUT FILES

109       None.
110

EXTENDED DESCRIPTION

112       None.
113

EXIT STATUS

115       If the trap name  or number  is invalid, a non-zero exit  status  shall
116       be  returned;  otherwise, zero shall be returned.  For both interactive
117       and non-interactive shells, invalid signal names  or numbers  shall not
118       be considered a syntax error and do not cause the shell to abort.
119

CONSEQUENCES OF ERRORS

121       Default.
122
123       The following sections are informative.
124

APPLICATION USAGE

126       None.
127

EXAMPLES

129       Write out a list of all traps and actions:
130
131
132              trap
133
134       Set  a  trap  so the logout utility in the directory referred to by the
135       HOME environment variable executes when the shell terminates:
136
137
138              trap '$HOME/logout' EXIT
139
140       or:
141
142
143              trap '$HOME/logout' 0
144
145       Unset traps on INT, QUIT, TERM, and EXIT:
146
147
148              trap - INT QUIT TERM EXIT
149

RATIONALE

151       Implementations may permit lowercase  signal  names  as  an  extension.
152       Implementations may also accept the names with the SIG prefix; no known
153       historical shell does so. The trap and kill utilities in this volume of
154       IEEE Std 1003.1-2001  are  now  consistent in their omission of the SIG
155       prefix for signal names. Some kill implementations  do  not  allow  the
156       prefix, and kill -l lists the signals without prefixes.
157
158       Trapping  SIGKILL or SIGSTOP is syntactically accepted by some histori‐
159       cal implementations, but it has no effect. Portable POSIX  applications
160       cannot attempt to trap these signals.
161
162       The  output format is not historical practice. Since the output of his‐
163       torical trap commands is not portable (because  numeric  signal  values
164       are  not  portable)  and had to change to become so, an opportunity was
165       taken to format the output in a way that a shell script  could  use  to
166       save and then later reuse a trap if it wanted.
167
168       The  KornShell uses an ERR trap that is triggered whenever set -e would
169       cause an exit. This is allowable as an extension, but was not mandated,
170       as other shells have not used it.
171
172       The text about the environment for the EXIT trap invalidates the behav‐
173       ior of some historical versions of interactive shells which, for  exam‐
174       ple,  close  the standard input before executing a trap on 0. For exam‐
175       ple, in some historical interactive shell sessions the  following  trap
176       on 0 would always print "--" :
177
178
179              trap 'read foo; echo "-$foo-"' 0
180

FUTURE DIRECTIONS

182       None.
183

SEE ALSO

185       Special Built-In Utilities
186
188       Portions  of  this text are reprinted and reproduced in electronic form
189       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
190       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
191       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
192       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
193       event of any discrepancy between this version and the original IEEE and
194       The  Open Group Standard, the original IEEE and The Open Group Standard
195       is the referee document. The original Standard can be  obtained  online
196       at http://www.opengroup.org/unix/online.html .
197
198
199
200IEEE/The Open Group                  2003                             TRAP(1P)
Impressum