User's Manual
by
Gregory Nutt
-
Last Updated: May 8, 2011
+Last Updated: July 19, 2011
@@ -247,11 +247,11 @@ paragraphs.Input Parameters:
CONFIG_MAX_TASK_ARG parameters may be provided.
If fewer than CONFIG_MAX_TASK_ARG parameters are
passed, the list should be terminated with a NULL argv[] value.
@@ -314,13 +314,13 @@ VxWorks provides the following similar interface:
Input Parameters:
CONFIG_MAX_TASK_ARG parameters may be provided.
If fewer than CONFIG_MAX_TASK_ARG parameters are
passed, the list should be terminated with a NULL argv[] value.
@@ -378,7 +378,7 @@ scheduler.
Input Parameters:
Input Parameters:
Input Parameters:
@@ -505,7 +505,7 @@ And the UNIX interface: The NuttX exit() differs from ANSI exit() in the following ways:
Input Parameters:
SCHED_FIFO or SCHED_RR).
+ policy. Scheduling policy requested (either SCHED_FIFO or SCHED_RR).
param. A structure whose member sched_priority is the
@@ -795,7 +795,7 @@ policy.
Input Parameters:
Input Parameters:
@@ -893,7 +893,7 @@ possible task priority for a specified scheduling policy.
Input Parameters:
@@ -930,9 +930,9 @@ interface of the same name. Input Parameters:
@@ -1105,27 +1105,27 @@ until it is closed by a successful call to mq_close().
Input Parameters:
If the calling task has attached a notification request to the message -queue via this mqdes (see mq_notify()), this attachment will be +queue via this mqdes (see mq_notify()), this attachment will be removed and the message queue is available for another task to attach for notification.
Input Parameters:
@@ -1219,7 +1219,7 @@ closed.
Input Parameters:
@@ -1569,13 +1569,13 @@ registration.
Input Parameters:
Input Parameters:
@@ -1653,14 +1653,14 @@ attributes associated with the specified message queue.
Input Parameters:
sched_lock().
However, consider the following example:
- At this point, the high-priority Task A cannot execute until - Task B (and possibly other medium-priority tasks) completes and until - Task C relinquishes the semaphore. In effect, the high-priority task, - Task A behaves as though it were lower in priority than the - low-priority task, Task C! This phenomenon is called priority - inversion. + At this point, the high-priority Task A cannot execute until + Task B (and possibly other medium-priority tasks) completes and until + Task C relinquishes the semaphore. In effect, the high-priority task, + Task A behaves as though it were lower in priority than the + low-priority task, Task C! This phenomenon is called priority + inversion.
- Some operating systems avoid priority inversion by automatically
- increasing the priority of the low-priority Task C (the operable
- buzz-word for this behavior is priority inheritance). NuttX
+ Some operating systems avoid priority inversion by automatically
+ increasing the priority of the low-priority Task C (the operable
+ buzz-word for this behavior is priority inheritance). NuttX
supports this behavior, but only if CONFIG_PRIORITY_INHERITANCE
is defined in your OS configuration file. If CONFIG_PRIORITY_INHERITANCE
is not defined, then it is left to the designer to provide implementations
@@ -1819,9 +1819,10 @@ interface of the same name.
-Only sem itself may be used for performing synchronization. The -result of referring to copies of sem in calls to sem_wait(), -sem_trywait(), sem_post(), and sem_destroy(), is +Only sem itself may be used for performing synchronization. The +result of referring to copies of sem in calls to sem_wait(), +sem_trywait(), sem_post(), and sem_destroy(), is not defined.
Input Parameters:
@@ -1878,18 +1879,18 @@ Differences from the full POSIX implementation include:
Description: This function is used to destroy the un-named semaphore -indicated by sem. Only a semaphore that was created using -sem_init() may be destroyed using sem_destroy(). The effect -of calling sem_destroy() with a named semaphore is undefined. The -effect of subsequent use of the semaphore sem is undefined until -sem is re-initialized by another call to sem_init(). +indicated by sem. Only a semaphore that was created using +sem_init() may be destroyed using sem_destroy(). The effect +of calling sem_destroy() with a named semaphore is undefined. The +effect of subsequent use of the semaphore sem is undefined until +sem is re-initialized by another call to sem_init().
The effect of destroying a semaphore upon which other tasks are currently blocked is undefined.
Input Parameters:
@@ -1928,27 +1929,27 @@ been no calls to sem_unlink()).
Input Parameters:
include/limits.h).
Input Parameters:
@@ -2033,7 +2034,7 @@ sem_close().
Input Parameters:
@@ -2078,7 +2079,7 @@ the lock or the call is interrupted by a signal.
Input Parameters:
@@ -2087,14 +2088,14 @@ the lock or the call is interrupted by a signal.
-If sem_wait returns -1 (ERROR) then the cause of the failure
+If sem_wait returns -1 (ERROR) then the cause of the failure
will be indicated by the thread-specific errno.
The following lists the possible values for errno:
@@ -2103,7 +2104,76 @@ received by this task. In this case, the semaphore has not be acquired. POSIX Compatibility: Comparable to the POSIX interface of the same name. -
+Function Prototype: +
+ #include <semaphore.h> + #include <time.h> + int sem_wait ( sem_t *sem, const struct timespec *abstime); ++ +
+Description:
+ This function will lock the semaphore referenced by sem as in the sem_wait() function.
+ However, if the semaphore cannot be locked without waiting for another process or thread to unlock the semaphore by performing a sem_post() function, this wait will be terminated when the specified timeout expires.
+
abstime passes, as measured by the clock on which timeouts are based (that is, when the value of that clock equals or exceeds abstime), or if the absolute time specified by abstime has already been passed at the time of the call.
+ This function attempts to lock the semaphore referenced by sem.
+ If the semaphore as already locked by another task, the calling task will not return until it either successfully acquires the lock or the call is interrupted by a signal.
++Input Parameters: +
+Returned Values: +
+If sem_wait returns -1 (ERROR) then the cause of the failure
+will be indicated by the thread-specific errno.
+The following lists the possible values for errno:
+
+
EINVAL:
+ Indicates that the sem input parameter is not valid or the
+ thread would have blocked, and the abstime parameter specified
+ a nanoseconds field value less than zero or greater than or
+ equal to 1000 million.
+ ETIMEDOUT:
+ The semaphore could not be locked before the specified timeout expired.
+ EDEADLK:
+ A deadlock condition was detected.
+ EINTR:
+ Indicates that the wait was interrupt by a signal received by this task.
+ In this case, the semaphore has not be acquired.
+ + Assumptions/Limitations: +
++ POSIX Compatibility: Derived from IEEE Std 1003.1d-1999. +
+ +Function Prototype: @@ -2119,7 +2189,7 @@ returns without blocking.
Input Parameters:
@@ -2127,14 +2197,14 @@ returns without blocking.
errno.
The following lists the possible values for errno:
@@ -2144,7 +2214,7 @@ not valid. POSIX Compatibility: Comparable to the POSIX interface of the same name. -
Function Prototype: @@ -2156,7 +2226,7 @@ interface of the same name.
Description: When a task has finished with a semaphore, it will call sem_post(). This function unlocks the semaphore referenced -by sem by performing the semaphore unlock operation. +by sem by performing the semaphore unlock operation.
If the semaphore value resulting from this operation is positive, then no tasks were blocked waiting for the semaphore to become unlocked; @@ -2164,13 +2234,13 @@ The semaphore value is simply incremented.
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 sem_wait(). +return successfully from its call to sem_wait().
-NOTE: sem_post() may be called from an interrupt handler. +NOTE: sem_post() may be called from an interrupt handler.
Input Parameters:
@@ -2187,7 +2257,7 @@ task is the one that is performing the unlock. POSIX Compatibility: Comparable to the POSIX interface of the same name. -
Function Prototype: @@ -2210,8 +2280,8 @@ number of tasks waiting for the semaphore.
Input Parameters:
@@ -2306,7 +2376,7 @@ has been started.
Input Parameters:
Input Parameters:
@@ -2407,7 +2477,7 @@ level.
Input Parameters:
@@ -2495,7 +2565,7 @@ VxWorks provides the following comparable interface: Returned Values:
- If successful, the clock_settime() function will return zero (OK). + If successful, the clock_settime() function will return zero (OK). Otherwise, an non-zero error number will be returned to indicate the error:
- If successful, the clock_gettime() function will return zero (OK). + If successful, the clock_gettime() function will return zero (OK). Otherwise, an non-zero error number will be returned to indicate the error:
- If successful, the clock_getres() function will return zero (OK). + If successful, the clock_getres() function will return zero (OK). Otherwise, an non-zero error number will be returned to indicate the error:
- If successful, the mktime() function will return zero (OK). + If successful, the mktime() function will return zero (OK). Otherwise, an non-zero error number will be returned to indicate the error:
- If successful, the gmtime() function will return the pointer to a statically
+ If successful, the gmtime() function will return the pointer to a statically
defined instance of struct tim.
Otherwise, a NULL will be returned to indicate the error:
- If successful, the gmtime_r() function will return the pointer, result,
+ If successful, the gmtime_r() function will return the pointer, result,
provided by the caller.
Otherwise, a NULL will be returned to indicate the error:
- If successful, the timer_delete() function will return zero (OK).
+ If successful, the timer_delete() function will return zero (OK).
Otherwise, the function will return a value of -1 (ERROR) and set
errno to indicate the error:
- If successful, the timer_gettime() function will return zero (OK). + If successful, the timer_gettime() function will return zero (OK). Otherwise, an non-zero error number will be returned to indicate the error:
Input Parameters:
@@ -3084,7 +3154,7 @@ by set such that all signals are included.
Input Parameters:
@@ -3114,8 +3184,8 @@ signo to the signal set specified by set.
Input Parameters:
@@ -3145,8 +3215,8 @@ by signo from the signal set specified by set.
Input Parameters:
@@ -3176,8 +3246,8 @@ by signo is a member of the set specified by set.
Input Parameters:
@@ -3212,12 +3282,12 @@ signal. The structure sigaction, used to describe an action to be taken, is defined to include the following members:
If the argument act is not NULL, it points to a structure specifying the @@ -3243,9 +3313,9 @@ sigaction().
Input Parameters:
@@ -3290,19 +3360,19 @@ If sigprocmask() fails, the signal mask of the task is not changed.
Input Parameters:
@@ -3340,7 +3410,7 @@ is delivered more than once."
Input Parameters:
@@ -3379,7 +3449,7 @@ resources (a very bad idea).
Input Parameters:
Input Parameters:
@@ -3461,19 +3531,19 @@ 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:
Input Parameters:
@@ -3496,7 +3566,7 @@ from si_code in a non-standard way).
Input Parameters:
@@ -3584,12 +3654,12 @@ be sent.
Input Parameters:
kill() 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
-Returned Values:
-If successful, the pthread_attr_init() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_init() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_destroy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_destroy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_setschedpolicy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_setschedpolicy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_getschedpolicy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_getschedpolicy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_getschedpolicy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_getschedpolicy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_getschedparam() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_getschedparam() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_setinheritsched() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_setinheritsched() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_getinheritsched() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_getinheritsched() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_setstacksize() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_setstacksize() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_attr_getstacksize() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_attr_getstacksize() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_create() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_create() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_detach() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_detach() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_exit() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_exit() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_cancel() function will return zero (OK). +If successful, the pthread_cancel() function will return zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be returned to indicate the error: +If successful, the pthread_setcancelstate() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_setcancelstate() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_setcancelstate() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_join() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_join() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_yield() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_yield() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_self() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_self() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
- If successful, the pthread_setschedparam() function will return - zero (OK). Otherwise, an error number will be + If successful, the pthread_setschedparam() function will return + zero (OK). Otherwise, an error number will be returned to indicate the error:
-Upon key creation, the value NULL will be associated with +Upon key creation, the value NULL will be associated with the new key in all active threads. Upon thread -creation, the value NULL will be associated with all +creation, the value NULL will be associated with all defined keys in the new thread.
Input Parameters:
Returned Values:
-If successful, the pthread_key_create() function will -store the newly created key value at *key and return -zero (OK). Otherwise, an error number will be +If successful, the pthread_key_create() function will +store the newly created key value at *key and return +zero (OK). Otherwise, an error number will be returned to indicate the error:
@@ -4617,34 +4687,34 @@ interface of the same name.
Description:
-The pthread_setspecific() function associates a thread- +The pthread_setspecific() function associates a thread- specific value with a key obtained via a previous call -to pthread_key_create(). Different threads may bind +to pthread_key_create(). 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.
-The effect of calling pthread_setspecific() with a key value -not obtained from pthread_key_create() or after a key has been -deleted with pthread_key_delete() is undefined. +The effect of calling pthread_setspecific() with a key value +not obtained from pthread_key_create() or after a key has been +deleted with pthread_key_delete() is undefined.
Input Parameters:
Returned Values:
-If successful, pthread_setspecific() will return zero (OK). +If successful, pthread_setspecific() will return zero (OK). Otherwise, an error number will be returned:
Assumptions/Limitations: @@ -4667,26 +4737,26 @@ destructor function.
Description:
-The pthread_getspecific() function returns the value +The pthread_getspecific() function returns the value currently bound to the specified key on behalf of the calling thread.
-The effect of calling pthread_getspecific() with a key value -not obtained from pthread_key_create() or after a key has been -deleted with pthread_key_delete() is undefined. +The effect of calling pthread_getspecific() with a key value +not obtained from pthread_key_create() or after a key has been +deleted with pthread_key_delete() is undefined.
Input Parameters:
Returned Values:
-The function pthread_getspecific() returns the thread- +The function pthread_getspecific() returns the thread- specific data associated with the given key. If no thread specific data is associated with the key, then -the value NULL is returned. +the value NULL is returned.
Assumptions/Limitations:
@@ -4709,19 +4779,19 @@ destructor function. Description:
This POSIX function should delete a thread-specific data -key previously returned by pthread_key_create(). However, +key previously returned by pthread_key_create(). However, this function does nothing in the present implementation.
Input Parameters:
Returned Values:
Assumptions/Limitations: @@ -4748,8 +4818,8 @@ interface of the same name.
Returned Values:
-If successful, the pthread_mutexattr_init() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutexattr_init() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutexattr_destroy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutexattr_destroy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutexattr_getpshared() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutexattr_getpshared() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutexattr_setpshared() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutexattr_setpshared() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutexattr_settype() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutexattr_settype() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutexattr_settype() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutexattr_settype() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutex_init() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutex_init() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutex_destroy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutex_destroy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutex_lock() function will return zero (OK). +If successful, the pthread_mutex_lock() function will return zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutex_trylock() function will return zero (OK). +If successful, the pthread_mutex_trylock() function will return zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_mutex_unlock() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_mutex_unlock() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_condattr_init() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_condattr_init() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_condattr_destroy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_condattr_destroy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_cond_init() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_cond_init() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_cond_destroy() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_cond_destroy() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_cond_broadcast() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_cond_broadcast() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_cond_signal() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_cond_signal() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error:
Returned Values:
-If successful, the pthread_cond_wait() function will return -zero (OK). Otherwise, an error number will be +If successful, the pthread_cond_wait() function will return +zero (OK). Otherwise, an error number will be returned to indicate the error: