NuttxUserGuide.html

<B>Input Parameters:</B> 
<UL>
<LI><I>wdog</I>. ID of the watchdog to cancel.
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>OK or ERROR
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> This is a NON-POSIX interface.
VxWorks provides the following comparable interface:
<PRE>
    STATUS wdCancel (WDOG_ID wdog);
</PRE>

<h3><a name="wdgettime">2.6.5 wd_gettime</a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;wdog.h&gt;
    Sint wd_gettime(WDOG_ID wdog);
</pre>
<p>
  <b>Description:</b> 
   This function returns the time remaining before the the specified watchdog expires.
</p>
<p>
  <b>Input Parameters:</b>
  <ul>
    <li><code>wdog</code>. Identifies the watchdog that the request is for.</li>
  </ul>
</p>
<p>
  <b>Returned Value:</b> 
  The time in system ticks remaining until the watchdog time expires.  Zero
  means either that wdog is not valid or that the wdog has already expired.
</p>

<HR>

<H2><A NAME="ClocksNTimers">2.7 Clocks and Timers</A></H2>
<ul>
  <li><a href="#clocksettime">2.7.1 clock_settime</a></li>
  <li><a href="#clockgettime">2.7.2 clock_gettime</a></li>
  <li><a href="#clockgetres">2.7.3 clock_getres</a></li>
  <li><a href="#mktime">2.7.4 mktime</a></li>
  <li><a href="#gmtimer">2.7.5 gmtime_r</a></li>
  <li><a href="#localtimer">2.7.6 localtime_r</a></li>
  <li><a href="#timercreate">2.7.7 timer_create</a></li>
  <li><a href="#timerdelete">2.7.8 timer_delete</a></li>
  <li><a href="#timersettime">2.7.9 timer_settime</a></li>
  <li><a href="#timergettime">2.7.10 timer_gettime</a></li>
  <li><a href="#timergetoverrun">2.7.11 timer_getoverrun</a></li>
</ul>

<H3><a name="clocksettime">2.7.1 clock_settime</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int clock_settime(clockid_t clockid, const struct timespec *tp);
</pre>
<p>
  <b>Description:</b>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>parm</code>. </li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>clock_settime()</I> function will return zero (<I>OK</I>).
  Otherwise, an non-zero error number will be returned to indicate the error:
</p>
<ul>
  <li><code>Exxx</code>.</li>
</ul>

<H3><a name="clockgettime">2.7.2 clock_gettime</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int clock_gettime(clockid_t clockid, struct timespec *tp);
</pre>
<p>
  <b>Description:</b>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>parm</code>. </li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>clock_gettime()</I> function will return zero (<I>OK</I>).
  Otherwise, an non-zero error number will be returned to indicate the error:
</p>
<ul>
  <li><code>Exxx</code>.</li>
</ul>

<H3><a name="clockgetres">2.7.3 clock_getres</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int clock_getres(clockid_t clockid, struct timespec *res);
</pre>
<p>
  <b>Description:</b>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>parm</code>. </li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>clock_getres()</I> function will return zero (<I>OK</I>).
  Otherwise, an non-zero error number will be returned to indicate the error:
</p>
<ul>
  <li><code>Exxx</code>.</li>
</ul>

<H3><a name="mktime">2.7.4 mktime</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    time_t mktime(struct tm *tp);
</pre>
<p>
  <b>Description:</b>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>parm</code>. </li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>mktime()</I> function will return zero (<I>OK</I>).
  Otherwise, an non-zero error number will be returned to indicate the error:
</p>
<ul>
  <li><code>Exxx</code>.</li>
</ul>

<H3><a name="gmtimer">2.7.5 gmtime_r</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    struct tm *gmtime_r(const time_t *clock, struct tm *result);
</pre>
<p>
  <b>Description:</b>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>parm</code>. </li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>gmtime_r()</I> function will return zero (<I>OK</I>).
  Otherwise, an non-zero error number will be returned to indicate the error:
</p>
<ul>
  <li><code>Exxx</code>.</li>
</ul>

<H3><a name="localtimer">2.7.6 localtime_r</A></H3>
<pre>
    #include &lt;time.h&gt;
    #define localtime_r(c,r) gmtime_r(c,r)
</pre>

<H3><a name="timercreate">2.7.7 timer_create</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int timer_create(clockid_t clockid, struct sigevent *evp, timer_t *timerid);
</pre>
<p>
  <b>Description:</b>
  The  <code>timer_create()</code> function creates per-thread timer using the specified
  clock, <code>clock_id</code>, as the timing base.
  The <code>timer_create()</code> function returns, in
  the location referenced by <code>timerid</code>, a timer ID of type timer_t used to identify
  the timer in timer requests.
  This timer ID is unique until the timer is deleted.
  The particular clock, <code>clock_id<code>, is defined in <code>&lt;time.h&gt;<code>.
  The timer whose ID is returned will be in a disarmed state upon return from
  <code>timer_create()</code>.
</p>
<p>
  The <code>evp</code> argument, if non-NULL, points to a <code>sigevent</code> structure.
  This structure is allocated by the called and defines the asynchronous notification to occur.
  If the <code>evp</code> argument is NULL, the effect is as if the <code>evp</code> argument pointed to
  a <code>sigevent</code> structure with the <code>sigev_notify</code> member having the value <code>SIGEV_SIGNAL</code>,
  the <code>sigev_signo</code> having a default signal number, and the <code>sigev_value</code> member
  having the value of the timer ID.
</p>
<p>
  Each implementation defines a set of clocks that can be used as timing bases
  for per-thread timers. All implementations shall support a <code>clock_id</code> of
  <code>CLOCK_REALTIME</code>.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>clockid</code>. Specifies the clock to use as the timing base.
    Must be <code>CLOCK_REALTIME</code>.</li>
  <li><code>evp</code>. Refers to a user allocated sigevent structure that defines the
    asynchronous notification.  evp may be NULL (see above).</li>
  <li><code>timerid</code>. The pre-thread timer created by the call to timer_create().</li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If the call succeeds, <code>timer_create()</code> will return 0 (<code>OK</code>) and update the
  location referenced by <code>timerid</code> to a <code>timer_t</code>, which can be passed to the
  other per-thread timer calls.  If an error occurs, the function will return
  a value of -1 (<code>ERROR</code>) and set errno to indicate the error.
</p>
<ul>
  <li><code>EAGAIN</code>. The system lacks sufficient signal queuing resources to honor the
    request.</li>
  <li><code>EAGAIN</code>. The calling process has already created all of the timers it is
    allowed by this implementation.</li>
  <li><code>EINVAL</code>. The specified clock ID is not defined.</li>
  <li><code>ENOTSUP</code>. The implementation does not support the creation of a timer attached
    to the CPU-time clock that is specified by clock_id and associated with a
    thread different thread invoking timer_create().</li>
</ul>
<p>
  <b>POSIX Compatibility:</b>
  Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include:
</p>
<ul>
  <li>Only <code>CLOCK_REALTIME</code> is supported for the <code>clockid</code> argument.</li>
</ul>

<H3><a name="timerdelete">2.7.8 timer_delete</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int timer_delete(timer_t timerid);
</pre>
<p>
  <b>Description:</b>
  The <code>timer_delete()</code> function deletes the specified timer, <code>timerid</code>, previously
  created by the <code>timer_create()</code> function.
  If the timer is armed when <code>timer_delete()</code> is called, the timer will be automatically disarmed before
  removal.
  The disposition of pending signals for the deleted timer is unspecified.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>timerid</code>.
  The pre-thread timer, previously created by the call to timer_create(), to be deleted.</li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>timer_delete()</I> function will return zero (<I>OK</I>).
  Otherwise, the function will return a value of -1 (ERROR) and set errno to indicate the error:
</p>
<ul>
  <li><code>EINVAL</code>. The timer specified timerid is not valid.</li>
</ul>
<p>
  <b>POSIX Compatibility:</b>
  Comparable to the POSIX interface of the same name.
</p>

<H3><a name="timersettime">2.7.9 timer_settime</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int timer_settime(timer_t timerid, int flags, const struct itimerspec *value,
                      struct itimerspec *ovalue);
</pre>
<p>
  <b>Description:</b>
  The <code>timer_settime()</code> function sets the time until the next expiration of the
  timer specified by <code>timerid</code> from the <code>it_value</code> member of the value argument
  and arm the timer if the <code>it_value</code> member of value is non-zero. If the
  specified timer was already armed when <code>timer_settime()</code> is called, this call
  will reset the time until next expiration to the value specified. If the
  <code>it_value</code> member of value is zero, the timer will be disarmed. The effect
  of disarming or resetting a timer with pending expiration notifications is
  unspecified.
</p>
<p>
  If the flag <code>TIMER_ABSTIME</code> is not set in the argument flags, <code>timer_settime()</code>
  will behave as if the time until next expiration is set to be equal to the
  interval specified by the <code>it_value</code> member of value. That is, the timer will
  expire in <code>it_value</code> nanoseconds from when the call is made. If the flag
  <code>TIMER_ABSTIME</code> is set in the argument flags, <code>timer_settime()</code> will behave as
  if the time until next expiration is set to be equal to the difference between
  the absolute time specified by the <code>it_value</code> member of value and the current
  value of the clock associated with <code>timerid</code>.  That is, the timer will expire
  when the clock reaches the value specified by the <code>it_value</code> member of value.
  If the specified time has already passed, the function will succeed and the
  expiration notification will be made.
</p>
<p>
  The reload value of the timer will be set to the value specified by the
  <code>it_interval</code> member of value.  When a timer is armed with a non-zero
  <code>it_interval</code>, a periodic (or repetitive) timer is specified.
</p>
<p>
  Time values that are between two consecutive non-negative integer multiples
  of the resolution of the specified timer will be rounded up to the larger
  multiple of the resolution. Quantization error will not cause the timer to
  expire earlier than the rounded time value.
</p>
<p>
  If the argument <code>ovalue</code> is not NULL, the t<code>imer_settime()</code> function will store,
  in the location referenced by <code>ovalue</code>, a value representing the previous
  amount of time before the timer would have expired, or zero if the timer was
  disarmed, together with the previous timer reload value. Timers will not
  expire before their scheduled time.
</p>
  <b>NOTE:</b>At present, the <code>ovalue</code> argument is ignored.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
 <li><code>timerid</code>. The pre-thread timer, previously created by the call to timer_create(), to be be set.</li>
 <li><code>flags</code>. Specifie characteristics of the timer (see above)</li>
 <li><code>value</code>. Specifies the timer value to set</li>
 <li><code>ovalue</code>. A location in which to return the time remaining from the previous timer setting (ignored).</li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If the timer_gettime() succeeds, a value of 0 (OK) will be returned.
  If an error occurs, the value -1 (ERROR) will be returned, and errno set to indicate the error.
</p>
<ul>
  <li><code>EINVAL</code>. The timerid argument does not correspond to an ID returned by timer_create() but not yet deleted by timer_delete().</li>
  <li><code>EINVAL</code>. A value structure specified a nanosecond value less than zero or greater than or equal to 1000 million,
    and the it_value member of that structure did not specify zero seconds and nanoseconds.</li>
</ul>
<p>
  <b>POSIX Compatibility:</b>
  Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include:
</p>
<ul>
  <li>The <code>ovalue</code> argument is ignored.</li>
</ul>

<H3><a name="timergettime">2.7.10 timer_gettime</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int timer_gettime(timer_t timerid, struct itimerspec *value);
</pre>
<p>
  <b>Description:</b>
  The <code>timer_gettime()</code> function will store the amount of time until the
  specified timer, <code>timerid</code>, expires and the reload value of the timer into the
  space pointed to by the <code>value</code> argument. The <code>it_value</code> member of this structure
  will contain the amount of time before the timer expires, or zero if the timer
  is disarmed. This value is returned as the interval until timer expiration,
  even if the timer was armed with absolute time. The <code>it_interval</code> member of
  <code>value</code> will contain the reload value last set by <code>timer_settime()</code>.
</p>
<p>
   Due to the asynchronous operation of this function, the time reported
   by this function could be significantly more than that actual time
   remaining on the timer at any time.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
 <li><code>timerid</code>. Specifies pre-thread timer, previously created by the call to
 t<code>imer_create()</code>, whose remaining count will be returned.</li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>timer_gettime()</I> function will return zero (<I>OK</I>).
  Otherwise, an non-zero error number will be returned to indicate the error:
</p>
<ul>
  <li><code>EINVAL</code>.
  The <code>timerid</code> argument does not correspond to an ID returned by
  <code>timer_create()</code> but not yet deleted by <code>timer_delete()</code>.</li>
</ul>
<p>
  <b>POSIX Compatibility:</b>
  Comparable to the POSIX interface of the same name.
</p>

<H3><a name="timergetoverrun">2.7.11 timer_getoverrun</A></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    int timer_getoverrun(timer_t timerid);
</pre>
<p>
  <b>Description:</b>
  Only a single signal will be queued to the process for a given timer at any
  point in time.  When a timer for which a signal is still pending expires, no
  signal will be queued, and a timer overrun will occur. When a timer
  expiration signal is delivered to or accepted by a process, if the
  implementation  supports  the  <i>Realtime Signals Extension</i>, the
  <code>timer_getoverrun()</code> function will return the timer expiration overrun count for
  the specified timer. The overrun count returned contains the number of extra
  timer expirations that occurred between the time the signal was generated
  (queued) and when it was delivered or accepted, up to but not including an 
  implementation-defined  maximum of <code>DELAYTIMER_MAX</code>. If the number of such
  extra expirations is greater than or equal to <code>DELAYTIMER_MAX</code>, then the
  overrun count will be set to <code>DELAYTIMER_MAX</code>. The value returned by
  <code>timer_getoverrun()</code> will apply to the most recent expiration signal delivery
  or acceptance for the timer.  If no expiration signal has been delivered
  for the timer, or if the <i>Realtime Signals Extension</i> is not supported, the
  return value of <code>timer_getoverrun()</code> is unspecified.
</p>
<p>
  <b>NOTE:</b>  This interface is not currently implemented in NuttX.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
 <li><code>timerid</code>. Specifies pre-thread timer, previously created by the call to
 <code>timer_create()</code>, whose overrun count will be returned.</li>
</ul>
<p>
  <b>Returned Values:</b>
  If the <code>timer_getoverrun()</code> function succeeds, it will return the timer
  expiration overrun count as explained above. <code>timer_getoverrun()</code> will fail if:
</p>
<ul>
  <li><code>EINVAL</code>.
  The <code>timerid</code> argument does not correspond to an ID returned by
  <code>timer_create()</code> but not yet deleted by <code>timer_delete()</code>.</li>
</ul>
<p>
  <b>POSIX Compatibility:</b>
  Comparable to the POSIX interface of the same name. Differences from the full POSIX implementation include:
</p>
<ul>
  <li>This interface is not currently implemented by NuttX.</li>
</ul>

<B>Assumptions/Limitations:</B>
<P>
<B>POSIX Compatibility:</B> Comparable to the POSIX
interface of the same name.

<HR>

<H2>2.8 <A NAME="Signals">Signal Interfaces</A></H2>

<p>
  NuttX provides signal interfaces for tasks. Signals are used to
  alter the flow control of tasks by communicating asynchronous events
  within or between task contexts.
  Any task or interrupt handler can post (or send) a signal to a particular task.
  The task being signaled will execute task-specified signal handler
  function the next time that the task has priority.
  The signal handler is a user-supplied function that is bound to
  a specific signal and performs whatever actions are necessary
  whenever the signal is received.
</p>
<p>
  There are no predefined actions for any signal.
  The default action for all signals (i.e., when no signal handler has
  been supplied by the user) is to ignore the signal.
  In this sense, all NuttX are <i>real time</i> signals.
</p>
<p>
  Tasks may also suspend themselves and wait until a signal is received.
</p>
<p>
  The following signal handling interfaces are provided by NuttX:
</p>
<ul>
  <li><a href="#sigemptyset">2.8.1 sigemptyset</a></li>
  <li><a href="#sigfillset">2.8.2 sigfillset</a></li>
  <li><a href="#sigaddset">2.8.3 sigaddset</a></li>
  <li><a href="#sigdelset">2.8.4 sigdelset</a></li>
  <li><a href="#sigismember">2.8.5 sigismember</a></li>
  <li><a href="#sigaction">2.8.6 sigaction</a></li>
  <li><a href="#sigprocmask">2.8.7 sigprocmask</a></li>
  <li><a href="#sigpending">2.8.8 sigpending</a></li>
  <li><a href="#sigsuspend">2.8.9 sigsuspend</a></li>
  <li><a href="#sigwaitinfo">2.8.10 sigwaitinfo</a></li>
  <li><a href="#sigtimedwait">2.8.11 sigtimedwait</a></li>
  <li><a href="#sigqueue">2.8.12 sigqueue</a></li>
  <li><a href="#kill">2.8.13 kill</a></li>
</ul>

<H3><a name="sigemptyset">2.8.1 sigemptyset</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigemptyset(sigset_t *set);
</PRE>

<P>
<B>Description:</B> This function initializes the signal set specified
by set such that all signals are excluded.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>. Signal set to initialize.
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK), or -1 (ERROR) if the signal set cannot be initialized.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigfillset">2.8.2 sigfillset</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigfillset(sigset_t *set);
</PRE>

<P>
<B>Description:</B> This function initializes the signal set specified
by set such that all signals are included.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>. Signal set to initialize
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK), or -1 (ERROR) if the signal set cannot be initialized.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigaddset">2.8.3 sigaddset</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigaddset(sigset_t *set, int signo);
</PRE>

<P>
<B>Description:</B> This function adds the signal specified by
signo to the signal set specified by set.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>. Signal set to add signal to
<LI><I>signo</I>. Signal to add
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK), or -1 (ERROR) if the signal number is invalid.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigdelset">2.8.4 sigdelset</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigdelset(sigset_t *set, int signo);
</PRE>

<P>
<B>Description:</B> This function deletes the signal specified
by signo from the signal set specified by set.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>. Signal set to delete the signal from
<LI><I>signo</I>. Signal to delete
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK), or -1 (ERROR) if the signal number is invalid.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigismember">2.8.5 sigismember</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int  sigismember(const sigset_t *set, int signo);
</PRE>

<P>
<B>Description:</B> This function tests whether the signal specified
by signo is a member of the set specified by set.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>. Signal set to test
<LI><I>signo</I>. Signal to test for
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>1 (TRUE), if the specified signal is a member of the set,
<LI>0 (OK or FALSE), if it is not, or
<LI>-1 (ERROR) if the signal number is invalid.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigaction">2.8.6 sigaction</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigaction( int signo, const struct sigaction *act,
                   struct sigaction *oact );
</PRE>

<P>
<B>Description:</B> This function allows the calling task to
examine and/or specify the action to be associated with a specific
signal.
<P>
The structure sigaction, used to describe an action to be taken, is defined
to include the following members:
<UL>
<LI><I>sa_u.sa_handler</I>.  A pointer to a signal-catching function.
<LI><I>sa_u.sa_sigaction</I>.  An alternative form for the signal catching
function.
<LI><I>sa_mask</I>.  Additional set of signals to be blocked during
execution of the signal-catching function.
<LI><I>sa_flags</I>:  Special flags to affect behavior of a signal.
</UL>
<P>
If the argument act is not NULL, it points to a structure specifying the
action to be associated with the specified signal.  If the argument oact
is not NULL, the action previously associated with the signal is stored
in the location pointed to by the argument oact.  If the argument act is
NULL, signal handling is unchanged by this function call; thus, the call
can be used to enquire about the current handling of a given signal.
<P>
When a signal is caught by a signal-catching function installed by the
sigaction() function, a new signal mask is calculated and installed for
the duration of the signal-catching function.  This mask is formed by taking
the union of the current signal mask and the value of the sa_mask for the
signal being delivered, and then including the signal being delivered.  If
and when the signal handler returns, the original signal mask is restored.
<P>
Signal catching functions execute in the same address environment as the
task that called sigaction() to install the signal-catching function.
<P>
Once an action is installed for a specific signal, it remains installed
until another action is explicitly requested by another call to
sigaction().
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>sig</I>. Signal of interest
<LI><I>act</I>. Location of new handler
<LI><I>oact</I>. Location to store old handler
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK), or -1 (ERROR) if the signal number is invalid.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.
Differences from the POSIX implementation include:
<UL>
<LI>Special values of sa_handler in the struct sigaction act input
not handled (SIG_DFL, SIG_IGN).
<LI>All sa_flags in struct sigaction of act input are ignored
(all treated like SA_SIGINFO).
</UL>

<H3><a name="sigprocmask">2.8.7 sigprocmask</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigprocmask(int how, const sigset_t *set, sigset_t *oset);
</PRE>

<P>
<B>Description:</B> This function allows the calling task to
examine and/or change its signal mask. If the set is not NULL,
then it points to a set of signals to be used to change the currently
blocked set. The value of how indicates the manner in which the
set is changed.
<P>
If there are any pending unblocked signals after the call to sigprocmask(),
those signals will be delivered before sigprocmask() returns.
<P>
If sigprocmask() fails, the signal mask of the task is not changed.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>how</I>. How the signal mast will be changed:
<UL>
<LI><I>osSIG_BLOCK</I>. The resulting set is the union of the
current set and the signal set pointed to by the <I>set</I> input parameter.
<LI><I>osSIG_UNBLOCK</I>. The resulting set is the intersection
of the current set and the complement of the signal set pointed
to by the <I>set</I> input parameter.
<LI><I>osSIG_SETMASK</I>. The resulting set is the signal set
pointed to by the <I>set</I> input parameter.
</UL>

<LI><I>set</I>. Location of the new signal mask
<LI><I>oset</I>. Location to store the old signal mask
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK), or -1 (ERROR) if how is invalid.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigpending">2.8.8 sigpending</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigpending( sigset_t *set );
</PRE>

<P>
<B>Description:</B> This function stores the returns the set of
signals that are blocked for delivery and that are pending for
the calling task in the space pointed to by set.
<P>
If the task receiving a signal has the signal blocked via its
sigprocmask, the signal will pend until it is unmasked.  Only one pending
signal (for a given signo) is retained by the system.  This is consistent
with POSIX which states:  &quot;If a subsequent occurrence of a pending
signal is generated, it is implementation defined as to whether the signal
is delivered more than once.&quot;
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>. The location to return the pending signal set.
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK) or -1 (ERROR)
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigsuspend">2.8.9 sigsuspend</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigsuspend( const sigset_t *set );
</PRE>

<P>
<B>Description:</B> The sigsuspend() function replaces the signal mask
with the set of signals pointed to by the argument set and then suspends
the task until delivery of a signal to the task.
<P>
If the effect of the set argument is to unblock a pending signal, then
no wait is performed.
<P>
The original signal mask is restored when sigsuspend() returns.
<P>
Waiting for an empty signal set stops a task without freeing any
resources (a very bad idea).
<P>
<B>Input Parameters:</B>
<UL>
<LI><I>set</I>.  The value of the signal <B>mask</B> to use while
suspended.
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>-1 (ERROR) always
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.
Differences from the POSIX specification include:
<UL>
<LI>POSIX does not indicate that the original signal mask is restored.
<LI>POSIX states that sigsuspend() &quot;suspends the task until
delivery of a signal whose action is either to execute a signal-catching
function or to terminate the task.&quot;  Only delivery of the signal
is required in the present implementation (even if the signal is ignored).
</UL>

<H3><a name="sigwaitinfo">2.8.10 sigwaitinfo</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigwaitinfo(const sigset_t *set, struct siginfo *info);
</PRE>

<P>
<B>Description:</B> This function is equivalent to sigtimedwait()
with a NULL timeout parameter. (see below).
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>.  The set of pending signals to wait for.
<LI><I>info</I>. The returned signal values
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>Signal number that cause the wait to be terminated, otherwise
-1 (ERROR) is returned.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.

<H3><a name="sigtimedwait">2.8.11 sigtimedwait</a></H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;signal.h&gt;
    int sigtimedwait( const sigset_t *set, struct siginfo *info,
                      const struct timespec *timeout );
</PRE>

<P>
<B>Description:</B> This function selects the pending signal set
specified by the argument set. If multiple signals are pending in set,
it will remove and return the lowest numbered one. If no signals in set
are pending at the time of the call, the calling task will be suspended
until one of the signals in set becomes pending OR until the task
interrupted by an unblocked signal OR until the time interval specified by
timeout (if any), has expired. If timeout is NULL, then the timeout interval
is forever.
<P>
If the info argument is non-NULL, the selected signal number is
stored in the si_signo member and the cause of the signal is store
in the si_code member. The content of si_value is only meaningful
if the signal was generated by sigqueue(). The following values
for si_code are defined in signal.h:
<UL>
  <LI><I>SI_USER</I>. Signal sent from kill, raise, or abort
  <LI><I>SI_QUEUE</I>. Signal sent from sigqueue
  <LI><I>SI_TIMER</I>. Signal is result of timer expiration
  <LI><I>SI_ASYNCIO</I>. Signal is the result of asynch IO completion 
  <LI><I>SI_MESGQ</I>. Signal generated by arrival of a message on an empty message queue.
</UL>

<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>set</I>.  The set of pending signals to wait for.
<LI><I>info</I>. The returned signal values
<LI><I>timeout</I>. The amount of time to wait
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>Signal number that cause the wait to be terminated, otherwise
-1 (ERROR) is returned.
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.
Differences from the POSIX interface include:
<UL>
<LI>Values for si_codes differ
<LI>No mechanism to return cause of ERROR. (It can be inferred