Tribblix: manual page: signal.h.3head

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

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)