NuttxUserGuide.html

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b>
<ul>
<li>Care must be taken to avoid deletion of a semaphore that another task
has already locked.
<li>sem_close() must not be called with an un-named semaphore.
</ul>
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="semunlink">2.5.5 sem_unlink</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_unlink ( const char *name );
</pre>

<p>
<b>Description:</b> This function will remove the semaphore named by the
input name parameter.  If one or more tasks have the semaphore named by
name open when sem_unlink() is called, destruction of the semaphore will
be postponed until all references have been destroyed by calls to
sem_close().
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>name</I>. Semaphore name
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<ul>
<li>Care must be taken to avoid deletion of a semaphore that another task
has already locked.
<li>sem_unlink() must not be called with an un-named semaphore.
</ul>
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.
Differences from the full POSIX implementation include:
<ul>
<li>Treatment of links/connections is highly simplified. It is
just a counting semaphore.
<li>Calls to sem_open() to re-create or re-connect to the semaphore may
refer to the same semaphore; POSIX specifies that a new semaphore with the
same name should be created after sem_unlink() is called.
</ul>

<H3><a name="semwait">2.5.6 sem_wait</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_wait ( sem_t *sem );
</pre>

<p>
<b>Description:</b> This function attempts to lock the semaphore
referenced by sem. If the semaphore as already locked by another
task, the calling task will not return until it either successfully acquires
the lock or the call is interrupted by a signal.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. Semaphore descriptor.
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK), or -1 (ERROR) is unsuccessful
</ul>
<p>
If <I>sem_wait</I> returns -1 (ERROR) then the cause of the failure
will be indicated by the thread-specific <a href="#ErrnoAccess"><code>errno</code></a>.
The following lists the possible values for <a href="#ErrnoAccess"><code>errno</code></a>:
<p>
<ul>
<li><I>EINVAL</I>:  Indicates that the <I>sem</I> input parameter is
not valid.
<li><I>EINTR</I>:  Indicates that the wait was interrupt by a signal
received by this task.  In this case, the semaphore has not be acquired.
</ul>
<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="semtrywait">2.5.7 sem_trywait</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_trywait ( sem_t *sem );
</pre>

<p>
<b>Description:</b> This function locks the specified semaphore
only if the semaphore is currently not locked.  In any event, the call
returns without blocking.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. The semaphore descriptor
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK) or -1 (ERROR) if unsuccessful
</ul>
If <I>sem_wait</I> returns -1 (ERROR) then the cause of the failure
will be indicated by the thread-specific <a href="#ErrnoAccess"><code>errno</code></a>.
The following lists the possible values for <a href="#ErrnoAccess"><code>errno</code></a>:
<p>
<ul>
<li><I>EINVAL</I>:  Indicates that the <I>sem</I> input parameter is
not valid.
<li><I>EAGAIN</I>:  Indicates that the semaphore was not acquired.
</ul>
<p>

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

<H3><a name="sempost">2.5.8 sem_post</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_post ( sem_t *sem );
</pre>

<p>
<b>Description:</b> When a task has finished with a semaphore,
it will call sem_post().  This function unlocks the semaphore referenced
by <I>sem</I> by performing the semaphore unlock operation.
<p>
If the semaphore value resulting from this operation is positive, then
no tasks were blocked waiting for the semaphore to become unlocked;
The semaphore value is simply incremented.
<p>
If the value of the semaphore resulting from this operation is zero, then
on of the tasks blocked waiting for the semaphore will be allowed to
return successfully from its call to <I>sem_wait()</I>.
<p>
<b>NOTE</b>:  <I>sem_post()</I> may be called from an interrupt handler.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. Semaphore descriptor
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK) or -1 (ERROR) if unsuccessful.
</ul>

<p>
<b>Assumptions/Limitations:</b> This function cannot be called
from an interrupt handler. It assumes the currently executing
task is the one that is performing the unlock.
<p>
<b>  POSIX  Compatibility:</b> Comparable to the POSIX
interface of the same name.

<H3><a name="semgetvalue">2.5.9 sem_getvalue</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;semaphore.h&gt;
    int sem_getvalue ( sem_t *sem, int *sval );
</pre>

<p>
<b>Description:</b> This function updates the location referenced
by sval argument to have the value of the semaphore referenced
by sem without effecting the state of the semaphore. The updated
value represents the actual semaphore value that occurred at some
unspecified time during the call, but may not reflect the actual
value of the semaphore when it is returned to the calling task.
<p>
If sem is locked, the value return by sem_getvalue() will either
be zero or a negative number whose absolute value represents the
number of tasks waiting for the semaphore.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>sem</I>. Semaphore descriptor
<li><I>sval</I>. Buffer by which the value is returned
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>0 (OK) or -1 (ERROR) if unsuccessful.
</ul>

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

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="Watchdogs"><h2>2.6 Watchdog Timer Interfaces</h2></a>
  </td>
  </tr>
</table>

<p>
  NuttX provides a general watchdog timer facility.
  This facility allows the NuttX user to specify a watchdog timer function
  that will run after a specified delay.
  The watchdog timer function will run in the context of the timer interrupt handler.
  Because of this, a limited number of NuttX interfaces are available to he watchdog timer function.
  However, the watchdog timer function may use <code>mq_send()</code>, <code>sigqueue()</code>,
  or <code>kill()</code> to communicate with NuttX tasks.
</p>
<ul>
  <li><a href="#wdcreate">2.6.1 wd_create</a></li>
  <li><a href="#wddelete">2.6.2 wd_delete</a></li>
  <li><a href="#wdstart">2.6.3 wd_start</a></li>
  <li><a href="#wdcancel">2.6.4 wd_cancel</a></li>
  <li><a href="#wdgettime">2.6.5 wd_gettime</a></li>
</ul>

<H3><a name="wdcreate">2.6.1 wd_create</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;wdog.h&gt;
    WDOG_ID wd_create (void);
</pre>

<p>
<b>Description:</b> The wd_create function will create a watchdog
by allocating the appropriate resources for the watchdog.
<p>
<b>Input Parameters:</b> None.
<p>
<b>Returned Values:</b> 
<ul>
<li>Pointer to watchdog that may be used as a handle in subsequent
NuttX calls (i.e., the watchdog ID), or NULL if insufficient resources
are available to create the watchdogs.
</ul>

<p>
<b>Assumptions/Limitations:</b> 
<p>
<b>  POSIX  Compatibility:</b> This is a NON-POSIX interface.
VxWorks provides the following comparable interface:
<pre>
    WDOG_ID wdCreate (void);
</pre>

<p>
Differences from the VxWorks interface include:
<ul>
<li>The number of available watchdogs is fixed (configured at
initialization time).
</ul>

<H3><a name="wddelete">2.6.2 wd_delete</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;wdog.h&gt;
    int wd_delete (WDOG_ID wdog);
</pre>

<p>
<b>Description:</b> The wd_delete function will deallocate a
watchdog. The watchdog will be removed from the timer queue if
has been started.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>wdog</I>. The watchdog ID to delete. This is actually a
pointer to a watchdog structure.
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>OK or ERROR
</ul>

<p>
<b>Assumptions/Limitations:</b> It is the responsibility of the
caller to assure that the watchdog is inactive before deleting
it.
<p>
<b>POSIX  Compatibility:</b> This is a NON-POSIX interface.
VxWorks provides the following comparable interface:
<pre>
    STATUS wdDelete (WDOG_ID wdog);
</pre>

<p>
Differences from the VxWorks interface include:
<ul>
<li>Does not make any checks to see if the watchdog is being used
before deallocating it (i.e., never returns ERROR).
</ul>

<H3><a name="wdstart">2.6.3 wd_start</a></H3>

<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;wdog.h&gt;
    int wd_start( WDOG_ID wdog, int delay, wdentry_t wdentry,
                     intt argc, ....);
</pre>

<p>
<b>Description:</b> This function adds a watchdog to the timer
queue. The specified watchdog function will be called from the
interrupt level after the specified number of ticks has elapsed.
Watchdog timers may be started from the interrupt level.
<p>
Watchdog times execute in the context of the timer interrupt handler.
<p>
Watchdog timers execute only once.
<p>
To replace either the timeout delay or the function to be executed,
call wd_start again with the same wdog; only the most recent
wd_start() on a given watchdog ID has any effect.
<p>
<b>Input Parameters:</b> 
<ul>
<li><I>wdog</I>. Watchdog ID
<li><I>delay</I>. Delay count in clock ticks
<li><I>wdentry</I>. Function to call on timeout
<li><I>argc</I>.  The number of uint32_t parameters to pass to wdentry.
<li><I>...</I>. uint32_t size parameters to pass to wdentry
</ul>

<p>
<b>Returned Values:</b> 
<ul>
<li>OK or ERROR
</ul>

<p>
<b>Assumptions/Limitations:</b> The watchdog routine runs in the
context of the timer interrupt handler and is subject to all ISR
restrictions.
<p>
<b>POSIX  Compatibility:</b> This is a NON-POSIX interface.
VxWorks provides the following comparable interface:
<pre>
    STATUS wdStart (WDOG_ID wdog, int delay, FUNCPTR wdentry, int parameter);
</pre>

<p>
Differences from the VxWorks interface include:
<ul>
<li>The present implementation supports multiple parameters passed
to wdentry; VxWorks supports only a single parameter.  The maximum
number of parameters is determined by 
</ul>

<H3><a name="wdcancel">2.6.4 wd_cancel</a></H3>
<p>
<b>Function Prototype:</b> 
<pre>
    #include &lt;wdog.h&gt;
    int wd_cancel (WDOG_ID wdog);
</pre>

<p>
<b>Description:</b> This function cancels a currently running
watchdog timer. Watchdog timers may be canceled from the interrupt
level.
<p>
<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 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>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="ClocksNTimers"><h2>2.7 Clocks and Timers</h2></a>
  </td>
  </tr>
</table>

<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="#gmtime">2.7.5 gmtime</a></li>
  <li><a href="#localtime">2.7.6 localtime</a></li>
  <li><a href="#gmtimer">2.7.7 gmtime_r</a></li>
  <li><a href="#localtimer">2.7.8 localtime_r</a></li>
  <li><a href="#timercreate">2.7.9 timer_create</a></li>
  <li><a href="#timerdelete">2.7.10 timer_delete</a></li>
  <li><a href="#timersettime">2.7.11 timer_settime</a></li>
  <li><a href="#timergettime">2.7.12 timer_gettime</a></li>
  <li><a href="#timergetoverrun">2.7.13 timer_getoverrun</a></li>
  <li><a href="#gettimeofday">2.7.14 gettimeofday</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>To be provided</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>To be provided</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>To be provided</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>To be provided</code>.</li>
</ul>

<H3><a name="gmtime">2.7.5 gmtime</a></H3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;time.h&gt;
    struct tm *gmtime(const time_t *clock);
</pre>
<p>
  <b>Description:</b>
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
  <li><code>clock</code>.
  Represents calendar time.
  This is an absolute time  value representing the number of seconds elapsed since 00:00:00
  on January 1, 1970, Coordinated Universal Time (UTC).
</li>
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>gmtime()</I> function will return the pointer to a statically
  defined instance of <code>struct tim</code>.
  Otherwise, a NULL will be returned to indicate the error:
</p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>

<H3><a name="localtime">2.7.6 localtime</a></H3>
<pre>
    #include &lt;time.h&gt;
    #define localtime(c) gmtime(c)
</pre>

<H3><a name="gmtimer">2.7.7 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>clock</code>.
  Represents calendar time.
  This is an absolute time  value representing the number of seconds elapsed since 00:00:00
  on January 1, 1970, Coordinated Universal Time (UTC).
  <li><code>result</code>.
  A user-provided buffer to receive the converted time structure.
</ul>
<p>
  <b>Returned Values:</b>
</p>
<p>
  If successful, the <I>gmtime_r()</I> function will return the pointer, <code>result</code>,
  provided by the caller.
  Otherwise, a NULL will be returned to indicate the error:
</p>
<ul>
  <li><code>To be provided</code>.</li>
</ul>

<H3><a name="localtimer">2.7.8 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.9 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 <a href="#ErrnoAccess"><code>errno</code></a> 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.10 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
  <a href="#ErrnoAccess"><code>errno</code></a> 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.11 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>. Specify 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 
  <a href="#ErrnoAccess"><code>errno</code></a> 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.12 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.13 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.
</p>

<h3><a name="gettimeofday">2.7.14 gettimeofday</a></h3>
<p>
  <b>Function Prototype:</b>
</p>
<pre>
    #include &lt;sys/time.h&gt;
    int gettimeofday(struct timeval *tp, void *tzp);
</pre>
<p>
  <b>Description:</b>
  This implementation of <code>gettimeofday()</code> is simply a thin wrapper around
  <a href="#clockgettime"><code>clock_gettime()</code></a>.
  It simply calls <code>clock_gettime()</code> using the <code>CLOCK_REALTIME</code> timer and
  converts the result to the required <code>struct timeval</code>.
</p>
<p>
  <b>Input Parameters:</b>
</p>
<ul>
 <li><code>tp</code>. The current time will be returned to this user provided location.</li>
 <li><code>tzp</code>. A reference to the timezone -- <i>IGNORED</i>.</li>
</ul>
<p>
  <b>Returned Values:</b>
  See <a href="#clockgettime"><code>clock_gettime()</code></a>.
</p>

<table width ="100%">
  <tr bgcolor="#e4e4e4">
  <td>
    <a name="Signals"><h2>2.8 Signal Interfaces</h2></a>
  </td>
  </tr>