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 n [condition...]
16       trap [action condition...]
17

DESCRIPTION

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
24       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
32       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
40       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
44       Each  time trap is invoked, the action argument shall be processed in a
45       manner equivalent to:
46
47
48           eval action
49
50       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
56       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
65       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
75
76           "trap -- %s %s ...\n", <action>, <condition> ...
77
78       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
82
83           save_traps=$(trap)
84           ...
85           eval "$save_traps"
86
87       XSI-conformant systems also allow numeric signal numbers for the condi‐
88       tions corresponding to the following signal names:
89
90       1     SIGHUP
91
92       2     SIGINT
93
94       3     SIGQUIT
95
96       6     SIGABRT
97
98       9     SIGKILL
99
100       14    SIGALRM
101
102       15    SIGTERM
103
104       The trap special built-in shall conform to the Base Definitions  volume
105       of POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
106

OPTIONS

108       None.
109

OPERANDS

111       See the DESCRIPTION.
112

STDIN

114       Not used.
115

INPUT FILES

117       None.
118

ENVIRONMENT VARIABLES

120       None.
121

ASYNCHRONOUS EVENTS

123       Default.
124

STDOUT

126       See the DESCRIPTION.
127

STDERR

129       The standard error shall be used only for diagnostic messages.
130

OUTPUT FILES

132       None.
133

EXTENDED DESCRIPTION

135       None.
136

EXIT STATUS

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

CONSEQUENCES OF ERRORS

144       Default.
145
146       The following sections are informative.
147

APPLICATION USAGE

149       None.
150

EXAMPLES

152       Write out a list of all traps and actions:
153
154
155           trap
156
157       Set a trap so the logout utility in the directory referred  to  by  the
158       HOME environment variable executes when the shell terminates:
159
160
161           trap '"$HOME"/logout' EXIT
162
163       or:
164
165
166           trap '"$HOME"/logout' 0
167
168       Unset traps on INT, QUIT, TERM, and EXIT:
169
170
171           trap - INT QUIT TERM EXIT
172

RATIONALE

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
181       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
185       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
191       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
195       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
201
202           trap 'read foo; echo "-$foo-"' 0
203
204       The command:
205
206
207           trap 'eval " $cmd"' 0
208
209       causes the contents of the shell variable cmd to be executed as a  com‐
210       mand when the shell exits. Using:
211
212
213           trap '$cmd' 0
214
215       does  not work correctly if cmd contains any special characters such as
216       quoting or redirections. Using:
217
218
219           trap " $cmd" 0
220
221       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

FUTURE DIRECTIONS

227       None.
228

SEE ALSO

230       Section 2.14, Special Built-In Utilities
231
232       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
246       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 .
250
251
252
253IEEE/The Open Group                  2017                             TRAP(1P)
Impressum