1 files changed, 765 insertions, 0 deletions
diff --git a/posix_users/process_environment.rst b/posix_users/process_environment.rst
new file mode 100644
index 0000000..0deee9d
--- /dev/null
+++ b/posix_users/process_environment.rst
@@ -0,0 +1,765 @@
+Process Environment Manager
+###########################
+
+Introduction
+============
+
+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:
+
+- ``getpid`` - Get Process ID
+
+- ``getppid`` - Get Parent Process ID
+
+- ``getuid`` - Get User ID
+
+- ``geteuid`` - Get Effective User ID
+
+- ``getgid`` - Get Real Group ID
+
+- ``getegid`` - Get Effective Group ID
+
+- ``setuid`` - Set User ID
+
+- ``setgid`` - Set Group ID
+
+- ``getgroups`` - Get Supplementary Group IDs
+
+- ``getlogin`` - Get User Name
+
+- ``getlogin_r`` - Reentrant Get User Name
+
+- ``getpgrp`` - Get Process Group ID
+
+- ``setsid`` - Create Session and Set Process Group ID
+
+- ``setpgid`` - Set Process Group ID for Job Control
+
+- ``uname`` - Get System Name
+
+- ``times`` - Get Process Times
+
+- ``getenv`` - Get Environment Variables
+
+- ``setenv`` - Set Environment Variables
+
+- ``ctermid`` - Generate Terminal Pathname
+
+- ``ttyname`` - Determine Terminal Device Name
+
+- ``ttyname_r`` - Reentrant Determine Terminal Device Name
+
+- ``isatty`` - Determine if File Descriptor is Terminal
+
+- ``sysconf`` - Get Configurable System Variables
+
+Background
+==========
+
+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 ``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.
+
+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 ``/etc/passwd`` for user Id mapping and``/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.
+
+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.
+
+Operations
+==========
+
+Accessing User and Group Ids
+----------------------------
+
+The user Id associated with the current thread may be obtain
+using the ``getuid()`` service.  Similarly, the group Id
+may be obtained using the ``getgid()`` service.
+
+Accessing Environment Variables
+-------------------------------
+
+The value associated with an environment variable may be
+obtained using the ``getenv()`` service and set using
+the ``putenv()`` service.
+
+Directives
+==========
+
+This section details the process environment 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.
+
+getpid - Get Process ID
+-----------------------
+.. index:: getpid
+.. index:: get process id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int getpid( void );
+
+**STATUS CODES:**
+
+The process Id is returned.
+
+**DESCRIPTION:**
+
+This service returns the process Id.
+
+**NOTES:**
+
+NONE
+
+getppid - Get Parent Process ID
+-------------------------------
+.. index:: getppid
+.. index:: get parent process id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int getppid( void );
+
+**STATUS CODES:**
+
+The parent process Id is returned.
+
+**DESCRIPTION:**
+
+This service returns the parent process Id.
+
+**NOTES:**
+
+NONE
+
+getuid - Get User ID
+--------------------
+.. index:: getuid
+.. index:: get user id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int getuid( void );
+
+**STATUS CODES:**
+
+The effective user Id is returned.
+
+**DESCRIPTION:**
+
+This service returns the effective user Id.
+
+**NOTES:**
+
+NONE
+
+geteuid - Get Effective User ID
+-------------------------------
+.. index:: geteuid
+.. index:: get effective user id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int geteuid( void );
+
+**STATUS CODES:**
+
+The effective group Id is returned.
+
+**DESCRIPTION:**
+
+This service returns the effective group Id.
+
+**NOTES:**
+
+NONE
+
+getgid - Get Real Group ID
+--------------------------
+.. index:: getgid
+.. index:: get real group id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int getgid( void );
+
+**STATUS CODES:**
+
+The group Id is returned.
+
+**DESCRIPTION:**
+
+This service returns the group Id.
+
+**NOTES:**
+
+NONE
+
+getegid - Get Effective Group ID
+--------------------------------
+.. index:: getegid
+.. index:: get effective group id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int getegid( void );
+
+**STATUS CODES:**
+
+The effective group Id is returned.
+
+**DESCRIPTION:**
+
+This service returns the effective group Id.
+
+**NOTES:**
+
+NONE
+
+setuid - Set User ID
+--------------------
+.. index:: setuid
+.. index:: set user id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int setuid(
+    uid_t uid
+    );
+
+**STATUS CODES:**
+
+This service returns 0.
+
+**DESCRIPTION:**
+
+This service sets the user Id to ``uid``.
+
+**NOTES:**
+
+NONE
+
+setgid - Set Group ID
+---------------------
+.. index:: setgid
+.. index:: set group id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int setgid(
+    gid_t  gid
+    );
+
+**STATUS CODES:**
+
+This service returns 0.
+
+**DESCRIPTION:**
+
+This service sets the group Id to ``gid``.
+
+**NOTES:**
+
+NONE
+
+getgroups - Get Supplementary Group IDs
+---------------------------------------
+.. index:: getgroups
+.. index:: get supplementary group ids
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int getgroups(
+    int    gidsetsize,
+    gid_t  grouplist[]
+    );
+
+**STATUS CODES:**
+
+NA
+
+**DESCRIPTION:**
+
+This service is not implemented as RTEMS has no notion of
+supplemental groups.
+
+**NOTES:**
+
+If supported, this routine would only be allowed for
+the super-user.
+
+getlogin - Get User Name
+------------------------
+.. index:: getlogin
+.. index:: get user name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    char \*getlogin( void );
+
+**STATUS CODES:**
+
+Returns a pointer to a string containing the name of the
+current user.
+
+**DESCRIPTION:**
+
+This routine returns the name of the current user.
+
+**NOTES:**
+
+This routine is not reentrant and subsequent calls to``getlogin()`` will overwrite the same buffer.
+
+getlogin_r - Reentrant Get User Name
+------------------------------------
+.. index:: getlogin_r
+.. index:: reentrant get user name
+.. index:: get user name, reentrant
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int getlogin_r(
+    char   \*name,
+    size_t  namesize
+    );
+
+**STATUS CODES:**
+
+*EINVAL*
+    The arguments were invalid.
+
+**DESCRIPTION:**
+
+This is a reentrant version of the ``getlogin()`` service.  The
+caller specified their own buffer, ``name``, as well as the
+length of this buffer, ``namesize``.
+
+**NOTES:**
+
+NONE
+
+getpgrp - Get Process Group ID
+------------------------------
+.. index:: getpgrp
+.. index:: get process group id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    pid_t getpgrp( void );
+
+**STATUS CODES:**
+
+The procress group Id is returned.
+
+**DESCRIPTION:**
+
+This service returns the current progress group Id.
+
+**NOTES:**
+
+This routine is implemented in a somewhat meaningful
+way for RTEMS but is truly not functional.
+
+setsid - Create Session and Set Process Group ID
+------------------------------------------------
+.. index:: setsid
+.. index:: create session and set process group id
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    pid_t setsid( void );
+
+**STATUS CODES:**
+
+*EPERM*
+    The application does not have permission to create a process group.
+
+**DESCRIPTION:**
+
+This routine always returns ``EPERM`` as RTEMS has no way
+to create new processes and thus no way to create a new process
+group.
+
+**NOTES:**
+
+NONE
+
+setpgid - Set Process Group ID for Job Control
+----------------------------------------------
+.. index:: setpgid
+.. index:: set process group id for job control
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int setpgid(
+    pid_t pid,
+    pid_t pgid
+    );
+
+**STATUS CODES:**
+
+*ENOSYS*
+    The routine is not implemented.
+
+**DESCRIPTION:**
+
+This service is not implemented for RTEMS as process groups are not
+supported.
+
+**NOTES:**
+
+NONE
+
+uname - Get System Name
+-----------------------
+.. index:: uname
+.. index:: get system name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int uname(
+    struct utsname \*name
+    );
+
+**STATUS CODES:**
+
+*EPERM*
+    The provided structure pointer is invalid.
+
+**DESCRIPTION:**
+
+This service returns system information to the caller.  It does this
+by filling in the ``struct utsname`` format structure for the
+caller.
+
+**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.
+
+times - Get process times
+-------------------------
+.. index:: times
+.. index:: get process times
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    #include <sys/time.h>
+    clock_t times(
+    struct tms \*ptms
+    );
+
+**STATUS CODES:**
+
+This routine returns the number of clock ticks that have elapsed
+since the system was initialized (e.g. the application was
+started).
+
+**DESCRIPTION:**
+
+``times`` stores the current process times in ``ptms``.  The
+format of ``struct tms`` is as defined in``<sys/times.h>``.  RTEMS fills in the field ``tms_utime``
+with the number of ticks that the calling thread has executed
+and the field ``tms_stime`` with the number of clock ticks
+since system boot (also returned).  All other fields in the``ptms`` are left zero.
+
+**NOTES:**
+
+RTEMS has no way to distinguish between user and system time
+so this routine returns the most meaningful information
+possible.
+
+getenv - Get Environment Variables
+----------------------------------
+.. index:: getenv
+.. index:: get environment variables
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    char \*getenv(
+    const char \*name
+    );
+
+**STATUS CODES:**
+
+*NULL*
+    when no match
+
+*pointer to value*
+    when successful
+
+**DESCRIPTION:**
+
+This service searches the set of environment variables for
+a string that matches the specified ``name``.  If found,
+it returns the associated value.
+
+**NOTES:**
+
+The environment list consists of name value pairs that
+are of the form *name = value*.
+
+setenv - Set Environment Variables
+----------------------------------
+.. index:: setenv
+.. index:: set environment variables
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int setenv(
+    const char \*name,
+    const char \*value,
+    int overwrite
+    );
+
+**STATUS CODES:**
+
+Returns 0 if successful and -1 otherwise.
+
+**DESCRIPTION:**
+
+This service adds the variable ``name`` to the environment with``value``.  If ``name`` is not already exist, then it is
+created.  If ``name`` exists and ``overwrite`` is zero, then
+the previous value is not overwritten.
+
+**NOTES:**
+
+NONE
+
+ctermid - Generate Terminal Pathname
+------------------------------------
+.. index:: ctermid
+.. index:: generate terminal pathname
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    char \*ctermid(
+    char \*s
+    );
+
+**STATUS CODES:**
+
+Returns a pointer to a string indicating the pathname for the controlling
+terminal.
+
+**DESCRIPTION:**
+
+This service returns the name of the terminal device associated with
+this process.  If ``s`` is NULL, then a pointer to a static buffer
+is returned.  Otherwise, ``s`` is assumed to have a buffer of
+sufficient size to contain the name of the controlling terminal.
+
+**NOTES:**
+
+By default on RTEMS systems, the controlling terminal is ``/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.
+
+ttyname - Determine Terminal Device Name
+----------------------------------------
+.. index:: ttyname
+.. index:: determine terminal device name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    char \*ttyname(
+    int fd
+    );
+
+**STATUS CODES:**
+
+Pointer to a string containing the terminal device name or
+NULL is returned on any error.
+
+**DESCRIPTION:**
+
+This service returns a pointer to the pathname of the terminal
+device that is open on the file descriptor ``fd``.  If``fd`` is not a valid descriptor for a terminal device,
+then NULL is returned.
+
+**NOTES:**
+
+This routine uses a static buffer.
+
+ttyname_r - Reentrant Determine Terminal Device Name
+----------------------------------------------------
+.. index:: ttyname_r
+.. index:: reentrant determine terminal device name
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int ttyname_r(
+    int   fd,
+    char \*name,
+    int   namesize
+    );
+
+**STATUS CODES:**
+
+This routine returns -1 and sets ``errno`` as follows:
+
+*EBADF*
+    If not a valid descriptor for a terminal device.
+
+*EINVAL*
+    If ``name`` is NULL or ``namesize`` are insufficient.
+
+**DESCRIPTION:**
+
+This service the pathname of the terminal device that is open
+on the file descriptor ``fd``.
+
+**NOTES:**
+
+NONE
+
+isatty - Determine if File Descriptor is Terminal
+-------------------------------------------------
+.. index:: isatty
+.. index:: determine if file descriptor is terminal
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    int isatty(
+    int fd
+    );
+
+**STATUS CODES:**
+
+Returns 1 if ``fd`` is a terminal device and 0 otherwise.
+
+**DESCRIPTION:**
+
+This service returns 1 if ``fd`` is an open file descriptor
+connected to a terminal and 0 otherwise.
+
+**NOTES:**
+
+sysconf - Get Configurable System Variables
+-------------------------------------------
+.. index:: sysconf
+.. index:: get configurable system variables
+
+**CALLING SEQUENCE:**
+
+.. code:: c
+
+    long sysconf(
+    int name
+    );
+
+**STATUS CODES:**
+
+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.
+
+**DESCRIPTION:**
+
+This service is the mechanism by which an application determines
+values for system limits or options at runtime.
+
+**NOTES:**
+
+Much of the information that may be obtained via ``sysconf``
+has equivalent macros in ``<unistd.h``.  However, those
+macros reflect conservative limits which may have been altered
+by application configuration.
+
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+
+.. COMMENT: All rights reserved.
+