NAME

signal.h − signals

SYNOPSIS

#include <signal.h>

DESCRIPTION

The <signal.h> header defines the following symbolic constants, each of which expands to a distinct constant expression of the type:

void (*)(int)

whose value matches no declarable function. 

SIG_DFL Request for default signal handling. 

SIG_ERR Return value from signal() in case of error. 

SIG_HOLD Request that signal be held. 

SIG_IGN Request that signal be ignored. 

The following data types are defined through typedef:

sig_atomic_t Integral type of an object that can be accessed as an atomic entity, even in the presence of asynchronous interrupts

sigset_t Integral or structure type of an object used to represent sets of signals. 

pid_t As described in <sys/types.h>. 

This header also declares the constants that are used to refer to the signals that occur in the system. Signals defined here begin with the letters SIG.  Each of the signals have distinct positive integral values. The value 0 is reserved for use as the null signal (see kill()). Additional implementation−dependent signals may occurin the system.

The following signals are supported on all implementations (default actions are explained below the table):

The default actions are as follows:

i Abnormal termination of the process. The process is terminated with all the consequences of _exit() except that the status is made available to wait() and waitpid() indicates abnormal termination by the specified signal. 

ii Abnormal termination of the process. Additionally, implementation−dependent abnormal termination actions, such as creation of a core file, may occur. 

iii Ignore the signal. 

iv Stop the process. 

v Continue the process, if it is stopped; otherwise ignore the signal. 

The header provides a declaration of struct sigaction, including at least the following members:

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

The following are declared as constants:

SA_NOCLDSTOP Do not generate SIGCHLD when children stop. 

SIG_BLOCK The resulting set is the union of the current set and the signal set pointed to by the argument set.

SIG_UNBLOCK The resulting set is the intersection of the current set and the complement of the signal set pointed to by the argument set.

SIG_SETMASK The resulting set is the signal set pointed to by the argument set. SA_ONSTACK Causes signal delivery to occur on an alternate stack. 

SA_RESETHAND Causes signal dispositions to be set to SIG_DFL on entry to signal handlers. 

SA_RESTART Causes certain functions to become restartable. 

SA_SIGINFO Causes extra information to be passed to signal handlers at the time of receipt of a signal. 

SA_NOCLDWAIT Causes implementations not to create zombie processes on child death. 

SA_NODEFER Causes signal not to be automatically blocked on entry to signal handler. 

SS_ONSTACK Process is executing on an alternate signal stack. 

SS_DISABLE Alternate signal stack is disabled. 

MINSIGSTKSZ Minimum stack size for a signal handler. 

SIGSTKSZ Default size in bytes for the alternate signal stack. 

The ucontext_t structure is defined through typedef as described in <ucontext.h>. 

The <signal.h> header defines the stack_t type as a structure that includes at least the following members:

The <signal.h> header defines the sigstack structure that includes at least the following members:

The <signal.h> header defines the siginfo_t type as a structure that includes at least the following members:

The macros specified in the Code column of the following table are defined for use as values of si_code that are signal−specific reasons why the signal was generated. 

Implementations may support additional si_code values not included in this list, may generate values included in this list under circumstances other than those described in this list, and may contain extensions or limitations that prevent some values from being generated. Implementations will not generate a different value from the ones described in this list for circumstances described in this list. 

In addition, the following signal−specific information will be available:

For some implementations, the value of si_addr may be inaccurate. 

The following are declared as functions and may also be defined as macros:

void  (*bsd_signal(int sig, void (*func)(int)))(int);
int   kill(pid_t pid, int sig);

int   killpg(pid_t pgrp, int sig);
int   raise(int sig);
int   sigaction(int sig, const struct sigaction
              *act, struct sigaction *oact);
int   sigaddset(sigset_t *set, int signo);

int   sigaltstack(const stack_t *ss, stack_t *oss);
int   sigdelset(sigset_t *set, int signo);
int   sigemptyset(sigset_t *set);
int   sigfillset(sigset_t *set);

int   sighold(int sig);
int   sigignore(int sig);
int   siginterrupt(int sig, int flag);
int   sigismember(const sigset_t *set, int signo);

int   sigmask(int signum);
void  (*signal(int sig, void (*func)(int)))(int);

int   sigpause(int sig);
int   sigpending(sigset_t *set);
int   sigprocmask(int how, const sigset_t *set, sigset_t *oset);
int   sigrelse(int sig);
void  *sigset(int sig, void (*disp)(int)))(int);
int   sigstack(struct sigstack *ss,
            struct sigstack *oss);
int   sigsuspend(const sigset_t *sigmask);

SEE ALSO

alarm(), bsd_signal(), ioctl(), kill(), killpg(), raise(), sigaction(), sigaddset(), sigaltstack(), sigdelset(), sigemptyset(), sigfillset(), siginterrupt(), sigismember(), signal(), sigpending(), sigprocmask(), sigstack(), sigsuspend(), wait(), waitid(), <errno.h>, <streams.h>, <sys/types.h>, <ucontext.h>. 

CHANGE HISTORY

First released in Issue 1. 

Issue 4

The following changes are incorporated for alignment with the ISO POSIX−1 standard:

• The function declarations in this header are expanded to full ISO C prototypes. 

• The DESCRIPTION section is changed:

− to define the type sig_atomic_t

− to define the syntax of signal names and functions

− to combine the two tables of constants

− SIGFPE is no longer limited to floating−point exceptions, but covers all erroneous arithmetic operations. 

The following change is incorporated for alignment with the ISO C standard:

• The raise() function is added to the list offunctions declared in this header. 

Other changes are incorporated as follows:

• A reference to <sys/types.h> is added for the definition of pid_t. This is marked as an extension.

• In the list of signals starting with SIGCHLD, the statement "but a system not supporting the job control option is not obliged to support the functionality of these signals" is removed. This is because job control is defined as mandatory on Issue 4 conforming implementations. 

• Reference to implementation−dependent abnormal termination routines, such as creation of a core file, in item ii in the defaults action list is marked as an extension. 

Issue 4, Version 2

The following changes are incorporated for X/OPEN UNIX conformance:

• The SIGTRAP, SIGBUS, SIGSYS, SIGPOLL, SIGPROF, SIGXCPU, SIGXFSZ, SIGURG, and SIGVTALRM signals are added to the list of signals that will be supported on all conforming implementations. 

• The sa_sigaction member is added to the sigaction structure, and a note is added that the storage used by sa_handler and sa_sigaction may overlap. 

• The SA_ONSTACK, SA_RESETHAND, SA_RESTART, SA_SIGINFO, SA_NOCLDWAIT, SS_ONSTACK, SS_DISABLE, MINSIGSTKSZ, and SIGSTKSZ constants are defined. The stack_t, sigstack, and siginfo structures are defined. 

• Definitions are given for the ucontext_t, stack_t, sigstack, and siginfo_t types. 

• A table is provided listing macros that are defined as signal−specific reasons why a signal was generated. Signal−specific additional information is specified. 

• The bsd_signal(), killpg(), _longjmp(), _setjmp(), sigaltstack(), sighold(), sigrelse(), sigset(), and sigstack() functions are added to the list of functions declared in this header. 

HP−UX EXTENSIONS

DESCRIPTION

HP-UX supports multiple signal interfaces (see sigaction(2), signal(2), sigvector(2), bsdproc(2), and sigset(2V)) that allow a process to specify the action taken upon receipt of a signal. All supported signal interfaces require specification of a signal, as designated by the Name and Number shown below.  Signal specification can be any of the following except SIGKILL or SIGSTOP, which cannot be caught or ignored:

The letters in the Notes column in the table above indicate the action taken when the signal is received, and any special conditions on its use:

A The default action is to terminate the process. 

B The default action of terminating the process also generates a core image file if possible. 

C The action is not reset to SIG_DFL before calling the signal-catching function. 

D The signal cannot be ignored. 

E The signal cannot be caught. 

F The signal will not be held off from a stopped process. 

G The default action is to ignore the signal. 

H The default action is to stop the process. 

All signal interfaces allow specification of an action that determines what to do upon the receipt of a signal, and should be one of the following:

SIG_DFL Execute the default action, which varies depending on the signal as described above:

A Terminate the receiving process with all of the consequences outlined in exit(2).

B If following conditions are met, generate a core image file (see core(4)) in the current working directory of the receiving process:

• The effective user ID and the real user ID of the receiving process are equal. 

• The effective group ID and the real group ID of the receiving process are equal. 

• A regular file named core does not exist and can be created, or exists and is writable. 

If the file is created, it has the following properties:

• The file mode is 0666, modified by the file creation mode mask (see umask(2)).

• The file user ID is equal to the effective user ID of the receiving process. 

• The file group ID is equal to the effective group ID of the receiving process. 

G Ignore the signal.  Do not terminate or stop the receiving process. 

H Stop the receiving process.  While a process is stopped, any additional signals sent to the process are suspended until the process is restarted (except those marked with Note F above, which are processed immediately).  However, when the process is restarted, pending signals are processed.  When a process that is in an orphaned process group (see glossary(9)) receives a SIGTSTP, SIGTTIN, or SIGTTOU signal, the process is not stopped because a process in an orphaned process group is not allowed to stop.  Instead, a SIGHUP signal is sent to the process, and the SIGTSTP, SIGTTIN, or SIGTTOU is discarded. 

SIG_IGN Ignore the signal. 
When one of the supported signal interface routines is used to set the action of a signal to SIG_IGN and an instance of the signal is pending, the pending signal is cleared. 

D Signals marked with Note D above cannot be ignored. 

address Catch the signal. 
Upon receipt of the signal, if signal() is used to set the action, reset the action for the signal caught to SIG_DFL (except signals marked with Note C). Then, call the signal-catching function to which address points, and resume executing the receiving process at the point where it was interrupted.  Signal interface routines other than signal() normally do not reset the action for the signal caught.  However, sigaction() and sigvector() provide a way of specifying this behavior (see sigaction(2) or sigvector(2)).

The signal-catching function is called with the following three parameters:

sig The signal number. 

code A word of information usually provided by the hardware. 

scp A pointer to the machine-dependent structure sigcontext defined in <signal.h>. 

Depending on the value of sig, code can be zero and/or scp can be NULL.  The meanings of code and scp and the conditions determining when they are other than zero or NULL are implementation-dependent (see DEPENDENCIES below).  It is possible for code to always be zero, and scp to always be NULL. 

The pointer scp is valid only during the context of the signal-catching function. 

Optional parameters can be omitted from the signal-catching function parameter list, in which case the signal-catching function is exactly compatible with UNIX System V.  Truly portable software should not use the optional parameters in signal-catching routines. 

Upon return from the signal-catching function, the receiving process resumes execution at the point where it was interrupted. 

When a signal is caught during the execution of system calls such as read(), write(), open(), or ioctl() on a slow device (such as a terminal, but not a file), during a pause() system call or a wait() system call that does not return immediately because a previously stopped or zombie process already exists, the signal-catching function is executed and the interrupted system call returns a −1 to the calling process with errno set to EINTR. 

C If the signal is marked with Note C above, the action is not reset to SIG_DFL before calling the signal-catching function.  Furthermore, the action is not reset if any signal interface routine other than signal() was used to set the action.  See the description of signal catching above. 

E If the signal is marked with Note E above, the signal cannot be caught. 

When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is generated for a process, pending SIGCONT signals for that process are discarded.  Conversely, when SIGCONT is generated for a process, all pending stop signals for that process are discarded.  When SIGCONT is generated for a stopped process, the process is continued, even if the SIGCONT signal is blocked or ignored.  If SIGCONT is blocked and not ignored, the process remains pending until it is either unblocked or a stop signal is generated. 

SIGKILL is sent by the system if an exec() system call is unsuccessful and the original program has already been deleted. 

WARNINGS

The signals SIGCLD and SIGPWR behave differently than those described above. 

The actions for these signals is modified as follows:

SIGCLD Setting the action for SIGCLD to SIG_IGN in a parent process prevents exiting children of the calling process from creating a zombie process.  If the parent process executes the wait() function, the calling process blocks until all of the child processes of the calling processes terminate.  The wait() function then returns a value of −1 with errno set to ECHILD (see wait(2)).

If one of the signal interface routines is used to set the action for SIGCLD to be caught (that is, a function address is supplied) in a process that currently has terminated (zombie) children, a SIGCLD signal is delivered to the parent process immediately.  Thus, if the signal-catching function reinstalls itself, the apparent effect is that any SIGCLD signals received due to the death of children while the function is executing are queued and the signal-catching function is continually reentered until the queue is empty.  Note that the function must reinstall itself after it calls wait(), wait3(), or waitpid().  Otherwise the presence of the child that caused the original signal causes another signal immediately, resulting in infinite recursion. 

When processing a pipeline, the Bourne shell (see sh-bourne(1)) makes the last process in the pipeline the parent of the preceding processes. Job control shells including C shell, Korn shell and the POSIX shell (see csh(1), ksh(1), and sh-posix(1)) make the shell itself the parent of all processes in the pipeline. Therefore, a process that can receive data from a pipe should not attempt to catch SIGCLD. 

SIGPWR The SIGPWR signal is sent to all processes after a power interruption when power is restored and the system has done all necessary reinitialization.  Processes restart by catching (or ignoring) SIGPWR. 

Applications that wish to recover from power failures should catch SIGPWR and take whatever necessary steps to reinitialize itself. 

Some implementations do not generate SIGPWR.  Only systems with nonvolatile memory can recover from power failures. 

DEPENDENCIES

Series 700

The signal SIGPWR is not currently generated. 

Series 700/800

The structure pointer scp is always defined. 

The code word is always zero for all signals except SIGILL and SIGFPE.  For SIGILL, code has the following values:

 8 Illegal instruction trap;

 9 Break instruction trap;

10 Privileged operation trap;

11 Privileged register trap. 

For SIGFPE, code has the following values:

12 Overflow trap;

13 Conditional trap;

14 Assist exception trap;

22 Assist emulation trap. 

Refer to the Series 800 processor documentation provided with your system for more detailed information about the meaning of these errors. 

The Instruction Address Offset Queue (program counter) is not advanced when a trap occurs on Series 800 systems.  If a signal generated by a hardware trap is masked or has its signal action set to SIG_IGN, the program loops infinitely since the instruction causing the trap is re-executed, causing the trap again.  If the signal is received by a signal-catching function in the user program, the instruction that caused the trap is re-executed upon return from the signal-catching function unless program flow is altered by the signal-catching function.  For example, the longjmp() routine (see setjmp(3C)) can be called. Using longjmp() ensures software portability across different hardware architectures. 

AUTHOR

signal was developed by HP, AT&T, and the University of California, Berkeley. 

SEE ALSO

kill(1), init(1M), bsdproc(2), exit(2), kill(2), lseek(2), pause(2), sigaction(2), signal(2), sigvector(2), wait(2), sigset(2V), abort(3C), setjmp(3C). 

STANDARDS CONFORMANCE

<signal.h>: AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996