Subversion Repositories or1k_old

@c

@c COPYRIGHT (c) 1988-2002.

@c On-Line Applications Research Corporation (OAR).

@c All rights reserved.

@c

@c procenv.t,v 1.7 2002/06/28 19:14:44 joel Exp

@c

@chapter Process Environment Manager

@section 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:

@itemize @bullet

@item @code{getpid} - Get Process ID

@item @code{getppid} - Get Parent Process ID

@item @code{getuid} - Get User ID

@item @code{geteuid} - Get Effective User ID

@item @code{getgid} - Get Real Group ID

@item @code{getegid} - Get Effective Group ID

@item @code{setuid} - Set User ID

@item @code{setgid} - Set Group ID

@item @code{getgroups} - Get Supplementary Group IDs

@item @code{getlogin} - Get User Name

@item @code{getlogin_r} - Reentrant Get User Name

@item @code{getpgrp} - Get Process Group ID

@item @code{setsid} - Create Session and Set Process Group ID

@item @code{setpgid} - Set Process Group ID for Job Control

@item @code{uname} - Get System Name

@item @code{times} - Get Process Times

@item @code{getenv} - Get Environment Variables

@item @code{setenv} - Set Environment Variables

@item @code{ctermid} - Generate Terminal Pathname

@item @code{ttyname} - Determine Terminal Device Name

@item @code{ttyname_r} - Reentrant Determine Terminal Device Name

@item @code{isatty} - Determine if File Descriptor is Terminal

@item @code{sysconf} - Get Configurable System Variables

@end itemize

@section Background

@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

@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

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.

@c

@c

@c

@page

@subsection getpid - Get Process ID

@findex getpid

@cindex  get process id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int getpid( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

The process Id is returned.

@subheading DESCRIPTION:

This service returns the process Id.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection getppid - Get Parent Process ID

@findex getppid

@cindex  get parent process id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int getppid( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

The parent process Id is returned.

@subheading DESCRIPTION:

This service returns the parent process Id.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection getuid - Get User ID

@findex getuid

@cindex  get user id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int getuid( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

The effective user Id is returned.

@subheading DESCRIPTION:

This service returns the effective user Id.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection geteuid - Get Effective User ID

@findex geteuid

@cindex  get effective user id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int geteuid( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

The effective group Id is returned.

@subheading DESCRIPTION:

This service returns the effective group Id.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection getgid - Get Real Group ID

@findex getgid

@cindex  get real group id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int getgid( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

The group Id is returned.

@subheading DESCRIPTION:

This service returns the group Id.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection getegid - Get Effective Group ID

@findex getegid

@cindex  get effective group id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int getegid( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

The effective group Id is returned.

@subheading DESCRIPTION:

This service returns the effective group Id.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection setuid - Set User ID

@findex setuid

@cindex  set user id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int setuid(

  uid_t uid

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

This service returns 0.

@subheading DESCRIPTION:

This service sets the user Id to @code{uid}.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection setgid - Set Group ID

@findex setgid

@cindex  set group id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int setgid(

  gid_t  gid

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

This service returns 0.

@subheading DESCRIPTION:

This service sets the group Id to @code{gid}.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection getgroups - Get Supplementary Group IDs

@findex getgroups

@cindex  get supplementary group ids

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int getgroups(

  int    gidsetsize,

  gid_t  grouplist[]

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

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

@page

@subsection getlogin - Get User Name

@findex getlogin

@cindex  get user name

@subheading CALLING SEQUENCE:

@ifset is-C

@example

char *getlogin( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

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

@page

@subsection getlogin_r - Reentrant Get User Name

@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

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

@table @b

@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

@page

@subsection getpgrp - Get Process Group ID

@findex getpgrp

@cindex  get process group id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

pid_t getpgrp( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

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

@page

@subsection setsid - Create Session and Set Process Group ID

@findex setsid

@cindex  create session and set process group id

@subheading CALLING SEQUENCE:

@ifset is-C

@example

pid_t setsid( void );

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

@table @b

@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

@page

@subsection setpgid - Set Process Group ID for Job Control

@findex setpgid

@cindex  set process group id for job control

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int setpgid(

  pid_t pid,

  pid_t pgid

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

@table @b

@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

@page

@subsection uname - Get System Name

@findex uname

@cindex  get system name

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int uname(

  struct utsname *name

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

@table @b

@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

@page

@subsection times - Get process times

@findex times

@cindex  get process times

@subheading CALLING SEQUENCE:

@example

#include 

clock_t times(

  struct tms *ptms

);

@end example

@subheading STATUS CODES:

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{ptms}.  The

format of @code{struct tms} is as defined in

@code{}.  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:

RTEMS has no way to distinguish between user and system time

so this routine returns the most meaningful information

possible.

@c

@c

@c

@page

@subsection getenv - Get Environment Variables

@findex getenv

@cindex  get environment variables

@subheading CALLING SEQUENCE:

@ifset is-C

@example

char *getenv(

  const char *name

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

@table @b

@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

@page

@subsection setenv - Set Environment Variables

@findex setenv

@cindex  set environment variables

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int setenv(

  const char *name,

  const char *value,

  int overwrite

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

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

@page

@subsection ctermid - Generate Terminal Pathname

@findex ctermid

@cindex  generate terminal pathname

@subheading CALLING SEQUENCE:

@ifset is-C

@example

char *ctermid(

  char *s

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

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

@page

@subsection ttyname - Determine Terminal Device Name

@findex ttyname

@cindex  determine terminal device name

@subheading CALLING SEQUENCE:

@ifset is-C

@example

char *ttyname(

  int fd

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

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

@page

@subsection ttyname_r - Reentrant Determine Terminal Device Name

@findex ttyname_r

@cindex  reentrant determine terminal device name

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int ttyname_r(

  int   fd,

  char *name,

  int   namesize

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

This routine returns -1 and sets @code{errno} as follows:

@table @b

@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

@page

@subsection isatty - Determine if File Descriptor is Terminal

@findex isatty

@cindex  determine if file descriptor is terminal

@subheading CALLING SEQUENCE:

@ifset is-C

@example

int isatty(

  int fd

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

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

@c

@c

@page

@subsection sysconf - Get Configurable System Variables

@findex sysconf

@cindex  get configurable system variables

@subheading CALLING SEQUENCE:

@ifset is-C

@example

long sysconf(

  int name