From fa70fd20878e402610c263f129266593d31a0376 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 26 Feb 2016 18:22:07 +1100 Subject: POSIX User clean up. --- posix_users/process_environment.rst | 468 +++++++++++++++++++----------------- 1 file changed, 254 insertions(+), 214 deletions(-) (limited to 'posix_users/process_environment.rst') diff --git a/posix_users/process_environment.rst b/posix_users/process_environment.rst index 50c89b0..4d65d58 100644 --- a/posix_users/process_environment.rst +++ b/posix_users/process_environment.rst @@ -1,59 +1,63 @@ +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Process Environment Manager ########################### Introduction ============ -The process environment manager is responsible for providing the -functions related to user and group Id management. +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 +- getpid_ - Get Process ID -- ``getppid`` - Get Parent Process ID +- getppid_ - Get Parent Process ID -- ``getuid`` - Get User ID +- getuid_ - Get User ID -- ``geteuid`` - Get Effective User ID +- geteuid_ - Get Effective User ID -- ``getgid`` - Get Real Group ID +- getgid_ - Get Real Group ID -- ``getegid`` - Get Effective Group ID +- getegid_ - Get Effective Group ID -- ``setuid`` - Set User ID +- setuid_ - Set User ID -- ``setgid`` - Set Group ID +- setgid_ - Set Group ID -- ``getgroups`` - Get Supplementary Group IDs +- getgroups_ - Get Supplementary Group IDs -- ``getlogin`` - Get User Name +- getlogin_ - Get User Name -- ``getlogin_r`` - Reentrant Get User Name +- getlogin_r_ - Reentrant Get User Name -- ``getpgrp`` - Get Process Group ID +- getpgrp_ - Get Process Group ID -- ``setsid`` - Create Session and Set Process Group ID +- setsid_ - Create Session and Set Process Group ID -- ``setpgid`` - Set Process Group ID for Job Control +- setpgid_ - Set Process Group ID for Job Control -- ``uname`` - Get System Name +- uname_ - Get System Name -- ``times`` - Get Process Times +- times_ - Get Process Times -- ``getenv`` - Get Environment Variables +- getenv_ - Get Environment Variables -- ``setenv`` - Set Environment Variables +- setenv_ - Set Environment Variables -- ``ctermid`` - Generate Terminal Pathname +- ctermid_ - Generate Terminal Pathname -- ``ttyname`` - Determine Terminal Device Name +- ttyname_ - Determine Terminal Device Name -- ``ttyname_r`` - Reentrant Determine Terminal Device Name +- ttyname_r_ - Reentrant Determine Terminal Device Name -- ``isatty`` - Determine if File Descriptor is Terminal +- isatty_ - Determine if File Descriptor is Terminal -- ``sysconf`` - Get Configurable System Variables +- sysconf_ - Get Configurable System Variables Background ========== @@ -61,51 +65,45 @@ 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. +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. +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 +:file:`/etc/passwd` for user Id mapping and :file:`/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. +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 ========== @@ -113,24 +111,24 @@ 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. +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. +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. +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: getpid - Get Process ID ----------------------- @@ -139,7 +137,7 @@ getpid - Get Process ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int getpid( void ); @@ -155,6 +153,8 @@ This service returns the process Id. NONE +.. _getppid: + getppid - Get Parent Process ID ------------------------------- .. index:: getppid @@ -162,7 +162,7 @@ getppid - Get Parent Process ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int getppid( void ); @@ -178,6 +178,8 @@ This service returns the parent process Id. NONE +.. _getuid: + getuid - Get User ID -------------------- .. index:: getuid @@ -185,7 +187,7 @@ getuid - Get User ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int getuid( void ); @@ -201,6 +203,8 @@ This service returns the effective user Id. NONE +.. _geteuid: + geteuid - Get Effective User ID ------------------------------- .. index:: geteuid @@ -208,7 +212,7 @@ geteuid - Get Effective User ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int geteuid( void ); @@ -224,6 +228,8 @@ This service returns the effective group Id. NONE +.. _getgid: + getgid - Get Real Group ID -------------------------- .. index:: getgid @@ -231,7 +237,7 @@ getgid - Get Real Group ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int getgid( void ); @@ -247,6 +253,8 @@ This service returns the group Id. NONE +.. _getegid: + getegid - Get Effective Group ID -------------------------------- .. index:: getegid @@ -254,7 +262,7 @@ getegid - Get Effective Group ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int getegid( void ); @@ -270,6 +278,8 @@ This service returns the effective group Id. NONE +.. _setuid: + setuid - Set User ID -------------------- .. index:: setuid @@ -277,10 +287,10 @@ setuid - Set User ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int setuid( - uid_t uid + uid_t uid ); **STATUS CODES:** @@ -295,6 +305,8 @@ This service sets the user Id to ``uid``. NONE +.. _setgid: + setgid - Set Group ID --------------------- .. index:: setgid @@ -302,10 +314,10 @@ setgid - Set Group ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int setgid( - gid_t gid + gid_t gid ); **STATUS CODES:** @@ -320,6 +332,8 @@ This service sets the group Id to ``gid``. NONE +.. _getgroups: + getgroups - Get Supplementary Group IDs --------------------------------------- .. index:: getgroups @@ -327,11 +341,11 @@ getgroups - Get Supplementary Group IDs **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int getgroups( - int gidsetsize, - gid_t grouplist[] + int gidsetsize, + gid_t grouplist[] ); **STATUS CODES:** @@ -340,13 +354,13 @@ NA **DESCRIPTION:** -This service is not implemented as RTEMS has no notion of -supplemental groups. +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. +If supported, this routine would only be allowed for the super-user. + +.. _getlogin: getlogin - Get User Name ------------------------ @@ -355,14 +369,13 @@ getlogin - Get User Name **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c - char \*getlogin( void ); + char *getlogin( void ); **STATUS CODES:** -Returns a pointer to a string containing the name of the -current user. +Returns a pointer to a string containing the name of the current user. **DESCRIPTION:** @@ -370,7 +383,10 @@ 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. +This routine is not reentrant and subsequent calls to ``getlogin()`` will +overwrite the same buffer. + +.. _getlogin_r: getlogin_r - Reentrant Get User Name ------------------------------------ @@ -380,28 +396,33 @@ getlogin_r - Reentrant Get User Name **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int getlogin_r( - char \*name, - size_t namesize + char *name, + size_t namesize ); **STATUS CODES:** -*EINVAL* - The arguments were invalid. +.. list-table:: + :class: rtems-table + + * - ``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``. +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: + getpgrp - Get Process Group ID ------------------------------ .. index:: getpgrp @@ -409,7 +430,7 @@ getpgrp - Get Process Group ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c pid_t getpgrp( void ); @@ -423,8 +444,10 @@ 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. +This routine is implemented in a somewhat meaningful way for RTEMS but is truly +not functional. + +.. _setsid: setsid - Create Session and Set Process Group ID ------------------------------------------------ @@ -433,25 +456,29 @@ setsid - Create Session and Set Process Group ID **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c pid_t setsid( void ); **STATUS CODES:** -*EPERM* - The application does not have permission to create a process group. +.. list-table:: + :class: rtems-table + + * - ``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. +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: + setpgid - Set Process Group ID for Job Control ---------------------------------------------- .. index:: setpgid @@ -459,27 +486,31 @@ setpgid - Set Process Group ID for Job Control **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int setpgid( - pid_t pid, - pid_t pgid + pid_t pid, + pid_t pgid ); **STATUS CODES:** -*ENOSYS* - The routine is not implemented. +.. list-table:: + :class: rtems-table + + * - ``ENOSYS`` + - The routine is not implemented. **DESCRIPTION:** -This service is not implemented for RTEMS as process groups are not -supported. +This service is not implemented for RTEMS as process groups are not supported. **NOTES:** NONE +.. _uname: + uname - Get System Name ----------------------- .. index:: uname @@ -487,29 +518,33 @@ uname - Get System Name **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int uname( - struct utsname \*name + struct utsname \*name ); **STATUS CODES:** -*EPERM* - The provided structure pointer is invalid. +.. list-table:: + :class: rtems-table + + * - ``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. +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. +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: times - Get process times ------------------------- @@ -518,32 +553,32 @@ times - Get process times **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include clock_t times( - struct tms \*ptms + 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). +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````. 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. +``times`` stores the current process times in ``ptms``. The format of ``struct +tms`` is as defined in ````. 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. +RTEMS has no way to distinguish between user and system time so this routine +returns the most meaningful information possible. + +.. _getenv: getenv - Get Environment Variables ---------------------------------- @@ -552,30 +587,33 @@ getenv - Get Environment Variables **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c - char \*getenv( - const char \*name + char *getenv( + const char \*name ); **STATUS CODES:** -*NULL* - when no match +.. list-table:: + :class: rtems-table -*pointer to value* - when successful + * - ``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. +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*. +The environment list consists of name value pairs that are of the form ``name = +value``. + +.. _setenv: setenv - Set Environment Variables ---------------------------------- @@ -584,12 +622,12 @@ setenv - Set Environment Variables **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int setenv( - const char \*name, - const char \*value, - int overwrite + const char *name, + const char *value, + int overwrite ); **STATUS CODES:** @@ -598,14 +636,16 @@ 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. +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: + ctermid - Generate Terminal Pathname ------------------------------------ .. index:: ctermid @@ -613,10 +653,10 @@ ctermid - Generate Terminal Pathname **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c - char \*ctermid( - char \*s + char *ctermid( + char *s ); **STATUS CODES:** @@ -626,18 +666,19 @@ 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. +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. +By default on RTEMS systems, the controlling terminal is :file:`/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: ttyname - Determine Terminal Device Name ---------------------------------------- @@ -646,27 +687,29 @@ ttyname - Determine Terminal Device Name **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c - char \*ttyname( - int fd + char *ttyname( + int fd ); **STATUS CODES:** -Pointer to a string containing the terminal device name or -NULL is returned on any error. +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. +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: + ttyname_r - Reentrant Determine Terminal Device Name ---------------------------------------------------- .. index:: ttyname_r @@ -674,33 +717,37 @@ ttyname_r - Reentrant Determine Terminal Device Name **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int ttyname_r( - int fd, - char \*name, - int namesize + 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. +.. list-table:: + :class: rtems-table -*EINVAL* - If ``name`` is NULL or ``namesize`` are insufficient. + * - ``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``. +This service the pathname of the terminal device that is open on the file +descriptor ``fd``. **NOTES:** NONE +.. _isatty: + isatty - Determine if File Descriptor is Terminal ------------------------------------------------- .. index:: isatty @@ -708,10 +755,10 @@ isatty - Determine if File Descriptor is Terminal **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c int isatty( - int fd + int fd ); **STATUS CODES:** @@ -720,11 +767,13 @@ 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. +This service returns 1 if ``fd`` is an open file descriptor connected to a +terminal and 0 otherwise. **NOTES:** +.. _sysconf: + sysconf - Get Configurable System Variables ------------------------------------------- .. index:: sysconf @@ -732,34 +781,25 @@ sysconf - Get Configurable System Variables **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c long sysconf( - int name + 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. +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. +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 ``