Specifies the action to take upon delivery of a signal.
sigaction | Standard C Library (libc.a) |
signal, sigvec | Standard C Library (libc.a); |
Berkeley Compatibility Library (libbsd.a)
#include <signal.h>
int sigaction (Signal, Action, OAction) int Signal; struct sigaction *Action, *OAction;
int sigvec (Signal, Invec, Outvec) int Signal; struct sigvec *Invec, *Outvec;
void (*signal (Signal, Action))( ) int Signal; void (*Action) (int);
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 (), 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 thread's process, that is, to any thread within the process.
Note: The sigaction subroutine must not be used concurrently to the sigwait subroutine on the same signal.
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.
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 non-zero, 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, then 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.
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 and the SA_NOCLDSTOP flag is not set in sa_flags , and the implementation supports the SIGCHLD signal, then 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 , then 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 then including the signal being delivered. If and when 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 via 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 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 the sigaction 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 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).
OAction | Points to a sigaction structure in which the signal action data in effect at the time of the sigaction subroutine is returned. |
Invec | Points to a sigvec structure that describes the action to be taken upon receipt of the Signal parameter signal. |
Outvec | Points to a sigvec structure in which the signal action data in effect at the time of the sigvec subroutine is returned. |
Action | Specifies the action associated with a signal. |
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:
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 the SIGKILL, SIGSTOP, and SIGCONT signals. |
These subroutines are part of Base Operating System (BOS) Runtime.
The acct subroutine, _exit, exit, or atexit subroutine, getinterval, incinterval, absinterval, resinc, resabs, alarm, ualarm, getitimer, or setitimer subroutine, getrlimit, setrlimit, or vlimit subroutine, kill subroutine, longjmp or setjmp subroutine, pause subroutine, ptrace subroutine, sigpause or sigsuspend subroutine, sigprocmask, sigsetmask, or sigblock subroutine, sigstack subroutine, sigwait subroutine, umask subroutine, wait, waitpid, or wait3 subroutine.
The kill command.
The core file.
Signal Management in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs provides more information about signal management in multi-threaded processes.