2007-03-28 18:00:57 +02:00
|
|
|
<html>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-28 18:00:57 +02:00
|
|
|
<head>
|
|
|
|
|
<title>NuttX Users Manual</title>
|
|
|
|
|
<meta name="AUTHOR" content="Gregory Nutt">
|
|
|
|
|
</head>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-02-28 02:16:49 +01:00
|
|
|
<body background="backgd.gif">
|
2008-09-12 21:17:15 +02:00
|
|
|
<hr><hr>
|
|
|
|
|
<table width ="100%">
|
|
|
|
|
<tr align="center" bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<h1><big><font color="#3c34ec"><i>NuttX Operating System<p>User's Manual</i></font></big></h1>
|
|
|
|
|
<p><small>by</small></p>
|
|
|
|
|
<p>Gregory Nutt<p>
|
2009-03-14 02:18:07 +01:00
|
|
|
<p>Last Updated: March 13, 2009</p>
|
2008-09-12 21:17:15 +02:00
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
<hr><hr>
|
|
|
|
|
|
|
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Introduction"><h1>1.0 Introduction</h1></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-03-27 23:27:41 +02:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
This manual provides general usage information for the NuttX RTOS from the
|
|
|
|
|
perspective of the firmware developer.
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="overview"><h2>1.1 Document Overview</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
This user's manual is divided into three sections plus a index:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<b>Section 1.0, <a href="#Introduction">Introduction</a></b>:
|
|
|
|
|
This section provides an overview of the NuttX user's manual.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<b>Section 2.0, <a href="#OS_Interfaces">OS Interfaces</a></b>:
|
|
|
|
|
This section details the program interfaces provided by NuttX.
|
|
|
|
|
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>
|
|
|
|
|
<li>Paragraph 2.2 <a href="#Task_Schedule">Task Scheduling Interfaces</a></li>
|
|
|
|
|
<li>Paragraph 2.3 <a href="#Task_Switch">Task Switching Interfaces</a></li>
|
|
|
|
|
<li>Paragraph 2.4 <a href="#Message_Queue">Named Message Queue Interfaces</a></li>
|
|
|
|
|
<li>Paragraph 2.5 <a href="#Semaphores">Counting Semaphore Interfaces</a></li>
|
|
|
|
|
<li>Paragraph 2.6 <a href="#Watchdogs">Watchdog Timer Interfaces</a></li>
|
|
|
|
|
<li>Paragraph 2.7 <a href="#ClocksNTimers">Clocks and Timers</a></li>
|
|
|
|
|
<li>Paragraph 2.8 <a href="#Signals">Signal Interfaces</a></li>
|
|
|
|
|
<li>Paragraph 2.9 <a href="#Pthread">Pthread Interfaces</a></li>
|
2007-07-01 01:42:46 +02:00
|
|
|
<li>Paragraph 2.10 <a href="#Environ">Environment Variables</a></li>
|
2007-12-10 18:15:11 +01:00
|
|
|
<li>Paragraph 2.11 <a href="#FileSystem">File System Interfaces</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li>Paragraph 2.12 <a href="#Network">Network Interfaces</a></li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
</li>
|
|
|
|
|
<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.
|
2008-02-03 18:09:22 +01:00
|
|
|
<ul>
|
|
|
|
|
<li>Paragraph 3.1 <a href="#ScalarType">Scalar Types</a></li>
|
|
|
|
|
<li>Paragraph 3.2 <a href="#HiddenStructures">Hidden Interface Structures</a></li>
|
|
|
|
|
<li>Paragraph 3.3 <a href="#ErrnoAccess">Access to the <code>errno</code> Variable</a></li>
|
|
|
|
|
<li>Paragraph 3.4 <a href="#UserStructures">User Interface Structures</a></li>
|
|
|
|
|
</ul>
|
2007-03-27 23:27:41 +02:00
|
|
|
</li>
|
|
|
|
|
<li>
|
2008-02-03 18:09:22 +01:00
|
|
|
<a href="#index"><b>Index</b></a>
|
2007-03-27 23:27:41 +02:00
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="scope"><h2>1.2 Intended Audience and Scope</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
The intended audience for this document are firmware developers who are implementing applications on NuttX.
|
|
|
|
|
Specifically, this documented is limited to addressing only NuttX RTOS APIs that are available to the application developer.
|
|
|
|
|
As such, this document does not focus on any technical details of the organization or implementation of NuttX.
|
|
|
|
|
Those technical details are provided in the <a href="NuttxPortingGuide.html">NuttX Porting Guide</a>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Information about configuring and building NuttX is also needed by the application developer.
|
|
|
|
|
That information can also be found in the <a href="NuttxPortingGuide.html#configandbuild">NuttX Porting Guide</a>.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="OS_Interfaces"><h1>2.0 OS Interfaces</h1></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-03-27 23:27:41 +02:00
|
|
|
|
|
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
is provided.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> The operation performed by the interface function
|
2007-02-18 00:21:28 +01:00
|
|
|
is discussed.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b> All input parameters are listed along
|
2007-02-18 00:21:28 +01:00
|
|
|
with brief descriptions of each input parameter.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b> All possible values returned by the interface
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b> Any unusual assumptions made by
|
2007-02-18 00:21:28 +01:00
|
|
|
the interface function or any non-obvious limitations to the use
|
|
|
|
|
of the interface function will be indicated here.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Any significant differences between the
|
2007-03-11 18:37:47 +01:00
|
|
|
NuttX interface and its corresponding POSIX interface will be noted
|
2007-02-18 00:21:28 +01:00
|
|
|
here.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-11 18:37:47 +01:00
|
|
|
NOTE: In order to achieve an independent name space for the NuttX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface functions, differences in function names and types are
|
|
|
|
|
to be expected and will not be identified as differences in these
|
|
|
|
|
paragraphs.
|
2008-09-12 21:17:15 +02:00
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Task_Control"><h2>2.1 Task Control Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
<b>Tasks</b>.
|
2007-03-24 16:57:35 +01:00
|
|
|
NuttX is a flat address OS. As such it does not support <i>processes</i>
|
2007-03-20 20:03:11 +01:00
|
|
|
in the way that, say, Linux does.
|
|
|
|
|
NuttX only supports simple threads running within the same address space.
|
2007-03-24 16:57:35 +01:00
|
|
|
However, the programming model makes a distinction between <i>tasks</i>
|
|
|
|
|
and <i>pthreads</i>:
|
2007-03-20 20:03:11 +01:00
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
<ul>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><i>tasks</i> are threads which have a degree of independence
|
|
|
|
|
<li><a href="#Pthread"><i>pthreads</i></a> share some resources.
|
2007-02-18 00:21:28 +01:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="taskcreate">2.1.1 task_create</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
2007-03-20 20:03:11 +01:00
|
|
|
int task_create(char *name, int priority, int stack_size, main_t entry, const char *argv[]);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
This function creates and activates a new task with a
|
|
|
|
|
specified priority and returns its system-assigned ID.
|
|
|
|
|
</p>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>The entry address entry is the address of the "main"
|
2007-02-18 00:21:28 +01:00
|
|
|
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>
|
2007-03-11 18:37:47 +01:00
|
|
|
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
|
2007-02-18 00:21:28 +01:00
|
|
|
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>
|
2007-03-11 18:37:47 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-03-11 18:37:47 +01:00
|
|
|
<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.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
</P>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>
|
2007-02-18 00:21:28 +01:00
|
|
|
Returns the non-zero task ID of the new task or
|
|
|
|
|
ERROR if memory is insufficient or the task cannot be
|
2008-02-03 18:09:22 +01:00
|
|
|
created (<a href="#ErrnoAccess"><code>errno</code></a> is not set).
|
2007-02-18 00:21:28 +01:00
|
|
|
</LI>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following similar interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-03-20 20:03:11 +01:00
|
|
|
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);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
The NuttX task_create() differs from VxWorks' taskSpawn() in the
|
|
|
|
|
following ways:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="taskinit">2.1.2 task_init</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
2007-03-20 20:03:11 +01:00
|
|
|
STATUS task_init(_TCB *tcb, char *name, int priority, uint32 *stack, uint32 stack_size,
|
|
|
|
|
maint_t entry, const char *argv[]);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
This function initializes a Task Control Block (TCB)
|
2007-03-11 18:37:47 +01:00
|
|
|
in preparation for starting a new thread. It performs a subset
|
|
|
|
|
of the functionality of <code>task_create()</code> (see above).
|
2007-02-18 00:21:28 +01:00
|
|
|
</P>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Unlike task_create(), task_init() does not activate the task.
|
|
|
|
|
This must be done by calling task_activate().
|
|
|
|
|
</P>
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-03-11 18:37:47 +01:00
|
|
|
<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.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2008-02-03 18:09:22 +01:00
|
|
|
a new, unique task ID to the TCB (<a href="#ErrnoAccess"><code>errno</code></a> is not set).</P>
|
2007-03-27 23:27:41 +02:00
|
|
|
</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
|
2007-02-18 00:21:28 +01:00
|
|
|
mechanism to initialize and start a new task.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following similar interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-03-20 20:03:11 +01:00
|
|
|
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);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
The NuttX task_init() differs from VxWorks' taskInit() in the
|
|
|
|
|
following ways:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="taskactivate">2.1.3 task_activate</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
STATUS task_activate( _TCB *tcb );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function activates tasks created by task_init().
|
2007-02-18 00:21:28 +01:00
|
|
|
Without activation, a task is ineligible for execution by the
|
|
|
|
|
scheduler.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>tcb</I>. The TCB for the task for the task (same as the
|
2007-02-18 00:21:28 +01:00
|
|
|
task_init argument).
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
2008-02-03 18:09:22 +01:00
|
|
|
<li>OK, or ERROR if the task cannot be activated (<a href="#ErrnoAccess"><code>errno</code></a> is not set).
|
2007-03-27 23:27:41 +02:00
|
|
|
</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
|
2007-02-18 00:21:28 +01:00
|
|
|
mechanism to initialize and start a new task.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following similar interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
STATUS taskActivate( int tid );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
The NuttX task_activate() differs from VxWorks' taskActivate() in the
|
|
|
|
|
following ways:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Function name
|
|
|
|
|
<li>With VxWork's taskActivate, the pid argument is supposed to be
|
2007-02-18 00:21:28 +01:00
|
|
|
the pointer to the WIND_TCB cast to an integer.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="taskdelete">2.1.4 task_delete</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
STATUS task_delete( pid_t pid );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function causes a specified task to cease
|
2007-02-18 00:21:28 +01:00
|
|
|
to exist -- its stack and TCB will be deallocated. This function
|
|
|
|
|
is the companion to task_create().
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>pid</I>. The task ID of the task to delete. An ID of
|
2007-02-18 00:21:28 +01:00
|
|
|
zero signifies the calling task.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>OK, or ERROR if the task cannot be deleted.
|
2008-02-03 18:09:22 +01:00
|
|
|
This function can fail if the provided pid does not correspond to a task (<a href="#ErrnoAccess"><code>errno</code></a> is not set)
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following similar interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
STATUS taskDelete( int tid );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
The NuttX task_delete() differs from VxWorks' taskDelete() in
|
|
|
|
|
the following ways:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>No support is provided for calling the tasks deletion routines
|
2007-02-18 00:21:28 +01:00
|
|
|
(because taskDeleteHookAdd() is not supported).
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>Deletion of self is not supported. Use _exit();
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="exit">2.1.5 exit</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
void exit( int code );
|
|
|
|
|
|
|
|
|
|
#include <nuttx/unistd.h>
|
|
|
|
|
void _exit( int code );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function causes the calling task to cease
|
2007-02-18 00:21:28 +01:00
|
|
|
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().
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>code</I>. (ignored)
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b> None.
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> This is equivalent to the ANSI interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
void exit( int code );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
And the unix interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
void _exit( int code );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
The NuttX exit() differs from ANSI exit() in the following ways:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>The <I>code</I> parameter is ignored.
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="taskrestart">2.1.6 task_restart</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
STATUS task_restart( pid_t pid );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function "restarts" a task.
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>pid</I>. The task ID of the task to delete. An ID of
|
2007-02-18 00:21:28 +01:00
|
|
|
zero signifies the calling task.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
2007-02-18 00:21:28 +01:00
|
|
|
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>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following similar interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
STATUS taskRestart (int tid);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
The NuttX task_restart() differs from VxWorks' taskRestart() in the following ways:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Restart of the currently running task is not supported.
|
|
|
|
|
<li>The VxWorks description says that the ID, priority, etc. take
|
2007-02-18 00:21:28 +01:00
|
|
|
the value that they had when the task was <I>terminated</I>.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="getpid">2.1.7 getpid</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <unistd.h>
|
|
|
|
|
pid_t getpid( void );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function returns the task ID of the
|
2007-02-18 00:21:28 +01:00
|
|
|
calling task. The task ID will be invalid if called at the interrupt
|
|
|
|
|
level.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
Compatible with the POSIX interface of the same name.
|
2008-09-12 21:17:15 +02:00
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Task_Schedule"><h2>2.2 Task Scheduling Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedsetparam">2.2.1 sched_setparam</a></H3>
|
2007-03-24 16:57:35 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
2007-03-24 16:57:35 +01:00
|
|
|
int sched_setparam(pid_t pid, const struct sched_param *param);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Description:</b>
|
2007-03-24 16:57:35 +01:00
|
|
|
This function sets the priority of the task specified by pid input parameter.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
NOTE: Setting a task's priority to the same value has the similar
|
|
|
|
|
effect to <code>sched_yield()</code>: The task will be moved to after all
|
|
|
|
|
other tasks with the same priority.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>pid</code>.
|
|
|
|
|
The task ID of the task.
|
|
|
|
|
If <code>pid</code> is zero, the priority of the calling task is set.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>param</code>.
|
|
|
|
|
A structure whose member <code>sched_priority</code> is the integer priority.
|
|
|
|
|
The range of valid priority numbers is from <code>SCHED_PRIORITY_MIN</code> through <code>SCHED_PRIORITY_MAX</code>.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
On success, sched_setparam() returns 0 (OK).
|
2008-02-03 18:09:22 +01:00
|
|
|
On error, -1 (ERROR) is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately.
|
2007-03-24 16:57:35 +01:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-24 16:57:35 +01:00
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>.
|
|
|
|
|
The parameter <code>param</code> is invalid or does not make sense for the current scheduling policy.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EPERM</code>.
|
|
|
|
|
The calling task does not have appropriate privileges.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>ESRCH</code>.
|
|
|
|
|
The task whose ID is <code>pid</code> could not be found.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>POSIX Compatibility:</b>
|
2007-03-24 16:57:35 +01:00
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
Differences from the full POSIX implementation include:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>The range of priority values for the POSIX call is 0 to 255.</li>
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedgetparam">2.2.2 sched_getparam</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
int sched_getparam (pid_t pid, struct sched_param *param);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function gets the scheduling priority
|
2007-02-18 00:21:28 +01:00
|
|
|
of the task specified by pid.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>pid</code>. The task ID of the task.
|
|
|
|
|
If pid is zero, the priority of the calling task is returned.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>param</code>.
|
|
|
|
|
A structure whose member <code>sched_priority</code> is the integer priority.
|
|
|
|
|
The task's priority is copied to the <code>sched_priority</code> element of this structure.
|
|
|
|
|
</li>
|
|
|
|
|
</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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedsetscheduler">2.2.3 sched_setscheduler</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
int sched_setscheduler (pid_t pid, int policy, const struct sched_param *param);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<I>pid</I>. The task ID of the task. If pid is zero, the
|
2007-02-18 00:21:28 +01:00
|
|
|
priority of the calling task is set.
|
2007-03-27 23:27:41 +02:00
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<I>policy</I>. Scheduling policy requested (either SCHED_FIFO or SCHED_RR).
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>param<code>. A structure whose member sched_priority is the
|
2007-02-18 00:21:28 +01:00
|
|
|
integer priority. The range of valid priority numbers is from
|
|
|
|
|
SCHED_PRIORITY_MIN through SCHED_PRIORITY_MAX.
|
2007-03-27 23:27:41 +02:00
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
On success, <i>sched_setscheduler()</i> returns OK (zero). On
|
2008-02-03 18:09:22 +01:00
|
|
|
error, ERROR (-1) is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-02-18 00:21:28 +01:00
|
|
|
</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>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="setgetscheduler">2.2.4 sched_getscheduler</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
int sched_getscheduler (pid_t pid);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
<i>sched_getscheduler()</i> returns the scheduling policy
|
2007-03-20 20:03:11 +01:00
|
|
|
currently applied to the task identified by pid. If
|
2007-02-18 00:21:28 +01:00
|
|
|
pid equals zero, the policy of the calling process will
|
|
|
|
|
be retrieved.
|
|
|
|
|
*
|
|
|
|
|
* Inputs:
|
|
|
|
|
*
|
|
|
|
|
* Return Value:
|
|
|
|
|
|
|
|
|
|
This function returns the current scheduling
|
|
|
|
|
policy.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>pid</I>.
|
2007-02-18 00:21:28 +01:00
|
|
|
The task ID of the task to query.
|
|
|
|
|
If pid is zero, the calling task is queried.
|
|
|
|
|
</LI>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
2007-02-18 00:21:28 +01:00
|
|
|
On success, <i>sched_getscheduler()</i> returns the policy for
|
|
|
|
|
the task (either SCHED_FIFO or SCHED_RR).
|
2008-02-03 18:09:22 +01:00
|
|
|
On error, ERROR (-1) is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-02-18 00:21:28 +01:00
|
|
|
<ul>
|
|
|
|
|
<li>ESRCH The task whose ID is pid could not be found.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the full POSIX implementation include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
2008-02-03 18:09:22 +01:00
|
|
|
<li>Does not report errors via <a href="#ErrnoAccess"><code>errno</code></a>.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="sched_yield">2.2.5 sched_yield</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
int sched_yield( void );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function forces the calling task to give
|
2007-02-18 00:21:28 +01:00
|
|
|
up the CPU (only to other tasks at the same priority).
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedgetprioritymax">2.2.6 sched_get_priority_max</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
int sched_get_priority_max (int policy)
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function returns the value of the highest
|
2007-02-18 00:21:28 +01:00
|
|
|
possible task priority for a specified scheduling policy.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedgetprioritymin">2.2.7 sched_get_priority_min</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
int sched_get_priority_min (int policy);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function returns the value of the lowest
|
2007-02-18 00:21:28 +01:00
|
|
|
possible task priority for a specified scheduling policy.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedgetrrinterval">2.2.8 sched_get_rr_interval</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
int sched_get_rr_interval (pid_t pid, struct timespec *interval);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li><I>pid</I>. The task ID of the task. If pid is zero, the
|
2007-02-18 00:21:28 +01:00
|
|
|
priority of the calling task is returned.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>interval</I>. A structure used to return the time slice.
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
On success, sched_rr_get_interval() returns OK (0). On
|
2008-02-03 18:09:22 +01:00
|
|
|
error, ERROR (-1) is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set to:
|
2007-02-18 00:21:28 +01:00
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
</P>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Task_Switch"><h2>2.3 Task Switching Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
STATUS sched_lock( void );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function disables context switching by
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the comparable interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
STATUS taskLock( void );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedunlock">2.3.2 sched_unlock</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
STATUS sched_unlock( void );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function decrements the preemption lock
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the comparable interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
STATUS taskUnlock( void );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="schedlockcount">2.3.3 sched_lockcount</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <sched.h>
|
|
|
|
|
sint32 sched_lockcount( void )
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function returns the current value of
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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.
|
2008-09-12 21:17:15 +02:00
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Message_Queue"><h2>2.4 Named Message Queue Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-29 15:25:18 +02:00
|
|
|
<li><a href="#mqtimedsend">2.4.5 mq_timedsend</a></li>
|
|
|
|
|
<li><a href="#mqreceive">2.4.6 mq_receive</a></li>
|
|
|
|
|
<li><a href="#mqtimedreceive">2.4.7 mq_timedreceive</a></li>
|
|
|
|
|
<li><a href="#mqnotify">2.4.8 mq_notify</a></li>
|
|
|
|
|
<li><a href="#mqsetattr">2.4.9 mq_setattr</a></li>
|
|
|
|
|
<li><a href="#mqgetattr">2.4.10 mq_getattr</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="mqopen">2.4.1 mq_open</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
|
|
|
|
mqd_t mq_open( const char *mqName, int oflags, ... );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function establish a connection between
|
2007-02-18 00:21:28 +01:00
|
|
|
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().
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
exist.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>O_EXCL</I>. Name must not exist when opened.
|
|
|
|
|
<li><I>O_NONBLOCK</I>. Don't wait for data.
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>... Optional parameters</I>.
|
2007-02-18 00:21:28 +01:00
|
|
|
When the O_CREAT flag is specified, POSIX requires that a third
|
|
|
|
|
and fourth parameter be supplied:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li><I>mode</I>. The mode parameter is of type mode_t. In the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
specification, this mode value provides file permission bits for the
|
|
|
|
|
message queue. This parameter is required but not used in the present
|
|
|
|
|
implementation.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>attr</I>. A pointer to an mq_attr that is provided to initialize.
|
2007-02-18 00:21:28 +01:00
|
|
|
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).
|
2007-03-27 23:27:41 +02:00
|
|
|
</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
|
2007-02-18 00:21:28 +01:00
|
|
|
of the same name.
|
|
|
|
|
Differences from the full POSIX implementation include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>The mq_msgsize attributes determines the maximum size of a message that
|
2007-02-18 00:21:28 +01:00
|
|
|
may be sent or received. In the present implementation, this maximum
|
|
|
|
|
message size is limited at 22 bytes.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="mqclose">2.4.2 mq_close</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
|
|
|
|
int mq_close( mqd_t mqdes );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function is used to indicate that the
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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,
|
2007-02-18 00:21:28 +01:00
|
|
|
-1 (ERROR).
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
2007-03-28 18:00:57 +02:00
|
|
|
<li>The behavior of a task that is blocked on either a <code>mq_send()</code> or
|
|
|
|
|
<code>mq_receive()</code> is undefined when <code>mq_close()</code> is called.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>The result of using this message queue descriptor after successful
|
2007-02-18 00:21:28 +01:00
|
|
|
return from mq_close() is undefined.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX interface
|
2007-02-18 00:21:28 +01:00
|
|
|
of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="mqunlink">2.4.3 mq_unlink</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
|
|
|
|
int mq_unlink( const char *mqName );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function removes the message queue named
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="mqsend">2.4.4 mq_send</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
</p>
|
|
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
2007-03-28 18:00:57 +02:00
|
|
|
int mq_send(mqd_t mqdes, const void *msg, size_t msglen, int prio);
|
|
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Description:</b>
|
|
|
|
|
This function adds the specified message, <code>msg</code>,
|
|
|
|
|
to the message queue, <code>mqdes</code>.
|
|
|
|
|
The <code>msglen</code> parameter specifies the length of the message in bytes pointed to by <code>msg</code>.
|
|
|
|
|
This length must not exceed the maximum message length from the <code>mq_getattr()</code>.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
If the message queue is not full, <code>mq_send()</code> will place the <code>msg</code>
|
|
|
|
|
in the message queue at the position indicated by the <code>prio</code> argument.
|
|
|
|
|
Messages with higher priority will be inserted before lower priority messages
|
|
|
|
|
The value of <code>prio</code> must not exceed <code>MQ_PRIO_MAX</code>.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
If the specified message queue is full and <code>O_NONBLOCK</code> is not
|
|
|
|
|
set in the message queue, then <code>mq_send()</code> will block until space
|
|
|
|
|
becomes available to the queue the message.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
If the message queue is full and <code>NON_BLOCK</code> is set, the message
|
|
|
|
|
is not queued and <code>ERROR</code> is returned.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
2007-03-28 18:00:57 +02:00
|
|
|
<li><code>mqdes</code>. Message queue descriptor.</li>
|
|
|
|
|
<li><code>msg</code>. Message to send.</li>
|
|
|
|
|
<li><code>msglen</code>. The length of the message in bytes.</li>
|
|
|
|
|
<li><code>prio</code>. The priority of the message.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
On success, <code>mq_send()</code> returns 0 (<code>OK</code>);
|
2008-02-03 18:09:22 +01:00
|
|
|
on error, -1 (<code>ERROR</code>) is returned, with <a href="#ErrnoAccess"><code>errno</code></a> set
|
2007-03-28 18:00:57 +02:00
|
|
|
to indicate the error:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
2007-03-28 18:00:57 +02:00
|
|
|
<li>
|
|
|
|
|
<code>EAGAIN</code>.
|
|
|
|
|
The queue was empty, and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>.
|
|
|
|
|
Either <code>msg</code> or <code>mqdes</code> is <code>NULL</code> or the value of <code>prio</code> is invalid.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EPERM</code>.
|
|
|
|
|
Message queue opened not opened for writing.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EMSGSIZE</code>.
|
|
|
|
|
<code>msglen</code> was greater than the <code>maxmsgsize</code> attribute of the message queue.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINTR</code>.
|
|
|
|
|
The call was interrupted by a signal handler.
|
|
|
|
|
</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-03-28 18:00:57 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-29 15:25:18 +02:00
|
|
|
<h3><a name="mqtimedsend">mq_timedsend</a></h3>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <mqueue.h>
|
|
|
|
|
int mq_timedsend(mqd_t mqdes, const char *msg, size_t msglen, int prio,
|
|
|
|
|
const struct timespec *abstime);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
This function adds the specified message, <code>msg</code>,
|
|
|
|
|
to the message queue, <code>mqdes</code>.
|
|
|
|
|
The <code>msglen</code> parameter specifies the length of the message in bytes pointed to by <code>msg</code>.
|
|
|
|
|
This length must not exceed the maximum message length from the <code>mq_getattr()</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the message queue is not full, <code>mq_timedsend()</code> will place the <code>msg</code>
|
|
|
|
|
in the message queue at the position indicated by the <code>prio</code> argument.
|
|
|
|
|
Messages with higher priority will be inserted before lower priority messages
|
|
|
|
|
The value of <code>prio</code> must not exceed <code>MQ_PRIO_MAX</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the specified message queue is full and <code>O_NONBLOCK</code> is not
|
|
|
|
|
set in the message queue, then <code>mq_send()</code> will block until space
|
|
|
|
|
becomes available to the queue the message or until a timeout occurs.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<code>mq_timedsend()</code> behaves just like <code>mq_send()</code>, except
|
|
|
|
|
that if the queue is full and the <code>O_NONBLOCK</code> flag is not enabled
|
|
|
|
|
for the message queue description, then <code>abstime</code> points to a
|
|
|
|
|
structure which specifies a ceiling on the time for which the call will block.
|
|
|
|
|
This ceiling is an absolute timeout in seconds and nanoseconds since the
|
|
|
|
|
Epoch (midnight on the morning of 1 January 1970).
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the message queue is full, and the timeout has already expired by the time
|
|
|
|
|
of the call, <code>mq_timedsend()<code> returns immediately.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>mqdes</code>. Message queue descriptor.</li>
|
|
|
|
|
<li><code>msg</code>. Message to send.</li>
|
|
|
|
|
<li><code>msglen</code>. The length of the message in bytes.</li>
|
|
|
|
|
<li><code>prio</code>. The priority of the message.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
On success, <code>mq_send()</code> returns 0 (<code>OK</code>);
|
2008-02-03 18:09:22 +01:00
|
|
|
on error, -1 (<code>ERROR</code>) is returned, with <a href="#ErrnoAccess"><code>errno</code></a> set
|
2007-03-29 15:25:18 +02:00
|
|
|
to indicate the error:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EAGAIN</code>.
|
|
|
|
|
The queue was empty, and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>.
|
|
|
|
|
Either <code>msg</code> or <code>mqdes</code> is <code>NULL</code> or the value of <code>prio</code> is invalid.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EPERM</code>.
|
|
|
|
|
Message queue opened not opened for writing.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EMSGSIZE</code>.
|
|
|
|
|
<code>msglen</code> was greater than the <code>maxmsgsize</code> attribute of the message queue.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINTR</code>.
|
|
|
|
|
The call was interrupted by a signal handler.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2007-03-28 18:00:57 +02:00
|
|
|
<h3><a name="mqreceive">2.4.5 mq_receive</a></h3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
2007-03-29 15:25:18 +02:00
|
|
|
ssize_t mq_receive(mqd_t mqdes, void *msg, size_t msglen, int *prio);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Description:</b>
|
|
|
|
|
This function receives the oldest of the highest priority messages from the message
|
|
|
|
|
queue specified by <code>mqdes</code>.
|
|
|
|
|
If the size of the buffer in bytes, <code>msgLen</code>, is less than the
|
|
|
|
|
<code>mq_msgsize</code> attribute of the message queue, <code>mq_receive()</code> will
|
|
|
|
|
return an error.
|
|
|
|
|
Otherwise, the selected message is removed from the queue and copied to <code>msg</code>.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
If the message queue is empty and <code>O_NONBLOCK</code> was not set, <code>mq_receive()</code>
|
|
|
|
|
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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
If the queue is empty and <code>O_NONBLOCK</code> is set, <code>ERROR</code> will be returned.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
2007-03-28 18:00:57 +02:00
|
|
|
<li><code>mqdes</code>. Message Queue Descriptor.</li>
|
|
|
|
|
<li><code>msg</code>. Buffer to receive the message.</li>
|
|
|
|
|
<li><code>msglen</code>. Size of the buffer in bytes.</li>
|
|
|
|
|
<li><code>prio</code>. If not NULL, the location to store message priority.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Returned Values:</b>.
|
|
|
|
|
One success, the length of the selected message in bytes is returned.
|
2008-02-03 18:09:22 +01:00
|
|
|
On failure, -1 (<code>ERROR</code>) is returned and the <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-03-28 18:00:57 +02:00
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
2007-03-28 18:00:57 +02:00
|
|
|
<li>
|
|
|
|
|
<code>EAGAIN</code>
|
|
|
|
|
The queue was empty and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EPERM</code>
|
|
|
|
|
Message queue opened not opened for reading.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EMSGSIZE</code>
|
|
|
|
|
<code>msglen</code> was less than the <code>maxmsgsize</code> attribute of the message queue.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINTR</code>
|
|
|
|
|
The call was interrupted by a signal handler.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>
|
|
|
|
|
Invalid <code>msg</code> or <code>mqdes</code>
|
|
|
|
|
</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-29 15:25:18 +02:00
|
|
|
<h3><a name="mqtimedreceive">2.4.6 mq_timedreceive</a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <mqueue.h>
|
|
|
|
|
ssize_t mq_timedreceive(mqd_t mqdes, void *msg, size_t msglen,
|
|
|
|
|
int *prio, const struct timespec *abstime);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
This function receives the oldest of the highest priority messages from the message
|
|
|
|
|
queue specified by <code>mqdes</code>.
|
|
|
|
|
If the size of the buffer in bytes, <code>msgLen</code>, is less than the
|
|
|
|
|
<code>mq_msgsize</code> attribute of the message queue, <code>mq_timedreceive()</code> will
|
|
|
|
|
return an error.
|
|
|
|
|
Otherwise, the selected message is removed from the queue and copied to <code>msg</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the message queue is empty and <code>O_NONBLOCK</code> was not set, <code>mq_timedreceive()</code>
|
|
|
|
|
will block until a message is added to the message queue (or until a timeout occurs).
|
|
|
|
|
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>
|
|
|
|
|
<p>
|
|
|
|
|
<code>mq_timedreceive()</code> behaves just like <code>mq_receive()<code>, except
|
|
|
|
|
that if the queue is empty and the <code>O_NONBLOCK<c/ode> flag is not enabled
|
|
|
|
|
for the message queue description, then <code>abstime</code> points to a structure
|
|
|
|
|
which specifies a ceiling on the time for which the call will block.
|
|
|
|
|
This ceiling is an absolute timeout in seconds and nanoseconds since the Epoch
|
|
|
|
|
(midnight on the morning of 1 January 1970).
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If no message is available, and the timeout has already expired by the time of
|
|
|
|
|
the call, <code>mq_timedreceive()</code> returns immediately.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>mqdes</code>. Message Queue Descriptor.</li>
|
|
|
|
|
<li><code>msg</code>. Buffer to receive the message.</li>
|
|
|
|
|
<li><code>msglen</code>. Size of the buffer in bytes.</li>
|
|
|
|
|
<li><code>prio</code>. If not NULL, the location to store message priority.
|
|
|
|
|
<li><code>abstime</code>. The absolute time to wait until a timeout is declared.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>.
|
|
|
|
|
One success, the length of the selected message in bytes is returned.
|
2008-02-03 18:09:22 +01:00
|
|
|
On failure, -1 (<code>ERROR</code>) is returned and the <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-03-29 15:25:18 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EAGAIN</code>:
|
|
|
|
|
The queue was empty and the <code>O_NONBLOCK</code> flag was set for the message queue description referred to by <code>mqdes</code>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EPERM</code>:
|
|
|
|
|
Message queue opened not opened for reading.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EMSGSIZE</code>:
|
|
|
|
|
<code>msglen</code> was less than the <code>maxmsgsize</code> attribute of the message queue.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINTR</code>:
|
|
|
|
|
The call was interrupted by a signal handler.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>:
|
|
|
|
|
Invalid <code>msg</code> or <code>mqdes</code> or <code>abstime</code>
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>ETIMEDOUT</code>:
|
|
|
|
|
The call timed out before a message could be transferred.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3><a name="mqnotify">2.4.7 mq_notify</a></h3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
2007-03-28 18:00:57 +02:00
|
|
|
int mq_notify(mqd_t mqdes, const struct sigevent *notification);
|
|
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> If the "notification" input parameter
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
When the notification is sent to the registered task, its registration
|
|
|
|
|
will be removed. The message queue will then be available for
|
|
|
|
|
registration.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>mqdes</I>. Message queue descriptor
|
|
|
|
|
<li><I>notification</I>. Real-time signal structure containing:
|
|
|
|
|
<ul>
|
2008-02-03 18:09:22 +01:00
|
|
|
<li><I>sigev_notify</I>. Should be SIGEV_SIGNAL (but actually
|
2007-02-18 00:21:28 +01:00
|
|
|
ignored)
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
of the same name.
|
|
|
|
|
Differences from the full POSIX implementation include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>The notification signal will be sent to the registered task even if
|
2007-02-18 00:21:28 +01:00
|
|
|
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."
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-29 15:25:18 +02:00
|
|
|
<H3><a name="mqsetattr">2.4.8 mq_setattr</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
|
|
|
|
int mq_setattr( mqd_t mqdes, const struct mq_attr *mqStat,
|
|
|
|
|
struct mq_attr *oldMqStat);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function sets the attributes associated
|
2007-02-18 00:21:28 +01:00
|
|
|
with the specified message queue "mqdes." Only the "O_NONBLOCK"
|
|
|
|
|
bit of the "mq_flags" can be changed.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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()).
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
(ERROR).
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-29 15:25:18 +02:00
|
|
|
<H3><a name="mqgetattr">2.4.9 mq_getattr</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <mqueue.h>
|
|
|
|
|
int mq_getattr( mqd_t mqdes, struct mq_attr *mqStat);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This functions gets status information and
|
2007-02-18 00:21:28 +01:00
|
|
|
attributes associated with the specified message queue.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
attributes include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2008-09-12 21:17:15 +02:00
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Semaphores"><h2>2.5 Counting Semaphore Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2009-03-14 02:18:07 +01:00
|
|
|
<a name="priorityinversion"><b>Priority Inversion</b></a>.
|
|
|
|
|
Proper use of semaphores avoids the issues of <code>sched_lock()</code>.
|
|
|
|
|
However, consider the following example:
|
2007-03-20 20:03:11 +01:00
|
|
|
<OL>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>Some low-priority task, <I>Task C</I>, acquires a semphore in order to
|
2007-03-20 20:03:11 +01:00
|
|
|
get exclusive access to a protected resource.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>Task C</I> is suspended to allow some high-priority task,</li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<I>Task A</I>, to execute.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>Task A</I> attempts to acquire the semaphore held by <I>Task C</I> and
|
2007-03-20 20:03:11 +01:00
|
|
|
gets blocked until <I>Task C</I> relinquishes the semaphore.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>Task C</I> is allowed to execute again, but gets suspended by some
|
2007-03-20 20:03:11 +01:00
|
|
|
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
|
2009-03-09 00:33:41 +01:00
|
|
|
buzz-word for this behavior is <I>priority inheritance</I>). NuttX
|
|
|
|
|
supports this behavior, but only if <code>CONFIG_PRIORITY_INHERITANCE</code>
|
|
|
|
|
is defined in your OS configuration file. If <code>CONFIG_PRIORITY_INHERITANCE</code>
|
|
|
|
|
is not defined, then it is left to the designer to provide implementations
|
|
|
|
|
that will not suffer from priority inversion.
|
2007-03-20 20:03:11 +01:00
|
|
|
The designer may, as examples:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Implement all tasks that need the semphore-managed resources at the
|
2007-03-20 20:03:11 +01:00
|
|
|
same priority level,</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>Boost the priority of the low-priority task before the semaphore is
|
2007-03-20 20:03:11 +01:00
|
|
|
acquired, or</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>Use sched_lock() in the low-priority task.</li>
|
|
|
|
|
</ul>
|
2009-03-14 02:18:07 +01:00
|
|
|
<p>
|
|
|
|
|
<a name="priorityinheritance"><b>Priority Inheritance</b></a>.
|
|
|
|
|
As mentioned, NuttX does support <i>priority inheritance</i> provided that
|
|
|
|
|
<code>CONFIG_PRIORITY_INHERITANCE</code> is defined in your OS configuration file.
|
|
|
|
|
However, the implementation and configuration of the priority inheritance feature
|
|
|
|
|
is sufficiently complex that more needs to be said.
|
|
|
|
|
How can a feature that can be described by a single, simple sentence require such
|
|
|
|
|
a complex implementation:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<b><code>CONFIG_SEM_PREALLOCHOLDERS</code>.</b>
|
|
|
|
|
First of all, in NuttX priority inheritance is implement on POSIX counting
|
|
|
|
|
semaphores. The reason for this is that these semaphores are the most
|
|
|
|
|
primitive waiting mechanism in NuttX; Most other waiting facilities are
|
|
|
|
|
based on semaphores. So if priority inheritance is implemented for POSIX
|
|
|
|
|
counting semaphores, then most NuttX waiting mechanisms will have this
|
|
|
|
|
capability.
|
|
|
|
|
<p>
|
|
|
|
|
Complexity arises because counting semaphores can have numerous
|
|
|
|
|
holders of semaphore counts. Therefore, in order to implement
|
|
|
|
|
priority inheritance across all holders, then internal data
|
|
|
|
|
structures must be allocated to manage the various holders associated
|
|
|
|
|
with a semaphore.
|
|
|
|
|
The setting <code>CONFIG_SEM_PREALLOCHOLDERS</code> defines the maximum
|
|
|
|
|
number of different threads (minus one per semaphore instance) that can
|
|
|
|
|
take counts on a semaphore with priority inheritance support.
|
|
|
|
|
This setting defines the size of a single pool of preallocated structures.
|
|
|
|
|
It may be set to zero if priority inheritance is disabled OR if you
|
|
|
|
|
are only using semaphores as mutexes (only one holder) OR if no more
|
|
|
|
|
than two threads participate using a counting semaphore.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The cost associated with setting <code>CONFIG_SEM_PREALLOCHOLDERS</code>
|
|
|
|
|
is slightly increased code size and around 6-12 bytes times the value
|
|
|
|
|
of <code>CONFIG_SEM_PREALLOCHOLDERS</code>.
|
|
|
|
|
</p>
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<b><code>CONFIG_SEM_NNESTPRIO</code>:</b>
|
|
|
|
|
In addition, there may be multiple threads of various priorities that
|
|
|
|
|
need to wait for a count from the semaphore.
|
|
|
|
|
These, the lower priority thread holding the semaphore may have to
|
|
|
|
|
be boosted numerous time and, to make things more complex, will have
|
|
|
|
|
to keep track of all of the boost priorities values in in order to
|
|
|
|
|
correctly restore the priorities after a count has been handed out
|
|
|
|
|
to the higher priority thread.
|
|
|
|
|
The <code>CONFIG_SEM_NNESTPRIO</code> defines the size of an array,
|
|
|
|
|
one array per active thread.
|
|
|
|
|
This setting is the maximum number of higher priority threads (minus
|
|
|
|
|
1) than can be waiting for another thread to release a count on a semaphore.
|
|
|
|
|
This value may be set to zero if no more than one thread is expected to
|
|
|
|
|
wait for a semaphore.
|
|
|
|
|
<p>
|
|
|
|
|
The cost associated with setting <code>CONFIG_SEM_NNESTPRIO</code>
|
|
|
|
|
is slightly increased code size and (<code>CONFIG_SEM_PREALLOCHOLDERS</code> + 1)
|
|
|
|
|
times the maximum number of active threads.
|
|
|
|
|
</p>
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<b>Increased Susceptibility to Bad Thread Behavior</b>.
|
|
|
|
|
These various structures tie the semaphore implementation more tightly to
|
|
|
|
|
the behavior of the implementation. For examples, if a thread executes while
|
|
|
|
|
holding counts on a semaphore, or if a thread exits without call <code>sem_destroy()</code>
|
|
|
|
|
then. Or what if the thread with the boosted priority reprioritizes itself?
|
|
|
|
|
The NuttX implement of priority inheritance attempts to handle all of these
|
|
|
|
|
types of corner cases, but it is very likely that some are missed.
|
|
|
|
|
The worst case result is that memory could by stranded within the priority
|
|
|
|
|
inheritance logic.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_init ( sem_t *sem, int pshared, unsigned int value );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function initializes the UN-NAMED semaphore
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the full POSIX implementation include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>pshared is not used.
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="semdestroy">2.5.2 sem_destroy</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_destroy ( sem_t *sem );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function is used to destroy the un-named semaphore
|
2007-02-18 00:21:28 +01:00
|
|
|
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>.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
The effect of destroying a semaphore upon which other tasks are currently
|
|
|
|
|
blocked is undefined.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="semopen">2.5.3 sem_open</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
sem_t *sem_open ( const char *name, int oflag, ...);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function establishes a connection between
|
2007-02-18 00:21:28 +01:00
|
|
|
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().
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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()).
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>name</I>. Semaphore name
|
|
|
|
|
<li><I>oflag</I>. Semaphore creation options. This may one of
|
2007-02-18 00:21:28 +01:00
|
|
|
the following bit settings:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li><I>oflag</I> = 0: Connect to the semaphore only if it already
|
2007-02-18 00:21:28 +01:00
|
|
|
exists.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>oflag</I> = O_CREAT: Connect to the semaphore if it exists,
|
2007-02-18 00:21:28 +01:00
|
|
|
otherwise create the semaphore.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>oflag</I> = O_CREAT with O_EXCL (O_CREAT|O_EXCL): Create
|
2007-02-18 00:21:28 +01:00
|
|
|
a new semaphore unless one of this name already exists.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<li>... Optional parameters.
|
2007-02-18 00:21:28 +01:00
|
|
|
NOTE: When the O_CREAT flag is specified, POSIX requires that a third
|
|
|
|
|
and fourth parameter be supplied:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li><I>mode</I>. The mode parameter is of type mode_t.
|
2007-02-18 00:21:28 +01:00
|
|
|
This parameter is required but not used in the present
|
|
|
|
|
implementation.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>value</I>. The value parameter is type unsigned int. The semaphore
|
2007-02-18 00:21:28 +01:00
|
|
|
is created with an initial value of <I>value</I>. Valid initial values for
|
2007-03-20 17:51:12 +01:00
|
|
|
semaphores must be less than or equal to <I>SEM_VALUE_MAX</I> (defined in
|
|
|
|
|
<CODE>include/limits.h</CODE>).
|
2007-03-27 23:27:41 +02:00
|
|
|
</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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the full POSIX implementation include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Treatment of links/connections is highly simplified. It is
|
2007-02-18 00:21:28 +01:00
|
|
|
just a counting semaphore.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="semclose">2.5.4 sem_close</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_close ( sem_t *sem );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function is called to indicate that the
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Care must be taken to avoid risking the deletion of a semaphore
|
|
|
|
|
that another calling task has already locked.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
has already locked.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>sem_close() must not be called with an un-named semaphore.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="semunlink">2.5.5 sem_unlink</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_unlink ( const char *name );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function will remove the semaphore named by the
|
2007-02-18 00:21:28 +01:00
|
|
|
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().
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
has already locked.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>sem_unlink() must not be called with an un-named semaphore.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the full POSIX implementation include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Treatment of links/connections is highly simplified. It is
|
2007-02-18 00:21:28 +01:00
|
|
|
just a counting semaphore.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>Calls to sem_open() to re-create or re-connect to the semaphore may
|
2007-02-18 00:21:28 +01:00
|
|
|
refer to the same semaphore; POSIX specifies that a new semaphore with the
|
|
|
|
|
same name should be created after sem_unlink() is called.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="semwait">2.5.6 sem_wait</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_wait ( sem_t *sem );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function attempts to lock the semaphore
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
If <I>sem_wait</I> returns -1 (ERROR) then the cause of the failure
|
2008-02-03 18:09:22 +01:00
|
|
|
will be indicated by the thread-specific <a href="#ErrnoAccess"><code>errno</code></a>.
|
|
|
|
|
The following lists the possible values for <a href="#ErrnoAccess"><code>errno</code></a>:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>EINVAL</I>: Indicates that the <I>sem</I> input parameter is
|
2007-02-18 00:21:28 +01:00
|
|
|
not valid.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>EINTR</I>: Indicates that the wait was interrupt by a signal
|
2007-02-18 00:21:28 +01:00
|
|
|
received by this task. In this case, the semaphore has not be acquired.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="semtrywait">2.5.7 sem_trywait</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_trywait ( sem_t *sem );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function locks the specified semaphore
|
2007-02-18 00:21:28 +01:00
|
|
|
only if the semaphore is currently not locked. In any event, the call
|
|
|
|
|
returns without blocking.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
If <I>sem_wait</I> returns -1 (ERROR) then the cause of the failure
|
2008-02-03 18:09:22 +01:00
|
|
|
will be indicated by the thread-specific <a href="#ErrnoAccess"><code>errno</code></a>.
|
|
|
|
|
The following lists the possible values for <a href="#ErrnoAccess"><code>errno</code></a>:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>EINVAL</I>: Indicates that the <I>sem</I> input parameter is
|
2007-02-18 00:21:28 +01:00
|
|
|
not valid.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="sempost">2.5.8 sem_post</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_post ( sem_t *sem );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> When a task has finished with a semaphore,
|
2007-02-18 00:21:28 +01:00
|
|
|
it will call sem_post(). This function unlocks the semaphore referenced
|
|
|
|
|
by <I>sem</I> by performing the semaphore unlock operation.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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>.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
from an interrupt handler. It assumes the currently executing
|
|
|
|
|
task is the one that is performing the unlock.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="semgetvalue">2.5.9 sem_getvalue</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <semaphore.h>
|
|
|
|
|
int sem_getvalue ( sem_t *sem, int *sval );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function updates the location referenced
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2008-09-12 21:17:15 +02:00
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Watchdogs"><h2>2.6 Watchdog Timer Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-20 20:03:11 +01:00
|
|
|
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.
|
2007-03-28 18:00:57 +02:00
|
|
|
However, the watchdog timer function may use <code>mq_send()</code>, <code>sigqueue()</code>,
|
|
|
|
|
or <code>kill()</code> to communicate with NuttX tasks.
|
2007-03-20 20:03:11 +01:00
|
|
|
</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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<li><a href="#wdgettime">2.6.5 wd_gettime</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="wdcreate">2.6.1 wd_create</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <wdog.h>
|
|
|
|
|
WDOG_ID wd_create (void);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> The wd_create function will create a watchdog
|
2007-02-18 00:21:28 +01:00
|
|
|
by allocating the appropriate resources for the watchdog.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-03-11 18:37:47 +01:00
|
|
|
NuttX calls (i.e., the watchdog ID), or NULL if insufficient resources
|
2007-02-18 00:21:28 +01:00
|
|
|
are available to create the watchdogs.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following comparable interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
WDOG_ID wdCreate (void);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Differences from the VxWorks interface include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>The number of available watchdogs is fixed (configured at
|
2007-02-18 00:21:28 +01:00
|
|
|
initialization time).
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="wddelete">2.6.2 wd_delete</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <wdog.h>
|
2007-02-21 22:55:16 +01:00
|
|
|
STATUS wd_delete (WDOG_ID wdog);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> The wd_delete function will deallocate a
|
2007-02-18 00:21:28 +01:00
|
|
|
watchdog. The watchdog will be removed from the timer queue if
|
|
|
|
|
has been started.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>wdog</I>. The watchdog ID to delete. This is actually a
|
2007-02-18 00:21:28 +01:00
|
|
|
pointer to a watchdog structure.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>OK or ERROR
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b> It is the responsibility of the
|
2007-02-18 00:21:28 +01:00
|
|
|
caller to assure that the watchdog is inactive before deleting
|
|
|
|
|
it.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following comparable interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-21 22:55:16 +01:00
|
|
|
STATUS wdDelete (WDOG_ID wdog);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Differences from the VxWorks interface include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Does not make any checks to see if the watchdog is being used
|
2007-02-18 00:21:28 +01:00
|
|
|
before de-allocating it (i.e., never returns ERROR).
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="wdstart">2.6.3 wd_start</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <wdog.h>
|
2007-02-21 22:55:16 +01:00
|
|
|
STATUS wd_start( WDOG_ID wdog, int delay, wdentry_t wdentry,
|
|
|
|
|
intt argc, ....);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function adds a watchdog to the timer
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-07-01 01:42:46 +02:00
|
|
|
Watchdog times execute in the context of the timer interrupt handler.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Watchdog timers execute only once.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
To replace either the timeout delay or the function to be executed,
|
2007-02-21 22:55:16 +01:00
|
|
|
call wd_start again with the same wdog; only the most recent
|
2007-02-18 00:21:28 +01:00
|
|
|
wd_start() on a given watchdog ID has any effect.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
context of the timer interrupt handler and is subject to all ISR
|
|
|
|
|
restrictions.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> This is a NON-POSIX interface.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following comparable interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-21 22:55:16 +01:00
|
|
|
STATUS wdStart (WDOG_ID wdog, int delay, FUNCPTR wdentry, int parameter);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Differences from the VxWorks interface include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>The present implementation supports multiple parameters passed
|
2007-02-21 22:55:16 +01:00
|
|
|
to wdentry; VxWorks supports only a single parameter. The maximum
|
|
|
|
|
number of parameters is determined by
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<H3><a name="wdcancel">2.6.4 wd_cancel</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <wdog.h>
|
2007-02-21 22:55:16 +01:00
|
|
|
STATUS wd_cancel (WDOG_ID wdog);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function cancels a currently running
|
2007-02-18 00:21:28 +01:00
|
|
|
watchdog timer. Watchdog timers may be canceled from the interrupt
|
|
|
|
|
level.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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.
|
2007-02-18 00:21:28 +01:00
|
|
|
VxWorks provides the following comparable interface:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-21 22:55:16 +01:00
|
|
|
STATUS wdCancel (WDOG_ID wdog);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-21 18:21:26 +01:00
|
|
|
<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>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="ClocksNTimers"><h2>2.7 Clocks and Timers</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="clocksettime">2.7.1 clock_settime</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><code>To be provided</code>.</li>
|
2007-03-21 01:56:49 +01:00
|
|
|
</ul>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="clockgettime">2.7.2 clock_gettime</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><code>To be provided</code>.</li>
|
2007-03-21 01:56:49 +01:00
|
|
|
</ul>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="clockgetres">2.7.3 clock_getres</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><code>To be provided</code>.</li>
|
2007-03-21 01:56:49 +01:00
|
|
|
</ul>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="mktime">2.7.4 mktime</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><code>To be provided</code>.</li>
|
2007-03-21 01:56:49 +01:00
|
|
|
</ul>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="gmtimer">2.7.5 gmtime_r</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><code>To be provided</code>.</li>
|
2007-03-21 01:56:49 +01:00
|
|
|
</ul>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="localtimer">2.7.6 localtime_r</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<pre>
|
|
|
|
|
#include <time.h>
|
|
|
|
|
#define localtime_r(c,r) gmtime_r(c,r)
|
|
|
|
|
</pre>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="timercreate">2.7.7 timer_create</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<li><code>clockid</code>. Specifies the clock to use as the timing base.
|
|
|
|
|
Must be <code>CLOCK_REALTIME</code>.</li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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
|
2008-02-03 18:09:22 +01:00
|
|
|
a value of -1 (<code>ERROR</code>) and set <a href="#ErrnoAccess"><code>errno</code></a> to indicate the error.
|
2007-03-21 01:56:49 +01:00
|
|
|
</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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<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>
|
2007-03-21 01:56:49 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="timerdelete">2.7.8 timer_delete</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>).
|
2008-02-03 18:09:22 +01:00
|
|
|
Otherwise, the function will return a value of -1 (ERROR) and set
|
|
|
|
|
<a href="#ErrnoAccess"><code>errno</code></a> to indicate the error:
|
2007-03-21 01:56:49 +01:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EINVAL</code>. The timer specified timerid is not valid.</li>
|
|
|
|
|
</ul>
|
2007-03-21 18:21:26 +01:00
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
2007-03-21 01:56:49 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="timersettime">2.7.9 timer_settime</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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.
|
2007-03-21 18:21:26 +01:00
|
|
|
</p>
|
|
|
|
|
<b>NOTE:</b>At present, the <code>ovalue</code> argument is ignored.
|
2007-03-21 01:56:49 +01:00
|
|
|
</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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<li><code>ovalue</code>. A location in which to return the time remaining from the previous timer setting (ignored).</li>
|
2007-03-21 01:56:49 +01:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the timer_gettime() succeeds, a value of 0 (OK) will be returned.
|
2008-02-03 18:09:22 +01:00
|
|
|
If an error occurs, the value -1 (ERROR) will be returned, and
|
|
|
|
|
<a href="#ErrnoAccess"><code>errno</code></a> set to indicate the error.
|
2007-03-21 01:56:49 +01:00
|
|
|
</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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<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>
|
2007-03-21 01:56:49 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="timergettime">2.7.10 timer_gettime</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<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>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
2007-03-21 01:56:49 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="timergetoverrun">2.7.11 timer_getoverrun</a></H3>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<p>
|
|
|
|
|
<b>NOTE:</b> This interface is not currently implemented in NuttX.
|
|
|
|
|
</p>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<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>
|
2007-03-21 01:56:49 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-03-21 01:56:49 +01:00
|
|
|
interface of the same name.
|
2008-09-12 21:17:15 +02:00
|
|
|
</p>
|
2007-03-21 01:56:49 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Signals"><h2>2.8 Signal Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2007-03-20 20:03:11 +01:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigemptyset">2.8.1 sigemptyset</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigemptyset(sigset_t *set);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
|
|
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigfillset">2.8.2 sigfillset</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigfillset(sigset_t *set);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function initializes the signal set specified
|
2007-02-18 00:21:28 +01:00
|
|
|
by set such that all signals are included.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigaddset">2.8.3 sigaddset</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigaddset(sigset_t *set, int signo);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function adds the signal specified by
|
2007-02-18 00:21:28 +01:00
|
|
|
signo to the signal set specified by set.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigdelset">2.8.4 sigdelset</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigdelset(sigset_t *set, int signo);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function deletes the signal specified
|
2007-02-18 00:21:28 +01:00
|
|
|
by signo from the signal set specified by set.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigismember">2.8.5 sigismember</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigismember(const sigset_t *set, int signo);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function tests whether the signal specified
|
2007-02-18 00:21:28 +01:00
|
|
|
by signo is a member of the set specified by set.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigaction">2.8.6 sigaction</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigaction( int signo, const struct sigaction *act,
|
|
|
|
|
struct sigaction *oact );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function allows the calling task to
|
2007-02-18 00:21:28 +01:00
|
|
|
examine and/or specify the action to be associated with a specific
|
|
|
|
|
signal.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
The structure sigaction, used to describe an action to be taken, is defined
|
|
|
|
|
to include the following members:
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
function.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>sa_mask</I>. Additional set of signals to be blocked during
|
2007-02-18 00:21:28 +01:00
|
|
|
execution of the signal-catching function.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>sa_flags</I>: Special flags to affect behavior of a signal.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Signal catching functions execute in the same address environment as the
|
|
|
|
|
task that called sigaction() to install the signal-catching function.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Once an action is installed for a specific signal, it remains installed
|
|
|
|
|
until another action is explicitly requested by another call to
|
|
|
|
|
sigaction().
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the POSIX implementation include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Special values of sa_handler in the struct sigaction act input
|
2007-02-18 00:21:28 +01:00
|
|
|
not handled (SIG_DFL, SIG_IGN).
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>All sa_flags in struct sigaction of act input are ignored
|
2007-02-18 00:21:28 +01:00
|
|
|
(all treated like SA_SIGINFO).
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigprocmask">2.8.7 sigprocmask</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigprocmask(int how, const sigset_t *set, sigset_t *oset);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function allows the calling task to
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
If there are any pending unblocked signals after the call to sigprocmask(),
|
|
|
|
|
those signals will be delivered before sigprocmask() returns.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
If sigprocmask() fails, the signal mask of the task is not changed.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>how</I>. How the signal mast will be changed:
|
|
|
|
|
<ul>
|
2008-02-03 18:09:22 +01:00
|
|
|
<li><I>SIG_BLOCK</I>. The resulting set is the union of the
|
2007-02-18 00:21:28 +01:00
|
|
|
current set and the signal set pointed to by the <I>set</I> input parameter.
|
2008-02-03 18:09:22 +01:00
|
|
|
<li><I>SIG_UNBLOCK</I>. The resulting set is the intersection
|
2007-02-18 00:21:28 +01:00
|
|
|
of the current set and the complement of the signal set pointed
|
|
|
|
|
to by the <I>set</I> input parameter.
|
2008-02-03 18:09:22 +01:00
|
|
|
<li><I>SIG_SETMASK</I>. The resulting set is the signal set
|
2007-02-18 00:21:28 +01:00
|
|
|
pointed to by the <I>set</I> input parameter.
|
2007-03-27 23:27:41 +02:00
|
|
|
</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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigpending">2.8.8 sigpending</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigpending( sigset_t *set );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function stores the returns the set of
|
2007-02-18 00:21:28 +01:00
|
|
|
signals that are blocked for delivery and that are pending for
|
|
|
|
|
the calling task in the space pointed to by set.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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."
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigsuspend">2.8.9 sigsuspend</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigsuspend( const sigset_t *set );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> The sigsuspend() function replaces the signal mask
|
2007-02-18 00:21:28 +01:00
|
|
|
with the set of signals pointed to by the argument set and then suspends
|
|
|
|
|
the task until delivery of a signal to the task.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
If the effect of the set argument is to unblock a pending signal, then
|
|
|
|
|
no wait is performed.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
The original signal mask is restored when sigsuspend() returns.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
Waiting for an empty signal set stops a task without freeing any
|
|
|
|
|
resources (a very bad idea).
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>set</I>. The value of the signal <b>mask</b> to use while
|
2007-02-18 00:21:28 +01:00
|
|
|
suspended.
|
2007-03-27 23:27:41 +02:00
|
|
|
</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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the POSIX specification include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>POSIX does not indicate that the original signal mask is restored.
|
|
|
|
|
<li>POSIX states that sigsuspend() "suspends the task until
|
2007-02-18 00:21:28 +01:00
|
|
|
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).
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigwaitinfo">2.8.10 sigwaitinfo</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigwaitinfo(const sigset_t *set, struct siginfo *info);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function is equivalent to sigtimedwait()
|
2007-02-18 00:21:28 +01:00
|
|
|
with a NULL timeout parameter. (see below).
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
-1 (ERROR) is returned.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigtimedwait">2.8.11 sigtimedwait</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
|
|
|
|
int sigtimedwait( const sigset_t *set, struct siginfo *info,
|
|
|
|
|
const struct timespec *timeout );
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function selects the pending signal set
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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:
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
-1 (ERROR) is returned.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the POSIX interface include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>Values for si_codes differ
|
|
|
|
|
<li>No mechanism to return cause of ERROR. (It can be inferred
|
2007-02-18 00:21:28 +01:00
|
|
|
from si_code in a non-standard way).
|
2007-03-27 23:27:41 +02:00
|
|
|
<li>POSIX states that "If no signal is pending at the time of the
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="sigqueue">2.8.12 sigqueue</a></H3>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <signal.h>
|
2008-01-10 20:16:50 +01:00
|
|
|
int sigqueue (int tid, int signo, union sigval value);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> This function sends the signal specified by
|
2007-02-18 00:21:28 +01:00
|
|
|
signo with the signal parameter value to the task specified
|
|
|
|
|
by tid.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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."
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-03-20 20:03:11 +01:00
|
|
|
On success (at least one signal was sent), zero (OK) is returned.
|
2008-02-03 18:09:22 +01:00
|
|
|
On error, -1 (ERROR) is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately.
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b> POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
Differences from the POSIX interface include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-21 01:56:49 +01:00
|
|
|
<H3><a name="kill">2.8.13 kill</a></H3>
|
2007-03-20 20:03:11 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-03-20 20:03:11 +01:00
|
|
|
#include <sys/types.h>
|
|
|
|
|
#include <signal.h>
|
|
|
|
|
int kill(pid_t pid, int sig);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-20 20:03:11 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-03-20 20:03:11 +01:00
|
|
|
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
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>signo</I>. The signal number to send.
|
2007-03-24 00:22:22 +01:00
|
|
|
If signo is zero, no signal is sent, but all error checking is performed.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-03-20 20:03:11 +01:00
|
|
|
|
|
|
|
|
<p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>OK or ERROR
|
|
|
|
|
</ul>
|
2007-03-20 20:03:11 +01:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Assumptions/Limitations:</b>
|
2007-03-20 20:03:11 +01:00
|
|
|
</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>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Pthread"><h2>2.9 Pthread Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-03-24 16:57:35 +01:00
|
|
|
<p>
|
|
|
|
|
NuttX does not support <i>processes</i> in the way that, say, Linux does.
|
|
|
|
|
NuttX only supports simple threads or tasks running within the same address space.
|
|
|
|
|
For the most part, threads and tasks are interchangeable and differ primarily
|
|
|
|
|
only in such things as the inheritance of file descriptors.
|
|
|
|
|
Basically, threads are initialized and uninitialized differently and share a
|
|
|
|
|
few more resources than tasks.
|
|
|
|
|
<p>
|
|
|
|
|
The following pthread interfaces are supported in some form by NuttX:
|
|
|
|
|
</p>
|
2007-03-20 20:03:11 +01:00
|
|
|
<ul>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2008-05-31 19:13:08 +02:00
|
|
|
<li><a href="#pthreadmutexattrgettype">2.9.30 pthread_mutexattr_gettype</a></li>
|
|
|
|
|
<li><a href="#pthreadmutexattrsettype">2.9.31 pthread_mutexattr_settype</a></li>
|
|
|
|
|
<li><a href="#pthreadmutexinit">2.9.32 pthread_mutex_init</a></li>
|
|
|
|
|
<li><a href="#pthreadmutexdestrory">2.9.33 pthread_mutex_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadmutexlock">2.9.34 pthread_mutex_lock</a></li>
|
|
|
|
|
<li><a href="#pthreadmutextrylock">2.9.35 pthread_mutex_trylock</a></li>
|
|
|
|
|
<li><a href="#pthreadmutexunlock">2.9.36 pthread_mutex_unlock</a></li>
|
|
|
|
|
<li><a href="#pthreadconaddrinit">2.9.37 pthread_condattr_init</a></li>
|
|
|
|
|
<li><a href="#pthreadocndattrdestroy">2.9.38 pthread_condattr_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadcondinit">2.9.39 pthread_cond_init</a></li>
|
|
|
|
|
<li><a href="#pthreadconddestroy">2.9.40 pthread_cond_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadcondbroadcast">2.9.41 pthread_cond_broadcast</a></li>
|
|
|
|
|
<li><a href="#pthreadcondsignal">2.9.42 pthread_cond_signal</a></li>
|
|
|
|
|
<li><a href="#pthreadcondwait">2.9.43 pthread_cond_wait</a></li>
|
|
|
|
|
<li><a href="#pthreadcondtimedwait">2.9.44 pthread_cond_timedwait</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierattrinit">2.9.45 pthread_barrierattr_init</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierattrdestroy">2.9.46 pthread_barrierattr_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierattrsetpshared">2.9.47 pthread_barrierattr_setpshared</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierattrgetpshared">2.9.48 pthread_barrierattr_getpshared</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierinit">2.9.49 pthread_barrier_init</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierdestroy">2.9.50 pthread_barrier_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierwait">2.9.51 pthread_barrier_wait</a></li>
|
|
|
|
|
<li><a href="#pthreadonce">2.9.52 pthread_once</a></li>
|
|
|
|
|
<li><a href="#pthreadkill">2.9.53 pthread_kill</a></li>
|
|
|
|
|
<li><a href="#pthreadsigmask">2.9.54 pthread_sigmask</a></li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
No support for the following pthread interfaces is provided by NuttX:
|
2007-03-24 16:57:35 +01:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>pthread_atfork</code>. register fork handlers.</li>
|
|
|
|
|
<li><code>pthread_attr_getdetachstate</code>. get and set the detachstate attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_getguardsize</code>. get and set the thread guardsize attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_getinheritsched</code>. get and set the inheritsched attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_getscope</code>. get and set the contentionscope attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_getstack</code>. get and set stack attributes.</li>
|
|
|
|
|
<li><code>pthread_attr_getstackaddr</code>. get and set the stackaddr attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_setdetachstate</code>. get and set the detachstate attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_setguardsize</code>. get and set the thread guardsize attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_setscope</code>. get and set the contentionscope attribute.</li>
|
|
|
|
|
<li><code>pthread_attr_setstack</code>. get and set stack attributes.</li>
|
|
|
|
|
<li><code>pthread_attr_setstackaddr</code>. get and set the stackaddr attribute.</li>
|
|
|
|
|
<li><code>pthread_barrier_destroy</code>. destroy and initialize a barrier object.</li>
|
|
|
|
|
<li><code>pthread_barrier_init</code>. destroy and initialize a barrier object.</li>
|
|
|
|
|
<li><code>pthread_barrier_wait</code>. synchronize at a barrier.</li>
|
|
|
|
|
<li><code>pthread_cleanup_pop</code>. establish cancellation handlers.</li>
|
|
|
|
|
<li><code>pthread_cleanup_push</code>. establish cancellation handlers.</li>
|
2008-05-31 19:13:08 +02:00
|
|
|
<li><code>pthread_condattr_getclock</code>. set the clock selection condition variable attribute.</li>
|
|
|
|
|
<li><code>pthread_condattr_getpshared</code>. get the process-shared condition variable attribute.</li>
|
|
|
|
|
<li><code>pthread_condattr_setclock</code>. set the clock selection condition variable attribute.</li>
|
|
|
|
|
<li><code>pthread_condattr_setpshared</code>. set the process-shared condition variable attribute.</li>
|
2007-03-24 16:57:35 +01:00
|
|
|
<li><code>pthread_getconcurrency</code>. get and set the level of concurrency.</li>
|
|
|
|
|
<li><code>pthread_getcpuclockid</code>. access a thread CPU-time clock.</li>
|
|
|
|
|
<li><code>pthread_mutex_getprioceiling</code>. get and set the priority ceiling of a mutex.</li>
|
|
|
|
|
<li><code>pthread_mutex_setprioceiling</code>. get and set the priority ceiling of a mutex.</li>
|
|
|
|
|
<li><code>pthread_mutex_timedlock</code>. lock a mutex.</li>
|
|
|
|
|
<li><code>pthread_mutexattr_getprioceiling</code>. get and set the prioceiling attribute of the mutex attributes object.</li>
|
|
|
|
|
<li><code>pthread_mutexattr_getprotocol</code>. get and set the protocol attribute of the mutex attributes object.</li>
|
|
|
|
|
<li><code>pthread_mutexattr_setprioceiling</code>. get and set the prioceiling attribute of the mutex attributes object.</li>
|
|
|
|
|
<li><code>pthread_mutexattr_setprotocol</code>. get and set the protocol attribute of the mutex attributes object.</li>
|
|
|
|
|
<li><code>pthread_rwlock_destroy</code>. destroy and initialize a read-write lock object.</li>
|
|
|
|
|
<li><code>pthread_rwlock_init</code>. destroy and initialize a read-write lock object.</li>
|
|
|
|
|
<li><code>pthread_rwlock_rdlock</code>. lock a read-write lock object for reading.</li>
|
|
|
|
|
<li><code>pthread_rwlock_timedrdlock</code>. lock a read-write lock for reading.</li>
|
|
|
|
|
<li><code>pthread_rwlock_timedwrlock</code>. lock a read-write lock for writing.</li>
|
|
|
|
|
<li><code>pthread_rwlock_tryrdlock</code>. lock a read-write lock object for reading.</li>
|
|
|
|
|
<li><code>pthread_rwlock_trywrlock</code>. lock a read-write lock object for writing.</li>
|
|
|
|
|
<li><code>pthread_rwlock_unlock</code>. unlock a read-write lock object.</li>
|
|
|
|
|
<li><code>pthread_rwlock_wrlock</code>. lock a read-write lock object for writing.</li>
|
|
|
|
|
<li><code>pthread_rwlockattr_destroy</code>. destroy and initialize the read-write lock attributes object.</li>
|
|
|
|
|
<li><code>pthread_rwlockattr_getpshared</code>. get and set the process-shared attribute of the read-write lock attributes object.</li>
|
|
|
|
|
<li><code>pthread_rwlockattr_init</code>. destroy and initialize the read-write lock attributes object.</li>
|
|
|
|
|
<li><code>pthread_rwlockattr_setpshared</code>. get and set the process-shared attribute of the read-write lock attributes object.</li>
|
|
|
|
|
<li><code>pthread_setcanceltype</code>. set cancelability state.</li>
|
|
|
|
|
<li><code>pthread_setconcurrency</code>. get and set the level of concurrency.</li>
|
|
|
|
|
<li><code>pthread_spin_destroy</code>. destroy or initialize a spin lock object.</li>
|
|
|
|
|
<li><code>pthread_spin_init</code>. destroy or initialize a spin lock object.</li>
|
|
|
|
|
<li><code>pthread_spin_lock</code>. lock a spin lock object.</li>
|
|
|
|
|
<li><code>pthread_spin_trylock</code>. lock a spin lock object.</li>
|
|
|
|
|
<li><code>pthread_spin_unlock</code>. unlock a spin lock object.</li>
|
|
|
|
|
<li><code>pthread_testcancel</code>. set cancelability state.</li>
|
|
|
|
|
</ul>
|
2007-03-20 20:03:11 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadattrinit">2.9.1 pthread_attr_init</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_init(pthread_attr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
Initializes a thread attributes object (attr) with default values
|
|
|
|
|
for all of the individual attributes used by the implementation.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_init()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<H3><a name="pthreadattrdestroy">2.9.2 pthread_attr_destroy</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_destroy(pthread_attr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
An attributes object can be deleted when it is no longer needed.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_destroy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<H3><a name="pthreadattrsetschedpolity">2.9.3 pthread_attr_setschedpolicy</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_setschedpolicy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadattrgetschedpolicy">2.9.4 pthread_attr_getschedpolicy</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_getschedpolicy(pthread_attr_t *attr, int *policy);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_getschedpolicy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadattrsetschedparam">2.9.5 pthread_attr_getschedpolicy</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_setschedparam(pthread_attr_t *attr,
|
|
|
|
|
const struct sched_param *param);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_getschedpolicy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadattrgetschedparam">2.9.6 pthread_attr_getschedparam</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_getschedparam(pthread_attr_t *attr,
|
|
|
|
|
struct sched_param *param);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_getschedparam()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadattrsetinheritsched">2.9.7 pthread_attr_setinheritsched</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_setinheritsched(pthread_attr_t *attr,
|
|
|
|
|
int inheritsched);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_setinheritsched()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<H3><a name="pthreadattrgetinheritsched">2.9.8 pthread_attr_getinheritsched</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_getinheritsched(const pthread_attr_t *attr,
|
|
|
|
|
int *inheritsched);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_getinheritsched()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadattrsetstacksize">2.9.9 pthread_attr_setstacksize</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_setstacksize(pthread_attr_t *attr, long stacksize);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_setstacksize()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadattrgetstacksize">2.9.10 pthread_attr_getstacksize</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_attr_getstacksize(pthread_attr_t *attr, long *stackaddr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_attr_getstacksize()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadcreate">2.9.11 pthread_create</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_create(pthread_t *thread, pthread_attr_t *attr,
|
|
|
|
|
pthread_startroutine_t startRoutine,
|
|
|
|
|
pthread_addr_t arg);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_create()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreaddetach">2.9.12 pthread_detach</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_detach(pthread_t thread);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
A thread object may be "detached" to specify that the
|
|
|
|
|
return value and completion status will not be requested.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_detach()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadexit">2.9.13 pthread_exit</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
void pthread_exit(pthread_addr_t pvValue);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
A thread may terminate it's own execution.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_exit()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadcancel">2.9.14 pthread_cancel</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_cancel(pthread_t thread);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>thread</I>.
|
2007-02-18 00:21:28 +01:00
|
|
|
Identifies the thread to be canceled.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>ESRCH</I>.
|
2007-02-18 00:21:28 +01:00
|
|
|
No thread could be found corresponding to that specified by the given thread ID.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name. Except:</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>The thread-specific data destructor functions shall be called for thread.
|
2007-02-18 00:21:28 +01:00
|
|
|
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>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadsetcancelstate">2.9.15 pthread_setcancelstate</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_setcancelstate(int state, int *oldstate);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>The <i>pthread_setcancelstate()</i> function atomically
|
2007-02-18 00:21:28 +01:00
|
|
|
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>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>state</I>
|
2007-02-18 00:21:28 +01:00
|
|
|
New cancelation state. One of PTHREAD_CANCEL_ENABLE or PTHREAD_CANCEL_DISABLE.<.li>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>oldstate</I>.
|
2007-02-18 00:21:28 +01:00
|
|
|
Location to return the previous cancelation state.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>ESRCH</I>.
|
2007-02-18 00:21:28 +01:00
|
|
|
No thread could be found corresponding to that specified by the given thread ID.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadtestcancelstate">2.9.16 pthread_testcancelstate</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
2007-03-20 20:03:11 +01:00
|
|
|
int pthread_setcancelstate(void);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p><b>NOT SUPPORTED</b>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_setcancelstate()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadjoin">2.9.17 pthread_join</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_join(pthread_t thread, pthread_addr_t *ppvValue);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
A thread can await termination of another thread and retrieve
|
|
|
|
|
the return value of the thread.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_join()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadyield">2.9.18 pthread_yield</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
void pthread_yield(void);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
A thread may tell the scheduler that its processor can be
|
|
|
|
|
made available.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_yield()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadself">2.9.19 pthread_self</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
pthread_t pthread_self(void);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2007-02-18 00:21:28 +01:00
|
|
|
A thread may obtain a copy of its own thread handle.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_self()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadgetschedparam">2.9.20 pthread_getschedparam</a></H3>
|
2007-03-24 16:57:35 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_getschedparam(pthread_t thread, int *policy,
|
2007-03-24 16:57:35 +01:00
|
|
|
struct sched_param *param);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_getschedparam()</code> functions will get the
|
|
|
|
|
scheduling policy and parameters of threads.
|
|
|
|
|
For <code>SCHED_FIFO</code> and <code>SCHED_RR</code>, the only
|
|
|
|
|
required member of the <code>sched_param</code> structure is the
|
|
|
|
|
priority <code>sched_priority</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The <code>pthread_getschedparam()</code> function will retrieve the
|
|
|
|
|
scheduling policy and scheduling parameters for the thread whose thread
|
|
|
|
|
ID is given by <code>thread</code> and will store those values in
|
|
|
|
|
<code>policy</code> and <code>param</code>, respectively.
|
|
|
|
|
The priority value returned from <code>pthread_getschedparam()</code>
|
|
|
|
|
will be the value specified by the most recent <code>pthread_setschedparam()</code>,
|
|
|
|
|
<code>pthread_setschedprio()</code>, or <code>pthread_create()</code> call
|
|
|
|
|
affecting the target thread.
|
|
|
|
|
It will not reflect any temporary adjustments to its priority (such as might
|
|
|
|
|
result of any priority inheritance, for example).
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The policy parameter may have the value <code>SCHED_FIFO</code> or <code>SCHED_RR</code>
|
|
|
|
|
(<code>SCHED_OTHER</code> and <code>SCHED_SPORADIC</code>, in particular, are not supported).
|
|
|
|
|
The <code>SCHED_FIFO</code> and <code>SCHED_RR<code> policies will have a single
|
|
|
|
|
scheduling parameter, <code>sched_priority</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>thread</code>.
|
|
|
|
|
The ID of thread whose scheduling parameters will be queried.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>policy</code>.
|
|
|
|
|
The location to store the thread's scheduling policy.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>param</code>.
|
|
|
|
|
The location to store the thread's priority.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
0 (<code>OK</code>) if successful.
|
|
|
|
|
Otherwise, the error code <code>ESRCH</code> if the value specified by
|
|
|
|
|
<code>thread</code> does not refer to an existing thread.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadsetschedparam">2.9.21 pthread_setschedparam</a></H3>
|
2007-03-24 16:57:35 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_setschedparam(pthread_t thread, int policy,
|
2007-03-24 16:57:35 +01:00
|
|
|
const struct sched_param *param);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_setschedparam()</code> functions will set the scheduling policy
|
|
|
|
|
and parameters of threads.
|
|
|
|
|
For <code>SCHED_FIFO</code> and <code>SCHED_RR</code>, the only required member
|
|
|
|
|
of the <code>sched_param</code> structure is the priority <code>sched_priority</code>.
|
|
|
|
|
</p>
|
|
|
|
|
</p>
|
|
|
|
|
The <code>pthread_setschedparam()</code> function will set the scheduling policy
|
|
|
|
|
and associated scheduling parameters for the thread whose thread ID is given by
|
|
|
|
|
<code>thread</code> to the policy and associated parameters provided in
|
|
|
|
|
<code>policy</code> and <code>param</code>, respectively.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The policy parameter may have the value <code>SCHED_FIFO</code> or <code>SCHED_RR</code>.
|
|
|
|
|
(<code>SCHED_OTHER</code> and <code>SCHED_SPORADIC</code>, in particular, are not supported).
|
|
|
|
|
The <code>SCHED_FIFO</code> and <code>SCHED_RR</code> policies will have a single
|
|
|
|
|
scheduling parameter, <code>sched_priority</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the <code>pthread_setschedparam()</code> function fails, the scheduling
|
|
|
|
|
parameters will not be changed for the target thread.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>thread</code>.
|
|
|
|
|
The ID of thread whose scheduling parameters will be modified.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>policy</code>.
|
|
|
|
|
The new scheduling policy of the thread.
|
|
|
|
|
Either <code>SCHED_FIFO</code> or <code>SCHED_RR<code>.
|
|
|
|
|
<code>SCHED_OTHER<code> and <code>SCHED_SPORADIC<code> are not supported.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>param</code>.
|
|
|
|
|
The location to store the thread's priority.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<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>EINVAL</code>.
|
|
|
|
|
The value specified by <code>policy</code> or one of the scheduling parameters
|
|
|
|
|
associated with the scheduling policy <code>policy</code> is invalid.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>ENOTSUP</code>.
|
|
|
|
|
An attempt was made to set the policy or scheduling parameters to an unsupported
|
|
|
|
|
value (<code>SCHED_OTHER</code> and <code>SCHED_SPORADIC</code> in particular are
|
|
|
|
|
not supported)
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EPERM</code>.
|
|
|
|
|
The caller does not have the appropriate permission to set either the scheduling
|
|
|
|
|
parameters or the scheduling policy of the specified thread.
|
|
|
|
|
Or, the implementation does not allow the application to modify one of the
|
|
|
|
|
parameters to the value specified.
|
|
|
|
|
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>ESRCH</code>.
|
|
|
|
|
The value specified by thread does not refer to a existing thread.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b>
|
|
|
|
|
Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadkeycreate">2.9.22 pthread_key_create</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_key_create( pthread_key_t *key, void (*destructor)(void*) )
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
be associated with each key that is invoked when a
|
|
|
|
|
thread exits. However, this argument is ignored in
|
|
|
|
|
the current implementation.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>EAGAIN</I>. The system lacked sufficient resources
|
2007-02-18 00:21:28 +01:00
|
|
|
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
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_setspecific( pthread_key_t key, void *value )
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
If successful, <I>pthread_setspecific()</I> will return zero (<I>OK</I>).
|
|
|
|
|
Otherwise, an error number will be returned:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><I>ENOMEM</I>. Insufficient memory exists to associate the value
|
2007-02-18 00:21:28 +01:00
|
|
|
with the key.
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><I>EINVAL</I>. The key value is invalid.
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>pthread_setspecific() may be called from a thread-specific data
|
2007-02-18 00:21:28 +01:00
|
|
|
destructor function.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadgetspecific">2.9.24 pthread_getspecific</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
void *pthread_getspecific( pthread_key_t key )
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
The <I>pthread_getspecific()</I> function returns the value
|
|
|
|
|
currently bound to the specified key on behalf of the
|
|
|
|
|
calling thread.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>pthread_getspecific() may be called from a thread-specific data
|
2007-02-18 00:21:28 +01:00
|
|
|
destructor function.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadkeydelete">2.9.25 pthread_key_delete</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_key_delete( pthread_key_t key )
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
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.
|
2007-03-27 23:27:41 +02:00
|
|
|
<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
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadmutexattrinit">2.9.26 pthread_mutexattr_init</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutexattr_init(pthread_mutexattr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_mutexattr_init()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadmutexattrdestroy">2.9.27 pthread_mutexattr_destroy</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Protoype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_mutexattr_destroy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadmutexattrgetpshared">2.9.28 pthread_mutexattr_getpshared</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutexattr_getpshared(pthread_mutexattr_t *attr,
|
|
|
|
|
int *pshared);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_mutexattr_getpshared()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<H3><a name="pthreadmutexattrsetpshared">2.9.29 pthread_mutexattr_setpshared</a></H3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr,
|
|
|
|
|
int pshared);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_mutexattr_setpshared()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadmutexattrgettype">2.9.30 pthread_mutexattr_gettype</a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
#ifdef CONFIG_MUTEX_TYPES
|
|
|
|
|
int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *type);
|
|
|
|
|
#endif
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> Return the mutex type from the mutex attributes.
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>attr</code>. The mutex attributes to query</li>
|
|
|
|
|
<li><code>type</code>. Location to return the mutex type. See
|
|
|
|
|
<a href="#pthreadmutexattrsettype"><code>pthread_mutexattr_setttyp()</code></a>
|
|
|
|
|
for a description of possible mutex types that may be returned.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
|
|
|
|
If successful, the <I>pthread_mutexattr_settype()</I> function will return
|
|
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EINVAL</code>. Parameters <code>attr</code> and/or <code>attr</code> are invalid.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
|
|
|
|
|
<h3><a name="pthreadmutexattrsettype">2.9.31 pthread_mutexattr_settype</a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
#ifdef CONFIG_MUTEX_TYPES
|
|
|
|
|
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type);
|
|
|
|
|
#endif
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b> Set the mutex type in the mutex attributes.
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>attr</code>. The mutex attributes in which to set the mutex type.</li>
|
|
|
|
|
<li><code>type</code>. The mutex type value to set. The following values are supported:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>PTHREAD_MUTEX_NORMAL</code>. This type of mutex does not detect deadlock. A thread
|
|
|
|
|
attempting to relock this mutex without first unlocking it will deadlock.
|
|
|
|
|
Attempting to unlock a mutex locked by a different thread results in undefined
|
|
|
|
|
behavior. Attempting to unlock an unlocked mutex results in undefined behavior. </li>
|
|
|
|
|
<li><code>PTHREAD_MUTEX_ERRORCHECK</code>. This type of mutex provides error checking.
|
|
|
|
|
A thread attempting to relock this mutex without first unlocking it will return with an error.
|
|
|
|
|
A thread attempting to unlock a mutex which another thread has locked will return with an error.
|
|
|
|
|
A thread attempting to unlock an unlocked mutex will return with an error.</li>
|
|
|
|
|
<li><code>PTHREAD_MUTEX_RECURSIVE</code>. A thread attempting to relock this mutex without first
|
|
|
|
|
unlocking it will succeed in locking the mutex. The relocking deadlock which can occur with mutexes
|
|
|
|
|
of type PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this mutex
|
|
|
|
|
require the same number of unlocks to release the mutex before another thread can acquire the mutex.
|
|
|
|
|
A thread attempting to unlock a mutex which another thread has locked will return with an error.
|
|
|
|
|
A thread attempting to unlock an unlocked mutex will return with an error.</li>
|
|
|
|
|
<li><code>PTHREAD_MUTEX_DEFAULT</code>. The default mutex type (PTHREAD_MUTEX_NORMAL).</li>
|
|
|
|
|
</ul>
|
2008-05-31 20:02:49 +02:00
|
|
|
<p>
|
|
|
|
|
In NuttX, <code>PTHREAD_MUTEX_NORMAL</code> is not implemented. Rather, the behavior described
|
|
|
|
|
for <code>PTHREAD_MUTEX_ERRORCHECK</code> is the <i>normal</i> behavior.
|
|
|
|
|
</p>
|
2008-05-31 19:13:08 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
|
|
|
|
If successful, the <I>pthread_mutexattr_settype()</I> function will return
|
|
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EINVAL</code>. Parameters <code>attr</code> and/or <code>attr</code> are invalid.</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.32 pthread_mutex_init</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutex_init(pthread_mutex_t *mutex,
|
|
|
|
|
pthread_mutexattr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_mutex_init()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadmutexdestrory">2.9.33 pthread_mutex_destroy</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutex_destroy(pthread_mutex_t *mutex);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_mutex_destroy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadmutexlock">2.9.34 pthread_mutex_lock</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutex_lock(pthread_mutex_t *mutex);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2008-05-31 20:02:49 +02:00
|
|
|
The mutex object referenced by mutex is locked by calling <code>pthread_mutex_lock()</code>.
|
|
|
|
|
If the mutex is already locked, the calling thread blocks until the mutex
|
|
|
|
|
becomes available. This operation returns with the mutex object referenced
|
|
|
|
|
by mutex in the locked state with the calling thread as its owner.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the mutex type is <code>PTHREAD_MUTEX_NORMAL</code>, deadlock detection is not provided.
|
|
|
|
|
Attempting to relock the mutex causes deadlock. If a thread attempts to unlock
|
|
|
|
|
a mutex that it has not locked or a mutex which is unlocked, undefined behavior
|
|
|
|
|
results.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
In NuttX, <code>PTHREAD_MUTEX_NORMAL</code> is not implemented. Rather, the behavior described
|
|
|
|
|
for <code>PTHREAD_MUTEX_ERRORCHECK</code> is the <i>normal</i> behavior.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the mutex type is <code>PTHREAD_MUTEX_ERRORCHECK</code>, then error checking is provided.
|
|
|
|
|
If a thread attempts to relock a mutex that it has already locked, an error
|
|
|
|
|
will be returned. If a thread attempts to unlock a mutex that it has not
|
|
|
|
|
locked or a mutex which is unlocked, an error will be returned.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If the mutex type is <code>PTHREAD_MUTEX_RECURSIVE</code>, then the mutex maintains the concept
|
|
|
|
|
of a lock count. When a thread successfully acquires a mutex for the first time,
|
|
|
|
|
the lock count is set to one. Every time a thread relocks this mutex, the lock count
|
|
|
|
|
is incremented by one. Each time the thread unlocks the mutex, the lock count is
|
|
|
|
|
decremented by one. When the lock count reaches zero, the mutex becomes available
|
|
|
|
|
for other threads to acquire. If a thread attempts to unlock a mutex that it has
|
|
|
|
|
not locked or a mutex which is unlocked, an error will be returned.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If a signal is delivered to a thread waiting for a mutex, upon return from
|
|
|
|
|
the signal handler the thread resumes waiting for the mutex as if it was
|
|
|
|
|
not interrupted.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
2008-05-31 20:02:49 +02:00
|
|
|
<li><code>mutex</code>. A reference to the mutex to be locked.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2008-05-31 20:02:49 +02:00
|
|
|
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:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
2008-05-31 20:02:49 +02:00
|
|
|
<p>Note that this function will never return the error EINTR.</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadmutextrylock">2.9.35 pthread_mutex_trylock</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutex_trylock(pthread_mutex_t *mutex);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
2008-05-31 20:02:49 +02:00
|
|
|
The function pthread_mutex_trylock() is identical to <a href="#pthreadmutexlock"><code>pthread_mutex_lock()</code></a>
|
|
|
|
|
except that if the mutex object referenced by mutex is currently locked
|
|
|
|
|
(by any thread, including the current thread), the call returns immediately
|
|
|
|
|
with the errno <code>EBUSY</code>.
|
|
|
|
|
<p>
|
|
|
|
|
If a signal is delivered to a thread waiting for a mutex, upon return from
|
|
|
|
|
the signal handler the thread resumes waiting for the mutex as if it was
|
|
|
|
|
not interrupted.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
2008-05-31 20:02:49 +02:00
|
|
|
<li><code>mutex</code>. A reference to the mutex to be locked.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2008-05-31 20:02:49 +02:00
|
|
|
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:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
2008-05-31 20:02:49 +02:00
|
|
|
<p>Note that this function will never return the error EINTR.</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadmutexunlock">2.9.36 pthread_mutex_unlock</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_mutex_unlock(pthread_mutex_t *mutex);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
2008-05-31 20:02:49 +02:00
|
|
|
The <code>pthread_mutex_unlock()</code> function releases the mutex object referenced
|
|
|
|
|
by mutex. The manner in which a mutex is released is dependent upon the
|
|
|
|
|
mutex's type attribute. If there are threads blocked on the mutex object
|
|
|
|
|
referenced by mutex when <code>pthread_mutex_unlock()</code> is called, resulting in
|
|
|
|
|
the mutex becoming available, the scheduling policy is used to determine
|
|
|
|
|
which thread shall acquire the mutex. (In the case of <code>PTHREAD_MUTEX_RECURSIVE</code>
|
|
|
|
|
mutexes, the mutex becomes available when the count reaches zero and the
|
|
|
|
|
calling thread no longer has any locks on this mutex).
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If a signal is delivered to a thread waiting for a mutex, upon return from
|
|
|
|
|
the signal handler the thread resumes waiting for the mutex as if it was
|
|
|
|
|
not interrupted.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
2007-03-24 00:22:22 +01:00
|
|
|
<li><code>param<code>.</li>
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_mutex_unlock()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
2008-05-31 20:02:49 +02:00
|
|
|
<p>Note that this function will never return the error EINTR.</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadconaddrinit">2.9.37 pthread_condattr_init</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_condattr_init(pthread_condattr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_condattr_init()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadocndattrdestroy">2.9.38 pthread_condattr_destroy</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_condattr_destroy(pthread_condattr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_condattr_destroy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadcondinit">2.9.39 pthread_cond_init</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_cond_init(pthread_cond_t *cond, pthread_condattr_t *attr);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_cond_init()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadconddestroy">2.9.40 pthread_cond_destroy</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_cond_destroy(pthread_cond_t *cond);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_cond_destroy()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadcondbroadcast">2.9.41 pthread_cond_broadcast</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_cond_broadcast(pthread_cond_t *cond);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_cond_broadcast()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadcondsignal">2.9.42 pthread_cond_signal</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_cond_signal(pthread_cond_t *dond);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_cond_signal()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadcondwait">2.9.43 pthread_cond_wait</a></H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
<p>
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
2007-03-24 00:22:22 +01:00
|
|
|
<b>Returned Values:</b>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-21 01:56:49 +01:00
|
|
|
If successful, the <I>pthread_cond_wait()</I> function will return
|
2007-02-18 00:21:28 +01:00
|
|
|
zero (<I>OK</I>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>To be provided</code>. </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface of the same name.
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<H3><a name="pthreadcondtimedwait">2.9.44 pthread_cond_timedwait</a></H3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_cond_timedwait(pthread_cond_t *cond, pthread_mutex_t *mutex,
|
|
|
|
|
const struct timespec *abstime);
|
2007-03-24 00:22:22 +01:00
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><code>To be provided</code>.</li>
|
2007-03-24 00:22:22 +01:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If successful, the <code>pthread_cond_timedwait()</code> function will return
|
|
|
|
|
zero (<code>OK</code>). Otherwise, an error number will be
|
|
|
|
|
returned to indicate the error:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
2007-03-27 23:27:41 +02:00
|
|
|
<li><code>To be provided</code>. </li>
|
2007-03-24 00:22:22 +01:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadbarrierattrinit">2.9.45 pthread_barrierattr_init</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_barrierattr_init(FAR pthread_barrierattr_t *attr);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_barrierattr_init()</code> function will initialize a barrier
|
|
|
|
|
attribute object <code>attr</code> with the default value for all of the attributes
|
|
|
|
|
defined by the implementation.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>attr</code>. Barrier attributes to be initialized.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
0 (<code>OK</code>) on success or <code>EINVAL</code> if <code>attr</code> is invalid.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadbarrierattrdestroy">2.9.46 pthread_barrierattr_destroy</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_barrierattr_destroy(FAR pthread_barrierattr_t *attr);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_barrierattr_destroy()</code> function will destroy a barrier attributes object.
|
|
|
|
|
A destroyed attributes object can be reinitialized using <code>pthread_barrierattr_init()</code>;
|
|
|
|
|
the results of otherwise referencing the object after it has been destroyed are undefined.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>attr</code>. Barrier attributes to be destroyed.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b> 0 (OK) on success or EINVAL if attr is invalid.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadbarrierattrsetpshared">2.9.47 pthread_barrierattr_setpshared</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_barrierattr_setpshared(FAR pthread_barrierattr_t *attr, int pshared);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The process-shared attribute is set to <code>PTHREAD_PROCESS_SHARED</code> to permit
|
|
|
|
|
a barrier to be operated upon by any thread that has access to the memory where the
|
|
|
|
|
barrier is allocated.
|
|
|
|
|
If the process-shared attribute is <code>PTHREAD_PROCESS_PRIVATE</code>, the barrier can
|
|
|
|
|
only be operated upon by threads created within the same process as the thread that
|
|
|
|
|
initialized the barrier.
|
|
|
|
|
If threads of different processes attempt to operate on such a barrier, the behavior is undefined.
|
|
|
|
|
The default value of the attribute is <code>PTHREAD_PROCESS_PRIVATE</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>attr</code>. Barrier attributes to be modified.</li>
|
|
|
|
|
<li><code>pshared</code>. The new value of the pshared attribute.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b> 0 (<code>OK</code>) on success or <code>EINVAL</code> if either
|
|
|
|
|
<code>attr</code> is invalid or <code>pshared</code> is not one of
|
|
|
|
|
<code>PTHREAD_PROCESS_SHARED</code> or <code>PTHREAD_PROCESS_PRIVATE</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadbarrierattrgetpshared">2.9.48 pthread_barrierattr_getpshared</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_barrierattr_getpshared(FAR const pthread_barrierattr_t *attr, FAR int *pshared);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_barrierattr_getpshared()</code> function will obtain the value of the
|
|
|
|
|
process-shared attribute from the attributes object referenced by <code>attr</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>attr</code>. Barrier attributes to be queried.</li>
|
|
|
|
|
<li><code>pshared</code>. The location to stored the current value of the pshared attribute.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b> 0 (<code>OK</code>) on success or <code>EINVAL</code> if
|
|
|
|
|
either <code>attr</code> or <code>pshared</code> is invalid.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadbarrierinit">2.9.49 pthread_barrier_init</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_barrier_init(FAR pthread_barrier_t *barrier,
|
|
|
|
|
FAR const pthread_barrierattr_t *attr, unsigned int count);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_barrier_init()</code> function allocates any resources required to
|
|
|
|
|
use the barrier referenced by <code>barrier</code> and initialized the barrier with
|
|
|
|
|
the attributes referenced by <code>attr</code>.
|
|
|
|
|
If <code>attr</code> is NULL, the default barrier attributes will be used.
|
|
|
|
|
The results are undefined if <code>pthread_barrier_init()</code> is called when any
|
|
|
|
|
thread is blocked on the barrier.
|
|
|
|
|
The results are undefined if a barrier is used without first being initialized.
|
|
|
|
|
The results are undefined if <code>pthread_barrier_init()</code> is called specifying
|
|
|
|
|
an already initialized barrier.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>barrier</code>.
|
|
|
|
|
The barrier to be initialized.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>attr</code>.
|
|
|
|
|
Barrier attributes to be used in the initialization.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>count</code>.
|
|
|
|
|
The count to be associated with the barrier.
|
|
|
|
|
The count argument specifies the number of threads that must call
|
|
|
|
|
<code>pthread_barrier_wait()</code> before any of them successfully return from the call.
|
|
|
|
|
The value specified by count must be greater than zero.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>0 (OK) on success or on of the following error numbers:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EAGAIN</code>.
|
|
|
|
|
The system lacks the necessary resources to initialize another barrier.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>.
|
|
|
|
|
The barrier reference is invalid, or the values specified by attr are invalid, or
|
|
|
|
|
the value specified by count is equal to zero.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>ENOMEM</code>.
|
|
|
|
|
Insufficient memory exists to initialize the barrier.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EBUSY</code>.
|
|
|
|
|
The implementation has detected an attempt to reinitialize a barrier while it is in use.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadbarrierdestroy">2.9.50 pthread_barrier_destroy</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_barrier_destroy(FAR pthread_barrier_t *barrier);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_barrier_destroy()</code> function destroys the barrier referenced
|
|
|
|
|
by <code>barrie</code> and releases any resources used by the barrier.
|
|
|
|
|
The effect of subsequent use of the barrier is undefined until the barrier is
|
|
|
|
|
reinitialized by another call to <code>pthread_barrier_init()</code>.
|
|
|
|
|
The results are undefined if <code>pthread_barrier_destroy()</code> is called when
|
|
|
|
|
any thread is blocked on the barrier, or if this function is called with an
|
|
|
|
|
uninitialized barrier.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>barrier</code>. The barrier to be destroyed.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b> 0 (<code>OK</code>) on success or on of the following error numbers:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EBUSY</code>.
|
|
|
|
|
The implementation has detected an attempt to destroy a barrier while it is in use.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>.
|
|
|
|
|
The value specified by barrier is invalid.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadbarrierwait">2.9.51 pthread_barrier_wait</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_barrier_wait(FAR pthread_barrier_t *barrier);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_barrier_wait()</code> function synchronizse participating
|
|
|
|
|
threads at the barrier referenced by <code>barrier</code>.
|
|
|
|
|
The calling thread is blocked until the required number of threads have called
|
|
|
|
|
<code>pthread_barrier_wait()</code> specifying the same <code>barrier</code>.
|
|
|
|
|
When the required number of threads have called <code>pthread_barrier_wait()</code>
|
|
|
|
|
specifying the <code>barrier</code>, the constant <code>PTHREAD_BARRIER_SERIAL_THREAD</code>
|
|
|
|
|
will be returned to one unspecified thread and zero will be returned to each of
|
|
|
|
|
the remaining threads.
|
|
|
|
|
At this point, the barrier will be reset to the state it had as a result of the most
|
|
|
|
|
recent <code>pthread_barrier_init()</code> function that referenced it.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The constant <code>PTHREAD_BARRIER_SERIAL_THREAD</code> is defined in
|
|
|
|
|
<code>pthread.h</code> and its value must be distinct from any other value
|
|
|
|
|
returned by <code>pthread_barrier_wait()</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The results are undefined if this function is called with an uninitialized barrier.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If a signal is delivered to a thread blocked on a barrier, upon return from the
|
|
|
|
|
signal handler the thread will resume waiting at the barrier if the barrier wait
|
|
|
|
|
has not completed.
|
|
|
|
|
Otherwise, the thread will continue as normal from the completed barrier wait.
|
|
|
|
|
Until the thread in the signal handler returns from it, it is unspecified whether
|
|
|
|
|
other threads may proceed past the barrier once they have all reached it.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
A thread that has blocked on a barrier will not prevent any unblocked thread that
|
|
|
|
|
is eligible to use the same processing resources from eventually making forward
|
|
|
|
|
progress in its execution.
|
|
|
|
|
Eligibility for processing resources will be determined by the scheduling policy.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>barrier</code>. The barrier on which to wait.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b> 0 (<code>OK</code>) on success or <code>EINVAL</code> if the barrier is not valid.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadonce">2.9.52 pthread_once</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_once(FAR pthread_once_t *once_control, CODE void (*init_routine)(void));
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The first call to <code>pthread_once()</code> by any thread with a given
|
|
|
|
|
<code>once_control</code>, will call the <code>init_routine()</code> with no arguments.
|
|
|
|
|
Subsequent calls to <code>pthread_once()</code> with the same <code>once_control</code> will have no effect.
|
|
|
|
|
On return from <code>pthread_once()</code>, <code>init_routine()</code> will have completed.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>once_control</code>.
|
|
|
|
|
Determines if <code>init_routine()</code> should be called.
|
|
|
|
|
<code>once_control</code> should be declared and intialized as follows:
|
|
|
|
|
<ul><pre>pthread_once_t once_control = PTHREAD_ONCE_INIT;
|
|
|
|
|
</pre></ul>
|
|
|
|
|
<code>PTHREAD_ONCE_INIT</code> is defined in <code>pthread.h</code>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>init_routine</code>.
|
|
|
|
|
The initialization routine that will be called once.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
0 (OK) on success or EINVAL if either once_control or init_routine are invalid.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadkill">2.9.53 pthread_kill</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <signal.h>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_kill(pthread_t thread, int signo)
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>pthread_kill()</code> system call can be used to send any
|
|
|
|
|
signal to a thread. See <code>kill()</code> for further information
|
|
|
|
|
as this is just a simple wrapper around the <code>kill()</code>
|
|
|
|
|
function.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>thread</code>.
|
|
|
|
|
The id of the thread to receive the signal. Only positive, non-zero values of <code>tthread</code>t are supported.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>signo</code>.
|
|
|
|
|
The signal number to send. If <code>signo</code> is zero, no signal is sent, but all error checking is performed.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
On success, the signal was sent and zero is returned.
|
|
|
|
|
On error one of the following error numbers is returned.
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EINVAL</code>.
|
|
|
|
|
An invalid signal was specified.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>EPERM</code>.
|
|
|
|
|
The thread does not have permission to send the signal to the target thread.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>ESRCH</code>.
|
|
|
|
|
No thread could be found corresponding to that specified by the given thread ID.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>ENOSYS</code>.
|
|
|
|
|
Do not support sending signals to process groups.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-05-31 19:13:08 +02:00
|
|
|
<h3><a name="pthreadsigmask">2.9.54 pthread_sigmask</a></h3>
|
2007-03-24 00:22:22 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <signal.h>
|
|
|
|
|
#include <pthread.h>
|
|
|
|
|
int pthread_sigmask(int how, FAR const sigset_t *set, FAR sigset_t *oset);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
This function is a simple wrapper around <code>sigprocmask()</code>.
|
|
|
|
|
See the <code>sigprocmask()</code> function description for further information.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>how</code>. How the signal mast will be changed:
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>SIG_BLOCK</code>:
|
|
|
|
|
The resulting set is the union of the current set and the signal set pointed to by <code>set</code>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>SIG_UNBLOCK</code>:
|
|
|
|
|
The resulting set is the intersection of the current set and the complement of the signal set pointed to by <code>set</code>.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>SIG_SETMASK</code>:
|
|
|
|
|
The resulting set is the signal set pointed to by <code>set</code>.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>set</code>. Location of the new signal mask.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>oset</code>. Location to store the old signal mask.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
0 (OK) on succes or EINVAL if <code>how</code> is invalid.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Assumptions/Limitations:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>POSIX Compatibility:</b> Comparable to the POSIX interface of the same name.
|
|
|
|
|
</p>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Environ"><h2>2.10 Environment Variables</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-07-01 01:42:46 +02:00
|
|
|
<p><b>Overview</b>.
|
|
|
|
|
NuttX supports environment variables that can be used to control the behavior of programs.
|
|
|
|
|
In the spirit of NuttX the environment variable behavior attempts to emulate the behavior of
|
|
|
|
|
environment variables in the mulit-processing OS:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><b>Task environments</b>.
|
|
|
|
|
When a new task is created using <a href="#taskcreate">task_create</a>, the environment
|
|
|
|
|
of the child task is an inherited, exact copy of the environment of the parent.
|
|
|
|
|
However, after child task has been created, subsequent operations by the child task on
|
|
|
|
|
its environment does not alter the environment of the parent.
|
|
|
|
|
No do operations by the parent effect the child's environment.
|
|
|
|
|
The environments start identical but are independent and may diverge.
|
|
|
|
|
</li>
|
|
|
|
|
<li><b>Thread environments</b>.
|
|
|
|
|
When a pthread is created using <a href="#pthreadcreate">pthread_create</a>, the child
|
|
|
|
|
thread also inherits that envirnment of the parent.
|
|
|
|
|
However, the child does not recieve a copy of the environment but, rather, shares the same
|
|
|
|
|
environment.
|
|
|
|
|
Changes to the environment are visiable to all threads with the same parentage.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p><b>Programming Interfaces</b>.
|
|
|
|
|
The following environment variable programming interfaces are provided by Nuttx and are
|
|
|
|
|
described in detail in the following paragraphs.
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><a href="#getenv">2.10.1 <code>getenv</code></a></li>
|
|
|
|
|
<li><a href="#putenv">2.10.2 <code>putenv</code></a></li>
|
|
|
|
|
<li><a href="#clearenv">2.10.3 <code>clearenv</code></a></li>
|
|
|
|
|
<li><a href="#setenv">2.10.4 <code>setenv</code></a></li>
|
|
|
|
|
<li><a href="#unsetenv">2.10.5 <code>unsetenv</code></a></li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p><b>Disabling Environment Variable Support</b>.
|
2008-11-16 23:05:28 +01:00
|
|
|
All support for environment variables can be disabled by setting <code>CONFIG_DISABLE_ENVIRON</code>
|
2007-07-01 01:42:46 +02:00
|
|
|
in the board configuration file.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="getenv">2.10.1 <code>getenv</code></a></h3>
|
2007-07-01 01:42:46 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <stdlib.h>
|
2007-07-01 01:42:46 +02:00
|
|
|
FAR char *getenv(const char *name);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>getenv()</code> function searches the environment list for a string that
|
|
|
|
|
matches the string pointed to by <code>name</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>name</code>.
|
|
|
|
|
The name of the variable to find.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
The value of the valiable (read-only) or NULL on failure.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="putenv">2.10.2 <code>putenv</code></a></h3>
|
2007-07-01 01:42:46 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <stdlib.h>
|
2007-07-01 01:42:46 +02:00
|
|
|
int putenv(char *string);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>putenv()</code> function adds or changes the value of environment variables.
|
|
|
|
|
The argument string is of the form <i>name=value</i>. If name does not already
|
|
|
|
|
exist in the environment, then string is added to the environment. If
|
|
|
|
|
name does exist, then the value of name in the environment is changed to
|
|
|
|
|
value.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>string</code>
|
|
|
|
|
name=value string describing the environment setting to add/modify.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
Zero on sucess.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="clearenv">2.10.3 <code>clearenv</code></a></h3>
|
2007-07-01 01:42:46 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <stdlib.h>
|
2007-07-01 01:42:46 +02:00
|
|
|
int clearenv(void);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>clearenv()</code> function clears the environment of all name-value pairs
|
|
|
|
|
and sets the value of the external variable environ to NULL.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
None
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
Zero on success.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="setenv">2.10.4 <code>setenv</code></a></h3>
|
2007-07-01 01:42:46 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <stdlib.h>
|
2007-07-01 01:42:46 +02:00
|
|
|
int setenv(const char *name, const char *value, int overwrite);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>setenv()</code> function adds the variable <code>name</code> to the environment with the
|
|
|
|
|
specified <code>value</code> if the variable <code>name</code> does not exist. If the <code>name</code>
|
|
|
|
|
does exist in the environment, then its value is changed to <code>value</code> if <code>overwrite</code>
|
|
|
|
|
is non-zero; if <code>overwrite</code> is zero, then the value of <code>name</code> is unaltered.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>name</code>
|
|
|
|
|
The name of the variable to change.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>value</code>
|
|
|
|
|
The new value of the variable.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>value</code>
|
|
|
|
|
Replace any existing value if non-zero.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
Zero on success.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="unsetenv">2.10.5 <code>unsetenv</code></a></h3>
|
2007-07-01 01:42:46 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <stdlib.h>
|
2007-07-01 01:42:46 +02:00
|
|
|
int unsetenv(const char *name);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>unsetenv()</code> function deletes the variable <code>name</code> from the environment.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>name</code>
|
|
|
|
|
The name of the variable to delete.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
Zero on success.
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="FileSystem"><h2>2.11 File System Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-12-10 18:15:11 +01:00
|
|
|
|
2008-08-10 18:36:33 +02:00
|
|
|
<ul>
|
|
|
|
|
<li><a href="#FileSystemOverview">2.11.1 NuttX File System Overview</a></li>
|
|
|
|
|
<li><a href="#driveroperations">2.11.2 Driver Operations</a></li>
|
|
|
|
|
<li><a href="#directoryoperations">2.11.3 Directory Operations</a></li>
|
|
|
|
|
<li><a href="#standardio">2.11.4 Standard I/O</a></li>
|
|
|
|
|
<li><a href="#PipesNFifos">2.11.5 Pipes and FIFOs</a></li>
|
|
|
|
|
<li><a href="#fatsupport">2.11.6 FAT File System Support</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmapxip">2.11.7 <code>mmap()</code> and eXecute In Place (XIP)</a></li>
|
2008-08-10 18:36:33 +02:00
|
|
|
</ul>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="FileSystemOverview">2.11.1 NuttX File System Overview</a></h3>
|
2008-07-26 17:09:21 +02:00
|
|
|
|
2007-12-10 18:15:11 +01:00
|
|
|
<p><b>Overview</b>.
|
|
|
|
|
NuttX includes an optional, scalable file system.
|
|
|
|
|
This file-system may be omitted altogther; NuttX does not depend on the presence
|
|
|
|
|
of any file system.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p><b>Pseudo Root File System</b>.
|
|
|
|
|
Or, a simple <i>in-memory</i>, <i>psuedo</i> file system can be enabled.
|
|
|
|
|
This simple file system can be enabled setting the CONFIG_NFILE_DESCRIPTORS
|
|
|
|
|
option to a non-zero value.
|
|
|
|
|
This is an <i>in-memory</i> file system because it does not require any
|
|
|
|
|
storage medium or block driver support.
|
|
|
|
|
Rather, file system contents are generated on-the-fly as referenced via
|
|
|
|
|
standard file system operations (open, close, read, write, etc.).
|
|
|
|
|
In this sense, the file system is <i>psuedo</i> file system (in the
|
|
|
|
|
same sense that the Linux <code>/proc</code> file system is also
|
|
|
|
|
referred to as a psuedo file system).
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Any user supplied data or logic can be accessed via the psuedo-file system.
|
|
|
|
|
Built in support is provided for character and block drivers in the
|
|
|
|
|
<code>/dev</code> psuedo file system directory.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p><b>Mounted File Systems</b>
|
|
|
|
|
The simple in-memory file system can be extended my mounting block
|
|
|
|
|
devices that provide access to true file systems backed up via some
|
|
|
|
|
mass storage device.
|
|
|
|
|
NuttX supports the standard <code>mount()</code> command that allows
|
|
|
|
|
a block driver to be bound to a mountpoint within the psuedo file system
|
|
|
|
|
and to a a file system.
|
|
|
|
|
At present, NuttX supports only the VFAT file system.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p><b>Comparison to Linux</b>
|
|
|
|
|
From a programming perspective, the NuttX file system appears very similar
|
|
|
|
|
to a Linux file system.
|
|
|
|
|
However, there is a fundamental difference:
|
|
|
|
|
The NuttX root file system is a psuedo file system and true file systems may be
|
|
|
|
|
mounted in the psuedo file system.
|
|
|
|
|
In the typical Linux installation by comparison, the Linux root file system
|
|
|
|
|
is a true file system and psuedo file systems may be mounted in the true,
|
|
|
|
|
root file system.
|
|
|
|
|
The approach selected by NuttX is intended to support greater scalability
|
|
|
|
|
from the very tiny platform to the moderate platform.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p><b>File System Interfaces</b>.
|
|
|
|
|
The NuttX file system simply supports a set of standard, file system APIs
|
2007-07-01 01:42:46 +02:00
|
|
|
(<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>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="driveroperations">2.11.2 Driver Operations</a></h3>
|
2008-11-19 00:00:29 +01:00
|
|
|
<ul>
|
|
|
|
|
<li><a href="#drvrfcntlops">2.11.2.1 <code>fcntl.h</code></a></li>
|
|
|
|
|
<li><a href="#drvrunistdops">2.11.2.2 <code>unistd.h</code></a></li>
|
|
|
|
|
<li><a href="#drvrioctlops">2.11.2.3 <code>sys/ioctl.h</code></a></li>
|
|
|
|
|
<li><a href="#drvrpollops">2.11.2.4 <code>poll.h</code></a></li>
|
|
|
|
|
<li><a href="#drvselectops">2.11.2.5 <code>sys/select.h</code></a></li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h4><a name="drvrfcntlops">2.11.2.1 fcntl.h</a></h4>
|
|
|
|
|
|
2007-07-01 01:42:46 +02:00
|
|
|
<ul><pre>
|
|
|
|
|
#include <fcntl.h>
|
|
|
|
|
int open(const char *path, int oflag, ...);
|
|
|
|
|
</pre></ul>
|
|
|
|
|
|
2008-11-19 00:00:29 +01:00
|
|
|
<h4><a name="drvrunistdops">2.11.2.2 unistd.h</a></h4>
|
|
|
|
|
|
2007-07-01 01:42:46 +02:00
|
|
|
<ul><pre>
|
|
|
|
|
#include <unistd.h>
|
2008-08-13 02:32:32 +02:00
|
|
|
int close(int fd);
|
|
|
|
|
int dup(int fildes);
|
|
|
|
|
int dup2(int fildes1, int fildes2);
|
|
|
|
|
off_t lseek(int fd, off_t offset, int whence);
|
|
|
|
|
ssize_t read(int fd, void *buf, size_t nbytes);
|
|
|
|
|
int unlink(const char *path);
|
|
|
|
|
ssize_t write(int fd, const void *buf, size_t nbytes);
|
2007-07-01 01:42:46 +02:00
|
|
|
</pre></ul>
|
|
|
|
|
|
2008-11-19 00:00:29 +01:00
|
|
|
<h4><a name="drvrioctlops">2.11.2.3 sys/ioctl.h</a></h4>
|
|
|
|
|
|
2007-07-01 01:42:46 +02:00
|
|
|
<ul><pre>
|
|
|
|
|
#include <sys/ioctl.h>
|
2008-08-13 02:32:32 +02:00
|
|
|
int ioctl(int fd, int req, unsigned long arg);
|
2007-07-01 01:42:46 +02:00
|
|
|
</pre></ul>
|
2008-11-19 00:00:29 +01:00
|
|
|
|
|
|
|
|
<h4><a name="drvrpollops">2.11.2.4 poll.h</a></h4>
|
|
|
|
|
|
|
|
|
|
<h5><a name="poll">2.11.2.4.1 poll</a></H5>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <poll.h>
|
|
|
|
|
int poll(struct pollfd *fds, nfds_t nfds, int timeout);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<code>poll()</code> waits for one of a set of file descriptors to become ready to
|
|
|
|
|
perform I/O. If none of the events requested (and no error) has
|
|
|
|
|
occurred for any of the file descriptors, then <code>poll()</code> blocks until
|
|
|
|
|
one of the events occurs.
|
|
|
|
|
</p>
|
2008-11-19 01:23:19 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Configuration Settings</b>.
|
|
|
|
|
In order to use the <code>poll()</code> API, the following must be defined
|
|
|
|
|
in your NuttX configuration file:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>CONFIG_NFILE_DESCRIPTORS</code> Defined to be greater than 0</li>
|
|
|
|
|
<li><code>CONFIG_DISABLE_POLL</code> NOT defined</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
In order to use the select with TCP/IP sockets test, you must also have the following additional things
|
|
|
|
|
selected in your NuttX configuration file:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>CONFIG_NET</code> Defined for general network support</li>
|
|
|
|
|
<li><code>CONFIG_NET_TCP</code> Defined for TCP/IP support</li>
|
|
|
|
|
<li><code>CONFIG_NSOCKET_DESCRIPTORS</code> Defined to be greater than 0</li>
|
|
|
|
|
<li><code>CONFIG_NET_NTCP_READAHEAD_BUFFERS</code> Defined to be greater than zero</li>
|
|
|
|
|
</ul>
|
2008-11-20 20:24:06 +01:00
|
|
|
<p>
|
|
|
|
|
In order to for select to work with incoming connections, you must also select:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>CONFIG_NET_TCPBACKLOG</code>
|
|
|
|
|
Incoming connections pend in a backlog until <code>accept()</cod> is called.
|
|
|
|
|
The size of the backlog is selected when <code>listen()</code> is called.</li>
|
|
|
|
|
</ul>
|
2008-11-19 00:00:29 +01:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>fds</code>. List of structures describing file descriptors to be monitored.</li>
|
|
|
|
|
<li><code>nfds</code>. The number of entries in the list.</li>
|
|
|
|
|
<li><code>timeout</code>. Specifies an upper limit on the time for which <code>poll()</code> will
|
|
|
|
|
block in milliseconds. A negative value of <code>timeout</code> means an infinite
|
|
|
|
|
timeout.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
On success, the number of structures that have nonzero <cod>revents</code> fields.
|
|
|
|
|
A value of 0 indicates that the call timed out and no file descriptors were ready.
|
|
|
|
|
On error, -1 is returned, and <code>errno</code> is set appropriately:
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EBADF</code>. An invalid file descriptor was given in one of the sets.</li>
|
|
|
|
|
<li><code>EFAULT</code>. The fds address is invalid</li>
|
|
|
|
|
<li><code>EINTR</code>. A signal occurred before any requested event.</li>
|
|
|
|
|
<li><code>EINVAL</code>. The nfds value exceeds a system limit.</li>
|
|
|
|
|
<li><code>ENOMEM</code>. There was no space to allocate internal data structures.</li>
|
|
|
|
|
<li><code>ENOSYS</code>. One or more of the drivers supporting the file descriptor does not support the poll method.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h4><a name="drvselectops">2.11.2.5 sys/select.h</a></h4>
|
|
|
|
|
|
|
|
|
|
<h5><a name="select">2.11.2.5.1 select</a></H5>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
#include <sys/select.h>
|
|
|
|
|
int select(int nfds, FAR fd_set *readfds, FAR fd_set *writefds,
|
|
|
|
|
FAR fd_set *exceptfds, FAR struct timeval *timeout);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<code>select()</code> allows a program to monitor multiple file descriptors, waiting
|
|
|
|
|
until one or more of the file descriptors become "ready" for some class
|
|
|
|
|
of I/O operation (e.g., input possible). A file descriptor is
|
|
|
|
|
considered ready if it is possible to perform the corresponding I/O
|
|
|
|
|
operation (e.g., read(2)) without blocking.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>NOTE:</b> <a href="#poll"><code>poll()</code></a> is the fundamental API for performing such monitoring
|
|
|
|
|
operation under NuttX. <code>select()</code> is provided for compatibility and
|
|
|
|
|
is simply a layer of added logic on top of <code>poll()</code>. As such, <code>select()</code>
|
|
|
|
|
is more wasteful of resources and <a href="#poll"><code>poll()</code></a> is the recommended API to be
|
|
|
|
|
used.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>nfds</code>. the maximum file descriptor number (+1) of any descriptor in any of the three sets.</li>
|
|
|
|
|
<li><code>readfds</code>. the set of descriptions to monitor for read-ready events</li>
|
|
|
|
|
<li><code>writefds</code>. the set of descriptions to monitor for write-ready events</li>
|
|
|
|
|
<li><code>exceptfds</code>. the set of descriptions to monitor for error events</li>
|
|
|
|
|
<li><code>timeout</code>. Return at this time if none of these events of interest occur.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>0:</code> Timer expired</li>
|
|
|
|
|
<li><code>>0:</code> The number of bits set in the three sets of descriptors</li>
|
|
|
|
|
<li><code>-1:</code> An error occurred (<code>errno</code> will be set appropriately,
|
|
|
|
|
see <a href="#poll"><code>poll()</code></a>).</li>
|
|
|
|
|
</ul>
|
2007-07-01 01:42:46 +02:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="directoryoperations">2.11.3 Directory Operations</a></h3>
|
2008-09-01 22:35:41 +02:00
|
|
|
<a name="dirdirentops">
|
2007-07-01 01:42:46 +02:00
|
|
|
<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>
|
2008-09-01 22:35:41 +02:00
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
<a name="dirunistdops">
|
2008-08-23 01:38:33 +02:00
|
|
|
<ul><pre>
|
|
|
|
|
#include <unistd.h>
|
|
|
|
|
int chdir(FAR const char *path);
|
|
|
|
|
FAR char *getcwd(FAR char *buf, size_t size);
|
|
|
|
|
</pre></ul>
|
2008-09-01 22:35:41 +02:00
|
|
|
</a>
|
2007-07-01 01:42:46 +02:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="standardio">2.11.4 Standard I/O</a></h3>
|
2007-07-01 01:42:46 +02:00
|
|
|
<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);
|
2008-09-01 22:35:41 +02:00
|
|
|
int fgetpos(FILE *stream, fpos_t *pos);
|
2007-07-01 01:42:46 +02:00
|
|
|
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);
|
2008-09-01 22:35:41 +02:00
|
|
|
int fseek(FILE *stream, long int offset, int whence);
|
|
|
|
|
int fsetpos(FILE *stream, fpos_t *pos);
|
|
|
|
|
long ftell(FILE *stream);
|
2007-07-01 01:42:46 +02:00
|
|
|
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);
|
|
|
|
|
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);
|
|
|
|
|
|
|
|
|
|
FILE *fdopen(int fd, const char *type);
|
|
|
|
|
int fstat(int fd, FAR struct stat *buf); /* Prototyped but not implemented */
|
|
|
|
|
int mkdir(const char *path, mode_t mode);
|
|
|
|
|
int rmdir(const char *path);
|
|
|
|
|
int stat(const char *path, FAR struct stat *buf);
|
|
|
|
|
int statfs(const char *path, FAR struct statfs *buf); /* Prototyped but not implemented */
|
|
|
|
|
</pre></ul>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="PipesNFifos">2.11.5 Pipes and FIFOs</a></h3>
|
2008-07-26 17:09:21 +02:00
|
|
|
|
2008-08-10 18:36:33 +02:00
|
|
|
<h3>2.11.5.1 <a name="pipe"><code>pipe</code></a></h3>
|
2008-07-26 17:09:21 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <unistd.h>
|
2008-07-26 17:09:21 +02:00
|
|
|
int pipe(int filedes[2]);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<p>
|
|
|
|
|
<code>pipe()</code> creates a pair of file descriptors, pointing to a pipe inode, and
|
|
|
|
|
places them in the array pointed to by <code>filedes</code>.
|
|
|
|
|
<code>filedes[0]</code> is for reading, <code>filedes[1]</code> is for writing.
|
|
|
|
|
</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>filedes[2]</code>. The user provided array in which to catch the pipe file descriptors.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<p>
|
|
|
|
|
0 is returned on success; otherwise, -1 is returned with <code>errno</code> set appropriately.
|
|
|
|
|
</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-08-10 18:36:33 +02:00
|
|
|
<h3>2.11.5.2 <a name="mkfifo"><code>mkfifo</code></a></h3>
|
2008-07-26 17:09:21 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/stat.h>
|
2008-07-26 17:09:21 +02:00
|
|
|
int mkfifo(FAR const char *pathname, mode_t mode);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<p>
|
|
|
|
|
<code>mkfifo()</code> makes a FIFO device driver file with name <code>pathname</code>.
|
|
|
|
|
Unlike Linux, a NuttX FIFO is not a special file type but simply a device driver instance.
|
|
|
|
|
<code>mode</code> specifies the FIFO's permissions (but is ignored in the current implementation).
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Once the FIFO has been created by <code>mkfifo()</code>, any thread can open it for
|
|
|
|
|
reading or writing, in the same way as an ordinary file.
|
|
|
|
|
However, it must have been opened from both reading and writing before input or output can be performed.
|
|
|
|
|
This FIFO implementation will block all attempts to open a FIFO read-only until at least one thread has opened the FIFO for writing.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If all threads that write to the FIFO have closed, subsequent calls to <code>read()</code> on the FIFO will return 0 (end-of-file).
|
|
|
|
|
</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>pathname</code>.
|
|
|
|
|
The full path to the FIFO instance to attach to or to create (if not already created).
|
|
|
|
|
</li>
|
|
|
|
|
<li><code>mode<code>.
|
|
|
|
|
Ignored for now
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<p>
|
|
|
|
|
0 is returned on success; otherwise, -1 is returned with <code>errno</code> set appropriately.
|
|
|
|
|
</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="fatsupport">2.11.6 FAT File System Support</a></h3>
|
|
|
|
|
<h3>2.11.6.1 <a name="mkfatfs"><code>mkfatfs</code></a></h3>
|
2008-07-26 17:09:21 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
2008-08-10 18:36:33 +02:00
|
|
|
<ul><pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <nuttx/mkfatfs.h>
|
2008-08-10 18:36:33 +02:00
|
|
|
int mkfatfs(FAR const char *pathname, FAR struct fat_format_s *fmt);
|
|
|
|
|
</pre></ul>
|
2008-07-26 17:09:21 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<p>
|
2008-09-04 16:55:48 +02:00
|
|
|
The <code>mkfats()</code> formats a FAT file system image on the block
|
2008-08-10 18:36:33 +02:00
|
|
|
device specified by <code>pathname</code>
|
|
|
|
|
</p>
|
|
|
|
|
<p>Assumptions: The caller must assure that the block driver is not mounted and not in
|
|
|
|
|
use when this function is called.
|
|
|
|
|
The result of formatting a mounted device is indeterminate (but likely not good).
|
2008-07-26 17:09:21 +02:00
|
|
|
</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
2008-08-10 18:36:33 +02:00
|
|
|
<code>pathname</code>
|
|
|
|
|
The full path to the registered block driver in the file system.
|
2008-07-26 17:09:21 +02:00
|
|
|
</li>
|
|
|
|
|
<li>
|
2008-08-10 18:36:33 +02:00
|
|
|
<code>fmt</code>
|
|
|
|
|
A reference to an instance of a structure that provides caller-selectable
|
|
|
|
|
attributes of the created FAT file system.
|
|
|
|
|
<ul>
|
|
|
|
|
<pre>
|
|
|
|
|
struct fat_format_s
|
|
|
|
|
{
|
|
|
|
|
ubyte ff_nfats; /* Number of FATs */
|
|
|
|
|
ubyte ff_fattype; /* FAT size: 0 (autoselect), 12, 16, or 32 */
|
|
|
|
|
ubyte ff_clustshift; /* Log2 of sectors per cluster: 0-5, 0xff (autoselect) */
|
|
|
|
|
ubyte ff_volumelabel[11]; /* Volume label */
|
|
|
|
|
uint16 ff_backupboot; /* Sector number of the backup boot sector (0=use default)*/
|
|
|
|
|
uint16 ff_rootdirentries; /* Number of root directory entries */
|
|
|
|
|
uint16 ff_rsvdseccount; /* Reserved sectors */
|
|
|
|
|
uint32 ff_hidsec; /* Count of hidden sectors preceding fat */
|
|
|
|
|
uint32 ff_volumeid; /* FAT volume id */
|
|
|
|
|
uint32 ff_nsectors; /* Number of sectors from device to use: 0: Use all */
|
|
|
|
|
};
|
|
|
|
|
</pre>
|
|
|
|
|
</ul></li>
|
2008-07-26 17:09:21 +02:00
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<p>
|
2008-08-10 18:36:33 +02:00
|
|
|
Zero (<code>OK</code>) on success;
|
|
|
|
|
-1 (<code>ERROR</code>) on failure with <code>errno</code> set appropriately:
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EINVAL</code> -
|
|
|
|
|
NULL block driver string, bad number of FATS in <code>fmt</code>,
|
|
|
|
|
bad FAT size in <code>fmt</code>, bad cluster size in <code>fmt</code>
|
|
|
|
|
</li>
|
|
|
|
|
<li><code>ENOENT</code> -
|
|
|
|
|
<code>pathname</code> does not refer to anything in the filesystem.
|
|
|
|
|
</li>
|
|
|
|
|
<li><code>ENOTBLK</code> -
|
|
|
|
|
<code>pathname</code> does not refer to a block driver
|
|
|
|
|
</li>
|
|
|
|
|
<li><code>EACCESS</code> -
|
|
|
|
|
block driver does not support write or geometry methods
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
2008-07-26 17:09:21 +02:00
|
|
|
</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<h3><a name="mmapxip">2.11.7 <code>mmap()</code> and eXecute In Place (XIP)</a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
NuttX operates in a flat open address space.
|
|
|
|
|
Therefore, it generally does not require <code>mmap()</code> functionality.
|
|
|
|
|
There is one one exception:
|
|
|
|
|
<code>mmap()</code> is the API that is used to support direct access to random
|
|
|
|
|
access media under the following very restrictive conditions:
|
|
|
|
|
<ol>
|
|
|
|
|
<li>
|
|
|
|
|
The filesystem supports the <code>FIOC_MMAP</code> ioctl command.
|
|
|
|
|
Any file system that maps files contiguously on the media should support this
|
|
|
|
|
<code>ioctl</code> command.
|
|
|
|
|
By comparison, most file system scatter files over the media in non-contiguous
|
|
|
|
|
sectors. As of this writing, ROMFS is the only file system that meets this requirement.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
The underly block driver supports the <code>BIOC_XIPBASE</code> <code>ioctl</code> command
|
|
|
|
|
that maps the underlying media to a randomly accessible address.
|
|
|
|
|
At present, only the RAM/ROM disk driver does this.
|
|
|
|
|
</li>
|
|
|
|
|
</ol>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3><a name="mmap">2.11.7.1 <code>mmap</code></a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul><pre>
|
|
|
|
|
#include <sys/mman.h>
|
|
|
|
|
int mkfatfs(FAR const char *pathname, FAR struct fat_format_s *fmt);
|
|
|
|
|
FAR void *mmap(FAR void *start, size_t length, int prot, int flags, int fd, off_t offset)
|
|
|
|
|
</pre></ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
Provides minimal <code>mmap()</code> as needed to support eXecute In Place (XIP)
|
|
|
|
|
operation (as described above).
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>start</code>
|
|
|
|
|
A hint at where to map the memory -- ignored.
|
|
|
|
|
The address of the underlying media is fixed and cannot be re-mapped without MMU support.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>length</code>
|
|
|
|
|
The length of the mapping -- ignored.
|
|
|
|
|
The entire underlying media is always accessible.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>prot</code>
|
|
|
|
|
See the <code>PROT_*</code> definitions in <code>sys/mman.h</code>.
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>PROT_NONE</code> - Will cause an error.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>PROT_READ</code> - <code>PROT_WRITE</code> and <code>PROT_EXEC</code> also assumed.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>PROT_WRITE</code> - <code>PROT_READ</code> and <code>PROT_EXEC</code> also assumed.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>PROT_EXEC</code> - <code>PROT_READ</code> and <code>PROT_WRITE</code> also assumed.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>flags</code>
|
|
|
|
|
See the <code>MAP_*</code> definitions in <code>sys/mman.h</code>.
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_SHARED</code> - Required
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_PRIVATE</code> - Will cause an error
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_FIXED</code> - Will cause an error
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_FILE</code> - Ignored
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_ANONYMOUS</code> - Will cause an error
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_ANON</code> - Will cause an error
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_GROWSDOWN</code> - Ignored
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_DENYWRITE</code> - Will cause an error
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_EXECUTABLE</code> - Ignored
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_LOCKED</code> - Ignored
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_NORESERVE</code> - Ignored
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>MAP_POPULATE</code> - Ignored
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>AP_NONBLOCK</code> - Ignored
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>fd</code>
|
|
|
|
|
file descriptor of the backing file -- required.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
<code>offset</code>
|
|
|
|
|
The offset into the file to map.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
<ul>
|
|
|
|
|
<p>
|
|
|
|
|
On success, <code>mmap()</code> returns a pointer to the mapped area.
|
|
|
|
|
On error, the value <code>MAP_FAILED</code> is returned, and <code>errno</code> is set appropriately.
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>ENOSYS</code> -
|
|
|
|
|
Returned if any of the unsupported <code>mmap()</code> features are attempted.
|
|
|
|
|
</li>
|
|
|
|
|
<li><code>EBADF</code> -
|
|
|
|
|
<code>fd</code> is not a valid file descriptor.
|
|
|
|
|
</li>
|
|
|
|
|
<li><code>EINVAL</code> -
|
|
|
|
|
Length is 0. flags contained neither <code>MAP_PRIVATE</code> or <code>MAP_SHARED</code>, or
|
|
|
|
|
contained both of these values.
|
|
|
|
|
</li>
|
|
|
|
|
<li><code>ENODEV</code> -
|
|
|
|
|
The underlying filesystem of the specified file does not support memory mapping.
|
|
|
|
|
</li>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
</ul>
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Network"><h2>2.12 Network Interfaces</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-09-08 17:26:55 +02:00
|
|
|
<p>NuttX includes a simple interface layer based on uIP (see <a href="http://www.sics.se/~adam/uip/index.php/Main_Page">http://www.sics.se</a>).
|
|
|
|
|
NuttX supports subset of a standard socket interface to uIP.
|
|
|
|
|
These network feature can be enabled by settings in the architecture
|
|
|
|
|
<a href="NuttxPortingGuide.html#apndxconfigs">configuration file</a>.
|
|
|
|
|
Those socket APIs are discussed in the following paragraphs.</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li>
|
|
|
|
|
</li>
|
|
|
|
|
<li><a href="#socket">2.12.1 socket</a></li>
|
|
|
|
|
<li><a href="#bind">2.12.2 bind</a></li>
|
|
|
|
|
<li><a href="#connect">2.12.3 connect</a></li>
|
2007-09-23 18:58:09 +02:00
|
|
|
<li><a href="#listen">2.12.4 listen</a></li>
|
|
|
|
|
<li><a href="#accept">2.12.5 accept</a></li>
|
|
|
|
|
<li><a href="#send">2.12.6 send</a></li>
|
|
|
|
|
<li><a href="#sendto">2.12.7 sendto</a></li>
|
|
|
|
|
<li><a href="#recv">2.12.8 recv</a></li>
|
|
|
|
|
<li><a href="#recvfrom">2.12.9 recvfrom</a></li>
|
|
|
|
|
<li><a href="#setsockopt">2.12.10 setsockopt</a></li>
|
|
|
|
|
<li><a href="#getsockopt">2.12.11 getsockopt</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3><a name="socket">2.12.1 <code>socket</code></a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
int socket(int domain, int type, int protocol);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
socket() creates an endpoint for communication and returns a descriptor.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>domain</code>: (see sys/socket.h)</li>
|
|
|
|
|
<li><code>type</code>: (see sys/socket.h)</li>
|
|
|
|
|
<li><code>protocol</code>: (see sys/socket.h)</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2008-02-03 18:09:22 +01:00
|
|
|
0 on success; -1 on error with <a href="#ErrnoAccess"><code>errno</code></a> set appropriately:
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EACCES</code>.
|
|
|
|
|
Permission to create a socket of the specified type and/or protocol is denied.</li>
|
|
|
|
|
<li><code>EAFNOSUPPORT</code>.
|
|
|
|
|
The implementation does not support the specified address family.</li>
|
|
|
|
|
<li><code>EINVAL</code>.
|
|
|
|
|
Unknown protocol, or protocol family not available.</li>
|
|
|
|
|
<li><code>EMFILE</code>.
|
|
|
|
|
Process file table overflow.</li>
|
|
|
|
|
<li><code>ENFILE</code>
|
|
|
|
|
The system limit on the total number of open files has been reached.</li>
|
|
|
|
|
<li><code>ENOBUFS</code> or <code>ENOMEM</code>.
|
|
|
|
|
Insufficient memory is available. The socket cannot be created until sufficient resources are freed.</li>
|
|
|
|
|
<li><code>EPROTONOSUPPORT</code>.
|
|
|
|
|
The protocol type or the specified protocol is not supported within this domain.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3><a name="bind">2.12.2 <code>bind</code></a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
int bind(int sockfd, const struct sockaddr *addr, socklen_t addrlen);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<code>bind()</code> gives the socket sockfd the local address <code>addr</code>.
|
|
|
|
|
<code>addr</code> is <code>addrlen</code> bytes long. Traditionally, this is called
|
|
|
|
|
"assigning a name to a socket." When a socket is created with <code>socket()</code>,
|
|
|
|
|
it exists in a name space (address family) but has no name assigned.
|
|
|
|
|
<p>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor from socket.</li>
|
|
|
|
|
<li><code>addr</code>: Socket local address.</li>
|
|
|
|
|
<li><code>addrlen</code>: Length of <code>addr</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2008-02-03 18:09:22 +01:00
|
|
|
0 on success; -1 on error with <a href="#ErrnoAccess"><code>errno</code></a> set appropriately:
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EACCES</code>
|
|
|
|
|
The address is protected, and the user is not the superuser.</li>
|
|
|
|
|
<li><code>EADDRINUSE</code>
|
|
|
|
|
The given address is already in use.</li>
|
|
|
|
|
<li><code>EBADF</code>
|
|
|
|
|
<code>sockfd</code> is not a valid descriptor.</li>
|
|
|
|
|
<li><code>EINVAL</code>
|
|
|
|
|
The socket is already bound to an address.</li>
|
|
|
|
|
<li><code>ENOTSOCK</code>
|
|
|
|
|
<code>sockfd</code> is a descriptor for a file, not a socket.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3><a name="connect">2.12.3 <code>connect</code></a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
int connect(int sockfd, const struct sockaddr *addr, socklen_t addrlen);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<code>connect()</code> connects the socket referred to by the file descriptor
|
|
|
|
|
<code>sockfd</code> to the address specified by <code>addr</code>.
|
|
|
|
|
The <code>addrlen</code> argument specifies the size of <code>addr</code>.
|
|
|
|
|
The format of the address in <code>addr</code> is determined by the address space
|
|
|
|
|
of the socket sockfd.
|
|
|
|
|
|
|
|
|
|
If the socket sockfd is of type SOCK_DGRAM then <code>addr</code> is the address
|
|
|
|
|
to which datagrams are sent by default, and the only address from which
|
|
|
|
|
datagrams are received. If the socket is of type SOCK_STREAM or
|
|
|
|
|
SOCK_SEQPACKET, this call attempts to make a connection to the socket
|
|
|
|
|
that is bound to the address specified by <code>addr</code>.
|
|
|
|
|
|
|
|
|
|
Generally, connection-based protocol sockets may successfully <code>connect()</code>
|
|
|
|
|
only once; connectionless protocol sockets may use <code>connect()</code> multiple
|
|
|
|
|
times to change their association. Connectionless sockets may dissolve
|
|
|
|
|
the association by connecting to an address with the sa_family member of
|
|
|
|
|
sockaddr set to AF_UNSPEC.
|
|
|
|
|
<p>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor returned by <code>socket()</code></li>
|
|
|
|
|
<li><code>addr</code>: Server address (form depends on type of socket)</li>
|
|
|
|
|
<li><code>addrlen</code>: Length of actual <code>addr</code></li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2008-02-03 18:09:22 +01:00
|
|
|
0 on success; -1 on error with <a href="#ErrnoAccess"><code>errno</code></a> set appropriately:
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<li><code>EACCES</code> or </code>EPERM</code>:
|
|
|
|
|
The user tried to connect to a broadcast address without having the
|
|
|
|
|
socket broadcast flag enabled or the connection request failed
|
|
|
|
|
because of a local firewall rule.</li>
|
|
|
|
|
<li><code>EADDRINUSE</code>
|
|
|
|
|
Local address is already in use.</li>
|
|
|
|
|
<li><code>EAFNOSUPPORT</code>
|
|
|
|
|
The passed address didn't have the correct address family in its
|
|
|
|
|
sa_family field.</li>
|
|
|
|
|
<li><code>EAGAIN</code>
|
|
|
|
|
No more free local ports or insufficient entries in the routing
|
|
|
|
|
cache. For PF_INET.</li>
|
|
|
|
|
<li><code>EALREADY</code>
|
|
|
|
|
The socket is non-blocking and a previous connection attempt has
|
|
|
|
|
not yet been completed.</li>
|
|
|
|
|
<li><code>EBADF</code>
|
|
|
|
|
The file descriptor is not a valid index in the descriptor table.</li>
|
|
|
|
|
<li><code>ECONNREFUSED</code>
|
|
|
|
|
No one listening on the remote address.</li>
|
|
|
|
|
<li><code>EFAULT</code>
|
|
|
|
|
The socket structure address is outside the user's address space.</li>
|
|
|
|
|
<li><code>EINPROGRESS</code>
|
|
|
|
|
The socket is non-blocking and the connection cannot be completed
|
|
|
|
|
immediately.</li>
|
|
|
|
|
<li><code>EINTR</code>
|
|
|
|
|
The system call was interrupted by a signal that was caught.</li>
|
|
|
|
|
<li><code>EISCONN</code>
|
|
|
|
|
The socket is already connected.</li>
|
|
|
|
|
<li><code>ENETUNREACH</code>
|
|
|
|
|
Network is unreachable.</li>
|
|
|
|
|
<li><code>ENOTSOCK</code>
|
|
|
|
|
The file descriptor is not associated with a socket.</li>
|
|
|
|
|
<li><code>ETIMEDOUT</code>
|
|
|
|
|
Timeout while attempting connection. The server may be too busy
|
|
|
|
|
to accept new connections.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
2007-09-23 18:58:09 +02:00
|
|
|
<h3><a name="listen">2.12.4 listen</a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-23 18:58:09 +02:00
|
|
|
int listen(int sockfd, int backlog);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
To accept connections, a socket is first created with <code>socket()</code>, a
|
|
|
|
|
willingness to accept incoming connections and a queue limit for incoming
|
|
|
|
|
connections are specified with <code>listen()</code>, and then the connections are
|
|
|
|
|
accepted with <code>accept()</code>. The <code>listen()</coe> call applies only to sockets of
|
|
|
|
|
type <code>SOCK_STREAM</code> or <code>SOCK_SEQPACKET</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor of the bound socket.</li>
|
|
|
|
|
<li><code>backlog</code>: The maximum length the queue of pending connections may grow.
|
|
|
|
|
If a connection request arrives with the queue full, the client may receive an error
|
|
|
|
|
with an indication of ECONNREFUSED or, if the underlying protocol supports retransmission,
|
|
|
|
|
the request may be ignored so that retries succeed.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2008-02-03 18:09:22 +01:00
|
|
|
On success, zero is returned. On error, -1 is returned, and
|
|
|
|
|
<a href="#ErrnoAccess"><code>errno</code></a> is set appropriately.
|
2007-09-23 18:58:09 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EADDRINUSE</code>: Another socket is already listening on the same port.</li>
|
|
|
|
|
<li><code>EBADF</code>: The argument <code>sockfd</code> is not a valid descriptor.</li>
|
|
|
|
|
<li><code>ENOTSOCK</code>: The argument <code>sockfd</code> is not a socket.</li>
|
|
|
|
|
<li><code>EOPNOTSUPP</code>: The socket is not of a type that supports the listen operation.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3><a name="accept">2.12.5 accept</a></h3>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-23 18:58:09 +02:00
|
|
|
int accept(int sockfd, struct sockaddr *addr, socklen_t *addrlen);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>accept()</code> function is used with connection-based socket types
|
|
|
|
|
(<code>SOCK_STREAM</code>, <code>SOCK_SEQPACKET</code> and <code>SOCK_RDM</code>).
|
|
|
|
|
It extracts the first connection request on the queue of pending connections,
|
|
|
|
|
creates a new connected socket with most of the same properties as <code>sockfd</code>,
|
|
|
|
|
and allocates a new socket descriptor for the socket, which is returned. The
|
|
|
|
|
newly created socket is no longer in the listening state. The original
|
|
|
|
|
socket <code>sockfd</code> is unaffected by this call. Per file descriptor flags
|
|
|
|
|
are not inherited across an accept.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The <code>sockfd</code> argument is a socket descriptor that has been created with
|
|
|
|
|
<code>socket()</code>, bound to a local address with <code>bind()</code>, and is listening for
|
|
|
|
|
connections after a call to <code>listen()</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
On return, the <code>addr</code> structure is filled in with the address of the
|
|
|
|
|
connecting entity. The <code>addrlen</code> argument initially contains the size
|
|
|
|
|
of the structure pointed to by <code>addr</code>; on return it will contain the
|
|
|
|
|
actual length of the address returned.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If no pending connections are present on the queue, and the socket is
|
|
|
|
|
not marked as non-blocking, accept blocks the caller until a connection
|
|
|
|
|
is present. If the socket is marked non-blocking and no pending
|
|
|
|
|
connections are present on the queue, accept returns <code>EAGAIN</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor of the listening socket.</li>
|
|
|
|
|
<li><code>addr</code>: Receives the address of the connecting client.</li>
|
|
|
|
|
<li><code>addrlen</code>: Input: allocated size of <code>addr</code>, Return: returned size of <code>addr</code>.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
Returns -1 on error. If it succeeds, it returns a non-negative integer
|
|
|
|
|
that is a descriptor for the accepted socket.
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EAGAIN</code> or <code>EWOULDBLOCK</code>:
|
|
|
|
|
The socket is marked non-blocking and no connections are present to be accepted.</li>
|
|
|
|
|
<li><code>EBADF</code>:
|
|
|
|
|
The descriptor is invalid.</li>
|
|
|
|
|
<li><code>ENOTSOCK</code>:
|
|
|
|
|
The descriptor references a file, not a socket.</li>
|
|
|
|
|
<li><code>EOPNOTSUPP</code>:
|
|
|
|
|
The referenced socket is not of type <code>SOCK_STREAM</code>.</li>
|
|
|
|
|
<li><code>EINTR</code>:
|
|
|
|
|
The system call was interrupted by a signal that was caught before a valid connection arrived.</li>
|
|
|
|
|
<li><code>ECONNABORTED</code>:
|
|
|
|
|
A connection has been aborted.</li>
|
|
|
|
|
<li><code>EINVAL</code>:
|
|
|
|
|
Socket is not listening for connections.</li>
|
|
|
|
|
<li><code>EMFILE</code>:
|
|
|
|
|
The per-process limit of open file descriptors has been reached.</li>
|
|
|
|
|
<li><code>ENFILE</code>:
|
|
|
|
|
The system maximum for file descriptors has been reached.</li>
|
|
|
|
|
<li><code>EFAULT</code>:
|
|
|
|
|
The addr parameter is not in a writable part of the user address space.</li>
|
|
|
|
|
<li><code>ENOBUFS</code> or <code>ENOMEM</code>:
|
|
|
|
|
Not enough free memory.</li>
|
|
|
|
|
<li><code>EPROTO</code>:
|
|
|
|
|
Protocol error.</li>
|
|
|
|
|
<li><code>EPERM</code>:
|
|
|
|
|
Firewall rules forbid connection.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3><a name="send">2.12.6 <code>send</code></a></h3>
|
2007-09-08 17:26:55 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
ssize_t send(int sockfd, const void *buf, size_t len, int flags);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>send()</code> call may be used only when the socket is in a connected state
|
|
|
|
|
(so that the intended recipient is known).
|
|
|
|
|
The only difference between <code>send()</code> and <code>write()</code> is the
|
|
|
|
|
presence of <code>flags</code>.
|
|
|
|
|
With <code>zero</code> flags parameter, <code>send()</code> is equivalent to
|
|
|
|
|
<code>write()</code>. Also, <code>send(s,buf,len,flags)</code> is
|
|
|
|
|
equivalent to <code>sendto(s,buf,len,flags,NULL,0)</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor of socket
|
|
|
|
|
<li><code>buf</code>: Data to send
|
|
|
|
|
<li><code>len</code>: Length of data to send
|
|
|
|
|
<li><code>flags</code>: Send flags
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
See <a href="#sendto"><code>sendto()</code></a>.
|
|
|
|
|
</p>
|
|
|
|
|
|
2007-09-23 18:58:09 +02:00
|
|
|
<h3><a name="sendto">2.12.7 <code>sendto</code></a></h3>
|
2007-09-08 17:26:55 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
ssize_t sendto(int sockfd, const void *buf, size_t len, int flags,
|
|
|
|
|
const struct sockaddr *to, socklen_t tolen);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
If <code>sendto()</code> is used on a connection-mode (SOCK_STREAM, SOCK_SEQPACKET)
|
|
|
|
|
socket, the parameters to and tolen are ignored (and the error EISCONN
|
|
|
|
|
may be returned when they are not NULL and 0), and the error ENOTCONN is
|
|
|
|
|
returned when the socket was not actually connected.
|
|
|
|
|
<p>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor of socket
|
|
|
|
|
<li><code>buf</code>: Data to send
|
|
|
|
|
<li><code>len</code>: Length of data to send
|
|
|
|
|
<li><code>flags</code>: Send flags
|
|
|
|
|
<li><code>to</code>: Address of recipient
|
|
|
|
|
<li><code>tolen</code>: The length of the address structure
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
2008-02-03 18:09:22 +01:00
|
|
|
On success, returns the number of characters sent. On error, -1 is returned,
|
|
|
|
|
and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EAGAIN</code> or <code>EWOULDBLOCK</code>.
|
|
|
|
|
The socket is marked non-blocking and the requested operation would block.
|
|
|
|
|
<li><code>EBADF</code>.
|
|
|
|
|
An invalid descriptor was specified.
|
|
|
|
|
<li><code>ECONNRESET</code>.
|
|
|
|
|
Connection reset by peer.
|
|
|
|
|
<li><code>EDESTADDRREQ</code>.
|
|
|
|
|
The socket is not connection-mode, and no peer address is set.
|
|
|
|
|
<li><code>EFAULT</code>.
|
|
|
|
|
An invalid user space address was specified for a parameter.
|
|
|
|
|
<li><code>EINTR</code>.
|
|
|
|
|
A signal occurred before any data was transmitted.
|
|
|
|
|
<li><code>EINVAL</code>.
|
|
|
|
|
Invalid argument passed.
|
|
|
|
|
<li><code>EISCONN</code>.
|
|
|
|
|
The connection-mode socket was connected already but a recipient
|
|
|
|
|
was specified. (Now either this error is returned, or the recipient
|
|
|
|
|
specification is ignored.)
|
|
|
|
|
<li><code>EMSGSIZE</code>.
|
|
|
|
|
The socket type requires that message be sent atomically, and the
|
|
|
|
|
size of the message to be sent made this impossible.
|
|
|
|
|
<li><code>ENOBUFS</code>.
|
|
|
|
|
The output queue for a network interface was full. This generally
|
|
|
|
|
indicates that the interface has stopped sending, but may be
|
|
|
|
|
caused by transient congestion.
|
|
|
|
|
<li><code>ENOMEM</code>.
|
|
|
|
|
No memory available.
|
|
|
|
|
<li><code>ENOTCONN</code>.
|
|
|
|
|
The socket is not connected, and no target has been given.
|
|
|
|
|
<li><code>ENOTSOCK</code>.
|
|
|
|
|
The argument s is not a socket.
|
|
|
|
|
<li><code>EOPNOTSUPP</code>.
|
|
|
|
|
Some bit in the flags argument is inappropriate for the socket type.
|
|
|
|
|
<li><code>EPIPE</code>.
|
|
|
|
|
The local end has been shut down on a connection oriented socket.
|
|
|
|
|
In this case the process will also receive a SIGPIPE unless
|
|
|
|
|
MSG_NOSIGNAL is set.
|
|
|
|
|
</ul>
|
|
|
|
|
|
2007-09-23 18:58:09 +02:00
|
|
|
<h3><a name="recv">2.12.8 <code>recv</code></a></h3>
|
2007-09-08 17:26:55 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
ssize_t recv(int sockfd, void *buf, size_t len, int flags);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
The <code>recv()</code> call is identical to
|
|
|
|
|
<a href="#recvfrom"><code>recvfrom()</code></a> with a NULL
|
|
|
|
|
<code>from</code> parameter.
|
|
|
|
|
<p>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
</li>
|
|
|
|
|
<li>sockfd</code>: Socket descriptor of socket </li>
|
|
|
|
|
<li>buf</code>: Buffer to receive data </li>
|
|
|
|
|
<li>len</code>: Length of buffer </li>
|
|
|
|
|
<li>flags</code>: Receive flags </li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
see <a href="#recvfrom"><code>recvfrom()</code></a>.
|
|
|
|
|
Zero on success.
|
|
|
|
|
</p>
|
|
|
|
|
|
2007-09-23 18:58:09 +02:00
|
|
|
<h3><a name="recvfrom">2.12.9 <code>recvfrom</code></a></h3>
|
2007-09-08 17:26:55 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
ssize_t recvfrom(int sockfd, void *buf, size_t len, int flags,
|
|
|
|
|
struct sockaddr *from, socklen_t *fromlen);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<code>recvfrom()</code> receives messages from a socket, and may be used to receive
|
|
|
|
|
data on a socket whether or not it is connection-oriented.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If <code>from</code> is not NULL, and the underlying protocol provides the source
|
|
|
|
|
address, this source address is filled in. The argument <code>fromlen</code>
|
|
|
|
|
initialized to the size of the buffer associated with <code>from</code>, and modified
|
|
|
|
|
on return to indicate the actual size of the address stored there.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor of socket.</li>
|
|
|
|
|
<li><code>buf</code>: Buffer to receive data.</li>
|
|
|
|
|
<li><code>len</code>: Length of buffer.</li>
|
|
|
|
|
<li><code>flags</code>: Receive flags.</li>
|
|
|
|
|
<li><code>from</code>: Address of source.</li>
|
|
|
|
|
<li><code>fromlen</code>: The length of the address structure.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
On success, returns the number of characters sent.
|
2008-02-03 18:09:22 +01:00
|
|
|
On error, -1 is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>EAGAIN</code>.
|
|
|
|
|
The socket is marked non-blocking and the receive operation would block,
|
|
|
|
|
or a receive timeout had been set and the timeout expired before data
|
|
|
|
|
was received.
|
|
|
|
|
<li><code>EBADF</code>.
|
|
|
|
|
The argument <code>sockfd</code> is an invalid descriptor.
|
|
|
|
|
<li><code>ECONNREFUSED</code>.
|
|
|
|
|
A remote host refused to allow the network connection (typically because
|
|
|
|
|
it is not running the requested service).
|
|
|
|
|
<li><code>EFAULT</code>.
|
|
|
|
|
The receive buffer pointer(s) point outside the process's address space.
|
|
|
|
|
<li><code>EINTR</code>.
|
|
|
|
|
The receive was interrupted by delivery of a signal before any data were
|
|
|
|
|
available.
|
|
|
|
|
<li><code>EINVAL</code>.
|
|
|
|
|
Invalid argument passed.
|
|
|
|
|
<li><code>ENOMEM</code>.
|
|
|
|
|
Could not allocate memory.
|
|
|
|
|
<li><code>ENOTCONN</code>.
|
|
|
|
|
The socket is associated with a connection-oriented protocol and has
|
|
|
|
|
not been connected.
|
|
|
|
|
<li><code>ENOTSOCK</code>.
|
|
|
|
|
The argument <code>sockfd</code> does not refer to a socket.
|
|
|
|
|
</ul>
|
|
|
|
|
|
2007-09-23 18:58:09 +02:00
|
|
|
<h3><a name="setsockopt">2.12.10 <code>setsockopt</code></a></h3>
|
2007-09-08 17:26:55 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
int setsockopt(int sockfd, int level, int option,
|
|
|
|
|
const void *value, socklen_t value_len);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<code>setsockopt()</code> sets the option specified by the <code>option</code> argument,
|
|
|
|
|
at the protocol level specified by the <code>level</code> argument, to the value
|
|
|
|
|
pointed to by the <code>value</code> argument for the socket associated with the
|
|
|
|
|
file descriptor specified by the <code>sockfd</code> argument.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The <code>level</code> argument specifies the protocol level of the option. To set
|
|
|
|
|
options at the socket level, specify the level argument as SOL_SOCKET.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2008-09-12 21:17:15 +02:00
|
|
|
See <code>sys/socket.h</code> for a complete list of values for the <code>option</code> argument.
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd</code>: Socket descriptor of socket
|
|
|
|
|
<li><code>level</code>: Protocol level to set the option
|
|
|
|
|
<li><code>option</code>: identifies the option to set
|
|
|
|
|
<li><code>value</code>: Points to the argument value
|
|
|
|
|
<li><code>value_len</code>: The length of the argument value
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
On success, returns the number of characters sent.
|
2008-02-03 18:09:22 +01:00
|
|
|
On error, -1 is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>BADF</code>.
|
|
|
|
|
The <code>sockfd</code> argument is not a valid socket descriptor.
|
|
|
|
|
<li><code>DOM</code>.
|
|
|
|
|
The send and receive timeout values are too big to fit into the
|
|
|
|
|
timeout fields in the socket structure.
|
|
|
|
|
<li><code>INVAL</code>.
|
|
|
|
|
The specified option is invalid at the specified socket <code>level</code> or the
|
|
|
|
|
socket has been shut down.
|
|
|
|
|
<li><code>ISCONN</code>.
|
|
|
|
|
The socket is already connected, and a specified option cannot be set
|
|
|
|
|
while the socket is connected.
|
|
|
|
|
<li><code>NOPROTOOPT</code>.
|
|
|
|
|
The <code>option</code> is not supported by the protocol.
|
|
|
|
|
<li><code>NOTSOCK</code>.
|
|
|
|
|
The <code>sockfd</code> argument does not refer to a socket.
|
|
|
|
|
<li><code>NOMEM</code>.
|
|
|
|
|
There was insufficient memory available for the operation to complete.
|
|
|
|
|
<li><code>NOBUFS</code>.
|
|
|
|
|
Insufficient resources are available in the system to complete the call.
|
|
|
|
|
</ul>
|
|
|
|
|
|
2007-09-23 18:58:09 +02:00
|
|
|
<h3><a name="getsockopt">2.12.11 <code>getsockopt</code></a></h3>
|
2007-09-08 17:26:55 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Function Prototype:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
2008-09-12 21:17:15 +02:00
|
|
|
#include <sys/socket.h>
|
2007-09-08 17:26:55 +02:00
|
|
|
int getsockopt(int sockfd, int level, int option,
|
|
|
|
|
void *value, socklen_t *value_len);
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Description:</b>
|
|
|
|
|
<code>getsockopt()</code> retrieve thse value for the option specified by the
|
|
|
|
|
<code>option</code> argument for the socket specified by the <code>sockfd</code> argument. If
|
|
|
|
|
the size of the option value is greater than <code>value_len</code>, the value
|
|
|
|
|
stored in the object pointed to by the <code>value</code> argument will be silently
|
|
|
|
|
truncated. Otherwise, the length pointed to by the <code>value_len</code> argument
|
|
|
|
|
will be modified to indicate the actual length of the<code>value</code>.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
The <code>level</code> argument specifies the protocol level of the option. To
|
|
|
|
|
retrieve options at the socket level, specify the level argument as
|
|
|
|
|
SOL_SOCKET.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2008-09-12 21:17:15 +02:00
|
|
|
See <code>sys/socket.h</code>for a complete list of values for the <code>option</code> argument.
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters:</b>
|
|
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>sockfd Socket descriptor of socket
|
|
|
|
|
<li><code>level Protocol level to set the option
|
|
|
|
|
<li><code>option identifies the option to get
|
|
|
|
|
<li><code>value Points to the argument value
|
|
|
|
|
<li><code>value_len The length of the argument value
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values:</b>
|
|
|
|
|
On success, returns the number of characters sent.
|
2008-02-03 18:09:22 +01:00
|
|
|
On error, -1 is returned, and <a href="#ErrnoAccess"><code>errno</code></a> is set appropriately:
|
2007-09-08 17:26:55 +02:00
|
|
|
</p>
|
|
|
|
|
<ul>
|
|
|
|
|
<li><code>BADF</code>.
|
|
|
|
|
The <code>sockfd</code> argument is not a valid socket descriptor.</li>
|
|
|
|
|
<li><code>INVAL</code>.
|
|
|
|
|
The specified option is invalid at the specified socket <code>level</code> or the
|
|
|
|
|
socket has been shutdown.</li>
|
|
|
|
|
<li><code>NOPROTOOPT</code>.
|
|
|
|
|
The <code>option</code> is not supported by the protocol.</li>
|
|
|
|
|
<li><code>NOTSOCK</code>.
|
|
|
|
|
The <code>sockfd</code> argument does not refer to a socket.</li>
|
|
|
|
|
<li><code>NOBUFS
|
|
|
|
|
Insufficient resources are available in the system to complete the call.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="Data_Structures"><h1>3.0 OS Data Structures</h1></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
|
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="ScalarType"><h2>3.1 Scalar Types</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-11 18:37:47 +01:00
|
|
|
Many of the types used to communicate with NuttX are simple
|
2007-02-18 00:21:28 +01:00
|
|
|
scalar types. These types are used to provide architecture independence
|
2007-03-11 18:37:47 +01:00
|
|
|
of the OS from the application. The scalar types used at the NuttX
|
2007-02-18 00:21:28 +01:00
|
|
|
interface include:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>pid_t
|
|
|
|
|
<li>size_t
|
|
|
|
|
<li>sigset_t
|
|
|
|
|
<li>STATUS
|
|
|
|
|
<li>time_t
|
|
|
|
|
</ul>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="HiddenStructures"><h2>3.2 Hidden Interface Structures</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-03-11 18:37:47 +01:00
|
|
|
Several of the types used to interface with NuttX are
|
2007-02-18 00:21:28 +01:00
|
|
|
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:
|
2007-03-27 23:27:41 +02:00
|
|
|
<ul>
|
|
|
|
|
<li>_TCB
|
|
|
|
|
<li>mqd_t
|
|
|
|
|
<li>sem_t
|
|
|
|
|
<li>WDOG_ID
|
|
|
|
|
<li>pthread_key_t
|
|
|
|
|
</ul>
|
|
|
|
|
<p>
|
2008-02-03 18:09:22 +01:00
|
|
|
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>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="ErrnoAccess"><h2>3.3 Access to the <code>errno</code> Variable</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2008-02-03 18:09:22 +01:00
|
|
|
A pointer to the thread-specific <code>errno</code> value is available through a
|
|
|
|
|
function call:
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2008-02-03 18:09:22 +01:00
|
|
|
<b>Function Prototype:</b>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2008-09-12 21:17:15 +02:00
|
|
|
<pre> #include <errno.h>
|
2008-02-03 18:09:22 +01:00
|
|
|
#define errno *get_errno_ptr()
|
|
|
|
|
int *get_errno_ptr( void )</pre>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2008-02-03 18:09:22 +01:00
|
|
|
<b>Description</b>:
|
|
|
|
|
<code>get_errno_ptr()</code> returns a pointer to the thread-specific <code>errno</code> value.
|
|
|
|
|
Note that the symbol <code>errno</code> is defined to be <code>get_errno_ptr()</code> so that the usual
|
|
|
|
|
access by referencing the symbol <code>errno</code> will work as expected.
|
|
|
|
|
</p>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2008-02-03 18:09:22 +01:00
|
|
|
There is a unique, private <code>errno</code> value for each NuttX task.
|
|
|
|
|
However, the implementation of <code>errno</code> differs somewhat from the use of
|
|
|
|
|
<code>errno</code> in most multi-threaded process environments:
|
|
|
|
|
In NuttX, each pthread will also have its own private copy of <code>errno</code> and the
|
|
|
|
|
<code>errno</code> will not be shared between pthreads.
|
|
|
|
|
This is, perhaps, non-standard but promotes better thread independence.
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
|
|
|
|
<b>Input Parameters</b>: None
|
|
|
|
|
<p>
|
|
|
|
|
<b>Returned Values</b>:
|
|
|
|
|
<p>
|
|
|
|
|
<ul>
|
2008-02-03 18:09:22 +01:00
|
|
|
<li>A pointer to the thread-specific <code>errno</code> value.
|
2007-03-27 23:27:41 +02:00
|
|
|
</ul>
|
2008-09-12 21:17:15 +02:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="UserStructures"><h2>3.4 User Interface Structures</h2></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.1 main_t</H3>
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
main_t defines the type of a task entry point. main_t is declared
|
|
|
|
|
in sys/types.h as:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
typedef int (*main_t)(int argc, char *argv[]);
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.2 struct sched_param</H3>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
This structure is used to pass scheduling priorities to and from
|
2007-03-11 18:37:47 +01:00
|
|
|
NuttX;
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
struct sched_param
|
|
|
|
|
{
|
|
|
|
|
int sched_priority;
|
|
|
|
|
};
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.3 struct timespec</H3>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
This structure is used to pass timing information between the
|
2007-03-11 18:37:47 +01:00
|
|
|
NuttX and a user application:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
struct timespec
|
|
|
|
|
{
|
|
|
|
|
time_t tv_sec; /* Seconds */
|
|
|
|
|
long tv_nsec; /* Nanoseconds */
|
|
|
|
|
};
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.4 struct mq_attr</H3>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
This structure is used to communicate message queue attributes
|
2007-03-11 18:37:47 +01:00
|
|
|
between NuttX and a MoBY application:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
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 */
|
|
|
|
|
};
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.5 struct sigaction</H3>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
The following structure defines the action to take for given signal:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-21 03:19:19 +01:00
|
|
|
struct sigaction
|
|
|
|
|
{
|
|
|
|
|
union
|
|
|
|
|
{
|
|
|
|
|
void (*_sa_handler)(int);
|
|
|
|
|
void (*_sa_sigaction)(int, siginfo_t *, void *);
|
2007-02-18 00:21:28 +01:00
|
|
|
} sa_u;
|
|
|
|
|
sigset_t sa_mask;
|
|
|
|
|
int sa_flags;
|
|
|
|
|
};
|
|
|
|
|
#define sa_handler sa_u._sa_handler
|
|
|
|
|
#define sa_sigaction sa_u._sa_sigaction
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.6 struct siginfo/siginfo_t</H3>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
The following types is used to pass parameters to/from signal
|
|
|
|
|
handlers:
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
typedef struct siginfo
|
|
|
|
|
{
|
|
|
|
|
int si_signo;
|
|
|
|
|
int si_code;
|
|
|
|
|
union sigval si_value;
|
|
|
|
|
} siginfo_t;
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.7 union sigval</H3>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
This defines the type of the struct siginfo si_value field and
|
|
|
|
|
is used to pass parameters with signals.
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
union sigval
|
|
|
|
|
{
|
|
|
|
|
int sival_int;
|
|
|
|
|
void *sival_ptr;
|
|
|
|
|
};
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
|
|
|
|
|
<H3>3.4.8 struct sigevent</H3>
|
|
|
|
|
|
2007-03-27 23:27:41 +02:00
|
|
|
<p>
|
2007-02-18 00:21:28 +01:00
|
|
|
The following is used to attach a signal to a message queue to
|
|
|
|
|
notify a task when a message is available on a queue.
|
2007-03-28 18:00:57 +02:00
|
|
|
<pre>
|
2007-02-18 00:21:28 +01:00
|
|
|
struct sigevent
|
|
|
|
|
{
|
|
|
|
|
int sigev_signo;
|
|
|
|
|
union sigval sigev_value;
|
|
|
|
|
int sigev_notify;
|
|
|
|
|
};
|
2007-03-28 18:00:57 +02:00
|
|
|
</pre>
|
2007-02-21 22:55:16 +01:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
2008-09-12 21:17:15 +02:00
|
|
|
<table width ="100%">
|
|
|
|
|
<tr bgcolor="#e4e4e4">
|
|
|
|
|
<td>
|
|
|
|
|
<a name="index"><h1>Index</h1></a>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
|
2007-09-08 17:26:55 +02:00
|
|
|
<table width="100%">
|
|
|
|
|
<tr>
|
2008-09-01 22:35:41 +02:00
|
|
|
<td valign="top" width="34%">
|
2007-09-23 18:58:09 +02:00
|
|
|
<li><a href="#accept">accept</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li><a href="#bind">bind</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmapxip">BIOC_XIPBASE</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#dirunistdops">chdir</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrunistdops">close</a></li>
|
|
|
|
|
<li><a href="#dirdirentops">closedir</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li><a href="#connect">connect</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<li><a href="#Data_Structures">Data structures</a></li>
|
|
|
|
|
<li><a href="#directoryoperations">Directory operations</a></li>
|
2008-11-19 03:40:54 +01:00
|
|
|
<li><a href="#dirdirentops">dirent.h</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<li><a href="#driveroperations">Driver operations</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrunistdops">dup</a></li>
|
|
|
|
|
<li><a href="#drvrunistdops">dup2</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmapxip">eXecute In Place (XIP)</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#exit">exit</a></li>
|
2008-08-10 18:36:33 +02:00
|
|
|
<li><a href="#fatsupport">FAT File System Support</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">fclose</a></li>
|
2008-11-19 00:00:29 +01:00
|
|
|
<li><a href="#drvrfcntlops">fcntl.h</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">fdopen</a></li>
|
|
|
|
|
<li><a href="#standardio">feof</a></li>
|
|
|
|
|
<li><a href="#standardio">ferror</a></li>
|
2008-07-26 17:09:21 +02:00
|
|
|
<li><a href="#FileSystem">File system, interfaces</a></li>
|
|
|
|
|
<li><a href="#FileSystemOverview">File system, overview</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">fflush</a></li>
|
|
|
|
|
<li><a href="#standardio">fgetc</a></li>
|
|
|
|
|
<li><a href="#standardio">fgetpos</a></li>
|
|
|
|
|
<li><a href="#standardio">fgets</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmapxip">FIOC_MMAP</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">fopen</a></li>
|
|
|
|
|
<li><a href="#standardio">fprintf</a></li>
|
|
|
|
|
<li><a href="#standardio">fputc</a></li>
|
|
|
|
|
<li><a href="#standardio">fputs</a></li>
|
|
|
|
|
<li><a href="#standardio">fread</a></li>
|
|
|
|
|
<li><a href="#standardio">fseek</a></li>
|
|
|
|
|
<li><a href="#standardio">fsetpos</a></li>
|
2008-11-19 00:00:29 +01:00
|
|
|
<li><a href="#standardio">fstat</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">ftell</a></li>
|
|
|
|
|
<li><a href="#standardio">fwrite</a></li>
|
|
|
|
|
<li><a href="#dirunistdops">getcwd</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#getpid">getpid</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">gets</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li><a href="#getsockopt">getsockopt</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<li><a href="#gmtimer">gmtime_r</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#Introduction">Introduction</a>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrioctlops">ioctl</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#kill">kill</a></li>
|
2007-09-23 18:58:09 +02:00
|
|
|
<li><a href="#listen">listen</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<li><a href="#localtimer">localtime_r</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrunistdops">lseek</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#Message_Queue">Named Message Queue Interfaces</a>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">mkdir</a></li>
|
2008-08-10 18:36:33 +02:00
|
|
|
<li><a href="#mkfatfs">mkfatfs</a></li>
|
2008-07-26 17:09:21 +02:00
|
|
|
<li><a href="#mkfifo">mkfifo</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<li><a href="#mktime">mktime</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-29 15:25:18 +02:00
|
|
|
<li><a href="#mqtimedreceive">mq_timedreceive</a></li>
|
|
|
|
|
<li><a href="#mqtimedsend">mq_timedsend</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#mqunlink">mq_unlink</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmap">mmap</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li><a href="#Network">Network Interfaces</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrfcntlops">open</a></li>
|
|
|
|
|
<li><a href="#dirdirentops">opendir</a></li>
|
2008-07-26 17:09:21 +02:00
|
|
|
<li><a href="#OS_Interfaces">OS Interfaces</a></li>
|
2008-11-19 00:00:29 +01:00
|
|
|
<li><a href="#pipe">pipe</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
</td>
|
|
|
|
|
<td valign="top" width="33%">
|
2008-11-19 00:00:29 +01:00
|
|
|
<li><a href="#poll">poll</a></li>
|
|
|
|
|
<li><a href="#drvrpollops">poll.h</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">printf</a></li>
|
2007-03-24 00:22:22 +01:00
|
|
|
<li><a href="#Pthread">Pthread Interfaces</a>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2008-07-26 17:12:31 +02:00
|
|
|
<li><a href="#pthreadattrgetstacksize">pthread_attr_getstacksize</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-24 00:22:22 +01:00
|
|
|
<li><a href="#pthreadbarrierattrinit">pthread_barrierattr_init</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierattrdestroy">pthread_barrierattr_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierattrgetpshared">pthread_barrierattr_getpshared</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierattrsetpshared">pthread_barrierattr_setpshared</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierdestroy">pthread_barrier_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierinit">pthread_barrier_init</a></li>
|
|
|
|
|
<li><a href="#pthreadbarrierwait">pthread_barrier_wait</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-24 00:22:22 +01:00
|
|
|
<li><a href="#pthreadkill">pthread_kill</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#pthreadmutexattrdestroy">pthread_mutexattr_destroy</a></li>
|
|
|
|
|
<li><a href="#pthreadmutexattrgetpshared">pthread_mutexattr_getpshared</a></li>
|
2008-05-31 19:13:08 +02:00
|
|
|
<li><a href="#pthreadmutexattrgettype">pthread_mutexattr_gettype</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#pthreadmutexattrinit">pthread_mutexattr_init</a></li>
|
2008-08-10 18:36:33 +02:00
|
|
|
<li><a href="#pthreadmutexattrsetpshared">pthread_mutexattr_setpshared</a></li>
|
2008-07-26 17:09:21 +02:00
|
|
|
<li><a href="#pthreadmutexattrsettype">pthread_mutexattr_settype</a></li>
|
2008-05-31 19:13:08 +02:00
|
|
|
<li><a href="#pthreadmutexdestrory">pthread_mutex_destroy</a></li>
|
2007-09-23 18:58:09 +02:00
|
|
|
<li><a href="#pthreadmutexinit">pthread_mutex_init</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-24 00:22:22 +01:00
|
|
|
<li><a href="#pthreadonce">pthread_once</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-24 00:22:22 +01:00
|
|
|
<li><a href="#pthreadsigmask">pthread_sigmask</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#pthreadtestcancelstate">pthread_testcancelstate</a></li>
|
|
|
|
|
<li><a href="#pthreadyield">pthread_yield</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">puts</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmapxip">RAM disk driver</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrunistdops">read</a></li>
|
|
|
|
|
<li><a href="#dirdirentops">readdir</a></li>
|
|
|
|
|
<li><a href="#dirdirentops">readdir_r</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li><a href="#recv">recv</a></li>
|
|
|
|
|
<li><a href="#recvfrom">recvfrom</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">rename</a></li>
|
|
|
|
|
<li><a href="#standardio">rmdir</a></li>
|
|
|
|
|
<li><a href="#dirdirentops">rewinddir</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmapxip">ROM disk driver</a></li>
|
|
|
|
|
<li><a href="#mmapxip">ROMFS</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#schedgetparam">sched_getparam</a></li>
|
2008-11-19 00:00:29 +01:00
|
|
|
<li><a href="#schedgetprioritymax">sched_get_priority_max</a></li>
|
2008-11-19 03:40:54 +01:00
|
|
|
<li><a href="#schedgetprioritymin">sched_get_priority_min</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
</td>
|
|
|
|
|
<td valign="top">
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2008-11-19 00:00:29 +01:00
|
|
|
<li><a href="#select">select</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#dirdirentops">seekdir</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li><a href="#send">send</a></li>
|
|
|
|
|
<li><a href="#sendto">sendto</a></li>
|
|
|
|
|
<li><a href="#setsockopt">setsockopt</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-09-08 17:26:55 +02:00
|
|
|
<li><a href="#socket">socket</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">sprintf</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<li><a href="#standardio">Standard I/O</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">stat</a></li>
|
|
|
|
|
<li><a href="#standardio">statfs</a></li>
|
2008-11-19 03:40:54 +01:00
|
|
|
<li><a href="#standardio">stdio.h</a></li>
|
2008-11-19 00:00:29 +01:00
|
|
|
<li><a href="#drvselectops">sys/select.h</a></li>
|
|
|
|
|
<li><a href="#drvrioctlops">sys/ioctl.h</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#dirdirentops">telldir</a></li>
|
2007-03-21 01:56:49 +01:00
|
|
|
<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>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#standardio">ungetc</a></li>
|
2008-11-19 03:40:54 +01:00
|
|
|
<li><a href="#drvrunistdops">unistd.h</a>,
|
|
|
|
|
<a href="#dirunistdops">unistd.h</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrunistdops">unlink</a></li>
|
|
|
|
|
<li><a href="#standardio">vfprintf</a></li>
|
|
|
|
|
<li><a href="#standardio">vprintf</a></li>
|
|
|
|
|
<li><a href="#standardio">vsprintf</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<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>
|
2007-03-21 18:21:26 +01:00
|
|
|
<li><a href="#wdgettime">wd_gettime</a></li>
|
2007-03-20 20:03:11 +01:00
|
|
|
<li><a href="#wdstart">wd_start</a></li>
|
2008-09-01 22:35:41 +02:00
|
|
|
<li><a href="#drvrunistdops">write</a></li>
|
2008-09-12 21:17:15 +02:00
|
|
|
<li><a href="#mmapxip">XIP</a></li>
|
2007-09-08 17:26:55 +02:00
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
2007-03-20 20:03:11 +01:00
|
|
|
|
2007-02-18 00:21:28 +01:00
|
|
|
</BODY>
|
|
|
|
|
</HTML>
|
