[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 2

sigaction, sigvec, or signal Subroutine

Purpose

Specifies the action to take upon delivery of a signal.

Libraries

sigaction Standard C Library (libc.a)
signal, sigvec Standard C Library (libc.a);

Berkeley Compatibility Library (libbsd.a)

Syntax


#include <signal.h>

int sigaction ( Signal, Action, OAction)
int Signal;
struct sigaction *Action, *OAction;

int sigvec (Signal, Invec, Outvec)
int Signal;
struct sigvec *Invec, *Outvec;

void (*signal (Signal, Action)) ()
int Signal;
void (*Action) (int);

Description

The sigaction subroutine allows a calling process to examine and change the action to be taken when a specific signal is delivered to the process issuing this subroutine.

In multi-threaded applications using the threads library (libpthreads.a), signal actions are common to all threads within the process. Any thread calling the sigaction subroutine changes the action to be taken when a specific signal is delivered to the threads process, that is, to any thread within the process.

Note
The sigaction subroutine must not be used concurrently to the sigwait subroutine on the same signal.

The Signal parameter specifies the signal. If the Action parameter is not null, it points to a sigaction structure that describes the action to be taken on receipt of the Signal parameter signal. If the OAction parameter is not null, it points to asigaction structure in which the signal action data in effect at the time of the sigaction subroutine call is returned. If the Action parameter is null, signal handling is unchanged; thus, the call can be used to inquire about the current handling of a given signal.

The sigaction structure has the following fields:

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

The sa_handler field can have a SIG_DFL or SIG_IGN value, or it can be a pointer to a function. A SIG_DFL value requests default action to be taken when a signal is delivered. A value of SIG_IGN requests that the signal have no effect on the receiving process. A pointer to a function requests that the signal be caught; that is, the signal should cause the function to be called. These actions are more fully described in "Parameters".

When a signal is delivered to a thread, if the action of that signal specifies termination, stop, or continue, the entire process is terminated, stopped, or continued, respectively.

If the SA_SIGINFO flag (see below) is cleared in the sa_flags field of the sigaction structure, the sa_handler field identifies the action to be associated with the specified signal. If the SA_SIGINFO flag is set in the sa_flags field, the sa_sigaction field specifies a signal-catching function. If the SA_SIGINFO bit is cleared and the sa_handler field specifies a signal-catching function, or if the SA_SIGINFO bit is set, the sa_mask field identifies a set of signals that will be added to the signal mask of the thread before the signal-catching function is invoked.

The sa_mask field can be used to specify that individual signals, in addition to those in the process signal mask, be blocked from being delivered while the signal handler function specified in the sa_handler field is operating. The sa_flags field can have the SA_ONSTACK, SA_OLDSTYLE, or SA_NOCLDSTOP bits set to specify further control over the actions taken on delivery of a signal.

If the SA_ONSTACK bit is set, the system runs the signal-catching function on the signal stack specified by the sigstack subroutine. If this bit is not set, the function runs on the stack of the process to which the signal is delivered.

If the SA_OLDSTYLE bit is set, the signal action is set to SIG_DFL label prior to calling the signal-catching function. This is supported for compatibility with old applications, and is not recommended since the same signal can recur before the signal-catching subroutine is able to reset the signal action and the default action (normally termination) is taken in that case.

If a signal for which a signal-catching function exists is sent to a process while that process is executing certain subroutines, the call can be restarted if the SA_RESTART bit is set for each signal. The only affected subroutines are the following:

Other subroutines do not restart and return EINTR label, independent of the setting of the SA_RESTART bit.

If SA_SIGINFO is 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. The second argument 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 receiving process' context 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 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 signal.h header description contains information about the signal specific contents of the elements of the siginfo_t type. If SA_NOCLDWAIT is set, and sig equals SIGCHLD, 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. Otherwise, terminating child processes will be transformed into zombie processes, unless SIGCHLD is set to SIG_IGN. If SA_RESETHAND is 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. If SA_NODEFER is 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 orsigsuspend 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.

If SA_SIGINFO is not set in sa_flags, then the disposition of subsequent occurrences of sig when it is already pending is implementation-dependent; the signal-catching function will be invoked with a single argument.

The sigvec and signal subroutines are provided for compatibility to older operating systems. Their function is a subset of that available with sigaction.

The sigvec subroutine uses the sigvec structure instead of the sigaction structure. The sigvec structure specifies a mask as an int instead of a sigset_t. The mask for the sigvec subroutine is constructed by setting the i-th bit in the mask if signal i is to be blocked. Therefore, the sigvec subroutine only allows signals between the values of 1 and 31 to be blocked when a signal-handling function is called. The other signals are not blocked by the signal-handler mask.

The sigvec structure has the following members:

int  (*sv_handler)();
/* signal handler */
int  sv_mask;
/* signal mask    */
int  sv_flags;
/* flags          */

The sigvec subroutine in the libbsd.a library interprets the SV_INTERRUPT flag and inverts it to the SA_RESTART flag of thesigaction subroutine. The sigvec subroutine in the libc.a library always sets the SV_INTERRUPT flag regardless of what was passed in the sigvec structure.

The sigvec subroutine in the libbsd.a library interprets the SV_INTERRUPT flag and inverts it to the SA_RESTART flag of the sigaction subroutine. The sigvec subroutine in the libc.a library always sets the SV_INTERRUPT flag regardless of what was passed in the sigvec structure.

The signal subroutine in the libc.a library allows an action to be associated with a signal. The Action parameter can have the same values that are described for the sv_handler field in the sigaction structure of thesigaction subroutine. However, no signal handler mask or flags can be specified; the signal subroutine implicitly sets the signal handler mask to additional signals and the flags to be SA_OLDSTYLE.

Upon successful completion of a signal call, the value of the previous signal action is returned. If the call fails, a value of -1 is returned and the errno global variable is set to indicate the error as in the sigaction call.

The signal in libc.a does not set the SA_RESTART flag. It sets the signal mask to the signal whose action is being specified, and sets flags to SA_OLDSTYLE. The Berkeley Software Distribution (BSD) version of signal sets the SA_RESTART flag and preserves the current settings of the signal mask and flags. The BSD version can be used by compiling with the Berkeley Compatibility Library (libbsd.a).

The signal in libc.a does not set the SA_RESTART flag. It sets the signal mask to the signal whose action is being specified, and sets flags to SA_OLDSTYLE. The Berkeley Software Distribution (BSD) version of signal sets the SA_RESTART flag and preserves the current settings of the signal mask and flags. The BSD version can be used by compiling with the Berkeley Compatibility Library (libbsd.a).

Parameters

Signal
Defines the signal. The following list describes signal names and the specification for each. The value of the Signal parameter can be any signal name from this list or its corresponding number except the SIGKILL name. If you use the signal name, you must include the signal.h file, because the name is correlated in the file with its corresponding number.
Note
The symbols in the following list of signals represent these actions:
*
Specifies the default action that includes creating a core dump file.
@
Specifies the default action that stops the process receiving these signals.
!
Specifies the default action that restarts or continues the process receiving these signals.
+
Specifies the default action that ignores these signals.
%
Indicates a likely shortage of paging space.
#
See Terminal Programming for more information on the use of these signals.
SIGHUP
Hang-up. (1)
SIGINT
Interrupt. (2)
SIGQUIT
Quit. (3*)
SIGILL
Invalid instruction (not reset when caught). (4*)
SIGTRAP
Trace trap (not reset when caught). (5*)
SIGIOT
End process (see the abort subroutine). (6*)
SIGEMT
EMT instruction. (7*)
SIGFPE
Arithmetic exception, integer divide by 0, or floating-point exception.(8*)
SIGKILL
Kill (cannot be caught or ignored). (9)
SIGBUS
Specification exception. (10*)
SIGSEGV
Segmentation violation. (11*)
SIGSYS
Parameter not valid to subroutine. (12*)
SIGPIPE
Write on a pipe when there is no process to read it. (13)
SIGALRM
Alarm clock. (14)
SIGTERM
Software termination signal. (15)
SIGURG
Urgent condition on I/O channel. (16+)
SIGSTOP
Stop (cannot be caught or ignored). (17@)
SIGTSTP
Interactive stop. (18@)
SIGCONT
Continue if stopped. (19!)
SIGCHLD
To parent on child stop or exit. (20+)
SIGTTIN
Background read attempted from control terminal. (21@)
SIGTTOU
Background write attempted from control terminal. (22@)
SIGIO
Input/output possible or completed. (23+)
SIGXCPU
CPU time limit exceeded (see the setrlimit subroutine). (24)
SIGXFSZ
File size limit exceeded (see the setrlimit subroutine).(25)
reserved
(26)
SIGMSG
Input data has been stored into the input ring buffer. (27#)
SIGWINCH
Window size change. (28+)
SIGPWR
Power-fail restart. (29+)
SIGUSR1
User-defined signal 1. (30)
SIGUSR2
User-defined signal 2. (31)
SIGPROF
Profiling timer expired. (see the setitimer subroutine).(32)
SIGDANGER
Paging space low. (33+%)
SIGVTALRM
Virtual time alarm (see the setitimer subroutine). (34)
SIGMIGRATE
Migrate process. (35)
SIGPRE
Programming exception (user defined). (36)
reserved
(37-58)
SIGGRANT
Monitor access wanted. (60#)
SIGRETRACT
Monitor access should be relinquished. (61#)
SIGSOUND
A sound control has completed execution. (62#)
SIGSAK
Secure attention key. (63)
 
 
Action
Points to a sigaction structure that describes the action to be taken upon receipt of the Signal parameter signal.

The three types of actions that can be associated with a signal (SIG_DFL, SIG_IGN, or a pointer to a function) are described as follows:

 
OAction
Points to a sigaction structure in which the signal action data in effect at the time of the sigaction subroutine is returned.
Invec
Points to a sigvec structure that describes the action to be taken upon receipt of the Signal parameter signal.
Outvec
Points to a sigvec structure in which the signal action data in effect at the time of the sigvec subroutine is returned.
Action
Specifies the action associated with a signal.

Return Values

Upon successful completion, the sigaction subroutine returns a value of 0. Otherwise, a value of SIG_ERR is returned and the errno global variable is set to indicate the error.

Error Codes

The sigaction subroutine is unsuccessful and no new signal handler is installed if one of the following occurs:

EFAULT The Action or OAction parameter points to a location outside of the allocated address space of the process.
EINVAL The Signal parameter is not a valid signal number.
EINVAL An attempt was made to ignore or supply a handler for theSIGKILL, SIGSTOP, and SIGCONT signals.

Related Information

The acct subroutine, _exit, exit, or atexit subroutine, getinterval,incinterval, absinterval, resinc, resabs, alarm,ualarm, getitimer, or setitimer subroutine, getrlimit, setrlimit, or vlimit subroutine, kill subroutine, longjmp or setjmp (setjmp or longjmp Subroutine) subroutine, pause subroutine, ptrace subroutine, sigpause or sigsuspend (sigsuspend or sigpause Subroutine) subroutine, sigprocmask,sigsetmask, or sigblock (sigprocmask, sigsetmask, or sigblock Subroutine) subroutine, sigstack (sigstack Subroutine) subroutine, sigwait (sigwait Subroutine) subroutine, umask (umask Subroutine) subroutine, wait, waitpid, or wait3 (wait, waitpid, wait3, or wait364 Subroutine) subroutine.

The kill command.

The core file.

Signal Management in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs provides more information about signal management in multi-threaded processes.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]