sigaction(S) 6 January 1993 sigaction(S) Name sigaction - change and/or examine signal action Syntax cc . . . -lc #include <signal.h> int sigaction (sig, act, oact) int sig; struct sigaction *act, *oact; Description The routine sigaction allows the calling process to examine or specify (or both) the action to be taken upon delivery of the specified signal. The structure sigaction, which describes the action to be taken, is defined in the header file <signal.h> to include the following members: _________________________________________________________________________ Member Description _________________________________________________________________________ void (*)() sa_handler SIG_DFL, SIG_IGN, or a pointer to a user-defined, signal-catching function. sigset_t sa_mask Additional set of signals to be blocked during exe- cution of a signal-catching function. int sa_flags Special flags to affect the behavior of the signal. The sig argument can be assigned any one of the following values except SIGKILL and SIGSTOP: _________________________________________________________________________ Signal ValueDescription XPG 3POSIX ANSI _________________________________________________________________________ SIGHUP 01 hangup + + SIGINT 02 interrupt + + + SIGQUIT 03[1]quit + + SIGILL 04[1]illegal instruction (not reset when caught) + + + SIGTRAP 05[1]trace trap (not reset when caught) SIGIOT 06[1]IOT instruction SIGABRT 06[1]used by abort, replaces SIGIOT + + + SIGEMT 07[1]EMT instruction SIGFPE 08[1]floating point exception + + + SIGKILL 09 kill (cannot be caught or ignored) + + SIGBUS 10[1]bus error SIGSEGV 11[1]segmentation violation + + + SIGSYS 12[1]bad argument to system call SIGPIPE 13 write on a pipe with no one to read it + + SIGALRM 14 alarm clock + + SIGTERM 15 software termination signal + + + SIGUSR1 16 user-defined signal 1 + + SIGUSR2 17 user-defined signal 2 + + SIGCLD 18[3]death of a child SIGCHLD 18[3]synonym for SIGCLD SIGPWR 19[3]power fail SIGWINCH 20 window change SIGPOLL 22[4]selectable event pending SIGSTOP 23[2]sendable stop signal not from tty + + SIGTSTP 24[2]stop signal from tty + + SIGCONT 25[2]continue a stopped process + + SIGTTIN 26[2]background tty read attempt + + SIGTTOU 27[2]background tty write attempt + + SIGVTALRM28 virtual timer alarm SIGPROF 29 profile alarm If the argument act is not null, it points to a structure specifying the action to be associated with the specified signal. If the argument oact is not null, the action previously associated with the signal is stored in the location pointed to by the argument oact. If the argument act is null, signal handling is unchanged; thus, the call can be used to enquire about the current handling of a given signal. The field sahandler of the structure sigaction identifies the action to be associated with the specified signal. The sahandler field is assigned one of the following three values: SIGDFL, SIGIGN, or an address of a function defined by the user. SIGDFL, and SIGIGN, are defined in the header file <signal.h>. Each is a macro that expands to a constant expression of type pointer to function returning void, and hav- ing a unique value that does not match a declarable function. The actions prescribed by the values of the sahandler are as follows: SIGDFL (execute default signal action) Upon receipt of the signal specified by sig, the receiving pro- cess will take the default action. The default action usually results in the termination of the process with all of the conse- quences outlined in exit(S). Those signals with a [1] or a [2] are exceptions to this rule. Their default behavior is described in the corresponding Note section. SIGIGN (ignore signal) Upon receipt of the signal specified by sig, the signal is ignored. Note: the signals SIGKILL and SIGSTOP cannot be ignored. signal-catching function (execute user-defined action) Upon receipt of the signal sig, the receiving process is to exe- cute the signal-catching function pointed to by sahandler. The signal number sig is passed as the only argument to the signal- catching function. Additional arguments are passed to the signal-catching function for hardware-generated signals. Upon return from the signal-catching function, the receiving pro- cess resumes execution at the point it was interrupted. If a signal-catching function is invoked, how it effects the interrupted function is described by each individual function. See the X/Open Portability Guide, Issue 3, 1989 section ``Signal Effects on Other Functions'', for further information. The sigaction routine does not catch an invalid structure field sahandler and results are undefined when an attempt is made to execute the function at the bad address. If the sahandler field points to a signal-catching function, the samask is used as an additional set of signals that are added to the process's current signal mask (that is, the union of the two signal sets is the result). This new mask is valid before entering and for the duration of the signal-catching function or until a call to either the sigprocmask or sigsuspend routines. If and when the signal-catching function returns normally, the initial signal mask is restored. The saflags field in the structure sigaction can be used to alter the behavior of the specified signal. The SANOCLDSTOP flag bit, also defined in the header file <signal.h>, can be set in saflags so that the signal SIGCHLD is not generated when children processes stop. If stopped children processes are not of interest, setting this flag bit prevents the invoking of a signal- catching function for these events. Once an action has been specified for a particular signal, it remains valid until a new course of action has been assigned to the signal with another call to the sigaction routine, a call to the signal routine, or until one of the exec routines is called. If the previous action for sig had been assigned using the signal rou- tine, the fields in the structure sigaction pointed to by the object oact are undefined. However, if a pointer to the same structure or its copy is passed to a subsequent call to sigaction using the act argument, the signal is handled as if the initial call to signal were repeated. If a call to the sigaction routine fails, a new signal handler is not installed. Return value Upon successful completion a value of zero is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error. Diagnostics If the following condition occurs, the sigaction routine returns -1 and sets errno to the corresponding value: [EINVAL] The value of the sig argument is an invalid or unsupported sig- nal number, or an attempt was made to catch a signal that can- not be caught or to ignore a signal that cannot be ignored. Notes [1] If SIGDFL is assigned for these signals, in addition to the process being terminated, a ``core image'' is constructed in the current working directory of the process, if the following conditions are met: The effective user ID and the real user ID of the receiving process are equal. An ordinary file named core exists and is writable or can be created. If the file must be created, it has the following properties: + a mode of 0666 modified by the file creation mask (see umask(S)). + a file owner ID that is the same as the effective user ID of the receiving process. + a file group ID that is the same as the effective group ID of the receiving process. [2] For the signals SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU the default action is to stop the process rather than to terminate the process. The distinction is that a stopped process can be started again with a SIGCONT whereas a terminated process cannot be restarted under any circumstance. For the SIGCONT signal, the default action is to continue the process if it is stopped, otherwise it is ignored. [3] For the signals SIGCLD and SIGPWR, the signal-handling function is, again, assigned one of three values: SIGDFL, SIGIGN, or a function address. The actions prescribed by these values are: SIGDFL (ignore signal) The signal is to be ignored. SIGIGN (ignore signal) The signal is to be ignored. Also, if sig is SIGCLD, the calling process's child processes does not create zombie pro- cesses when they terminate (see exit(S)). function address (catch signal) If the signal is SIGPWR, the action to be taken is the same as that described above for sahandler equal to function address. The same is true if the signal is SIGCLD with one exception: while the process is executing the signal- catching function, any received SIGCLD signals are ignored. (This is the default action.) In addition, SIGCLD affects the wait, waitpid, and exit system calls as follows: wait If the sahandler for SIGCLD is set to SIGIGN and a wait is executed, the wait blocks until all of the calling process's child processes terminate; it then returns a value of -1 with errno set to ECHILD waitpid If the sahandler for SIGCLD is set to SIGIGN and a waitpid is executed, the waitpid blocks until all of the calling pro- cess's child processes terminate; it then returns a value of -1 with errno set to ECHILD. However, if the WNOHANG option is specified, waitpid does not block. exit If in the exiting process's parent process the sahandler value of SIGCLD is set to SIGIGN, the exiting process does not create a zombie process. When processing a pipeline, the shell makes the last process in the pipeline the parent of the preceding processes. A process that may be piped into in this manner (and thus become the parent of other processes) should take care not to set SIGCLD to be caught. [4] SIGPOLL is issued when a file descriptor corresponding to a STREAMS (see Intro(S)) file has a ``selectable'' event pending. A process must specifically request that this signal be sent using the ISETSIG ioctl call. Otherwise, the process never receives SIGPOLL. SIGPOLL is defined to have a value of 20 if used in cross-compiling for XENIX. See also ioctl(S), kill(S), signal(S), sigprocmask(S), sigpending(S), sigsuspend(S), sigset(S), sigsetv(S), sigsetjmp(S) Standards conformance sigaction is conformant with: IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1); X/Open Portability Guide, Issue 3, 1989; and NIST FIPS 151-1.