Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
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. | |
19 | .\" | |
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. | |
31 | .\" | |
32 | .\" @(#)signal.3 6.7 (Berkeley) 7/31/91 | |
33 | .\" | |
34 | .Dd July 31, 1991 | |
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 | |
43 | .Fn *signal sig func Ns Pq | |
44 | .Ft void | |
45 | .\" can not do this with .Fn yet | |
46 | .br | |
47 | \*(lp\|\*(fN*func\*(rp\*(lp\|\*(rp\fR | |
48 | .Sh DESCRIPTION | |
49 | This | |
50 | .Fn signal | |
51 | facility | |
52 | is a simplified interface to the more general | |
53 | .Xr sigaction 2 | |
54 | facility. | |
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 | |
64 | its control terminal while in the background (see | |
65 | .Xr tty 4 ) . | |
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. | |
70 | Most signals result in the termination of the process receiving them | |
71 | if no action | |
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. | |
75 | Except for the | |
76 | .Dv SIGKILL | |
77 | and | |
78 | .Dv SIGSTOP | |
79 | signals, the | |
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" | |
86 | .It Sy " Name " " Default Action " " Description" | |
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, | |
146 | further occurrences of the signal are | |
147 | automatically blocked and | |
148 | .Fa func | |
149 | is called. | |
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 . ) | |
166 | The affected system calls include | |
167 | .Xr read 2 , | |
168 | .Xr write 2 , | |
169 | .Xr sendto 2 , | |
170 | .Xr recvfrom 2 , | |
171 | .Xr sendmsg 2 | |
172 | and | |
173 | .Xr recvmsg 2 | |
174 | on a communications channel or a low speed device | |
175 | and during a | |
176 | .Xr ioctl 2 | |
177 | or | |
178 | .Xr wait 2 . | |
179 | However, calls that have already committed are not restarted, | |
180 | but instead return a partial success (for example, a short read count). | |
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; | |
188 | ignored signals remain ignored. | |
189 | .Sh RETURN VALUES | |
190 | The previous action is returned on a successful call. | |
191 | Otherwise, \-1 is returned and the global variable | |
192 | .Va errno | |
193 | is set to indicate the error. | |
194 | .Sh ERRORS | |
195 | .Xr Signal | |
196 | will fail and no action will take place if one of the | |
197 | following occur: | |
198 | .Bl -tag -width [EINVAL] | |
199 | .It Bq Er EINVAL | |
200 | .Em Sig | |
201 | is not a valid signal number. | |
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 , | |
212 | .Xr sigprocmask 2 , | |
213 | .Xr sigsuspend 2 , | |
214 | .Xr sigstack 2 , | |
215 | .Xr setjmp 3 , | |
216 | .Xr tty 4 | |
217 | .Sh HISTORY | |
218 | This | |
219 | .Nm signal | |
220 | facility appeared in | |
221 | .Bx 4.0 . |