354501be05
git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@114 42af7a65-404d-4744-a932-0658087f49c3
5003 lines
142 KiB
HTML
5003 lines
142 KiB
HTML
<HTML>
|
|
|
|
<HEAD>
|
|
<TITLE>NuttX Users Manual</TITLE>
|
|
<META NAME="AUTHOR" CONTENT="Gregory Nutt">
|
|
</HEAD>
|
|
|
|
<body background="backgd.gif">
|
|
<hr>
|
|
<hr>
|
|
<center><h1><i>Under Construction</i></h1></center>
|
|
<hr>
|
|
<hr>
|
|
<CENTER><BIG><B>
|
|
NuttX Operating System
|
|
<P>
|
|
User's Manual
|
|
</B></BIG>
|
|
<P>
|
|
<SMALL>by</SMALL>
|
|
<P>
|
|
Gregory Nutt
|
|
<P>
|
|
<SMALL>Last Update: March 21, 2007</SMALL>
|
|
</CENTER>
|
|
|
|
<H1>1.0 <A NAME="Introduction">Introduction</A></H1>
|
|
|
|
<P>
|
|
This user's manual is divided into three sections plus a index:
|
|
<UL>
|
|
<LI><B>Section 1.0, <A HREF="#Introduction">Introduction</A></B>:
|
|
This section provides an overview of the NuttX user's manual.
|
|
<LI><B>Section 2.0, <A HREF="#OS_Interfaces">OS Interfaces</A></B>:
|
|
This section details the interfaces provided by NuttX from the
|
|
perspective of the firmware developer. This section is divided
|
|
into several paragraphs that describe different groups of OS interfaces:
|
|
<UL>
|
|
<LI>Paragraph 2.1 <A HREF="#Task_Control">Task Control Interfaces</A>
|
|
<LI>Paragraph 2.2 <A HREF="#Task_Schedule">Task Scheduling Interfaces</A>
|
|
<LI>Paragraph 2.3 <A HREF="#Task_Switch">Task Switching Interfaces</A>
|
|
<LI>Paragraph 2.4 <A HREF="#Message_Queue">Named Message Queue Interfaces</A>
|
|
<LI>Paragraph 2.5 <A HREF="#Semaphores">Counting Semaphore Interfaces</A>
|
|
<LI>Paragraph 2.6 <A HREF="#Watchdogs">Watchdog Timer Interfaces</A>
|
|
<LI>Paragraph 2.7 <A HREF="#ClocksNTimers">Clocks and Timers</A>
|
|
<LI>Paragraph 2.8 <A HREF="#Signals">Signal Interfaces</A>
|
|
<LI>Paragraph 2.9 <A HREF="#Pthread">Pthread Interfaces</A>
|
|
<LI>Paragraph 2.10 <A HREF="#FileSystem">Filesystem Interfaces</A>
|
|
</UL>
|
|
<LI><B>Section 3.0, <A HREF="#Data_Structures">OS Data Structures</A></B>:
|
|
This section documents the data structures that are used at the NuttX
|
|
interface.
|
|
<li><a href="#index">Index</a></li>
|
|
</ul>
|
|
<HR>
|
|
|
|
<H1>2.0 <A NAME="OS_Interfaces">OS Interfaces</A></H1>
|
|
|
|
<P>
|
|
This section describes each C-callable interface to the NuttX
|
|
Operating System. The description of each interface is presented
|
|
in the following format:
|
|
<P>
|
|
<B>Function Prototype:</B> The C prototype of the interface function
|
|
is provided.
|
|
<P>
|
|
<B>Description:</B> The operation performed by the interface function
|
|
is discussed.
|
|
<P>
|
|
<B>Input Parameters:</B> All input parameters are listed along
|
|
with brief descriptions of each input parameter.
|
|
<P>
|
|
<B>Returned Values:</B> All possible values returned by the interface
|
|
function are listed. Values returned as side-effects (through
|
|
pointer input parameters or through global variables) will be
|
|
addressed in the description of the interface function.
|
|
<P>
|
|
<B>Assumptions/Limitations:</B> Any unusual assumptions made by
|
|
the interface function or any non-obvious limitations to the use
|
|
of the interface function will be indicated here.
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Any significant differences between the
|
|
NuttX interface and its corresponding POSIX interface will be noted
|
|
here.
|
|
<P>
|
|
NOTE: In order to achieve an independent name space for the NuttX
|
|
interface functions, differences in function names and types are
|
|
to be expected and will not be identified as differences in these
|
|
paragraphs.
|
|
<HR>
|
|
|
|
<H2>2.1 <A NAME="Task_Control">Task Control Interfaces</A></H2>
|
|
|
|
<p>
|
|
<b>Tasks</b>.
|
|
NuttX is a flat address OS. As such it does not support "processes"
|
|
in the way that, say, Linux does.
|
|
NuttX only supports simple threads running within the same address space.
|
|
However, the programming model makes a distinction between "tasks"
|
|
and pthreads:
|
|
</p>
|
|
<ul>
|
|
<li><i>tasks</i> are threads which have a degree of independence
|
|
<li><a href="#Pthread"><i>pthreads</i></a> share some resources.
|
|
</ul>
|
|
<p>
|
|
<b>File Descriptors and Streams</b>.
|
|
This applies, in particular, in the area of opened file descriptors and streams.
|
|
When a task is started using the interfaces in this section, it will be created
|
|
with at most three open files.
|
|
</p>
|
|
</p>
|
|
If CONFIG_DEV_CONSOLE is defined, the first three file descriptors (corresponding
|
|
to stdin, stdout, stderr) will be duplicated for the the new task.
|
|
Since these file descriptors are duplicated, the child task can free close
|
|
them or manipulate them in any way without effecting the parent task.
|
|
File-related operations (open, close, etc.) within a task will have no effect
|
|
on other tasks.
|
|
Since the three file descriptors are duplicated, it is also possible to perform
|
|
some level of redirection.
|
|
</p>
|
|
<p>
|
|
pthreads, on the other hand, will always share file descriptors with the parent
|
|
thread. In this case, file operations will have effect only all pthreads the
|
|
were started from the same parent thread.
|
|
</p>
|
|
<p>
|
|
The following task control interfaces are provided by Nuttx:
|
|
</p>
|
|
<ul>
|
|
<li><a href="#taskcreate">2.1.1 task_create</a></li>
|
|
<li><a href="#taskinit">2.1.2 task_init</a></li>
|
|
<li><a href="#taskactivate">2.1.3 task_activate</a></li>
|
|
<li><a href="#taskdelete">2.1.4 task_delete</a></li>
|
|
<li><a href="#exit">2.1.5 exit</a></li>
|
|
<li><a href="#taskrestart">2.1.6 task_restart</a></li>
|
|
<li><a href="#getpid">2.1.7 getpid</a></li>
|
|
</ul>
|
|
|
|
<H3><a name="taskcreate">2.1.1 task_create</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int task_create(char *name, int priority, int stack_size, main_t entry, const char *argv[]);
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B>
|
|
This function creates and activates a new task with a
|
|
specified priority and returns its system-assigned ID.
|
|
</p>
|
|
|
|
<P>The entry address entry is the address of the "main"
|
|
function of the task.
|
|
This function will be called once the C environment has been set up.
|
|
The specified function will be called with four arguments.
|
|
Should the specified routine return, a call to exit() will automatically be made.
|
|
</P>
|
|
<p>
|
|
Note that an arbitrary number of arguments may be passed to the
|
|
spawned functions. The maximum umber of arguments is an OS
|
|
configuration parameter (<code>CONFIG_MAX_TASK_ARGS</code>).
|
|
</p>
|
|
<p>
|
|
The arguments are copied (via <code>strdup</code>) so that the
|
|
life of the passed strings is not dependent on the life of the
|
|
caller to <code>task_create()</code>.
|
|
</p>
|
|
<p>
|
|
The newly created task does not inherit scheduler characteristics
|
|
from the parent task: The new task is started at the
|
|
default system priority and with the SCHED_FIFO scheduling
|
|
policy. These characteristcs may be modified after the new
|
|
task has been started.
|
|
</p>
|
|
<p>
|
|
The newly created task does inherit the first three file
|
|
descriptors (corresponding to stdin, stdout, and stderr) and
|
|
redirection of standard I/O is supported.
|
|
</p>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>name</I>. Name of the new task</LI>
|
|
<LI><I>priority</I>. Priority of the new task</LI>
|
|
<LI><I>stack_size</I>. size (in bytes) of the stack needed</LI>
|
|
<LI><I>entry</I>. Entry point of a new task</LI>
|
|
<LI><I>argv</I>. A pointer to an array of input parameters. Up to
|
|
<code>CONFIG_MAX_TASK_ARG</code> parameters may be provided.
|
|
If fewer than <code>CONFIG_MAX_TASK_ARG</code> parameters are
|
|
passed, the list should be terminated with a NULL argv[] value.
|
|
If no parameters are required, argv may be NULL.
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
</P>
|
|
<UL>
|
|
<LI>
|
|
Returns the non-zero task ID of the new task or
|
|
ERROR if memory is insufficient or the task cannot be
|
|
created (errno is not set).
|
|
</LI>
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> This is a NON-POSIX interface.
|
|
VxWorks provides the following similar interface:
|
|
<PRE>
|
|
int taskSpawn(char *name, int priority, int options, int stackSize, FUNCPTR entryPt,
|
|
int arg1, int arg2, int arg3, int arg4, int arg5,
|
|
int arg6, int arg7, int arg8, int arg9, int arg10);
|
|
</PRE>
|
|
|
|
<P>
|
|
The NuttX task_create() differs from VxWorks' taskSpawn() in the
|
|
following ways:
|
|
</p>
|
|
<UL>
|
|
<LI>Interface name
|
|
<LI>Various differences in types of arguments
|
|
<LI>There is no options arguement.
|
|
<LI>A variable number of parameters can be passed to a task (VxWorks supports ten).
|
|
</UL>
|
|
|
|
<H3><a name="taskinit">2.1.2 task_init</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
STATUS task_init(_TCB *tcb, char *name, int priority, uint32 *stack, uint32 stack_size,
|
|
maint_t entry, const char *argv[]);
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
This function initializes a Task Control Block (TCB)
|
|
in preparation for starting a new thread. It performs a subset
|
|
of the functionality of <code>task_create()</code> (see above).
|
|
</P>
|
|
<P>
|
|
Unlike task_create(), task_init() does not activate the task.
|
|
This must be done by calling task_activate().
|
|
</P>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>tcb</I>. Address of the new task's TCB
|
|
<LI><I>name</I>. Name of the new task (not used)
|
|
<LI><I>priority</I>. Priority of the new task
|
|
<LI><I>stack</I>. Start of the pre-allocated stack
|
|
<LI><I>stack_size</I>. size (in bytes) of the pre-allocated stack
|
|
<LI><I>entry</I>. Entry point of a new task
|
|
<LI><I>argv</I>. A pointer to an array of input parameters. Up to
|
|
<code>CONFIG_MAX_TASK_ARG</code> parameters may be provided.
|
|
If fewer than <code>CONFIG_MAX_TASK_ARG</code> parameters are
|
|
passed, the list should be terminated with a NULL argv[] value.
|
|
If no parameters are required, argv may be NULL.
|
|
</UL>
|
|
</p>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
</p>
|
|
<UL>
|
|
<LI><P>OK, or ERROR if the task cannot be initialized.</P>
|
|
<P>This function can only failure is it is unable to assign
|
|
a new, unique task ID to the TCB (errno is not set).</P>
|
|
</UL>
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<UL>
|
|
<LI>task_init() is provided to support internal OS functionality. It is
|
|
<B>not recommended</B> for normal usage. task_create() is the preferred
|
|
mechanism to initialize and start a new task.
|
|
</UL>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> This is a NON-POSIX interface.
|
|
VxWorks provides the following similar interface:
|
|
<PRE>
|
|
STATUS taskInit(WIND_TCB *pTcb, char *name, int priority, int options, uint32 *pStackBase, int stackSize,
|
|
FUNCPTR entryPt, int arg1, int arg2, int arg3, int arg4, int arg5,
|
|
int arg6, int arg7, int arg8, int arg9, int arg10);
|
|
</PRE>
|
|
|
|
<P>
|
|
The NuttX task_init() differs from VxWorks' taskInit() in the
|
|
following ways:
|
|
</p>
|
|
<UL>
|
|
<LI>Interface name
|
|
<LI>Various differences in types or arguments
|
|
<LI>There is no options argument.
|
|
<LI>A variable number of parameters can be passed to a task (VxWorks supports ten).
|
|
</UL>
|
|
|
|
<H3><a name="taskactivate">2.1.3 task_activate</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
STATUS task_activate( _TCB *tcb );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function activates tasks created by task_init().
|
|
Without activation, a task is ineligible for execution by the
|
|
scheduler.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>tcb</I>. The TCB for the task for the task (same as the
|
|
task_init argument).
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>OK, or ERROR if the task cannot be activated (errno is not set).
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<UL>
|
|
<LI>task_activate() is provided to support internal OS functionality. It is
|
|
<B>not recommended</B> for normal usage. task_create() is the preferred
|
|
mechanism to initialize and start a new task.
|
|
</UL>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> This is a NON-POSIX interface.
|
|
VxWorks provides the following similar interface:
|
|
<PRE>
|
|
STATUS taskActivate( int tid );
|
|
</PRE>
|
|
|
|
<P>
|
|
The NuttX task_activate() differs from VxWorks' taskActivate() in the
|
|
following ways:
|
|
</p>
|
|
<UL>
|
|
<LI>Function name
|
|
<LI>With VxWork's taskActivate, the pid argument is supposed to be
|
|
the pointer to the WIND_TCB cast to an integer.
|
|
</UL>
|
|
|
|
<H3><a name="taskdelete">2.1.4 task_delete</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
STATUS task_delete( pid_t pid );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function causes a specified task to cease
|
|
to exist -- its stack and TCB will be deallocated. This function
|
|
is the companion to task_create().
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>pid</I>. The task ID of the task to delete. An ID of
|
|
zero signifies the calling task.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>OK, or ERROR if the task cannot be deleted.
|
|
This function can fail if the provided pid does not correspond to a task (errno is not set)
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
task_delete() must be used with caution: If the task holds resources
|
|
(for example, allocated memory or semaphores needed by other tasks), then
|
|
task_delete() can strand those resources.
|
|
<P>
|
|
<B>POSIX Compatibility:</B> This is a NON-POSIX interface.
|
|
VxWorks provides the following similar interface:
|
|
<PRE>
|
|
STATUS taskDelete( int tid );
|
|
</PRE>
|
|
|
|
<P>
|
|
The NuttX task_delete() differs from VxWorks' taskDelete() in
|
|
the following ways:
|
|
</p>
|
|
<UL>
|
|
<LI>No support is provided for calling the tasks deletion routines
|
|
(because taskDeleteHookAdd() is not supported).
|
|
<LI>Deletion of self is not supported. Use _exit();
|
|
</UL>
|
|
|
|
<H3><a name="exit">2.1.5 exit</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
void exit( int code );
|
|
|
|
#include <nuttx/unistd.h>
|
|
void _exit( int code );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function causes the calling task to cease
|
|
to exist -- its stack and TCB will be deallocated. exit differs from
|
|
_exit in that it flushs streams, closes file descriptors and will
|
|
execute any function registered with atexit().
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>code</I>. (ignored)
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B> None.
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
|
|
<P>
|
|
<B>POSIX Compatibility:</B> This is equivalent to the ANSI interface:
|
|
<PRE>
|
|
void exit( int code );
|
|
</PRE>
|
|
And the unix interface:
|
|
<PRE>
|
|
void _exit( int code );
|
|
</PRE>
|
|
|
|
<P>
|
|
The NuttX exit() differs from ANSI exit() in the following ways:
|
|
</p>
|
|
<UL>
|
|
<LI>The <I>code</I> parameter is ignored.
|
|
</UL>
|
|
|
|
<H3><a name="taskrestart">2.1.6 task_restart</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
STATUS task_restart( pid_t pid );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function "restarts" a task.
|
|
The task is first terminated and then reinitialized with same
|
|
ID, priority, original entry point, stack size, and parameters
|
|
it had when it was first started.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>pid</I>. The task ID of the task to delete. An ID of
|
|
zero signifies the calling task.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>
|
|
OK, or ERROR if the task ID is invalid or the task could
|
|
not be restarted.
|
|
This function can fail if:
|
|
(1) A pid of zero or the pid of the calling task is provided (functionality not implemented)
|
|
(2) The pid is not associated with any task known to the system.
|
|
</LI>
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> This is a NON-POSIX interface.
|
|
VxWorks provides the following similar interface:
|
|
<PRE>
|
|
STATUS taskRestart (int tid);
|
|
</PRE>
|
|
|
|
<P>
|
|
The NuttX task_restart() differs from VxWorks' taskRestart() in the following ways:
|
|
</p>
|
|
<UL>
|
|
<LI>Restart of the currently running task is not supported.
|
|
<LI>The VxWorks description says that the ID, priority, etc. take
|
|
the value that they had when the task was <I>terminated</I>.
|
|
</UL>
|
|
|
|
<H3><a name="getpid">2.1.7 getpid</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <unistd.h>
|
|
pid_t getpid( void );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function returns the task ID of the
|
|
calling task. The task ID will be invalid if called at the interrupt
|
|
level.
|
|
<P>
|
|
<B>Input Parameters:</B> None.
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>The task ID of the calling task.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B>
|
|
Compatible with the POSIX interface of the same name.
|
|
|
|
<H2>2.2 <A NAME="Task_Schedule">Task Scheduling Interfaces</A></H2>
|
|
|
|
<p>
|
|
By default, NuttX performs strict priority scheduling: Tasks of higher
|
|
priority have exclusive access to the CPU until they become blocked.
|
|
At that time, the CPU is available to tasks of lower priority.
|
|
Tasks of equal priority are scheduled FIFO.
|
|
</p>
|
|
<p>
|
|
Optionally, a Nuttx task or thread can be configured with round-robin
|
|
scheduler. This is similar to priority scheduling <i>except</i> that
|
|
tasks with equal priority and share CPU time via <i>time-slicing</i>.
|
|
The time-slice interval is a constant determined by the configuration
|
|
setting <code>CONFIG_RR_INTERVAL</code>.
|
|
</p>
|
|
<p>
|
|
The OS interfaces described in the following paragraphs provide
|
|
a POSIX- compliant interface to the NuttX scheduler:
|
|
</p>
|
|
<ul>
|
|
<li><a href="#schedsetparam">2.2.1 sched_setparam</a></li>
|
|
<li><a href="#schedgetparam">2.2.2 sched_getparam</a></li>
|
|
<li><a href="#schedsetscheduler">2.2.3 sched_setscheduler</a></li>
|
|
<li><a href="#setgetscheduler">2.2.4 sched_getscheduler</a></li>
|
|
<li><a href="#sched_yield">2.2.5 sched_yield</a></li>
|
|
<li><a href="#schedgetprioritymax">2.2.6 sched_get_priority_max</a></li>
|
|
<li><a href="#schedgetprioritymin">2.2.7 sched_get_priority_min</a></li>
|
|
<li><a href="#schedgetrrinterval">2.2.8 sched_get_rr_interval</a></li>
|
|
</ul>
|
|
|
|
<H3><a name="schedsetparam">2.2.1 sched_setparam</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_setparam( pid_t pid, const struct sched_param *param );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function sets the priority of the task
|
|
specified by pid input parameter.
|
|
<P>
|
|
NOTE: Setting a task's priority to the same value has the similar
|
|
effect to sched_yield() -- The task will be moved to after all
|
|
other tasks with the same priority.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>pid</I>. The task ID of the task. If pid is zero, the
|
|
priority of the calling task is set.
|
|
<LI><I>param</I>. A structure whose member sched_priority is the
|
|
integer priority. The range of valid priority numbers is from
|
|
SCHED_PRIORITY_MIN through SCHED_PRIORITY_MAX.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>
|
|
0 (OK) if successful, otherwise -1 (ERROR).
|
|
This function can fail for the following reasons:
|
|
(1) parm is NULL or parm->sched_priority is out of range.
|
|
(2) pid does not correspond to any task.
|
|
</LI>
|
|
</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>The range of priority values for the POSIX call is 0 to 255
|
|
</UL>
|
|
|
|
<H3><a name="schedgetparam">2.2.2 sched_getparam</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_getparam (pid_t pid, struct sched_param *param);
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function gets the scheduling priority
|
|
of the task specified by pid.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>pid</I>. The task ID of the task. If pid is zero, the
|
|
priority of the calling task is returned.
|
|
<LI><I>param</I>. A structure whose member sched_priority is the
|
|
integer priority. The task's priority is copied to the sched_priority
|
|
element of this structure.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>0 (OK) if successful, otherwise -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="schedsetscheduler">2.2.3 sched_setscheduler</a></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_setscheduler (pid_t pid, int policy, const struct sched_param *param);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<i>sched_setscheduler()</i> sets both the scheduling policy
|
|
and the priority for the task identified by pid.
|
|
If pid equals zero, the scheduler of the calling
|
|
thread will be set.
|
|
The parameter 'param' holds the priority of the thread under the new policy.
|
|
</p>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>pid</I>. The task ID of the task. If pid is zero, the
|
|
priority of the calling task is set.
|
|
<LI><I>policy</I>. Scheduling policy requested (either SCHED_FIFO
|
|
or SCHED_RR).
|
|
<LI><I>param</I>. A structure whose member sched_priority is the
|
|
integer priority. The range of valid priority numbers is from
|
|
SCHED_PRIORITY_MIN through SCHED_PRIORITY_MAX.
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
On success, <i>sched_setscheduler()</i> returns OK (zero). On
|
|
error, ERROR (-1) is returned, and errno is set appropriately:
|
|
</p>
|
|
<ul>
|
|
<li>EINVAL The scheduling policy is not one of the
|
|
recognized policies.</li>
|
|
<li>ESRCH The task whose ID is pid could not be found.</li>
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B> POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="setgetscheduler">2.2.4 sched_getscheduler</a></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_getscheduler (pid_t pid);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<i>sched_getscheduler()</i> returns the scheduling policy
|
|
currently applied to the task identified by pid. If
|
|
pid equals zero, the policy of the calling process will
|
|
be retrieved.
|
|
*
|
|
* Inputs:
|
|
*
|
|
* Return Value:
|
|
|
|
This function returns the current scheduling
|
|
policy.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>pid</I>.
|
|
The task ID of the task to query.
|
|
If pid is zero, the calling task is queried.
|
|
</LI>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>
|
|
On success, <i>sched_getscheduler()</i> returns the policy for
|
|
the task (either SCHED_FIFO or SCHED_RR).
|
|
On error, ERROR (-1) is returned, and errno is set appropriately:
|
|
<ul>
|
|
<li>ESRCH The task whose ID is pid could not be found.</li>
|
|
</ul>
|
|
</li>
|
|
</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>Does not report errors via <I>errno</I>.
|
|
</UL>
|
|
|
|
<H3><a name="sched_yield">2.2.5 sched_yield</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_yield( void );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function forces the calling task to give
|
|
up the CPU (only to other tasks at the same priority).
|
|
<P>
|
|
<B>Input Parameters:</B> None.
|
|
<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="schedgetprioritymax">2.2.6 sched_get_priority_max</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_get_priority_max (int policy)
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function returns the value of the highest
|
|
possible task priority for a specified scheduling policy.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>policy</I>. Scheduling policy requested.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>The maximum priority value 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="schedgetprioritymin">2.2.7 sched_get_priority_min</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_get_priority_min (int policy);
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function returns the value of the lowest
|
|
possible task priority for a specified scheduling policy.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>policy</I>. Scheduling policy requested.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>The minimum priority value 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="schedgetrrinterval">2.2.8 sched_get_rr_interval</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
int sched_get_rr_interval (pid_t pid, struct timespec *interval);
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B>
|
|
<i>sched_rr_get_interval()</i> writes the timeslice interval
|
|
for task identified by <i>pid</i> into the timespec structure
|
|
pointed to by <i>interval</i>. If pid is zero, the timeslice
|
|
for the calling process is written into 'interval. The
|
|
identified process should be running under the SCHED_RR
|
|
scheduling policy.'
|
|
</p>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
</p>
|
|
<UL>
|
|
<LI><I>pid</I>. The task ID of the task. If pid is zero, the
|
|
priority of the calling task is returned.
|
|
<LI><I>interval</I>. A structure used to return the time slice.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
On success, sched_rr_get_interval() returns OK (0). On
|
|
error, ERROR (-1) is returned, and errno is set to:
|
|
</p>
|
|
<UL>
|
|
<LI>EFAULT Cannot copy to interval</LI>
|
|
<LI>EINVAL Invalid pid.</LI>
|
|
<LI>ENOSYS The system call is not yet implemented.</LI>
|
|
<LI>ESRCH The process whose ID is pid could not be found.</LI>
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
</P>
|
|
|
|
<H2>2.3 <A NAME="Task_Switch">Task Switching Interfaces</A></H2>
|
|
|
|
<ul>
|
|
<li><a href="#schedlock">2.3.1 sched_lock</a></li>
|
|
<li><a href="#schedunlock">2.3.2 sched_unlock</a></li>
|
|
<li><a href="#schedlockcount">2.3.3 sched_lockcount</a></li>
|
|
</ul>
|
|
|
|
<H3><a name="schedlock">2.3.1 sched_lock</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
STATUS sched_lock( void );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function disables context switching by
|
|
Disabling addition of new tasks to the ready-to-run task list.
|
|
The task that calls this function will be the only task that is
|
|
allowed to run until it either calls sched_unlock (the appropriate
|
|
number of times) or until it blocks itself.
|
|
<P>
|
|
<B>Input Parameters:</B> None.
|
|
<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 comparable interface:
|
|
<PRE>
|
|
STATUS taskLock( void );
|
|
</PRE>
|
|
|
|
<H3><a name="schedunlock">2.3.2 sched_unlock</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
STATUS sched_unlock( void );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function decrements the preemption lock
|
|
count. Typically this is paired with sched_lock() and concludes
|
|
a critical section of code. Preemption will not be unlocked until
|
|
sched_unlock() has been called as many times as sched_lock().
|
|
When the lockCount is decremented to zero, any tasks that were
|
|
eligible to preempt the current task will execute.
|
|
<P>
|
|
<B>Input Parameters:</B> None.
|
|
<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 comparable interface:
|
|
<PRE>
|
|
STATUS taskUnlock( void );
|
|
</PRE>
|
|
|
|
<H3><a name="schedlockcount">2.3.3 sched_lockcount</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sched.h>
|
|
sint32 sched_lockcount( void )
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function returns the current value of
|
|
the lockCount. If zero, preemption is enabled; if non-zero, this
|
|
value indicates the number of times that sched_lock() has been called
|
|
on this thread of execution.
|
|
<P>
|
|
<B>Input Parameters:</B> None.
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>The current value of the lockCount.
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B> POSIX Compatibility:</B> None.
|
|
<HR>
|
|
|
|
<H2>2.4 <A NAME="Message_Queue">Named Message Queue Interfaces</A></H2>
|
|
|
|
<p>
|
|
NuttX supports POSIX named message queues for intertask communication.
|
|
Any task may send or receive messages on named message queues.
|
|
Interrupt handlers may send messages via named message queues.
|
|
</p>
|
|
<ul>
|
|
<li><a href="#mqopen">2.4.1 mq_open</a></li>
|
|
<li><a href="#mqclose">2.4.2 mq_close</a></li>
|
|
<li><a href="#mqunlink">2.4.3 mq_unlink</a></li>
|
|
<li><a href="#mqsend">2.4.4 mq_send</a></li>
|
|
<li><a href="#mqreceive">2.4.5 mq_receive</a></li>
|
|
<li><a href="#mqnotify">2.4.6 mq_notify</a></li>
|
|
<li><a href="#mqsetattr">2.4.7 mq_setattr</a></li>
|
|
<li><a href="#mqgetattr">2.4.8 mq_getattr</a></li>
|
|
</ul>
|
|
|
|
<H3><a name="mqopen">2.4.1 mq_open</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
mqd_t mq_open( const char *mqName, int oflags, ... );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function establish a connection between
|
|
a named message queue and the calling task. After a successful
|
|
call of mq_open(), the task can reference the message queue using
|
|
the address returned by the call. The message queue remains usable
|
|
until it is closed by a successful call to mq_close().
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>mqName</I>. Name of the queue to open
|
|
<LI><I>oflags</I>. Open flags. These may be any combination of:
|
|
<UL>
|
|
<LI><I>O_RDONLY</I>. Open for read access.
|
|
<LI><I>O_WRONLY</I>. Open for write access.
|
|
<LI><I>O_RDWR</I>. Open for both read & write access.
|
|
<LI><I>O_CREAT</I>. Create message queue if it does not already
|
|
exist.
|
|
<LI><I>O_EXCL</I>. Name must not exist when opened.
|
|
<LI><I>O_NONBLOCK</I>. Don't wait for data.
|
|
</UL>
|
|
|
|
<LI><I>... Optional parameters</I>.
|
|
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. In the POSIX
|
|
specification, this mode value provides file permission bits for the
|
|
message queue. This parameter is required but not used in the present
|
|
implementation.
|
|
<LI><I>attr</I>. A pointer to an mq_attr that is provided to initialize.
|
|
the message queue. If attr is NULL, then the messages queue is created
|
|
with implementation-defined default message queue attributes. If attr is
|
|
non-NULL, then the message queue mq_maxmsg attribute is set to the
|
|
corresponding value when the queue is created. The mq_maxmsg attribute
|
|
determines the maximum number of messages that can be queued before
|
|
addition attempts to send messages on the message queue fail or cause the
|
|
sender to block; the mq_msgsize attribute determines the maximum size of a
|
|
message that can be sent or received. Other elements of attr are ignored
|
|
(i.e, set to default message queue attributes).
|
|
</UL>
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>A message queue descriptor or -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>The mq_msgsize attributes determines the maximum size of a message that
|
|
may be sent or received. In the present implementation, this maximum
|
|
message size is limited at 22 bytes.
|
|
</UL>
|
|
|
|
<H3><a name="mqclose">2.4.2 mq_close</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
int mq_close( mqd_t mqdes );
|
|
</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><a name="mqunlink">2.4.3 mq_unlink</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
int mq_unlink( const char *mqName );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function removes the message queue named
|
|
by "mqName." 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><a name="mqsend">2.4.4 mq_send</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
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 "msgLen" parameter
|
|
specifies the length of the message in bytes pointed to by "msg."
|
|
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 "msgPrio"
|
|
argument. Messages with higher priority will be inserted before
|
|
lower priority messages. The value of "msgPrio" 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><a name="mqreceive">2.4.5 mq_receive</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
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 "mqdes."
|
|
If the size of the buffer in bytes (msgLen) is less than the "mq_msgsize"
|
|
attribute of the message queue, mq_receive will return an error.
|
|
Otherwise, the select message is removed from the queue and copied
|
|
to "msg."
|
|
<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><a name="mqnotify">2.4.6 mq_notify</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
int mq_notify( mqd_t mqdes, const struct sigevent *notification );
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> If the "notification" 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 "notification" 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, "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."
|
|
</UL>
|
|
|
|
<H3><a name="mqsetattr">2.4.7 mq_setattr</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
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 "mqdes." Only the "O_NONBLOCK"
|
|
bit of the "mq_flags" can be changed.
|
|
<P>
|
|
If "oldMqStat" 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><a name="mqgetattr">2.4.8 mq_getattr</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <mqueue.h>
|
|
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>
|
|
<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>
|
|
<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>
|
|
<LI><I>Task C</I> is suspended to allow some high-priority task,</li>
|
|
<I>Task A</I>, to execute.</li>
|
|
<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>
|
|
<LI><I>Task C</I> is allowed to execute again, but gets suspended by some
|
|
medium-priority <I>Task B</I>.</li>
|
|
</OL>
|
|
<p>
|
|
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>
|
|
<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>priority inheritance</I>). 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:
|
|
</p>
|
|
<UL>
|
|
<LI>Implement all tasks that need the semphore-managed resources at the
|
|
same priority level,</li>
|
|
<LI>Boost the priority of the low-priority task before the semaphore is
|
|
acquired, or</li>
|
|
<LI>Use sched_lock() in the low-priority task.</li>
|
|
</UL>
|
|
<p>
|
|
POSIX semaphore interfaces:
|
|
</p>
|
|
<ul>
|
|
<li><a href="#seminit">2.5.1 sem_init</a></li>
|
|
<li><a href="#semdestroy">2.5.2 sem_destroy</a></li>
|
|
<li><a href="#semopen">2.5.3 sem_open</a></li>
|
|
<li><a href="#semclose">2.5.4 sem_close</a></li>
|
|
<li><a href="#semunlink">2.5.5 sem_unlink</a></li>
|
|
<li><a href="#semwait">2.5.6 sem_wait</a></li>
|
|
<li><a href="#semtrywait">2.5.7 sem_trywait</a></li>
|
|
<li><a href="#sempost">2.5.8 sem_post</a></li>
|
|
<li><a href="#semgetvalue">2.5.9 sem_getvalue</a></li>
|
|
</ul>
|
|
|
|
<H3><a name="seminit">2.5.1 sem_init</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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><a name="semdestroy">2.5.2 sem_destroy</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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><a name="semopen">2.5.3 sem_open</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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_VALUE_MAX</I> (defined in
|
|
<CODE>include/limits.h</CODE>).
|
|
</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><a name="semclose">2.5.4 sem_close</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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><a name="semunlink">2.5.5 sem_unlink</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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><a name="semwait">2.5.6 sem_wait</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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><a name="semtrywait">2.5.7 sem_trywait</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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><a name="sempost">2.5.8 sem_post</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <semaphore.h>
|
|
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 <semaphore.h>
|
|
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>
|
|
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 mq_send(), sigqueue(), or kill() 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 <wdog.h>
|
|
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 <wdog.h>
|
|
STATUS 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 de-allocating 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 <wdog.h>
|
|
STATUS 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, 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 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 parameters to pass to wdentry.
|
|
<LI><I>...</I>. uint32 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 <wdog.h>
|
|
STATUS 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 <wdog.h>
|
|
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 <time.h>
|
|
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 <time.h>
|
|
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 <time.h>
|
|
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 <time.h>
|
|
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 <time.h>
|
|
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 <time.h>
|
|
#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 <time.h>
|
|
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><time.h><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 <time.h>
|
|
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 <time.h>
|
|
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 <time.h>
|
|
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 <time.h>
|
|
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 <signal.h>
|
|
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 <signal.h>
|
|
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 <signal.h>
|
|
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 <signal.h>
|
|
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 <signal.h>
|
|
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 <signal.h>
|
|
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 <signal.h>
|
|
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 <signal.h>
|
|
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: "If a subsequent occurrence of a pending
|
|
signal is generated, it is implementation defined as to whether the signal
|
|
is delivered more than once."
|
|
<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 <signal.h>
|
|
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() "suspends the task until
|
|
delivery of a signal whose action is either to execute a signal-catching
|
|
function or to terminate the task." 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 <signal.h>
|
|
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 <signal.h>
|
|
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
|
|
from si_code in a non-standard way).
|
|
<LI>POSIX states that "If no signal is pending at the time of the
|
|
call, the calling task shall be suspended until one or more signals
|
|
in set become pending or until it is interrupted by an unblocked,
|
|
<I>caught</I> signal." The present implementation does not require
|
|
that the unblocked signal be caught; the task will be resumed even if
|
|
the unblocked signal is ignored.
|
|
</UL>
|
|
|
|
<H3><a name="sigqueue">2.8.12 sigqueue</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <signal.h>
|
|
int sigqueue (int tid, int signo, const union sigval value);
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B> This function sends the signal specified by
|
|
signo with the signal parameter value to the task specified
|
|
by tid.
|
|
<P>
|
|
If the receiving task 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: "If a subsequent occurrence of a pending signal
|
|
is generated, it is implementation defined as to whether the signal
|
|
is delivered more than once."
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<UL>
|
|
<LI><I>tid</I>. ID of the task to receive signal
|
|
<LI><I>signo</I>. Signal number
|
|
<LI><I>value</I>. Value to pass to task with signal
|
|
</UL>
|
|
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>
|
|
On success (at least one signal was sent), zero (OK) is returned.
|
|
On error, -1 (ERROR) is returned, and errno is set appropriately.
|
|
<ul>
|
|
<li><code>EGAIN</code>. The limit of signals which may be queued has been reached.</li>
|
|
<li><code>EINVAL</code>. signo was invalid.</li>
|
|
<li><code>EPERM</code>. The task does not have permission to send the signal to the receiving process.</li>
|
|
<li><code>ESRCH</code>. No process has a PID matching pid.</li>
|
|
</ul>
|
|
</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>Default action is to ignore signals.
|
|
<LI>Signals are processed one at a time in order
|
|
<LI>POSIX states that, "If signo is zero (the null signal), error
|
|
checking will be performed but no signal is actually sent."
|
|
There is no null signal in the present implementation; a zero signal will
|
|
be sent.
|
|
</UL>
|
|
|
|
<H3><a name="kill">2.8.13 kill</a></H3>
|
|
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<PRE>
|
|
#include <sys/types.h>
|
|
#include <signal.h>
|
|
int kill(pid_t pid, int sig);
|
|
</PRE>
|
|
|
|
<P>
|
|
<B>Description:</B>
|
|
The kill() system call can be used to send any signal to
|
|
any task.
|
|
</p>
|
|
<p>
|
|
If the receiving task 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: "If a subsequent occurrence of a pending signal
|
|
is generated, it is implementation defined as to whether the signal
|
|
is delivered more than once."
|
|
</p>
|
|
<p>
|
|
<b>Input Parameters:</b>
|
|
<ul>
|
|
<li><I>pid</I>. The id of the task to receive the signal.
|
|
The POSIX <code>kill()</code> specification encodes process group
|
|
information as zero and negative pid values.
|
|
Only positive, non-zero values of pid are supported by this
|
|
implementation. ID of the task to receive signal
|
|
<LI><I>signo</I>. The signal number to send.
|
|
</UL>
|
|
|
|
<p>
|
|
<B>Returned Values:</B>
|
|
<UL>
|
|
<LI>OK or ERROR
|
|
</UL>
|
|
</p>
|
|
|
|
<p>
|
|
<B>Assumptions/Limitations:</B>
|
|
</p>
|
|
<p>
|
|
<b>POSIX Compatibility:</b>
|
|
Comparable to the POSIX interface of the same name.
|
|
Differences from the POSIX interface include:
|
|
</p>
|
|
<ul>
|
|
<li>Default action is to ignore signals.</li>
|
|
<li>Signals are processed one at a time in order </li>
|
|
<li>Sending of signals to 'process groups' is not supported in NuttX.</li>
|
|
</ul>
|
|
|
|
<H2>2.9 <A NAME="Pthread">Pthread Interfaces</A></H2>
|
|
<ul>
|
|
<li><a href="#pthreadattrinit">2.9.1 pthread_attr_init</a></li>
|
|
<li><a href="#pthreadattrdestroy">2.9.2 pthread_attr_destroy</a></li>
|
|
<li><a href="#pthreadattrsetschedpolity">2.9.3 pthread_attr_setschedpolicy</a></li>
|
|
<li><a href="#pthreadattrgetschedpolicy">2.9.4 pthread_attr_getschedpolicy</a></li>
|
|
<li><a href="#pthreadattrsetschedparam">2.9.5 pthread_attr_setschedparam</a></li>
|
|
<li><a href="#pthreadattrgetschedparam">2.9.6 pthread_attr_getschedparam</a></li>
|
|
<li><a href="#pthreadattrsetinheritsched">2.9.7 pthread_attr_setinheritsched</a></li>
|
|
<li><a href="#pthreadattrgetinheritsched">2.9.8 pthread_attr_getinheritsched</a></li>
|
|
<li><a href="#pthreadattrsetstacksize">2.9.9 pthread_attr_setstacksize</a></li>
|
|
<li><a href="#pthreadattrgetstacksize">2.9.10 pthread_attr_getstacksize</a></li>
|
|
<li><a href="#pthreadcreate">2.9.11 pthread_create</a></li>
|
|
<li><a href="#pthreaddetach">2.9.12 pthread_detach</a></li>
|
|
<li><a href="#pthreadexit">2.9.13 pthread_exit</a></li>
|
|
<li><a href="#pthreadcancel">2.9.14 pthread_cancel</a></li>
|
|
<li><a href="#pthreadsetcancelstate">2.9.15 pthread_setcancelstate</a></li>
|
|
<li><a href="#pthreadtestcancelstate">2.9.16 pthread_testcancelstate</a></li>
|
|
<li><a href="#pthreadjoin">2.9.17 pthread_join</a></li>
|
|
<li><a href="#pthreadyield">2.9.18 pthread_yield</a></li>
|
|
<li><a href="#pthreadself">2.9.19 pthread_self</a></li>
|
|
<li><a href="#pthreadgetschedparam">2.9.20 pthread_getschedparam</a></li>
|
|
<li><a href="#pthreadsetschedparam">2.9.21 pthread_setschedparam</a></li>
|
|
<li><a href="#pthreadkeycreate">2.9.22 pthread_key_create</a></li>
|
|
<li><a href="#pthreadsetspecific">2.9.23 pthread_setspecific</a></li>
|
|
<li><a href="#pthreadgetspecific">2.9.24 pthread_getspecific</a></li>
|
|
<li><a href="#pthreadkeydelete">2.9.25 pthread_key_delete</a></li>
|
|
<li><a href="#pthreadmutexattrinit">2.9.26 pthread_mutexattr_init</a></li>
|
|
<li><a href="#pthreadmutexattrdestroy">2.9.27 pthread_mutexattr_destroy</a></li>
|
|
<li><a href="#pthreadmutexattrgetpshared">2.9.28 pthread_mutexattr_getpshared</a></li>
|
|
<li><a href="#pthreadmutexattrsetpshared">2.9.29 pthread_mutexattr_setpshared</a></li>
|
|
<li><a href="#pthreadmutexinit">2.9.30 pthread_mutex_init</a></li>
|
|
<li><a href="#pthreadmutexdestrory">2.9.31 pthread_mutex_destroy</a></li>
|
|
<li><a href="#pthreadmutexlock">2.9.32 pthread_mutex_lock</a></li>
|
|
<li><a href="#pthreadmutextrylock">2.9.33 pthread_mutex_trylock</a></li>
|
|
<li><a href="#pthreadmutexunlock">2.9.34 pthread_mutex_unlock</a></li>
|
|
<li><a href="#pthreadconaddrinit">2.9.35 pthread_condattr_init</a></li>
|
|
<li><a href="#pthreadocndattrdestroy">2.9.36 pthread_condattr_destroy</a></li>
|
|
<li><a href="#pthreadcondinit">2.9.37 pthread_cond_init</a></li>
|
|
<li><a href="#pthreadconddestroy">2.9.38 pthread_cond_destroy</a></li>
|
|
<li><a href="#pthreadcondbroadcast">2.9.39 pthread_cond_broadcast</a></li>
|
|
<li><a href="#pthreadcondsignal">2.9.40 pthread_cond_signal</a></li>
|
|
<li><a href="#pthreadcondwait">2.9.41 pthread_cond_wait</a></li>
|
|
<li><a href="#pthreadcondtimedwait">2.9.42 pthread_cond_timedwait</a></li>
|
|
</ul>
|
|
|
|
<H3><a name="pthreadattrinit">2.9.1 pthread_attr_init</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_init(pthread_attr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
Initializes a thread attributes object (attr) with default values
|
|
for all of the individual attributes used by the implementation.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_init()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
<P>
|
|
<H3><a name="pthreadattrdestroy">2.9.2 pthread_attr_destroy</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_destroy(pthread_attr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
An attributes object can be deleted when it is no longer needed.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_destroy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
<P>
|
|
<H3><a name="pthreadattrsetschedpolity">2.9.3 pthread_attr_setschedpolicy</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_setschedpolicy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadattrgetschedpolicy">2.9.4 pthread_attr_getschedpolicy</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_getschedpolicy(pthread_attr_t *attr, int *policy);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_getschedpolicy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadattrsetschedparam">2.9.5 pthread_attr_getschedpolicy</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_setschedparam(pthread_attr_t *attr,
|
|
const struct sched_param *param);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_getschedpolicy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadattrgetschedparam">2.9.6 pthread_attr_getschedparam</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_getschedparam(pthread_attr_t *attr,
|
|
struct sched_param *param);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_getschedparam()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadattrsetinheritsched">2.9.7 pthread_attr_setinheritsched</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_setinheritsched(pthread_attr_t *attr,
|
|
int inheritsched);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_setinheritsched()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
<P>
|
|
<H3><a name="pthreadattrgetinheritsched">2.9.8 pthread_attr_getinheritsched</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_getinheritsched(const pthread_attr_t *attr,
|
|
int *inheritsched);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_getinheritsched()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadattrsetstacksize">2.9.9 pthread_attr_setstacksize</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_setstacksize(pthread_attr_t *attr, long stacksize);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_setstacksize()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadattrgetstacksize">2.9.10 pthread_attr_getstacksize</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_attr_getstacksize(pthread_attr_t *attr, long *stackaddr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_attr_getstacksize()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadcreate">2.9.11 pthread_create</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_create(pthread_t *thread, pthread_attr_t *attr,
|
|
pthread_startroutine_t startRoutine,
|
|
pthread_addr_t arg);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
To create a thread object and runnable thread, a routine
|
|
must be specified as the new thread's start routine. An
|
|
argument may be passed to this routine, as an untyped
|
|
address; an untyped address may also be returned as the
|
|
routine's value. An attributes object may be used to
|
|
specify details about the kind of thread being created.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_create()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreaddetach">2.9.12 pthread_detach</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_detach(pthread_t thread);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
A thread object may be "detached" to specify that the
|
|
return value and completion status will not be requested.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_detach()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadexit">2.9.13 pthread_exit</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
void pthread_exit(pthread_addr_t pvValue);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
A thread may terminate it's own execution.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_exit()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadcancel">2.9.14 pthread_cancel</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_cancel(pthread_t thread);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
|
|
<p>The pthread_cancel() function shall request that thread
|
|
be canceled. The target thread's cancelability state determines
|
|
when the cancellation takes effect. When the
|
|
cancellation is acted on, thread shall be terminated.</p>
|
|
|
|
<p>When cancelability is disabled, all cancels are held pending
|
|
in the target thread until the thread changes the cancelability.
|
|
When cancelability is deferred, all cancels are held pending in
|
|
the target thread until the thread changes the cancelability or
|
|
calls pthread_testcancel().</p>
|
|
|
|
<p>Cancelability is asynchronous; all cancels are acted upon
|
|
immediately (when enable), interrupting the thread with its processing.</p>
|
|
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>thread</I>.
|
|
Identifies the thread to be canceled.</li>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>ptnread_cancel()</I> function will return zero (<I>OK</I>).
|
|
Otherwise, an error number will be returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<LI><I>ESRCH</I>.
|
|
No thread could be found corresponding to that specified by the given thread ID.</li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name. Except:</p>
|
|
<UL>
|
|
<LI>The thread-specific data destructor functions shall be called for thread.
|
|
However, these destructors are not currently supported.</li>
|
|
<li>Cancellation types are not supported. The thread will be canceled
|
|
at the time that pthread_cancel() is called or, if cancelation is disabled, at
|
|
the time when cancelation is re-enabled.</li>
|
|
<li><tt>pthread_testcancel()</tt> is not supported.</li>
|
|
<li>Thread cancellation at <i>cancellation points</i> is not supported.</li>
|
|
</UL>
|
|
|
|
<H3><a name="pthreadsetcancelstate">2.9.15 pthread_setcancelstate</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_setcancelstate(int state, int *oldstate);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>The <i>pthread_setcancelstate()</i> function atomically
|
|
sets both the calling thread's cancelability state to the indicated
|
|
state and returns the previous cancelability state at the location
|
|
referenced by oldstate.
|
|
Legal values for state are PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DISABLE.<.li>
|
|
|
|
<p>Any pending thread cancelation may occur at the time that the
|
|
cancelation state is set to PTHREAD_CANCEL_ENABLE.</p>
|
|
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>state</I>
|
|
New cancelation state. One of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.<.li>
|
|
<LI><I>oldstate</I>.
|
|
Location to return the previous cancelation state.
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_setcancelstate()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<LI><I>ESRCH</I>.
|
|
No thread could be found corresponding to that specified by the given thread ID.</li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadtestcancelstate">2.9.16 pthread_testcancelstate</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_setcancelstate(void);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P><b>NOT SUPPORTED</b>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_setcancelstate()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadjoin">2.9.17 pthread_join</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_join(pthread_t thread, pthread_addr_t *ppvValue);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
A thread can await termination of another thread and retrieve
|
|
the return value of the thread.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_join()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadyield">2.9.18 pthread_yield</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
void pthread_yield(void);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
A thread may tell the scheduler that its processor can be
|
|
made available.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_yield()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadself">2.9.19 pthread_self</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
pthread_t pthread_self(void);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
A thread may obtain a copy of its own thread handle.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_self()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadgetschedparam">2.9.20 pthread_getschedparam</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_getschedparam(pthread_t thread, int *policy,
|
|
struct sched_param *param);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_getschedparam()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadsetschedparam">2.9.21 pthread_setschedparam</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_setschedparam(pthread_t thread, int policy,
|
|
const struct sched_param *param);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_setschedparam()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadkeycreate">2.9.22 pthread_key_create</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_key_create( pthread_key_t *key, void (*destructor)(void*) )
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
This function creates a thread-specific data key visible
|
|
to all threads in the system. Although the same key value
|
|
may be used by different threads, the values bound to
|
|
the key by <I>pthread_setspecific()</I> are maintained on a
|
|
per-thread basis and persist for the life of the calling
|
|
thread.
|
|
<P>
|
|
Upon key creation, the value <I>NULL</I> will be associated with
|
|
the the new key in all active threads. Upon thread
|
|
creation, the value <I>NULL</I> will be associated with all
|
|
defined keys in the new thread.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>key</I> is a pointer to the key to create.
|
|
<LI><I>destructor</I> is an optional destructor() function that may
|
|
be associated with each key that is invoked when a
|
|
thread exits. However, this argument is ignored in
|
|
the current implementation.
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_key_create()</I> function will
|
|
store the newly created key value at *<I>key</I> and return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<LI><I>EAGAIN</I>. The system lacked sufficient resources
|
|
to create another thread-specific data key, or the
|
|
system-imposed limit on the total number of keys
|
|
per task {<I>PTHREAD_KEYS_MAX</I>} has been exceeded
|
|
<LI><I>ENONMEM</I> Insufficient memory exists to create the key.
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
<UL>
|
|
<LI>The present implementation ignores the destructor argument.
|
|
</UL>
|
|
|
|
<H3><a name="pthreadsetspecific">2.9.23 pthread_setspecific</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_setspecific( pthread_key_t key, void *value )
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
The <I>pthread_setspecific()</I> function associates a thread-
|
|
specific value with a key obtained via a previous call
|
|
to <I>pthread_key_create()</I>. Different threads may bind
|
|
different values to the same key. These values are
|
|
typically pointers to blocks of dynamically allocated
|
|
memory that have been reserved for use by the calling
|
|
thread.
|
|
<P>
|
|
The effect of calling <I>pthread_setspecific()</I> with a key value
|
|
not obtained from <I>pthread_key_create()</I> or after a key has been
|
|
deleted with <I>pthread_key_delete()</I> is undefined.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>key</I>. The data key to set the binding for.
|
|
<LI><I>value</I>. The value to bind to the key.
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, <I>pthread_setspecific()</I> will return zero (<I>OK</I>).
|
|
Otherwise, an error number will be returned:
|
|
<P>
|
|
<UL>
|
|
<LI><I>ENOMEM</I>. Insufficient memory exists to associate the value
|
|
with the key.
|
|
<LI><I>EINVAL</I>. The key value is invalid.
|
|
</UL>
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
<UL>
|
|
<LI>pthread_setspecific() may be called from a thread-specific data
|
|
destructor function.
|
|
</UL>
|
|
|
|
<H3><a name="pthreadgetspecific">2.9.24 pthread_getspecific</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
void *pthread_getspecific( pthread_key_t key )
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
The <I>pthread_getspecific()</I> function returns the value
|
|
currently bound to the specified key on behalf of the
|
|
calling thread.
|
|
<P>
|
|
The effect of calling <I>pthread_getspecific()</I> with a key value
|
|
not obtained from <I>pthread_key_create()</I> or after a key has been
|
|
deleted with <I>pthread_key_delete()</I> is undefined.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>key</I>. The data key to get the binding for.
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
The function <I>pthread_getspecific()</I> returns the thread-
|
|
specific data associated with the given key. If no
|
|
thread specific data is associated with the key, then
|
|
the value <I>NULL</I> is returned.
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
<UL>
|
|
<LI>pthread_getspecific() may be called from a thread-specific data
|
|
destructor function.
|
|
</UL>
|
|
|
|
<H3><a name="pthreadkeydelete">2.9.25 pthread_key_delete</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_key_delete( pthread_key_t key )
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
This POSIX function should delete a thread-specific data
|
|
key previously returned by <I>pthread_key_create()</I>. However,
|
|
this function does nothing in the present implementation.
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>key</I>. The key to delete
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
<UL>
|
|
<LI>Always returns <I>EINVAL</I>.
|
|
</UL>
|
|
<P>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexattrinit">2.9.26 pthread_mutexattr_init</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutexattr_init(pthread_mutexattr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutexattr_init()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexattrdestroy">2.9.27 pthread_mutexattr_destroy</A></H3>
|
|
<P>
|
|
<B>Function Protoype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutexattr_destroy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexattrgetpshared">2.9.28 pthread_mutexattr_getpshared</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
|
|
int *pshared);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutexattr_getpshared()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexattrsetpshared">2.9.29 pthread_mutexattr_setpshared</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
|
|
int pshared);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutexattr_setpshared()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexinit">2.9.30 pthread_mutex_init</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutex_init(pthread_mutex_t *mutex,
|
|
pthread_mutexattr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutex_init()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexdestrory">2.9.31 pthread_mutex_destroy</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutex_destroy(pthread_mutex_t *mutex);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutex_destroy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexlock">2.9.32 pthread_mutex_lock</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutex_lock(pthread_mutex_t *mutex);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutex_lock()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutextrylock">2.9.33 pthread_mutex_trylock</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutex_trylock(pthread_mutex_t *mutex);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutex_trylock()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadmutexunlock">2.9.34 pthread_mutex_unlock</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_mutex_unlock(pthread_mutex_t *mutex);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_mutex_unlock()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadconaddrinit">2.9.35 pthread_condattr_init</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_condattr_init(pthread_condattr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_condattr_init()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadocndattrdestroy">2.9.36 pthread_condattr_destroy</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_condattr_destroy(pthread_condattr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_condattr_destroy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadcondinit">2.9.37 pthread_cond_init</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *attr);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_cond_init()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadconddestroy">2.9.38 pthread_cond_destroy</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_cond_destroy(pthread_cond_t *cond);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_cond_destroy()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadcondbroadcast">2.9.39 pthread_cond_broadcast</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_cond_broadcast(pthread_cond_t *cond);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_cond_broadcast()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadcondsignal">2.9.40 pthread_cond_signal</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_cond_signal(pthread_cond_t *dond);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_cond_signal()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadcondwait">2.9.41 pthread_cond_wait</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_cond_wait()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<H3><a name="pthreadcondtimedwait">2.9.42 pthread_cond_timedwait</A></H3>
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE>
|
|
#include <pthread.h>
|
|
int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
|
|
const struct timespec *abstime);
|
|
</PRE>
|
|
<P>
|
|
<B>Description:</B>
|
|
<P>
|
|
<B>Input Parameters:</B>
|
|
<P>
|
|
<UL>
|
|
<LI><I>parm</I>
|
|
</UL>
|
|
<P>
|
|
<B>Returned Values:</B>
|
|
<P>
|
|
If successful, the <I>pthread_cond_timedwait()</I> function will return
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
returned to indicate the error:
|
|
<P>
|
|
<UL>
|
|
<li><code>Exxx</code>. </li>
|
|
</UL>
|
|
<B>Assumptions/Limitations:</B>
|
|
<P>
|
|
<B>POSIX Compatibility:</B> Comparable to the POSIX
|
|
interface of the same name.
|
|
|
|
<P>
|
|
<HR>
|
|
<H1>3.0 <A NAME="Data_Structures">OS Data Structures</A></H1>
|
|
<H2>3.1 Scalar types</H2>
|
|
<P>
|
|
Many of the types used to communicate with NuttX are simple
|
|
scalar types. These types are used to provide architecture independence
|
|
of the OS from the application. The scalar types used at the NuttX
|
|
interface include:
|
|
<UL>
|
|
<LI>pid_t
|
|
<LI>size_t
|
|
<LI>sigset_t
|
|
<LI>STATUS
|
|
<LI>time_t
|
|
</UL>
|
|
|
|
<H2>3.2 Hidden Interface Structures</H2>
|
|
<P>
|
|
Several of the types used to interface with NuttX are
|
|
structures that are intended to be hidden from the application.
|
|
From the standpoint of the application, these structures (and
|
|
structure pointers) should be treated as simple handles to reference
|
|
OS resources. These hidden structures include:
|
|
<UL>
|
|
<LI>_TCB
|
|
<LI>mqd_t
|
|
<LI>sem_t
|
|
<LI>WDOG_ID
|
|
<LI>pthread_key_t
|
|
</UL>
|
|
<P>
|
|
In order to maintain portability, applications should not reference
|
|
specific elements within these hidden structures. These hidden
|
|
structures will not be described further in this user's manual.
|
|
<P>
|
|
|
|
<H2>3.3. Access to the <I>errno</I> Variable</H2>
|
|
<P>
|
|
A pointer to the thread-specific <I>errno</I>. value is available through a
|
|
function call:
|
|
<P>
|
|
<B>Function Prototype:</B>
|
|
<P>
|
|
<PRE> int *get_errno_ptr( void )</PRE>
|
|
<P>
|
|
<B>Description</B>: <I>osGetErrnorPtr()</I> returns a pointer to
|
|
the thread-specific <I>errno</I> value.
|
|
<P>
|
|
This differs somewhat from the use for errno in a multi-threaded process environment:
|
|
Each pthread will have its own private copy of errno and the errno will not be shared
|
|
between pthreads.
|
|
<P>
|
|
<B>Input Parameters</B>: None
|
|
<P>
|
|
<B>Returned Values</B>:
|
|
<P>
|
|
<UL>
|
|
<LI>A pointer to the thread-specific <I>errno</I> value.
|
|
</UL>
|
|
<P>
|
|
|
|
<H2>3.4 User Interface Structures</H2>
|
|
<P>
|
|
<H3>3.4.1 main_t</H3>
|
|
<P>
|
|
main_t defines the type of a task entry point. main_t is declared
|
|
in sys/types.h as:
|
|
<PRE>
|
|
typedef int (*main_t)(int argc, char *argv[]);
|
|
</PRE>
|
|
|
|
<H3>3.4.2 struct sched_param</H3>
|
|
|
|
<P>
|
|
This structure is used to pass scheduling priorities to and from
|
|
NuttX;
|
|
<PRE>
|
|
struct sched_param
|
|
{
|
|
int sched_priority;
|
|
};
|
|
</PRE>
|
|
|
|
<H3>3.4.3 struct timespec</H3>
|
|
|
|
<P>
|
|
This structure is used to pass timing information between the
|
|
NuttX and a user application:
|
|
<PRE>
|
|
struct timespec
|
|
{
|
|
time_t tv_sec; /* Seconds */
|
|
long tv_nsec; /* Nanoseconds */
|
|
};
|
|
</PRE>
|
|
|
|
<H3>3.4.4 struct mq_attr</H3>
|
|
|
|
<P>
|
|
This structure is used to communicate message queue attributes
|
|
between NuttX and a MoBY application:
|
|
<PRE>
|
|
struct mq_attr {
|
|
size_t mq_maxmsg; /* Max number of messages in queue */
|
|
size_t mq_msgsize; /* Max message size */
|
|
unsigned mq_flags; /* Queue flags */
|
|
size_t mq_curmsgs; /* Number of messages currently in queue */
|
|
};
|
|
</PRE>
|
|
|
|
<H3>3.4.5 struct sigaction</H3>
|
|
|
|
<P>
|
|
The following structure defines the action to take for given signal:
|
|
<PRE>
|
|
struct sigaction
|
|
{
|
|
union
|
|
{
|
|
void (*_sa_handler)(int);
|
|
void (*_sa_sigaction)(int, siginfo_t *, void *);
|
|
} sa_u;
|
|
sigset_t sa_mask;
|
|
int sa_flags;
|
|
};
|
|
#define sa_handler sa_u._sa_handler
|
|
#define sa_sigaction sa_u._sa_sigaction
|
|
</PRE>
|
|
|
|
<H3>3.4.6 struct siginfo/siginfo_t</H3>
|
|
|
|
<P>
|
|
The following types is used to pass parameters to/from signal
|
|
handlers:
|
|
<PRE>
|
|
typedef struct siginfo
|
|
{
|
|
int si_signo;
|
|
int si_code;
|
|
union sigval si_value;
|
|
} siginfo_t;
|
|
</PRE>
|
|
|
|
<H3>3.4.7 union sigval</H3>
|
|
|
|
<P>
|
|
This defines the type of the struct siginfo si_value field and
|
|
is used to pass parameters with signals.
|
|
<PRE>
|
|
union sigval
|
|
{
|
|
int sival_int;
|
|
void *sival_ptr;
|
|
};
|
|
</PRE>
|
|
|
|
<H3>3.4.8 struct sigevent</H3>
|
|
|
|
<P>
|
|
The following is used to attach a signal to a message queue to
|
|
notify a task when a message is available on a queue.
|
|
<PRE>
|
|
struct sigevent
|
|
{
|
|
int sigev_signo;
|
|
union sigval sigev_value;
|
|
int sigev_notify;
|
|
};
|
|
</PRE>
|
|
|
|
<H3>3.4.9 Watchdog Data Types</H3>
|
|
|
|
<p>
|
|
When a watchdog expires, the callback function with this
|
|
type is called:
|
|
</p>
|
|
<pre>
|
|
typedef void (*wdentry_t)(int argc, ...);
|
|
</pre>
|
|
<p>
|
|
Where argc is the number of uint32 type arguments that follow.
|
|
</p>
|
|
The arguments are passed as uint32 values.
|
|
For systems where the sizeof(pointer) < sizeof(uint32), the
|
|
following union defines the alignment of the pointer within the
|
|
uint32. For example, the SDCC MCS51 general pointer is
|
|
24-bits, but uint32 is 32-bits (of course).
|
|
</p>
|
|
<pre>
|
|
union wdparm_u
|
|
{
|
|
void *pvarg;
|
|
uint32 *dwarg;
|
|
};
|
|
typedef union wdparm_u wdparm_t;
|
|
</pre>
|
|
<p>
|
|
For most 32-bit systems, pointers and uint32 are the same size
|
|
For systems where sizeof(pointer) > sizeof(uint32), we will
|
|
have to do some redesign.
|
|
</p>
|
|
|
|
<h1><a name="FileSystem">2.10 Filesystem Interfaces</a></h1>
|
|
<p>
|
|
The NuttX filesystem is very simple; it does not involve any block drivers or
|
|
particular filesystem (like FAT or EXT2 etc.).
|
|
The NuttX filesystem simply supports a set a filesystem APIs
|
|
(<code>open()</code>, <code>close()</code>, <code>read()</code>, <code>write</code>, etc.)
|
|
and a registration mechanism that allows devices drivers to a associated with <i>nodes</i>
|
|
in a file-system-like name space.
|
|
</p>
|
|
|
|
<h2><a name="driveroperations">2.10.1 Driver Operations</a></h2>
|
|
<ul><pre>
|
|
#include <fcntl.h>
|
|
int open(const char *path, int oflag, ...);
|
|
</pre></ul>
|
|
|
|
<ul><pre>
|
|
#include <unistd.h>
|
|
int close(int fd);
|
|
int dup(int fildes);
|
|
int dup2(int fildes1, int fildes2);
|
|
off_t lseek(int fd, off_t offset, int whence); /* Prototyped but not implemented */
|
|
int read(int fd, void *buf, unsigned int nbytes);
|
|
int unlink(const char *path);
|
|
int write(int fd, const void *buf, unsigned int nbytes);
|
|
</pre></ul>
|
|
|
|
<ul><pre>
|
|
#include <sys/ioctl.h>
|
|
int ioctl(int fd, int req, unsigned long arg);
|
|
</pre></ul>
|
|
|
|
<h2><a name="directoryoperations">2.10.2 Directory Operations</a></h2>
|
|
<ul><pre>
|
|
#include <dirent.h>
|
|
int closedir(DIR *dirp);
|
|
FAR DIR *opendir(const char *path);
|
|
FAR struct dirent *readdir(FAR DIR *dirp);
|
|
int readdir_r(FAR DIR *dirp, FAR struct dirent *entry, FAR struct dirent **result);
|
|
void rewinddir(FAR DIR *dirp);
|
|
void seekdir(FAR DIR *dirp, int loc);
|
|
int telldir(FAR DIR *dirp);
|
|
</pre></ul>
|
|
|
|
<h2><a name="standardio">2.10.3 Standard I/O</a></h2>
|
|
<ul><pre>
|
|
#include <stdio.h>
|
|
int fclose(FILE *stream);
|
|
int fflush(FILE *stream);
|
|
int feof(FILE *stream); /* Prototyped but not implemented */
|
|
int ferror(FILE *stream); /* Prototyped but not implemented */
|
|
int fgetc(FILE *stream);
|
|
char *fgets(char *s, int n, FILE *stream);
|
|
FILE *fopen(const char *path, const char *type);
|
|
int fprintf(FILE *stream, const char *format, ...);
|
|
int fputc(int c, FILE *stream);
|
|
int fputs(const char *s, FILE *stream);
|
|
size_t fread(void *ptr, size_t size, size_t n_items, FILE *stream);
|
|
int fseek(FILE *stream, long int offset, int whence); /* Prototyped but not implemented */
|
|
size_t fwrite(const void *ptr, size_t size, size_t n_items, FILE *stream);
|
|
char *gets(char *s);
|
|
|
|
int printf(const char *format, ...);
|
|
int puts(const char *s);
|
|
int rename(const char *source, const char *target); /* Prototyped but not implemented */
|
|
int sprintf(char *dest, const char *format, ...);
|
|
int ungetc(int c, FILE *stream);
|
|
int vprintf(const char *s, va_list ap);
|
|
int vfprintf(FILE *stream, const char *s, va_list ap);
|
|
int vsprintf(char *buf, const char *s, va_list ap);
|
|
|
|
int chdir(const char *path); /* Prototyped but not implemented */
|
|
FILE *fdopen(int fd, const char *type);
|
|
int fstat(int fd, FAR struct stat *buf); /* Prototyped but not implemented */
|
|
char *getcwd(FAR char *buf, size_t size); /* Prototyped but not implemented */
|
|
int mkdir(const char *path, mode_t mode); /* Prototyped but not implemented */
|
|
int rmdir(const char *path); /* Prototyped but not implemented */
|
|
int stat(const char *path, FAR struct stat *buf); /* Prototyped but not implemented */
|
|
int statfs(const char *path, FAR struct statfs *buf); /* Prototyped but not implemented */
|
|
</pre></ul>
|
|
|
|
<h1><a name="index">Index</a></h1>
|
|
<ul>
|
|
<li><a href="#clockgetres">clock_getres</a></li>
|
|
<li><a href="#clockgettime">clock_gettime</a></li>
|
|
<li><a href="#ClocksNTimers">Clocks</a></li>
|
|
<li><a href="#clocksettime">clock_settime</a></li>
|
|
<li><a href="#Data_Structures">Data structures</a></li>
|
|
<li><a href="#directoryoperations">Directory operations</a></li>
|
|
<li><a href="#driveroperations">Driver operations</a></li>
|
|
<li><a href="#exit">exit</a></li>
|
|
<li><a href="#FileSystem">Filesystem interfaces</a></li>
|
|
<li><a href="#getpid">getpid</a></li>
|
|
<li><a href="#gmtimer">gmtime_r</a></li>
|
|
<li><a href="#Introduction">Introduction</a>
|
|
<li><a href="#kill">kill</a></li>
|
|
<li><a href="#localtimer">localtime_r</a></li>
|
|
<li><a href="#Message_Queue">Named Message Queue Interfaces</a>
|
|
<li><a href="#mktime">mktime</a></li>
|
|
<li><a href="#mqclose">mq_close</a></li>
|
|
<li><a href="#mqgetattr">mq_getattr</a></li>
|
|
<li><a href="#mqnotify">mq_notify</a></li>
|
|
<li><a href="#mqopen">mq_open</a></li>
|
|
<li><a href="#mqreceive">mq_receive</a></li>
|
|
<li><a href="#mqsend">mq_send</a></li>
|
|
<li><a href="#mqsetattr">mq_setattr</a></li>
|
|
<li><a href="#mqunlink">mq_unlink</a></li>
|
|
<li><a href="#OS_Interfaces">OS Interfaces</a>
|
|
<li><a href="#pthreadattrdestroy">pthread_attr_destroy</a></li>
|
|
<li><a href="#pthreadattrgetinheritsched">pthread_attr_getinheritsched</a></li>
|
|
<li><a href="#pthreadattrgetschedparam">pthread_attr_getschedparam</a></li>
|
|
<li><a href="#pthreadattrgetschedpolicy">pthread_attr_getschedpolicy</a></li>
|
|
<li><a href="#pthreadattrgetstacksize">0 pthread_attr_getstacksize</a></li>
|
|
<li><a href="#pthreadattrinit">pthread_attr_init</a></li>
|
|
<li><a href="#pthreadattrsetinheritsched">pthread_attr_setinheritsched</a></li>
|
|
<li><a href="#pthreadattrsetschedparam">pthread_attr_setschedparam</a></li>
|
|
<li><a href="#pthreadattrsetschedpolity">pthread_attr_setschedpolicy</a></li>
|
|
<li><a href="#pthreadattrsetstacksize">pthread_attr_setstacksize</a></li>
|
|
<li><a href="#pthreadcancel">pthread_cancel</a></li>
|
|
<li><a href="#pthreadconaddrinit">pthread_condattr_init</a></li>
|
|
<li><a href="#pthreadcondbroadcast">pthread_cond_broadcast</a></li>
|
|
<li><a href="#pthreadconddestroy">pthread_cond_destroy</a></li>
|
|
<li><a href="#pthreadcondinit">pthread_cond_init</a></li>
|
|
<li><a href="#pthreadcondsignal">pthread_cond_signal</a></li>
|
|
<li><a href="#pthreadcondtimedwait">pthread_cond_timedwait</a></li>
|
|
<li><a href="#pthreadcondwait">pthread_cond_wait</a></li>
|
|
<li><a href="#pthreadcreate">pthread_create</a></li>
|
|
<li><a href="#pthreaddetach">pthread_detach</a></li>
|
|
<li><a href="#pthreadexit">pthread_exit</a></li>
|
|
<li><a href="#pthreadgetschedparam">pthread_getschedparam</a></li>
|
|
<li><a href="#pthreadgetspecific">pthread_getspecific</a></li>
|
|
<li><a href="#Pthread"><i>pthreads</i></a> share some resources.
|
|
<li><a href="#pthreadjoin">pthread_join</a></li>
|
|
<li><a href="#pthreadkeycreate">pthread_key_create</a></li>
|
|
<li><a href="#pthreadkeydelete">pthread_key_delete</a></li>
|
|
<li><a href="#pthreadmutexattrdestroy">pthread_mutexattr_destroy</a></li>
|
|
<li><a href="#pthreadmutexattrgetpshared">pthread_mutexattr_getpshared</a></li>
|
|
<li><a href="#pthreadmutexattrinit">pthread_mutexattr_init</a></li>
|
|
<li><a href="#pthreadmutexattrsetpshared">pthread_mutexattr_setpshared</a></li>
|
|
<li><a href="#pthreadmutexdestrory">pthread_mutex_destroy</a></li>
|
|
<li><a href="#pthreadmutexinit">pthread_mutex_init</a></li>
|
|
<li><a href="#pthreadmutexlock">pthread_mutex_lock</a></li>
|
|
<li><a href="#pthreadmutextrylock">pthread_mutex_trylock</a></li>
|
|
<li><a href="#pthreadmutexunlock">pthread_mutex_unlock</a></li>
|
|
<li><a href="#pthreadocndattrdestroy">pthread_condattr_destroy</a></li>
|
|
<li><a href="#Pthread">Pthread Interfaces</a>
|
|
<li><a href="#pthreadself">pthread_self</a></li>
|
|
<li><a href="#pthreadsetcancelstate">pthread_setcancelstate</a></li>
|
|
<li><a href="#pthreadsetschedparam">pthread_setschedparam</a></li>
|
|
<li><a href="#pthreadsetspecific">pthread_setspecific</a></li>
|
|
<li><a href="#pthreadtestcancelstate">pthread_testcancelstate</a></li>
|
|
<li><a href="#pthreadyield">pthread_yield</a></li>
|
|
<li><a href="#schedgetparam">sched_getparam</a></li>
|
|
<li><a href="#schedgetprioritymax">sched_get_priority_max</a></li>
|
|
<li><a href="#schedgetprioritymin">sched_get_priority_min</a></li>
|
|
<li><a href="#schedgetrrinterval">sched_get_rr_interval</a></li>
|
|
<li><a href="#schedlockcount">sched_lockcount</a></li>
|
|
<li><a href="#schedlock">sched_lock</a></li>
|
|
<li><a href="#schedsetparam">sched_setparam</a></li>
|
|
<li><a href="#schedsetscheduler">sched_setscheduler</a></li>
|
|
<li><a href="#schedunlock">sched_unlock</a></li>
|
|
<li><a href="#sched_yield">sched_yield</a></li>
|
|
<li><a href="#Semaphores">Counting Semaphore Interfaces</a>
|
|
<li><a href="#semclose">sem_close</a></li>
|
|
<li><a href="#semdestroy">sem_destroy</a></li>
|
|
<li><a href="#semgetvalue">sem_getvalue</a></li>
|
|
<li><a href="#seminit">sem_init</a></li>
|
|
<li><a href="#semopen">sem_open</a></li>
|
|
<li><a href="#sempost">sem_post</a></li>
|
|
<li><a href="#semtrywait">sem_trywait</a></li>
|
|
<li><a href="#semunlink">sem_unlink</a></li>
|
|
<li><a href="#semwait">sem_wait</a></li>
|
|
<li><a href="#setgetscheduler">sched_getscheduler</a></li>
|
|
<li><a href="#sigaction">sigaction</a></li>
|
|
<li><a href="#sigaddset">sigaddset</a></li>
|
|
<li><a href="#sigdelset">sigdelset</a></li>
|
|
<li><a href="#sigemptyset">sigemptyset</a></li>
|
|
<li><a href="#sigfillset">sigfillset</a></li>
|
|
<li><a href="#sigismember">sigismember</a></li>
|
|
<li><a href="#Signals">Signal Interfaces</a>
|
|
<li><a href="#sigpending">sigpending</a></li>
|
|
<li><a href="#sigprocmask">sigprocmask</a></li>
|
|
<li><a href="#sigqueue">sigqueue</a></li>
|
|
<li><a href="#sigsuspend">sigsuspend</a></li>
|
|
<li><a href="#sigtimedwait">sigtimedwait</a></li>
|
|
<li><a href="#sigwaitinfo">sigwaitinfo</a></li>
|
|
<li><a href="#standardio">Standard I/O</a></li>
|
|
<li><a href="#taskactivate">task_activate</a></li>
|
|
<li><a href="#Task_Control">Task Control Interfaces</a>
|
|
<li><a href="#taskcreate">task_create</a></li>
|
|
<li><a href="#taskdelete">task_delete</a></li>
|
|
<li><a href="#taskinit">task_init</a></li>
|
|
<li><a href="#taskrestart">task_restart</a></li>
|
|
<li><a href="#Task_Schedule">Task Scheduling Interfaces</a>
|
|
<li><a href="#Task_Switch">Task Switching Interfaces</a>
|
|
<li><a href="#timercreate">timer_create</a></li>
|
|
<li><a href="#timerdelete">timer_delete</a></li>
|
|
<li><a href="#timergetoverrun">timer_getoverrun</a></li>
|
|
<li><a href="#timergettime">timer_gettime</a></li>
|
|
<li><a href="#ClocksNTimers">Timers</a></li>
|
|
<li><a href="#timersettime">timer_settime</a></li>
|
|
<li><a href="#Watchdogs">Watchdog Timer Interfaces</a>
|
|
<li><a href="#wdcancel">wd_cancel</a></li>
|
|
<li><a href="#wdcreate">wd_create</a></li>
|
|
<li><a href="#wddelete">wd_delete</a></li>
|
|
<li><a href="#wdgettime">wd_gettime</a></li>
|
|
<li><a href="#wdstart">wd_start</a></li>
|
|
</ul>
|
|
|
|
</BODY>
|
|
</HTML>
|