share/man/man1/trap.1

   1 '\" te
   2 .\" Copyright (c) 2007 Sun Microsystems, Inc. - All Rights Reserved.
   3 .\" Copyright 1989
   4 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
   5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8 .TH TRAP 1 "Nov 20, 2007"
   9 .SH NAME
  10 trap, onintr \- shell built-in functions to respond to (hardware) signals
  11 .SH SYNOPSIS
  12 .SS "sh"
  13 .LP
  14 .nf
  15 \fBtrap\fR [\fIargument\fR \fIn\fR [\fIn2\fR]...]
  16 .fi
  17
  18 .SS "csh"
  19 .LP
  20 .nf
  21 \fBonintr\fR [\fB-|\fR \fIlabel\fR]
  22 .fi
  23
  24 .SS "ksh"
  25 .LP
  26 .nf
  27 \fB*trap\fR [\fIarg\fR \fIsig\fR [\fIsig2\fR...]]
  28 .fi
  29
  30 .SS "ksh93"
  31 .LP
  32 .nf
  33 \fB+trap\fR [\fB-p\fR] [\fIaction\fR \fIcondition\fR...]
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .SS "sh"
  38 .sp
  39 .LP
  40 The \fBtrap\fR command \fIargument\fR is to be read and executed when the shell
  41 receives numeric or symbolic signal(s) (\fIn\fR). (Note: \fIargument\fR is
  42 scanned once when the trap is set and once when the trap is taken.) Trap
  43 commands are executed in order of signal number or corresponding symbolic
  44 names. Any attempt to set a trap on a signal that was ignored on entry to the
  45 current shell is ineffective. An attempt to trap on signal 11 (memory fault)
  46 produces an error. If \fIargument\fR is absent all trap(s) \fIn\fR are reset to
  47 their original values. If \fIargument\fR is the null string this signal is
  48 ignored by the shell and by the commands it invokes. If \fIn\fR is \fB0\fR the
  49 command \fIargument\fR is executed on exit from the shell. The \fBtrap\fR
  50 command with no arguments prints a list of commands associated with each signal
  51 number.
  52 .SS "csh"
  53 .sp
  54 .LP
  55 \fBonintr\fR controls the action of the shell on interrupts. With no arguments,
  56 \fBonintr\fR restores the default action of the shell on interrupts. (The shell
  57 terminates shell scripts and returns to the terminal command input level). With
  58 the \fB\(mi\fR argument, the shell ignores all interrupts. With a \fIlabel\fR
  59 argument, the shell executes a \fBgoto\fR \fIlabel\fR when an interrupt is
  60 received or a child process terminates because it was interrupted.
  61 .SS "ksh"
  62 .sp
  63 .LP
  64 \fBtrap\fR uses \fIarg\fR as a command to be read and executed when the shell
  65 receives signal(s) \fIsig\fR. \fIarg\fR is scanned once when the trap is set
  66 and once when the trap is taken. Each \fIsig\fR can be specified as a number or
  67 as the name of the signal. \fBtrap\fR commands are executed in order of signal
  68 number. Any attempt to set a trap on a signal that was ignored on entry to the
  69 current shell is ineffective. If \fIarg\fR is omitted or is \fB\(mi\fR, then
  70 the trap(s) for each \fIsig\fR are reset to their original values. If \fIarg\fR
  71 is the null (the empty string, for example, \fB""\fR) string then this signal
  72 is ignored by the shell and by the commands it invokes. If \fIsig\fR is
  73 \fBERR\fR then \fIarg\fR are executed whenever a command has a non-zero exit
  74 status. If \fIsig\fR is \fBDEBUG\fR then \fIarg\fR are executed after each
  75 command. If \fIsig\fR is \fB0\fR or \fBEXIT\fR for a \fBtrap\fR set outside any
  76 function then the command \fIarg\fR is executed on exit from the shell. The
  77 \fBtrap\fR command with no arguments prints a list of commands associated with
  78 each signal number.
  79 .sp
  80 .LP
  81 On this manual page, \fBksh\fR(1) commands that are preceded by one or two *
  82 (asterisks) are treated specially in the following ways:
  83 .RS +4
  84 .TP
  85 1.
  86 Variable assignment lists preceding the command remain in effect when the
  87 command completes.
  88 .RE
  89 .RS +4
  90 .TP
  91 2.
  92 I/O redirections are processed after variable assignments.
  93 .RE
  94 .RS +4
  95 .TP
  96 3.
  97 Errors cause a script that contains them to abort.
  98 .RE
  99 .RS +4
 100 .TP
 101 4.
 102 Words, following a command preceded by ** that are in the format of a
 103 variable assignment, are expanded with the same rules as a variable assignment.
 104 This means that tilde substitution is performed after the \fB=\fR sign and word
 105 splitting and file name generation are not performed.
 106 .RE
 107 .SS "ksh93"
 108 .sp
 109 .LP
 110 \fBtrap\fR is a special built-in that defines actions to be taken when
 111 conditions such as receiving a signal occur. \fBtrap\fR can also be used to
 112 display the current trap settings on standard output.
 113 .sp
 114 .LP
 115 If \fIaction\fR is \fB-\fR, \fBtrap\fR resets each condition to the default
 116 value. If \fIaction\fR is an empty string, the shell ignores each of the
 117 conditions if they arise. Otherwise, the argument \fIaction\fR is read and
 118 executed by the shell as if it were processed by \fBeval\fR when one of the
 119 corresponding conditions arise. The action of the trap overrides any previous
 120 action associated with each specified condition. The value of \fB$?\fR is not
 121 altered by the trap execution.
 122 .sp
 123 .LP
 124 \fIcondition\fR can be the name or number of a signal, or one of the following:
 125 .sp
 126 .ne 2
 127 .na
 128 \fB\fBEXIT\fR\fR
 129 .ad
 130 .RS 9n
 131 Execute this trap when the shell exits. If defined within a function with the
 132 \fBfunction\fR reserved word, executes the trap in the caller's environment
 133 when the function returns. The trap action is restored to the value it had when
 134 it called the function.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fB0\fR\fR
 141 .ad
 142 .RS 9n
 143 Same as \fBEXIT\fR.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBDEBUG\fR\fR
 150 .ad
 151 .RS 9n
 152 Execute before each simple command is executed but after the arguments are
 153 expanded.
 154 .RE
 155
 156 .sp
 157 .ne 2
 158 .na
 159 \fB\fBERR\fR\fR
 160 .ad
 161 .RS 9n
 162 Execute whenever \fBset -e\fR would cause the shell to exit.
 163 .RE
 164
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBKEYBD\fR\fR
 169 .ad
 170 .RS 9n
 171 Execute when a key is entered from a terminal device.
 172 .RE
 173
 174 .sp
 175 .LP
 176 Signal names are case insensitive and the \fBsig\fR prefix is optional. Signals
 177 that were ignored on entry to a non-interactive shell cannot trapped or reset
 178 although doing so does not report an error. The use of signal numbers other
 179 than 1, 2, 3, 6, 9, 14, and 15 are not portable.
 180 .sp
 181 .LP
 182 Although trap is a special built-in, specifying a condition that the shell does
 183 not know about causes trap to exit with a \fBnon-zero\fR exit status, but does
 184 not terminate the invoking shell.
 185 .sp
 186 .LP
 187 If no action or conditions are specified then all the current trap settings are
 188 written to standard output.
 189 .sp
 190 .LP
 191 The following options are supported by the \fBtrap\fR built-in command in
 192 \fBksh93\fR:
 193 .sp
 194 .ne 2
 195 .na
 196 \fB\fB-p\fR\fR
 197 .ad
 198 .RS 6n
 199 Causes the current traps to be output in a format that can be processed as
 200 input to the shell to recreate the current traps.
 201 .RE
 202
 203 .sp
 204 .LP
 205 The trap built-in in \fBksh93\fR exits with one of the following values:
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fB0\fR\fR
 210 .ad
 211 .RS 6n
 212 Successful completion.
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fB>0\fR\fR
 219 .ad
 220 .RS 6n
 221 An error occurred.
 222 .RE
 223
 224 .sp
 225 .LP
 226 On this manual page, \fBksh93\fR(1) commands that are preceded by one or two
 227 \fB+\fR (plus signs) are treated specially in the following ways:
 228 .RS +4
 229 .TP
 230 1.
 231 Variable assignment lists preceding the command remain in effect when the
 232 command completes.
 233 .RE
 234 .RS +4
 235 .TP
 236 2.
 237 I/O redirections are processed after variable assignments.
 238 .RE
 239 .RS +4
 240 .TP
 241 3.
 242 Errors cause a script that contains them to abort.
 243 .RE
 244 .RS +4
 245 .TP
 246 4.
 247 They are not valid function names.
 248 .RE
 249 .RS +4
 250 .TP
 251 5.
 252 Words, following a command preceded by \fB++\fR that are in the format of a
 253 variable assignment, are expanded with the same rules as a variable assignment.
 254 This means that tilde substitution is performed after the \fB=\fR sign and word
 255 splitting and file name generation are not performed.
 256 .RE
 257 .SH SEE ALSO
 258 .sp
 259 .LP
 260 \fBcsh\fR(1), \fBeval\fR(1), \fBexit\fR(1), \fBksh\fR(1), \fBksh93\fR(1),
 261 \fBsh\fR(1), \fBattributes\fR(5)