8322 nl: misleading-indentation

[unleashed/tickless.git] / usr / src / man / man3head / signal.h.3head

'\" te
.\" Copyright (c) 1995 IEEE.  All Rights Reserved.
.\" Portions Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
.\"  This notice shall appear on any product containing this material.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SIGNAL.H 3HEAD "Jan 4, 2014"
.SH NAME
signal.h, signal \- base signals
.SH SYNOPSIS
.LP
.nf
\fB#include <signal.h>\fR
.fi

.SH DESCRIPTION
.sp
.LP
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 \fBkill\fR(2) or
\fBsigsend\fR(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
\fBsiginfo.h\fR(3HEAD).
.sp
.LP
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 \fBSIGSEGV\fR or \fBSIGBUS\fR;
a floating point exception can generate \fBSIGFPE\fR; and the execution of an
illegal instruction can generate \fBSIGILL\fR. 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.
.sp
.LP
Signals may also be generated by calling \fBkill()\fR, \fBsigqueue()\fR, or
\fBsigsend()\fR. Events such as keyboard interrupts generate signals, such as
\fBSIGINT\fR, 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:
.RS +4
.TP
.ie t \(bu
.el o
The thread is blocked in a call to \fBsigwait\fR(2) whose argument includes the
type of signal generated.
.RE
.RS +4
.TP
.ie t \(bu
.el o
The thread has a signal mask that does not include the type of signal
generated. See \fBpthread_sigmask\fR(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
\fBsigaction()\fR, \fBsignal()\fR or  \fBsigset()\fR, or until the process
\fBexecs()\fR. See \fBsigaction\fR(2) and  \fBsignal\fR(3C). When a process
execs, all signals whose disposition has been set to catch the signal will be
set to \fBSIG_DFL.\fR Alternatively, a process may request that the system
automatically reset the disposition of a signal to  \fBSIG_DFL\fR after it has
been caught. See \fBsigaction\fR(2) and \fBsignal\fR(3C).
.RE
.SS "SIGNAL DELIVERY"
.sp
.LP
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
\fBsigaction\fR(2). The second method uses \fBsigwait\fR(2) to create a thread
to handle the receipt of the signal. The \fBsigaction()\fR function can be used
for both synchronously and asynchronously generated signals. The
\fBsigwait()\fR function will work only for asynchronously generated signals,
as synchronously generated signals are sent to the thread that caused the
event. The \fBsigwait()\fR function is the recommended for use with a
multithreaded application.
.SS "SIGNAL MASK"
.sp
.LP
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 \fBpthread_sigmask\fR(3C)
or \fBsigprocmask\fR(2). See \fBalarm\fR(2) for current semantics of delivery
of \fBSIGALRM\fR. Signals that are directed to a particular thread  are
delivered to the targeted thread. See \fBpthread_kill\fR(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,
\fBkill\fR(2), \fBsigsend\fR(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.
.sp
.LP
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.
.sp
.LP
The signals currently defined by <\fBsignal.h\fR> are as follows:
.sp

.sp
.TS
c c c c
l l l l .
Name    Value   Default Event
\fBSIGHUP\fR    1       Exit    Hangup (see \fBtermio\fR(7I))
\fBSIGINT\fR    2       Exit    Interrupt (see \fBtermio\fR(7I))
\fBSIGQUIT\fR   3       Core    Quit (see \fBtermio\fR(7I))
\fBSIGILL\fR    4       Core    Illegal Instruction
\fBSIGTRAP\fR   5       Core    Trace or Breakpoint Trap
\fBSIGABRT\fR   6       Core    Abort
\fBSIGEMT\fR    7       Core    Emulation Trap
\fBSIGFPE\fR    8       Core    Arithmetic Exception
\fBSIGKILL\fR   9       Exit    Killed
\fBSIGBUS\fR    10      Core    Bus Error
\fBSIGSEGV\fR   11      Core    Segmentation Fault
\fBSIGSYS\fR    12      Core    Bad System Call
\fBSIGPIPE\fR   13      Exit    Broken Pipe
\fBSIGALRM\fR   14      Exit    Alarm Clock
\fBSIGTERM\fR   15      Exit    Terminated
\fBSIGUSR1\fR   16      Exit    User Signal 1
\fBSIGUSR2\fR   17      Exit    User Signal 2
\fBSIGCHLD\fR   18      Ignore  Child Status Changed
\fBSIGPWR\fR    19      Ignore  Power Fail or Restart
\fBSIGWINCH\fR  20      Ignore  Window Size Change
\fBSIGURG\fR    21      Ignore  Urgent Socket Condition
\fBSIGPOLL\fR   22      Exit    Pollable Event (see \fBstreamio\fR(7I))
\fBSIGSTOP\fR   23      Stop    Stopped (signal)
\fBSIGTSTP\fR   24      Stop    Stopped (user) (see \fBtermio\fR(7I))
\fBSIGCONT\fR   25      Ignore  Continued
\fBSIGTTIN\fR   26      Stop    Stopped (tty input) (see \fBtermio\fR(7I))
\fBSIGTTOU\fR   27      Stop    Stopped (tty output) (see \fBtermio\fR(7I))
\fBSIGVTALRM\fR 28      Exit    Virtual Timer Expired
\fBSIGPROF\fR   29      Exit    Profiling Timer Expired
\fBSIGXCPU\fR   30      Core    T{
CPU time limit exceeded (see \fBgetrlimit\fR(2))
T}
\fBSIGXFSZ\fR   31      Core    T{
File size limit exceeded (see \fBgetrlimit\fR(2))
T}
\fBSIGWAITING\fR        32      Ignore  Reserved
\fBSIGLWP\fR    33      Ignore  Reserved
\fBSIGFREEZE\fR 34      Ignore  Check point Freeze
\fBSIGTHAW\fR   35      Ignore  Check point Thaw
\fBSIGCANCEL\fR 36      Ignore  Reserved for threading support
\fBSIGLOST\fR   37      Exit    T{
Resource lost (for example, record-lock lost)
T}
\fBSIGXRES\fR   38      Ignore  T{
Resource control exceeded (see \fBsetrctl\fR(2))
T}
\fBSIGJVM1\fR   39      Ignore  Reserved for Java Virtual Machine 1
\fBSIGJVM2\fR   40      Ignore  Reserved for Java Virtual Machine 2
\fBSIGINFO\fR   41      Ignore  Status request
\fBSIGRTMIN\fR  \fB*\fR Exit    First real time signal
(\fBSIGRTMIN\fR+1)      *       Exit    Second real time signal
\fB\|.\|.\|.\fR                 
(\fBSIGRTMAX\fR-1)      *       Exit    Second-to-last real time signal
\fBSIGRTMAX\fR  \fB*\fR Exit    Last real time signal
.TE

.sp
.LP
The symbols \fBSIGRTMIN\fR through \fBSIGRTMAX\fR are evaluated dynamically to
permit future configurability.
.sp
.LP
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.
.SS "SIGNAL DISPOSITION"
.sp
.LP
A process using a \fBsignal\fR(3C), \fBsigset\fR(3C) or \fBsigaction\fR(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.
.SS "Default Action: SIG_DFL"
.sp
.LP
A disposition of  \fBSIG_DFL\fR specifies the default action. The default
action for each signal is listed in the table above and is selected from the
following:
.sp
.ne 2
.na
\fBExit\fR
.ad
.RS 10n
When it gets the signal, the receiving process is to be terminated with all the
consequences outlined in \fBexit\fR(2).
.RE

.sp
.ne 2
.na
\fBCore\fR
.ad
.RS 10n
When it gets the signal, the receiving process is to be terminated with all the
consequences outlined in \fBexit\fR(2). In addition, a ``core image'' of the
process is constructed in the  current working directory.
.RE

.sp
.ne 2
.na
\fBStop\fR
.ad
.RS 10n
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.
.RE

.sp
.ne 2
.na
\fBIgnore\fR
.ad
.RS 10n
When it gets the signal, the receiving process is to ignore it. This is
identical to setting the disposition to \fBSIG_IGN\fR.
.RE

.SS "Ignore Signal: SIG_IGN"
.sp
.LP
A disposition of \fBSIG_IGN\fR specifies that the signal is to be ignored.
Setting a signal action to \fBSIG_IGN\fR 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.
.SS "Catch Signal: function address"
.sp
.LP
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 \fBsigaction\fR(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.
.sp
.LP
If the disposition has been set with the \fBsigset()\fR or \fBsigaction()\fR,
the signal is automatically blocked in the thread while it is executing the
signal catcher. If a \fBlongjmp()\fR is used to leave the signal catcher, then
the signal must be explicitly unblocked by the user. See \fBsetjmp\fR(3C),
\fBsignal\fR(3C) and \fBsigprocmask\fR(2).
.sp
.LP
If execution of the signal handler interrupts a blocked function call, the
handler is executed and the interrupted function call returns  \fB\(mi1\fR to
the calling process with \fBerrno\fR set to \fBEINTR\fR. If the
\fBSA_RESTART\fR flag is set, however, certain function calls will be
transparently restarted.
.sp
.LP
Some signal-generating functions, such as high resolution timer expiration,
asynchronous I/O completion, inter-process message arrival, and the
\fBsigqueue\fR(3C) function, support the specification of an application
defined value, either explicitly as a parameter to the function, or in a
\fBsigevent\fR structure parameter. The \fBsigevent\fR structure is defined by
\fB<signal.h>\fR and contains at least the following members:
.sp

.sp
.TS
c c c
l l l .
Type    Name    Description
_
\fBint\fR       \fBsigev_notify\fR      Notification type
\fBint\fR       \fBsigev_signo\fR       Signal number
_
\fBunion sigval\fR      \fBsigev_value\fR       Signal value
_
\fBvoid(*)(union sigval)\fR     \fBsigev_notify_function\fR     Notification function
_
\fB(pthread_attr_t *)\fR        \fBsigev_notify_attributes\fR   Notification attributes
.TE

.sp
.LP
The \fBsigval\fR union is defined by \fB<signal.h>\fRand contains at least the
following members:
.sp

.sp
.TS
c c c
l l l .
Type    Name    Description
_
\fBint\fR       \fBsival_int\fR Integer signal value
\fBvoid *\fR    \fBsival_ptr\fR Pointer signal value
.TE

.sp
.LP
The  \fBsigev_notify\fR member specifies the notification mechanism to use when
an asynchronous event occurs. The \fBsigev_notify\fR member may be defined with
the following values:
.sp
.ne 2
.na
\fB\fBSIGEV_NONE\fR\fR
.ad
.RS 16n
No asynchronous notification is delivered when the event of interest occurs.
.RE

.sp
.ne 2
.na
\fB\fBSIGEV_SIGNAL\fR\fR
.ad
.RS 16n
A queued signal, with its value equal to \fBsigev_signo\fR, is generated when
the event of interest occurs.
.RE

.sp
.ne 2
.na
\fB\fBSIGEV_THREAD\fR\fR
.ad
.RS 16n
The \fBsigev_notify_function\fR is called, with \fBsigev_value\fR 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 \fBsigev_notify_attributes\fR. If
\fBsigev_notify_attributes\fR is \fINULL\fR, 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.
.RE

.sp
.ne 2
.na
\fB\fBSIGEV_PORT\fR\fR
.ad
.RS 16n
An asynchronous notification is delivered to an event port when the event of
interest occurs. The \fBsigev_value.sival_ptr\fR member points to a
\fBport_notify_t\fR structure defined in <\fBport.h\fR> (see
\fBport_associate\fR(3C)). The event port identifier as well as an
application-defined cookie are part of the \fBport_notify_t\fR structure.
.RE

.sp
.LP
The \fBsigev_signo\fR member contains the application-defined value to be
passed to the signal-catching function (for notification type
\fBSIGEV_SIGNAL\fR) at the time of the signal delivery as the \fBsi_value\fR
member of the \fBsiginfo_t\fR structure, or as the argument to the notification
function (for notification type \fBSIGEV_THREAD\fR) that is called when the
asynchronous event occurs.  For notification type \fBSIGEV_PORT\fR,
\fBsigev_value.sival_ptr\fR points to a \fBport_notify_t\fR structure that
specifies the port and an application-defined cookie.
.sp
.LP
The \fBsigev_value\fR member references the application defined value to be
passed to the signal-catching function at the time of the signal delivery as
the \fBsi_value\fR member of the \fBsiginfo_t\fR structure.
.sp
.LP
The \fBsival_int\fR member is used when the application defined value is of
type \fBint\fR, and the \fBsival_ptr\fR member is used when the application
defined value is a pointer.
.sp
.LP
When a signal is generated by \fBsigqueue\fR(3C) or any signal\(migenerating
function which supports the specification of an application defined value, the
signal is marked pending and, if the  \fBSA_SIGINFO\fR 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  \fBSA_SIGINFO\fR flag is not set for that signal, later
occurrences of that signal's generation, when a signal is already queued, are
silently discarded.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE  ATTRIBUTE VALUE
_
Interface Stability     Committed
_
Standard        See \fBstandards\fR(5).
.TE

.SH SEE ALSO
.sp
.LP
\fBlockd\fR(1M), \fBIntro\fR(2), \fBalarm\fR(2), \fBexit\fR(2), \fBfcntl\fR(2),
\fBgetrlimit\fR(2), \fBioctl\fR(2), \fBkill\fR(2), \fBpause\fR(2),
\fBsetrctl\fR(2), \fBsigaction\fR(2), \fBsigaltstack\fR(2),
\fBsigprocmask\fR(2), \fBsigsend\fR(2), \fBsigsuspend\fR(2), \fBsigwait\fR(2),
\fBport_associate\fR(3C), \fBpthread_create\fR(3C), \fBpthread_kill\fR(3C),
\fBpthread_sigmask\fR(3C), \fBsetjmp\fR(3C), \fBsiginfo.h\fR(3HEAD),
\fBsignal\fR(3C), \fBsigqueue\fR(3C), \fBsigsetops\fR(3C),
\fBucontext.h\fR(3HEAD), \fBwait\fR(3C), \fBattributes\fR(5),
\fBstandards\fR(5)
.SH NOTES
.sp
.LP
The dispositions of the \fBSIGKILL\fR and \fBSIGSTOP\fR signals cannot be
altered from their default values. The system generates an error if this is
attempted.
.sp
.LP
The \fBSIGKILL\fR, \fBSIGSTOP\fR, and \fBSIGCANCEL\fR signals cannot be
blocked. The system silently enforces this restriction.
.sp
.LP
The \fBSIGCANCEL\fR signal cannot be directed to an individual thread using
\fBpthread_kill\fR(3C), but it can be sent to a process using \fBkill\fR(2),
\fBsigsend\fR(2), or \fBsigqueue\fR(3C).
.sp
.LP
Whenever a process receives a \fBSIGSTOP\fR, \fBSIGTSTP\fR, \fBSIGTTIN\fR, or
\fBSIGTTOU\fR signal, regardless of its disposition, any pending \fBSIGCONT\fR
signal are discarded.
.sp
.LP
Whenever a process receives a \fBSIGCONT\fR signal, regardless of its
disposition, any pending \fBSIGSTOP\fR, \fBSIGTSTP\fR, \fBSIGTTIN\fR, and
\fBSIGTTOU\fR signals is discarded. In addition, if the process was stopped, it
is continued.
.sp
.LP
\fBSIGPOLL\fR is issued when a file descriptor corresponding to a STREAMS file
has a "selectable" event pending. See \fBIntro\fR(2). A process must
specifically request that this signal be sent using the \fBI_SETSIG\fR
\fBioctl\fR call. Otherwise, the process will never receive \fBSIGPOLL\fR.
.sp
.LP
If the disposition of the \fBSIGCHLD\fR signal has been set with \fBsignal()\fR
or \fBsigset()\fR, or with \fBsigaction()\fR and the \fBSA_NOCLDSTOP\fR 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.
.sp
.LP
The name \fBSIGCLD\fR is also defined in this header and identifies the same
signal as  \fBSIGCHLD\fR. \fBSIGCLD\fR is provided for backward compatibility,
new applications should use  \fBSIGCHLD\fR.
.sp
.LP
The disposition of signals that are inherited as \fBSIG_IGN\fR should not be
changed.
.sp
.LP
Signals which are generated synchronously should not be masked. If such a
signal is blocked and delivered, the receiving process is killed.