]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/sigaction.2
xnu-7195.101.1.tar.gz
[apple/xnu.git] / bsd / man / man2 / sigaction.2
CommitLineData
9bccf70c
A
1.\" Copyright (c) 1980, 1990, 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.\"
55e303ae
A
32.\" From: @(#)sigaction.2 8.2 (Berkeley) 4/3/94
33.\" $FreeBSD: src/lib/libc/sys/sigaction.2,v 1.48 2003/03/24 16:07:19 charnier Exp $
9bccf70c 34.\"
b0d623f7 35.Dd September 18, 2008
9bccf70c
A
36.Dt SIGACTION 2
37.Os
38.Sh NAME
39.Nm sigaction
40.Nd software signal facilities
55e303ae
A
41.Sh LIBRARY
42.Lb libc
9bccf70c 43.Sh SYNOPSIS
55e303ae 44.In signal.h
9bccf70c 45.Bd -literal
b0d623f7 46
55e303ae 47struct sigaction {
b0d623f7 48 union __sigaction_u __sigaction_u; /* signal handler */
55e303ae 49 sigset_t sa_mask; /* signal mask to apply */
b0d623f7
A
50 int sa_flags; /* see signal options below */
51};
52
53union __sigaction_u {
54 void (*__sa_handler)(int);
3e170ce0 55 void (*__sa_sigaction)(int, siginfo_t *,
b0d623f7 56 void *);
9bccf70c 57};
55e303ae
A
58
59#define sa_handler __sigaction_u.__sa_handler
60#define sa_sigaction __sigaction_u.__sa_sigaction
b0d623f7 61
9bccf70c
A
62.Ed
63.Ft int
55e303ae
A
64.Fo sigaction
65.Fa "int sig"
2d21ac55
A
66.Fa "const struct sigaction *restrict act"
67.Fa "struct sigaction *restrict oact"
55e303ae 68.Fc
9bccf70c
A
69.Sh DESCRIPTION
70The system defines a set of signals that may be delivered to a process.
71Signal delivery resembles the occurrence of a hardware interrupt:
55e303ae 72the signal is normally blocked from further occurrence, the current process
9bccf70c
A
73context is saved, and a new one is built. A process may specify a
74.Em handler
55e303ae 75to which a signal is delivered, or specify that a signal is to be
9bccf70c
A
76.Em ignored .
77A process may also specify that a default action is to be taken
78by the system when a signal occurs.
79A signal may also be
80.Em blocked ,
81in which case its delivery is postponed until it is
82.Em unblocked .
83The action to be taken on delivery is determined at the time
84of delivery.
85Normally, signal handlers execute on the current stack
86of the process. This may be changed, on a per-handler basis,
87so that signals are taken on a special
88.Em "signal stack" .
89.Pp
55e303ae 90Signal routines normally execute with the signal that caused their
9bccf70c
A
91invocation
92.Em blocked ,
93but other signals may yet occur.
55e303ae 94A global
9bccf70c
A
95.Em "signal mask"
96defines the set of signals currently blocked from delivery
97to a process. The signal mask for a process is initialized
98from that of its parent (normally empty). It
99may be changed with a
100.Xr sigprocmask 2
101call, or when a signal is delivered to the process.
102.Pp
103When a signal
104condition arises for a process, the signal is added to a set of
105signals pending for the process.
106If the signal is not currently
107.Em blocked
108by the process then it is delivered to the process.
109Signals may be delivered any time a process enters the operating system
110(e.g., during a system call, page fault or trap, or clock interrupt).
111If multiple signals are ready to be delivered at the same time,
112any signals that could be caused by traps are delivered first.
113Additional signals may be processed at the same time, with each
114appearing to interrupt the handlers for the previous signals
115before their first instructions.
116The set of pending signals is returned by the
117.Xr sigpending 2
55e303ae 118system call.
9bccf70c
A
119When a caught signal
120is delivered, the current state of the process is saved,
55e303ae 121a new signal mask is calculated (as described below),
9bccf70c
A
122and the signal handler is invoked. The call to the handler
123is arranged so that if the signal handling routine returns
124normally the process will resume execution in the context
125from before the signal's delivery.
126If the process wishes to resume in a different context, then it
127must arrange to restore the previous context itself.
128.Pp
129When a signal is delivered to a process a new signal mask is
130installed for the duration of the process' signal handler
131(or until a
55e303ae
A
132.Xr sigprocmask 2
133system call is made).
9bccf70c 134This mask is formed by taking the union of the current signal mask set,
55e303ae 135the signal to be delivered, and
9bccf70c
A
136the signal mask associated with the handler to be invoked.
137.Pp
55e303ae
A
138The
139.Fn sigaction
140system call
141assigns an action for a signal specified by
142.Fa sig .
9bccf70c
A
143If
144.Fa act
145is non-zero, it
146specifies an action
55e303ae 147.Dv ( SIG_DFL ,
9bccf70c
A
148.Dv SIG_IGN ,
149or a handler routine) and mask
150to be used when delivering the specified signal.
55e303ae 151If
9bccf70c
A
152.Fa oact
153is non-zero, the previous handling information for the signal
154is returned to the user.
155.Pp
55e303ae 156Once a signal handler is installed, it normally remains installed
9bccf70c
A
157until another
158.Fn sigaction
55e303ae 159system call is made, or an
9bccf70c
A
160.Xr execve 2
161is performed.
162A signal-specific default action may be reset by
163setting
164.Fa sa_handler
165to
166.Dv SIG_DFL .
167The defaults are process termination, possibly with core dump;
168no action; stopping the process; or continuing the process.
169See the signal list below for each signal's default action.
170If
171.Fa sa_handler
172is
173.Dv SIG_DFL ,
174the default action for the signal is to discard the signal,
175and if a signal is pending,
176the pending signal is discarded even if the signal is masked.
177If
178.Fa sa_handler
179is set to
180.Dv SIG_IGN
181current and pending instances
182of the signal are ignored and discarded.
183.Pp
184Options may be specified by setting
55e303ae
A
185.Va sa_flags .
186The meaning of the various bits is as follows:
187.Bl -tag -offset indent -width SA_RESETHANDXX
188.It Dv SA_NOCLDSTOP
189If this bit is set when installing a catching function
9bccf70c
A
190for the
191.Dv SIGCHLD
192signal,
193the
194.Dv SIGCHLD
195signal will be generated only when a child process exits,
196not when a child process stops.
55e303ae
A
197.It Dv SA_NOCLDWAIT
198If this bit is set when calling
199.Fn sigaction
200for the
201.Dv SIGCHLD
202signal, the system will not create zombie processes when children of
203the calling process exit. If the calling process subsequently issues
204a
205.Xr wait 2
206(or equivalent), it blocks until all of the calling process's child
207processes terminate, and then returns a value of -1 with errno set to
208.Er ECHILD .
209.It Dv SA_ONSTACK
210If this bit is set, the system will deliver the signal to the process
211on a
9bccf70c
A
212.Em "signal stack" ,
213specified with
55e303ae
A
214.Xr sigaltstack 2 .
215.It Dv SA_NODEFER
216If this bit is set, further occurrences of the delivered signal are
217not masked during the execution of the handler.
218.It Dv SA_RESETHAND
219If this bit is set, the handler is reset back to
220.Dv SIG_DFL
221at the moment the signal is delivered.
222.It Dv SA_RESTART
223See paragraph below.
224.It Dv SA_SIGINFO
225If this bit is set, the handler function is assumed to be pointed to by the
226.Dv sa_sigaction
227member of struct sigaction and should match the prototype shown above or as
228below in
229.Sx EXAMPLES .
230This bit should not be set when assigning
231.Dv SIG_DFL
232or
233.Dv SIG_IGN .
234.El
9bccf70c
A
235.Pp
236If a signal is caught during the system calls listed below,
237the call may be forced to terminate
238with the error
55e303ae 239.Er EINTR ,
9bccf70c
A
240the call may return with a data transfer shorter than requested,
241or the call may be restarted.
242Restart of pending calls is requested
243by setting the
244.Dv SA_RESTART
245bit in
55e303ae 246.Va sa_flags .
9bccf70c
A
247The affected system calls include
248.Xr open 2 ,
249.Xr read 2 ,
250.Xr write 2 ,
251.Xr sendto 2 ,
252.Xr recvfrom 2 ,
253.Xr sendmsg 2
254and
255.Xr recvmsg 2
256on a communications channel or a slow device (such as a terminal,
257but not a regular file)
258and during a
259.Xr wait 2
260or
261.Xr ioctl 2 .
262However, calls that have already committed are not restarted,
263but instead return a partial success (for example, a short read count).
264.Pp
265After a
266.Xr fork 2
267or
268.Xr vfork 2
269all signals, the signal mask, the signal stack,
270and the restart/interrupt flags are inherited by the child.
271.Pp
55e303ae
A
272The
273.Xr execve 2
274system call reinstates the default
9bccf70c
A
275action for all signals which were caught and
276resets all signals to be caught on the user stack.
277Ignored signals remain ignored;
278the signal mask remains the same;
279signals that restart pending system calls continue to do so.
280.Pp
281The following is a list of all signals
282with names as in the include file
283.Aq Pa signal.h :
284.Bl -column SIGVTALARMXX "create core imagexxx"
55e303ae 285.It Sy "NAME Default Action Description"
9bccf70c
A
286.It Dv SIGHUP No " terminate process" " terminal line hangup"
287.It Dv SIGINT No " terminate process" " interrupt program"
288.It Dv SIGQUIT No " create core image" " quit program"
289.It Dv SIGILL No " create core image" " illegal instruction"
290.It Dv SIGTRAP No " create core image" " trace trap"
55e303ae 291.It Dv SIGABRT No " create core image" Ta Xr abort 3
9bccf70c
A
292call (formerly
293.Dv SIGIOT )
294.It Dv SIGEMT No " create core image" " emulate instruction executed"
295.It Dv SIGFPE No " create core image" " floating-point exception"
296.It Dv SIGKILL No " terminate process" " kill program"
297.It Dv SIGBUS No " create core image" " bus error"
298.It Dv SIGSEGV No " create core image" " segmentation violation"
55e303ae 299.It Dv SIGSYS No " create core image" " non-existent system call invoked"
9bccf70c
A
300.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader"
301.It Dv SIGALRM No " terminate process" " real-time timer expired"
302.It Dv SIGTERM No " terminate process" " software termination signal"
303.It Dv SIGURG No " discard signal" " urgent condition present on socket"
304.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)"
305.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard"
306.It Dv SIGCONT No " discard signal" " continue after stop"
307.It Dv SIGCHLD No " discard signal" " child status has changed"
308.It Dv SIGTTIN No " stop process" " background read attempted from control terminal"
309.It Dv SIGTTOU No " stop process" " background write attempted to control terminal"
310.It Dv SIGIO No " discard signal" Tn " I/O"
311is possible on a descriptor (see
312.Xr fcntl 2 )
313.It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see"
314.Xr setrlimit 2 )
315.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see"
316.Xr setrlimit 2 )
317.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see"
318.Xr setitimer 2 )
319.It Dv SIGPROF No " terminate process" " profiling timer alarm (see"
320.Xr setitimer 2 )
321.It Dv SIGWINCH No " discard signal" " Window size change"
322.It Dv SIGINFO No " discard signal" " status request from keyboard"
323.It Dv SIGUSR1 No " terminate process" " User defined signal 1"
324.It Dv SIGUSR2 No " terminate process" " User defined signal 2"
325.El
326.Sh NOTE
55e303ae
A
327The
328.Fa sa_mask
329field specified in
9bccf70c
A
330.Fa act
331is not allowed to block
332.Dv SIGKILL
333or
334.Dv SIGSTOP .
55e303ae
A
335Any attempt to do so will be silently ignored.
336.Pp
337The following functions are either reentrant or not interruptible
338by signals and are async-signal safe.
339Therefore applications may
340invoke them, without restriction, from signal-catching functions:
341.Pp
342Base Interfaces:
343.Pp
344.Fn _exit ,
345.Fn access ,
346.Fn alarm ,
347.Fn cfgetispeed ,
348.Fn cfgetospeed ,
349.Fn cfsetispeed ,
350.Fn cfsetospeed ,
351.Fn chdir ,
352.Fn chmod ,
353.Fn chown ,
354.Fn close ,
355.Fn creat ,
356.Fn dup ,
357.Fn dup2 ,
358.Fn execle ,
359.Fn execve ,
360.Fn fcntl ,
361.Fn fork ,
362.Fn fpathconf ,
363.Fn fstat ,
364.Fn fsync ,
365.Fn getegid ,
366.Fn geteuid ,
367.Fn getgid ,
368.Fn getgroups ,
369.Fn getpgrp ,
370.Fn getpid ,
371.Fn getppid ,
372.Fn getuid ,
373.Fn kill ,
374.Fn link ,
375.Fn lseek ,
376.Fn mkdir ,
377.Fn mkfifo ,
378.Fn open ,
379.Fn pathconf ,
380.Fn pause ,
381.Fn pipe ,
382.Fn raise ,
383.Fn read ,
384.Fn rename ,
385.Fn rmdir ,
386.Fn setgid ,
387.Fn setpgid ,
388.Fn setsid ,
389.Fn setuid ,
390.Fn sigaction ,
391.Fn sigaddset ,
392.Fn sigdelset ,
393.Fn sigemptyset ,
394.Fn sigfillset ,
395.Fn sigismember ,
396.Fn signal ,
397.Fn sigpending ,
398.Fn sigprocmask ,
399.Fn sigsuspend ,
400.Fn sleep ,
401.Fn stat ,
402.Fn sysconf ,
403.Fn tcdrain ,
404.Fn tcflow ,
405.Fn tcflush ,
406.Fn tcgetattr ,
407.Fn tcgetpgrp ,
408.Fn tcsendbreak ,
409.Fn tcsetattr ,
410.Fn tcsetpgrp ,
411.Fn time ,
412.Fn times ,
413.Fn umask ,
414.Fn uname ,
415.Fn unlink ,
416.Fn utime ,
417.Fn wait ,
418.Fn waitpid ,
419.Fn write .
420.Pp
421Realtime Interfaces:
422.Pp
423.Fn aio_error ,
55e303ae 424.Fn sigpause ,
55e303ae 425.Fn aio_return ,
55e303ae
A
426.Fn aio_suspend ,
427.Fn sem_post ,
b0d623f7 428.Fn sigset .
55e303ae
A
429.Pp
430ANSI C Interfaces:
431.Pp
432.Fn strcpy ,
433.Fn strcat ,
434.Fn strncpy ,
435.Fn strncat ,
436and perhaps some others.
437.Pp
438Extension Interfaces:
439.Pp
440.Fn strlcpy ,
441.Fn strlcat .
442.Pp
443All functions not in the above lists are considered to be unsafe
444with respect to signals. That is to say, the behaviour of such
445functions when called from a signal handler is undefined.
446In general though, signal handlers should do little more than set a
447flag; most other actions are not safe.
448.Pp
449Also, it is good practice to make a copy of the global variable
9bccf70c 450.Va errno
55e303ae
A
451and restore it before returning from the signal handler.
452This protects against the side effect of
453.Va errno
454being set by functions called from inside the signal handler.
455.Sh RETURN VALUES
456.Rv -std sigaction
457.Sh EXAMPLES
458There are three possible prototypes the handler may match:
459.Bl -tag -offset indent -width short
460.It ANSI C:
461.Ft void
462.Fn handler int ;
463.It POSIX SA_SIGINFO:
464.Ft void
465.Fn handler int "siginfo_t *info" "ucontext_t *uap" ;
466.El
467.Pp
468The handler function should match the SA_SIGINFO prototype if the
469SA_SIGINFO bit is set in flags.
470It then should be pointed to by the
471.Dv sa_sigaction
472member of
473.Dv struct sigaction .
474Note that you should not assign SIG_DFL or SIG_IGN this way.
475.Pp
476If the SA_SIGINFO flag is not set, the handler function should match
477either the ANSI C or traditional
478.Bx
479prototype and be pointed to by
480the
481.Dv sa_handler
482member of
483.Dv struct sigaction .
484In practice,
485.Fx
486always sends the three arguments of the latter and since the ANSI C
487prototype is a subset, both will work.
488The
489.Dv sa_handler
490member declaration in
491.Fx
492include files is that of ANSI C (as required by POSIX),
493so a function pointer of a
494.Bx Ns -style
495function needs to be casted to
496compile without warning.
497The traditional
498.Bx
499style is not portable and since its capabilities
500are a full subset of a SA_SIGINFO handler,
501its use is deprecated.
9bccf70c 502.Pp
55e303ae 503The
9bccf70c 504.Fa sig
55e303ae
A
505argument is the signal number, one of the
506.Dv SIG...
507values from <signal.h>.
508.Pp
509The
510.Fa code
511argument of the
512.Bx Ns -style
513handler and the
514.Dv si_code
515member of the
516.Dv info
517argument to a SA_SIGINFO handler contain a numeric code explaining the
518cause of the signal, usually one of the
519.Dv SI_...
520values from
521<sys/signal.h> or codes specific to a signal, i.e. one of the
522.Dv FPE_...
523values for SIGFPE.
524.Pp
525The
526.Fa uap
527argument to a POSIX SA_SIGINFO handler points to an instance of
528ucontext_t.
9bccf70c 529.Sh ERRORS
55e303ae
A
530The
531.Fn sigaction
532system call
9bccf70c
A
533will fail and no new signal handler will be installed if one
534of the following occurs:
535.Bl -tag -width Er
2d21ac55 536.\" ===========
9bccf70c
A
537.It Bq Er EFAULT
538Either
539.Fa act
55e303ae 540or
9bccf70c
A
541.Fa oact
542points to memory that is not a valid part of the process
543address space.
2d21ac55 544.\" ===========
9bccf70c 545.It Bq Er EINVAL
55e303ae
A
546The
547.Fa sig
548argument
9bccf70c 549is not a valid signal number.
2d21ac55 550.\" ===========
9bccf70c
A
551.It Bq Er EINVAL
552An attempt is made to ignore or supply a handler for
553.Dv SIGKILL
554or
555.Dv SIGSTOP .
2d21ac55
A
556.\" ===========
557.It Bq Er EINVAL
558An attempt was made to set the action to SIG_DFL
559for a signal that cannot be caught or ignored (or both).
9bccf70c
A
560.El
561.Sh STANDARDS
562The
55e303ae
A
563.Fn sigaction
564system call is expected to conform to
565.St -p1003.1-90 .
9bccf70c
A
566The
567.Dv SA_ONSTACK
568and
569.Dv SA_RESTART
570flags are Berkeley extensions,
571as are the signals,
572.Dv SIGTRAP ,
573.Dv SIGEMT ,
574.Dv SIGBUS ,
575.Dv SIGSYS ,
576.Dv SIGURG ,
577.Dv SIGIO ,
578.Dv SIGXCPU ,
579.Dv SIGXFSZ ,
580.Dv SIGVTALRM ,
581.Dv SIGPROF ,
582.Dv SIGWINCH ,
583and
584.Dv SIGINFO .
585Those signals are available on most
55e303ae 586.Bx Ns \-derived
9bccf70c 587systems.
55e303ae
A
588The
589.Dv SA_NODEFER
590and
591.Dv SA_RESETHAND
592flags are intended for backwards compatibility with other operating
593systems. The
594.Dv SA_NOCLDSTOP ,
595and
596.Dv SA_NOCLDWAIT
597.\" and
598.\" SA_SIGINFO
599flags are featuring options commonly found in other operating systems.
9bccf70c
A
600.Sh SEE ALSO
601.Xr kill 1 ,
9bccf70c 602.Xr kill 2 ,
55e303ae
A
603.Xr ptrace 2 ,
604.Xr sigaltstack 2 ,
9bccf70c 605.Xr sigblock 2 ,
9bccf70c 606.Xr sigpause 2 ,
55e303ae
A
607.Xr sigpending 2 ,
608.Xr sigprocmask 2 ,
609.Xr sigsetmask 2 ,
610.Xr sigsuspend 2 ,
611.Xr sigvec 2 ,
612.Xr wait 2 ,
613.Xr fpsetmask 3 ,
9bccf70c
A
614.Xr setjmp 3 ,
615.Xr siginterrupt 3 ,
616.Xr sigsetops 3 ,
55e303ae 617.Xr ucontext 3 ,
9bccf70c 618.Xr tty 4