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