4. Process Environment Manager

4.1. 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:

4.2. Background

4.2.1. 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.

4.2.2. 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.

4.2.3. 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.

4.3. Operations

4.3.1. 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.

4.3.2. Accessing Environment Variables

The value associated with an environment variable may be obtained using the getenv() service and set using the putenv() service.

4.4. 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.

4.4.1. getpid - Get Process ID

CALLING SEQUENCE:

int getpid( void );

STATUS CODES:

The process Id is returned.

DESCRIPTION:

This service returns the process Id.

NOTES:

NONE

4.4.2. getppid - Get Parent Process ID

CALLING SEQUENCE:

int getppid( void );

STATUS CODES:

The parent process Id is returned.

DESCRIPTION:

This service returns the parent process Id.

NOTES:

NONE

4.4.3. getuid - Get User ID

CALLING SEQUENCE:

int getuid( void );

STATUS CODES:

The effective user Id is returned.

DESCRIPTION:

This service returns the effective user Id.

NOTES:

NONE

4.4.4. geteuid - Get Effective User ID

CALLING SEQUENCE:

int geteuid( void );

STATUS CODES:

The effective group Id is returned.

DESCRIPTION:

This service returns the effective group Id.

NOTES:

NONE

4.4.5. getgid - Get Real Group ID

CALLING SEQUENCE:

int getgid( void );

STATUS CODES:

The group Id is returned.

DESCRIPTION:

This service returns the group Id.

NOTES:

NONE

4.4.6. getegid - Get Effective Group ID

CALLING SEQUENCE:

int getegid( void );

STATUS CODES:

The effective group Id is returned.

DESCRIPTION:

This service returns the effective group Id.

NOTES:

NONE

4.4.7. setuid - Set User ID

CALLING SEQUENCE:

int setuid(
    uid_t uid
);

STATUS CODES:

This service returns 0.

DESCRIPTION:

This service sets the user Id to uid.

NOTES:

NONE

4.4.8. setgid - Set Group ID

CALLING SEQUENCE:

int setgid(
    gid_t  gid
);

STATUS CODES:

This service returns 0.

DESCRIPTION:

This service sets the group Id to gid.

NOTES:

NONE

4.4.9. getgroups - Get Supplementary Group IDs

CALLING SEQUENCE:

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.

4.4.10. getlogin - Get User Name

CALLING SEQUENCE:

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.

4.4.11. getlogin_r - Reentrant Get User Name

CALLING SEQUENCE:

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

4.4.12. getpgrp - Get Process Group ID

CALLING SEQUENCE:

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.

4.4.13. getrusage - Get Resource Utilization

CALLING SEQUENCE:

int getrusage( int who, struct rusage *rusage );

STATUS CODES:

Returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error.

DESCRIPTION:

This function provides a measures of the resources being used by RTEMS. RTEMS is a single process environment so child process requests result in an error being returned.

A who value of RUSAGE_SELF results in the struct rusage field ru_utime returning the total active time of all threads that exist when the call is made and the field ru_stime returning the total idle time.

A who value of RUSAGE_THREAD results in the struct rusage field ru_utime returning the total active time of the current thread and the field ru_stime is set to 0.

NOTES:

The time returned can be more than the system up time if there is more than one CPU.

This routine is implemented using the internal thread iterator and accounts for time spent by the currently active threads. RTEMS does not account for the execution time of threads that are no longer running.

The idle time is the total time spent in IDLE since RTEMS started. The time for each CPU is summed.

The ratio of the difference between samples made by getrusage of the user and system idle time can be used to compute the current load.

4.4.14. setsid - Create Session and Set Process Group ID

CALLING SEQUENCE:

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

4.4.15. setpgid - Set Process Group ID for Job Control

CALLING SEQUENCE:

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

4.4.16. uname - Get System Name

CALLING SEQUENCE:

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.

4.4.17. times - Get process times

CALLING SEQUENCE:

#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.

4.4.18. getenv - Get Environment Variables

CALLING SEQUENCE:

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.

4.4.19. setenv - Set Environment Variables

CALLING SEQUENCE:

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

4.4.20. ctermid - Generate Terminal Pathname

CALLING SEQUENCE:

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.

4.4.21. ttyname - Determine Terminal Device Name

CALLING SEQUENCE:

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.

4.4.22. ttyname_r - Reentrant Determine Terminal Device Name

CALLING SEQUENCE:

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

4.4.23. isatty - Determine if File Descriptor is Terminal

CALLING SEQUENCE:

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:

4.4.24. sysconf - Get Configurable System Variables

CALLING SEQUENCE:

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.