sigaction(2)

sigaction -- detailed signal management

Synopsis

   #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(5) for an explanation of general signal concepts.]

sig specifies the signal and can be assigned any of the signals specified in signal(5), except SIGKILL and SIGSTOP.

If the argument act is not NULL, it points to a structure specifying the new action to be taken when delivering sig. If the argument oact is not NULL, it points to a structure where the action previously associated with sig is to be stored on return from sigaction.

The sigaction structure is defined in sys/signal.h:

   struct sigaction {
           int             sa_flags;
           union {
                   void    (*sa__handler)(int);
                   void    (*sa__sigaction)(int, siginfo_t *, void *);
           } sa_u;
           sigset_t        sa_mask;
           int             sa_resv[2];
   };
   
   #define sa_handler      sa_u.sa__handler
   #define sa_sigaction    sa_u.sa__sigaction

sa_handler specifies the disposition of the signal and may be SIG_DFL, SIG_IGN (see signal(2)), or a pointer to a signal catching (handling) function.

sa_mask specifies a set of signals to be blocked while the signal handler is active. 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_sigaction points to a signal catching function (see the description of SA_SIGINFO, below).

SA_ONSTACK

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

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 LWP.

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

SA_RESETHAND

If set and the signal is caught, the disposition of the signal is reset to SIG_DFL (SIGILL, SIGTRAP, and SIGPWR cannot be automatically reset when delivered; the system silently enforces this restriction).

SA_NODEFER

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

SA_RESTART

If set and the signal is caught, a call that is interrupted by the execution of this signal's handler is transparently restarted by the system. Otherwise, that call returns an EINTR error. Some system calls cannot be restarted when they are interrupted, even when SA_RESTART is set. For example, sleep(3C), pause(2), sigpause(3bsd), sigsuspend(2) cannot be restarted.

SA_SIGINFO

If this flag is not set 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 [see siginfo(5)]. The third argument can be cast to a pointer to an object of type ucontext_t to refer to the context of receiving process that was interrupted when the signal was delivered [see ucontext(5)].

In this latter 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, if non-zero, 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.

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(2), it blocks until all of the calling process's child processes terminate, and then returns a value of -1 with errno set to ECHILD.

SA_NOCLDSTOP

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

SA_WAITSIG

When sig is SIGWAITING [see signal(5)] this flag requests the generation of the SIGWAITING signal type when all LWPs of the process are blocked at an interruptible priority.

The SA_WAITSIG signal type might be used by user level threads libraries trigger the creation of additional LWPs for the process.

Return values

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

Errors

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

EINVAL: The value of the sig argument is an invalid or unsupported signal number; or, an attempt was made to catch a signal that cannot be caught or to ignore a signal that cannot be ignored.
EFAULT: act or oact points outside the process's allocated address space.

References

exit(2), intro(2), kill(1), kill(2), pause(2), sigaltstack(2), siginfo(5), signal(2), signal(5), sigprocmask(2), sigsend(2), sigsetops(3C), sigsuspend(2), ucontext(5), wait(2)

Notices

If the system call is reading from or writing to a terminal and the terminal's NOFLSH bit is cleared, data may be flushed [see termio(7)].

The storage occupied by sa_handler and sa_sigaction may overlap, and a portable program must not use both simultaneously.

Considerations for threads programming

The handler defined by act is common to all threads in a process.

The Threads Library does not support alternate signal handling stacks for threads.

The SA_WAITSIG flag (see description above) can be used in support of threads libraries.

Further details can be found in signal(5).