1TRAP(1P) POSIX Programmer's Manual TRAP(1P)
2
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 n [condition...]
16 trap [action condition...]
17
19 If the first operand is an unsigned decimal integer, the shell shall
20 treat all operands as conditions, and shall reset each condition to the
21 default value. Otherwise, if there are operands, the first is treated
22 as an action and the remaining as conditions.
23 If action is '-', the shell shall reset each condition to the default
25 value. If action is null (""), the shell shall ignore each specified
26 condition if it arises. Otherwise, the argument action shall be read
27 and executed by the shell when one of the corresponding conditions
28 arises. The action of trap shall override a previous action (either
29 default action or one explicitly set). The value of "$?" after the trap
30 action completes shall be the value it had before trap was invoked.
31 The condition can be EXIT, 0 (equivalent to EXIT), or a signal speci‐
33 fied using a symbolic name, without the SIG prefix, as listed in the
34 tables of signal names in the <signal.h> header defined in the Base
35 Definitions volume of POSIX.1‐2017, Chapter 13, Headers; for example,
36 HUP, INT, QUIT, TERM. Implementations may permit names with the SIG
37 prefix or ignore case in signal names as an extension. Setting a trap
38 for SIGKILL or SIGSTOP produces undefined results.
39 The environment in which the shell executes a trap on EXIT shall be
41 identical to the environment immediately after the last command exe‐
42 cuted before the trap on EXIT was taken.
43 Each time trap is invoked, the action argument shall be processed in a
45 manner equivalent to:
46 eval action
49 Signals that were ignored on entry to a non-interactive shell cannot be
51 trapped or reset, although no error need be reported when attempting to
52 do so. An interactive shell may reset or catch signals ignored on
53 entry. Traps shall remain in place for a given shell until explicitly
54 changed with another trap command.
55 When a subshell is entered, traps that are not being ignored shall be
57 set to the default actions, except in the case of a command substitu‐
58 tion containing only a single trap command, when the traps need not be
59 altered. Implementations may check for this case using only lexical
60 analysis; for example, if `trap` and $( trap -- ) do not alter the
61 traps in the subshell, cases such as assigning var=trap and then using
62 $($var) may still alter them. This does not imply that the trap command
63 cannot be used within the subshell to set new traps.
64 The trap command with no operands shall write to standard output a list
66 of commands associated with each condition. If the command is executed
67 in a subshell, the implementation does not perform the optional check
68 described above for a command substitution containing only a single
69 trap command, and no trap commands with operands have been executed
70 since entry to the subshell, the list shall contain the commands that
71 were associated with each condition immediately before the subshell
72 environment was entered. Otherwise, the list shall contain the com‐
73 mands currently associated with each condition. The format shall be:
74 "trap -- %s %s ...\n", <action>, <condition> ...
77 The shell shall format the output, including the proper use of quoting,
79 so that it is suitable for reinput to the shell as commands that
80 achieve the same trapping results. For example:
81 save_traps=$(trap)
84 ...
85 eval "$save_traps"
86 XSI-conformant systems also allow numeric signal numbers for the condi‐
88 tions corresponding to the following signal names:
89 1 SIGHUP
91 2 SIGINT
93 3 SIGQUIT
95 6 SIGABRT
97 9 SIGKILL
99 14 SIGALRM
101 15 SIGTERM
103 The trap special built-in shall conform to the Base Definitions volume
105 of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
106
108 None.
109
111 See the DESCRIPTION.
112
114 Not used.
115
117 None.
118
120 None.
121
123 Default.
124
126 See the DESCRIPTION.
127
129 The standard error shall be used only for diagnostic messages.
130
132 None.
133
135 None.
136
138 If the trap name or number is invalid, a non-zero exit status shall be
139 returned; otherwise, zero shall be returned. For both interactive and
140 non-interactive shells, invalid signal names or numbers shall not be
141 considered a syntax error and do not cause the shell to abort.
142
144 Default.
145 The following sections are informative.
147
149 None.
150
152 Write out a list of all traps and actions:
153 trap
156 Set a trap so the logout utility in the directory referred to by the
158 HOME environment variable executes when the shell terminates:
159 trap '"$HOME"/logout' EXIT
162 or:
164 trap '"$HOME"/logout' 0
167 Unset traps on INT, QUIT, TERM, and EXIT:
169 trap - INT QUIT TERM EXIT
172
174 Implementations may permit lowercase signal names as an extension.
175 Implementations may also accept the names with the SIG prefix; no known
176 historical shell does so. The trap and kill utilities in this volume of
177 POSIX.1‐2017 are now consistent in their omission of the SIG prefix for
178 signal names. Some kill implementations do not allow the prefix, and
179 kill -l lists the signals without prefixes.
180 Trapping SIGKILL or SIGSTOP is syntactically accepted by some histori‐
182 cal implementations, but it has no effect. Portable POSIX applications
183 cannot attempt to trap these signals.
184 The output format is not historical practice. Since the output of his‐
186 torical trap commands is not portable (because numeric signal values
187 are not portable) and had to change to become so, an opportunity was
188 taken to format the output in a way that a shell script could use to
189 save and then later reuse a trap if it wanted.
190 The KornShell uses an ERR trap that is triggered whenever set -e would
192 cause an exit. This is allowable as an extension, but was not mandated,
193 as other shells have not used it.
194 The text about the environment for the EXIT trap invalidates the behav‐
196 ior of some historical versions of interactive shells which, for exam‐
197 ple, close the standard input before executing a trap on 0. For exam‐
198 ple, in some historical interactive shell sessions the following trap
199 on 0 would always print "--":
200 trap 'read foo; echo "-$foo-"' 0
203 The command:
205 trap 'eval " $cmd"' 0
208 causes the contents of the shell variable cmd to be executed as a com‐
210 mand when the shell exits. Using:
211 trap '$cmd' 0
214 does not work correctly if cmd contains any special characters such as
216 quoting or redirections. Using:
217 trap " $cmd" 0
220 also works (the leading <space> character protects against unlikely
222 cases where cmd is a decimal integer or begins with '-'), but it
223 expands the cmd variable when the trap command is executed, not when
224 the exit action is executed.
225
227 None.
228
230 Section 2.14, Special Built-In Utilities
231 The Base Definitions volume of POSIX.1‐2017, Section 12.2, Utility Syn‐
233 tax Guidelines, <signal.h>
234
236 Portions of this text are reprinted and reproduced in electronic form
237 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
238 table Operating System Interface (POSIX), The Open Group Base Specifi‐
239 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
240 Electrical and Electronics Engineers, Inc and The Open Group. In the
241 event of any discrepancy between this version and the original IEEE and
242 The Open Group Standard, the original IEEE and The Open Group Standard
243 is the referee document. The original Standard can be obtained online
244 at http://www.opengroup.org/unix/online.html .
245 Any typographical or formatting errors that appear in this page are
247 most likely to have been introduced during the conversion of the source
248 files to man page format. To report such errors, see https://www.ker‐
249 nel.org/doc/man-pages/reporting_bugs.html .
250IEEE/The Open Group 2017 TRAP(1P)