Merge from vendor branch BZIP:
[dragonfly.git] / lib / libc / gen / signal.3
CommitLineData
984263bc
MD
1.\" Copyright (c) 1980, 1991, 1993
2.\" The Regents of the University of California. 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 8.3 (Berkeley) 4/19/94
33.\" $FreeBSD: src/lib/libc/gen/signal.3,v 1.17.2.9 2003/03/13 18:05:37 trhodes Exp $
44cb301e 34.\" $DragonFly: src/lib/libc/gen/signal.3,v 1.5 2006/05/26 19:39:36 swildner Exp $
984263bc
MD
35.\"
36.Dd April 19, 1994
37.Dt SIGNAL 3
38.Os
39.Sh NAME
40.Nm signal
41.Nd simplified software signal facilities
42.Sh LIBRARY
43.Lb libc
44.Sh SYNOPSIS
45.In signal.h
46.\" The following is Quite Ugly, but syntactically correct. Don't try to
47.\" fix it.
48.Ft void \*(lp*
49.Fn signal "int sig" "void \*(lp*func\*(rp\*(lpint\*(rp\*(rp\*(rp\*(lpint"
50.Pp
51or in
9bb2a92d 52.Dx Ns 's
984263bc
MD
53equivalent but easier to read typedef'd version:
54.Ft typedef "void \*(lp*sig_t\*(rp \*(lpint\*(rp" ;
55.Ft sig_t
56.Fn signal "int sig" "sig_t func"
57.Sh DESCRIPTION
58This
59.Fn signal
60facility
61is a simplified interface to the more general
62.Xr sigaction 2
63facility.
64.Pp
65Signals allow the manipulation of a process from outside its
66domain as well as allowing the process to manipulate itself or
67copies of itself (children). There are two general types of signals:
68those that cause termination of a process and those that do not.
69Signals which cause termination of a program might result from
70an irrecoverable error or might be the result of a user at a terminal
71typing the `interrupt' character.
72Signals are used when a process is stopped because it wishes to access
73its control terminal while in the background (see
74.Xr tty 4 ) .
75Signals are optionally generated
76when a process resumes after being stopped,
77when the status of child processes changes,
78or when input is ready at the control terminal.
79Most signals result in the termination of the process receiving them
80if no action
81is taken; some signals instead cause the process receiving them
82to be stopped, or are simply discarded if the process has not
83requested otherwise.
84Except for the
85.Dv SIGKILL
86and
87.Dv SIGSTOP
88signals, the
89.Fn signal
90function allows for a signal to be caught, to be ignored, or to generate
91an interrupt.
92These signals are defined in the file
44cb301e 93.In signal.h :
984263bc
MD
94.Bl -column SIGVTALARMXX "create core imagexxx"
95.It Sy "Name Default Action Description"
96.It Dv SIGHUP Ta "terminate process" Ta "terminal line hangup"
97.It Dv SIGINT Ta "terminate process" Ta "interrupt program"
98.It Dv SIGQUIT Ta "create core image" Ta "quit program"
99.It Dv SIGILL Ta "create core image" Ta "illegal instruction"
100.It Dv SIGTRAP Ta "create core image" Ta "trace trap"
101.It Dv SIGABRT Ta "create core image" Ta "abort program"
102(formerly
103.Dv SIGIOT )
104.It Dv SIGEMT Ta "create core image" Ta "emulate instruction executed"
105.It Dv SIGFPE Ta "create core image" Ta "floating-point exception"
106.It Dv SIGKILL Ta "terminate process" Ta "kill program"
107.It Dv SIGBUS Ta "create core image" Ta "bus error"
108.It Dv SIGSEGV Ta "create core image" Ta "segmentation violation"
109.It Dv SIGSYS Ta "create core image" Ta "non-existent system call invoked"
110.It Dv SIGPIPE Ta "terminate process" Ta "write on a pipe with no reader"
111.It Dv SIGALRM Ta "terminate process" Ta "real-time timer expired"
112.It Dv SIGTERM Ta "terminate process" Ta "software termination signal"
113.It Dv SIGURG Ta "discard signal" Ta "urgent condition present on socket"
114.It Dv SIGSTOP Ta "stop process" Ta "stop (cannot be caught or ignored)"
115.It Dv SIGTSTP Ta "stop process" Ta "stop signal generated from keyboard"
116.It Dv SIGCONT Ta "discard signal" Ta "continue after stop"
117.It Dv SIGCHLD Ta "discard signal" Ta "child status has changed"
118.It Dv SIGTTIN Ta "stop process" Ta "background read attempted from control terminal"
119.It Dv SIGTTOU Ta "stop process" Ta "background write attempted to control terminal"
120.It Dv SIGIO Ta "discard signal" Ta Tn "I/O"
121is possible on a descriptor (see
122.Xr fcntl 2 )
123.It Dv SIGXCPU Ta "terminate process" Ta "cpu time limit exceeded (see"
124.Xr setrlimit 2 )
125.It Dv SIGXFSZ Ta "terminate process" Ta "file size limit exceeded (see"
126.Xr setrlimit 2 )
127.It Dv SIGVTALRM Ta "terminate process" Ta "virtual time alarm (see"
128.Xr setitimer 2 )
129.It Dv SIGPROF Ta "terminate process" Ta "profiling timer alarm (see"
130.Xr setitimer 2 )
131.It Dv SIGWINCH Ta "discard signal" Ta "Window size change"
132.It Dv SIGINFO Ta "discard signal" Ta "status request from keyboard"
133.It Dv SIGUSR1 Ta "terminate process" Ta "User defined signal 1"
134.It Dv SIGUSR2 Ta "terminate process" Ta "User defined signal 2"
31542891
MD
135.It Dv SIGCKPT Ta "checkpoint process" Ta "Checkpoint"
136.It Dv SIGCKPTEXIT Ta "terminate process" Ta "Checkpoint and exit"
984263bc
MD
137.El
138.Pp
139The
140.Fa sig
141argument specifies which signal was received.
142The
143.Fa func
144procedure allows a user to choose the action upon receipt of a signal.
145To set the default action of the signal to occur as listed above,
146.Fa func
147should be
148.Dv SIG_DFL .
149A
150.Dv SIG_DFL
151resets the default action.
152To ignore the signal
153.Fa func
154should be
155.Dv SIG_IGN .
156This will cause subsequent instances of the signal to be ignored
157and pending instances to be discarded.
158If
159.Dv SIG_IGN
160is not used,
161further occurrences of the signal are
162automatically blocked and
163.Fa func
164is called.
165.Pp
166The handled signal is unblocked when the
167function returns and
168the process continues from where it left off when the signal occurred.
169.Bf -symbolic
170Unlike previous signal facilities, the handler
171func() remains installed after a signal has been delivered.
172.Ef
173.Pp
174For some system calls, if a signal is caught while the call is
175executing and the call is prematurely terminated,
176the call is automatically restarted.
177(The handler is installed using the
178.Dv SA_RESTART
179flag with
180.Xr sigaction 2 . )
181The affected system calls include
182.Xr read 2 ,
183.Xr write 2 ,
184.Xr sendto 2 ,
185.Xr recvfrom 2 ,
186.Xr sendmsg 2
187and
188.Xr recvmsg 2
189on a communications channel or a low speed device
190and during a
191.Xr ioctl 2
192or
193.Xr wait 2 .
194However, calls that have already committed are not restarted,
195but instead return a partial success (for example, a short read count).
196These semantics could be changed with
197.Xr siginterrupt 3 .
198.Pp
199When a process which has installed signal handlers forks,
200the child process inherits the signals.
201All caught signals may be reset to their default action by a call
202to the
203.Xr execve 2
204function;
205ignored signals remain ignored.
206.Pp
207See
208.Xr sigaction 2
209for a list of functions
210that are considered safe for use in signal handlers.
211.Sh RETURN VALUES
212The previous action is returned on a successful call.
213Otherwise, SIG_ERR is returned and the global variable
214.Va errno
215is set to indicate the error.
216.Sh ERRORS
217The
218.Fn signal
219function
220will fail and no action will take place if one of the
221following occur:
222.Bl -tag -width Er
223.It Bq Er EINVAL
224The
225.Fa sig
226argument
227is not a valid signal number.
228.It Bq Er EINVAL
229An attempt is made to ignore or supply a handler for
230.Dv SIGKILL
231or
232.Ev SIGSTOP .
233.El
234.Sh SEE ALSO
235.Xr kill 1 ,
236.Xr kill 2 ,
237.Xr ptrace 2 ,
238.Xr sigaction 2 ,
239.Xr sigaltstack 2 ,
240.Xr sigprocmask 2 ,
241.Xr sigsuspend 2 ,
242.Xr fpsetmask 3 ,
243.Xr setjmp 3 ,
244.Xr siginterrupt 3 ,
245.Xr tty 4
246.Sh HISTORY
247This
248.Fn signal
249facility appeared in
250.Bx 4.0 .