Now build.

3 files changed, 489 insertions, 175 deletions

diff --git a/doc/posix_users/message.t b/doc/posix_users/message.t
index d4b85ab788..aa458f0c43 100644
--- a/doc/posix_users/message.t
+++ b/doc/posix_users/message.t
@@ -1,6 +1,6 @@
 @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$
@@ -10,250 +10,315 @@
 
 @section Introduction
 
-The 
-message passing manager is ...
+The message passing manager is the means to provide communication and synchronization capabilities using POSIX message queues. 
 
-The directives provided by the message passing manager are:
+The directives provided by the message passing manager are: 
 
 @itemize @bullet
-@item @code{mq_open} - 
-@item @code{mq_close} - 
-@item @code{mq_unlink} - 
-@item @code{mq_send} - 
-@item @code{mq_receive} - 
-@item @code{mq_notify} - 
-@item @code{mq_setattr} - 
-@item @code{mq_getattr} - 
+@item @code{mq_open} - to begin using a message queue
+@item @code{mq_close} - to close the queue after a message has been sent.
+@item @code{mq_unlink} - to remove a message queue from the system entirely 
+@item @code{mq_send} - to send messages to a queue you have accessed
+@item @code{mq_receive} - to receive messages from a queue you have accessed
+@item @code{mq_notify} - to notify that a message is on the queue
+@item @code{mq_setattr} - to change the blocking/non-blocking behavior of the message queue
+@item @code{mq_getattr} - to retrieve the message queue attributes for the named queue
 @end itemize
 
 @section Background
 
-There is currently no text in this section.
+@subsection Theory
+
+Message queues are named objects that operate with readers and writers.  In addition, a message queue is a priority queue of discrete messages.  POSIX message queues offer a certain, basic amount of application access to, and control over, the message queue geometry that can be changed.
+
+@subsection Messages
+
+A message is a variable length buffer where information can be stored to support communication.  The length of the message and the information stored in that message are user-defined and can be actual data, pointer(s), or empty.  There is a maximum acceptable length for a message that is associated with each message queue.
+
+@subsection Message Queues
+
+Message queues are named objects similar to the pipes of POSIX.  They are a means of communicating data between multiple processes and for passing messages among tasks and ISRs.  Message queues can contain a variable number of messages from 0 to an upper limit that is user defined.  The maximum length of the message can be set on a per message queue basis.  Normally messages are sent and received from the message queue in FIFO order.  However, messages can also be prioritized and a priority queue established for the passing of messages.  Synchronization is needed when a task waits for a message to arrive at a queue.  Also, a task may poll a queue for the arrival of a message.
+The message queue descriptor mqd_t mq represents the message queue.  It is passed as an argument to all of the message queue functions.
+
+@subsection Building a Message Queue Attribute Set
+
+ The mq_attr structure is used to define the characteristics of the message queue.
+
+@example
+@group
+/*
+ *  Create Message Queue (mq) Structure
+ */
+
+typedef struct mq_attr@{
+	long mq_flags;			/* Message queue flags */
+	long mq_maxmsg;			/* Maximum number of messages for the queue */
+	long mq_msgsize;		/* Maximum message size */
+	long mq_curmsgs;		/* Number of messages currently queued */
+@};
+@end group
+@end example
+
+All of these attributes are set when the message queue is created using mq_open.  The mq_flags field is not used in the creation of a message queue, it is only used by mq_setattr and mq_getattr.  The structure mq_attr is passed as an argument to mq_setattr and mq_getattr.
+The mq_flags contain information affecting the behavior of the message queue.  The O_NONBLOCK mq_flag is the only flag that is defined.  In mq_setattr, the mq_flag can be set to dynamically change the blocking and non-blocking behavior of the message queue.  If the non-block flag is set then the message queue is non-blocking, and requests to send and receive messages do not block waiting for resources.  For a blocking message queue, a request to send might have to wait for an empty message queue, and a request to receive might have to wait for a message to arrive on the queue. Both mq_maxmsg and mq_msgsize affect the sizing of the message queue.  mq_maxmsg specifies how many messages the queue can hold at any one time.  mq_msgsize specifies the size of any one message on the queue.  If either of these limits is exceeded, an error message results.
+Upon return from mq_getattr, the mq_curmsgs is set according to the current state of the message queue.  This specifies the number of messages currently on the queue.
+
+@subsection Notification of a Message on the Queue
+
+Every message queue has the ability to notify one (and only one) process whenever the queue's state changes from empty (0 messages) to nonempty.  This means that the process does not have to block or constantly poll while it waits for a message.  By calling mq_notify, you can attach a notification request to a message queue.  When a message is received by an empty queue, if there are no processes blocked and waiting for the message, then the queue notifies the requesting process of a message arrival.  There is only one signal sent by the message queue, after that the notification request is de-registered and another process can attach its notification request.  After receipt of a notification, a process must re-register if it wishes to be notified again.
+If there is a process blocked and waiting for the message, that process gets the message, and notification is not sent.  It is also possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request.
+Only one process can have a notification request attached to a message queue at any one time.  If another process attempts to register a notification request, it fails.  You can de-register for a message queue by passing a NULL to mq_notify, this removes any notification request attached to the queue.  Whenever the message queue is closed, all notification attachments are removed.
 
 @section Operations
 
-There is currently no text in this section.
+@subsection Opening or Creating a Message Queue
+
+If the message queue already exists, mq_open() opens it, if the message queue does not exist, mq_open() creates it.  When a message queue is created, the geometry of the message queue is contained in the attribute structure that is passed in as an argument.  This includes mq_msgsize that dictates the maximum size of a single message, and the mq_maxmsg that dictates the maximum number of messages the queue can hold at one time.  The blocking or non-blocking behavior of the queue can also specified.
+
+@subsection Closing a Message Queue
+
+The mq_close() function is used to close the connection made to a message queue that was made during mq_open.  The message queue itself and the messages on the queue are persistent and remain after the queue is closed.
+
+@subsection Removing a Message Queue
+
+The mq_unlink() function removes the named message queue.  If the message queue is not open when mq_unlink is called, then the queue is immediately eliminated.  Any messages that were on the queue are lost, and the queue can not be opened again.  If processes have the queue open when mq_unlink is called, the removal of the queue is delayed until the last process using the queue has finished.  However, the name of the message queue is removed so that no other process can open it.
+
+@subsection Sending a Message to a Message Queue
+
+The mq_send() function adds the message in priority order to the message queue.  Each message has an assigned a priority.  The highest priority message is be at the front of the queue.
+The maximum number of messages that a message queue may accept is specified at creation by the mq_maxmsg field of the attribute structure.  If this amount is exceeded, the behavior of the process is determined according to what oflag was used when the message queue was opened.  If the queue was opened with O_NONBLOCK flag set, the process does not block, and an error is returned.  If the O_NONBLOCK flag was not set, the process does block and wait for space on the queue.
+
+@subsection Receiving a Message from a Message Queue
+
+The mq_receive() function is used to receive the oldest of the highest priority message(s) from the message queue specified by mqdes.  The messages are received in FIFO order within the priorities.  The received message's priority is stored in the location referenced by the msg_prio.  If the msg_prio is a NULL, the priority is discarded.  The message is removed and stored in an area pointed to by msg_ptr whose length is of msg_len.  The msg_len must be at least equal to the mq_msgsize attribute of the message queue.
+The blocking behavior of the message queue is set by O_NONBLOCK at mq_open or by setting O_NONBLOCK in mq_flags in a call to mq_setattr.  If this is a blocking queue, the process does block and wait on an empty queue.  If this a non-blocking queue, the process does not block.
+Upon successful completion, mq_receive returns the length of the selected message in bytes and the message is removed from the queue.
+
+@subsection Notification of Receipt of a Message on an Empty Queue
+
+The mq_notify() function registers the calling process to be notified of message arrival at an empty message queue.  Every message queue has the ability to notify one (and only one) process whenever the queue's state changes from empty (0 messages) to nonempty.  This means that the process does not have to block or constantly poll while it waits for a message.  By calling mq_notify, a notification request is attached to a message queue.  When a message is received by an empty queue, if there are no processes blocked and waiting for the message, then the queue notifies the requesting process of a message arrival.  There is only one signal sent by the message queue, after that the notification request is de-registered and another process can attach its notification request.  After receipt of a notification, a process must re-register if it wishes to be notified again.
+If there is a process blocked and waiting for the message, that process gets the message, and notification is not sent.  Only one process can have a notification request attached to a message queue at any one time.  If another process attempts to register a notification request, it fails.  You can de-register for a message queue by passing a NULL to mq_notify, this removes any notification request attached to the queue.  Whenever the message queue is closed, all notification attachments are removed.
+
+@subsection Setting the Attributes of a Message Queue
+
+The mq_setattr() function is used to set attributes associated with the open message queue description referenced by the message queue descriptor specified by mqdes.  The *omqstat represents the old or previous attributes.  If omqstat is non-NULL, the function mq_setattr() stores, in the location referenced by omqstat, the previous message queue attributes and the current queue status.  These values are the same as would be returned by a call to mq_getattr() at that point.
+There is only one mq_attr.mq_flag that can be altered by this call.  This is the flag that deals with the blocking and non-blocking behavior of the message queue.  If the flag is set then the message queue is non-blocking, and requests to send or receive do not block while waiting for resources.  If the flag is not set, then message send and receive may involve waiting for an empty queue or waiting for a message to arrive.
+
+@subsection Getting the Attributes of a Message Queue
+
+The mq_getattr() function is used to get status information and attributes of the message queue associated with the message queue descriptor.  The results are returned in the mq_attr structure referenced by the mqstat argument.  All of these attributes are set at create time, except the blocking/non-blocking behavior of the message queue which can be dynamically set by using mq_setattr.  The attribute mq_curmsg is set to reflect the number of messages on the queue at the time that mq_getattr was called.
 
 @section Directives
 
-This section details the message passing manager's directives.
-A subsection is dedicated to each of this manager's directives
-and describes the calling sequence, related constants, usage,
-and status codes.
+This section details the message passing manager's directives. A subsection is dedicated to each of this manager's directives and describes the calling sequence, related constants, usage, and status codes. 
 
-@page
-@subsection mq_open - 
+@subsection mq_open -to create or open a message queue
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_open(
-);
+#include <mqueue.h>
+mqd_t mq_open(const char *name, int oflag, mode_t mode, struct mq_attr *attr);    
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
+@code{EACCES} - Either the message queue exists and the permissions requested in oflags were denied, or the message does not exist and permission to create one is denied.
+
+@code{EEXIST} - You tried to create a message queue that already exists.
+
+@code{EINVAL} - An inappropriate name was given for the message queue, or the values of mq-maxmsg or mq_msgsize were less than 0.
+
+@code{ENOENT} - The message queue does not exist, and you did not specify to create it.
+
+@code{EINTR} - The call to mq_open was interrupted by a signal.
+
+@code{EMFILE} - The process has too many files or message queues open.  This is a process limit error.
 
-@end table
+@code{ENFILE} - The system has run out of resources to support more open message queues.  This is a system error.
+
+@code{ENAMETOOLONG} - mq_name is too long.
 
 @subheading DESCRIPTION:
 
+The mq_open () function establishes the connection between a process and a message queue with a message queue descriptor.  If the message queue already exists, mq_open opens it, if the message queue does not exist, mq_open creates it.  Message queues can have multiple senders and receivers.  If mq_open is successful, the function returns a message queue descriptor.  Otherwise, the function returns a -1 and sets 'errno' to indicate the error.
+
+The name of the message queue is used as an argument.  For the best of portability, the name of the message queue should begin with a "/" and no other "/" should be in the name.  Different systems interpret the name in different ways.
+
+The oflags contain information on how the message is opened if the queue already exists.  This may be O_RDONLY for read only, O_WRONLY for write only, of O_RDWR, for read and write.
+
+In addition, the oflags contain information needed in the creation of a message queue.
+@code{O_NONBLOCK} - If the non-block flag is set then the message queue is non-blocking, and requests to send and receive messages do not block waiting for resources.  If the flag is not set then the message queue is blocking, and a request to send might have to wait for an empty message queue.  Similarly, a request to receive might have to wait for a message to arrive on the queue.
+@code{O_CREAT} - This call specifies that the call the mq_open is to create a new message queue.  In this case the mode and attribute arguments of the function call are utilized.  The message queue is created with a mode similar to the creation of a file, read and write permission creator, group, and others.
+
+The geometry of the message queue is contained in the attribute structure.  This includes mq_msgsize that dictates the maximum size of a single message, and the mq_maxmsg that dictates the maximum number of messages the queue can hold at one time.  If a NULL is used in the mq_attr argument, then the message queue is created with implementation defined defaults.
+@code{O_EXCL} - is always set if O_CREAT flag is set.  If the message queue already exists, O_EXCL causes an error message to be returned, otherwise, the new message queue fails and appends to the existing one.
+
 @subheading NOTES:
 
-@page
-@subsection mq_close - 
+The mq_open () function does not add or remove messages from the queue.  When a new message queue is being created, the mq_flag field of the attribute structure is not used.
+
+@subsection mq_close - to close the queue after a message has been sent
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_close(
-);
+#include <mqueue.h>
+int mq_close(mqd_t mqdes);
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+@code{EINVAL} - The descriptor does not represent a valid open message queue
 
 @subheading DESCRIPTION:
 
+The mq_close function removes the association between the message queue descriptor, mqdes, and its message queue. If mq_close() is successfully completed, the function returns a value of zero; otherwise, the function returns a value of -1 and sets errno to indicate the error.
+
 @subheading NOTES:
 
-@page
-@subsection mq_unlink - 
+If the process had successfully attached a notification request to the message queue via mq_notify, this attachment is removed, and the message queue is available for another process to attach for notification.  mq_close has no effect on the contents of the message queue, all the messages that were in the queue remain in the queue.
+
+@subsection mq_unlink - to remove a message queue from the system entirely
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_unlink(
-);
+#include <mqueue.h>
+int mq_unlink(const char *name);
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+@code{EINVAL} - The descriptor does not represent a valid message queue
 
 @subheading DESCRIPTION:
 
+The mq_unlink() function removes the named message queue.  If the message queue is not open when mq_unlink is called, then the queue is immediately eliminated.  Any messages that were on the queue are lost, and the queue can not be opened again.  If processes have the queue open when mq_unlink is called, the removal of the queue is delayed until the last process using the queue has finished.  However, the name of the message queue is removed so that no other process can open it.  Upon successful completion, the function returns a value of zero.  Otherwise, the named message queue is not changed by this function call, and the function returns a value of -1 and sets errno to indicate the error. 
+
 @subheading NOTES:
 
-@page
-@subsection mq_send - 
+Calls to mq_open() to re-create the message queue may fail until the message queue is actually removed.  However, the mq_unlink() call need not block until all references have been closed; it may return immediately.
+
+subsection mq_send - to send messages to a queue you have accessed
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_send(
-);
+#include<mqueue.h>
+int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len, unsigned int msg_prio);
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+@code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for read only O_RDONLY
+@code{EINVAL} - The value of msg_prio was greater than the MQ_PRIO_MAX.
+@code{EMSGSIZE} - The msg_len is greater than the mq_msgsize attribute of the message queue
+@code{EAGAIN} - The message queue is non-blocking, and there is no room on the queue for another message as specified by the mq_maxmsg.
+@code{EINTR} - The message queue is blocking.  While the process was waiting for free space on the queue, a signal arrived that interrupted the wait.
 
 @subheading DESCRIPTION:
 
+The mq_send() function adds the message pointed to by the argument msg_ptr to the message queue specified by mqdes.  Each message is assigned a priority , from 0 to MQ_PRIO_MAX. MQ_PRIO_MAX is defined in <limits.h> and must be at least 32.  Messages are added to the queue in order of their priority.  The highest priority message is at the front of the queue.
+The maximum number of messages that a message queue may accept is specified at creation by the mq_maxmsg field of the attribute structure.  If this amount is exceeded, the behavior of the process is determined according to what oflag was used when the message queue was opened.  If the queue was opened with O_NONBLOCK flag set, then the EAGAIN error is returned.  If the O_NONBLOCK flag was not set, the process blocks and waits for space on the queue, unless it is interrupted by a signal.
+Upon successful completion, the mq_send () function returns a value of zero.  Otherwise, no message is enqueued, the function returns -1, and errno is set to indicate the error.
+
 @subheading NOTES:
 
-@page
-@subsection mq_receive - 
+If the specified message queue is not full, mq_send inserts the message at the position indicated by the msg_prio argument.
+
+@subsection mq_receive - to receive messages from a queue you have accessed
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_receive(
-);
+#include <mqueue.h>
+size_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len, unsigned int *msg_prio);
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+@code{EBADF} - The descriptor does not represent a valid message queue, or the queue was opened for write only O_WRONLY
+@code{EMSGSIZE} - The msg_len is less than the mq_msgsize attribute of the message queue
+@code{EAGAIN} - The message queue is non-blocking, and the queue is empty
+@code{EINTR} - The message queue is blocking.  While the process was waiting for a message to arrive on the queue, a signal arrived that interrupted the wait.
 
 @subheading DESCRIPTION:
 
+The mq_receive function is used to receive the oldest of the highest priority message(s) from the message queue specified by mqdes.  The messages are received in FIFO order within the priorities.  The received message's priority is stored in the location referenced by the msg_prio.  If the msg_prio is a NULL, the priority is discarded.  The message is removed and stored in an area pointed to by msg_ptr whose length is of msg_len.  The msg_len must be at least equal to the mq_msgsize attribute of the message queue.
+The blocking behavior of the message queue is set by O_NONBLOCK at mq_open or by setting O_NONBLOCK in mq_flags in a call to mq_setattr.  If this is a blocking queue, the process blocks and waits on an empty queue.  If this a non-blocking queue, the process does not block.
+Upon successful completion, mq_receive returns the length of the selected message in bytes and the message is removed from the queue.  Otherwise, no message is removed from the queue, the function returns a value of -1, and sets errno to indicate the error.
+
 @subheading NOTES:
 
-@page
-@subsection mq_notify - 
+If the size of the buffer in bytes, specified by the msg_len argument, is less than the mq_msgsize attribute of the message queue, the function fails and returns an error
+
+@subsection mq_notify - to notify that a message is on the queue
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_notify(
-);
+#include <mqueue.h>
+int mq_notify (mqd_t mqdes, const struct sigevent * notification);
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+@code{EBADF} - The descriptor does not refer to a valid message queue
+@code{EBUSY} - A notification request is already attached to the queue
 
 @subheading DESCRIPTION:
 
+If the argument notification is not NULL, this function registers the calling process to be notified of message arrival at an empty message queue associated with the specified message queue descriptor, mqdes.
+Every message queue has the ability to notify one (and only one) process whenever the queue's state changes from empty (0 messages) to nonempty.  This means that the process does not have to block or constantly poll while it waits for a message.  By calling mq_notify, a notification request is attached to a message queue.  When a message is received by an empty queue, if there are no processes blocked and waiting for the message, then the queue notifies the requesting process of a message arrival.  There is only one signal sent by the message queue, after that the notification request is de-registered and another process can attach its notification request.  After receipt of a notification, a process must re-register if it wishes to be notified again.
+If there is a process blocked and waiting for the message, that process gets the message, and notification is not be sent.  Only one process can have a notification request attached to a message queue at any one time.  If another process attempts to register a notification request, it fails.  You can de-register for a message queue by passing a NULL to mq_notify; this removes any notification request attached to the queue.  Whenever the message queue is closed, all notification attachments are removed.
+Upon successful completion, mq_notify returns a value of zero; otherwise, the function returns a value of -1 and sets errno to indicate the error.
+
 @subheading NOTES:
 
-@page
-@subsection mq_setattr - 
+It is possible for another process to receive the message after the notification is sent but before the notified process has sent its receive request.
+
+@subsection mq_setattr - to change the blocking and non-blocking behavior of the message queue
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_setattr(
-);
+#include <mqueue.h>
+int mq_setattr(mqd_t mqdes, const struct mq_attr *mqstat, struct mq_attr *omqstat);
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+@code{EBADF} - The message queue descriptor does not refer to a valid, open queue.
+@code{EINVAL} - The mq_flag value is invalid.
 
 @subheading DESCRIPTION:
 
+The mq_setattr function is used to set attributes associated with the open message queue description referenced by the message queue descriptor specified by mqdes.  The *omqstat represents the old or previous attributes.  If omqstat is non-NULL, the function mq_setattr() stores, in the location referenced by omqstat, the previous message queue attributes and the current queue status.  These values are the same as would be returned by a call to mq_getattr() at that point.
+There is only one mq_attr.mq_flag which can be altered by this call.  This is the flag that deals with the blocking and non-blocking behavior of the message queue.  If the flag is set then the message queue is non-blocking, and requests to send or receive do not block while waiting for resources.  If the flag is not set, then message send and receive may involve waiting for an empty queue or waiting for a message to arrive.
+Upon successful completion, the function returns a value of zero and the attributes of the message queue have been changed as specified.  Otherwise, the message queue attributes is unchanged, and the function returns a value of -1 and sets errno to indicate the error.
+
 @subheading NOTES:
 
-@page
-@subsection mq_getattr - 
+All other fields in the mq_attr are ignored by this call.
+
+@subsection mq_getattr - retrieves the message queue attributes
 
 @subheading CALLING SEQUENCE:
 
-@ifset is-C
 @example
-int mq_getattr(
-);
+#include <mqueue.h>
+int mq_getattr(mqd_t mqdes, struct mq_attr *mqstat);
 @end example
-@end ifset
-
-@ifset is-Ada
-@end ifset
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+@code{EBADF} - The message queue descriptor does not refer to a valid, open message queue.
 
 @subheading DESCRIPTION:
 
+The mqdes argument specifies a message queue descriptor.  The mq_getattr function is used to get status information and attributes of the message queue associated with the message queue descriptor.  The results are returned in the mq_attr structure referenced by the mqstat argument.  All of these attributes are set at create time, except the blocking/non-blocking behavior of the message queue which can be dynamically set by using mq_setattr.  The attribute mq_curmsg is set to reflect the number of messages on the queue at the time that mq_getattr was called.
+Upon successful completion, the mq_getattr function returns zero.  Otherwise, the function returns -1 and sets errno to indicate the error. 
+
 @subheading NOTES:
 
diff --git a/doc/posix_users/posix_users.texi b/doc/posix_users/posix_users.texi
index fbbe5b9905..1439478001 100644
--- a/doc/posix_users/posix_users.texi
+++ b/doc/posix_users/posix_users.texi
@@ -119,7 +119,7 @@ This is the online version of the RTEMS POSIX API User's Guide
 * Device- and Class- Specific Functions Manager::
 * Language-Specific Services for the C Programming Language Manager::
 * System Databases Manager::
-* Semaphores Manager::
+* Semaphore Manager::
 * Mutex Manager::
 * Condition Variable Manager::
 * Memory Management Manager::
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.