Specifies the action to take upon delivery of a signal.
| Item | Description |
|---|---|
| sigaction | Standard C Library (libc.a) |
| signal, sigvec | Standard C Library (libc.a); |
Berkeley Compatibility Library (libbsd.a)
The sigaction subroutine allows a calling process to examine and change the action to be taken when a specific signal is delivered to the process issuing this subroutine.
In multi-threaded applications using the threads library (libpthreads.a), signal actions are common to all threads within the process. Any thread calling the sigaction subroutine changes the action to be taken when a specific signal is delivered to the threads process, that is, to any thread within the process.
The signal parameter specifies the signal. If the action parameter is not null, it points to a sigaction structure that describes the action to be taken on receipt of the signal parameter signal. If the oaction parameter is not null, it points to a sigaction structure in which the signal action data in effect at the time of the sigaction subroutine call is returned. If the action parameter is null, signal handling is unchanged; thus, the call can be used to inquire about the current handling of a given signal.
The sigaction structure has the following fields:
| Member Type | Member Name | Description |
|---|---|---|
| void(*) (int) | sa_handler | SIG_DFL, SIG_IGN or pointer to a function. |
| sigset_t | sa_mask | Additional set of signals to be blocked during execution of signal-catching function. |
| int | sa_flags | Special flags to affect behaviour of signal. |
| void(*) (int, siginfo_t *, void *) | sa_sigaction | Signal-catching function. |
The sa_handler field can have a SIG_DFL or SIG_IGN value, or it can be a pointer to a function. A SIG_DFL value requests default action to be taken when a signal is delivered. A value of SIG_IGN requests that the signal have no effect on the receiving process. A pointer to a function requests that the signal be caught; that is, the signal should cause the function to be called. These actions are more fully described in "Parameters".
When a signal is delivered to a thread, if the action of that signal specifies termination, stop, or continue, the entire process is terminated, stopped, or continued, respectively.
If the SA_SIGINFO flag (see below) is cleared in the sa_flags field of the sigaction structure, the sa_handler field identifies the action to be associated with the specified signal. If the SA_SIGINFO flag is set in the sa_flags field, the sa_sigaction field specifies a signal-catching function. If the SA_SIGINFO bit is cleared and the sa_handler field specifies a signal-catching function, or if the SA_SIGINFO bit is set, the sa_mask field identifies a set of signals that will be added to the signal mask of the thread before the signal-catching function is invoked.
The sa_mask field can be used to specify that individual signals, in addition to those in the process signal mask, be blocked from being delivered while the signal handler function specified in the sa_handler field is operating. The sa_flags field can have the SA_ONSTACK, SA_OLDSTYLE, or SA_NOCLDSTOP bits set to specify further control over the actions taken on delivery of a signal.
If the SA_ONSTACK bit is set, the system runs the signal-catching function on the signal stack specified by the sigstack subroutine. If this bit is not set, the function runs on the stack of the process to which the signal is delivered.
If the SA_OLDSTYLE bit is set, the signal action is set to SIG_DFL label prior to calling the signal-catching function. This is supported for compatibility with old applications, and is not recommended since the same signal can recur before the signal-catching subroutine is able to reset the signal action and the default action (normally termination) is taken in that case.
If a signal for which a signal-catching function exists is sent to a process while that process is executing certain subroutines, the call can be restarted if the SA_RESTART bit is set for each signal. The only affected subroutines are the following:
Other subroutines do not restart and return EINTR label, independent of the setting of the SA_RESTART bit.
If SA_SIGINFO is cleared and the signal is caught, the signal-catching function will be entered as: void func(int signo);
Where signo is the only argument to the signal catching function. In this case the sa_handler member must be used to describe the signal catching function and the application must not modify the sa_sigaction member. If SA_SIGINFO is set and the signal is caught, the signal-catching function will be entered as: void func(int signo, siginfo_t * info, void * context); where two additional arguments are passed to the signal catching function.
The second argument will point to an object of type siginfo_t explaining the reason why the signal was generated. The third argument can be cast to a pointer to an object of type ucontext_t to refer to the receiving process' context that was interrupted when the signal was delivered. In this case the sa_sigaction member must be used to describe the signal catching function and the application must not modify the sa_handler member.
The si_signo member contains the system-generated signal number. The si_errno member may contain implementation-dependent additional error information. If nonzero, it contains an error number identifying the condition that caused the signal to be generated. The si_code member contains a code identifying the cause of the signal. If the value of si_code is less than or equal to 0, the signal was generated by a process and si_pid and si_uid respectively indicate the process ID and the real user ID of the sender.
The signal.h header description contains information about the signal specific contents of the elements of the siginfo_t type. If SA_NOCLDWAIT is set and sig equals SIGCHLD, child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and wait, wait3, waitid and waitpid will fail and set errno to ECHILD. Otherwise, terminating child processes will be transformed into zombie processes, unless SIGCHLD is set to SIG_IGN. When SIGCHLD is set to SIG_IGN, the signal is ignored and any zombie children of the process will be cleaned up.
If SA_RESETHAND is set, the disposition of the signal will be reset to SIG_DFL and the SA_SIGINFO flag will be cleared on entry to the signal handler.
If SA_NODEFER is set and sig is caught, sig will not be added to the process' signal mask on entry to the signal handler unless it is included in sa_mask. Otherwise, sig will always be added to the process' signal mask on entry to the signal handler. If sig is SIGCHLD, the SA_NOCLDSTOP flag is not set in sa_flags, and the implementation supports the SIGCHLD signal, a SIGCHLD signal will be generated for the calling process whenever any of its child processes stop.
If sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, the implementation will not generate a SIGCHLD signal in this way. When a signal is caught by a signal-catching function installed by sigaction, a new signal mask is calculated and installed for the duration of the signal-catching function (or until a call to either sigprocmask orsigsuspend is made).
This mask is formed by taking the union of the current signal mask and the value of the sa_mask for the signal being delivered unless SA_NODEFER or SA_RESETHAND is set, and including the signal being delivered. If the user's signal handler returns normally, the original signal mask is restored.
Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to sigaction), until the SA_RESETHAND flag causes resetting of the handler, or until one of the exec functions is called.
If the previous action for sig had been established by signal, the values of the fields returned in the structure pointed to by oact are unspecified, and in particular oact->sa_handler is not necessarily the same value passed to signal.
However, if a pointer to the same structure or a copy thereof is passed to a subsequent call to sigaction through the act argument, handling of the signal will be as if the original call to signal were repeated.
If sigaction fails, no new signal handler is installed. It is unspecified whether an attempt to set the action for a signal that cannot be caught or ignored to SIG_DFL is ignored or causes an error to be returned with errno set to EINVAL.
If SA_SIGINFO is not set in sa_flags, then the disposition of subsequent occurrences of sig when it is already pending is implementation-dependent; the signal-catching function will be invoked with a single argument.
The sigvec and signal subroutines are provided for compatibility to older operating systems. Their function is a subset of that available with sigaction.
The sigvec subroutine uses the sigvec structure instead of the sigaction structure. The sigvec structure specifies a mask as an int instead of a sigset_t. The mask for the sigvec subroutine is constructed by setting the i-th bit in the mask if signal i is to be blocked. Therefore, the sigvec subroutine only allows signals between the values of 1 and 31 to be blocked when a signal-handling function is called. The other signals are not blocked by the signal-handler mask.
The sigvec structure has the following members:
int (*sv_handler)();
/* signal handler */
int sv_mask;
/* signal mask */
int sv_flags;
/* flags */The sigvec subroutine in the libbsd.a library interprets the SV_INTERRUPT flag and inverts it to the SA_RESTART flag of the sigaction subroutine. The sigvec subroutine in the libc.a library always sets the SV_INTERRUPT flag regardless of what was passed in the sigvec structure.
The signal subroutine in the libc.a library allows an action to be associated with a signal. The action parameter can have the same values that are described for the sv_handler field in the sigaction structure of thesigaction subroutine. However, no signal handler mask or flags can be specified; the signal subroutine implicitly sets the signal handler mask to additional signals and the flags to be SA_OLDSTYLE.
Upon successful completion of a signal call, the value of the previous signal action is returned. If the call fails, a value of -1 is returned and the errno global variable is set to indicate the error as in the sigaction call.
The signal in libc.a does not set the SA_RESTART flag. It sets the signal mask to the signal whose action is being specified, and sets flags to SA_OLDSTYLE. The Berkeley Software Distribution (BSD) version of signal sets the SA_RESTART flag and preserves the current settings of the signal mask and flags. The BSD version can be used by compiling with the Berkeley Compatibility Library (libbsd.a).
The three types of actions that can be associated with a signal (SIG_DFL, SIG_IGN, or a pointer to a function) are described as follows:
Except for those signal numbers marked with a + (plus sign), @ (at sign), or ! (exclamation point), the default action for a signal ends the receiving process with all of the consequences described in the _exit subroutine. In addition, a memory image file is created in the current directory of the receiving process if an asterisk appears with a signal parameter and the following conditions are met:
For signal numbers marked with a @ (at sign), the default action stops the execution of the receiving process temporarily. When a process stops, a SIGCHLD signal is sent to its parent process, unless the parent process has set the SA_NOCLDSTOP bit. While a process has stopped, any additional signals that are sent are not delivered until the process has started again. An exception to this is the SIGKILL signal, which always terminates the receiving process. Another exception is the SIGCONT signal, which always causes the receiving process to restart or continue running. A process whose parent process has ended is sent a SIGKILL signal if the SIGTSTP, SIGTTIN, or SIGTTOU signals are generated for that process.
For signal numbers marked with a +, the default action ignores the signal. In this case, the delivery of a signal does not affect the receiving process.
If a signal action is set to SIG_DFL while the signal is pending, the signal remains pending.
Delivery of the signal does not affect the receiving process. If a signal action is set to the SIG_IGN action while the signal is pending, the pending signal is discarded.
An exception to this is the SIGCHLD signal whose SIG_DFL action ignores the signal. If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and wait, wait3, waitid and waitpid will fail and set errno to ECHILD.
Upon delivery of the signal, the receiving process runs the signal-catching function specified by the pointer to function. The signal-handler subroutine can be declared as follows:
handler(signal, Code, SCP)
int signal, Code;
struct sigcontext *SCP;A new signal mask is calculated and installed for the duration of the signal-catching function (or until sigprocmask orsigsuspend subroutine is made). This mask is formed by joining the process-signal mask (the mask associated with the action for the signal being delivered) and the mask corresponding to the signal being delivered. The mask associated with the signal-catching function is not allowed to block those signals that cannot be ignored. This is enforced by the kernel without causing an error to be indicated. If and when the signal-catching function returns, the original signal mask is restored (modified by any sigprocmask calls that were made since the signal-catching function was called) and the receiving process resumes execution at the point it was interrupted.
The signal-catching function can cause the process to resume in a different context by calling the longjmp subroutine. When the longjmp subroutine is called, the process leaves the signal stack, if it is currently on the stack, and restores the process signal mask to the state when the corresponding setjmp subroutine was made.
Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to the sigaction subroutine), or until one of the exec subroutines is called. An exception to this is when the SA_OLDSTYLE bit is set. In this case the action of a caught signal gets set to the SIG_DFL action before the signal-catching function for that signal is called.
If a signal action is set to a pointer to a function while the signal is pending, the signal remains pending.
The signal handler should not wait directly or indirectly on the input from a different thread in the form of a variable, pipe or anything similar. This will cause a deadlock in the case of a multithreaded application. As this will be a programmer initiated deadlock, the application will not handle it.
When signal-catching functions are invoked asynchronously with process execution, the behavior of some of the functions defined by this standard is unspecified if they are called from a signal-catching function. The following set of functions are reentrant with respect to signals; that is, applications can invoke them, without restriction, from signal-catching functions:
All other subroutines should not be called from signal-catching functions since their behavior is undefined.
Upon successful completion, the sigaction subroutine returns a value of 0. Otherwise, a value of SIG_ERR is returned and the errno global variable is set to indicate the error.
The sigaction subroutine is unsuccessful and no new signal handler is installed if one of the following occurs:
| Item | Description |
|---|---|
| EFAULT | The action or oaction parameter points to a location outside of the allocated address space of the process. |
| EINVAL | The signal parameter is not a valid signal number. |
| EINVAL | An attempt was made to ignore or supply a handler for theSIGKILL, SIGSTOP, and SIGCONT signals. |