1TRAP(1P) POSIX Programmer's Manual TRAP(1P)
2
3
4
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
12 trap - trap signals
13
15 trap [action condition ...]
16
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
85 None.
86
88 See the DESCRIPTION.
89
91 Not used.
92
94 None.
95
97 None.
98
100 Default.
101
103 See the DESCRIPTION.
104
106 The standard error shall be used only for diagnostic messages.
107
109 None.
110
112 None.
113
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
121 Default.
122
123 The following sections are informative.
124
126 None.
127
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
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
182 None.
183
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)