diff options
Diffstat (limited to 'lib/libc/sys/sigaction.2')
| -rw-r--r-- | lib/libc/sys/sigaction.2 | 669 |
1 files changed, 669 insertions, 0 deletions
diff --git a/lib/libc/sys/sigaction.2 b/lib/libc/sys/sigaction.2 new file mode 100644 index 0000000..53b6a46 --- /dev/null +++ b/lib/libc/sys/sigaction.2 @@ -0,0 +1,669 @@ +.\" Copyright (c) 1980, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" From: @(#)sigaction.2 8.2 (Berkeley) 4/3/94 +.\" $FreeBSD$ +.\" +.Dd June 7, 2004 +.Dt SIGACTION 2 +.Os +.Sh NAME +.Nm sigaction +.Nd software signal facilities +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In signal.h +.Bd -literal +struct sigaction { + union { + void (*__sa_handler)(int); + void (*__sa_sigaction)(int, struct __siginfo *, void *); + } __sigaction_u; /* signal handler */ + int sa_flags; /* see signal options below */ + sigset_t sa_mask; /* signal mask to apply */ +}; + +#define sa_handler __sigaction_u.__sa_handler +#define sa_sigaction __sigaction_u.__sa_sigaction +.Ed +.Ft int +.Fo sigaction +.Fa "int sig" +.Fa "const struct sigaction * restrict act" +.Fa "struct sigaction * restrict oact" +.Fc +.Sh DESCRIPTION +The system defines a set of signals that may be delivered to a process. +Signal delivery resembles the occurrence of a hardware interrupt: +the signal is normally blocked from further occurrence, the current process +context is saved, and a new one is built. +A process may specify a +.Em handler +to which a signal is delivered, or specify that a signal is to be +.Em ignored . +A process may also specify that a default action is to be taken +by the system when a signal occurs. +A signal may also be +.Em blocked , +in which case its delivery is postponed until it is +.Em unblocked . +The action to be taken on delivery is determined at the time +of delivery. +Normally, signal handlers execute on the current stack +of the process. +This may be changed, on a per-handler basis, +so that signals are taken on a special +.Em "signal stack" . +.Pp +Signal routines normally execute with the signal that caused their +invocation +.Em blocked , +but other signals may yet occur. +A global +.Em "signal mask" +defines the set of signals currently blocked from delivery +to a process. +The signal mask for a process is initialized +from that of its parent (normally empty). +It may be changed with a +.Xr sigprocmask 2 +call, or when a signal is delivered to the process. +.Pp +When a signal +condition arises for a process, the signal is added to a set of +signals pending for the process. +If the signal is not currently +.Em blocked +by the process then it is delivered to the process. +Signals may be delivered any time a process enters the operating system +(e.g., during a system call, page fault or trap, or clock interrupt). +If multiple signals are ready to be delivered at the same time, +any signals that could be caused by traps are delivered first. +Additional signals may be processed at the same time, with each +appearing to interrupt the handlers for the previous signals +before their first instructions. +The set of pending signals is returned by the +.Xr sigpending 2 +system call. +When a caught signal +is delivered, the current state of the process is saved, +a new signal mask is calculated (as described below), +and the signal handler is invoked. +The call to the handler +is arranged so that if the signal handling routine returns +normally the process will resume execution in the context +from before the signal's delivery. +If the process wishes to resume in a different context, then it +must arrange to restore the previous context itself. +.Pp +When a signal is delivered to a process a new signal mask is +installed for the duration of the process' signal handler +(or until a +.Xr sigprocmask 2 +system call is made). +This mask is formed by taking the union of the current signal mask set, +the signal to be delivered, and +the signal mask associated with the handler to be invoked. +.Pp +The +.Fn sigaction +system call +assigns an action for a signal specified by +.Fa sig . +If +.Fa act +is non-zero, it +specifies an action +.Dv ( SIG_DFL , +.Dv SIG_IGN , +or a handler routine) and mask +to be used when delivering the specified signal. +If +.Fa oact +is non-zero, the previous handling information for the signal +is returned to the user. +.Pp +Once a signal handler is installed, it normally remains installed +until another +.Fn sigaction +system call is made, or an +.Xr execve 2 +is performed. +A signal-specific default action may be reset by +setting +.Va sa_handler +to +.Dv SIG_DFL . +The defaults are process termination, possibly with core dump; +no action; stopping the process; or continuing the process. +See the signal list below for each signal's default action. +If +.Va sa_handler +is +.Dv SIG_DFL , +the default action for the signal is to discard the signal, +and if a signal is pending, +the pending signal is discarded even if the signal is masked. +If +.Va sa_handler +is set to +.Dv SIG_IGN +current and pending instances +of the signal are ignored and discarded. +.Pp +Options may be specified by setting +.Va sa_flags . +The meaning of the various bits is as follows: +.Bl -tag -offset indent -width SA_RESETHANDXX +.It Dv SA_NOCLDSTOP +If this bit is set when installing a catching function +for the +.Dv SIGCHLD +signal, +the +.Dv SIGCHLD +signal will be generated only when a child process exits, +not when a child process stops. +.It Dv SA_NOCLDWAIT +If this bit is set when calling +.Fn sigaction +for the +.Dv SIGCHLD +signal, the system will not create zombie processes when children of +the calling process exit. +If the calling process subsequently issues a +.Xr wait 2 +(or equivalent), it blocks until all of the calling process's child +processes terminate, and then returns a value of \-1 with +.Va errno +set to +.Er ECHILD . +The same effect of avoiding zombie creation can also be achieved by setting +.Va sa_handler +for +.Dv SIGCHLD +to +.Dv SIG_IGN . +.It Dv SA_ONSTACK +If this bit is set, the system will deliver the signal to the process +on a +.Em "signal stack" , +specified with +.Xr sigaltstack 2 . +.It Dv SA_NODEFER +If this bit is set, further occurrences of the delivered signal are +not masked during the execution of the handler. +.It Dv SA_RESETHAND +If this bit is set, the handler is reset back to +.Dv SIG_DFL +at the moment the signal is delivered. +.It Dv SA_RESTART +See paragraph below. +.It Dv SA_SIGINFO +If this bit is set, the handler function is assumed to be pointed to by the +.Va sa_sigaction +member of +.Vt "struct sigaction" +and should match the prototype shown above or as below in +.Sx EXAMPLES . +This bit should not be set when assigning +.Dv SIG_DFL +or +.Dv SIG_IGN . +.El +.Pp +If a signal is caught during the system calls listed below, +the call may be forced to terminate +with the error +.Er EINTR , +the call may return with a data transfer shorter than requested, +or the call may be restarted. +Restart of pending calls is requested +by setting the +.Dv SA_RESTART +bit in +.Va sa_flags . +The affected system calls include +.Xr open 2 , +.Xr read 2 , +.Xr write 2 , +.Xr sendto 2 , +.Xr recvfrom 2 , +.Xr sendmsg 2 +and +.Xr recvmsg 2 +on a communications channel or a slow device (such as a terminal, +but not a regular file) +and during a +.Xr wait 2 +or +.Xr ioctl 2 . +However, calls that have already committed are not restarted, +but instead return a partial success (for example, a short read count). +.Pp +After a +.Xr fork 2 +or +.Xr vfork 2 +all signals, the signal mask, the signal stack, +and the restart/interrupt flags are inherited by the child. +.Pp +The +.Xr execve 2 +system call reinstates the default +action for all signals which were caught and +resets all signals to be caught on the user stack. +Ignored signals remain ignored; +the signal mask remains the same; +signals that restart pending system calls continue to do so. +.Pp +The following is a list of all signals +with names as in the include file +.In signal.h : +.Bl -column SIGVTALARMXX "create core imagexxx" +.It Sy "NAME Default Action Description" +.It Dv SIGHUP No " terminate process" " terminal line hangup" +.It Dv SIGINT No " terminate process" " interrupt program" +.It Dv SIGQUIT No " create core image" " quit program" +.It Dv SIGILL No " create core image" " illegal instruction" +.It Dv SIGTRAP No " create core image" " trace trap" +.It Dv SIGABRT No " create core image" Ta Xr abort 3 +call (formerly +.Dv SIGIOT ) +.It Dv SIGEMT No " create core image" " emulate instruction executed" +.It Dv SIGFPE No " create core image" " floating-point exception" +.It Dv SIGKILL No " terminate process" " kill program" +.It Dv SIGBUS No " create core image" " bus error" +.It Dv SIGSEGV No " create core image" " segmentation violation" +.It Dv SIGSYS No " create core image" " non-existent system call invoked" +.It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" +.It Dv SIGALRM No " terminate process" " real-time timer expired" +.It Dv SIGTERM No " terminate process" " software termination signal" +.It Dv SIGURG No " discard signal" " urgent condition present on socket" +.It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" +.It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" +.It Dv SIGCONT No " discard signal" " continue after stop" +.It Dv SIGCHLD No " discard signal" " child status has changed" +.It Dv SIGTTIN No " stop process" " background read attempted from control terminal" +.It Dv SIGTTOU No " stop process" " background write attempted to control terminal" +.It Dv SIGIO No " discard signal" Tn " I/O" +is possible on a descriptor (see +.Xr fcntl 2 ) +.It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" +.Xr setrlimit 2 ) +.It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" +.Xr setitimer 2 ) +.It Dv SIGPROF No " terminate process" " profiling timer alarm (see" +.Xr setitimer 2 ) +.It Dv SIGWINCH No " discard signal" " Window size change" +.It Dv SIGINFO No " discard signal" " status request from keyboard" +.It Dv SIGUSR1 No " terminate process" " User defined signal 1" +.It Dv SIGUSR2 No " terminate process" " User defined signal 2" +.El +.Sh NOTE +The +.Va sa_mask +field specified in +.Fa act +is not allowed to block +.Dv SIGKILL +or +.Dv SIGSTOP . +Any attempt to do so will be silently ignored. +.Pp +The following functions are either reentrant or not interruptible +by signals and are async-signal safe. +Therefore applications may +invoke them, without restriction, from signal-catching functions: +.Pp +Base Interfaces: +.Pp +.Fn _exit , +.Fn access , +.Fn alarm , +.Fn cfgetispeed , +.Fn cfgetospeed , +.Fn cfsetispeed , +.Fn cfsetospeed , +.Fn chdir , +.Fn chmod , +.Fn chown , +.Fn close , +.Fn creat , +.Fn dup , +.Fn dup2 , +.Fn execle , +.Fn execve , +.Fn fcntl , +.Fn fork , +.Fn fpathconf , +.Fn fstat , +.Fn fsync , +.Fn getegid , +.Fn geteuid , +.Fn getgid , +.Fn getgroups , +.Fn getpgrp , +.Fn getpid , +.Fn getppid , +.Fn getuid , +.Fn kill , +.Fn link , +.Fn lseek , +.Fn mkdir , +.Fn mkfifo , +.Fn open , +.Fn pathconf , +.Fn pause , +.Fn pipe , +.Fn raise , +.Fn read , +.Fn rename , +.Fn rmdir , +.Fn setgid , +.Fn setpgid , +.Fn setsid , +.Fn setuid , +.Fn sigaction , +.Fn sigaddset , +.Fn sigdelset , +.Fn sigemptyset , +.Fn sigfillset , +.Fn sigismember , +.Fn signal , +.Fn sigpending , +.Fn sigprocmask , +.Fn sigsuspend , +.Fn sleep , +.Fn stat , +.Fn sysconf , +.Fn tcdrain , +.Fn tcflow , +.Fn tcflush , +.Fn tcgetattr , +.Fn tcgetpgrp , +.Fn tcsendbreak , +.Fn tcsetattr , +.Fn tcsetpgrp , +.Fn time , +.Fn times , +.Fn umask , +.Fn uname , +.Fn unlink , +.Fn utime , +.Fn wait , +.Fn waitpid , +.Fn write . +.Pp +Realtime Interfaces: +.Pp +.Fn aio_error , +.Fn clock_gettime , +.Fn sigpause , +.Fn timer_getoverrun , +.Fn aio_return , +.Fn fdatasync , +.Fn sigqueue , +.Fn timer_gettime , +.Fn aio_suspend , +.Fn sem_post , +.Fn sigset , +.Fn timer_settime . +.Pp +.Tn ANSI C +Interfaces: +.Pp +.Fn strcpy , +.Fn strcat , +.Fn strncpy , +.Fn strncat , +and perhaps some others. +.Pp +Extension Interfaces: +.Pp +.Fn strlcpy , +.Fn strlcat . +.Pp +All functions not in the above lists are considered to be unsafe +with respect to signals. +That is to say, the behaviour of such +functions when called from a signal handler is undefined. +In general though, signal handlers should do little more than set a +flag; most other actions are not safe. +.Pp +Also, it is good practice to make a copy of the global variable +.Va errno +and restore it before returning from the signal handler. +This protects against the side effect of +.Va errno +being set by functions called from inside the signal handler. +.Sh RETURN VALUES +.Rv -std sigaction +.Sh EXAMPLES +There are three possible prototypes the handler may match: +.Bl -tag -offset indent -width short +.It Tn ANSI C : +.Ft void +.Fn handler int ; +.It Traditional BSD style: +.Ft void +.Fn handler int "int code" "struct sigcontext *scp" ; +.It Tn POSIX Dv SA_SIGINFO : +.Ft void +.Fn handler int "siginfo_t *info" "ucontext_t *uap" ; +.El +.Pp +The handler function should match the +.Dv SA_SIGINFO +prototype if the +.Dv SA_SIGINFO +bit is set in +.Va sa_flags . +It then should be pointed to by the +.Va sa_sigaction +member of +.Vt "struct sigaction" . +Note that you should not assign +.Dv SIG_DFL +or +.Dv SIG_IGN +this way. +.Pp +If the +.Dv SA_SIGINFO +flag is not set, the handler function should match +either the +.Tn ANSI C +or traditional +.Bx +prototype and be pointed to by +the +.Va sa_handler +member of +.Vt "struct sigaction" . +In practice, +.Fx +always sends the three arguments of the latter and since the +.Tn ANSI C +prototype is a subset, both will work. +The +.Va sa_handler +member declaration in +.Fx +include files is that of +.Tn ANSI C +(as required by +.Tn POSIX ) , +so a function pointer of a +.Bx Ns -style +function needs to be casted to +compile without warning. +The traditional +.Bx +style is not portable and since its capabilities +are a full subset of a +.Dv SA_SIGINFO +handler, +its use is deprecated. +.Pp +The +.Fa sig +argument is the signal number, one of the +.Dv SIG... +values from +.In signal.h . +.Pp +The +.Fa code +argument of the +.Bx Ns -style +handler and the +.Va si_code +member of the +.Fa info +argument to a +.Dv SA_SIGINFO +handler contain a numeric code explaining the +cause of the signal, usually one of the +.Dv SI_... +values from +.In sys/signal.h +or codes specific to a signal, i.e., one of the +.Dv FPE_... +values for +.Dv SIGFPE . +.Pp +The +.Fa scp +argument to a +.Bx Ns -style +handler points to an instance of +.Vt "struct sigcontext" . +.Pp +The +.Fa uap +argument to a +.Tn POSIX +.Dv SA_SIGINFO +handler points to an instance of +ucontext_t. +.Sh ERRORS +The +.Fn sigaction +system call +will fail and no new signal handler will be installed if one +of the following occurs: +.Bl -tag -width Er +.It Bq Er EFAULT +Either +.Fa act +or +.Fa oact +points to memory that is not a valid part of the process +address space. +.It Bq Er EINVAL +The +.Fa sig +argument +is not a valid signal number. +.It Bq Er EINVAL +An attempt is made to ignore or supply a handler for +.Dv SIGKILL +or +.Dv SIGSTOP . +.El +.Sh SEE ALSO +.Xr kill 1 , +.Xr kill 2 , +.Xr ptrace 2 , +.Xr sigaltstack 2 , +.Xr sigblock 2 , +.Xr sigpause 2 , +.Xr sigpending 2 , +.Xr sigprocmask 2 , +.Xr sigsetmask 2 , +.Xr sigsuspend 2 , +.Xr sigvec 2 , +.Xr wait 2 , +.Xr fpsetmask 3 , +.Xr setjmp 3 , +.Xr siginfo 3 , +.Xr siginterrupt 3 , +.Xr sigsetops 3 , +.Xr ucontext 3 , +.Xr tty 4 +.Sh STANDARDS +The +.Fn sigaction +system call is expected to conform to +.St -p1003.1-90 . +The +.Dv SA_ONSTACK +and +.Dv SA_RESTART +flags are Berkeley extensions, +as are the signals, +.Dv SIGTRAP , +.Dv SIGEMT , +.Dv SIGBUS , +.Dv SIGSYS , +.Dv SIGURG , +.Dv SIGIO , +.Dv SIGXCPU , +.Dv SIGXFSZ , +.Dv SIGVTALRM , +.Dv SIGPROF , +.Dv SIGWINCH , +and +.Dv SIGINFO . +Those signals are available on most +.Bx Ns \-derived +systems. +The +.Dv SA_NODEFER +and +.Dv SA_RESETHAND +flags are intended for backwards compatibility with other operating +systems. +The +.Dv SA_NOCLDSTOP , +and +.Dv SA_NOCLDWAIT +.\" and +.\" SA_SIGINFO +flags are featuring options commonly found in other operating systems. +The flags are approved by +.St -susv2 , +along with the option to avoid zombie creation by ignoring +.Dv SIGCHLD . |
