diff options
Diffstat (limited to 'man2/sigaction.2')
| -rw-r--r-- | man2/sigaction.2 | 466 |
1 files changed, 466 insertions, 0 deletions
diff --git a/man2/sigaction.2 b/man2/sigaction.2 new file mode 100644 index 000000000..eaa4f67b8 --- /dev/null +++ b/man2/sigaction.2 @@ -0,0 +1,466 @@ +'\" t +.\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au> +.\" based on work by faith@cs.unc.edu +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" Modified, aeb, 960424 +.\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. +.\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox - add POSIX.1b signals +.\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones <ejones@uwaterloo.ca> - SA_ONSTACK +.\" +.TH SIGACTION 2 2001-12-29 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +sigaction, sigprocmask, sigpending, sigsuspend \- POSIX signal handling functions +.SH SYNOPSIS +.B #include <signal.h> +.sp 2 +.BI "int sigaction(int " signum ", const struct sigaction *" act , +.BI "struct sigaction *" oldact ); +.sp +.BI "int sigprocmask(int " how ", const sigset_t *" set , +.BI "sigset_t *" oldset ); +.sp +.BI "int sigpending(sigset_t *" set ); +.sp +.BI "int sigsuspend(const sigset_t *" mask ); +.SH DESCRIPTION +The +.B sigaction +system call is used to change the action taken by a process on +receipt of a specific signal. +.PP +.I signum +specifies the signal and can be any valid signal except +.B SIGKILL +and +.BR SIGSTOP . +.PP +If +.I act +is non\-null, the new action for signal +.I signum +is installed from +.IR act . +If +.I oldact +is non\-null, the previous action is saved in +.IR oldact . +.PP +The +.B sigaction +structure is defined as something like +.sp +.RS +.nf +struct sigaction { + void (*sa_handler)(int); + void (*sa_sigaction)(int, siginfo_t *, void *); + sigset_t sa_mask; + int sa_flags; + void (*sa_restorer)(void); +} +.fi +.RE +.PP +On some architectures a union is involved - do not assign to both +.I sa_handler +and +.IR sa_sigaction . +.PP +The +.I sa_restorer +element is obsolete and should not be used. +POSIX does not specify a +.I sa_restorer +element. +.PP +.I sa_handler +specifies the action to be associated with +.I signum +and may be +.B SIG_DFL +for the default action, +.B SIG_IGN +to ignore this signal, or a pointer to a signal handling function. +This function receives the signal number as its only argument. +.PP +.I sa_sigaction +also specifies the action to be associated with +.IR signum . +This function receives the signal number as its first argument, a +pointer to a +.I siginfo_t +as its second argument and a pointer to a +.I ucontext_t +(cast to void *) as its third argument. +.PP +.I sa_mask +gives a mask of signals which should be blocked during execution of +the signal handler. In addition, the signal which triggered the handler +will be blocked, unless the +.B SA_NODEFER +or +.B SA_NOMASK +flags are used. +.PP +.I sa_flags +specifies a set of flags which modify the behaviour of the signal handling +process. It is formed by the bitwise OR of zero or more of the following: +.RS +.TP +.B SA_NOCLDSTOP +If +.I signum +is +.BR SIGCHLD ", " +do not receive notification when child processes stop (i.e., when child +processes receive one of +.BR SIGSTOP ", " SIGTSTP ", " SIGTTIN +or +.BR SIGTTOU ")." +.TP +.BR SA_ONESHOT " or " SA_RESETHAND +Restore the signal action to the default state once the signal handler +has been called. +.TP +.BR SA_ONSTACK +Call the signal handler on an alternate signal stack provided by +.BR sigaltstack (2). +If an alternate stack is not available, the default stack will be used. +.TP +.B SA_RESTART +Provide behaviour compatible with BSD signal semantics by making certain +system calls restartable across signals. +.TP +.BR SA_NOMASK " or " SA_NODEFER +Do not prevent the signal from being received from within its own signal +handler. +.TP +.B SA_SIGINFO +The signal handler takes 3 arguments, not one. In this case, +.I sa_sigaction +should be set instead of +.IR sa_handler . +(The sa_sigaction field was added in Linux 2.1.86.) +.RE +.PP +The +.I siginfo_t +parameter to +.I sa_sigaction +is a struct with the following elements +.sp +.RS +.nf +.ta 4 13 24 +siginfo_t { + int si_signo; /* Signal number */ + int si_errno; /* An errno value */ + int si_code; /* Signal code */ + pid_t si_pid; /* Sending process ID */ + uid_t si_uid; /* Real user ID of sending process */ + int si_status; /* Exit value or signal */ + clock_t si_utime; /* User time consumed */ + clock_t si_stime; /* System time consumed */ + sigval_t si_value; /* Signal value */ + int si_int; /* POSIX.1b signal */ + void * si_ptr; /* POSIX.1b signal */ + void * si_addr; /* Memory location which caused fault */ + int si_band; /* Band event */ + int si_fd; /* File descriptor */ +} +.fi +.RE + +.IR si_signo ", " si_errno " and " si_code +are defined for all signals. +The rest of the struct may be a union, so that one should only +read the fields that are meaningful for the given signal. +.BR kill (2), +POSIX.1b signals and SIGCHLD fill in +.IR si_pid " and " si_uid . +.BR +SIGCHLD also fills in +.IR si_status ", " si_utime " and " si_stime . +.IR si_int " and " si_ptr +are specified by the sender of the POSIX.1b signal. +.\" See +.\" .BR sigqueue (2) +.\" for more details. +SIGILL, SIGFPE, SIGSEGV and SIGBUS fill in +.I si_addr +with the address of the fault. +SIGPOLL fills in +.IR si_band " and " si_fd . + +.I si_code +indicates why this signal was sent. It is a value, not a bitmask. The +values which are possible for any signal are listed in this table: +.TS +tab(:) allbox; +c s +l l. +\fIsi_code\fR +Value:Signal origin +SI_USER:kill, sigsend or raise +SI_KERNEL:The kernel +SI_QUEUE:sigqueue +SI_TIMER:timer expired +SI_MESGQ:mesq state changed +SI_ASYNCIO:AIO completed +SI_SIGIO:queued SIGIO +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGILL +ILL_ILLOPC:illegal opcode +ILL_ILLOPN:illegal operand +ILL_ILLADR:illegal addressing mode +ILL_ILLTRP:illegal trap +ILL_PRVOPC:privileged opcode +ILL_PRVREG:privileged register +ILL_COPROC:coprocessor error +ILL_BADSTK:internal stack error +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGFPE +FPE_INTDIV:integer divide by zero +FPE_INTOVF:integer overflow +FPE_FLTDIV:floating point divide by zero +FPE_FLTOVF:floating point overflow +FPE_FLTUND:floating point underflow +FPE_FLTRES:floating point inexact result +FPE_FLTINV:floating point invalid operation +FPE_FLTSUB:subscript out of range +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGSEGV +SEGV_MAPERR:address not mapped to object +SEGV_ACCERR:invalid permissions for mapped object +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGBUS +BUS_ADRALN:invalid address alignment +BUS_ADRERR:non-existent physical address +BUS_OBJERR:object specific hardware error +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGTRAP +TRAP_BRKPT:process breakpoint +TRAP_TRACE:process trace trap +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGCHLD +CLD_EXITED:child has exited +CLD_KILLED:child was killed +CLD_DUMPED:child terminated abnormally +CLD_TRAPPED:traced child has trapped +CLD_STOPPED:child has stopped +CLD_CONTINUED:stopped child has continued +.TE + +.TS +tab(:) allbox; +c s +l l. +SIGPOLL +POLL_IN:data input available +POLL_OUT:output buffers available +POLL_MSG:input message available +POLL_ERR:i/o error +POLL_PRI:high priority input available +POLL_HUP:device disconnected +.TE + +.PP +The +.B sigprocmask +call is used to change the list of currently blocked signals. The +behaviour of the call is dependent on the value of +.IR how , +as follows. +.RS +.TP +.B SIG_BLOCK +The set of blocked signals is the union of the current set and the +.I set +argument. +.TP +.B SIG_UNBLOCK +The signals in +.I set +are removed from the current set of blocked signals. It is legal to +attempt to unblock a signal which is not blocked. +.TP +.B SIG_SETMASK +The set of blocked signals is set to the argument +.IR set . +.RE +.PP +If +.I oldset +is non\-null, the previous value of the signal mask is stored in +.IR oldset . +.PP +The +.B sigpending +call allows the examination of pending signals (ones which have been +raised while blocked). The signal mask of pending signals is stored +in +.IR set . +.PP +The +.B sigsuspend +call temporarily replaces the signal mask for the process with that +given by +.I mask +and then suspends the process until a signal is received. + +.SH "RETURN VALUE" +The functions +.BR sigaction , +.BR sigprocmask , +and +.B sigpending +return 0 on success and \-1 on error. +The function +.B sigsuspend +always returns \-1, normally with the error +.BR EINTR . + +.SH ERRORS +.TP +.B EFAULT +.IR act ", " oldact ", " set ", " oldset +or +.I mask +point to memory which is not a valid part of the process address space. +.TP +.B EINTR +System call was interrupted. +.TP +.B EINVAL +An invalid signal was specified. This will also be generated if an attempt +is made to change the action for +.BR SIGKILL " or " SIGSTOP ", " +which cannot be caught. +.SH NOTES +It is not possible to block +.BR SIGKILL " or " SIGSTOP +with the sigprocmask call. Attempts to do so will be silently ignored. +.PP +According to POSIX, the behaviour of a process is undefined after it +ignores a SIGFPE, SIGILL, or SIGSEGV signal that was not generated +by the \fIkill()\fP or the \fIraise()\fP functions. +Integer division by zero has undefined result. +On some architectures it will generate a SIGFPE signal. +(Also dividing the most negative integer by \-1 may generate SIGFPE.) +Ignoring this signal might lead to an endless loop. +.PP +POSIX (B.3.3.1.3) disallows setting the action for SIGCHLD to SIG_IGN. +The BSD and SYSV behaviours differ, causing BSD software +that sets the action for SIGCHLD to SIG_IGN to fail on Linux. +.PP +The POSIX spec only defines +.BR SA_NOCLDSTOP . +Use of other +.I sa_flags +is non\-portable. +.PP +The +.B SA_RESETHAND +flag is compatible with the SVr4 flag of the same name. +.PP +The +.B SA_NODEFER +flag is compatible with the SVr4 flag of the same name under kernels +1.3.9 and newer. On older kernels the Linux implementation +allowed the receipt of any signal, not just the one we are installing +(effectively overriding any +.I sa_mask +settings). +.PP +The +.BR SA_RESETHAND " and " SA_NODEFER +names for SVr4 compatibility are present only in library versions 3.0.9 +and greater. +.PP +The +.B SA_SIGINFO +flag is specified by POSIX.1b. Support for it was added in Linux 2.2. +.PP +.B sigaction +can be called with a null second argument to query the current signal +handler. It can also be used to check whether a given signal is valid for +the current machine by calling it with null second and third arguments. +.PP +See +.BR sigsetops (3) +for details on manipulating signal sets. +.SH "CONFORMING TO" +POSIX, SVr4. SVr4 does not document the EINTR condition. + +.SH UNDOCUMENTED +Before the introduction of +.B SA_SIGINFO +it was also possible to get some additional information, +namely by using a sa_handler with second argument of type +.IR "struct sigcontext". +See the relevant kernel sources for details. +This use is obsolete now. + +.SH "SEE ALSO" +.BR kill (1), +.BR kill (2), +.BR killpg (2), +.BR pause (2), +.BR sigaltstack (2), +.BR signal (2), +.BR sigvec (2), +.BR raise (3), +.BR siginterrupt (3), +.BR sigsetops (3), +.BR signal (7) |