sigaction

Synopsis

Description

The sigaction() function allows the calling process to examine or specify the
action to be taken on delivery of a specific signal. See signal.h(3HEAD)
for an explanation of general signal concepts.

The sig argument specifies the signal and can be assigned any of
the signals specified in signal.h(3HEAD) 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 storage occupied by sa_handler and sa_sigaction may overlap, and a standard-conforming
application (see standards(5)) must not use both simultaneously.

The sa_handler member identifies the action to be associated with the specified
signal, if the SA_SIGINFO flag (see below) is cleared in the
sa_flags field of the sigaction structure. It may take any of the
values specified in signal.h(3HEAD) or that of a user specified signal handler.
If the SA_SIGINFO flag is set in the sa_flags field, the
sa_sigaction field specifies a signal-catching function.

The sa_mask member 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).

The sa_flags member 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 if the thread that is chosen to processes a delivered signal has an alternate signal stack declared with sigaltstack(2), then it will process the signal on that stack. Otherwise, the signal is delivered on the thread's normal stack.

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

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, functions that are interrupted by the execution of this signal's handler are transparently restarted by the system, namely fcntl(2), ioctl(2), wait(3C), waitid(2), and the following functions on slow devices like terminals: getmsg() and getpmsg() (see getmsg(2)); putmsg() and putpmsg() (see putmsg(2)); pread(), read(), and readv() (see read(2)); pwrite(), write(), and writev() (see write(2)); recv(), recvfrom(), and recvmsg() (see recv(3SOCKET)); and send(), sendto(), and sendmsg() (see send(3SOCKET)). Otherwise, the function returns an EINTR error.

SA_SIGINFO

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

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

SA_NOCLDSTOP

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

Return Values

Upon successful completion, 0 is returned. Otherwise, -1 is returned, errno is
set to indicate the error, and no new signal handler is installed.

Errors

The sigaction() function will fail if:

EINVAL

The value of the sig argument is not a valid signal number or is equal to SIGKILL or SIGSTOP. In addition, if in a multithreaded process, it is equal to SIGWAITING, SIGCANCEL, or SIGLWP.

Notes

The handler routine can be declared:

void handler (int sig, siginfo_t *sip, ucontext_t *ucp);

The sig argument is the signal number. The sip argument is a
pointer (to space on the stack) to a siginfo_t structure, which provides
additional detail about the delivery of the signal. The ucp argument is a
pointer (again to space on the stack) to a ucontext_t structure (defined
in <sys/ucontext.h>) which contains the context from before the signal. It
is not recommended that ucp be used by the handler to restore
the context from before the signal delivery.