Fix cross refs.
[kopensolaris-gnu/glibc.git] / manual / users.texi
1 @node Users and Groups, System Information, Job Control, Top
2 @chapter Users and Groups
3
4 Every user who can log in on the system is identified by a unique number
5 called the @dfn{user ID}.  Each process has an effective user ID which
6 says which user's access permissions it has.
7
8 Users are classified into @dfn{groups} for access control purposes.  Each
9 process has one or more @dfn{group ID values} which say which groups the
10 process can use for access to files.
11
12 The effective user and group IDs of a process collectively form its
13 @dfn{persona}.  This determines which files the process can access.
14 Normally, a process inherits its persona from the parent process, but
15 under special circumstances a process can change its persona and thus
16 change its access permissions.
17
18 Each file in the system also has a user ID and a group ID.  Access
19 control works by comparing the user and group IDs of the file with those
20 of the running process.
21
22 The system keeps a database of all the registered users, and another
23 database of all the defined groups.  There are library functions you
24 can use to examine these databases.
25
26 @menu
27 * User and Group IDs::          Each user has a unique numeric ID;
28                                  likewise for groups.
29 * Process Persona::             The user IDs and group IDs of a process.
30 * Why Change Persona::          Why a program might need to change
31                                  its user and/or group IDs.
32 * How Change Persona::          Changing the user and group IDs.
33 * Reading Persona::             How to examine the user and group IDs.
34
35 * Setting User ID::             Functions for setting the user ID.
36 * Setting Groups::              Functions for setting the group IDs.
37
38 * Enable/Disable Setuid::       Turning setuid access on and off.
39 * Setuid Program Example::      The pertinent parts of one sample program.
40 * Tips for Setuid::             How to avoid granting unlimited access.
41
42 * Who Logged In::               Getting the name of the user who logged in,
43                                  or of the real user ID of the current process.
44
45 * User Database::               Functions and data structures for
46                                  accessing the user database.
47 * Group Database::              Functions and data structures for
48                                  accessing the group database.
49 * Database Example::            Example program showing use of database
50                                  inquiry functions.
51 @end menu
52
53 @node User and Group IDs
54 @section User and Group IDs
55
56 @cindex login name
57 @cindex user name
58 @cindex user ID
59 Each user account on a computer system is identified by a @dfn{user
60 name} (or @dfn{login name}) and @dfn{user ID}.  Normally, each user name
61 has a unique user ID, but it is possible for several login names to have
62 the same user ID.  The user names and corresponding user IDs are stored
63 in a data base which you can access as described in @ref{User Database}.
64
65 @cindex group name
66 @cindex group ID
67 Users are classified in @dfn{groups}.  Each user name also belongs to
68 one or more groups, and has one @dfn{default group}.  Users who are
69 members of the same group can share resources (such as files) that are
70 not accessible to users who are not a member of that group.  Each group
71 has a @dfn{group name} and @dfn{group ID}.  @xref{Group Database},
72 for how to find information about a group ID or group name.
73
74 @node Process Persona
75 @section The Persona of a Process
76 @cindex persona
77 @cindex effective user ID
78 @cindex effective group ID
79
80 At any time, each process has a single user ID and a group ID which
81 determine the privileges of the process.  These are collectively called
82 the @dfn{persona} of the process, because they determine ``who it is''
83 for purposes of access control.  These IDs are also called the
84 @dfn{effective user ID} and @dfn{effective group ID} of the process.
85
86 Your login shell starts out with a persona which consists of your user
87 ID and your default group ID.  In normal circumstances. all your other
88 processes inherit these values.
89
90 @cindex real user ID
91 @cindex real group ID
92 A process also has a @dfn{real user ID} which identifies the user who
93 created the process, and a @dfn{real group ID} which identifies that
94 user's default group.  These values do not play a role in access
95 control, so we do not consider them part of the persona.  But they are
96 also important.
97
98 Both the real and effective user ID can be changed during the lifetime
99 of a process.  @xref{Why Change Persona}.
100
101 @cindex supplementary group IDs
102 In addition, a user can belong to multiple groups, so the persona
103 includes have @dfn{supplementary group IDs} that also contribute to
104 access permission.
105
106 For details on how a process's effective user IDs and group IDs affect
107 its permission to access files, see @ref{Access Permission}.
108
109 The user ID of a process also controls permissions for sending signals
110 using the @code{kill} function.  @xref{Signaling Another Process}.
111
112 @node Why Change Persona
113 @section Why Change the Persona of a Process?
114
115 The most obvious situation where it is necessary for a process to change
116 its user and/or group IDs is the @code{login} program.  When
117 @code{login} starts running, its user ID is @code{root}.  Its job is to
118 start a shell whose user and group IDs are those of the user who is
119 logging in.  (To accomplish this fully, @code{login} must set the real
120 user and group IDs as well as its persona.  But this is a special case.)
121
122 The more common case of changing persona is when an ordinary user
123 programs needs access to a resource that wouldn't ordinarily be
124 accessible to the user actually running it.
125
126 For example, you may have a file that is controlled by your program but
127 that shouldn't be read or modified directly by other users, either
128 because it implements some kind of locking protocol, or because you want
129 to preserve the integrity or privacy of the information it contains.
130 This kind of restricted access can be implemented by having the program
131 change its effective user or group ID to match that of the resource.
132
133 Thus, imagine a game program that saves scores in a file.  The game
134 program itself needs to be able to update this file no matter who is
135 running it, but if users can write the file without going through the
136 game, they can give themselves any scores they like.  Some people
137 consider this undesirable, or even reprehensible.  It can be prevented
138 by creating a new user ID and login name (say, @code{games}) to own the
139 scores file, and make the file writable only by this user.  Then, when
140 the game program wants to update this file, it can change its effective
141 user ID to be that for @code{games}.  In effect, the program must
142 adopt the persona of @code{games} so it can write the scores file.
143
144 @node How Change Persona
145 @section How an Application can Change Persona
146 @cindex @code{setuid} programs
147
148 The ability to change the persona of a process can be a source of
149 unintentional privacy violations, or even intentional abuse.  Because of
150 the potential for problems, changing persona is restricted to special
151 circumstances.
152
153 You can't arbitrarily set your user ID or group ID to anything you want;
154 only privileged processes can do that.  Instead, the normal way for a
155 program to change its persona is that it has been set up in advance to
156 change to a particular user or group.  This is the function of the suid
157 and sgid bits of a file's access mode.
158
159 When the suid bit of an executable file is set, executing that file
160 automatically changes the effective user ID to the user that owns the
161 file.  Likewise, executing a file whose sgid bit is set changes the
162 effective group ID to the group of the file.  @xref{Executing a File}.
163 Creating a file that changes to a particular user or group ID thus
164 requires full access to that user or group ID.
165
166 @xref{File Attributes}, for a more general discussion of file modes and
167 accessibility.
168
169 A process can always change its effective user (or group) ID back to its
170 real ID.  Programs do this so as to turn off their special privileges
171 when they are not needed, which makes for more robustness.
172
173 @node Reading Persona
174 @section Reading the Persona of a Process
175
176 Here are detailed descriptions of the functions for reading the user and
177 group IDs of a process, both real and effective.  To use these
178 facilities, you must include the header files @file{sys/types.h} and
179 @file{unistd.h}.
180 @pindex unistd.h
181 @pindex sys/types.h
182
183 @comment sys/types.h
184 @comment POSIX.1
185 @deftp {Data Type} uid_t
186 This is an integer data type used to represent user IDs.  In the GNU
187 library, this is an alias for @code{unsigned short int}.
188 @end deftp
189
190 @comment sys/types.h
191 @comment POSIX.1
192 @deftp {Data Type} gid_t
193 This is an integer data type used to represent group IDs.  In the GNU
194 library, this is an alias for @code{unsigned short int}.
195 @end deftp
196
197 @comment unistd.h
198 @comment POSIX.1
199 @deftypefun uid_t getuid ()
200 The @code{getuid} function returns the real user ID of the process.
201 @end deftypefun
202
203 @comment unistd.h
204 @comment POSIX.1
205 @deftypefun gid_t getgid ()
206 The @code{getgid} function returns the real group ID of the process.
207 @end deftypefun
208
209 @comment unistd.h
210 @comment POSIX.1
211 @deftypefun uid_t geteuid ()
212 The @code{geteuid} function returns the effective user ID of the process.
213 @end deftypefun
214
215 @comment unistd.h
216 @comment POSIX.1
217 @deftypefun gid_t getegid ()
218 The @code{getegid} function returns the effective group ID of the process.
219 @end deftypefun
220
221 @comment unistd.h
222 @comment POSIX.1
223 @deftypefun int getgroups (int @var{count}, gid_t *@var{groups})
224 The @code{getgroups} function is used to inquire about the supplementary
225 group IDs of the process.  Up to @var{count} of these group IDs are
226 stored in the array @var{groups}; the return value from the function is
227 the number of group IDs actually stored.  If @var{count} is smaller than
228 the total number of supplementary group IDs, then @code{getgroups}
229 returns a value of @code{-1} and @code{errno} is set to @code{EINVAL}.
230
231 If @var{count} is zero, then @code{getgroups} just returns the total
232 number of supplementary group IDs.
233
234 Here's how to use @code{getgroups} to read all the supplementary group
235 IDs:
236
237 @example
238 gid_t *
239 read_all_groups ()
240 @{
241   int ngroups = getgroups (0, 0);
242   gid_t *groups = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
243   int val = getgroups (ngroups, groups);
244   if (val < 0)
245     return 0;
246   return groups;
247 @}
248 @end example
249 @end deftypefun
250
251 @node Setting User ID
252 @section Setting the User ID
253
254 This section describes the functions for altering the user ID (real
255 and/or effective) of a process.  To use these facilities, you must
256 include the header files @file{sys/types.h} and @file{unistd.h}.
257 @pindex unistd.h
258 @pindex sys/types.h
259
260 @comment unistd.h
261 @comment POSIX.1
262 @deftypefun int setuid (@var{newuid})
263 This function sets both the real and effective user ID of the process
264 to @var{newuid}, provided that the process has appropriate privileges.
265
266 If the process is not privileged, then @var{newuid} must either be equal
267 to the real user ID or the saved user ID (if the system supports the
268 @code{_POSIX_SAVED_IDS} feature).  In this case, @code{setuid} sets only
269 the effective user ID and not the real user ID.
270
271 The @code{setuid} function returns a value of @code{0} to indicate
272 successful completion, and a value of @code{-1} to indicate an error.
273 The following @code{errno} error conditions are defined for this
274 function:
275
276 @table @code
277 @item EINVAL
278 The value of the @var{newuid} argument is invalid.
279
280 @item EPERM
281 The process does not have the appropriate privileges; you do not
282 have permission to change to the specified ID.
283 @end table
284 @end deftypefun
285
286 @comment unistd.h
287 @comment BSD
288 @deftypefun int setreuid (int @var{ruid}, int @var{euid})
289 This function sets the real user ID of the process to @var{ruid} and
290 the effective user ID to @var{euid}.
291
292 The @code{setreuid} function exists for compatibility with 4.2 BSD Unix,
293 which does not support saved IDs.  You can use this function to swap the
294 effective and real user IDs of the process.  (Privileged processes are
295 not limited to this particular usage.)  If saved IDs are supported, you
296 should use that feature instead of this function.  @xref{Enable/Disable
297 Setuid}.
298
299 The return value is @code{0} on success and @code{-1} on failure.
300 The following @code{errno} error conditions are defined for this
301 function:
302
303 @table @code
304 @item EPERM
305 The process does not have the appropriate privileges; you do not
306 have permission to change to the specified ID.
307 @end table
308 @end deftypefun
309
310 @node Setting Groups
311 @section Setting the Group IDs
312
313 This section describes the functions for altering the group IDs (real
314 and effective) of a process.  To use these facilities, you must include
315 the header files @file{sys/types.h} and @file{unistd.h}.
316 @pindex unistd.h
317 @pindex sys/types.h
318
319 @comment unistd.h
320 @comment POSIX.1
321 @deftypefun int setgid (@var{newgid})
322 This function sets both the real and effective group ID of the process
323 to @var{newgid}, provided that the process has appropriate privileges.
324
325 If the process is not privileged, then @var{newgid} must either be equal
326 to the real group ID or the saved group ID.  In this case, @code{setgid}
327 sets only the effective group ID and not the real group ID.
328
329 The return values and error conditions for @code{setgid} are the same
330 as those for @code{setuid}.
331 @end deftypefun
332
333 @comment unistd.h
334 @comment BSD
335 @deftypefun int setregid (int @var{rgid}, int @var{egid})
336 This function sets the real group ID of the process to @var{rgid} and
337 the effective group ID to @var{egid}.
338
339 The @code{setregid} function is provided for compatibility with 4.2 BSD
340 Unix, which does not support saved IDs.  You can use this function to
341 swap the effective and real group IDs of the process.  (Privileged
342 processes are not limited to this usage.)  If saved IDs are supported,
343 you should use that feature instead of using this function.
344 @xref{Enable/Disable Setuid}.
345
346 The return values and error conditions for @code{setregid} are the same
347 as those for @code{setreuid}.
348 @end deftypefun
349
350 The GNU system also lets privileged processes change their supplementary 
351 group IDs.  To use @code{setgroups} or @code{initgroups}, your programs
352 should include the header file @file{grp.h}.
353 @pindex grp.h
354
355 @comment grp.h
356 @comment BSD
357 @deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups})
358 This function sets the process's supplementary group IDs.  It can only
359 be called from privileged processes.  The @var{count} argument specifies
360 the number of group IDs in the array @var{groups}.
361
362 This function returns @code{0} if successful and @code{-1} on error.
363 The following @code{errno} error conditions are defined for this
364 function:
365
366 @table @code
367 @item EPERM
368 The calling process is not privileged.
369 @end table
370 @end deftypefun
371
372 @comment grp.h
373 @comment BSD
374 @deftypefun int initgroups (const char *@var{user}, gid_t @var{gid})
375 The @code{initgroups} function effectively calls @code{setgroups} to
376 set the process's supplementary group IDs to be the normal default for
377 the user name @var{user}.  The group ID @var{gid} is also included.
378 @end deftypefun
379
380 @node Enable/Disable Setuid
381 @section Enabling and Disabling Setuid Access
382
383 A typical setuid program does not need its special access all of the
384 time.  It's a good idea to turn off this access when it isn't needed,
385 so it can't possibly give unintended access.
386
387 If the system supports the saved user ID feature, you can accomplish
388 this with @code{setuid}.  When the game program starts, its real user ID
389 is @code{jdoe}, its effective user ID is @code{games}, and its saved
390 user ID is also @code{games}.  The program should record both user ID
391 values once at the beginning, like this:
392
393 @example
394 user_user_id = getuid ();
395 game_user_id = geteuid ();
396 @end example
397
398 Then it can turn off game file access with 
399
400 @example
401 setuid (user_user_id);
402 @end example
403
404 @noindent
405 and turn it on with 
406
407 @example
408 setuid (game_user_id);
409 @end example
410
411 @noindent
412 Throughout this process, the real user ID remains @code{jdoe} and the
413 saved user ID remains @code{games}, so the program can always set its
414 effective user ID to either one.
415
416 On other systems that don't support the saved user ID feature, you can
417 turn setuid access on and off by using @code{setreuid} to swap the real
418 and effective user IDs of the process, as follows:
419
420 @example
421 setreuid (geteuid (), getuid ());
422 @end example
423
424 @noindent
425 This special case is always allowed---it cannot fail.
426
427 Why does this have the effect of toggling the setuid access?  Suppose a
428 game program has just started, and its real user ID is @code{jdoe} while
429 its effective user ID is @code{games}.  In this state, the game can
430 write the scores file.  If it swaps the two uids, the real becomes
431 @code{games} and the effective becomes @code{jdoe}; now the program has
432 only @code{jdoe} to access.  Another swap brings @code{games} back to
433 the effective user ID and restores access to the scores file.
434
435 In order to handle both kinds of systems, test for the saved user ID
436 feature with a preprocessor conditional, like this:
437
438 @example
439 #ifdef _POSIX_SAVED_IDS
440   setuid (user_user_id);
441 #else
442   setreuid (geteuid (), getuid ());
443 @end example
444
445 @node Setuid Program Example
446 @section Setuid Program Example
447
448 Here's an example showing how to set up a program that changes its
449 effective user ID.
450
451 This is part of a game program called @code{caber-toss} that
452 manipulates a file @file{scores} that should be writable only by the game
453 program itself.  The program assumes that its executable
454 file will be installed with the set-user-ID bit set and owned by the
455 same user as the @file{scores} file.  Typically, a system
456 administrator will set up an account like @code{games} for this purpose.
457
458 The executable file is given mode @code{4755}, so that doing an 
459 @samp{ls -l} on it produces output like:
460
461 @example
462 -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
463 @end example
464
465 @noindent
466 The set-user-ID bit shows up in the file modes as the @samp{s}.
467
468 The scores file is given mode @code{644}, and doing an @samp{ls -l} on
469 it shows:
470
471 @example
472 -rw-r--r--  1 games           0 Jul 31 15:33 scores
473 @end example
474
475 Here are the parts of the program that show how to set up the changed
476 user ID.  This program is conditionalized so that it makes use of the
477 saved IDs feature if it is supported, and otherwise uses @code{setreuid}
478 to swap the effective and real user IDs.
479
480 @example
481 #include <stdio.h>
482 #include <sys/types.h>
483 #include <unistd.h>
484 #include <stdlib.h>
485
486
487 /* @r{Save the effective and real UIDs.} */
488
489 uid_t euid, ruid;
490
491
492 /* @r{Restore the effective UID to its original value.} */
493
494 void
495 do_setuid ()
496 @{
497   int status;
498
499 #ifdef _POSIX_SAVED_IDS
500   status = setuid (euid);
501 #else
502   status = setreuid (ruid, euid);
503 #endif
504   if (status < 0) @{
505     fprintf (stderr, "Couldn't set uid.\n");
506     exit (status);
507     @}
508 @}
509
510
511 /* @r{Set the effective UID to the real UID.} */
512
513 void
514 undo_setuid ()
515 @{
516   int status;
517
518 #ifdef _POSIX_SAVED_IDS
519   status = setuid (ruid);
520 #else
521   status = setreuid (euid, ruid);
522 #endif
523   if (status < 0) @{
524     fprintf (stderr, "Couldn't set uid.\n");
525     exit (status);
526     @}
527 @}
528
529
530 /* @r{Main program.} */
531
532 int
533 main ()
534 @{
535   /* @r{Save the real and effective user IDs.}  */
536   ruid = getuid ();
537   euid = geteuid ();
538   undo_setuid ();
539
540   /* @r{Do the game and record the score.}  */
541   @dots{}
542 @}
543 @end example
544
545 Notice how the first thing the @code{main} function does is to set the
546 effective user ID back to the real user ID.  This is so that any other
547 file accesses that are performed while the user is playing the game use
548 the real user ID for determining permissions.  Only when the program
549 needs to open the scores file does it switch back to the original
550 effective user ID, like this:
551
552 @example
553 /* @r{Record the score.} */
554
555 int
556 record_score (int score)
557 @{
558   FILE *stream;
559   char *myname;
560
561   /* @r{Open the scores file.} */
562   do_setuid ();
563   stream = fopen (SCORES_FILE, "a");
564   undo_setuid ();
565
566   /* @r{Write the score to the file.} */
567   if (stream) @{
568     myname = cuserid (NULL);
569     if (score < 0)
570       fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
571     else
572       fprintf (stream, "%10s: %d feet.\n", myname, score);
573     fclose (stream);
574     return 0;
575     @}
576   else
577     return -1;
578 @}
579 @end example
580
581 @node Tips for Setuid
582 @section Tips for Writing Setuid Programs
583
584 It is easy for setuid programs to give the user access that isn't 
585 intended---in fact, if you want to avoid this, you need to be careful.
586 Here are some guidelines for preventing unintended access and
587 minimizing its consequences when it does occur:
588
589 @itemize @bullet
590 @item
591 Don't have @code{setuid} programs with privileged user IDs such as
592 @code{root} unless it is absolutely necessary.  If the resource is
593 specific to your particular program, it's better to define a new,
594 nonprivileged user ID or group ID just to manage that resource.
595
596 @item
597 Be cautious about using the @code{system} and @code{exec} functions in
598 combination with changing the effective user ID.  Don't let users of
599 your program execute arbitrary programs under a changed user ID.
600 Executing a shell is especially bad news.  Less obviously, the
601 @code{execlp} and @code{execvp} functions are a potential risk (since
602 the program they execute depends on the user's @code{PATH} environment
603 variable).
604
605 If you must @code{exec} another program under a changed ID, specify an
606 absolute file name (@pxref{File Name Resolution}) for the executable,
607 and make sure that the protections on that executable and @emph{all}
608 containing directories are such that ordinary users cannot replace it
609 with some other program.
610
611 @item
612 Only use the user ID controlling the resource in the part of the program
613 that actually uses that resource.  When you're finished with it, restore
614 the effective user ID back to the actual user's user ID.
615 @xref{Enable/Disable Setuid}.
616
617 @item
618 If the @code{setuid} part of your program needs to access other files
619 besides the controlled resource, it should verify that the real user
620 would ordinarily have permission to access those files.  You can use the
621 @code{access} function (@pxref{Access Permission}) to check this; it
622 uses the real user and group IDs, rather than the effective IDs.
623 @end itemize
624
625 @node Who Logged In
626 @section Identifying Who Logged In
627 @cindex login name, determining
628 @cindex user ID, determining
629
630 You can use the functions listed in this section to determine the login
631 name of the user who is running a process, and the name of the user who
632 logged in the current session.  See also the function @code{getuid} and
633 friends (@pxref{Reading Persona}).
634
635 The @code{getlogin} function is declared in @file{unistd.h}, while
636 @code{cuserid} and @code{L_cuserid} are declared in @file{stdio.h}.
637 @pindex stdio.h
638 @pindex unistd.h
639
640 @comment unistd.h
641 @comment POSIX.1
642 @deftypefun {char *} getlogin ()
643 The @code{getlogin} function returns a pointer to string containing the
644 name of the user logged in on the controlling terminal of the process,
645 or a null pointer if this information cannot be determined.  The string
646 is statically allocated and might be overwritten on subsequent calls to
647 this function or to @code{cuserid}.
648 @end deftypefun
649
650 @comment stdio.h
651 @comment POSIX.1
652 @deftypefun {char *} cuserid (@var{string})
653 The @code{cuserid} function returns a pointer to a string containing a
654 user name associated with the effective ID of the process.  If
655 @var{string} is not a null pointer, it should be an array that can hold
656 at least @code{L_cuserid} characters; the string is returned in this
657 array.  Otherwise, a pointer to a string in a static area is returned.
658 This string is statically allocated and might be overwritten on
659 subsequent calls to this function or to @code{getlogin}.
660 @end deftypefun
661
662 @comment stdio.h
663 @comment POSIX.1
664 @deftypevr Macro int L_cuserid
665 An integer constant that indicates how long an array you might need to
666 store a user name.
667 @end deftypevr
668
669 These functions let your program identify positively the user who is
670 running or the user who logged in this session.  (These can differ when
671 setuid programs are involved; @xref{Process Persona}.)  The user cannot
672 do anything to fool these functions.
673
674 For most purposes, it is more useful to use the environment variable
675 @code{LOGNAME} to find out who the user is.  This is more flexible
676 precisely because the user can set @code{LOGNAME} arbitrarily.
677 @xref{Standard Environment}.
678
679 @node User Database
680 @section User Database
681 @cindex user database
682 @cindex password database
683 @pindex /etc/passwd
684
685 This section describes all about now to search and scan the database of
686 registered users.  The database itself is kept in the file
687 @file{/etc/passwd} on most systems, but on some systems a special
688 network server gives access to it.
689
690 @menu
691 * User Data Structure::         What each user record contains.
692 * Lookup User::                 How to look for a particular user.
693 * Scanning All Users::          Scanning the list of all users, one by one.
694 * Writing a User Entry::        How a program can rewrite a user's record.
695 @end menu
696
697 @node User Data Structure
698 @subsection The Data Structure that Describes a User
699
700 The functions and data structures for accessing the system user database
701 are declared in the header file @file{pwd.h}.
702 @pindex pwd.h
703
704 @comment pwd.h
705 @comment POSIX.1
706 @deftp {struct Type} passwd
707 The @code{passwd} data structure is used to hold information about 
708 entries in the system user data base.  It has at least the following members:
709
710 @table @code
711 @item char *pw_name
712 The user's login name.
713
714 @item char *pw_passwd.
715 The encrypted password string.
716
717 @item uid_t pw_uid
718 The user ID number.
719
720 @item gid_t pw_gid
721 The user's default group ID number.
722
723 @item char *pw_gecos
724 A string typically containing the user's real name, and possibly other
725 information such as a phone number.
726
727 @item char *pw_dir
728 The user's home directory, or initial working directory.  This might be
729 a null pointer, in which case the interpretation is system-dependent.
730
731 @item char *pw_shell
732 The user's default shell, or the initial program run when the user logs in.
733 This might be a null pointer, indicating that the system default should
734 be used.
735 @end table
736 @end deftp
737
738 @node Lookup User
739 @subsection Looking Up One User
740 @cindex converting user ID to user name
741 @cindex converting user name to user ID
742
743 You can search the system user database for information about a
744 specific user using @code{getpwuid} or @code{getpwnam}.  These
745 functions are declared in @file{pwd.h}.
746
747 @comment pwd.h
748 @comment POSIX.1
749 @deftypefun {struct passwd *} getpwuid (uid_t @var{uid})
750 This function returns a pointer to a statically-allocated structure
751 containing information about the user whose user ID is @var{uid}.  This
752 structure may be overwritten on subsequent calls to @code{getpwuid}.
753
754 A null pointer value indicates there is no user in the data base with
755 user ID @var{uid}.
756 @end deftypefun
757
758 @comment pwd.h
759 @comment POSIX.1
760 @deftypefun {struct passwd *} getpwnam (const char *@var{name})
761 This function returns a pointer to a statically-allocated structure
762 containing information about the user whose user name is @var{name}.
763 This structure may be overwritten on subsequent calls to
764 @code{getpwnam}.
765
766 A null pointer value indicates there is no user named @var{name}.
767 @end deftypefun
768
769 @node Scanning All Users
770 @subsection Scanning the List of All Users
771 @cindex scanning the user list
772
773 This section explains how a program can read the list of all users in
774 the system, one user at a time.  The functions described here are
775 declared in @file{pwd.h}.
776
777 The recommended way to scan the users is to open the user file and
778 then call @code{fgetgrent} for each successive user:
779
780 @comment pwd.h
781 @comment SVID
782 @deftypefun {struct passwd *} fgetpwent (FILE *@var{stream})
783 This function reads the next user entry from @var{stream} and returns a
784 pointer to the entry.  The structure is statically allocated and is
785 rewritten on subsequent calls to @code{getpwent}.  You must copy the
786 contents of the structure if you wish to save the information.
787
788 This stream must correspond to a file in the same format as the standard
789 password database file.  This function comes from System V.
790 @end deftypefun
791
792 Another way to scan all the entries in the group database is with
793 @code{setpwent}, @code{getpwent}, and @code{endpwent}.  But this method
794 is less robust than @code{fgetpwent}, so we provide it only for
795 compatibility with SVID.  In particular, these functions are not
796 reentrant and are not suitable for use in programs with multiple threads
797 of control.  Calling @code{getpwgid} or @code{getpwnam} can also confuse
798 the internal state of these functions.
799
800 @comment pwd.h
801 @comment SVID, BSD
802 @deftypefun void setpwent ()
803 This function initializes a stream which @code{getpwent} uses to read
804 the user database.
805 @end deftypefun
806
807 @comment pwd.h
808 @comment SVID, BSD
809 @deftypefun {struct passwd *} getpwent ()
810 The @code{getpwent} function reads the next entry from the stream
811 initialized by @code{setpwent}.  It returns a pointer to the entry.  The
812 structure is statically allocated and is rewritten on subsequent calls
813 to @code{getpwent}.  You must copy the contents of the structure if you
814 wish to save the information.
815 @end deftypefun
816
817 @comment pwd.h
818 @comment SVID, BSD
819 @deftypefun void endpwent ()
820 This function closes the internal stream used by @code{getpwent}.
821 @end deftypefun
822
823 @node Writing a User Entry
824 @subsection Writing a User Entry
825
826 @comment pwd.h
827 @comment SVID
828 @deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream})
829 This function writes the user entry @code{*@var{p}} to the stream
830 @var{stream}, in the format used for the standard user database
831 file.  The return value is zero on success and non-zero on failure.
832
833 This function exists for compatibility with SVID.  We recommend that you
834 avoid using it, because it makes sense only on the assumption that the
835 @code{struct passwd} structure has no members except the standard ones;
836 on a system which merges the traditional Unix data base with other
837 extended information about users, adding an entry using this function
838 would inevitably leave out much of the important information.
839
840 The function @code{putpwent} is declared in @file{pwd.h}.
841 @end deftypefun
842
843 @node Group Database
844 @section Group Database
845 @cindex group database
846 @pindex /etc/group
847
848 This section describes all about now to search and scan the database of
849 registered groups.  The database itself is kept in the file
850 @file{/etc/group} on most systems, but on some systems a special network
851 service provides access to it.
852
853 @menu
854 * Group Data Structure::        What each group record contains.
855 * Lookup Group::                How to look for a particular group.
856 * Scanning All Groups::         Scanning the list of all groups.
857 @end menu
858
859 @node Group Data Structure
860 @subsection The Data Structure for a Group
861
862 The functions and data structures for accessing the system group
863 database are declared in the header file @file{grp.h}.
864 @pindex grp.h
865
866 @comment grp.h
867 @comment POSIX.1
868 @deftp {Data Type} {struct group} 
869 The @code{group} structure is used to hold information about an entry in
870 the system group database.  It has at least the following members:
871
872 @table @code
873 @item char *gr_name
874 The name of the group.
875
876 @item gid_t gr_gid
877 The group ID of the group.
878
879 @item char **gr_mem
880 A vector of pointers to the names of users in the group.  Each user name
881 is a null-terminated string, and the vector itself is terminated by a
882 null pointer.
883 @end table
884 @end deftp
885
886 @node Lookup Group
887 @subsection Looking Up One Group
888 @cindex converting group name to group ID
889 @cindex converting group ID to group name
890
891 You can search the group database for information about a specific
892 group using @code{getgrgid} or @code{getgrnam}.  These functions are
893 declared in @file{grp.h}.
894
895 @comment grp.h
896 @comment POSIX.1
897 @deftypefun {struct group *} getgrgid (gid_t @var{gid})
898 This function returns a pointer to a statically-allocated structure
899 containing information about the group whose group ID is @var{gid}.
900 This structure may be overwritten by subsequent calls to
901 @code{getgrgid}.
902
903 A null pointer indicates there is no group with ID @var{gid}.
904 @end deftypefun
905
906 @comment grp.h
907 @comment POSIX.1
908 @deftypefun {struct group *} getgrnam (const char *@var{name})
909 This function returns a pointer to a statically-allocated structure
910 containing information about the group whose group name is @var{name}.
911 This structure may be overwritten by subsequent calls to
912 @code{getgrnam}.
913
914 A null pointer indicates there is no group named @var{name}.
915 @end deftypefun
916
917 @node Scanning All Groups
918 @subsection Scanning the List of All Groups
919 @cindex scanning the group list
920
921 This section explains how a program can read the list of all groups in
922 the system, one group at a time.  The functions described here are
923 declared in @file{grp.h}.
924
925 The recommended way to scan the groups is to open the group file and
926 then call @code{fgetgrent} for each successive group:
927
928 @comment grp.h
929 @comment SVID
930 @deftypefun {struct group *} fgetgrent (FILE *@var{stream})
931 The @code{fgetgrent} function reads the next entry from @var{stream}.
932 It returns a pointer to the entry.  The structure is statically
933 allocated and is rewritten on subsequent calls to @code{getgrent}.  You
934 must copy the contents of the structure if you wish to save the
935 information.
936
937 The stream must correspond to a file in the same format as the standard
938 group database file.
939 @end deftypefun
940
941 Another way to scan all the entries in the group database is with
942 @code{setgrent}, @code{getgrent}, and @code{endgrent}.  But this method
943 is less robust than @code{fgetgrent}, so we provide it only for
944 compatibility with SVID.  In particular, these functions are not
945 reentrant and are not suitable for use in programs with multiple threads
946 of control.  Calling @code{getgrgid} or @code{getgrnam} can also confuse
947 the internal state of these functions.
948
949 @comment grp.h
950 @comment SVID, BSD
951 @deftypefun void setgrent ()
952 This function initializes a stream for reading from the group data base.
953 You use this stream by calling @code{getgrent}.
954 @end deftypefun
955
956 @comment grp.h
957 @comment SVID, BSD
958 @deftypefun {struct group *} getgrent ()
959 The @code{getgrent} function reads the next entry from the stream
960 initialized by @code{setgrent}.  It returns a pointer to the entry.  The
961 structure is statically allocated and is rewritten on subsequent calls
962 to @code{getgrent}.  You must copy the contents of the structure if you
963 wish to save the information.
964 @end deftypefun
965
966 @comment grp.h
967 @comment SVID, BSD
968 @deftypefun void endgrent ()
969 This function closes the internal stream used by @code{getgrent}.
970 @end deftypefun
971
972 @node Database Example
973 @section User and Group Database Example
974
975 Here is an example program showing the use of the system database inquiry
976 functions.  The program prints some information about the user running
977 the program.
978
979 @example
980 @include db.c.texi
981 @end example
982
983 Here is some output from this program:
984
985 @example
986 My login name is snurd.
987 My uid is 31093.
988 My home directory is /home/fsg/snurd.
989 My default shell is /bin/sh.
990 My default group is guest (12).
991 The members of this group are:
992   friedman
993   @dots{}
994 @end example