logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

trap.1p (8828B)


  1. '\" et
  2. .TH TRAP "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. trap
  12. \(em trap signals
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. trap \fIn \fB[\fIcondition\fR...\fB]\fR
  17. trap \fB[\fIaction condition\fR...\fB]\fR
  18. .fi
  19. .SH DESCRIPTION
  20. If the first operand is an unsigned decimal integer, the shell shall
  21. treat all operands as conditions, and shall reset each condition to
  22. the default value. Otherwise, if there are operands, the first is
  23. treated as an action and the remaining as conditions.
  24. .P
  25. If
  26. .IR action
  27. is
  28. .BR '\-' ,
  29. the shell shall reset each
  30. .IR condition
  31. to the default value. If
  32. .IR action
  33. is null (\c
  34. .BR \(dq\^\(dq ),
  35. the shell shall ignore each specified
  36. .IR condition
  37. if it arises. Otherwise, the argument
  38. .IR action
  39. shall be read and executed by the shell when one of the corresponding
  40. conditions arises. The action of
  41. .IR trap
  42. shall override a previous action (either default action or one
  43. explicitly set). The value of
  44. .BR \(dq$?\(dq
  45. after the
  46. .IR trap
  47. action completes shall be the value it had before
  48. .IR trap
  49. was invoked.
  50. .P
  51. The condition can be EXIT, 0 (equivalent to EXIT), or a signal
  52. specified using a symbolic name, without the SIG prefix, as listed in
  53. the tables of signal names in the
  54. .IR <signal.h>
  55. header defined in the Base Definitions volume of POSIX.1\(hy2017,
  56. .IR "Chapter 13" ", " "Headers";
  57. for example, HUP, INT, QUIT, TERM. Implementations may permit names with
  58. the SIG prefix or ignore case in signal names as an extension. Setting
  59. a trap for SIGKILL or SIGSTOP produces undefined results.
  60. .P
  61. The environment in which the shell executes a
  62. .IR trap
  63. on EXIT shall be identical to the environment immediately after the
  64. last command executed before the
  65. .IR trap
  66. on EXIT was taken.
  67. .P
  68. Each time
  69. .IR trap
  70. is invoked, the
  71. .IR action
  72. argument shall be processed in a manner equivalent to:
  73. .sp
  74. .RS 4
  75. .nf
  76. eval \fIaction\fR
  77. .fi
  78. .P
  79. .RE
  80. .P
  81. Signals that were ignored on entry to a non-interactive shell cannot be
  82. trapped or reset, although no error need be reported when attempting to
  83. do so. An interactive shell may reset or catch signals ignored on
  84. entry. Traps shall remain in place for a given shell until explicitly
  85. changed with another
  86. .IR trap
  87. command.
  88. .P
  89. When a subshell is entered, traps that are not being ignored shall be
  90. set to the default actions, except in the case of a command substitution
  91. containing only a single
  92. .IR trap
  93. command, when the traps need not be altered. Implementations may check
  94. for this case using only lexical analysis; for example, if
  95. .IR `trap`
  96. and
  97. .IR "$( trap -- )"
  98. do not alter the traps in the subshell, cases such as assigning
  99. .IR var=trap
  100. and then using
  101. .IR $($var)
  102. may still alter them. This does not imply that the
  103. .IR trap
  104. command cannot be used within the subshell to set new traps.
  105. .P
  106. The
  107. .IR trap
  108. command with no operands shall write to standard output a list of commands
  109. associated with each condition. If the command is executed in a subshell,
  110. the implementation does not perform the optional check described above
  111. for a command substitution containing only a single
  112. .IR trap
  113. command, and no
  114. .IR trap
  115. commands with operands have been executed since entry to the subshell,
  116. the list shall contain the commands that were associated with each
  117. condition immediately before the subshell environment was entered.
  118. Otherwise, the list shall contain the commands currently associated with
  119. each condition. The format shall be:
  120. .sp
  121. .RS 4
  122. .nf
  123. "trap -- %s %s ...\en", <\fIaction\fR>, <\fIcondition\fR> ...
  124. .fi
  125. .P
  126. .RE
  127. .P
  128. The shell shall format the output, including the proper use of quoting,
  129. so that it is suitable for reinput to the shell as commands that
  130. achieve the same trapping results. For example:
  131. .sp
  132. .RS 4
  133. .nf
  134. save_traps=$(trap)
  135. \&...
  136. eval "$save_traps"
  137. .fi
  138. .P
  139. .RE
  140. .P
  141. XSI-conformant systems also allow numeric signal numbers for the
  142. conditions corresponding to the following signal names:
  143. .IP 1 6
  144. SIGHUP
  145. .IP 2 6
  146. SIGINT
  147. .IP 3 6
  148. SIGQUIT
  149. .IP 6 6
  150. SIGABRT
  151. .IP 9 6
  152. SIGKILL
  153. .IP 14 6
  154. SIGALRM
  155. .IP 15 6
  156. SIGTERM
  157. .P
  158. The
  159. .IR trap
  160. special built-in shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  161. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  162. .SH OPTIONS
  163. None.
  164. .SH OPERANDS
  165. See the DESCRIPTION.
  166. .SH STDIN
  167. Not used.
  168. .SH "INPUT FILES"
  169. None.
  170. .SH "ENVIRONMENT VARIABLES"
  171. None.
  172. .SH "ASYNCHRONOUS EVENTS"
  173. Default.
  174. .SH STDOUT
  175. See the DESCRIPTION.
  176. .SH STDERR
  177. The standard error shall be used only for diagnostic messages.
  178. .SH "OUTPUT FILES"
  179. None.
  180. .SH "EXTENDED DESCRIPTION"
  181. None.
  182. .SH "EXIT STATUS"
  183. If the trap name
  184. or number
  185. is invalid, a non-zero exit status shall be returned; otherwise, zero
  186. shall be returned. For both interactive and non-interactive shells,
  187. invalid signal names
  188. or numbers
  189. shall not be considered a syntax error and do not cause the shell to
  190. abort.
  191. .SH "CONSEQUENCES OF ERRORS"
  192. Default.
  193. .LP
  194. .IR "The following sections are informative."
  195. .SH "APPLICATION USAGE"
  196. None.
  197. .SH EXAMPLES
  198. Write out a list of all traps and actions:
  199. .sp
  200. .RS 4
  201. .nf
  202. trap
  203. .fi
  204. .P
  205. .RE
  206. .P
  207. Set a trap so the
  208. .IR logout
  209. utility in the directory referred to by the
  210. .IR HOME
  211. environment variable executes when the shell terminates:
  212. .sp
  213. .RS 4
  214. .nf
  215. trap \(aq"$HOME"/logout\(aq EXIT
  216. .fi
  217. .P
  218. .RE
  219. .P
  220. or:
  221. .sp
  222. .RS 4
  223. .nf
  224. trap \(aq"$HOME"/logout\(aq 0
  225. .fi
  226. .P
  227. .RE
  228. .P
  229. Unset traps on INT, QUIT, TERM, and EXIT:
  230. .sp
  231. .RS 4
  232. .nf
  233. trap - INT QUIT TERM EXIT
  234. .fi
  235. .P
  236. .RE
  237. .SH "RATIONALE"
  238. Implementations may permit lowercase signal names as an extension.
  239. Implementations may also accept the names with the SIG prefix; no known
  240. historical shell does so. The
  241. .IR trap
  242. and
  243. .IR kill
  244. utilities in this volume of POSIX.1\(hy2017 are now consistent in their omission of the SIG
  245. prefix for signal names. Some
  246. .IR kill
  247. implementations do not allow the prefix, and
  248. .IR kill
  249. .BR \-l
  250. lists the signals without prefixes.
  251. .P
  252. Trapping SIGKILL or SIGSTOP is syntactically accepted by some
  253. historical implementations, but it has no effect. Portable POSIX
  254. applications cannot attempt to trap these signals.
  255. .P
  256. The output format is not historical practice. Since the output of
  257. historical
  258. .IR trap
  259. commands is not portable (because numeric signal values are not
  260. portable) and had to change to become so, an opportunity was taken to
  261. format the output in a way that a shell script could use to save and
  262. then later reuse a trap if it wanted.
  263. .P
  264. The KornShell uses an
  265. .BR ERR
  266. trap that is triggered whenever
  267. .IR set
  268. .BR \-e
  269. would cause an exit. This is allowable as an extension, but was not
  270. mandated, as other shells have not used it.
  271. .P
  272. The text about the environment for the EXIT trap invalidates the
  273. behavior of some historical versions of interactive shells which, for
  274. example, close the standard input before executing a trap on 0. For
  275. example, in some historical interactive shell sessions the following
  276. trap on 0 would always print
  277. .BR \(dq--\(dq :
  278. .sp
  279. .RS 4
  280. .nf
  281. trap \(aqread foo; echo "-$foo-"\(aq 0
  282. .fi
  283. .P
  284. .RE
  285. .P
  286. The command:
  287. .sp
  288. .RS 4
  289. .nf
  290. trap \(aqeval " $cmd"\(aq 0
  291. .fi
  292. .P
  293. .RE
  294. .P
  295. causes the contents of the shell variable
  296. .IR cmd
  297. to be executed as a command when the shell exits. Using:
  298. .sp
  299. .RS 4
  300. .nf
  301. trap \(aq$cmd\(aq 0
  302. .fi
  303. .P
  304. .RE
  305. .P
  306. does not work correctly if
  307. .IR cmd
  308. contains any special characters such as quoting or redirections. Using:
  309. .sp
  310. .RS 4
  311. .nf
  312. trap " $cmd" 0
  313. .fi
  314. .P
  315. .RE
  316. .P
  317. also works (the leading
  318. <space>
  319. character protects against unlikely cases where
  320. .IR cmd
  321. is a decimal integer or begins with
  322. .BR '\-' ),
  323. but it expands the
  324. .IR cmd
  325. variable when the
  326. .IR trap
  327. command is executed, not when the exit action is executed.
  328. .SH "FUTURE DIRECTIONS"
  329. None.
  330. .SH "SEE ALSO"
  331. .IR "Section 2.14" ", " "Special Built-In Utilities"
  332. .P
  333. The Base Definitions volume of POSIX.1\(hy2017,
  334. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  335. .IR "\fB<signal.h>\fP"
  336. .\"
  337. .SH COPYRIGHT
  338. Portions of this text are reprinted and reproduced in electronic form
  339. from IEEE Std 1003.1-2017, Standard for Information Technology
  340. -- Portable Operating System Interface (POSIX), The Open Group Base
  341. Specifications Issue 7, 2018 Edition,
  342. Copyright (C) 2018 by the Institute of
  343. Electrical and Electronics Engineers, Inc and The Open Group.
  344. In the event of any discrepancy between this version and the original IEEE and
  345. The Open Group Standard, the original IEEE and The Open Group Standard
  346. is the referee document. The original Standard can be obtained online at
  347. http://www.opengroup.org/unix/online.html .
  348. .PP
  349. Any typographical or formatting errors that appear
  350. in this page are most likely
  351. to have been introduced during the conversion of the source files to
  352. man page format. To report such errors, see
  353. https://www.kernel.org/doc/man-pages/reporting_bugs.html .