sigaction(S)

sigaction -- detailed signal management

Syntax

cc . . . -lc

#include <signal.h>

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

Description

sigaction allows the calling process to examine and/or specify the action to be taken on delivery of a specific signal. (See signal(M) for an explanation of general signal concepts and a list of supported signals.)

Arguments

sig: specifies the signal and can be assigned any signal listed on the signal(M) page. SIGKILL and SIGSTOP are valid only if the act argument is NULL; in other words, you can query their settings but cannot modify. EINVAL is returned if sig is set to SIGKILL and SIGSTOP and act is not NULL.
act: pointer to a sigaction structure that specifies the new action to be taken when delivering sig. If act is NULL, signal handling is unchanged; this is used to enquire about the current handling of the specified signal.
oact: pointer to a sigaction structure where the action previously associated with sig is to be stored on return from sigaction. If oact is NULL, information is not returned about the old settings.

If both act and oact are NULL, sigaction( ) has no effect except to verify that sig is within the valid range of signal numbers. EINVAL is returned if sig is out of range.

sigaction structure

The sigaction structure includes the following members:

   union {
   	void		(*sa_handler)(int);
   	void		(*sa_sigaction)(int, siginfo_t *, void *);
   }
   sigset_t	sa_mask;
   int		sa_flags;

These members are defined as:

sa_handler

Specifies the action to be associated with the specified signal and may take any of the values specified in signal(M). If sa_handler is set, the sa_sigaction member must not be set.

sa_sigaction

Describes the signal-catching function when the SA_SIGINFO flag is set. If sa_sigaction is set, the sa_handler member must not be set. For details of the sa_sigaction member, see the SA_SIGINFO flag, below.

sa_mask

Specifies a set of signals to be blocked (added to the process signal mask) while the function specified as the signal handler is active. This member is used only when either the sa_handler or sa_sigaction member specifies a signal-catching function. On entry to the signal handler, that set of signals is added to the set of signals already being blocked when the signal is delivered. In addition, the signal that caused the handler to be executed will also be blocked, unless the SA_NODEFER flag has been specified. SIGSTOP and SIGKILL cannot be blocked (the system silently enforces this restriction).

sa_flags

specifies a set of flags used to modify the delivery of the signal. It is formed by a logical OR of any of the following values:

SA_ONSTACK

If set, and the signal is caught and an alternate signal stack has been declared by the receiving process, the signal is delivered on that stack. Otherwise, the signal should be delivered on the current stack of the receiving process.

The SA_ONSTACK flag specifies that whenever the process receives the signal type sig the response is handled on an alternative stack. The location and size of the alternative stack is specified per process.

Alternate signal handling stacks can be defined via the sigaltstack(S) system call.

SA_RESETHAND

If set and the signal is caught, the disposition of the signal is reset to SIG_DFL and the signal will not be blocked on entry to the signal handler (SIGILL, SIGTRAP, and SIGPWR cannot be automatically reset when delivered; the system silently enforces this restriction). Otherwise, the disposition of the signal is not modified on entry to the signal handler.

Additionally, if this flag is set, sigaction behaves as if the SA_NODEFER flag were also set.

SA_NODEFER

If set and the signal is caught, the signal will not be automatically blocked by the kernel while it is being caught, unless it is included in sa_mask.

SA_RESTART

If set and the signal is caught, a system call that is interrupted by the execution of this signal's handler is transparently restarted by the system. Otherwise, that system call returns an EINTR error.

SA_SIGINFO

If cleared and the signal is caught, the signal-catching function is entered as follows:

void func(int signo);

where signo is passed as the only argument to the signal-catching function. In such cases, set sa_handler to describe the signal-catching function and do not set sa_sigaction.

If SA_SIGINFO is set and the signal is caught, two additional arguments are passed to the signal-catching function. If the second argument is not NULL, it points to a siginfo_t structure containing the reason why the signal was generated (see siginfo(FP)); the third argument points to a ucontext_t structure containing the receiving process's context, as interrupted when the signal was delivered (see ucontext(FP)).

In this case, populate the sa_sigaction member to describe the signal-catching function and do not set the sa_handler member. The members of the siginfo(FP) structure are set as follows:

si_signo: contains the system-generated signal number.
si_errno: If si_signo is non-zero, the si_errno member contains an error number identifying the the condition that caused the signal to be generated.
si_code: 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.

SA_NOCLDWAIT

If set and sig equals SIGCHLD, the system will not create zombie processes when children of the calling process exit. If the calling process subsequently issues a wait(S), wait3(S), waitid(S) or waitpid(S), it blocks until all of the calling process's child processes terminate, and then returns a value of -1 with errno set to ECHILD. Otherwise, terminating child processes are transformed into zombies unless SIGCHLD is set to SIG_IGN.

SA_NOCLDSTOP

If set and sig equals SIGCHLD, sig will not be sent to the calling process when its child processes stop or continue.

Usage

If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, then SIGCHLD is generated for the calling process whenever any of its child processes stop. If sig is SIGCHLD and SA_NOCLDSTOP flag is set in sa_flags, SIGCHLD is not generated.

Whenever a signal is caught by a function installed using the sigaction function, a new signal mask is calculated and installed for the duration of the function or until sigprocmask(S) or sigsuspend(S) is called. This mask is calculated from the union of the existing mask and the value of sa_mask specified for the signal being delivered, unless SA_NODEFER or SA_RESETHAND are set, and then including the signal being delivered. If and when the signal-catching routine returns normally, the original signal mask is restored.

Once an action has been associated with a signal, it remains in force until another call to sigaction, until the SA_RESETHAND flag resets the handler, or until one of the exec(S) functions is called.

If the previous action associated with sig had been established using signal(S), the values of the members returned in the structure indicated by oact cannot be predicted, 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 of the structure is passed to a subsequent call of sigaction via the act argument, handling of the signal is carried out as if the original call to signal had been repeated.

If sigaction fails, no new signal handler is installed.

Return values

On success, sigaction returns 0. On failure, sigaction returns -1 and sets errno to identify the error.

Diagnostics

In the following conditions, sigaction fails and sets errno to:

[EINVAL]: The value of the sig argument is not a valid signal number or is equal to SIGKILL or SIGSTOP and the act argument is not NULL.
[EFAULT]: act or oact points outside the process's allocated address space.

Files

/lib/libc.a: linking library

Standards conformance

sigaction is conformant with:

AT&T SVID Issue 3;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2) ;
X/Open Portability Guide, Issue 3, 1989 ;
X/Open Portability Guide Issue 4, Version 2 (Spec-1170)
and NIST FIPS 151-1 .