2001-06-28 Joel Sherrill <joel@OARcorp.com>

	* preface.texi, procenv.t, process.t, signal.t, stamp-vti,
	version.texi: Updated as part of starting a sweep on the POSIX
	User's Guide.

7 files changed, 358 insertions, 143 deletions

diff --git a/doc/posix_users/ChangeLog b/doc/posix_users/ChangeLog
index adf1d1a42f..c8ceac2424 100644
--- a/doc/posix_users/ChangeLog
+++ b/doc/posix_users/ChangeLog
@@ -1,3 +1,8 @@
+2001-06-28	Joel Sherrill <joel@OARcorp.com>
+
+	* preface.texi, procenv.t, process.t, signal.t, stamp-vti,
+	version.texi: Updated as part of starting a sweep on the POSIX
+	User's Guide.
 2002-03-27	Ralf Corsepius <corsepiu@faw.uni-ulm.de>
 
 	* Makefile.am: Remove AUTOMAKE_OPTIONS.
diff --git a/doc/posix_users/preface.texi b/doc/posix_users/preface.texi
index 9fc063d90a..19933dcbaf 100644
--- a/doc/posix_users/preface.texi
+++ b/doc/posix_users/preface.texi
@@ -23,12 +23,14 @@ on the following standards:
 
 @item POSIX 1003.1h/D3.
 
+@item Open Group Single UNIX Specification.
+
 @end itemize
 
 Much of the POSIX API standard is actually implemented in the
 Cygnus Newlib ANSI C Library.  Please refer to documentation on
-Newlib for more information on what it supplies.
+Newlib for more information on the functionality it supplies.
 
-At this point, this is just beginning to become what it 
-ultimately should be.
+This manual is still under construction and improvements
+are welcomed from users.
 
diff --git a/doc/posix_users/procenv.t b/doc/posix_users/procenv.t
index d1af8ae672..db3f8936d8 100644
--- a/doc/posix_users/procenv.t
+++ b/doc/posix_users/procenv.t
@@ -10,7 +10,8 @@
 
 @section Introduction
 
-The process environment manager is ...
+The process environment manager is responsible for providing the
+functions related to user and group Id management.
 
 The directives provided by the process environment manager are:
 
@@ -42,11 +43,67 @@ The directives provided by the process environment manager are:
 
 @section Background
 
-There is currently no text in this section.
+@subsection Users and Groups
+
+RTEMS provides a single process, multi-threaded execution environment.
+In this light, the notion of user and group is somewhat without meaning.
+But RTEMS does provide services to provide a synthetic version of
+user and group.  By default, a single user and group is associated 
+with the application.  Thus unless special actions are taken,
+every thread in the application shares the same user and group Id.
+The initial rationale for providing user and group Id functionality
+in RTEMS was for the filesystem infrastructure to implement
+file permission checks.  The effective user/group Id capability
+has since been used to implement permissions checking by
+the @code{ftpd} server.
+
+In addition to the "real" user and group Ids, a process may
+have an effective user/group Id.  This allows a process to
+function using a more limited permission set for certain operations.
+
+@subsection User and Group Names
+
+POSIX considers user and group Ids to be a unique integer that
+may be associated with a name.  This is usually accomplished
+via a file named @code{/etc/passwd} for user Id mapping and
+@code{/etc/groups} for group Id mapping.  Again, although
+RTEMS is effectively a single process and thus single user
+system, it provides limited support for user and group
+names.  When configured with an appropriate filesystem, RTEMS 
+will access the appropriate files to map user and group Ids
+to names.
+
+If these files do not exist, then RTEMS will synthesize
+a minimal version so this family of services return without
+error.  It is important to remember that a design goal of
+the RTEMS POSIX services is to provide useable and 
+meaningful results even though a full process model
+is not available.
+
+@subsection Environment Variables
+
+POSIX allows for variables in the run-time environment.  These are 
+name/value pairs that make be dynamically set and obtained by
+programs.  In a full POSIX environment with command line shell
+and multiple processes,  environment variables may be set in
+one process -- such as the shell -- and inherited by child
+processes.  In RTEMS, there is only one process and thus
+only one set of environment variables across all processes.
+
 
 @section Operations
 
-There is currently no text in this section.
+@subsection Accessing User and Group Ids
+
+The user Id associated with the current thread may be obtain
+using the @code{getuid()} service.  Similarly, the group Id
+may be obtained using the @code{getgid()} service.  
+
+@subsection Accessing Environment Variables
+
+The value associated with an environment variable may be 
+obtained using the @code{getenv()} service and set using
+the @code{putenv()} service.
 
 @section Directives
 
@@ -68,8 +125,7 @@ and status codes.
 
 @ifset is-C
 @example
-int getpid(
-);
+int getpid( void );
 @end example
 @end ifset
 
@@ -78,16 +134,16 @@ int getpid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The process Id is returned.
 
 @subheading DESCRIPTION:
 
+This service returns the process Id.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -101,8 +157,7 @@ The
 
 @ifset is-C
 @example
-int getppid(
-);
+int getppid( void );
 @end example
 @end ifset
 
@@ -111,16 +166,16 @@ int getppid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The parent process Id is returned.
 
 @subheading DESCRIPTION:
 
+This service returns the parent process Id.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -134,8 +189,7 @@ The
 
 @ifset is-C
 @example
-int getuid(
-);
+int getuid( void );
 @end example
 @end ifset
 
@@ -144,16 +198,16 @@ int getuid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The effective user Id is returned.
 
 @subheading DESCRIPTION:
 
+This service returns the effective user Id.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -167,8 +221,7 @@ The
 
 @ifset is-C
 @example
-int geteuid(
-);
+int geteuid( void );
 @end example
 @end ifset
 
@@ -177,16 +230,16 @@ int geteuid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The effective group Id is returned.
 
 @subheading DESCRIPTION:
 
+This service returns the effective group Id.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -200,8 +253,7 @@ The
 
 @ifset is-C
 @example
-int getgid(
-);
+int getgid( void );
 @end example
 @end ifset
 
@@ -210,16 +262,16 @@ int getgid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The group Id is returned.
 
 @subheading DESCRIPTION:
 
+This service returns the group Id.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -233,8 +285,7 @@ The
 
 @ifset is-C
 @example
-int getegid(
-);
+int getegid( void );
 @end example
 @end ifset
 
@@ -243,16 +294,16 @@ int getegid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The effective group Id is returned.
 
 @subheading DESCRIPTION:
 
+This service returns the effective group Id.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -267,6 +318,7 @@ The
 @ifset is-C
 @example
 int setuid(
+  uid_t uid
 );
 @end example
 @end ifset
@@ -276,16 +328,16 @@ int setuid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+This service returns 0.
 
 @subheading DESCRIPTION:
 
+This service sets the user Id to @code{uid}.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -300,6 +352,7 @@ The
 @ifset is-C
 @example
 int setgid(
+  gid_t  gid
 );
 @end example
 @end ifset
@@ -309,16 +362,16 @@ int setgid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+This service returns 0.
 
 @subheading DESCRIPTION:
 
+This service sets the group Id to @code{gid}.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -333,6 +386,8 @@ The
 @ifset is-C
 @example
 int getgroups(
+  int    gidsetsize,
+  gid_t  grouplist[]
 );
 @end example
 @end ifset
@@ -342,16 +397,18 @@ int getgroups(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+NA
 
 @subheading DESCRIPTION:
 
+This service is not implemented as RTEMS has no notion of 
+supplemental groups.
+
 @subheading NOTES:
 
+If supported, this routine would only be allowed for
+the super-user.
+
 @c
 @c
 @c
@@ -365,8 +422,7 @@ The
 
 @ifset is-C
 @example
-int getlogin(
-);
+char *getlogin( void );
 @end example
 @end ifset
 
@@ -375,16 +431,18 @@ int getlogin(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+Returns a pointer to a string containing the name of the
+current user.
 
 @subheading DESCRIPTION:
 
+This routine returns the name of the current user.
+
 @subheading NOTES:
 
+This routine is not reentrant and subsequent calls to
+@code{getlogin()} will overwrite the same buffer.
+
 @c
 @c
 @c
@@ -393,12 +451,15 @@ The
 
 @findex getlogin_r
 @cindex  reentrant get user name
+@cindex  get user name, reentrant
 
 @subheading CALLING SEQUENCE:
 
 @ifset is-C
 @example
 int getlogin_r(
+  char   *name,
+  size_t  namesize  
 );
 @end example
 @end ifset
@@ -409,15 +470,21 @@ int getlogin_r(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EINVAL
+The arguments were invalid.
 
 @end table
 
 @subheading DESCRIPTION:
 
+This is a reentrant version of the @code{getlogin()} service.  The 
+caller specified their own buffer, @code{name}, as well as the 
+length of this buffer, @code{namesize}.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -431,8 +498,7 @@ The
 
 @ifset is-C
 @example
-int getpgrp(
-);
+pid_t getpgrp( void );
 @end example
 @end ifset
 
@@ -441,16 +507,17 @@ int getpgrp(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The procress group Id is returned.
 
 @subheading DESCRIPTION:
 
+This service returns the current progress group Id.
+
 @subheading NOTES:
 
+This routine is implemented in a somewhat meaningful
+way for RTEMS but is truly not functional.
+
 @c
 @c
 @c
@@ -464,8 +531,7 @@ The
 
 @ifset is-C
 @example
-int setsid(
-);
+pid_t setsid( void );
 @end example
 @end ifset
 
@@ -475,15 +541,21 @@ int setsid(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EPERM
+The application does not have permission to create a process group.
 
 @end table
 
 @subheading DESCRIPTION:
 
+This routine always returns @code{EPERM} as RTEMS has no way
+to create new processes and thus no way to create a new process
+group.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -498,6 +570,8 @@ The
 @ifset is-C
 @example
 int setpgid(
+  pid_t pid,
+  pid_t pgid
 );
 @end example
 @end ifset
@@ -508,15 +582,20 @@ int setpgid(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item ENOSYS
+The routine is not implemented.
 
 @end table
 
 @subheading DESCRIPTION:
 
+This service is not implemented for RTEMS as process groups are not
+supported.
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -531,6 +610,7 @@ The
 @ifset is-C
 @example
 int uname(
+  struct utsname *name
 );
 @end example
 @end ifset
@@ -541,15 +621,24 @@ int uname(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item EPERM
+The provided structure pointer is invalid.
 
 @end table
 
 @subheading DESCRIPTION:
 
+This service returns system information to the caller.  It does this
+by filling in the @code{struct utsname} format structure for the
+caller.
+
 @subheading NOTES:
 
+The information provided includes the operating system (RTEMS in
+all configurations), the node number, the release as the RTEMS
+version, and the CPU family and model.  The CPU model name 
+will indicate the multilib executive variant being used.
+
 @c
 @c
 @c
@@ -565,26 +654,31 @@ The
 #include <sys/time.h>
 
 clock_t times(
-  struct tms *buf
+  struct tms *ptms
 );
 @end example
 
 @subheading STATUS CODES:
 
-This routine returns the process times
+This routine returns the number of clock ticks that have elapsed
+since the system was initialized (e.g. the application was 
+started).
 
 @subheading DESCRIPTION:
 
-@code{times} stores the current process times in @code{buf}.
-
-@code{struct tms} is as defined in @code{/usr/include/sys/times.h}
-
-@code{times} returns the number of clock ticks that have elapsed
-since the systm has been up.
+@code{times} stores the current process times in @code{ptms}.  The
+format of @code{struct tms} is as defined in
+@code{<sys/times.h>}.  RTEMS fills in the field @code{tms_utime}
+with the number of ticks that the calling thread has executed
+and the field @code{tms_stime} with the number of clock ticks
+since system boot (also returned).  All other fields in the
+@code{ptms} are left zero.
 
 @subheading NOTES:
 
-NONE
+RTEMS has no way to distinguish between user and system time
+so this routine returns the most meaningful information 
+possible.
 
 @c
 @c
@@ -599,7 +693,8 @@ NONE
 
 @ifset is-C
 @example
-int getenv(
+char *getenv(
+  const char *name
 );
 @end example
 @end ifset
@@ -610,15 +705,25 @@ int getenv(
 @subheading STATUS CODES:
 
 @table @b
-@item E
-The
+@item NULL
+when no match
+
+@item pointer to value
+when successful
 
 @end table
 
 @subheading DESCRIPTION:
 
+This service searches the set of environment variables for 
+a string that matches the specified @code{name}.  If found,
+it returns the associated value.
+
 @subheading NOTES:
 
+The environment list consists of name value pairs that
+are of the form @i{name = value}.
+
 @c
 @c
 @c
@@ -633,6 +738,9 @@ The
 @ifset is-C
 @example
 int setenv(
+  const char *name,
+  const char *value,
+  int overwrite
 );
 @end example
 @end ifset
@@ -642,16 +750,19 @@ int setenv(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+Returns 0 if successful and -1 otherwise.
 
 @subheading DESCRIPTION:
 
+This service adds the variable @code{name} to the environment with
+@code{value}.  If @code{name} is not already exist, then it is
+created.  If @code{name} exists and @code{overwrite} is zero, then
+the previous value is not overwritten. 
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -665,7 +776,8 @@ The
 
 @ifset is-C
 @example
-int ctermid(
+char *ctermid(
+  char *s
 );
 @end example
 @end ifset
@@ -675,16 +787,24 @@ int ctermid(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+Returns a pointer to a string indicating the pathname for the controlling
+terminal.
 
 @subheading DESCRIPTION:
 
+This service returns the name of the terminal device associated with
+this process.  If @code{s} is NULL, then a pointer to a static buffer
+is returned.  Otherwise, @code{s} is assumed to have a buffer of
+sufficient size to contain the name of the controlling terminal.
+
 @subheading NOTES:
 
+By default on RTEMS systems, the controlling terminal is @code{/dev/console}.
+Again this implementation is of limited meaning, but it provides
+true and useful results which should be sufficient to ease porting
+applications from a full POSIX implementation to the reduced
+profile supported by RTEMS.
+
 @c
 @c
 @c
@@ -698,7 +818,8 @@ The
 
 @ifset is-C
 @example
-int ttyname(
+char *ttyname(
+  int fd
 );
 @end example
 @end ifset
@@ -708,16 +829,20 @@ int ttyname(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+Pointer to a string containing the terminal device name or
+NULL is returned on any error.
 
 @subheading DESCRIPTION:
 
+This service returns a pointer to the pathname of the terminal
+device that is open on the file descriptor @code{fd}.  If 
+@code{fd} is not a valid descriptor for a terminal device,
+then NULL is returned.
+
 @subheading NOTES:
 
+This routine uses a static buffer.
+
 @c
 @c
 @c
@@ -732,6 +857,9 @@ The
 @ifset is-C
 @example
 int ttyname_r(
+  int   fd,
+  char *name,
+  int   namesize
 );
 @end example
 @end ifset
@@ -741,16 +869,26 @@ int ttyname_r(
 
 @subheading STATUS CODES:
 
+This routine returns -1 and sets @code{errno} as follows:
+
 @table @b
-@item E
-The
+@item EBADF
+If not a valid descriptor for a terminal device.
+
+@item EINVAL
+If @code{name} is NULL or @code{namesize} are insufficient.
 
 @end table
 
 @subheading DESCRIPTION:
 
+This service the pathname of the terminal device that is open
+on the file descriptor @code{fd}.  
+
 @subheading NOTES:
 
+NONE
+
 @c
 @c
 @c
@@ -765,6 +903,7 @@ The
 @ifset is-C
 @example
 int isatty(
+  int fd
 );
 @end example
 @end ifset
@@ -774,14 +913,13 @@ int isatty(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+Returns 1 if @code{fd} is a terminal device and 0 otherwise.
 
 @subheading DESCRIPTION:
 
+This service returns 1 if @code{fd} is an open file descriptor 
+connected to a terminal and 0 otherwise.
+
 @subheading NOTES:
 
 @c
@@ -797,7 +935,8 @@ The
 
 @ifset is-C
 @example
-int sysconf(
+long sysconf(
+  int name
 );
 @end example
 @end ifset
@@ -807,13 +946,19 @@ int sysconf(
 
 @subheading STATUS CODES:
 
-@table @b
-@item E
-The
-
-@end table
+The value returned is the actual value of the system resource.
+If the requested configuration name is a feature flag, then
+1 is returned if the available and 0 if it is not.  On any
+other error condition, -1 is returned.
 
 @subheading DESCRIPTION:
 
+This service is the mechanism by which an application determines
+values for system limits or options at runtime. 
+
 @subheading NOTES:
 
+Much of the information that may be obtained via @code{sysconf}
+has equivalent macros in @code{<unistd.h}.  However, those
+macros reflect conservative limits which may have been altered
+by application configuration.
diff --git a/doc/posix_users/process.t b/doc/posix_users/process.t
index 4b23172a25..7bb4bb12ad 100644
--- a/doc/posix_users/process.t
+++ b/doc/posix_users/process.t
@@ -10,7 +10,10 @@
 
 @section Introduction
 
-The process creation and execution manager is ...
+The process creation and execution manager provides the 
+functionality associated with the creation and termination
+of processes.  
+
 
 The directives provided by the process creation and execution manager are:
 
@@ -30,11 +33,24 @@ The directives provided by the process creation and execution manager are:
 
 @section Background
 
-There is currently no text in this section.
+POSIX process functionality can not be completely 
+supported by RTEMS.  This is because RTEMS provides no memory
+protection and implements a @i{single process, multi-threaded 
+execution model}.  In this light, RTEMS provides none of the
+routines that are associated with the creation of new processes.
+However, since the entire RTEMS application (e.g. executable)
+is logically a single POSIX process, RTEMS is able to provide
+implementations of many operations on processes.  The rule of
+thumb is that those routines provide a meaningful result.
+For example, @code{getpid()} returns the node number. 
 
 @section Operations
 
-There is currently no text in this section.
+The only functionality method defined by this manager which is
+supported by RTEMS is the @code{_exit} service.  The 
+implementation of @code{_exit} shuts the application down and
+is equivalent to invoking either @code{exit} or
+@code{rtems_shutdown_executive}.
 
 @section Directives
 
diff --git a/doc/posix_users/signal.t b/doc/posix_users/signal.t
index c882c4d3f4..b56d325422 100644
--- a/doc/posix_users/signal.t
+++ b/doc/posix_users/signal.t
@@ -10,7 +10,9 @@
 
 @section Introduction
 
-The signal manager ...
+The signal manager provides the functionality associated with
+the generation, delivery, and management of process-oriented
+signals.
 
 The directives provided by the signal manager are:
 
@@ -37,12 +39,35 @@ The directives provided by the signal manager are:
 
 @section Background
 
+@subsection Signals
+
+POSIX signals are an asynchronous event mechanism.  Each process
+and thread has a set of signals associated with it.  Individual
+signals may be enabled (e.g. unmasked) or blocked (e.g. ignored)
+on both a per-thread and process level.  Signals which are
+enabled have a signal handler associated with them.  When the
+signal is generated and conditions are met, then the signal
+handler is invoked in the proper process or thread context
+asynchronous relative to the logical thread of execution.
+
+If a signal has been blocked when it is generated, then it
+is queued and kept pending until the thread or process unblocks
+the signal or explicitly checks for it.
+Traditional, non-real-time POSIX signals do not queue.  Thus
+if a process or thread has blocked a particular signal, then
+multiple occurrences of that signal are recorded as a 
+single occurrence of that signal.  
+
+One can check for the set of outstanding signals that have been
+blocked.   Services are provided to check for outstanding process
+or thread directed signals.
+
 @subsection Signal Delivery
 
-Signals directed at a thread are delivered to the specified thread.
+Signals which are directed at a thread are delivered to the specified thread.
 
-Signals directed at a process are delivered to a thread which is selected
-based on the following algorithm:
+Signals which are directed at a process are delivered to a thread which
+is selected based on the following algorithm:
 
 @enumerate
 @item If the action for this signal is currently @code{SIG_IGN},
@@ -71,7 +96,29 @@ pending. The first thread to unblock the signal (@code{sigprocmask()} or
 
 @section Operations
 
-There is currently no text in this section.
+@subsection Signal Set Management
+
+Each process and each thread within that process has a set of
+individual signals and handlers associated with it.   Services
+are provided to construct signal sets for the purposes of building
+signal sets -- type @code{sigset_t} -- that are used to 
+provide arguments to the services that mask, unmask, and 
+check on pending signals.
+
+@subsection Blocking Until Signal Generation
+
+A thread may block until receipt of a signal.  The "sigwait"
+and "pause" families of services block until the requested
+signal is received or if using @code{sigtimedwait()} until the specified 
+timeout period has elapsed.
+
+@subsection Sending a Signal
+
+This is accomplished
+via one of a number of services that sends a signal to either a 
+process or thread.  Signals may be directed at a process by 
+the service @code{kill()} or at a thread by the service
+@code{pthread_kill()}
 
 @section Directives
 
@@ -618,8 +665,8 @@ Signal interrupted this function.
 
 @subheading DESCRIPTION:
 
-This function causes the calling thread to be blocked until the signal
-is received.
+This function causes the calling thread to be blocked until an
+unblocked signal is received.
 
 @subheading NOTES:
 
diff --git a/doc/posix_users/stamp-vti b/doc/posix_users/stamp-vti
index 71b7aee620..c2e2d65fe2 100644
--- a/doc/posix_users/stamp-vti
+++ b/doc/posix_users/stamp-vti
@@ -1,4 +1,4 @@
 @set UPDATED 17 January 2002
 @set UPDATED-MONTH January 2002
-@set EDITION Snapshot
-@set VERSION Snapshot
+@set EDITION ss-20020528
+@set VERSION ss-20020528
diff --git a/doc/posix_users/version.texi b/doc/posix_users/version.texi
index 71b7aee620..c2e2d65fe2 100644
--- a/doc/posix_users/version.texi
+++ b/doc/posix_users/version.texi
@@ -1,4 +1,4 @@
 @set UPDATED 17 January 2002
 @set UPDATED-MONTH January 2002
-@set EDITION Snapshot
-@set VERSION Snapshot
+@set EDITION ss-20020528
+@set VERSION ss-20020528