From 7479042a5914a6b9223e734b4a14652314661e1a Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Mon, 11 Oct 1999 21:24:38 +0000 Subject: Generated concept and function index entries. --- doc/posix_users/mutex.t | 292 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 194 insertions(+), 98 deletions(-) (limited to 'doc/posix_users/mutex.t') diff --git a/doc/posix_users/mutex.t b/doc/posix_users/mutex.t index 82f6767d5d..f39868bbcd 100644 --- a/doc/posix_users/mutex.t +++ b/doc/posix_users/mutex.t @@ -1,9 +1,9 @@ @c -@c COPYRIGHT (c) 1988-1998. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. +@c COPYRIGHT (c) 1988-1998. +@c On-Line Applications Research Corporation (OAR). +@c All rights reserved. @c -@c $Id$ +@c $Id$ @c @chapter Mutex Manager @@ -11,7 +11,7 @@ @section Introduction The mutex manager implements the functionality required of the mutex -manager as defined by POSIX 1003.1b-1996. This standard requires that +manager as defined by POSIX 1003.1b-1996. This standard requires that a compliant operating system provide the facilties to ensure that threads can operate with mutual exclusion from one another and defines the API that must be provided. @@ -41,9 +41,9 @@ The services provided by the mutex manager are: @subsection Mutex Attributes -Mutex attributes are utilized only at mutex creation time. A mutex +Mutex attributes are utilized only at mutex creation time. A mutex attribute structure may be initialized and passed as an argument to -the @code{mutex_init} routine. Note that the priority ceiling of +the @code{mutex_init} routine. Note that the priority ceiling of a mutex may be set at run-time. @table @b @@ -69,7 +69,7 @@ pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER; This indicates that @code{my_mutex} will be automatically initialized by an implicit call to @code{pthread_mutex_init} the first time -the mutex is used. +the mutex is used. Note that the mutex will be initialized with default attributes. @@ -84,16 +84,22 @@ A subsection is dedicated to each of this manager's services and describes the calling sequence, related constants, usage, and status codes. +@c +@c +@c @page @subsection pthread_mutexattr_init - Initialize a Mutex Attribute Set +@findex pthread_mutexattr_init +@cindex initialize a mutex attribute set + @subheading CALLING SEQUENCE: @example #include int pthread_mutexattr_init( - pthread_mutexattr_t *attr +pthread_mutexattr_t *attr ); @end example @@ -115,16 +121,22 @@ individual attributes. XXX insert list of default attributes here. +@c +@c +@c @page @subsection pthread_mutexattr_destroy - Destroy a Mutex Attribute Set +@findex pthread_mutexattr_destroy +@cindex destroy a mutex attribute set + @subheading CALLING SEQUENCE: @example #include int pthread_mutexattr_destroy( - pthread_mutexattr_t *attr +pthread_mutexattr_t *attr ); @end example @@ -142,24 +154,30 @@ The attribute set is not initialized. @subheading DESCRIPTION: The @code{pthread_mutex_attr_destroy} routine is used to destroy a mutex -attributes object. The behavior of using an attributes object after +attributes object. The behavior of using an attributes object after it is destroyed is implementation dependent. @subheading NOTES: NONE +@c +@c +@c @page @subsection pthread_mutexattr_setprotocol - Set the Blocking Protocol +@findex pthread_mutexattr_setprotocol +@cindex set the blocking protocol + @subheading CALLING SEQUENCE: @example #include int pthread_mutexattr_setprotocol( - pthread_mutexattr_t *attr, - int protocol +pthread_mutexattr_t *attr, +int protocol ); @end example @@ -171,16 +189,16 @@ The attribute pointer argument is invalid. @item EINVAL The attribute set is not initialized. - + @item EINVAL The protocol argument is invalid. - + @end table @subheading DESCRIPTION: The @code{pthread_mutexattr_setprotocol} routine is used to set value of the -@code{protocol} attribute. This attribute controls the order in which +@code{protocol} attribute. This attribute controls the order in which threads waiting on this mutex will receive it. The @code{protocol} can be one of the following: @@ -191,11 +209,11 @@ The @code{protocol} can be one of the following: in which case blocking order is FIFO. @item @code{PTHREAD_PRIO_INHERIT} -in which case blocking order is priority with the priority inheritance +in which case blocking order is priority with the priority inheritance protocol in effect. @item @code{PTHREAD_PRIO_PROTECT} -in which case blocking order is priority with the priority ceiling +in which case blocking order is priority with the priority ceiling protocol in effect. @end table @@ -205,116 +223,134 @@ protocol in effect. There is currently no way to get simple priority blocking ordering with POSIX mutexes even though this could easily by supported by RTEMS. +@c +@c +@c @page @subsection pthread_mutexattr_getprotocol - Get the Blocking Protocol - + +@findex pthread_mutexattr_getprotocol +@cindex get the blocking protocol + @subheading CALLING SEQUENCE: - + @example #include - + int pthread_mutexattr_getprotocol( - pthread_mutexattr_t *attr, - int *protocol +pthread_mutexattr_t *attr, +int *protocol ); @end example - + @subheading STATUS CODES: - + @table @b @item EINVAL The attribute pointer argument is invalid. @item EINVAL The attribute set is not initialized. - + @item EINVAL The protocol pointer argument is invalid. - + @end table - + @subheading DESCRIPTION: - + The @code{pthread_mutexattr_getprotocol} routine is used to obtain -the value of the @code{protocol} attribute. This attribute controls +the value of the @code{protocol} attribute. This attribute controls the order in which threads waiting on this mutex will receive it. @subheading NOTES: NONE +@c +@c +@c @page @subsection pthread_mutexattr_setprioceiling - Set the Priority Ceiling +@findex pthread_mutexattr_setprioceiling +@cindex set the priority ceiling + @subheading CALLING SEQUENCE: @example #include int pthread_mutexattr_setprioceiling( - pthread_mutexattr_t *attr, - int prioceiling +pthread_mutexattr_t *attr, +int prioceiling ); @end example @subheading STATUS CODES: - + @table @b @item EINVAL The attribute pointer argument is invalid. @item EINVAL The attribute set is not initialized. - + @item EINVAL The prioceiling argument is invalid. - + @end table @subheading DESCRIPTION: The @code{pthread_mutexattr_setprioceiling} routine is used to set value of the -@code{prioceiling} attribute. This attribute specifies the priority that -is the ceiling for threads obtaining this mutex. Any task obtaining this -mutex may not be of greater priority that the ceiling. If it is of lower -priority, then its priority will be elevated to @code{prioceiling}. +@code{prioceiling} attribute. This attribute specifies the priority that +is the ceiling for threads obtaining this mutex. Any task obtaining this +mutex may not be of greater priority that the ceiling. If it is of lower +priority, then its priority will be elevated to @code{prioceiling}. @subheading NOTES: NONE +@c +@c +@c @page @subsection pthread_mutexattr_getprioceiling - Get the Priority Ceiling +@findex pthread_mutexattr_getprioceiling +@cindex get the priority ceiling + @subheading CALLING SEQUENCE: @example #include int pthread_mutexattr_getprioceiling( - const pthread_mutexattr_t *attr, - int *prioceiling +const pthread_mutexattr_t *attr, +int *prioceiling ); @end example @subheading STATUS CODES: - + @table @b @item EINVAL The attribute pointer argument is invalid. @item EINVAL The attribute set is not initialized. - + @item EINVAL The prioceiling pointer argument is invalid. - + @end table @subheading DESCRIPTION: The @code{pthread_mutexattr_getprioceiling} routine is used to obtain the -value of the @code{prioceiling} attribute. This attribute specifies the +value of the @code{prioceiling} attribute. This attribute specifies the priority ceiling for this mutex. @@ -322,81 +358,99 @@ priority ceiling for this mutex. NONE +@c +@c +@c @page @subsection pthread_mutexattr_setpshared - Set the Visibility +@findex pthread_mutexattr_setpshared +@cindex set the visibility + @subheading CALLING SEQUENCE: @example #include int pthread_mutexattr_setpshared( - pthread_mutexattr_t *attr, - int pshared +pthread_mutexattr_t *attr, +int pshared ); @end example @subheading STATUS CODES: - + @table @b @item EINVAL The attribute pointer argument is invalid. @item EINVAL The attribute set is not initialized. - + @item EINVAL The pshared argument is invalid. - + @end table @subheading DESCRIPTION: @subheading NOTES: +@c +@c +@c @page @subsection pthread_mutexattr_getpshared - Get the Visibility +@findex pthread_mutexattr_getpshared +@cindex get the visibility + @subheading CALLING SEQUENCE: @example #include int pthread_mutexattr_getpshared( - const pthread_mutexattr_t *attr, - int *pshared +const pthread_mutexattr_t *attr, +int *pshared ); @end example @subheading STATUS CODES: - + @table @b @item EINVAL The attribute pointer argument is invalid. @item EINVAL The attribute set is not initialized. - + @item EINVAL The pshared pointer argument is invalid. - + @end table @subheading DESCRIPTION: @subheading NOTES: +@c +@c +@c @page @subsection pthread_mutex_init - Initialize a Mutex +@findex pthread_mutex_init +@cindex initialize a mutex + @subheading CALLING SEQUENCE: @example #include int pthread_mutex_init( - pthread_mutex_t *mutex, - const pthread_mutexattr_t *attr +pthread_mutex_t *mutex, +const pthread_mutexattr_t *attr ); @end example @@ -405,7 +459,7 @@ int pthread_mutex_init( @table @b @item EINVAL The attribute set is not initialized. - + @item EINVAL The specified protocol is invalid. @@ -425,21 +479,27 @@ initialized, but not yet destroyed. @subheading NOTES: +@c +@c +@c @page @subsection pthread_mutex_destroy - Destroy a Mutex +@findex pthread_mutex_destroy +@cindex destroy a mutex + @subheading CALLING SEQUENCE: @example #include int pthread_mutex_destroy( - pthread_mutex_t *mutex +pthread_mutex_t *mutex ); @end example @subheading STATUS CODES: - + @table @b @item EINVAL The specified mutex is invalid. @@ -447,23 +507,29 @@ The specified mutex is invalid. @item EBUSY Attempted to destroy the object reference by mutex, while it is locked or referenced by another thread. - + @end table @subheading DESCRIPTION: @subheading NOTES: +@c +@c +@c @page @subsection pthread_mutex_lock - Lock a Mutex +@findex pthread_mutex_lock +@cindex lock a mutex + @subheading CALLING SEQUENCE: @example #include int pthread_mutex_lock( - pthread_mutex_t *mutex +pthread_mutex_t *mutex ); @end example @@ -474,7 +540,7 @@ int pthread_mutex_lock( The specified mutex is invalid. @item EINVAL -The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the +The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the priority of the calling thread is higher than the current priority ceiling. @@ -487,60 +553,72 @@ The current thread already owns the mutex. @subheading NOTES: +@c +@c +@c @page @subsection pthread_mutex_trylock - Poll to Lock a Mutex - + +@findex pthread_mutex_trylock +@cindex poll to lock a mutex + @subheading CALLING SEQUENCE: - + @example #include - + int pthread_mutex_trylock( - pthread_mutex_t *mutex +pthread_mutex_t *mutex ); @end example - + @subheading STATUS CODES: - + @table @b @item EINVAL The specified mutex is invalid. - + @item EINVAL The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the priority of the calling thread is higher than the current priority ceiling. - + @item EDEADLK The current thread already owns the mutex. - + @end table - + @subheading DESCRIPTION: - + @subheading NOTES: - + +@c +@c +@c @page @subsection pthread_mutex_timedlock - Lock a Mutex with Timeout - + +@findex pthread_mutex_timedlock +@cindex lock a mutex with timeout + @subheading CALLING SEQUENCE: - + @example #include #include - + int pthread_mutex_timedlock( - pthread_mutex_t *mutex, - const struct timespec *timeout +pthread_mutex_t *mutex, +const struct timespec *timeout ); @end example - + @subheading STATUS CODES: - + @table @b @item EINVAL The specified mutex is invalid. - + @item EINVAL The nanoseconds field of timeout is invalid. @@ -548,27 +626,33 @@ The nanoseconds field of timeout is invalid. The mutex has the protocol attribute of PTHREAD_PRIO_PROTECT and the priority of the calling thread is higher than the current priority ceiling. - + @item EDEADLK The current thread already owns the mutex. @end table - + @subheading DESCRIPTION: - + @subheading NOTES: - + +@c +@c +@c @page @subsection pthread_mutex_unlock - Unlock a Mutex +@findex pthread_mutex_unlock +@cindex unlock a mutex + @subheading CALLING SEQUENCE: @example #include int pthread_mutex_unlock( - pthread_mutex_t *mutex +pthread_mutex_t *mutex ); @end example @@ -577,30 +661,36 @@ int pthread_mutex_unlock( @table @b @item EINVAL The specified mutex is invalid. - + @end table @subheading DESCRIPTION: @subheading NOTES: +@c +@c +@c @page @subsection pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling +@findex pthread_mutex_setprioceiling +@cindex dynamically set the priority ceiling + @subheading CALLING SEQUENCE: @example #include int pthread_mutex_setprioceiling( - pthread_mutex_t *mutex, - int prioceiling, - int *oldceiling +pthread_mutex_t *mutex, +int prioceiling, +int *oldceiling ); @end example @subheading STATUS CODES: - + @table @b @item EINVAL The oldceiling pointer parameter is invalid. @@ -610,36 +700,42 @@ The prioceiling parameter is an invalid priority. @item EINVAL The specified mutex is invalid. - + @end table @subheading DESCRIPTION: @subheading NOTES: +@c +@c +@c @page @subsection pthread_mutex_getprioceiling - Get the Current Priority Ceiling +@findex pthread_mutex_getprioceiling +@cindex get the current priority ceiling + @subheading CALLING SEQUENCE: @example #include int pthread_mutex_getprioceiling( - pthread_mutex_t *mutex, - int *prioceiling +pthread_mutex_t *mutex, +int *prioceiling ); @end example @subheading STATUS CODES: - + @table @b @item EINVAL The prioceiling pointer parameter is invalid. @item EINVAL The specified mutex is invalid. - + @end table @subheading DESCRIPTION: -- cgit v1.2.3