Commit | Line | Data |
---|---|---|
74155b62 KB |
1 | .\" Copyright (c) 1980, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
9d335a2c | 3 | .\" |
ad787160 C |
4 | .\" Redistribution and use in source and binary forms, with or without |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
9d335a2c | 19 | .\" |
ad787160 C |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
ae59e04c | 31 | .\" |
ad787160 C |
32 | .\" @(#)signal.3 8.1 (Berkeley) 6/4/93 |
33 | .\" | |
34 | .Dd June 4, 1993 | |
ae59e04c CL |
35 | .Dt SIGNAL 3 |
36 | .Os BSD 4 | |
37 | .Sh NAME | |
38 | .Nm signal | |
39 | .Nd simplified software signal facilities | |
40 | .Sh SYNOPSIS | |
41 | .Fd #include <signal.h> | |
42 | .Ft void | |
9090ce11 | 43 | .Fn *signal sig func\*(lp\*(rp |
48dd900b | 44 | .Ft void |
ae59e04c | 45 | .\" can not do this with .Fn yet |
ae59e04c | 46 | .br |
48dd900b | 47 | \*(lp\|\*(fN*func\*(rp\*(lp\|\*(rp\fR |
ae59e04c CL |
48 | .Sh DESCRIPTION |
49 | This | |
50 | .Fn signal | |
51 | facility | |
3c31698f | 52 | is a simplified interface to the more general |
ae59e04c | 53 | .Xr sigaction 2 |
3c31698f | 54 | facility. |
ae59e04c CL |
55 | .Pp |
56 | Signals allow the manipulation of a process from outside its | |
57 | domain as well as allowing the process to manipulate itself or | |
58 | copies of itself (children). There are two general types of signals: | |
59 | those that cause termination of a process and those that do not. | |
60 | Signals which cause termination of a program might result from | |
61 | an irrecoverable error or might be the result of a user at a terminal | |
62 | typing the `interrupt' character. | |
63 | Signals are used when a process is stopped because it wishes to access | |
3c31698f | 64 | its control terminal while in the background (see |
ae59e04c | 65 | .Xr tty 4 ) . |
3c31698f KM |
66 | Signals are optionally generated |
67 | when a process resumes after being stopped, | |
68 | when the status of child processes changes, | |
69 | or when input is ready at the control terminal. | |
ae59e04c CL |
70 | Most signals result in the termination of the process receiving them |
71 | if no action | |
3c31698f KM |
72 | is taken; some signals instead cause the process receiving them |
73 | to be stopped, or are simply discarded if the process has not | |
74 | requested otherwise. | |
ae59e04c CL |
75 | Except for the |
76 | .Dv SIGKILL | |
77 | and | |
78 | .Dv SIGSTOP | |
3c31698f | 79 | signals, the |
ae59e04c CL |
80 | .Fn signal |
81 | function allows for a signal to be caught, to be ignored, or to generate | |
82 | an interupt. | |
83 | These signals are defined in the file | |
84 | .Aq Pa signal.h : | |
85 | .Bl -column SIGVTALARMXX "create core imagexxx" | |
48dd900b | 86 | .It Sy " Name " " Default Action " " Description" |
ae59e04c CL |
87 | .It Dv SIGHUP No " terminate process" " terminal line hangup" |
88 | .It Dv SIGINT No " terminate process" " interrupt program" | |
89 | .It Dv SIGQUIT No " create core image" " quit program" | |
90 | .It Dv SIGILL No " create core image" " illegal instruction" | |
91 | .It Dv SIGTRAP No " create core image" " trace trap" | |
92 | .It Dv SIGABRT No " create core image" Xr abort 2 | |
93 | call (formerly | |
94 | .Dv SIGIOT ) | |
95 | .It Dv SIGEMT No " create core image" " emulate instruction executed" | |
96 | .It Dv SIGFPE No " create core image" " floating-point exception" | |
97 | .It Dv SIGKILL No " terminate process" " kill program" | |
98 | .It Dv SIGBUS No " create core image" " bus error" | |
99 | .It Dv SIGSEGV No " create core image" " segmentation violation" | |
100 | .It Dv SIGSYS No " create core image" " system call given invalid argument" | |
101 | .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" | |
102 | .It Dv SIGALRM No " terminate process" " real-time timer expired" | |
103 | .It Dv SIGTERM No " terminate process" " software termination signal" | |
104 | .It Dv SIGURG No " discard signal" " urgent condition present on socket" | |
105 | .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" | |
106 | .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" | |
107 | .It Dv SIGCONT No " discard signal" " continue after stop" | |
108 | .It Dv SIGCHLD No " discard signal" " child status has changed" | |
109 | .It Dv SIGTTIN No " stop process" " background read attempted from control terminal" | |
110 | .It Dv SIGTTOU No " stop process" " background write attempted to control terminal" | |
111 | .It Dv SIGIO No " discard signal" Tn " I/O" | |
112 | is possible on a descriptor (see | |
113 | .Xr fcntl 2 ) | |
114 | .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" | |
115 | .Xr setrlimit 2 ) | |
116 | .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" | |
117 | .Xr setrlimit 2 ) | |
118 | .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" | |
119 | .Xr setitimer 2 ) | |
120 | .It Dv SIGPROF No " terminate process" " profiling timer alarm (see" | |
121 | .Xr setitimer 2 ) | |
122 | .It Dv SIGWINCH No " discard signal" " Window size change" | |
123 | .It Dv SIGINFO No " discard signal" " status request from keyboard" | |
124 | .It Dv SIGUSR1 No " terminate process" " User defined signal 1" | |
125 | .It Dv SIGUSR2 No " terminate process" " User defined signal 2" | |
126 | .El | |
127 | .Pp | |
128 | The | |
129 | .Fa func | |
130 | procedure allows a user to choose the action upon receipt of a signal. | |
131 | To set the default action of the signal to occur as listed above, | |
132 | .Fa func | |
133 | should be | |
134 | .Dv SIG_DFL . | |
135 | A | |
136 | .Dv SIG_DFL | |
137 | resets the default action. | |
138 | To ignore the signal | |
139 | .Fa func | |
140 | should be | |
141 | .Dv SIG_IGN . | |
142 | This will cause subsequent instances of the signal to be ignored | |
143 | and pending instances to be discarded. If | |
144 | .Dv SIG_IGN | |
145 | is not used, | |
963ad392 | 146 | further occurrences of the signal are |
3c31698f | 147 | automatically blocked and |
ae59e04c | 148 | .Fa func |
3c31698f | 149 | is called. |
ae59e04c CL |
150 | .Pp |
151 | The handled signal is unblocked with the | |
152 | function returns and | |
153 | the process continues from where it left off when the signal occured. | |
154 | .Bf -symbolic | |
155 | Unlike previous signal facilities, the handler | |
156 | func() remains installed after a signal has been delivered. | |
157 | .Ef | |
158 | .Pp | |
159 | For some system calls, if a signal is caught while the call is | |
160 | executing and the call is permaturely terminated, | |
161 | the call is automatically restarted. | |
162 | (The handler is installed using the | |
163 | .Dv SA_RESTART | |
164 | flag with | |
165 | .Xr sigaction 2 . ) | |
bc9788fb | 166 | The affected system calls include |
ae59e04c CL |
167 | .Xr read 2 , |
168 | .Xr write 2 , | |
169 | .Xr sendto 2 , | |
170 | .Xr recvfrom 2 , | |
171 | .Xr sendmsg 2 | |
bc9788fb | 172 | and |
ae59e04c CL |
173 | .Xr recvmsg 2 |
174 | on a communications channel or a low speed device | |
3c31698f | 175 | and during a |
ae59e04c | 176 | .Xr ioctl 2 |
bc9788fb | 177 | or |
ae59e04c | 178 | .Xr wait 2 . |
bc9788fb MK |
179 | However, calls that have already committed are not restarted, |
180 | but instead return a partial success (for example, a short read count). | |
ae59e04c CL |
181 | .Pp |
182 | When a process which has installed signal handlers forks, | |
183 | the child process inherits the signals. | |
184 | All caught signals may be reset to their default action by a call | |
185 | to the | |
186 | .Xr execve 2 | |
187 | function; | |
3c31698f | 188 | ignored signals remain ignored. |
ae59e04c | 189 | .Sh RETURN VALUES |
3c31698f | 190 | The previous action is returned on a successful call. |
ae59e04c CL |
191 | Otherwise, \-1 is returned and the global variable |
192 | .Va errno | |
3c31698f | 193 | is set to indicate the error. |
ae59e04c CL |
194 | .Sh ERRORS |
195 | .Xr Signal | |
3c31698f KM |
196 | will fail and no action will take place if one of the |
197 | following occur: | |
ae59e04c CL |
198 | .Bl -tag -width [EINVAL] |
199 | .It Bq Er EINVAL | |
200 | .Em Sig | |
3c31698f | 201 | is not a valid signal number. |
ae59e04c CL |
202 | .It Bq Er EINVAL |
203 | An attempt is made to ignore or supply a handler for | |
204 | .Dv SIGKILL | |
205 | or | |
206 | .Ev SIGSTOP . | |
207 | .Sh SEE ALSO | |
208 | .Xr kill 1 , | |
209 | .Xr ptrace 2 , | |
210 | .Xr kill 2 , | |
211 | .Xr sigaction 2 , | |
bce5def7 | 212 | .Xr sigaltstack 2 , |
ae59e04c CL |
213 | .Xr sigprocmask 2 , |
214 | .Xr sigsuspend 2 , | |
ae59e04c CL |
215 | .Xr setjmp 3 , |
216 | .Xr tty 4 | |
217 | .Sh HISTORY | |
218 | This | |
219 | .Nm signal | |
220 | facility appeared in | |
221 | .Bx 4.0 . |