SIGNAL.H(3HEAD) Headers SIGNAL.H(3HEAD)
NAME
signal.h, signal - base signals
SYNOPSIS
#include <signal.h>DESCRIPTION
A signal is an asynchronous notification of an event. A signal is said to
be generated for (or sent to) a process when the event associated with
that signal first occurs. Examples of such events include hardware
faults, timer expiration and terminal activity, as well as the invocation
of the
kill(2) or
sigsend(2) functions. In some circumstances, the same
event generates signals for multiple processes. A process may request a
detailed notification of the source of the signal and the reason why it
was generated. See
siginfo.h(3HEAD).
Signals can be generated synchronously or asynchronously. Events directly
caused by the execution of code by a thread, such as a reference to an
unmapped, protected, or bad memory can generate
SIGSEGV or
SIGBUS; a
floating point exception can generate
SIGFPE; and the execution of an
illegal instruction can generate
SIGILL. Such events are referred to as
traps; signals generated by traps are said to be synchronously generated.
Synchronously generated signals are initiated by a specific thread and
are delivered to and handled by that thread.
Signals may also be generated by calling
kill(),
sigqueue(), or
sigsend(). Events such as keyboard interrupts generate signals, such as
SIGINT, which are sent to the target process. Such events are referred to
as interrupts; signals generated by interrupts are said to be
asynchronously generated. Asynchronously generated signals are not
directed to a particular thread but are handled by an arbitrary thread
that meets either of the following conditions:
o The thread is blocked in a call to
sigwait(2) whose argument
includes the type of signal generated.
o The thread has a signal mask that does not include the type of
signal generated. See
pthread_sigmask(3C). Each process can
specify a system action to be taken in response to each signal
sent to it, called the signal's disposition. All threads in
the process share the disposition. The set of system signal
actions for a process is initialized from that of its parent.
Once an action is installed for a specific signal, it usually
remains installed until another disposition is explicitly
requested by a call to either
sigaction(),
signal() or
sigset(), or until the process
execs(). See
sigaction(2) and
signal(3C). When a process execs, all signals whose
disposition has been set to catch the signal will be set to
SIG_DFL. Alternatively, a process may request that the system
automatically reset the disposition of a signal to
SIG_DFL after it has been caught. See
sigaction(2) and
signal(3C).
SIGNAL DELIVERY
A signal is said to be delivered to a process when a thread within the
process takes the appropriate action for the disposition of the signal.
Delivery of a signal can be blocked. There are two methods for handling
delivery of a signal in a multithreaded application. The first method
specifies a signal handler function to execute when the signal is
received by the process. See
sigaction(2). The second method uses
sigwait(2) to create a thread to handle the receipt of the signal. The
sigaction() function can be used for both synchronously and
asynchronously generated signals. The
sigwait() function will work only
for asynchronously generated signals, as synchronously generated signals
are sent to the thread that caused the event. The
sigwait() function is
the recommended for use with a multithreaded application.
SIGNAL MASK
Each thread has a signal mask that defines the set of signals currently
blocked from delivery to it. The signal mask of the main thread is
inherited from the signal mask of the thread that created it in the
parent process. The selection of the thread within the process that is to
take the appropriate action for the signal is based on the method of
signal generation and the signal masks of the threads in the receiving
process. Signals that are generated by action of a particular thread such
as hardware faults are delivered to the thread that caused the signal.
See
pthread_sigmask(3C) or
sigprocmask(2). See
alarm(2) for current
semantics of delivery of
SIGALRM. Signals that are directed to a
particular thread are delivered to the targeted thread. See
pthread_kill(3C). If the selected thread has blocked the signal, it
remains pending on the thread until it is unblocked. For all other types
of signal generation (for example,
kill(2),
sigsend(2), terminal
activity, and other external events not ascribable to a particular
thread) one of the threads that does not have the signal blocked is
selected to process the signal. If all the threads within the process
block the signal, it remains pending on the process until a thread in the
process unblocks it. If the action associated with a signal is set to
ignore the signal then both currently pending and subsequently generated
signals of this type are discarded immediately for this process.
The determination of which action is taken in response to a signal is
made at the time the signal is delivered to a thread within the process,
allowing for any changes since the time of generation. This
determination is independent of the means by which the signal was
originally generated.
The signals currently defined by <
signal.h> are as follows:
Name Value Default Event
SIGHUP 1 Exit Hangup (see
termio(4I))
SIGINT 2 Exit Interrupt (see
termio(4I))
SIGQUIT 3 Core Quit (see
termio(4I))
SIGILL 4 Core Illegal Instruction
SIGTRAP 5 Core Trace or Breakpoint Trap
SIGABRT 6 Core Abort
SIGEMT 7 Core Emulation Trap
SIGFPE 8 Core Arithmetic Exception
SIGKILL 9 Exit Killed
SIGBUS 10 Core Bus Error
SIGSEGV 11 Core Segmentation Fault
SIGSYS 12 Core Bad System Call
SIGPIPE 13 Exit Broken Pipe
SIGALRM 14 Exit Alarm Clock
SIGTERM 15 Exit Terminated
SIGUSR1 16 Exit User Signal 1
SIGUSR2 17 Exit User Signal 2
SIGCHLD 18 Ignore Child Status Changed
SIGPWR 19 Ignore Power Fail or Restart
SIGWINCH 20 Ignore Window Size Change
SIGURG 21 Ignore Urgent Socket Condition
SIGPOLL 22 Exit Pollable Event (see
streamio(4I))
SIGSTOP 23 Stop Stopped (signal)
SIGTSTP 24 Stop Stopped (user) (see
termio(4I))
SIGCONT 25 Ignore Continued
SIGTTIN 26 Stop Stopped (tty input) (see
termio(4I))
SIGTTOU 27 Stop Stopped (tty output) (see
termio(4I))
SIGVTALRM 28 Exit Virtual Timer Expired
SIGPROF 29 Exit Profiling Timer Expired
SIGXCPU 30 Core CPU time limit exceeded (see
getrlimit(2))
SIGXFSZ 31 Core File size limit exceeded (see
getrlimit(2))
SIGWAITING 32 Ignore Reserved
SIGLWP 33 Ignore Reserved
SIGFREEZE 34 Ignore Check point Freeze
SIGTHAW 35 Ignore Check point Thaw
SIGCANCEL 36 Ignore Reserved for threading support
SIGLOST 37 Exit Resource lost (for example,
record-lock lost)
SIGXRES 38 Ignore Resource control exceeded (see
setrctl(2))
SIGJVM1 39 Ignore Reserved for Java Virtual Machine 1
SIGJVM2 40 Ignore Reserved for Java Virtual Machine 2
SIGINFO 41 Ignore Status request
SIGRTMIN * Exit First real time signal
(
SIGRTMIN+1) * Exit Second real time signal
... (
SIGRTMAX-1) * Exit Second-to-last real time signal
SIGRTMAX * Exit Last real time signal
The symbols
SIGRTMIN through
SIGRTMAX are evaluated dynamically to permit
future configurability.
Applications should not use any of the signals marked "reserved" in the
above table for any purpose, to avoid interfering with their use by the
system.
SIGNAL DISPOSITION
A process using a
signal(3C),
sigset(3C) or
sigaction(2) system call can
specify one of three dispositions for a signal: take the default action
for the signal, ignore the signal, or catch the signal.
Default Action: SIG_DFL A disposition of
SIG_DFL specifies the default action. The default
action for each signal is listed in the table above and is selected from
the following:
Exit When it gets the signal, the receiving process is to be
terminated with all the consequences outlined in
exit(2).
Core When it gets the signal, the receiving process is to be
terminated with all the consequences outlined in
exit(2). In
addition, a ``core image'' of the process is constructed in the
current working directory.
Stop When it gets the signal, the receiving process is to stop. When
a process is stopped, all the threads within the process also
stop executing.
Ignore When it gets the signal, the receiving process is to ignore it.
This is identical to setting the disposition to
SIG_IGN.
Ignore Signal: SIG_IGN A disposition of
SIG_IGN specifies that the signal is to be ignored.
Setting a signal action to
SIG_IGN for a signal that is pending causes
the pending signal to be discarded, whether or not it is blocked. Any
queued values pending are also discarded, and the resources used to queue
them are released and made available to queue other signals.
Catch Signal: function address A disposition that is a function address specifies that, when it gets the
signal, the thread within the process that is selected to process the
signal will execute the signal handler at the specified address.
Normally, the signal handler is passed the signal number as its only
argument. If the disposition was set with the
sigaction(2) function,
however, additional arguments can be requested. When the signal handler
returns, the receiving process resumes execution at the point it was
interrupted, unless the signal handler makes other arrangements. If an
invalid function address is specified, results are undefined.
If the disposition has been set with the
sigset() or
sigaction(), the
signal is automatically blocked in the thread while it is executing the
signal catcher. If a
longjmp() is used to leave the signal catcher, then
the signal must be explicitly unblocked by the user. See
setjmp(3C),
signal(3C) and
sigprocmask(2).
If execution of the signal handler interrupts a blocked function call,
the handler is executed and the interrupted function call returns
-1 to
the calling process with
errno set to
EINTR. If the
SA_RESTART flag is
set, however, certain function calls will be transparently restarted.
Some signal-generating functions, such as high resolution timer
expiration, asynchronous I/O completion, inter-process message arrival,
and the
sigqueue(3C) function, support the specification of an
application defined value, either explicitly as a parameter to the
function, or in a
sigevent structure parameter. The
sigevent structure is
defined by
<signal.h> and contains at least the following members:
Type Name Description
--------------------------------------------------------------------------
int sigev_notify Notification type
int sigev_signo Signal number
--------------------------------------------------------------------------
union sigval sigev_value Signal value
--------------------------------------------------------------------------
void(*)(union sigval) sigev_notify_function Notification function
--------------------------------------------------------------------------
(pthread_attr_t *) sigev_notify_attributes Notification attributes
The
sigval union is defined by
<signal.h>and contains at least the
following members:
Type Name Description
------------------------------------------
int sival_int Integer signal value
void * sival_ptr Pointer signal value
The
sigev_notify member specifies the notification mechanism to use when
an asynchronous event occurs. The
sigev_notify member may be defined with
the following values:
SIGEV_NONE No asynchronous notification is delivered when the event
of interest occurs.
SIGEV_SIGNAL A queued signal, with its value equal to
sigev_signo, is
generated when the event of interest occurs.
SIGEV_THREAD The
sigev_notify_function is called, with
sigev_value as
its argument, to perform notification when the
asynchronous event occurs. The function is executed in an
environment as if it were the start routine for a newly
created thread with thread attributes
sigev_notify_attributes. If
sigev_notify_attributes is
NULL, the thread runs as a detached thread with default
attributes. Otherwise, the thread runs with the specified
attributes, but as a detached thread regardless. The
thread runs with all blockable signals blocked.
SIGEV_PORT An asynchronous notification is delivered to an event
port when the event of interest occurs. The
sigev_value.sival_ptr member points to a
port_notify_t structure defined in <
port.h> (see
port_associate(3C)).
The event port identifier as well as an application-
defined cookie are part of the
port_notify_t structure.
The
sigev_signo member contains the application-defined value to be
passed to the signal-catching function (for notification type
SIGEV_SIGNAL) at the time of the signal delivery as the
si_value member
of the
siginfo_t structure, or as the argument to the notification
function (for notification type
SIGEV_THREAD) that is called when the
asynchronous event occurs. For notification type
SIGEV_PORT,
sigev_value.sival_ptr points to a
port_notify_t structure that specifies
the port and an application-defined cookie.
The
sigev_value member references the application defined value to be
passed to the signal-catching function at the time of the signal delivery
as the
si_value member of the
siginfo_t structure.
The
sival_int member is used when the application defined value is of
type
int, and the
sival_ptr member is used when the application defined
value is a pointer.
When a signal is generated by
sigqueue(3C) or any signal-generating
function which supports the specification of an application defined
value, the signal is marked pending and, if the
SA_SIGINFO flag is set
for that signal, the signal is queued to the process along with the
application specified signal value. Multiple occurrences of signals so
generated are queued in FIFO order. If the
SA_SIGINFO flag is not set
for that signal, later occurrences of that signal's generation, when a
signal is already queued, are silently discarded.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-------------------+
|Interface Stability | Committed |
+--------------------+-------------------+
|Standard | See
standards(7). |
+--------------------+-------------------+
SEE ALSO
Intro(2),
alarm(2),
exit(2),
fcntl(2),
getrlimit(2),
ioctl(2),
kill(2),
pause(2),
setrctl(2),
sigaction(2),
sigaltstack(2),
sigprocmask(2),
sigsend(2),
sigsuspend(2),
sigwait(2),
port_associate(3C),
pthread_create(3C),
pthread_kill(3C),
pthread_sigmask(3C),
setjmp(3C),
signal(3C),
sigqueue(3C),
sigsetops(3C),
wait(3C),
siginfo.h(3HEAD),
ucontext.h(3HEAD),
attributes(7),
standards(7),
lockd(8)NOTES
The dispositions of the
SIGKILL and
SIGSTOP signals cannot be altered
from their default values. The system generates an error if this is
attempted.
The
SIGKILL,
SIGSTOP, and
SIGCANCEL signals cannot be blocked. The system
silently enforces this restriction.
The
SIGCANCEL signal cannot be directed to an individual thread using
pthread_kill(3C), but it can be sent to a process using
kill(2),
sigsend(2), or
sigqueue(3C).
Whenever a process receives a
SIGSTOP,
SIGTSTP,
SIGTTIN, or
SIGTTOU signal, regardless of its disposition, any pending
SIGCONT signal are
discarded.
Whenever a process receives a
SIGCONT signal, regardless of its
disposition, any pending
SIGSTOP,
SIGTSTP,
SIGTTIN, and
SIGTTOU signals
is discarded. In addition, if the process was stopped, it is continued.
SIGPOLL is issued when a file descriptor corresponding to a STREAMS file
has a "selectable" event pending. See
Intro(2). A process must
specifically request that this signal be sent using the
I_SETSIG ioctl call. Otherwise, the process will never receive
SIGPOLL.
If the disposition of the
SIGCHLD signal has been set with
signal() or
sigset(), or with
sigaction() and the
SA_NOCLDSTOP flag has been
specified, it will only be sent to the calling process when its children
exit; otherwise, it will also be sent when the calling process's children
are stopped or continued due to job control.
The name
SIGCLD is also defined in this header and identifies the same
signal as
SIGCHLD.
SIGCLD is provided for backward compatibility, new
applications should use
SIGCHLD.
The disposition of signals that are inherited as
SIG_IGN should not be
changed.
Signals which are generated synchronously should not be masked. If such a
signal is blocked and delivered, the receiving process is killed.
January 4, 2014
SIGNAL.H(3HEAD)