source: rtems/doc/posix_users/procenv.t @ 0a535af

4.104.114.84.95
Last change on this file since 0a535af was 0a535af, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 28, 2002 at 7:14:44 PM

2001-06-28 Joel Sherrill <joel@…>

  • 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.
  • Property mode set to 100644
File size: 17.0 KB
Line 
1@c
2@c COPYRIGHT (c) 1988-2002.
3@c On-Line Applications Research Corporation (OAR).
4@c All rights reserved.
5@c
6@c $Id$
7@c
8
9@chapter Process Environment Manager
10
11@section Introduction
12
13The process environment manager is responsible for providing the
14functions related to user and group Id management.
15
16The directives provided by the process environment manager are:
17
18@itemize @bullet
19@item @code{getpid} - Get Process ID
20@item @code{getppid} - Get Parent Process ID
21@item @code{getuid} - Get User ID
22@item @code{geteuid} - Get Effective User ID
23@item @code{getgid} - Get Real Group ID
24@item @code{getegid} - Get Effective Group ID
25@item @code{setuid} - Set User ID
26@item @code{setgid} - Set Group ID
27@item @code{getgroups} - Get Supplementary Group IDs
28@item @code{getlogin} - Get User Name
29@item @code{getlogin_r} - Reentrant Get User Name
30@item @code{getpgrp} - Get Process Group ID
31@item @code{setsid} - Create Session and Set Process Group ID
32@item @code{setpgid} - Set Process Group ID for Job Control
33@item @code{uname} - Get System Name
34@item @code{times} - Get Process Times
35@item @code{getenv} - Get Environment Variables
36@item @code{setenv} - Set Environment Variables
37@item @code{ctermid} - Generate Terminal Pathname
38@item @code{ttyname} - Determine Terminal Device Name
39@item @code{ttyname_r} - Reentrant Determine Terminal Device Name
40@item @code{isatty} - Determine if File Descriptor is Terminal
41@item @code{sysconf} - Get Configurable System Variables
42@end itemize
43
44@section Background
45
46@subsection Users and Groups
47
48RTEMS provides a single process, multi-threaded execution environment.
49In this light, the notion of user and group is somewhat without meaning.
50But RTEMS does provide services to provide a synthetic version of
51user and group.  By default, a single user and group is associated
52with the application.  Thus unless special actions are taken,
53every thread in the application shares the same user and group Id.
54The initial rationale for providing user and group Id functionality
55in RTEMS was for the filesystem infrastructure to implement
56file permission checks.  The effective user/group Id capability
57has since been used to implement permissions checking by
58the @code{ftpd} server.
59
60In addition to the "real" user and group Ids, a process may
61have an effective user/group Id.  This allows a process to
62function using a more limited permission set for certain operations.
63
64@subsection User and Group Names
65
66POSIX considers user and group Ids to be a unique integer that
67may be associated with a name.  This is usually accomplished
68via a file named @code{/etc/passwd} for user Id mapping and
69@code{/etc/groups} for group Id mapping.  Again, although
70RTEMS is effectively a single process and thus single user
71system, it provides limited support for user and group
72names.  When configured with an appropriate filesystem, RTEMS
73will access the appropriate files to map user and group Ids
74to names.
75
76If these files do not exist, then RTEMS will synthesize
77a minimal version so this family of services return without
78error.  It is important to remember that a design goal of
79the RTEMS POSIX services is to provide useable and
80meaningful results even though a full process model
81is not available.
82
83@subsection Environment Variables
84
85POSIX allows for variables in the run-time environment.  These are
86name/value pairs that make be dynamically set and obtained by
87programs.  In a full POSIX environment with command line shell
88and multiple processes,  environment variables may be set in
89one process -- such as the shell -- and inherited by child
90processes.  In RTEMS, there is only one process and thus
91only one set of environment variables across all processes.
92
93
94@section Operations
95
96@subsection Accessing User and Group Ids
97
98The user Id associated with the current thread may be obtain
99using the @code{getuid()} service.  Similarly, the group Id
100may be obtained using the @code{getgid()} service. 
101
102@subsection Accessing Environment Variables
103
104The value associated with an environment variable may be
105obtained using the @code{getenv()} service and set using
106the @code{putenv()} service.
107
108@section Directives
109
110This section details the process environment manager's directives.
111A subsection is dedicated to each of this manager's directives
112and describes the calling sequence, related constants, usage,
113and status codes.
114
115@c
116@c
117@c
118@page
119@subsection getpid - Get Process ID
120
121@findex getpid
122@cindex  get process id
123
124@subheading CALLING SEQUENCE:
125
126@ifset is-C
127@example
128int getpid( void );
129@end example
130@end ifset
131
132@ifset is-Ada
133@end ifset
134
135@subheading STATUS CODES:
136
137The process Id is returned.
138
139@subheading DESCRIPTION:
140
141This service returns the process Id.
142
143@subheading NOTES:
144
145NONE
146
147@c
148@c
149@c
150@page
151@subsection getppid - Get Parent Process ID
152
153@findex getppid
154@cindex  get parent process id
155
156@subheading CALLING SEQUENCE:
157
158@ifset is-C
159@example
160int getppid( void );
161@end example
162@end ifset
163
164@ifset is-Ada
165@end ifset
166
167@subheading STATUS CODES:
168
169The parent process Id is returned.
170
171@subheading DESCRIPTION:
172
173This service returns the parent process Id.
174
175@subheading NOTES:
176
177NONE
178
179@c
180@c
181@c
182@page
183@subsection getuid - Get User ID
184
185@findex getuid
186@cindex  get user id
187
188@subheading CALLING SEQUENCE:
189
190@ifset is-C
191@example
192int getuid( void );
193@end example
194@end ifset
195
196@ifset is-Ada
197@end ifset
198
199@subheading STATUS CODES:
200
201The effective user Id is returned.
202
203@subheading DESCRIPTION:
204
205This service returns the effective user Id.
206
207@subheading NOTES:
208
209NONE
210
211@c
212@c
213@c
214@page
215@subsection geteuid - Get Effective User ID
216
217@findex geteuid
218@cindex  get effective user id
219
220@subheading CALLING SEQUENCE:
221
222@ifset is-C
223@example
224int geteuid( void );
225@end example
226@end ifset
227
228@ifset is-Ada
229@end ifset
230
231@subheading STATUS CODES:
232
233The effective group Id is returned.
234
235@subheading DESCRIPTION:
236
237This service returns the effective group Id.
238
239@subheading NOTES:
240
241NONE
242
243@c
244@c
245@c
246@page
247@subsection getgid - Get Real Group ID
248
249@findex getgid
250@cindex  get real group id
251
252@subheading CALLING SEQUENCE:
253
254@ifset is-C
255@example
256int getgid( void );
257@end example
258@end ifset
259
260@ifset is-Ada
261@end ifset
262
263@subheading STATUS CODES:
264
265The group Id is returned.
266
267@subheading DESCRIPTION:
268
269This service returns the group Id.
270
271@subheading NOTES:
272
273NONE
274
275@c
276@c
277@c
278@page
279@subsection getegid - Get Effective Group ID
280
281@findex getegid
282@cindex  get effective group id
283
284@subheading CALLING SEQUENCE:
285
286@ifset is-C
287@example
288int getegid( void );
289@end example
290@end ifset
291
292@ifset is-Ada
293@end ifset
294
295@subheading STATUS CODES:
296
297The effective group Id is returned.
298
299@subheading DESCRIPTION:
300
301This service returns the effective group Id.
302
303@subheading NOTES:
304
305NONE
306
307@c
308@c
309@c
310@page
311@subsection setuid - Set User ID
312
313@findex setuid
314@cindex  set user id
315
316@subheading CALLING SEQUENCE:
317
318@ifset is-C
319@example
320int setuid(
321  uid_t uid
322);
323@end example
324@end ifset
325
326@ifset is-Ada
327@end ifset
328
329@subheading STATUS CODES:
330
331This service returns 0.
332
333@subheading DESCRIPTION:
334
335This service sets the user Id to @code{uid}.
336
337@subheading NOTES:
338
339NONE
340
341@c
342@c
343@c
344@page
345@subsection setgid - Set Group ID
346
347@findex setgid
348@cindex  set group id
349
350@subheading CALLING SEQUENCE:
351
352@ifset is-C
353@example
354int setgid(
355  gid_t  gid
356);
357@end example
358@end ifset
359
360@ifset is-Ada
361@end ifset
362
363@subheading STATUS CODES:
364
365This service returns 0.
366
367@subheading DESCRIPTION:
368
369This service sets the group Id to @code{gid}.
370
371@subheading NOTES:
372
373NONE
374
375@c
376@c
377@c
378@page
379@subsection getgroups - Get Supplementary Group IDs
380
381@findex getgroups
382@cindex  get supplementary group ids
383
384@subheading CALLING SEQUENCE:
385
386@ifset is-C
387@example
388int getgroups(
389  int    gidsetsize,
390  gid_t  grouplist[]
391);
392@end example
393@end ifset
394
395@ifset is-Ada
396@end ifset
397
398@subheading STATUS CODES:
399
400NA
401
402@subheading DESCRIPTION:
403
404This service is not implemented as RTEMS has no notion of
405supplemental groups.
406
407@subheading NOTES:
408
409If supported, this routine would only be allowed for
410the super-user.
411
412@c
413@c
414@c
415@page
416@subsection getlogin - Get User Name
417
418@findex getlogin
419@cindex  get user name
420
421@subheading CALLING SEQUENCE:
422
423@ifset is-C
424@example
425char *getlogin( void );
426@end example
427@end ifset
428
429@ifset is-Ada
430@end ifset
431
432@subheading STATUS CODES:
433
434Returns a pointer to a string containing the name of the
435current user.
436
437@subheading DESCRIPTION:
438
439This routine returns the name of the current user.
440
441@subheading NOTES:
442
443This routine is not reentrant and subsequent calls to
444@code{getlogin()} will overwrite the same buffer.
445
446@c
447@c
448@c
449@page
450@subsection getlogin_r - Reentrant Get User Name
451
452@findex getlogin_r
453@cindex  reentrant get user name
454@cindex  get user name, reentrant
455
456@subheading CALLING SEQUENCE:
457
458@ifset is-C
459@example
460int getlogin_r(
461  char   *name,
462  size_t  namesize 
463);
464@end example
465@end ifset
466
467@ifset is-Ada
468@end ifset
469
470@subheading STATUS CODES:
471
472@table @b
473@item EINVAL
474The arguments were invalid.
475
476@end table
477
478@subheading DESCRIPTION:
479
480This is a reentrant version of the @code{getlogin()} service.  The
481caller specified their own buffer, @code{name}, as well as the
482length of this buffer, @code{namesize}.
483
484@subheading NOTES:
485
486NONE
487
488@c
489@c
490@c
491@page
492@subsection getpgrp - Get Process Group ID
493
494@findex getpgrp
495@cindex  get process group id
496
497@subheading CALLING SEQUENCE:
498
499@ifset is-C
500@example
501pid_t getpgrp( void );
502@end example
503@end ifset
504
505@ifset is-Ada
506@end ifset
507
508@subheading STATUS CODES:
509
510The procress group Id is returned.
511
512@subheading DESCRIPTION:
513
514This service returns the current progress group Id.
515
516@subheading NOTES:
517
518This routine is implemented in a somewhat meaningful
519way for RTEMS but is truly not functional.
520
521@c
522@c
523@c
524@page
525@subsection setsid - Create Session and Set Process Group ID
526
527@findex setsid
528@cindex  create session and set process group id
529
530@subheading CALLING SEQUENCE:
531
532@ifset is-C
533@example
534pid_t setsid( void );
535@end example
536@end ifset
537
538@ifset is-Ada
539@end ifset
540
541@subheading STATUS CODES:
542
543@table @b
544@item EPERM
545The application does not have permission to create a process group.
546
547@end table
548
549@subheading DESCRIPTION:
550
551This routine always returns @code{EPERM} as RTEMS has no way
552to create new processes and thus no way to create a new process
553group.
554
555@subheading NOTES:
556
557NONE
558
559@c
560@c
561@c
562@page
563@subsection setpgid - Set Process Group ID for Job Control
564
565@findex setpgid
566@cindex  set process group id for job control
567
568@subheading CALLING SEQUENCE:
569
570@ifset is-C
571@example
572int setpgid(
573  pid_t pid,
574  pid_t pgid
575);
576@end example
577@end ifset
578
579@ifset is-Ada
580@end ifset
581
582@subheading STATUS CODES:
583
584@table @b
585@item ENOSYS
586The routine is not implemented.
587
588@end table
589
590@subheading DESCRIPTION:
591
592This service is not implemented for RTEMS as process groups are not
593supported.
594
595@subheading NOTES:
596
597NONE
598
599@c
600@c
601@c
602@page
603@subsection uname - Get System Name
604
605@findex uname
606@cindex  get system name
607
608@subheading CALLING SEQUENCE:
609
610@ifset is-C
611@example
612int uname(
613  struct utsname *name
614);
615@end example
616@end ifset
617
618@ifset is-Ada
619@end ifset
620
621@subheading STATUS CODES:
622
623@table @b
624@item EPERM
625The provided structure pointer is invalid.
626
627@end table
628
629@subheading DESCRIPTION:
630
631This service returns system information to the caller.  It does this
632by filling in the @code{struct utsname} format structure for the
633caller.
634
635@subheading NOTES:
636
637The information provided includes the operating system (RTEMS in
638all configurations), the node number, the release as the RTEMS
639version, and the CPU family and model.  The CPU model name
640will indicate the multilib executive variant being used.
641
642@c
643@c
644@c
645@page
646@subsection times - Get process times
647
648@findex times
649@cindex  get process times
650
651@subheading CALLING SEQUENCE:
652
653@example
654#include <sys/time.h>
655
656clock_t times(
657  struct tms *ptms
658);
659@end example
660
661@subheading STATUS CODES:
662
663This routine returns the number of clock ticks that have elapsed
664since the system was initialized (e.g. the application was
665started).
666
667@subheading DESCRIPTION:
668
669@code{times} stores the current process times in @code{ptms}.  The
670format of @code{struct tms} is as defined in
671@code{<sys/times.h>}.  RTEMS fills in the field @code{tms_utime}
672with the number of ticks that the calling thread has executed
673and the field @code{tms_stime} with the number of clock ticks
674since system boot (also returned).  All other fields in the
675@code{ptms} are left zero.
676
677@subheading NOTES:
678
679RTEMS has no way to distinguish between user and system time
680so this routine returns the most meaningful information
681possible.
682
683@c
684@c
685@c
686@page
687@subsection getenv - Get Environment Variables
688
689@findex getenv
690@cindex  get environment variables
691
692@subheading CALLING SEQUENCE:
693
694@ifset is-C
695@example
696char *getenv(
697  const char *name
698);
699@end example
700@end ifset
701
702@ifset is-Ada
703@end ifset
704
705@subheading STATUS CODES:
706
707@table @b
708@item NULL
709when no match
710
711@item pointer to value
712when successful
713
714@end table
715
716@subheading DESCRIPTION:
717
718This service searches the set of environment variables for
719a string that matches the specified @code{name}.  If found,
720it returns the associated value.
721
722@subheading NOTES:
723
724The environment list consists of name value pairs that
725are of the form @i{name = value}.
726
727@c
728@c
729@c
730@page
731@subsection setenv - Set Environment Variables
732
733@findex setenv
734@cindex  set environment variables
735
736@subheading CALLING SEQUENCE:
737
738@ifset is-C
739@example
740int setenv(
741  const char *name,
742  const char *value,
743  int overwrite
744);
745@end example
746@end ifset
747
748@ifset is-Ada
749@end ifset
750
751@subheading STATUS CODES:
752
753Returns 0 if successful and -1 otherwise.
754
755@subheading DESCRIPTION:
756
757This service adds the variable @code{name} to the environment with
758@code{value}.  If @code{name} is not already exist, then it is
759created.  If @code{name} exists and @code{overwrite} is zero, then
760the previous value is not overwritten.
761
762@subheading NOTES:
763
764NONE
765
766@c
767@c
768@c
769@page
770@subsection ctermid - Generate Terminal Pathname
771
772@findex ctermid
773@cindex  generate terminal pathname
774
775@subheading CALLING SEQUENCE:
776
777@ifset is-C
778@example
779char *ctermid(
780  char *s
781);
782@end example
783@end ifset
784
785@ifset is-Ada
786@end ifset
787
788@subheading STATUS CODES:
789
790Returns a pointer to a string indicating the pathname for the controlling
791terminal.
792
793@subheading DESCRIPTION:
794
795This service returns the name of the terminal device associated with
796this process.  If @code{s} is NULL, then a pointer to a static buffer
797is returned.  Otherwise, @code{s} is assumed to have a buffer of
798sufficient size to contain the name of the controlling terminal.
799
800@subheading NOTES:
801
802By default on RTEMS systems, the controlling terminal is @code{/dev/console}.
803Again this implementation is of limited meaning, but it provides
804true and useful results which should be sufficient to ease porting
805applications from a full POSIX implementation to the reduced
806profile supported by RTEMS.
807
808@c
809@c
810@c
811@page
812@subsection ttyname - Determine Terminal Device Name
813
814@findex ttyname
815@cindex  determine terminal device name
816
817@subheading CALLING SEQUENCE:
818
819@ifset is-C
820@example
821char *ttyname(
822  int fd
823);
824@end example
825@end ifset
826
827@ifset is-Ada
828@end ifset
829
830@subheading STATUS CODES:
831
832Pointer to a string containing the terminal device name or
833NULL is returned on any error.
834
835@subheading DESCRIPTION:
836
837This service returns a pointer to the pathname of the terminal
838device that is open on the file descriptor @code{fd}.  If
839@code{fd} is not a valid descriptor for a terminal device,
840then NULL is returned.
841
842@subheading NOTES:
843
844This routine uses a static buffer.
845
846@c
847@c
848@c
849@page
850@subsection ttyname_r - Reentrant Determine Terminal Device Name
851
852@findex ttyname_r
853@cindex  reentrant determine terminal device name
854
855@subheading CALLING SEQUENCE:
856
857@ifset is-C
858@example
859int ttyname_r(
860  int   fd,
861  char *name,
862  int   namesize
863);
864@end example
865@end ifset
866
867@ifset is-Ada
868@end ifset
869
870@subheading STATUS CODES:
871
872This routine returns -1 and sets @code{errno} as follows:
873
874@table @b
875@item EBADF
876If not a valid descriptor for a terminal device.
877
878@item EINVAL
879If @code{name} is NULL or @code{namesize} are insufficient.
880
881@end table
882
883@subheading DESCRIPTION:
884
885This service the pathname of the terminal device that is open
886on the file descriptor @code{fd}. 
887
888@subheading NOTES:
889
890NONE
891
892@c
893@c
894@c
895@page
896@subsection isatty - Determine if File Descriptor is Terminal
897
898@findex isatty
899@cindex  determine if file descriptor is terminal
900
901@subheading CALLING SEQUENCE:
902
903@ifset is-C
904@example
905int isatty(
906  int fd
907);
908@end example
909@end ifset
910
911@ifset is-Ada
912@end ifset
913
914@subheading STATUS CODES:
915
916Returns 1 if @code{fd} is a terminal device and 0 otherwise.
917
918@subheading DESCRIPTION:
919
920This service returns 1 if @code{fd} is an open file descriptor
921connected to a terminal and 0 otherwise.
922
923@subheading NOTES:
924
925@c
926@c
927@c
928@page
929@subsection sysconf - Get Configurable System Variables
930
931@findex sysconf
932@cindex  get configurable system variables
933
934@subheading CALLING SEQUENCE:
935
936@ifset is-C
937@example
938long sysconf(
939  int name
940);
941@end example
942@end ifset
943
944@ifset is-Ada
945@end ifset
946
947@subheading STATUS CODES:
948
949The value returned is the actual value of the system resource.
950If the requested configuration name is a feature flag, then
9511 is returned if the available and 0 if it is not.  On any
952other error condition, -1 is returned.
953
954@subheading DESCRIPTION:
955
956This service is the mechanism by which an application determines
957values for system limits or options at runtime.
958
959@subheading NOTES:
960
961Much of the information that may be obtained via @code{sysconf}
962has equivalent macros in @code{<unistd.h}.  However, those
963macros reflect conservative limits which may have been altered
964by application configuration.
Note: See TracBrowser for help on using the repository browser.