[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 Base Operating System and Extensions Technical Reference, 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 (), 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 thread's 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 a sigaction 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 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 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 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 the sigaction 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:

  • SIG_DFL Default action: signal-specific default action.

    Except for those signal numbers marked with a + (plus sign), @ (at sign), or ! (exclamation point), the default action for a signal ends the receiving process with all of the consequences described in the _exit subroutine. In addition, a memory image file is created in the current directory of the receiving process if an asterisk appears with a Signal parameter and the following conditions are met:

    • The saved user ID and the real user ID of the receiving process are equal.
    • An ordinary file named core exists in the current directory and is writable, or it can be created. If the file is created, it must have the following properties:

      The access permission code 0666 (0x1B6), modified by the file-creation mask (see the umask subroutine)

      A file owner ID that is the same as the effective user ID of the receiving process

      A file group ID that is the same as the effective group ID of the receiving process.

    For signal numbers marked with a ! (exclamation point), the default action restarts the receiving process if it has stopped, or continues to run the receiving process.

    For signal numbers marked with a @ (at sign), the default action stops the execution of the receiving process temporarily. When a process stops, a SIGCHLD signal is sent to its parent process, unless the parent process has set the SA_NOCLDSTOP bit. While a process has stopped, any additional signals that are sent are not delivered until the process has started again. An exception to this is the SIGKILL signal, which always terminates the receiving process. Another exception is the SIGCONT signal, which always causes the receiving process to restart or continue running. A process whose parent process has ended is sent a SIGKILL signal if the SIGTSTP, SIGTTIN, or SIGTTOU signals are generated for that process.

    For signal numbers marked with a +, the default action ignores the signal. In this case, the delivery of a signal does not affect the receiving process.

    If a signal action is set to SIG_DFL while the signal is pending, the signal remains pending.

  • SIG_IGN Ignore signal.

    Delivery of the signal does not affect the receiving process. If a signal action is set to the SIG_IGN action while the signal is pending, the pending signal is discarded.

    An exception to this is the SIGCHLD signal whose SIG_DFL action ignores the signal. If the action for the SIGCHLD signal is set to SIG_IGN, 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.

Note: The SIGKILL and SIGSTOP signals cannot be ignored.
  • Pointer to a function, catch signal.

    Upon delivery of the signal, the receiving process runs the signal-catching function specified by the pointer to function. The signal-handler subroutine can be declared as follows:

    handler(Signal, Code, SCP)
int Signal, Code;
struct sigcontext *SCP;
    The Signal parameter is the signal number. The Code parameter is provided only for compatibility with other UNIX-compatible systems. The Code parameter value is always 0. The SCP parameter points to the sigcontext structure that is later used to restore the previous execution context of the process. The sigcontext structure is defined in the signal.h file.

    A new signal mask is calculated and installed for the duration of the signal-catching function (or until sigprocmask or sigsuspend subroutine is made). This mask is formed by joining the process-signal mask (the mask associated with the action for the signal being delivered) and the mask corresponding to the signal being delivered. The mask associated with the signal-catching function is not allowed to block those signals that cannot be ignored. This is enforced by the kernel without causing an error to be indicated. If and when the signal-catching function returns, the original signal mask is restored (modified by any sigprocmask calls that were made since the signal-catching function was called) and the receiving process resumes execution at the point it was interrupted.

    The signal-catching function can cause the process to resume in a different context by calling the longjmp subroutine. When the longjmp subroutine is called, the process leaves the signal stack, if it is currently on the stack, and restores the process signal mask to the state when the corresponding setjmp subroutine was made.

    Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to the sigaction subroutine), or until one of the exec subroutines is called. An exception to this is when the SA_OLDSTYLE bit is set. In this case the action of a caught signal gets set to the SIG_DFL action before the signal-catching function for that signal is called.

    If a signal action is set to a pointer to a function while the signal is pending, the signal remains pending.

    When signal-catching functions are invoked asynchronously with process execution, the behavior of some of the functions defined by this standard is unspecified if they are called from a signal-catching function. The following set of functions are reentrant with respect to signals; that is, applications can invoke them, without restriction, from signal-catching functions:

    _exit
    access
    alarm
    cfgetispeed
    cfgetospeed
    cfsetispeed
    cfsetospeed
    chdir
    chmod
    chown
    close
    creat
    dup
    dup2
    exec
    execle
    execve
    fcntl
    fork
    fpathconf
    fstat
    getegid
    geteuid
    getgid
    getgroups
    getpgrp
    getpid
    getppid
    getuid
    kill
    link
    lseek
    mkdir
    mkfifo
    open
    pathconf
    pause
    pipe
    raise
    read
    readx
    rename
    rmdir
    setgid
    setpgid
    setpgrp
    setsid
    setuid
    sigaction
    sigaddset
    sigdelset
    sigemptyset
    sigismember
    signal
    sigpending
    sigprocmask
    sigsuspend
    sleep
    stat
    statx
    sysconf
    tcdrain
    tcflow
    tcflush
    tcgetattr
    tcgetpgrp
    tcsendbreak
    tcsetattr
    tcsetpgrp
    time
    times
    umask
    uname
    unlink
    ustat
    utime
    wait
    waitpid
    write

    All other subroutines should not be called from signal-catching functions since their behavior is undefined.

    • 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 the SIGKILL, SIGSTOP, and SIGCONT signals.

    Implementation Specifics

    These subroutines are part of Base Operating System (BOS) Runtime.

    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 subroutine, pause subroutine, ptrace subroutine, sigpause or sigsuspend subroutine, sigprocmask, sigsetmask, or sigblock subroutine, sigstack subroutine, sigwait subroutine, umask subroutine, wait, waitpid, or wait3 subroutine.

    The kill command.

    The core file.

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

    [ Previous | Next | Contents | Glossary | Home | Search ]