xsh_chap02.html

IEEE 1003.1-2003, Single Unix Specification v3

<p>This option may be implemented as a per-thread variable whereby an <i>errno</i> field is allocated in the user space object
representing a thread, and whereby the function <i>__errno</i>() makes a system call to determine the location of its user space
object and returns the address of the <i>errno</i> field of that object. Another implementation, one that avoids calling the
kernel, involves allocating stacks in chunks. The stack allocator keeps a side table indexed by chunk number containing a pointer
to the thread object that uses that chunk. The <i>__errno</i>() function then looks at the stack pointer, determines the chunk
number, and uses that as an index into the chunk table to find its thread object and thus its private value of <i>errno</i>. On
most architectures, this can be done in four to five instructions. Some compilers may wish to implement <i>__errno</i>() inline to
improve performance.</p>

<h5><a name="tag_03_02_03_02"></a>Disallowing Return of the [EINTR] Error Code</h5>

<p>Many blocking interfaces defined by IEEE&nbsp;Std&nbsp;1003.1-2001 may return [EINTR] if interrupted during their execution by a
signal handler. Blocking interfaces introduced under the Threads option do not have this property. Instead, they require that the
interface appear to be atomic with respect to interruption. In particular, clients of blocking interfaces need not handle any
possible [EINTR] return as a special case since it will never occur. If it is necessary to restart operations or complete
incomplete operations following the execution of a signal handler, this is handled by the implementation, rather than by the
application.</p>

<p>Requiring applications to handle [EINTR] errors on blocking interfaces has been shown to be a frequent source of often
unreproducible bugs, and it adds no compelling value to the available functionality. Thus, blocking interfaces introduced for use
by multi-threaded programs do not use this paradigm. In particular, in none of the functions <a href=
"../functions/flockfile.html"><i>flockfile</i>()</a>, <a href=
"../functions/pthread_cond_timedwait.html"><i>pthread_cond_timedwait</i>()</a>, <a href=
"../functions/pthread_cond_wait.html"><i>pthread_cond_wait</i>()</a>, <a href=
"../functions/pthread_join.html"><i>pthread_join</i>()</a>, <a href=
"../functions/pthread_mutex_lock.html"><i>pthread_mutex_lock</i>()</a>, and <a href=
"../functions/sigwait.html"><i>sigwait</i>()</a> did providing [EINTR] returns add value, or even particularly make sense. Thus,
these functions do not provide for an [EINTR] return, even when interrupted by a signal handler. The same arguments can be applied
to <a href="../functions/sem_wait.html"><i>sem_wait</i>()</a>, <a href="../functions/sem_trywait.html"><i>sem_trywait</i>()</a>, <a
href="../functions/sigwaitinfo.html"><i>sigwaitinfo</i>()</a>, and <a href=
"../functions/sigtimedwait.html"><i>sigtimedwait</i>()</a>, but implementations are permitted to return [EINTR] error codes for
these functions for compatibility with earlier versions of IEEE&nbsp;Std&nbsp;1003.1. Applications cannot rely on calls to these
functions returning [EINTR] error codes when signals are delivered to the calling thread, but they should allow for the
possibility.</p>

<h5><a name="tag_03_02_03_03"></a>Additional Error Numbers</h5>

<p>The ISO&nbsp;C standard defines the name space for implementations to add additional error numbers.</p>

<h4><a name="tag_03_02_04"></a>Signal Concepts</h4>

<p>Historical implementations of signals, using the <a href="../functions/signal.html"><i>signal</i>()</a> function, have
shortcomings that make them unreliable for many application uses. Because of this, a new signal mechanism, based very closely on
the one of 4.2 BSD and 4.3 BSD, was added to POSIX.1.</p>

<h5><a name="tag_03_02_04_01"></a>Signal Names</h5>

<p>The restriction on the actual type used for <b>sigset_t</b> is intended to guarantee that these objects can always be assigned,
have their address taken, and be passed as parameters by value. It is not intended that this type be a structure including pointers
to other data structures, as that could impact the portability of applications performing such operations. A reasonable
implementation could be a structure containing an array of some integer type.</p>

<p>The signals described in IEEE&nbsp;Std&nbsp;1003.1-2001 must have unique values so that they may be named as parameters of
<b>case</b> statements in the body of a C-language <b>switch</b> clause. However, implementation-defined signals may have values
that overlap with each other or with signals specified in IEEE&nbsp;Std&nbsp;1003.1-2001. An example of this is SIGABRT, which
traditionally overlaps some other signal, such as SIGIOT.</p>

<p>SIGKILL, SIGTERM, SIGUSR1, and SIGUSR2 are ordinarily generated only through the explicit use of the <a href=
"../functions/kill.html"><i>kill</i>()</a> function, although some implementations generate SIGKILL under extraordinary
circumstances. SIGTERM is traditionally the default signal sent by the <a href="../utilities/kill.html"><i>kill</i></a>
command.</p>

<p>The signals SIGBUS, SIGEMT, SIGIOT, SIGTRAP, and SIGSYS were omitted from POSIX.1 because their behavior is
implementation-defined and could not be adequately categorized. Conforming implementations may deliver these signals, but must
document the circumstances under which they are delivered and note any restrictions concerning their delivery. The signals SIGFPE,
SIGILL, and SIGSEGV are similar in that they also generally result only from programming errors. They were included in POSIX.1
because they do indicate three relatively well-categorized conditions. They are all defined by the ISO&nbsp;C standard and thus
would have to be defined by any system with an ISO&nbsp;C standard binding, even if not explicitly included in POSIX.1.</p>

<p>There is very little that a Conforming POSIX.1 Application can do by catching, ignoring, or masking any of the signals SIGILL,
SIGTRAP, SIGIOT, SIGEMT, SIGBUS, SIGSEGV, SIGSYS, or SIGFPE. They will generally be generated by the system only in cases of
programming errors. While it may be desirable for some robust code (for example, a library routine) to be able to detect and
recover from programming errors in other code, these signals are not nearly sufficient for that purpose. One portable use that does
exist for these signals is that a command interpreter can recognize them as the cause of a process' termination (with <a href=
"../functions/wait.html"><i>wait</i>()</a>) and print an appropriate message. The mnemonic tags for these signals are derived from
their PDP-11 origin.</p>

<p>The signals SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU, and SIGCONT are provided for job control and are unchanged from 4.2 BSD. The
signal SIGCHLD is also typically used by job control shells to detect children that have terminated or, as in 4.2 BSD, stopped.</p>

<p>Some implementations, including System&nbsp;V, have a signal named SIGCLD, which is similar to SIGCHLD in 4.2 BSD. POSIX.1
permits implementations to have a single signal with both names. POSIX.1 carefully specifies ways in which conforming applications
can avoid the semantic differences between the two different implementations. The name SIGCHLD was chosen for POSIX.1 because most
current application usages of it can remain unchanged in conforming applications. SIGCLD in System&nbsp;V has more cases of
semantics that POSIX.1 does not specify, and thus applications using it are more likely to require changes in addition to the name
change.</p>

<p>The signals SIGUSR1 and SIGUSR2 are commonly used by applications for notification of exceptional behavior and are described as
&quot;reserved as application-defined&quot; so that such use is not prohibited. Implementations should not generate SIGUSR1 or SIGUSR2,
except when explicitly requested by <a href="../functions/kill.html"><i>kill</i>()</a>. It is recommended that libraries not use
these two signals, as such use in libraries could interfere with their use by applications calling the libraries. If such use is
unavoidable, it should be documented. It is prudent for non-portable libraries to use non-standard signals to avoid conflicts with
use of standard signals by portable libraries.</p>

<p>There is no portable way for an application to catch or ignore non-standard signals. Some implementations define the range of
signal numbers, so applications can install signal-catching functions for all of them. Unfortunately, implementation-defined
signals often cause problems when caught or ignored by applications that do not understand the reason for the signal. While the
desire exists for an application to be more robust by handling all possible signals (even those only generated by <a href=
"../functions/kill.html"><i>kill</i>()</a>), no existing mechanism was found to be sufficiently portable to include in POSIX.1. The
value of such a mechanism, if included, would be diminished given that SIGKILL would still not be catchable.</p>

<p>A number of new signal numbers are reserved for applications because the two user signals defined by POSIX.1 are insufficient
for many realtime applications. A range of signal numbers is specified, rather than an enumeration of additional reserved signal
names, because different applications and application profiles will require a different number of application signals. It is not
desirable to burden all application domains and therefore all implementations with the maximum number of signals required by all
possible applications. Note that in this context, signal numbers are essentially different signal priorities.</p>

<p>The relatively small number of required additional signals, {_POSIX_RTSIG_MAX}, was chosen so as not to require an unreasonably
large signal mask/set. While this number of signals defined in POSIX.1 will fit in a single 32-bit word signal mask, it is
recognized that most existing implementations define many more signals than are specified in POSIX.1 and, in fact, many
implementations have already exceeded 32 signals (including the &quot;null signal&quot;). Support of {_POSIX_RTSIG_MAX} additional signals
may push some implementation over the single 32-bit word line, but is unlikely to push any implementations that are already over
that line beyond the 64-signal line.</p>

<h5><a name="tag_03_02_04_02"></a>Signal Generation and Delivery</h5>

<p>The terms defined in this section are not used consistently in documentation of historical systems. Each signal can be
considered to have a lifetime beginning with generation and ending with delivery or acceptance. The POSIX.1 definition of
&quot;delivery&quot; does not exclude ignored signals; this is considered a more consistent definition. This revised text in several parts
of IEEE&nbsp;Std&nbsp;1003.1-2001 clarifies the distinct semantics of asynchronous signal delivery and synchronous signal
acceptance. The previous wording attempted to categorize both under the term &quot;delivery&quot;, which led to conflicts over whether the
effects of asynchronous signal delivery applied to synchronous signal acceptance.</p>

<p>Signals generated for a process are delivered to only one thread. Thus, if more than one thread is eligible to receive a signal,
one has to be chosen. The choice of threads is left entirely up to the implementation both to allow the widest possible range of
conforming implementations and to give implementations the freedom to deliver the signal to the &quot;easiest possible&quot; thread should
there be differences in ease of delivery between different threads.</p>

<p>Note that should multiple delivery among cooperating threads be required by an application, this can be trivially constructed
out of the provided single-delivery semantics. The construction of a <i>sigwait_multiple</i>() function that accomplishes this goal
is presented with the rationale for <a href="../functions/sigwaitinfo.html"><i>sigwaitinfo</i>()</a>.</p>

<p>Implementations should deliver unblocked signals as soon after they are generated as possible. However, it is difficult for
POSIX.1 to make specific requirements about this, beyond those in <a href="../functions/kill.html"><i>kill</i>()</a> and <a href=
"../functions/sigprocmask.html"><i>sigprocmask</i>()</a>. Even on systems with prompt delivery, scheduling of higher priority
processes is always likely to cause delays.</p>

<p>In general, the interval between the generation and delivery of unblocked signals cannot be detected by an application. Thus,
references to pending signals generally apply to blocked, pending signals. An implementation registers a signal as pending on the
process when no thread has the signal unblocked and there are no threads blocked in a <a href=
"../functions/sigwait.html"><i>sigwait</i>()</a> function for that signal. Thereafter, the implementation delivers the signal to
the first thread that unblocks the signal or calls a <a href="../functions/sigwait.html"><i>sigwait</i>()</a> function on a signal
set containing this signal rather than choosing the recipient thread at the time the signal is sent.</p>

<p>In the 4.3 BSD system, signals that are blocked and set to SIG_IGN are discarded immediately upon generation. For a signal that
is ignored as its default action, if the action is SIG_DFL and the signal is blocked, a generated signal remains pending. In the
4.1 BSD system and in System&nbsp;V Release 3 (two other implementations that support a somewhat similar signal mechanism), all
ignored blocked signals remain pending if generated. Because it is not normally useful for an application to simultaneously ignore
and block the same signal, it was unnecessary for POSIX.1 to specify behavior that would invalidate any of the historical
implementations.</p>

<p>There is one case in some historical implementations where an unblocked, pending signal does not remain pending until it is
delivered. In the System&nbsp;V implementation of <a href="../functions/signal.html"><i>signal</i>()</a>, pending signals are
discarded when the action is set to SIG_DFL or a signal-catching routine (as well as to SIG_IGN). Except in the case of setting
SIGCHLD to SIG_DFL, implementations that do this do not conform completely to POSIX.1. Some earlier proposals for POSIX.1
explicitly stated this, but these statements were redundant due to the requirement that functions defined by POSIX.1 not change
attributes of processes defined by POSIX.1 except as explicitly stated.</p>

<p>POSIX.1 specifically states that the order in which multiple, simultaneously pending signals are delivered is unspecified. This
order has not been explicitly specified in historical implementations, but has remained quite consistent and been known to those
familiar with the implementations. Thus, there have been cases where applications (usually system utilities) have been written with
explicit or implicit dependencies on this order. Implementors and others porting existing applications may need to be aware of such
dependencies.</p>

<p>When there are multiple pending signals that are not blocked, implementations should arrange for the delivery of all signals at
once, if possible. Some implementations stack calls to all pending signal-catching routines, making it appear that each
signal-catcher was interrupted by the next signal. In this case, the implementation should ensure that this stacking of signals
does not violate the semantics of the signal masks established by <a href="../functions/sigaction.html"><i>sigaction</i>()</a>.
Other implementations process at most one signal when the operating system is entered, with remaining signals saved for later
delivery. Although this practice is widespread, this behavior is neither standardized nor endorsed. In either case, implementations
should attempt to deliver signals associated with the current state of the process (for example, SIGFPE) before other signals, if
possible.</p>

<p>In 4.2 BSD and 4.3 BSD, it is not permissible to ignore or explicitly block SIGCONT, because if blocking or ignoring this signal
prevented it from continuing a stopped process, such a process could never be continued (only killed by SIGKILL). However, 4.2 BSD
and 4.3 BSD do block SIGCONT during execution of its signal-catching function when it is caught, creating exactly this problem. A
proposal was considered to disallow catching SIGCONT in addition to ignoring and blocking it, but this limitation led to
objections. The consensus was to require that SIGCONT always continue a stopped process when generated. This removed the need to
disallow ignoring or explicit blocking of the signal; note that SIG_IGN and SIG_DFL are equivalent for SIGCONT.</p>

<h5><a name="tag_03_02_04_03"></a>Realtime Signal Generation and Delivery</h5>

<p>The Realtime Signals Extension option to POSIX.1 signal generation and delivery behavior is required for the following
reasons:</p>

<ul>
<li>
<p>The <b>sigevent</b> structure is used by other POSIX.1 functions that result in asynchronous event notifications to specify the
notification mechanism to use and other information needed by the notification mechanism. IEEE&nbsp;Std&nbsp;1003.1-2001 defines
only three symbolic values for the notification mechanism. SIGEV_NONE is used to indicate that no notification is required when the
event occurs. This is useful for applications that use asynchronous I/O with polling for completion. SIGEV_SIGNAL indicates that a
signal is generated when the event occurs. SIGEV_THREAD provides for &quot;callback functions&quot; for asynchronous notifications done by
a function call within the context of a new thread. This provides a multi-threaded process with a more natural means of
notification than signals. The primary difficulty with previous notification approaches has been to specify the environment of the
notification routine.</p>

<ul>
<li>
<p>One approach is to limit the notification routine to call only functions permitted in a signal handler. While the list of
permissible functions is clearly stated, this is overly restrictive.</p>
</li>

<li>
<p>A second approach is to define a new list of functions or classes of functions that are explicitly permitted or not permitted.
This would give a programmer more lists to deal with, which would be awkward.</p>
</li>

<li>
<p>The third approach is to define completely the environment for execution of the notification function. A clear definition of an
execution environment for notification is provided by executing the notification function in the environment of a newly created