diff options
Diffstat (limited to 'posix_users/process_environment.rst')
| -rw-r--r-- | posix_users/process_environment.rst | 807 |
1 files changed, 0 insertions, 807 deletions
diff --git a/posix_users/process_environment.rst b/posix_users/process_environment.rst deleted file mode 100644 index 0556d12..0000000 --- a/posix_users/process_environment.rst +++ /dev/null @@ -1,807 +0,0 @@ -.. comment SPDX-License-Identifier: CC-BY-SA-4.0 - -.. 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 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 -: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. - -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: - -getpid - Get Process ID ------------------------ -.. index:: getpid -.. index:: get process id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int getpid( void ); - -**STATUS CODES:** - -The process Id is returned. - -**DESCRIPTION:** - -This service returns the process Id. - -**NOTES:** - -NONE - -.. _getppid: - -getppid - Get Parent Process ID -------------------------------- -.. index:: getppid -.. index:: get parent process id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int getppid( void ); - -**STATUS CODES:** - -The parent process Id is returned. - -**DESCRIPTION:** - -This service returns the parent process Id. - -**NOTES:** - -NONE - -.. _getuid: - -getuid - Get User ID --------------------- -.. index:: getuid -.. index:: get user id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int getuid( void ); - -**STATUS CODES:** - -The effective user Id is returned. - -**DESCRIPTION:** - -This service returns the effective user Id. - -**NOTES:** - -NONE - -.. _geteuid: - -geteuid - Get Effective User ID -------------------------------- -.. index:: geteuid -.. index:: get effective user id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int geteuid( void ); - -**STATUS CODES:** - -The effective group Id is returned. - -**DESCRIPTION:** - -This service returns the effective group Id. - -**NOTES:** - -NONE - -.. _getgid: - -getgid - Get Real Group ID --------------------------- -.. index:: getgid -.. index:: get real group id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int getgid( void ); - -**STATUS CODES:** - -The group Id is returned. - -**DESCRIPTION:** - -This service returns the group Id. - -**NOTES:** - -NONE - -.. _getegid: - -getegid - Get Effective Group ID --------------------------------- -.. index:: getegid -.. index:: get effective group id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int getegid( void ); - -**STATUS CODES:** - -The effective group Id is returned. - -**DESCRIPTION:** - -This service returns the effective group Id. - -**NOTES:** - -NONE - -.. _setuid: - -setuid - Set User ID --------------------- -.. index:: setuid -.. index:: set user id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int setuid( - uid_t uid - ); - -**STATUS CODES:** - -This service returns 0. - -**DESCRIPTION:** - -This service sets the user Id to ``uid``. - -**NOTES:** - -NONE - -.. _setgid: - -setgid - Set Group ID ---------------------- -.. index:: setgid -.. index:: set group id - -**CALLING SEQUENCE:** - -.. code-block:: c - - int setgid( - gid_t gid - ); - -**STATUS CODES:** - -This service returns 0. - -**DESCRIPTION:** - -This service sets the group Id to ``gid``. - -**NOTES:** - -NONE - -.. _getgroups: - -getgroups - Get Supplementary Group IDs ---------------------------------------- -.. index:: getgroups -.. index:: get supplementary group ids - -**CALLING SEQUENCE:** - -.. code-block:: 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: - -getlogin - Get User Name ------------------------- -.. index:: getlogin -.. index:: get user name - -**CALLING SEQUENCE:** - -.. code-block:: 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: - -getlogin_r - Reentrant Get User Name ------------------------------------- -.. index:: getlogin_r -.. index:: reentrant get user name -.. index:: get user name, reentrant - -**CALLING SEQUENCE:** - -.. code-block:: c - - int getlogin_r( - char *name, - size_t namesize - ); - -**STATUS CODES:** - -.. 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``. - -**NOTES:** - -NONE - -.. _getpgrp: - -getpgrp - Get Process Group ID ------------------------------- -.. index:: getpgrp -.. index:: get process group id - -**CALLING SEQUENCE:** - -.. code-block:: 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: - -setsid - Create Session and Set Process Group ID ------------------------------------------------- -.. index:: setsid -.. index:: create session and set process group id - -**CALLING SEQUENCE:** - -.. code-block:: c - - pid_t setsid( void ); - -**STATUS CODES:** - -.. 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. - -**NOTES:** - -NONE - -.. _setpgid: - -setpgid - Set Process Group ID for Job Control ----------------------------------------------- -.. index:: setpgid -.. index:: set process group id for job control - -**CALLING SEQUENCE:** - -.. code-block:: c - - int setpgid( - pid_t pid, - pid_t pgid - ); - -**STATUS CODES:** - -.. 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. - -**NOTES:** - -NONE - -.. _uname: - -uname - Get System Name ------------------------ -.. index:: uname -.. index:: get system name - -**CALLING SEQUENCE:** - -.. code-block:: c - - int uname( - struct utsname *name - ); - -**STATUS CODES:** - -.. 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. - -**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: - -times - Get process times -------------------------- -.. index:: times -.. index:: get process times - -**CALLING SEQUENCE:** - -.. code-block:: 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: - -getenv - Get Environment Variables ----------------------------------- -.. index:: getenv -.. index:: get environment variables - -**CALLING SEQUENCE:** - -.. code-block:: c - - char *getenv( - const char *name - ); - -**STATUS CODES:** - -.. list-table:: - :class: rtems-table - - * - ``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: - -setenv - Set Environment Variables ----------------------------------- -.. index:: setenv -.. index:: set environment variables - -**CALLING SEQUENCE:** - -.. code-block:: 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: - -ctermid - Generate Terminal Pathname ------------------------------------- -.. index:: ctermid -.. index:: generate terminal pathname - -**CALLING SEQUENCE:** - -.. code-block:: 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 :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 ----------------------------------------- -.. index:: ttyname -.. index:: determine terminal device name - -**CALLING SEQUENCE:** - -.. code-block:: 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: - -ttyname_r - Reentrant Determine Terminal Device Name ----------------------------------------------------- -.. index:: ttyname_r -.. index:: reentrant determine terminal device name - -**CALLING SEQUENCE:** - -.. code-block:: c - - int ttyname_r( - int fd, - char *name, - int namesize - ); - -**STATUS CODES:** - -This routine returns -1 and sets ``errno`` as follows: - -.. list-table:: - :class: rtems-table - - * - ``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: - -isatty - Determine if File Descriptor is Terminal -------------------------------------------------- -.. index:: isatty -.. index:: determine if file descriptor is terminal - -**CALLING SEQUENCE:** - -.. code-block:: 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: - -sysconf - Get Configurable System Variables -------------------------------------------- -.. index:: sysconf -.. index:: get configurable system variables - -**CALLING SEQUENCE:** - -.. code-block:: 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. |