Index: doc/posix_users/mutex.t
===================================================================
--- doc/posix_users/mutex.t	(revision d48ea699b4c1d24d45aa00cd096db855190d7575)
+++ doc/posix_users/mutex.t	(revision 56853af0e1b3adb9688af41f489c87976e93e757)
@@ -11,44 +11,80 @@
 @section Introduction
 
-The mutex manager ...
-
-The directives provided by the mutex manager are:
+The mutex manager implements the functionality required of the mutex
+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.
+
+The services provided by the mutex manager are:
 
 @itemize @bullet
-@item @code{pthread_mutexattr_init} - 
-@item @code{pthread_mutexattr_destroy} - 
-@item @code{pthread_mutexattr_setprotocol} - 
-@item @code{pthread_mutexattr_getprotocol} - 
-@item @code{pthread_mutexattr_setprioceiling} - 
-@item @code{pthread_mutexattr_getprioceiling} - 
-@item @code{pthread_mutexattr_setpshared} - 
-@item @code{pthread_mutexattr_getpshared} - 
-@item @code{pthread_mutex_init} - 
-@item @code{pthread_mutex_destroy} - 
-@item @code{pthread_mutex_lock} - 
-@item @code{pthread_mutex_trylock} - 
-@item @code{pthread_mutex_timedlock} - 
-@item @code{pthread_mutex_unlock} - 
-@item @code{pthread_mutex_setprioceiling} - 
-@item @code{pthread_mutex_getprioceiling} - 
+@item @code{pthread_mutexattr_init} - Initialize a Mutex Attribute Set
+@item @code{pthread_mutexattr_destroy} - Destroy a Mutex Attribute Set
+@item @code{pthread_mutexattr_setprotocol} - Set the Blocking Protocol
+@item @code{pthread_mutexattr_getprotocol} - Get the Blocking Protocol
+@item @code{pthread_mutexattr_setprioceiling} - Set the Priority Ceiling
+@item @code{pthread_mutexattr_getprioceiling} - Get the Priority Ceiling
+@item @code{pthread_mutexattr_setpshared} - Set the Visibility
+@item @code{pthread_mutexattr_getpshared} - Get the Visibility
+@item @code{pthread_mutex_init} - Initialize a Mutex
+@item @code{pthread_mutex_destroy} - Destroy a Mutex
+@item @code{pthread_mutex_lock} - Lock a Mutex
+@item @code{pthread_mutex_trylock} - Poll to Lock a Mutex
+@item @code{pthread_mutex_timedlock} - Lock a Mutex with Timeout
+@item @code{pthread_mutex_unlock} - Unlock a Mutex
+@item @code{pthread_mutex_setprioceiling} - Dynamically Set the Priority Ceiling
+@item @code{pthread_mutex_getprioceiling} - Dynamically Get the Priority Ceiling
 @end itemize
 
 @section Background
 
+@subsection Mutex Attributes
+
+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
+a mutex may be set at run-time.
+
+@table @b
+@item blocking protcol
+is the XXX
+
+@item priority ceiling
+is the XXX
+
+@item pshared
+is the XXX
+
+@end table
+
+@subsection PTHREAD_MUTEX_INITIALIZER
+
+This is a special value that a variable of type @code{pthread_mutex_t}
+may be statically initialized to as shown below:
+
+@example
+pthread_mutex_t my_mutex = PTHREAD_MUTEX_INITIALIZER;
+@end example
+
+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.  
+
+Note that the mutex will be initialized with default attributes.
+
+@section Operations
+
 There is currently no text in this section.
 
-@section Operations
-
-There is currently no text in this section.
-
-@section Directives
-
-This section details the mutex manager's directives.
-A subsection is dedicated to each of this manager's directives
+@section Services
+
+This section details the mutex manager's services.
+A subsection is dedicated to each of this manager's services
 and describes the calling sequence, related constants, usage,
 and status codes.
 
 @page
-@subsection pthread_mutexattr_init
+@subsection pthread_mutexattr_init - Initialize a Mutex Attribute Set
 
 @subheading CALLING SEQUENCE:
@@ -72,8 +108,14 @@
 @subheading DESCRIPTION:
 
-@subheading NOTES:
-
-@page
-@subsection pthread_mutexattr_destroy
+The @code{pthread_mutexattr_init} routine initializes the mutex attributes
+object specified by @code{attr} with the default value for all of the
+individual attributes.
+
+@subheading NOTES:
+
+XXX insert list of default attributes here.
+
+@page
+@subsection pthread_mutexattr_destroy - Destroy a Mutex Attribute Set
 
 @subheading CALLING SEQUENCE:
@@ -100,8 +142,14 @@
 @subheading DESCRIPTION:
 
-@subheading NOTES:
-
-@page
-@subsection pthread_mutexattr_setprotocol
+The @code{pthread_mutex_attr_destroy} routine is used to destroy a mutex
+attributes object.  The behavior of using an attributes object after
+it is destroyed is implementation dependent.
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection pthread_mutexattr_setprotocol - Set the Blocking Protocol
 
 @subheading CALLING SEQUENCE:
@@ -132,8 +180,32 @@
 @subheading DESCRIPTION:
 
-@subheading NOTES:
-
-@page
-@subsection pthread_mutexattr_getprotocol
+The @code{pthread_mutexattr_setprotocol} routine is used to set value of the
+@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:
+
+@table @b
+
+@item @code{PTHREAD_PRIO_NONE}
+in which case blocking order is FIFO.
+
+@item @code{PTHREAD_PRIO_INHERIT}
+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
+protocol in effect.
+
+@end table
+
+@subheading NOTES:
+
+There is currently no way to get simple priority blocking ordering
+with POSIX mutexes even though this could easily by supported by RTEMS.
+
+@page
+@subsection pthread_mutexattr_getprotocol - Get the Blocking Protocol
  
 @subheading CALLING SEQUENCE:
@@ -164,8 +236,14 @@
 @subheading DESCRIPTION:
  
-@subheading NOTES:
-
-@page
-@subsection pthread_mutexattr_setprioceiling
+The @code{pthread_mutexattr_getprotocol} routine is used to obtain
+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
+
+@page
+@subsection pthread_mutexattr_setprioceiling - Set the Priority Ceiling
 
 @subheading CALLING SEQUENCE:
@@ -196,8 +274,16 @@
 @subheading DESCRIPTION:
 
-@subheading NOTES:
-
-@page
-@subsection pthread_mutexattr_getprioceiling
+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}.  
+
+@subheading NOTES:
+
+NONE
+
+@page
+@subsection pthread_mutexattr_getprioceiling - Get the Priority Ceiling
 
 @subheading CALLING SEQUENCE:
@@ -228,8 +314,15 @@
 @subheading DESCRIPTION:
 
-@subheading NOTES:
-
-@page
-@subsection pthread_mutexattr_setpshared
+The @code{pthread_mutexattr_getprioceiling} routine is used to obtain the
+value of the @code{prioceiling} attribute.  This attribute specifies the
+priority ceiling for this mutex.
+
+
+@subheading NOTES:
+
+
+NONE
+@page
+@subsection pthread_mutexattr_setpshared - Set the Visibility
 
 @subheading CALLING SEQUENCE:
@@ -263,5 +356,5 @@
 
 @page
-@subsection pthread_mutexattr_getpshared
+@subsection pthread_mutexattr_getpshared - Get the Visibility
 
 @subheading CALLING SEQUENCE:
@@ -295,5 +388,5 @@
 
 @page
-@subsection pthread_mutex_init
+@subsection pthread_mutex_init - Initialize a Mutex
 
 @subheading CALLING SEQUENCE:
@@ -334,5 +427,5 @@
 
 @page
-@subsection pthread_mutex_destroy
+@subsection pthread_mutex_destroy - Destroy a Mutex
 
 @subheading CALLING SEQUENCE:
@@ -363,5 +456,5 @@
 
 @page
-@subsection pthread_mutex_lock
+@subsection pthread_mutex_lock - Lock a Mutex
 
 @subheading CALLING SEQUENCE:
@@ -396,5 +489,5 @@
 
 @page
-@subsection pthread_mutex_trylock
+@subsection pthread_mutex_trylock - Poll to Lock a Mutex
  
 @subheading CALLING SEQUENCE:
@@ -429,5 +522,5 @@
  
 @page
-@subsection pthread_mutex_timedlock
+@subsection pthread_mutex_timedlock - Lock a Mutex with Timeout
  
 @subheading CALLING SEQUENCE:
@@ -468,5 +561,5 @@
 
 @page
-@subsection pthread_mutex_unlock
+@subsection pthread_mutex_unlock - Unlock a Mutex
 
 @subheading CALLING SEQUENCE:
@@ -493,5 +586,5 @@
 
 @page
-@subsection pthread_mutex_setprioceiling
+@subsection pthread_mutex_setprioceiling - Dynamically Set the Priority Ceiling
 
 @subheading CALLING SEQUENCE:
@@ -526,5 +619,5 @@
 
 @page
-@subsection pthread_mutex_getprioceiling
+@subsection pthread_mutex_getprioceiling - Get the Current Priority Ceiling
 
 @subheading CALLING SEQUENCE:
