sigaction.html

IEEE 1003.1-2003, Single Unix Specification v3

then including the signal being delivered. If and when the user's signal handler returns normally, the original signal mask is
restored.</p>

<p>Once an action is installed for a specific signal, it shall remain installed until another action is explicitly requested (by
another call to <i>sigaction</i>()), <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif"
alt="[Option Start]" border="0"> &nbsp;until the SA_RESETHAND flag causes resetting of the handler, <img src=
"../images/opt-end.gif" alt="[Option End]" border="0"> &nbsp;or until one of the <i><a href="../functions/exec.html">exec</a></i>
functions is called.</p>

<p>If the previous action for <i>sig</i> had been established by <a href="../functions/signal.html"><i>signal</i>()</a>, the values
of the fields returned in the structure pointed to by <i>oact</i> are unspecified, and in particular <i>oact</i>-&gt;
<i>sa_handler</i> is not necessarily the same value passed to <a href="../functions/signal.html"><i>signal</i>()</a>. However, if a
pointer to the same structure or a copy thereof is passed to a subsequent call to <i>sigaction</i>() via the <i>act</i> argument,
handling of the signal shall be as if the original call to <a href="../functions/signal.html"><i>signal</i>()</a> were
repeated.</p>

<p>If <i>sigaction</i>() fails, no new signal handler is installed.</p>

<p>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 <i>errno</i> set to [EINVAL].</p>

<p>If SA_SIGINFO is not set in <i>sa_flags</i>, then the disposition of subsequent occurrences of <i>sig</i> when it is already
pending is implementation-defined; the signal-catching function shall be invoked with a single argument. <sup>[<a href=
"javascript:open_code('RTS')">RTS</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0"> &nbsp;If the
implementation supports the Realtime Signals Extension option, and if SA_SIGINFO is set in <i>sa_flags</i>, then subsequent
occurrences of <i>sig</i> generated by <a href="../functions/sigqueue.html"><i>sigqueue</i>()</a> or as a result of any
signal-generating function that supports the specification of an application-defined value (when <i>sig</i> is already pending)
shall be queued in FIFO order until delivered or accepted; the signal-catching function shall be invoked with three arguments. The
application specified value is passed to the signal-catching function as the <i>si_value</i> member of the <b>siginfo_t</b>
structure. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>

<p>The result of the use of <i>sigaction</i>() and a <a href="../functions/sigwait.html"><i>sigwait</i>()</a> function concurrently
within a process on the same signal is unspecified.</p>
</blockquote>

<h4><a name="tag_03_680_04"></a>RETURN VALUE</h4>

<blockquote>
<p>Upon successful completion, <i>sigaction</i>() shall return 0; otherwise, -1 shall be returned, <i>errno</i> shall be set to
indicate the error, and no new signal-catching function shall be installed.</p>
</blockquote>

<h4><a name="tag_03_680_05"></a>ERRORS</h4>

<blockquote>
<p>The <i>sigaction</i>() function shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>The <i>sig</i> argument is not a valid signal number or an attempt is made to catch a signal that cannot be caught or ignore a
signal that cannot be ignored.</dd>

<dt>[ENOTSUP]</dt>

<dd>The SA_SIGINFO bit flag is set in the <i>sa_flags</i> field of the <b>sigaction</b> structure, and the implementation does not
support either the Realtime Signals Extension option, or the XSI Extension option.</dd>
</dl>

<p>The <i>sigaction</i>() function may fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>An attempt was made to set the action to SIG_DFL for a signal that cannot be caught or ignored (or both).</dd>
</dl>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_680_06"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_680_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>The <i>sigaction</i>() function supersedes the <a href="../functions/signal.html"><i>signal</i>()</a> function, and should be
used in preference. In particular, <i>sigaction</i>() and <a href="../functions/signal.html"><i>signal</i>()</a> should not be used
in the same process to control the same signal. The behavior of reentrant functions, as defined in the DESCRIPTION, is as specified
by this volume of IEEE&nbsp;Std&nbsp;1003.1-2001, regardless of invocation from a signal-catching function. This is the only
intended meaning of the statement that reentrant functions may be used in signal-catching functions without restrictions.
Applications must still consider all effects of such functions on such things as data structures, files, and process state. In
particular, application writers need to consider the restrictions on interactions when interrupting <a href=
"../functions/sleep.html"><i>sleep</i>()</a> and interactions among multiple handles for a file description. The fact that any
specific function is listed as reentrant does not necessarily mean that invocation of that function from a signal-catching function
is recommended.</p>

<p>In order to prevent errors arising from interrupting non-reentrant function calls, applications should protect calls to these
functions either by blocking the appropriate signals or through the use of some programmatic semaphore (see <a href=
"semget.html"><i>semget</i>()</a> , <a href="sem_init.html"><i>sem_init</i>()</a> , <a href="sem_open.html"><i>sem_open</i>()</a> ,
and so on). Note in particular that even the &quot;safe&quot; functions may modify <i>errno</i>; the signal-catching function, if not
executing as an independent thread, may want to save and restore its value. Naturally, the same principles apply to the reentrancy
of application routines and asynchronous data access. Note that <a href="../functions/longjmp.html"><i>longjmp</i>()</a> and <a
href="../functions/siglongjmp.html"><i>siglongjmp</i>()</a> are not in the list of reentrant functions. This is because the code
executing after <a href="../functions/longjmp.html"><i>longjmp</i>()</a> and <a href=
"../functions/siglongjmp.html"><i>siglongjmp</i>()</a> can call any unsafe functions with the same danger as calling those unsafe
functions directly from the signal handler. Applications that use <a href="../functions/longjmp.html"><i>longjmp</i>()</a> and <a
href="../functions/siglongjmp.html"><i>siglongjmp</i>()</a> from within signal handlers require rigorous protection in order to be
portable. Many of the other functions that are excluded from the list are traditionally implemented using either <a href=
"../functions/malloc.html"><i>malloc</i>()</a> or <a href="../functions/free.html"><i>free</i>()</a> functions or the standard I/O
library, both of which traditionally use data structures in a non-reentrant manner. Since any combination of different functions
using a common data structure can cause reentrancy problems, this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does not define the
behavior when any unsafe function is called in a signal handler that interrupts an unsafe function.</p>

<p>If the signal occurs other than as the result of calling <a href="../functions/abort.html"><i>abort</i>()</a>, <a href=
"../functions/kill.html"><i>kill</i>()</a>, or <a href="../functions/raise.html"><i>raise</i>()</a>, the behavior is undefined if
the signal handler calls any function in the standard library other than one of the functions listed in the table above or refers
to any object with static storage duration other than by assigning a value to a static storage duration variable of type
<b>volatile sig_atomic_t</b>. Furthermore, if such a call fails, the value of <i>errno</i> is unspecified.</p>

<p>Usually, the signal is executed on the stack that was in effect before the signal was delivered. An alternate stack may be
specified to receive a subset of the signals being caught.</p>

<p>When the signal handler returns, the receiving process resumes execution at the point it was interrupted unless the signal
handler makes other arrangements. If <a href="../functions/longjmp.html"><i>longjmp</i>()</a> or <a href=
"../functions/_longjmp.html"><i>_longjmp</i>()</a> is used to leave the signal handler, then the signal mask must be explicitly
restored by the process.</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 defines the third argument of a signal handling function when SA_SIGINFO is set as
a <b>void *</b> instead of a <b>ucontext_t *</b>, but without requiring type checking. New applications should explicitly cast the
third argument of the signal handling function to <b>ucontext_t *</b>.</p>

<p>The BSD optional four argument signal handling function is not supported by this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. The
BSD declaration would be:</p>

<pre>
<tt>void handler(int</tt> <i>sig</i><tt>, int</tt> <i>code</i><tt>, struct sigcontext *</tt><i>scp</i><tt>,
    char *</tt><i>addr</i><tt>);
</tt>
</pre>

<p>where <i>sig</i> is the signal number, <i>code</i> is additional information on certain signals, <i>scp</i> is a pointer to the
<b>sigcontext</b> structure, and <i>addr</i> is additional address information. Much the same information is available in the
objects pointed to by the second argument of the signal handler specified when SA_SIGINFO is set.</p>
</blockquote>

<h4><a name="tag_03_680_08"></a>RATIONALE</h4>

<blockquote>
<p>Although this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that signals that cannot be ignored shall not be added to the
signal mask when a signal-catching function is entered, there is no explicit requirement that subsequent calls to
<i>sigaction</i>() reflect this in the information returned in the <i>oact</i> argument. In other words, if SIGKILL is included in
the <i>sa_mask</i> field of <i>act</i>, it is unspecified whether or not a subsequent call to <i>sigaction</i>() returns with
SIGKILL included in the <i>sa_mask</i> field of <i>oact</i>.</p>

<p>The SA_NOCLDSTOP flag, when supplied in the <i>act</i>-&gt; <i>sa_flags</i> parameter, allows overloading SIGCHLD with the
System V semantics that each SIGCLD signal indicates a single terminated child. Most conforming applications that catch SIGCHLD are
expected to install signal-catching functions that repeatedly call the <a href="../functions/waitpid.html"><i>waitpid</i>()</a>
function with the WNOHANG flag set, acting on each child for which status is returned, until <a href=
"../functions/waitpid.html"><i>waitpid</i>()</a> returns zero. If stopped children are not of interest, the use of the SA_NOCLDSTOP
flag can prevent the overhead from invoking the signal-catching routine when they stop.</p>

<p>Some historical implementations also define other mechanisms for stopping processes, such as the <i>ptrace</i>() function. These
implementations usually do not generate a SIGCHLD signal when processes stop due to this mechanism; however, that is beyond the
scope of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that calls to <i>sigaction</i>() that supply a NULL <i>act</i> argument
succeed, even in the case of signals that cannot be caught or ignored (that is, SIGKILL or SIGSTOP). The System V <a href=
"../functions/signal.html"><i>signal</i>()</a> and BSD <i>sigvec</i>() functions return [EINVAL] in these cases and, in this
respect, their behavior varies from <i>sigaction</i>().</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that <i>sigaction</i>() properly save and restore a signal action set up
by the ISO&nbsp;C standard <a href="../functions/signal.html"><i>signal</i>()</a> function. However, there is no guarantee that the
reverse is true, nor could there be given the greater amount of information conveyed by the <b>sigaction</b> structure. Because of
this, applications should avoid using both functions for the same signal in the same process. Since this cannot always be avoided
in case of general-purpose library routines, they should always be implemented with <i>sigaction</i>().</p>

<p>It was intended that the <a href="../functions/signal.html"><i>signal</i>()</a> function should be implementable as a library
routine using <i>sigaction</i>().</p>

<p>The POSIX Realtime Extension extends the <i>sigaction</i>() function as specified by the POSIX.1-1990 standard to allow the
application to request on a per-signal basis via an additional signal action flag that the extra parameters, including the
application-defined signal value, if any, be passed to the signal-catching function.</p>
</blockquote>

<h4><a name="tag_03_680_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_680_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="xsh_chap02_04.html#tag_02_04"><i>Signal Concepts</i></a> , <a href="bsd_signal.html"><i>bsd_signal</i>()</a> , <a href=
"kill.html"><i>kill</i>()</a> , <a href="_longjmp.html"><i>_longjmp</i>()</a> , <a href="longjmp.html"><i>longjmp</i>()</a> , <a
href="raise.html"><i>raise</i>()</a> , <a href="semget.html"><i>semget</i>()</a> , <a href="sem_init.html"><i>sem_init</i>()</a> ,
<a href="sem_open.html"><i>sem_open</i>()</a> , <a href="sigaddset.html"><i>sigaddset</i>()</a> , <a href=
"sigaltstack.html"><i>sigaltstack</i>()</a> , <a href="sigdelset.html"><i>sigdelset</i>()</a> , <a href=
"sigemptyset.html"><i>sigemptyset</i>()</a> , <a href="sigfillset.html"><i>sigfillset</i>()</a> , <a href=
"sigismember.html"><i>sigismember</i>()</a> , <a href="signal.html"><i>signal</i>()</a> , <a href=
"sigprocmask.html"><i>sigprocmask</i>()</a> , <a href="sigsuspend.html"><i>sigsuspend</i>()</a> , <a href=
"wait.html"><i>wait</i>()</a> , <a href="waitid.html"><i>waitid</i>()</a> , <a href="waitpid.html"><i>waitpid</i>()</a> , the Base
Definitions volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/signal.h.html"><i>&lt;signal.h&gt;</i></a>, <a href=
"../basedefs/ucontext.h.html"><i>&lt;ucontext.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_03_680_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 3. Included for alignment with the POSIX.1-1988 standard.</p>
</blockquote>

<h4><a name="tag_03_680_12"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and POSIX Threads Extension.</p>

<p>In the DESCRIPTION, the second argument to <i>func</i> when SA_SIGINFO is set is no longer permitted to be NULL, and the
description of permitted <b>siginfo_t</b> contents is expanded by reference to <a href=
"../basedefs/signal.h.html"><i>&lt;signal.h&gt;</i></a>.</p>

<p>Since the X/OPEN UNIX Extension functionality is now folded into the BASE, the [ENOTSUP] error is deleted.</p>
</blockquote>

<h4><a name="tag_03_680_13"></a>Issue 6</h4>

<blockquote>
<p>The Open Group Corrigendum U028/7 is applied. In the paragraph entitled &quot;Signal Effects on Other Functions&quot;, a reference to <a
href="../functions/sigpending.html"><i>sigpending</i>()</a> is added.</p>

<p>In the DESCRIPTION, the text &quot;Signal Generation and Delivery&quot;, &quot;Signal Actions&quot;, and &quot;Signal Effects on Other Functions''
are moved to a separate section of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<p>Text describing functionality from the Realtime Signals option is marked.</p>

<p>The following changes are made for alignment with the ISO&nbsp;POSIX-1:1996 standard:</p>

<ul>
<li>
<p>The [ENOTSUP] error condition is added.</p>
</li>
</ul>

<p>The DESCRIPTION is updated to avoid use of the term &quot;must&quot; for application requirements.</p>

<p>The <b>restrict</b> keyword is added to the <i>sigaction</i>() prototype for alignment with the ISO/IEC&nbsp;9899:1999
standard.</p>

<p>References to the <i>wait3</i>() function are removed.</p>

<p>The SYNOPSIS is marked CX since the presence of this function in the <a href=
"../basedefs/signal.h.html"><i>&lt;signal.h&gt;</i></a> header is an extension over the ISO&nbsp;C standard.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XSH/TC1/D6/57 is applied, changing text in the table describing the
<b>sigaction</b> structure.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>