Now build.

1 files changed, 293 insertions, 44 deletions

diff --git a/doc/posix_users/semaphores.t b/doc/posix_users/semaphores.t
index e3fa6b2cd1..92d5b6ccc3 100644
--- a/doc/posix_users/semaphores.t
+++ b/doc/posix_users/semaphores.t
@@ -1,38 +1,71 @@
 @c
-@c  COPYRIGHT (c) 1988-1998.
-@c  On-Line Applications Research Corporation (OAR).
+@c  COPYRIGHT(c) 1988-1998.
+@c  On-Line Applications Research Corporation(OAR).
 @c  All rights reserved. 
 @c
 @c  $Id$
 @c
 
-@chapter Semaphores Manager
+@chapter Semaphore Manager
 
 @section Introduction
 
-The 
-semaphore manager is ...
+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:
 
 @itemize @bullet
-@item @code{sem_init} - 
-@item @code{sem_destroy} - 
-@item @code{sem_open} - 
-@item @code{sem_close} - 
-@item @code{sem_unlink} - 
-@item @code{sem_wait} - 
-@item @code{sem_trywait} - 
-@item @code{sem_post} - 
-@item @code{sem_getvalue} - 
+@item @code{sem_init} - Initialize an unnamed semaphore
+@item @code{sem_destroy} - Destroy an unnamed semaphore
+@item @code{sem_open} - Open a named semaphore
+@item @code{sem_close} - Close a named semaphore
+@item @code{sem_unlink} - Remove a named semaphore
+@item @code{sem_wait} - Lock a semaphore
+@item @code{sem_trywait} - Lock a semaphore
+@item @code{sem_post} - Unlock a semaphore
+@item @code{sem_getvalue} - Get the value of a semeaphore
 @end itemize
 
 @section Background
 
-There is currently no text in this section.
+@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. 
+
+@subsection "sem_t" Structure
+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
+   */
+
+  typedef int sem_t
+@end example
+ 
+@subsection Building a Semaphore Attribute Set
 
 @section Operations
 
+@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. 
+
 There is currently no text in this section.
 
 @section Directives
@@ -43,13 +76,16 @@ and describes the calling sequence, related constants, usage,
 and status codes.
 
 @page
-@subsection sem_init - 
+@subsection sem_init - Initialize an unnamed semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_init(
+  sem_t *sem,
+  int pshared,
+  unsigned int value
 );
 @end example
 @end ifset
@@ -60,23 +96,44 @@ int sem_init(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EINVAL
+The value argument exceeds SEM_VALUE_MAX
+
+@item ENOSPC
+A resource required to initialize the semaphore has been exhausted
+The limit on semaphores (SEM_VALUE_MAX) has been reached
+
+@item ENOSYS
+The function sem_init is not supported by this implementation
+
+@item EPERM
+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 
+semaphore remains valid until it is destroyed.
+
+ADD MORE HERE XXX
 
 @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
+that occurred.
+
+Multiprocessing is currently not supported in this implementation.
 
 @page
-@subsection sem_destroy - 
+@subsection sem_destroy - Destroy an unnamed semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_destroy(
+  sem_t *sem
 );
 @end example
 @end ifset
@@ -87,23 +144,40 @@ int sem_destroy(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EINVAL
+The value argument exceeds SEM_VALUE_MAX
+
+@item ENOSYS
+The function sem_init is not supported by this implementation
+
+@item EBUSY
+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 
+sem_init.
 
 @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
+that occurred.
+
+Multiprocessing is currently not supported in this implementation.
+
 
 @page
-@subsection sem_open - 
+@subsection sem_open - Open a named semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
-int sem_open(
+int sem_open)
+  const char *name,
+  int oflag
 );
 @end example
 @end ifset
@@ -111,26 +185,71 @@ int sem_open(
 @ifset is-Ada
 @end ifset
 
+@subheading ARGUMENTS:
+
+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_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 E
-The
+@item EACCES
+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.
+
+@item EINVAL
+The sem_open() operation is not supported for the given name.
+
+@item EMFILE
+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.
+
+@item ENOENT
+O_CREAT is not set and the named semaphore does not exist.
+
+@item ENOSPC
+There is insufficient space for the creation of a new named semaphore.
+
+@item ENOSYS
+The function sem_open() is not supported by this implementation.
 
 @end table
 
 @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 
+determining if the semaphore is created or accessed by a call to sem_open().
 
 @subheading NOTES:
 
+
 @page
-@subsection sem_close - 
+@subsection sem_close - Close a named semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_close(
+  sem_t *sem_close
 );
 @end example
 @end ifset
@@ -141,23 +260,32 @@ int sem_close(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EACCES
+The semaphore argument is  not a valid semaphore descriptor.
+
+@item ENOSYS
+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 
+return and errno is set.
 
 @subheading NOTES:
 
 @page
-@subsection sem_unlink - 
+@subsection sem_unlink - Unlink a semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_unlink(
+  const char *name
 );
 @end example
 @end ifset
@@ -168,23 +296,45 @@ int sem_unlink(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EACCESS
+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.
+
+@item ENOENT
+The name of the semaphore does not exist.
+
+@item ENOSPC
+There is insufficient space for the creation of a new named semaphore.
+
+@item ENOSYS
+The function sem_unlink is not supported by this implementation.
 
 @end table
 
 @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
+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.  
+
+If the termination is successful, the function shall return 0.  Otherwise, a -1
+is returned and the errno is set.
 
 @subheading NOTES:
 
 @page
-@subsection sem_wait - 
+@subsection sem_wait - Wait on a Semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_wait(
+  sem_t *sem
 );
 @end example
 @end ifset
@@ -195,23 +345,77 @@ int sem_wait(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EINVAL
+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
+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 zero), then the function will block until the semaphore becomes
+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
+appropriate error code.
 
 @subheading NOTES:
+Multiprocessing is not supported in this implementation.
 
 @page
-@subsection sem_trywait - 
+@subsection sem_trywait - Non-blocking Wait on a Semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_trywait(
+  sem_t *sem
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+@table @b
+@item EAGAIN
+The semaphore is not available (i.e., the semaphore value is zero), so the
+semaphore could not be locked.
+
+@item EINVAL
+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
+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
+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.
+
+If the call is unsuccessful, then the function returns -1 and sets
+@code{errno} to the appropriate error code.
+
+@subheading NOTES:
+Multiprocessing is not supported in this implementation.
+
+@page
+@subsection sem_timedwait - 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
 );
 @end example
 @end ifset
@@ -222,23 +426,41 @@ int sem_trywait(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EAGAIN
+The semaphore is not available (i.e., the semaphore value is zero), so the
+semaphore could not be locked.
+
+@item EINVAL
+The @code{sem} argument does not refewr to a valid semaphore
 
 @end table
 
 @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
+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
+is unavailable, then the function will wait for the semaphore to become
+available for the amount of time specified by @code{timeout}.
+
+If the semaphore does not become available within the interval specified by
+@code{timeout}, then the function returns -1 and sets @code{errno} to EAGAIN.
+If any other error occurs, the function returns -1 and sets @code{errno} to
+the appropriate error code.
 
 @subheading NOTES:
+Multiprocessing is not supported in this implementation.
 
 @page
-@subsection sem_post - 
+@subsection sem_post - Unlock a Semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_post(
+  sem_t *sem
 );
 @end example
 @end ifset
@@ -249,23 +471,36 @@ int sem_post(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EINVAL
+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
+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()}
+returns 0 upon successful completion.
+
+If an error occurs, the function returns -1 and sets @code{errno} to the
+appropriate error code.
 
 @subheading NOTES:
+Multiprocessing is not supported in this implementation.
 
 @page
-@subsection sem_getvalue - 
+@subsection sem_getvalue - Get the value of a semaphore
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int sem_getvalue(
+  sem_t *sem,
+  int *sval
 );
 @end example
 @end ifset
@@ -276,12 +511,26 @@ int sem_getvalue(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EINVAL
+The "sem" argument does not refer to a valid semaphore
+
+@item ENOSYS
+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 
+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 
+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 
+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 
+that occurred.