Commit | Line | Data |
---|---|---|
ae59e04c CL |
1 | .\" Copyright (c) 1980, 1991 Regents of the University of California. |
2 | .\" All rights reserved. | |
9d335a2c | 3 | .\" |
ae59e04c | 4 | .\" %sccs.include.redist.man% |
9d335a2c | 5 | .\" |
bce5def7 | 6 | .\" @(#)signal.3 6.9 (Berkeley) %G% |
ae59e04c CL |
7 | .\" |
8 | .Dd | |
9 | .Dt SIGNAL 3 | |
10 | .Os BSD 4 | |
11 | .Sh NAME | |
12 | .Nm signal | |
13 | .Nd simplified software signal facilities | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <signal.h> | |
16 | .Ft void | |
9090ce11 | 17 | .Fn *signal sig func\*(lp\*(rp |
48dd900b | 18 | .Ft void |
ae59e04c | 19 | .\" can not do this with .Fn yet |
ae59e04c | 20 | .br |
48dd900b | 21 | \*(lp\|\*(fN*func\*(rp\*(lp\|\*(rp\fR |
ae59e04c CL |
22 | .Sh DESCRIPTION |
23 | This | |
24 | .Fn signal | |
25 | facility | |
3c31698f | 26 | is a simplified interface to the more general |
ae59e04c | 27 | .Xr sigaction 2 |
3c31698f | 28 | facility. |
ae59e04c CL |
29 | .Pp |
30 | Signals allow the manipulation of a process from outside its | |
31 | domain as well as allowing the process to manipulate itself or | |
32 | copies of itself (children). There are two general types of signals: | |
33 | those that cause termination of a process and those that do not. | |
34 | Signals which cause termination of a program might result from | |
35 | an irrecoverable error or might be the result of a user at a terminal | |
36 | typing the `interrupt' character. | |
37 | Signals are used when a process is stopped because it wishes to access | |
3c31698f | 38 | its control terminal while in the background (see |
ae59e04c | 39 | .Xr tty 4 ) . |
3c31698f KM |
40 | Signals are optionally generated |
41 | when a process resumes after being stopped, | |
42 | when the status of child processes changes, | |
43 | or when input is ready at the control terminal. | |
ae59e04c CL |
44 | Most signals result in the termination of the process receiving them |
45 | if no action | |
3c31698f KM |
46 | is taken; some signals instead cause the process receiving them |
47 | to be stopped, or are simply discarded if the process has not | |
48 | requested otherwise. | |
ae59e04c CL |
49 | Except for the |
50 | .Dv SIGKILL | |
51 | and | |
52 | .Dv SIGSTOP | |
3c31698f | 53 | signals, the |
ae59e04c CL |
54 | .Fn signal |
55 | function allows for a signal to be caught, to be ignored, or to generate | |
56 | an interupt. | |
57 | These signals are defined in the file | |
58 | .Aq Pa signal.h : | |
59 | .Bl -column SIGVTALARMXX "create core imagexxx" | |
48dd900b | 60 | .It Sy " Name " " Default Action " " Description" |
ae59e04c CL |
61 | .It Dv SIGHUP No " terminate process" " terminal line hangup" |
62 | .It Dv SIGINT No " terminate process" " interrupt program" | |
63 | .It Dv SIGQUIT No " create core image" " quit program" | |
64 | .It Dv SIGILL No " create core image" " illegal instruction" | |
65 | .It Dv SIGTRAP No " create core image" " trace trap" | |
66 | .It Dv SIGABRT No " create core image" Xr abort 2 | |
67 | call (formerly | |
68 | .Dv SIGIOT ) | |
69 | .It Dv SIGEMT No " create core image" " emulate instruction executed" | |
70 | .It Dv SIGFPE No " create core image" " floating-point exception" | |
71 | .It Dv SIGKILL No " terminate process" " kill program" | |
72 | .It Dv SIGBUS No " create core image" " bus error" | |
73 | .It Dv SIGSEGV No " create core image" " segmentation violation" | |
74 | .It Dv SIGSYS No " create core image" " system call given invalid argument" | |
75 | .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" | |
76 | .It Dv SIGALRM No " terminate process" " real-time timer expired" | |
77 | .It Dv SIGTERM No " terminate process" " software termination signal" | |
78 | .It Dv SIGURG No " discard signal" " urgent condition present on socket" | |
79 | .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" | |
80 | .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" | |
81 | .It Dv SIGCONT No " discard signal" " continue after stop" | |
82 | .It Dv SIGCHLD No " discard signal" " child status has changed" | |
83 | .It Dv SIGTTIN No " stop process" " background read attempted from control terminal" | |
84 | .It Dv SIGTTOU No " stop process" " background write attempted to control terminal" | |
85 | .It Dv SIGIO No " discard signal" Tn " I/O" | |
86 | is possible on a descriptor (see | |
87 | .Xr fcntl 2 ) | |
88 | .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" | |
89 | .Xr setrlimit 2 ) | |
90 | .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" | |
91 | .Xr setrlimit 2 ) | |
92 | .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" | |
93 | .Xr setitimer 2 ) | |
94 | .It Dv SIGPROF No " terminate process" " profiling timer alarm (see" | |
95 | .Xr setitimer 2 ) | |
96 | .It Dv SIGWINCH No " discard signal" " Window size change" | |
97 | .It Dv SIGINFO No " discard signal" " status request from keyboard" | |
98 | .It Dv SIGUSR1 No " terminate process" " User defined signal 1" | |
99 | .It Dv SIGUSR2 No " terminate process" " User defined signal 2" | |
100 | .El | |
101 | .Pp | |
102 | The | |
103 | .Fa func | |
104 | procedure allows a user to choose the action upon receipt of a signal. | |
105 | To set the default action of the signal to occur as listed above, | |
106 | .Fa func | |
107 | should be | |
108 | .Dv SIG_DFL . | |
109 | A | |
110 | .Dv SIG_DFL | |
111 | resets the default action. | |
112 | To ignore the signal | |
113 | .Fa func | |
114 | should be | |
115 | .Dv SIG_IGN . | |
116 | This will cause subsequent instances of the signal to be ignored | |
117 | and pending instances to be discarded. If | |
118 | .Dv SIG_IGN | |
119 | is not used, | |
963ad392 | 120 | further occurrences of the signal are |
3c31698f | 121 | automatically blocked and |
ae59e04c | 122 | .Fa func |
3c31698f | 123 | is called. |
ae59e04c CL |
124 | .Pp |
125 | The handled signal is unblocked with the | |
126 | function returns and | |
127 | the process continues from where it left off when the signal occured. | |
128 | .Bf -symbolic | |
129 | Unlike previous signal facilities, the handler | |
130 | func() remains installed after a signal has been delivered. | |
131 | .Ef | |
132 | .Pp | |
133 | For some system calls, if a signal is caught while the call is | |
134 | executing and the call is permaturely terminated, | |
135 | the call is automatically restarted. | |
136 | (The handler is installed using the | |
137 | .Dv SA_RESTART | |
138 | flag with | |
139 | .Xr sigaction 2 . ) | |
bc9788fb | 140 | The affected system calls include |
ae59e04c CL |
141 | .Xr read 2 , |
142 | .Xr write 2 , | |
143 | .Xr sendto 2 , | |
144 | .Xr recvfrom 2 , | |
145 | .Xr sendmsg 2 | |
bc9788fb | 146 | and |
ae59e04c CL |
147 | .Xr recvmsg 2 |
148 | on a communications channel or a low speed device | |
3c31698f | 149 | and during a |
ae59e04c | 150 | .Xr ioctl 2 |
bc9788fb | 151 | or |
ae59e04c | 152 | .Xr wait 2 . |
bc9788fb MK |
153 | However, calls that have already committed are not restarted, |
154 | but instead return a partial success (for example, a short read count). | |
ae59e04c CL |
155 | .Pp |
156 | When a process which has installed signal handlers forks, | |
157 | the child process inherits the signals. | |
158 | All caught signals may be reset to their default action by a call | |
159 | to the | |
160 | .Xr execve 2 | |
161 | function; | |
3c31698f | 162 | ignored signals remain ignored. |
ae59e04c | 163 | .Sh RETURN VALUES |
3c31698f | 164 | The previous action is returned on a successful call. |
ae59e04c CL |
165 | Otherwise, \-1 is returned and the global variable |
166 | .Va errno | |
3c31698f | 167 | is set to indicate the error. |
ae59e04c CL |
168 | .Sh ERRORS |
169 | .Xr Signal | |
3c31698f KM |
170 | will fail and no action will take place if one of the |
171 | following occur: | |
ae59e04c CL |
172 | .Bl -tag -width [EINVAL] |
173 | .It Bq Er EINVAL | |
174 | .Em Sig | |
3c31698f | 175 | is not a valid signal number. |
ae59e04c CL |
176 | .It Bq Er EINVAL |
177 | An attempt is made to ignore or supply a handler for | |
178 | .Dv SIGKILL | |
179 | or | |
180 | .Ev SIGSTOP . | |
181 | .Sh SEE ALSO | |
182 | .Xr kill 1 , | |
183 | .Xr ptrace 2 , | |
184 | .Xr kill 2 , | |
185 | .Xr sigaction 2 , | |
bce5def7 | 186 | .Xr sigaltstack 2 , |
ae59e04c CL |
187 | .Xr sigprocmask 2 , |
188 | .Xr sigsuspend 2 , | |
ae59e04c CL |
189 | .Xr setjmp 3 , |
190 | .Xr tty 4 | |
191 | .Sh HISTORY | |
192 | This | |
193 | .Nm signal | |
194 | facility appeared in | |
195 | .Bx 4.0 . |