NuttxUserGuide.html

</PRE>

<P>
<B>Description:</B> This function is used to indicate that the
calling task is finished with the specified message queued mqdes.
The mq_close() deallocates any system resources allocated by the
system for use by this task for its message queue.
<P>
If the calling task has attached a notification request to the message
queue via this <I>mqdes</I> (see mq_notify()), this attachment will be
removed and the message queue is available for another task to attach
for notification.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>mqdes</I>. Message queue descriptor.
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK) if the message queue is closed successfully, otherwise,
-1 (ERROR).
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<UL>
<LI>The behavior of a task that is blocked on either a mq_send() or
mq_receive() is undefined when mq_close() is called.
<LI>The result of using this message queue descriptor after successful
return from mq_close() is undefined.
</UL>
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX interface
of the same name.

<H3>2.4.3 mq_unlink</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;mqueue.h&gt;
    int mq_unlink( const char *mqName );
</PRE>

<P>
<B>Description:</B> This function removes the message queue named
by &quot;mqName.&quot; If one or more tasks have the message queue
open when mq_unlink() is called, removal of the message queue
is postponed until all references to the message queue have been
closed.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>mqName</I>. Name of the message queue
</UL>

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

<H3>2.4.4 mq_send</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;mqueue.h&gt;
    int mq_send( mqd_t mqdes, const void *msg, size_t msgLen, int msgPrio );
</PRE>

<P>
<B>Description:</B> This function adds the specified message (msg)
to the message queue (mqdes). The &quot;msgLen&quot; parameter
specifies the length of the message in bytes pointed to by &quot;msg.&quot;
This length must not exceed the maximum message length from the
mq_getattr().
<P>
If the message queue is not full, mq_send() will in the message
in the message queue at the position indicated by the &quot;msgPrio&quot;
argument. Messages with higher priority will be inserted before
lower priority messages. The value of &quot;msgPrio&quot; must
not exceed MQ_PRIO_MAX.
<P>
If the specified message queue is full and O_NONBLOCK is not
set in the message queue, then mq_send() will block until space
becomes available to the queue the message.
<P>
If the message queue is full and osNON_BLOCK is set, the message
is not queued and ERROR is returned.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>mqdes</I>. Message queue descriptor
<LI><I>msg</I>. Message to send
<LI><I>msgLen</I>. The length of the message in bytes
<LI><I>msgPrio</I>. The priority of the message
</UL>

<P>
<B>Returned Values:</B> None.
<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.
Differences from the full POSIX implementation include:
<UL>
<LI>Control is not returned if a signal is received.
</UL>

<H3>2.4.5 mq_receive</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;mqueue.h&gt;
    int mq_receive( mqd_t mqdes, void *msg, size_t msgLen, int *msgPrio );
</PRE>

<P>
<B>Description:</B> This function receives the oldest of the highest
priority messages from the message queue specified by &quot;mqdes.&quot;
If the size of the buffer in bytes (msgLen) is less than the &quot;mq_msgsize&quot;
attribute of the message queue, mq_receive will return an error.
Otherwise, the select message is removed from the queue and copied
to &quot;msg.&quot;
<P>
If the message queue is empty and O_NONBLOCK was not set, mq_receive()
will block until a message is added to the message queue. If more
than one task is waiting to receive a message, only the task with
the highest priority that has waited the longest will be unblocked.
<P>
If the queue is empty and O_NONBLOCK is set, ERROR will be
returned.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>mqdes</I>. Message Queue Descriptor
<LI><I>msg</I>. Buffer to receive the message
<LI><I>msgLen</I>. Size of the buffer in bytes
<LI><I>msgPrio</I>. If not NULL, the location to store message
priority.
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>Length of the selected message in bytes, otherwise -1 (ERROR).
</UL>

<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX
interface of the same name.
Differences from the full POSIX implementation include:
<UL>
<LI>Control is not returned if a signal is received.
</UL>

<H3>2.4.6 mq_notify</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;mqueue.h&gt;
    int mq_notify( mqd_t mqdes, const struct sigevent *notification );
</PRE>

<P>
<B>Description:</B> If the &quot;notification&quot; input parameter
is not NULL, this function connects the task with the message queue such
that the specified signal will be sent to the task whenever the message
changes from empty to non-empty. One notification can be attached
to a message queue.
<P>
If &quot;notification&quot; is NULL, the attached notification
is detached (if it was held by the calling task) and the queue
is available to attach another notification.
<P>
When the notification is sent to the registered task, its registration
will be removed.  The message queue will then be available for
registration.
<P>
<B>Input Parameters:</B>
<UL>
<LI><I>mqdes</I>. Message queue descriptor
<LI><I>notification</I>. Real-time signal structure containing:
<UL>
<LI><I>sigev_notify</I>. Should be osSIGEV_SIGNAL (but actually
ignored)
<LI><I>sigev_signo</I>. The signo to use for the notification
<LI><I>sigev_value</I>. Value associated with the signal
</UL>

</UL>

<P>
<B>Returned Values:</B> None.
<P>
<B>Assumptions/Limitations:</B> 
<P>
<B>  POSIX  Compatibility:</B> Comparable to the POSIX interface
of the same name.
Differences from the full POSIX implementation include:
<UL>
<LI>The notification signal will be sent to the registered task even if
another task is waiting for the message queue to become non-empty.  This is
inconsistent with the POSIX specification which states, &quot;If a process
has registered for notification of message arrival at a message queue and
some process is blocked in <I>mq_receive</I> waiting to receive a message
when a message arrives at the queue, the arriving message shall satisfy the
appropriate <I>mq_receive()</I> ... The resulting behavior is as if the
message queue remains empty, and no notification shall be sent.&quot;
</UL>

<H3>2.4.7 mq_setattr</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;mqueue.h&gt;
    int mq_setattr( mqd_t mqdes, const struct mq_attr *mqStat,
                     struct mq_attr *oldMqStat);
</PRE>

<P>
<B>Description:</B> This function sets the attributes associated
with the specified message queue &quot;mqdes.&quot; Only the &quot;O_NONBLOCK&quot;
bit of the &quot;mq_flags&quot; can be changed.
<P>
If &quot;oldMqStat&quot; is non-null, mq_setattr() will store
the previous message queue attributes at that location (just as
would have been returned by mq_getattr()).
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>mqdes</I>. Message queue descriptor
<LI><I>mqStat</I>. New attributes
<LI><I>oldMqState</I>. Old attributes
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK) if attributes are set successfully, otherwise -1
(ERROR).
</UL>

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

<H3>2.4.8 mq_getattr</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;mqueue.h&gt;
    int mq_getattr( mqd_t mqdes, struct mq_attr *mqStat);
</PRE>

<P>
<B>Description:</B> This functions gets status information and
attributes associated with the specified message queue.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>mqdes</I>. Message queue descriptor
<LI><I>mqStat</I>. Buffer in which to return attributes. The returned
attributes include:
<UL>
<LI><I>mq_maxmsg</I>. Max number of messages in queue.
<LI><I>mq_msgsize</I>. Max message size.
<LI><I>mq_flags</I>. Queue flags.
<LI><I>mq_curmsgs</I>. Number of messages currently in queue.
</UL>

</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>0 (OK) if attributes provided, -1 (ERROR) otherwise.
</UL>

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

<H2>2.5 <A NAME="Semaphores">Counting Semaphore Interfaces</A></H2>

<P>
<B>Semaphores</B>.  Semaphores are the basis for
synchronization and mutual exclusion in Nuttx. Nuttx supports
POSIX semaphores.
<P>
Semaphores are the preferred mechanism for gaining exclusive access to a
resource.  sched_lock() and sched_unlock() can also be used for this purpose.
However, sched_lock() and sched_unlock() have other undesirable side-affects
in the operation of the system:  sched_lock() also prevents higher-priority
tasks from running that do not depend upon the semaphore-managed resource
and, as a result, can adversely affect system response times.
<P>
<B>Priority Inversion</B>.  Proper use of semaphores avoids the issues of
sched_lock().  However, consider the following example:
<OL>
<LI>Some low-priority task, <I>Task C</I>, acquires a semphore in order to
get exclusive access to a protected resource.
<LI><I>Task C</I> is suspended to allow some high-priority task,
<I>Task A</I>, to execute.
<LI><I>Task A</I> attempts to acquire the semaphore held by <I>Task C</I> and
gets blocked until <I>Task C</I> relinquishes the semaphore.
<LI><I>Task C</I> is allowed to execute again, but gets suspended by some
medium-priority <I>Task B</I>.
</OL>
At this point, the high-priority <I>Task A</I> cannot execute until
<I>Task B</I> (and possibly other medium-priority tasks) completes and until
<I>Task C</I> relinquishes the semaphore.  In effect, the high-priority task,
<I>Task A</I> behaves as though it were lower in priority than the
low-priority task, <I>Task C</I>!  This phenomenon is called <I>priority
inversion</I>.
<P>
Some operating systems avoid priority inversion by <I>automatically</I>
increasing the priority of the low-priority <I>Task C</I> (the operable
buzz-word for this behavior is <I>mutex</I> semaphores).  The Nuttx does not
support this behavior.  As a consequence, it is left to the designer to
provide implementations that will not suffer from priority inversion.
The designer may, as examples:
<UL>
<LI>Implement all tasks that need the semphore-managed resources at the
same priority level,
<LI>Boost the priority of the low-priority task before the semaphore is
acquired, or
<LI>Use sched_lock() in the low-priority task.
</UL>
<P>

<H3>2.5.1 sem_init</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;semaphore.h&gt;
    int sem_init ( sem_t *sem, int pshared, unsigned int value );
</PRE>

<P>
<B>Description:</B> This function initializes the UN-NAMED semaphore
sem. Following a successful call to sem_init(), the semaphore
may be used in subsequent calls to sem_wait(), sem_post(), and
sem_trywait(). The semaphore remains usable until it is destroyed.
<P>
Only <I>sem</I> itself may be used for performing synchronization.  The
result of referring to copies of <I>sem</I> in calls to <I>sem_wait()</I>,
<I>sem_trywait()</I>, <I>sem_post()</I>, and <I>sem_destroy()</I>, is
not defined.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>sem</I>. Semaphore to be initialized
<LI><I>pshared</I>. Process sharing (not used)
<LI><I>value</I>. Semaphore initialization value 
</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.
Differences from the full POSIX implementation include:
<UL>
<LI>pshared is not used.
</UL>

<H3>2.5.2 sem_destroy</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;semaphore.h&gt;
    int sem_destroy ( sem_t *sem );
</PRE>

<P>
<B>Description:</B> This function is used to destroy the un-named semaphore
indicated by <I>sem</I>.  Only a semaphore that was created using
<I>sem_init()</I> may be destroyed using <I>sem_destroy()</I>.  The effect
of calling <I>sem_destroy()</I> with a named semaphore is undefined.  The
effect of subsequent use of the semaphore <I>sem</I> is undefined until
<I>sem</I> is re-initialized by another call to <I>sem_init()</I>.
<P>
The effect of destroying a semaphore upon which other tasks are currently
blocked is undefined.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>sem</I>. Semaphore to be destroyed.
</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.

<H3>2.5.3 sem_open</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;semaphore.h&gt;
    sem_t *sem_open ( const char *name, int oflag, ...);
</PRE>

<P>
<B>Description:</B> This function establishes a connection between
named semaphores and a task. Following a call to sem_open() with
the semaphore name, the task may reference the semaphore associated
with name using the address returned by this call. The semaphore
may be used in subsequent calls to sem_wait(), sem_trywait(),
and sem_post(). The semaphore remains usable until the semaphore
is closed by a successful call to sem_close().
<P>
If a task makes multiple calls to sem_open() with the same name,
then the same semaphore address is returned (provided there have
been no calls to sem_unlink()).
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>name</I>. Semaphore name
<LI><I>oflag</I>. Semaphore creation options. This may one of
the following bit settings:
<UL>
<LI><I>oflag</I> = 0: Connect to the semaphore only if it already
exists.
<LI><I>oflag</I> = O_CREAT: Connect to the semaphore if it exists,
otherwise create the semaphore.
<LI><I>oflag</I> = O_CREAT with O_EXCL (O_CREAT|O_EXCL): Create
a new semaphore unless one of this name already exists.
</UL>
<LI>... Optional parameters.
NOTE:  When the O_CREAT flag is specified, POSIX requires that a third
and fourth parameter be supplied:
<UL>
<LI><I>mode</I>.  The mode parameter is of type mode_t.  
This parameter is required but not used in the present
implementation.
<LI><I>value</I>.  The value parameter is type unsigned int.  The semaphore
is created with an initial value of <I>value</I>.  Valid initial values for
semaphores must be less than or equal to <I>SEM_MAX_VALUE</I>.
</UL>
</UL>

<P>
<B>Returned Values:</B> 
<UL>
<LI>A pointer to sem_t 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.
Differences from the full POSIX implementation include:
<UL>
<LI>Treatment of links/connections is highly simplified. It is
just a counting semaphore.
</UL>

<H3>2.5.4 sem_close</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;semaphore.h&gt;
    int sem_close ( sem_t *sem );
</PRE>

<P>
<B>Description:</B> This function is called to indicate that the
calling task is finished with the specified named semaphore, sem.
The sem_close() deallocates any system resources allocated by
the system for this named semaphore.
<P>
If the semaphore has not been removed with a call to sem_unlink(),
then sem_close() has no effect on the named semaphore. However,
when the named semaphore has been fully unlinked, the semaphore
will vanish when the last task closes it.
<P>
Care must be taken to avoid risking the deletion of a semaphore
that another calling task has already locked.
<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>
<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>2.5.5 sem_unlink</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 oepn 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>2.5.6 sem_wait</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 <I>errno</I> value (a pointer
to this value can be obtained using <I>get_errno_ptr()</I>).  The following
lists the possible values for <I>errno</I>:
<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>2.5.7 sem_trywait</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 <I>errno</I> value (a pointer
to this value can be obtained using <I>get_errno_ptr()</I>).  The following
lists the possible values for <I>errno</I>:
<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>2.5.8 sem_post</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>2.5.9 sem_getvalue</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.

<HR>

<H2>2.6 <A NAME="Watchdogs">Watchdog Timer Interfaces</A></H2>

<P>
The 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
the watchdog timer function. However, the watchdog timer function
may use mq_send(), and sigqueue() to communicate with Nuttx tasks.

<H3>2.6.1 wd_create</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>2.6.2 wd_delete</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;wdog.h&gt;
    STATUS wd_delete (WDOG_ID wdId);
</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>wdId</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 wdId);
</PRE>

<P>
Differences from the VxWorks interface include:
<UL>
<LI>Does not make any checks to see if the watchdog is being used
before de-allocating it (i.e., never returns ERROR).
</UL>

<H3>2.6.3 wd_start</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;wdog.h&gt;
    STATUS wd_start( WDOG_ID wdId, int delay, wdentry_t wdentry,
                     int parm1, int parm2, int parm3, int parm4 );
</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, but
with the PIC/PID address environment that was in place when wd_start()
was called.
<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 wdId; only the most recent
wd_start() on a given watchdog ID has any effect.
<P>
<B>Input Parameters:</B> 
<UL>
<LI><I>wdId</I>. Watchdog ID
<LI><I>delay</I>. Delay count in clock ticks
<LI><I>wdentry</I>. Function to call on timeout
<LI><I>parm1..4</I>. 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 wdId, int delay, FUNCPTR wdentry, int parameter);
</PRE>

<P>
Differences from the VxWorks interface include:
<UL>
<LI>The present implementation supports four parameters passed
to wdentry; VxWorks supports only a single parameter.
</UL>

<H3>2.6.4 wd_cancel</H3>

<P>
<B>Function Prototype:</B> 
<PRE>
    #include &lt;wdog.h&gt;
    STATUS wd_cancel (WDOG_ID wdId);
</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>wdId</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 wdId);
</PRE>

<HR>

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

<P>
The 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>
Signal handlers execute in the context of the task that registered
the signal handler.
<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.
<P>
Tasks may also suspend themselves and wait until a signal is received.

<H3>2.7.1 sigemptyset</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>2.7.2 sigfillset</H3>

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