From 0a535af128773487c42b1c416755c892a0914560 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 28 Jun 2002 19:14:44 +0000 Subject: 2001-06-28 Joel Sherrill * preface.texi, procenv.t, process.t, signal.t, stamp-vti, version.texi: Updated as part of starting a sweep on the POSIX User's Guide. --- doc/posix_users/ChangeLog | 5 + doc/posix_users/preface.texi | 8 +- doc/posix_users/procenv.t | 397 +++++++++++++++++++++++++++++-------------- doc/posix_users/process.t | 22 ++- doc/posix_users/signal.t | 61 ++++++- doc/posix_users/stamp-vti | 4 +- doc/posix_users/version.texi | 4 +- 7 files changed, 358 insertions(+), 143 deletions(-) (limited to 'doc') diff --git a/doc/posix_users/ChangeLog b/doc/posix_users/ChangeLog index adf1d1a42f..c8ceac2424 100644 --- a/doc/posix_users/ChangeLog +++ b/doc/posix_users/ChangeLog @@ -1,3 +1,8 @@ +2001-06-28 Joel Sherrill + + * preface.texi, procenv.t, process.t, signal.t, stamp-vti, + version.texi: Updated as part of starting a sweep on the POSIX + User's Guide. 2002-03-27 Ralf Corsepius * Makefile.am: Remove AUTOMAKE_OPTIONS. diff --git a/doc/posix_users/preface.texi b/doc/posix_users/preface.texi index 9fc063d90a..19933dcbaf 100644 --- a/doc/posix_users/preface.texi +++ b/doc/posix_users/preface.texi @@ -23,12 +23,14 @@ on the following standards: @item POSIX 1003.1h/D3. +@item Open Group Single UNIX Specification. + @end itemize Much of the POSIX API standard is actually implemented in the Cygnus Newlib ANSI C Library. Please refer to documentation on -Newlib for more information on what it supplies. +Newlib for more information on the functionality it supplies. -At this point, this is just beginning to become what it -ultimately should be. +This manual is still under construction and improvements +are welcomed from users. diff --git a/doc/posix_users/procenv.t b/doc/posix_users/procenv.t index d1af8ae672..db3f8936d8 100644 --- a/doc/posix_users/procenv.t +++ b/doc/posix_users/procenv.t @@ -10,7 +10,8 @@ @section Introduction -The process environment manager is ... +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: @@ -42,11 +43,67 @@ The directives provided by the process environment manager are: @section Background -There is currently no text in this section. +@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 -There is currently no text in this section. +@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 @@ -68,8 +125,7 @@ and status codes. @ifset is-C @example -int getpid( -); +int getpid( void ); @end example @end ifset @@ -78,16 +134,16 @@ int getpid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +The process Id is returned. @subheading DESCRIPTION: +This service returns the process Id. + @subheading NOTES: +NONE + @c @c @c @@ -101,8 +157,7 @@ The @ifset is-C @example -int getppid( -); +int getppid( void ); @end example @end ifset @@ -111,16 +166,16 @@ int getppid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +The parent process Id is returned. @subheading DESCRIPTION: +This service returns the parent process Id. + @subheading NOTES: +NONE + @c @c @c @@ -134,8 +189,7 @@ The @ifset is-C @example -int getuid( -); +int getuid( void ); @end example @end ifset @@ -144,16 +198,16 @@ int getuid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +The effective user Id is returned. @subheading DESCRIPTION: +This service returns the effective user Id. + @subheading NOTES: +NONE + @c @c @c @@ -167,8 +221,7 @@ The @ifset is-C @example -int geteuid( -); +int geteuid( void ); @end example @end ifset @@ -177,16 +230,16 @@ int geteuid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +The effective group Id is returned. @subheading DESCRIPTION: +This service returns the effective group Id. + @subheading NOTES: +NONE + @c @c @c @@ -200,8 +253,7 @@ The @ifset is-C @example -int getgid( -); +int getgid( void ); @end example @end ifset @@ -210,16 +262,16 @@ int getgid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +The group Id is returned. @subheading DESCRIPTION: +This service returns the group Id. + @subheading NOTES: +NONE + @c @c @c @@ -233,8 +285,7 @@ The @ifset is-C @example -int getegid( -); +int getegid( void ); @end example @end ifset @@ -243,16 +294,16 @@ int getegid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +The effective group Id is returned. @subheading DESCRIPTION: +This service returns the effective group Id. + @subheading NOTES: +NONE + @c @c @c @@ -267,6 +318,7 @@ The @ifset is-C @example int setuid( + uid_t uid ); @end example @end ifset @@ -276,16 +328,16 @@ int setuid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +This service returns 0. @subheading DESCRIPTION: +This service sets the user Id to @code{uid}. + @subheading NOTES: +NONE + @c @c @c @@ -300,6 +352,7 @@ The @ifset is-C @example int setgid( + gid_t gid ); @end example @end ifset @@ -309,16 +362,16 @@ int setgid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +This service returns 0. @subheading DESCRIPTION: +This service sets the group Id to @code{gid}. + @subheading NOTES: +NONE + @c @c @c @@ -333,6 +386,8 @@ The @ifset is-C @example int getgroups( + int gidsetsize, + gid_t grouplist[] ); @end example @end ifset @@ -342,16 +397,18 @@ int getgroups( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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 @@ -365,8 +422,7 @@ The @ifset is-C @example -int getlogin( -); +char *getlogin( void ); @end example @end ifset @@ -375,16 +431,18 @@ int getlogin( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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 @@ -393,12 +451,15 @@ The @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 @@ -409,15 +470,21 @@ int getlogin_r( @subheading STATUS CODES: @table @b -@item E -The +@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 @@ -431,8 +498,7 @@ The @ifset is-C @example -int getpgrp( -); +pid_t getpgrp( void ); @end example @end ifset @@ -441,16 +507,17 @@ int getpgrp( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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 @@ -464,8 +531,7 @@ The @ifset is-C @example -int setsid( -); +pid_t setsid( void ); @end example @end ifset @@ -475,15 +541,21 @@ int setsid( @subheading STATUS CODES: @table @b -@item E -The +@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 @@ -498,6 +570,8 @@ The @ifset is-C @example int setpgid( + pid_t pid, + pid_t pgid ); @end example @end ifset @@ -508,15 +582,20 @@ int setpgid( @subheading STATUS CODES: @table @b -@item E -The +@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 @@ -531,6 +610,7 @@ The @ifset is-C @example int uname( + struct utsname *name ); @end example @end ifset @@ -541,15 +621,24 @@ int uname( @subheading STATUS CODES: @table @b -@item E -The +@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 @@ -565,26 +654,31 @@ The #include clock_t times( - struct tms *buf + struct tms *ptms ); @end example @subheading STATUS CODES: -This routine returns the process times +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{buf}. - -@code{struct tms} is as defined in @code{/usr/include/sys/times.h} - -@code{times} returns the number of clock ticks that have elapsed -since the systm has been up. +@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: -NONE +RTEMS has no way to distinguish between user and system time +so this routine returns the most meaningful information +possible. @c @c @@ -599,7 +693,8 @@ NONE @ifset is-C @example -int getenv( +char *getenv( + const char *name ); @end example @end ifset @@ -610,15 +705,25 @@ int getenv( @subheading STATUS CODES: @table @b -@item E -The +@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 @@ -633,6 +738,9 @@ The @ifset is-C @example int setenv( + const char *name, + const char *value, + int overwrite ); @end example @end ifset @@ -642,16 +750,19 @@ int setenv( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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 @@ -665,7 +776,8 @@ The @ifset is-C @example -int ctermid( +char *ctermid( + char *s ); @end example @end ifset @@ -675,16 +787,24 @@ int ctermid( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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 @@ -698,7 +818,8 @@ The @ifset is-C @example -int ttyname( +char *ttyname( + int fd ); @end example @end ifset @@ -708,16 +829,20 @@ int ttyname( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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 @@ -732,6 +857,9 @@ The @ifset is-C @example int ttyname_r( + int fd, + char *name, + int namesize ); @end example @end ifset @@ -741,16 +869,26 @@ int ttyname_r( @subheading STATUS CODES: +This routine returns -1 and sets @code{errno} as follows: + @table @b -@item E -The +@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 @@ -765,6 +903,7 @@ The @ifset is-C @example int isatty( + int fd ); @end example @end ifset @@ -774,14 +913,13 @@ int isatty( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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 @@ -797,7 +935,8 @@ The @ifset is-C @example -int sysconf( +long sysconf( + int name ); @end example @end ifset @@ -807,13 +946,19 @@ int sysconf( @subheading STATUS CODES: -@table @b -@item E -The - -@end table +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. @subheading DESCRIPTION: +This service is the mechanism by which an application determines +values for system limits or options at runtime. + @subheading NOTES: +Much of the information that may be obtained via @code{sysconf} +has equivalent macros in @code{