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 examines and changes the signal action. Specifically, it allows the calling process to examine and/or specify the action that is taken when a specific signal is delivered.

sig specifies the signal and can be assigned any signal except SIGKILL or SIGSTOP.

If act is not NULL, it points to a structure that specifies the new action associated with the specified signal. If act is NULL, the sigaction() call does not change the signal handling and the call can be used to inquire about the current handling of a given signal. If oact is not NULL, the action previously associated with the signal is stored in the location that oact points to.

If sigaction() fails, no new signal handler is installed.

The sigaction structure contains the following members:

union {
	void (*sa_handler)(int sig);
	void (*sa_sigaction)(int sig, siginfo_t *info, void *context);
};

sigset_t
sa_mask;

int sa_flags;

sa_handler and sa_sigaction specify the disposition of the signal, and may take either a pointer to a signal handler function, or may take the value SIG_DFL or SIG_IGN. sa_sigaction should be set only if SA_SIGINFO is specified in sa_flags; otherwise, sa_handler should be set.

sa_mask specifies the 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 already been specified. SIGSTOP and SIGKILL cannot be blocked (the system silently enforces this restriction).

The following bits may be set in sa_flags:

SA_ONSTACK

Signal is to be delivered using signal stack.

SA_RESETHAND

If set and the signal is caught, the disposition of the signal is reset to SIG_DFL and the signal is not blocked on entry to the signal handler.

SA_NODEFER

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

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, 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. The second argument points to a siginfo_t structure containing the reason why the signal was generated. If the third argument is not NULL, it points to a ucontext_t structure containing the receiving process's context when the signal was delivered.

When SA_SIGINFO is set, 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) are queued in FIFO order until delivered or accepted. The application specified value is passed to the signal catching function as the si_value member of the siginfo_t structure.

SA_NOCLDWAIT

If set and sig equals SIGCHLD, the system does not create zombie processes when children of the calling process exit. If the calling process subsequently issues a wait(), 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 are not sent to the calling process when its child processes stop or continue.

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 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 sa_mask for the signal being delivered (unless SA_NODEFER or SA_RESETHAND is set for that signal), and then including the signal being delivered. If and when the user's signal handler returns normally, the original signal mask is restored.

After a fork(), or vfork() the child inherits all signals, the signal mask, and the restart/interrupt and reset-signal-handler flags.

The exec() family of functions resets all caught signals to SIG_DFL. Ignored signals remain ignored; the signal mask remains the same; signals that interrupt system calls continue to do so.

Refer to api_intro for a discussion of the signals that the NuTCRACKER Platform supports and their default actions.

PARAMETERS

sig: Specifies the signal number to examine or modify.
act: Points to a structure that specifies a new signal action.
oact: Is a return pointer to a structure for holding the old signal action.

RETURN VALUES

If successful, sigaction() returns zero. On failure, it returns -1 and sets errno to one of the following values:

EFAULT: act or oact is an invalid pointer.
EINVAL: The value of sig is an invalid or unsupported signal number, or sigaction() attempted to catch a signal that cannot be caught, or the function tried to ignore a signal that cannot be ignored.

CONFORMANCE

UNIX 98, with exceptions.

MULTITHREAD SAFETY LEVEL

Async-signal-safe.

PORTING ISSUES

The SA_ONSTACK, SA_NOCLDWAIT, and SA_NOCLDSTOP flags are currently silently ignored by the NuTCRACKER Platform. Most system calls do not yet support automatic restart when the SA_RESTART flag is set. Refer to the siginfo_t page for details on the information that the NuTCRACKER Platform provides when SA_SIGINFO is specified.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

sigaction()
examine and change signal action

Function