sigaction(2)

NAME

sigaction — examine and change signal action

SYNOPSIS

#include <signal.h>

int sigaction (
     int sig,
     const struct sigaction *act,
     struct sigaction *oact
);

DESCRIPTION

The sigaction() function allows the calling process to examine and/or specify the action to be associated with a specific signal. The argument sig specifies the signal; acceptable values are defined in <signal.h>.

The structure sigaction, used to describe an action to be taken, is defined in the header <signal.h> to include at least the following members:

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 behavior of signal.
`void()(int, siginfo_t,void *)`	`sa_sigaction`	signal-catching function.

If the argument act is not a null pointer, it points to a structure specifying the action to be associated with the specified signal. If the argument oact is not a null pointer, the action previously associated with the signal is stored in the location pointed to by the argument oact.

If the argument act is a null pointer, signal handling is unchanged; thus, the call can be used to enquire about the current handling of a given signal. The sa_handler field of the sigaction structure identifies the action to be associated with the specified signal. If the sa_handler field specifies a signal-catching function, the sa_mask field identifies a set of signals that will be added to the thread's signal mask before the signal-catching function is invoked. The SIGKILL and SIGSTOP signals will not be added to the signal mask using this mechanism; this restriction will be enforced by the system without causing an error to be indicated.

The sa_flags field can be used to modify the behavior of the specified signal. The following flags, defined in the header <signal.h>, can be set in sa_flags:

SA_NOCLDSTOP

Do not generate SIGCHLD when children stop.

SA_ONSTACK

If set and an alternate signal stack has been declared with sigaltstack() or sigstack(), the signal will be delivered to the calling process on that stack. Otherwise, the signal will be delivered on the current stack.

SA_RESETHAND

If 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 (Note: SIGILL, SIGTRAP, and SIGPWR cannot be automatically reset when delivered; the system silently enforces this restriction). Otherwise, the disposition of the signal will not be modified on entry to the signal handler. In addition, if this flag is set, sigaction() behaves as if the SA_NODEFER flag were also set.

SA_RESTART

This flag affects the behavior of interruptible functions; that is, those specified to fail with errno set to EINTR. If set, and a function specified as interruptible is interrupted by this signal, the function will restart and will not fail with EINTR unless otherwise specified. If the flag is not set, interruptible functions interrupted by this signal will fail with errno set to EINTR.

SA_SIGINFO

If 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. If the second argument is not a null pointer, it 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 context of the receiving process or thread 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 of info 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 values of si_pid and si_uid are otherwise meaningless.

If SA_SIGINFO is set in sa_flags, subsequent occurrences of sig generated by sigqueue() or as a result of any signal-generating function that supports the specification of an application-defined value - when sig is already pending - will be queued in FIFO order until delivered, and the application specified value will be passed to the signal-catching function as the si_value member of info (See Realtime Signals Extension). If SA_SIGINFO is not set in sa_flags, then the disposition of subsequent occurrences of sig when it is already pending is implementation-defined.

SA_NOCLDWAIT

If set, and sig equals SIGCHLD, child processes of the calling process 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.

SA_NODEFER

If 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() or sigsuspend() 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.

A signal is said to be generated for (or sent to) a process when the event that causes the signal first occurs. Examples of such events include detection of hardware faults, timer expiration and terminal activity, as well as the invocation of kill() and sigqueue(). In some circumstances, the same event generates signals for multiple processes.

Each process has an action to be taken in response to each signal defined by the system (see Signal Actions). A signal is said to be delivered to a process when the appropriate action for the process and signal is taken.

During the time between the generation of a signal and its delivery, the signal is said to be pending. Ordinarily, this interval cannot be detected by an application.

However, a signal can be blocked from delivery to a thread. If the action associated with a blocked signal is anything other than to ignore the signal, and if that signal is generated for the thread, the signal will remain pending until either it is unblocked or the action associated with it is set to ignore the signal.

If the action associated with a blocked signal is to ignore the signal and if that signal is generated for the process, it is unspecified whether the signal is discarded immediately upon generation or remains pending.

Each thread has a signal mask that defines the set of signals currently blocked from delivery to it. The signal mask for a thread is initialized from that of its parent. The sigaction(), sigprocmask(), and sigsuspend() functions control the manipulation of the signal mask.

The determination of which action is taken in response to a signal is made at the time the signal is delivered, allowing for any changes since the time of generation. This determination is independent of the means by which the signal was originally generated. If a subsequent occurrence of a pending signal is generated, it is implementation-dependent as to whether the signal is delivered more than once. The order in which multiple, simultaneously pending signals are delivered to a process is unspecified.

When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is generated for a process, any pending SIGCONT signals for that process will be discarded. Conversely, when SIGCONT is generated for a process, all pending stop signals for that process will be discarded. When SIGCONT is generated for a process that is stopped, the process will be continued, even if the SIGCONT signal is blocked or ignored. If SIGCONT is blocked and not ignored, it will remain pending until it is either unblocked or a stop signal is generated for the process.

Some signal-generating functions, such as high-resolution timer expiration, asynchronous I/O completion, interprocess message arrival, and the sigqueue() function, support the specification of an application-defined value, either explicitly as a parameter to the function or in a sigevent structure parameter (see signal(5)).

Realtime Signals Extension

When a signal is generated by sigqueue() or any signal-generating function that supports the specification of an application-defined value, and if the SA_SIGINFO flag is set for that signal, the signal will be queued to the process along with the application-specified signal value.

Multiple occurrences of signals so generated are queued in FIFO order. When multiple unblocked signals, all in the range SIGRTMIN to SIGRTMAX, are pending, the implementation delivers the pending unblocked signal with the lowest signal number within that range.

The selection order between realtime and nonrealtime signals, or between multiple pending nonrealtime signals, is unspecified.

Signals generated by kill() or other events that cause signals to occur, such as detection of hardware faults, alarm() timer expiration, or terminal activity, and for which the implementation does not support queueing, will have no effect on signals already queued for the same signal number.

If, when a pending signal is delivered, there are additional signals to be queued to that signal number, the signal will remain pending. Otherwise, the pending indication will be reset.

An implementation will document any condition not specified by this document under which the implementation generates signals.

Signal Actions

There are three types of action that can be associated with a signal: SIG_DFL, SIG_IGN or a pointer to a function. Initially, all signals will be set to SIG_DFL or SIG_IGN prior to entry of the main() routine (see the exec functions). The actions prescribed by these values are as follows:

SIG_DFL - signal-specific default action

The default actions for the signals defined in this document are specified under signal(5).
If the default action is to stop the process, the execution of that process is temporarily suspended. When a process stops, a SIGCHLD signal will be generated for its parent process, unless the parent process has set the SA_NOCLDSTOP flag. While a process is stopped, any additional signals that are sent to the process will not be delivered until the process is continued, except SIGKILL which always terminates the receiving process. A process that is a member of an orphaned process group will not be allowed to stop in response to the SIGTSTP, SIGTTIN, or SIGTTOU signals. In cases where delivery of one of these signals would stop such a process, the signal will be discarded.
Setting a signal action to SIG_DFL for a signal that is pending, and whose default action is to ignore the signal (for example, SIGCHLD), will cause the pending signal to be discarded, whether or not it is blocked. Any queued values pending will be discarded, and the system resources used to queue them will be released and made available to queue other signals.

SIG_IGN - ignore signal

Delivery of the signal will have no effect on the process. The behavior of a process is undefined after it ignores a SIGFPE, SIGILL, or SIGSEGV signal that was not generated by kill(), sigqueue()or raise().
The system will not allow the action for the signals SIGKILL or SIGSTOP to be set to SIG_IGN.
Setting a signal action to SIG_IGN for a signal that is pending will cause the pending signal to be discarded, whether or not it is blocked. Any queued values pending will be discarded, and the system resources used to queue them will be released and made available to queue other signals.
If a process sets the action for the SIGCHLD signal to SIG_IGN, the behavior is unspecified, except as specified below.
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.

Pointer to a function - catch signal

On delivery of the signal, the receiving process is to execute the signal-catching function at the specified address. After returning from the signal-catching function, the receiving process will resume execution at the point at which it was interrupted.
If SA_SIGINFO is cleared, the signal-catching function will be entered as:
void func(int signo);
where func is the specified signal-catching function and signo is the signal number of the signal being delivered.
If SA_SIGINFO is set, the signal-catching function will be entered as:
void func(int signo, siginfo_t *siginfo, void *ucontextptr);
where func is the specified signal-catching function, signo is the signal number of the signal being delivered, siginfo points to an object of type siginfo_t associated with the signal being delivered, and ucontextptr points to a ucontext_t.
The behavior of a process is undefined after it returns normally from a signal- catching function for a SIGBUS, SIGFPE, SIGILL, or SIGSEGV signal that was not generated by kill() or raise().
The system will not allow a process to catch the signals SIGKILL and SIGSTOP.
If a process establishes a signal-catching function for the SIGCHLD signal while it has a terminated child process for which it has not waited, a SIGCHLD signal is delivered to the parent process immediately.
When signal-catching functions are invoked asynchronously with process execution, the behavior of some of the functions defined by this document is unspecified if they are called from a signal-catching function.
Refer to the "Async Signal Safe" section of thread_safety(5) which defines a set of functions that are either reentrant or not interruptible by signals. Therefore applications may invoke them, without restriction, from signal-catching functions.
All functions not mentioned under the "Async Signal Safe" section of thread_safety(5) are considered to be unsafe with respect to signals. In the presence of signals, all functions defined by this document will behave as defined when called from or interrupted by a signal-catching function, with a single exception: when a signal interrupts an unsafe function and the signal-catching function calls an unsafe function, the behavior is undefined.

Signal Effects on Other Functions

Signals affect the behavior of certain functions (defined under the Async Signal Safe section of thread_safety(5)) if delivered to a process while it is executing such a function. If the action of the signal is to terminate the process, the process will be terminated and the function will not return.

If the action of the signal is to stop the process, the process will stop until continued or terminated. Generation of a SIGCONT signal for the process causes the process to be continued, and the original function will continue at the point the process was stopped.

If the action of the signal is to invoke a signal-catching function, the signal-catching function will be invoked; in this case the original function is said to be interrupted by the signal. If the signal-catching function executes a return statement, the behavior of the interrupted function will be as described individually for that function. Signals that are ignored will not affect the behavior of any function; signals that are blocked will not affect the behavior of any function until they are unblocked and then delivered.

APPLICATION USAGE

The sigaction() function supersedes the signal() interface, and should be used in preference. In particular, sigaction() and signal() should not be used in the same process to control the same signal.

The behavior of reentrant functions, as defined in the description, is as specified by this document, regardless of invocation from a signal-catching function. This is the only intended meaning of the statement that reentrant functions may be used in signal-catching functions without restrictions. Applications must still consider all effects of such functions on such things as data structures, files and process state. In particular, application writers need to consider the restrictions on interactions when interrupting sleep() and interactions among multiple handles for a file descriptor.

The fact that any specific function is listed as reentrant does not necessarily mean that invocation of that function from a signal-catching function is recommended.

In order to prevent errors arising from interrupting non-reentrant function calls, applications should protect calls to these functions either by blocking the appropriate signals or through the use of some programmatic semaphore.

This document does not address the more general problem of synchronizing access to shared data structures. Note in particular that even the "safe" functions may modify the global variable errno; the signal-catching function may want to save and restore its value. Naturally, the same principles apply to the reentrancy of application routines and asynchronous data access.

Note that longjmp() and siglongjmp() are not in the list of reentrant functions. This is because the code executing after longjmp() and siglongjmp() can call any unsafe functions with the same danger as calling those unsafe functions directly from the signal handler. Applications that use longjmp() and siglongjmp() from within signal handlers require rigorous protection in order to be portable.

Many of the other functions that are excluded from the list are traditionally implemented using either malloc() or free() functions or the standard I/O library, both of which traditionally use data structures in a non-reentrant manner.

Because any combination of different functions using a common data structure can cause reentrancy problems, this document does not define the behavior when any unsafe function is called in a signal handler that interrupts an unsafe function.

If the signal occurs other than as the result of calling abort(), kill(), sigqueue(), or raise(), the behavior is undefined if the signal handler calls any function in the standard library other than one of the functions listed in the table above or refers to any object with static storage duration other than by assigning a value to a static storage duration variable of type volatile sig_atomic_t. Furthermore, if such a call fails, the value of errno is indeterminate.

Usually, the signal is executed on the stack that was in effect before the signal was delivered. An alternate stack may be specified to receive a subset of the signals being caught.

When the signal handler returns, the receiving process will resume execution at the point it was interrupted unless the signal handler makes other arrangements. If longjmp() or _longjmp() is used to leave the signal handler, then the signal mask must be explicitly restored by the process.

POSIX.4-1993 defines the third argument of a signal handling function when SA_SIGINFO is set as a void * instead of a ucontext_t *, but without requiring type checking. New applications should explicitly cast the third argument of the signal handling function to uncontext_t *.

The BSD optional four argument signal handling function is not supported by this specification. The BSD declaration would be

void handler(int sig, int code, struct sigcontext *scp, char *addr); 

where sig is the signal number, code is additional information on certain signals, scp is a pointer to the sigcontext structure, and addr is additional address information. Much the same information is available in the objects pointed to by the second argument of the signal handler specified when SA_SIGINFO is set.

Threads Considerations

The signal disposition, catch/ignore/default, established by sigaction() is shared by all threads in the process.

If the signal disposition for sig is set to SIG_IGN or is set to SIG_DFL and the default action for sig is to ignore the signal, any instances of sig pending on the process or any of the threads will be discarded. The signals are discarded regardless of whether the signal is blocked by any of the threads.

For more information regarding signals and threads, see signal(5).

RETURN VALUE

Upon successful completion, sigaction() returns 0. Otherwise -1 is returned, errno is set to indicate the error and no new signal-catching function will be installed.

ERRORS

The sigaction() function will fail if:

EINVAL: The sig argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a signal that cannot be ignored.
EFAULT: act or oact points to an invalid address. The reliable detection of this error is implementation dependent.

The sigaction() function may fail if:

EINVAL: An attempt was made to set the action to SIG_DFL for a signal that cannot be caught or ignored (or both).

WARNINGS

The fpathconf() function is marked as an extension in the list of safe functions because it is not included in the corresponding list in the ISO POSIX-1 standard, but it is expected to be added in a future revision of that standard.

AUTHOR

sigaction() was derived from the IEEE POSIX 1003.1-1988 Standard.

STANDARDS CONFORMANCE

sigaction(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1