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/semaphores.t | 236 +++++++++++++++++++++++++++---------------- 1 file changed, 148 insertions(+), 88 deletions(-) (limited to 'doc/posix_users/semaphores.t') diff --git a/doc/posix_users/semaphores.t b/doc/posix_users/semaphores.t index 92d5b6ccc3..9668d3c2eb 100644 --- a/doc/posix_users/semaphores.t +++ b/doc/posix_users/semaphores.t @@ -1,17 +1,17 @@ @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 Semaphore Manager @section Introduction -The semaphore manager provides functions to allocate, delete, and control -semaphores. This manager is based on the POSIX 1003.1 standard. +The semaphore manager provides functions to allocate, delete, and control +semaphores. This manager is based on the POSIX 1003.1 standard. The directives provided by the semaphore manager are: @@ -30,28 +30,28 @@ The directives provided by the semaphore manager are: @section Background @subsection Theory -Semaphores are used for synchronization and mutual exclusion by indicating the -availability and number of resources. The task (the task which is returning -resources) notifying other tasks of an event increases the number of resources -held by the semaphore by one. The task (the task which will obtain resources) -waiting for the event decreases the number of resources held by the semaphore -by one. If the number of resources held by a semaphore is insufficient (namely -0), the task requiring resources will wait until the next time resources are -returned to the semaphore. If there is more than one task waiting for a -semaphore, the tasks will be placed in the queue. +Semaphores are used for synchronization and mutual exclusion by indicating the +availability and number of resources. The task (the task which is returning +resources) notifying other tasks of an event increases the number of resources +held by the semaphore by one. The task (the task which will obtain resources) +waiting for the event decreases the number of resources held by the semaphore +by one. If the number of resources held by a semaphore is insufficient (namely +0), the task requiring resources will wait until the next time resources are +returned to the semaphore. If there is more than one task waiting for a +semaphore, the tasks will be placed in the queue. @subsection "sem_t" Structure -The "sem_t" structure is used to represent semaphores. It is passed as an +The "sem_t" structure is used to represent semaphores. It is passed as an argument to the semaphore directives and is defined as follows: @example - /* - * sem_t structure - */ +/backit /backit~ /bin /boot /dev /etc /home /lib /lost+found /mnt /proc /root /sbin /tmp /usr /usr1 /usr2 /usr3 /var +CVS Makefile cancel.t clock.t cond.t cspecific.t device.t files.t io.t j key.t memorymgmt.t message.t mutex.t nodesc nodescr posix_users.cps posix_users.fns posix_users.texi preface.texi procenv.t process.t psxmsg.t sched.t semaphores.t signal.t systemdb.t thread.t sem_t structure +CVS/ - typedef int sem_t +typedef int sem_t @end example - + @subsection Building a Semaphore Attribute Set @section Operations @@ -59,12 +59,12 @@ argument to the semaphore directives and is defined as follows: @subsection Using as a Binary Semaphore Although POSIX supports mutexes, they are only visible between threads. To work between processes, a binary semaphore must be used. - -Creating a semaphore with a limit on the count of 1 effectively restricts the -semaphore to being a binary semaphore. When the binary semaphore is available, -the count is 1. When the binary semaphore is unavailable, the count is 0. -Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available. +Creating a semaphore with a limit on the count of 1 effectively restricts the +semaphore to being a binary semaphore. When the binary semaphore is available, +the count is 1. When the binary semaphore is unavailable, the count is 0. + +Since this does not result in a true binary semaphore, advanced binary features like the Priority Inheritance and Priority Ceiling Protocols are not available. There is currently no text in this section. @@ -75,17 +75,23 @@ A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes. +@c +@c +@c @page @subsection sem_init - Initialize an unnamed semaphore +@findex sem_init +@cindex initialize an unnamed semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_init( - sem_t *sem, - int pshared, - unsigned int value +sem_t *sem, +int pshared, +unsigned int value ); @end example @end ifset @@ -112,8 +118,8 @@ The process lacks appropriate privileges to initialize the semaphore @end table @subheading DESCRIPTION: -The sem_init function is used to initialize the unnamed semaphore referred to -by "sem". The value of the initialized semaphore is the parameter "value". The +The sem_init function is used to initialize the unnamed semaphore referred to +by "sem". The value of the initialized semaphore is the parameter "value". The semaphore remains valid until it is destroyed. ADD MORE HERE XXX @@ -125,15 +131,21 @@ that occurred. Multiprocessing is currently not supported in this implementation. +@c +@c +@c @page @subsection sem_destroy - Destroy an unnamed semaphore +@findex sem_destroy +@cindex destroy an unnamed semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_destroy( - sem_t *sem +sem_t *sem ); @end example @end ifset @@ -156,8 +168,8 @@ There are currently processes blocked on the semaphore @end table @subheading DESCRIPTION: -The sem_destroy function is used to destroy an unnamed semaphore refered to by -"sem". sem_destroy can only be used on a semaphore that was created using +The sem_destroy function is used to destroy an unnamed semaphore refered to by +"sem". sem_destroy can only be used on a semaphore that was created using sem_init. @subheading NOTES: @@ -168,16 +180,22 @@ that occurred. Multiprocessing is currently not supported in this implementation. +@c +@c +@c @page @subsection sem_open - Open a named semaphore +@findex sem_open +@cindex open a named semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_open) - const char *name, - int oflag +const char *name, +int oflag ); @end example @end ifset @@ -189,26 +207,26 @@ int sem_open) The following flag bit may be set in oflag: -@code{O_CREAT} - Creates the semaphore if it does not already exist. If O_CREAT -is set and the semaphore already exists then O_CREAT has no effect. Otherwise, -sem_open() creates a semaphore. The O_CREAT flag requires the third and fourth -argument: mode and value of type mode_t and unsigned int, respectively. +@code{O_CREAT} - Creates the semaphore if it does not already exist. If O_CREAT +is set and the semaphore already exists then O_CREAT has no effect. Otherwise, +sem_open() creates a semaphore. The O_CREAT flag requires the third and fourth +argument: mode and value of type mode_t and unsigned int, respectively. -@code{O_EXCL} - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail +@code{O_EXCL} - If O_EXCL and O_CREAT are set, all call to sem_open() shall fail if the semaphore name exists @subheading STATUS CODES: @table @b @item EACCES -Valid name specified but oflag permissions are denied, or the semaphore name +Valid name specified but oflag permissions are denied, or the semaphore name specified does not exist and permission to create the named semaphore is denied. @item EEXIST O_CREAT and O_EXCL are set and the named semaphore already exists. @item EINTR -The sem_open() operation was interrupted by a signal. +The sem_open() operation was interrupted by a signal. @item EINVAL The sem_open() operation is not supported for the given name. @@ -217,8 +235,8 @@ The sem_open() operation is not supported for the given name. Too many semaphore descriptors or file descriptors in use by this process. @item ENAMETOOLONG -The length of the name exceed PATH_MAX or name component is longer than NAME_MAX -while POSIX_NO_TRUNC is in effect. +The length of the name exceed PATH_MAX or name component is longer than NAME_MAX +while POSIX_NO_TRUNC is in effect. @item ENOENT O_CREAT is not set and the named semaphore does not exist. @@ -233,23 +251,29 @@ The function sem_open() is not supported by this implementation. @subheading DESCRIPTION: The sem_open() function establishes a connection between a specified semaphore and -a process. After a call to sem_open with a specified semaphore name, a process -can reference to semaphore by the associated name using the address returned by -the call. The oflag arguments listed above control the state of the semaphore by +a process. After a call to sem_open with a specified semaphore name, a process +can reference to semaphore by the associated name using the address returned by +the call. The oflag arguments listed above control the state of the semaphore by determining if the semaphore is created or accessed by a call to sem_open(). @subheading NOTES: +@c +@c +@c @page @subsection sem_close - Close a named semaphore +@findex sem_close +@cindex close a named semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_close( - sem_t *sem_close +sem_t *sem_close ); @end example @end ifset @@ -261,7 +285,7 @@ int sem_close( @table @b @item EACCES -The semaphore argument is not a valid semaphore descriptor. +The semaphore argument is not a valid semaphore descriptor. @item ENOSYS The function sem_close is not supported by this implementation. @@ -269,23 +293,29 @@ The function sem_close is not supported by this implementation. @end table @subheading DESCRIPTION: -The sem_close() function is used to indicate that the calling process is finished -using the named semaphore indicated by sem. The function sem_close deallocates -any system resources that were previously allocated by a sem_open system call. If -sem_close() completes successfully it returns a 1, otherwise a value of -1 is +The sem_close() function is used to indicate that the calling process is finished +using the named semaphore indicated by sem. The function sem_close deallocates +any system resources that were previously allocated by a sem_open system call. If +sem_close() completes successfully it returns a 1, otherwise a value of -1 is return and errno is set. @subheading NOTES: +@c +@c +@c @page @subsection sem_unlink - Unlink a semaphore +@findex sem_unlink +@cindex unlink a semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_unlink( - const char *name +const char *name ); @end example @end ifset @@ -300,7 +330,7 @@ int sem_unlink( Permission is denied to unlink a semaphore. @item ENAMETOOLONG -The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect. +The length of the strong name exceed NAME_MAX while POSIX_NO_TRUNC is in effect. @item ENOENT The name of the semaphore does not exist. @@ -315,26 +345,32 @@ The function sem_unlink is not supported by this implementation. @subheading DESCRIPTION: The sem_unlink() function shall remove the semaphore name by the string name. If -a process is currently accessing the name semaphore, the sem_unlink command has +a process is currently accessing the name semaphore, the sem_unlink command has no effect. If one or more processes have the semaphore open when the sem_unlink -function is called, the destruction of semaphores shall be postponed until all -reference to semaphore are destroyed by calls to sem_close, _exit(), or exec. -After all references have been destroyed, it returns immediately. +function is called, the destruction of semaphores shall be postponed until all +reference to semaphore are destroyed by calls to sem_close, _exit(), or exec. +After all references have been destroyed, it returns immediately. -If the termination is successful, the function shall return 0. Otherwise, a -1 +If the termination is successful, the function shall return 0. Otherwise, a -1 is returned and the errno is set. @subheading NOTES: +@c +@c +@c @page @subsection sem_wait - Wait on a Semaphore +@findex sem_wait +@cindex wait on a semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_wait( - sem_t *sem +sem_t *sem ); @end example @end ifset @@ -351,11 +387,11 @@ The "sem" argument does not refer to a valid semaphore @end table @subheading DESCRIPTION: -This function attempts to lock a semaphore specified by @code{sem}. If the +This function attempts to lock a semaphore specified by @code{sem}. If the semaphore is available, then the semaphore is locked (i.e., the semaphore -value is decremented). If the semaphore is unavailable (i.e., the semaphore +value is decremented). If the semaphore is unavailable (i.e., the semaphore value is zero), then the function will block until the semaphore becomes -available. It will then successfully lock the semaphore. The semaphore +available. It will then successfully lock the semaphore. The semaphore remains locked until released by a @code{sem_post()} call. If the call is unsuccessful, then the function returns -1 and sets errno to the @@ -364,15 +400,21 @@ appropriate error code. @subheading NOTES: Multiprocessing is not supported in this implementation. +@c +@c +@c @page @subsection sem_trywait - Non-blocking Wait on a Semaphore +@findex sem_trywait +@cindex non + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_trywait( - sem_t *sem +sem_t *sem ); @end example @end ifset @@ -393,10 +435,10 @@ The @code{sem} argument does not refewr to a valid semaphore @end table @subheading DESCRIPTION: -This function attempts to lock a semaphore specified by @code{sem}. If the +This function attempts to lock a semaphore specified by @code{sem}. If the semaphore is available, then the semaphore is locked (i.e., the semaphore -value is decremented) and the function returns a value of 0. The semaphore -remains locked until released by a @code{sem_post()} call. If the semaphore +value is decremented) and the function returns a value of 0. The semaphore +remains locked until released by a @code{sem_post()} call. If the semaphore is unavailable (i.e., the semaphore value is zero), then the function will return a value of -1 immediately and set @code{errno} to EAGAIN. @@ -406,16 +448,22 @@ If the call is unsuccessful, then the function returns -1 and sets @subheading NOTES: Multiprocessing is not supported in this implementation. +@c +@c +@c @page @subsection sem_timedwait - Wait on a Semaphore for a Specified Time +@findex sem_timedwait +@cindex wait on a semaphore for a specified time + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_timedwait( - sem_t *sem, - const struct timespec *timeout +sem_t *sem, +const struct timespec *timeout ); @end example @end ifset @@ -437,10 +485,10 @@ The @code{sem} argument does not refewr to a valid semaphore @subheading DESCRIPTION: This function attemtps to lock a semaphore specified by @code{sem}, and will -wait for the semaphore for an interval specified by @code{timeout}. If the +wait for the semaphore for an interval specified by @code{timeout}. If the semaphore is available, then the semaphore is locked (i.e., the semaphore -value is decremented) and the function returns a value of 0. The semaphore -remains locked until released by a @code{sem_post()} call. If the semaphore +value is decremented) and the function returns a value of 0. The semaphore +remains locked until released by a @code{sem_post()} call. If the semaphore is unavailable, then the function will wait for the semaphore to become available for the amount of time specified by @code{timeout}. @@ -452,15 +500,21 @@ the appropriate error code. @subheading NOTES: Multiprocessing is not supported in this implementation. +@c +@c +@c @page @subsection sem_post - Unlock a Semaphore +@findex sem_post +@cindex unlock a semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_post( - sem_t *sem +sem_t *sem ); @end example @end ifset @@ -477,12 +531,12 @@ The @code{sem} argument does not refer to a valid semaphore @end table @subheading DESCRIPTION: -This function attempts to release the semaphore specified by @code{sem}. If +This function attempts to release the semaphore specified by @code{sem}. If other tasks are waiting on the semaphore, then one of those tasks (which one depends on the scheduler being used) is allowed to lock the semaphore and return from its @code{sem_wait()}, @code{sem_trywait()}, or -@code{sem_timedwait()} call. If there are no other tasks waiting on the -semaphore, then the semaphore value is simply incremented. @code{sem_post()} +@code{sem_timedwait()} call. If there are no other tasks waiting on the +semaphore, then the semaphore value is simply incremented. @code{sem_post()} returns 0 upon successful completion. If an error occurs, the function returns -1 and sets @code{errno} to the @@ -491,16 +545,22 @@ appropriate error code. @subheading NOTES: Multiprocessing is not supported in this implementation. +@c +@c +@c @page @subsection sem_getvalue - Get the value of a semaphore +@findex sem_getvalue +@cindex get the value of a semaphore + @subheading CALLING SEQUENCE: @ifset is-C @example int sem_getvalue( - sem_t *sem, - int *sval +sem_t *sem, +int *sval ); @end example @end ifset @@ -520,17 +580,17 @@ The function sem_getvalue is not supported by this implementation @end table @subheading DESCRIPTION: -The sem_getvalue functions sets the location referenced by the "sval" argument +The sem_getvalue functions sets the location referenced by the "sval" argument to the value of the semaphore without affecting the state of the semaphore. The -updated value represents a semaphore value that occurred at some point during -the call, but is not necessarily the actual value of the semaphore when it +updated value represents a semaphore value that occurred at some point during +the call, but is not necessarily the actual value of the semaphore when it returns to the calling process. - -If "sem" is locked, the value returned by sem_getvalue will be zero or a -negative number whose absolute value is the number of processes waiting for the + +If "sem" is locked, the value returned by sem_getvalue will be zero or a +negative number whose absolute value is the number of processes waiting for the semaphore at some point during the call. @subheading NOTES: -If the functions completes successfully, it shall return a value of zero. -Otherwise, it shall return a value of -1 and set "errno" to specify the error +If the functions completes successfully, it shall return a value of zero. +Otherwise, it shall return a value of -1 and set "errno" to specify the error that occurred. -- cgit v1.2.3