diff options
author | Joel Sherrill <joel.sherrill@OARcorp.com> | 2002-06-28 19:14:44 +0000 |
---|---|---|
committer | Joel Sherrill <joel.sherrill@OARcorp.com> | 2002-06-28 19:14:44 +0000 |
commit | 0a535af128773487c42b1c416755c892a0914560 (patch) | |
tree | 7b834c51974368e4bd90c49ef07ac5c8c9da54ca /doc | |
parent | 2002-06-28 Joel Sherrill <joel@OARcorp.com> (diff) | |
download | rtems-0a535af128773487c42b1c416755c892a0914560.tar.bz2 |
2001-06-28 Joel Sherrill <joel@OARcorp.com>
* 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.
Diffstat (limited to '')
-rw-r--r-- | doc/posix_users/ChangeLog | 5 | ||||
-rw-r--r-- | doc/posix_users/preface.texi | 8 | ||||
-rw-r--r-- | doc/posix_users/procenv.t | 397 | ||||
-rw-r--r-- | doc/posix_users/process.t | 22 | ||||
-rw-r--r-- | doc/posix_users/signal.t | 61 | ||||
-rw-r--r-- | doc/posix_users/stamp-vti | 4 | ||||
-rw-r--r-- | doc/posix_users/version.texi | 4 |
7 files changed, 358 insertions, 143 deletions
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 <joel@OARcorp.com> + + * 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 <corsepiu@faw.uni-ulm.de> * 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 <sys/time.h> 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{<sys/times.h>}. 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{<unistd.h}. However, those +macros reflect conservative limits which may have been altered +by application configuration. diff --git a/doc/posix_users/process.t b/doc/posix_users/process.t index 4b23172a25..7bb4bb12ad 100644 --- a/doc/posix_users/process.t +++ b/doc/posix_users/process.t @@ -10,7 +10,10 @@ @section Introduction -The process creation and execution manager is ... +The process creation and execution manager provides the +functionality associated with the creation and termination +of processes. + The directives provided by the process creation and execution manager are: @@ -30,11 +33,24 @@ The directives provided by the process creation and execution manager are: @section Background -There is currently no text in this section. +POSIX process functionality can not be completely +supported by RTEMS. This is because RTEMS provides no memory +protection and implements a @i{single process, multi-threaded +execution model}. In this light, RTEMS provides none of the +routines that are associated with the creation of new processes. +However, since the entire RTEMS application (e.g. executable) +is logically a single POSIX process, RTEMS is able to provide +implementations of many operations on processes. The rule of +thumb is that those routines provide a meaningful result. +For example, @code{getpid()} returns the node number. @section Operations -There is currently no text in this section. +The only functionality method defined by this manager which is +supported by RTEMS is the @code{_exit} service. The +implementation of @code{_exit} shuts the application down and +is equivalent to invoking either @code{exit} or +@code{rtems_shutdown_executive}. @section Directives diff --git a/doc/posix_users/signal.t b/doc/posix_users/signal.t index c882c4d3f4..b56d325422 100644 --- a/doc/posix_users/signal.t +++ b/doc/posix_users/signal.t @@ -10,7 +10,9 @@ @section Introduction -The signal manager ... +The signal manager provides the functionality associated with +the generation, delivery, and management of process-oriented +signals. The directives provided by the signal manager are: @@ -37,12 +39,35 @@ The directives provided by the signal manager are: @section Background +@subsection Signals + +POSIX signals are an asynchronous event mechanism. Each process +and thread has a set of signals associated with it. Individual +signals may be enabled (e.g. unmasked) or blocked (e.g. ignored) +on both a per-thread and process level. Signals which are +enabled have a signal handler associated with them. When the +signal is generated and conditions are met, then the signal +handler is invoked in the proper process or thread context +asynchronous relative to the logical thread of execution. + +If a signal has been blocked when it is generated, then it +is queued and kept pending until the thread or process unblocks +the signal or explicitly checks for it. +Traditional, non-real-time POSIX signals do not queue. Thus +if a process or thread has blocked a particular signal, then +multiple occurrences of that signal are recorded as a +single occurrence of that signal. + +One can check for the set of outstanding signals that have been +blocked. Services are provided to check for outstanding process +or thread directed signals. + @subsection Signal Delivery -Signals directed at a thread are delivered to the specified thread. +Signals which are directed at a thread are delivered to the specified thread. -Signals directed at a process are delivered to a thread which is selected -based on the following algorithm: +Signals which are directed at a process are delivered to a thread which +is selected based on the following algorithm: @enumerate @item If the action for this signal is currently @code{SIG_IGN}, @@ -71,7 +96,29 @@ pending. The first thread to unblock the signal (@code{sigprocmask()} or @section Operations -There is currently no text in this section. +@subsection Signal Set Management + +Each process and each thread within that process has a set of +individual signals and handlers associated with it. Services +are provided to construct signal sets for the purposes of building +signal sets -- type @code{sigset_t} -- that are used to +provide arguments to the services that mask, unmask, and +check on pending signals. + +@subsection Blocking Until Signal Generation + +A thread may block until receipt of a signal. The "sigwait" +and "pause" families of services block until the requested +signal is received or if using @code{sigtimedwait()} until the specified +timeout period has elapsed. + +@subsection Sending a Signal + +This is accomplished +via one of a number of services that sends a signal to either a +process or thread. Signals may be directed at a process by +the service @code{kill()} or at a thread by the service +@code{pthread_kill()} @section Directives @@ -618,8 +665,8 @@ Signal interrupted this function. @subheading DESCRIPTION: -This function causes the calling thread to be blocked until the signal -is received. +This function causes the calling thread to be blocked until an +unblocked signal is received. @subheading NOTES: diff --git a/doc/posix_users/stamp-vti b/doc/posix_users/stamp-vti index 71b7aee620..c2e2d65fe2 100644 --- a/doc/posix_users/stamp-vti +++ b/doc/posix_users/stamp-vti @@ -1,4 +1,4 @@ @set UPDATED 17 January 2002 @set UPDATED-MONTH January 2002 -@set EDITION Snapshot -@set VERSION Snapshot +@set EDITION ss-20020528 +@set VERSION ss-20020528 diff --git a/doc/posix_users/version.texi b/doc/posix_users/version.texi index 71b7aee620..c2e2d65fe2 100644 --- a/doc/posix_users/version.texi +++ b/doc/posix_users/version.texi @@ -1,4 +1,4 @@ @set UPDATED 17 January 2002 @set UPDATED-MONTH January 2002 -@set EDITION Snapshot -@set VERSION Snapshot +@set EDITION ss-20020528 +@set VERSION ss-20020528 |