Changed many summary cookies that said GNU to properly say BSD.
[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.  @xref{Controlling Process
283 Privileges}.
284 @end table
285 @end deftypefun
286
287 @comment unistd.h
288 @comment BSD
289 @deftypefun int setreuid (int @var{ruid}, int @var{euid})
290 This function sets the real user ID of the process to @var{ruid} and
291 the effective user ID to @var{euid}.
292
293 The @code{setreuid} function exists for compatibility with 4.2 BSD Unix,
294 which does not support saved IDs.  You can use this function to swap the
295 effective and real user IDs of the process.  (Privileged processes are
296 not limited to this particular usage.)  If saved IDs are supported, you
297 should use that feature instead of this function.  @xref{Enable/Disable
298 Setuid}.
299
300 The return value is @code{0} on success and @code{-1} on failure.
301 The following @code{errno} error conditions are defined for this
302 function:
303
304 @table @code
305 @item EPERM
306 The process does not have the appropriate privileges; you do not
307 have permission to change to the specified ID.  @xref{Controlling Process
308 Privileges}.
309 @end table
310 @end deftypefun
311
312 @node Setting Groups
313 @section Setting the Group IDs
314
315 This section describes the functions for altering the group IDs (real
316 and effective) of a process.  To use these facilities, you must include
317 the header files @file{sys/types.h} and @file{unistd.h}.
318 @pindex unistd.h
319 @pindex sys/types.h
320
321 @comment unistd.h
322 @comment POSIX.1
323 @deftypefun int setgid (@var{newgid})
324 This function sets both the real and effective group ID of the process
325 to @var{newgid}, provided that the process has appropriate privileges.
326
327 If the process is not privileged, then @var{newgid} must either be equal
328 to the real group ID or the saved group ID.  In this case, @code{setgid}
329 sets only the effective group ID and not the real group ID.
330
331 The return values and error conditions for @code{setgid} are the same
332 as those for @code{setuid}.
333 @end deftypefun
334
335 @comment unistd.h
336 @comment BSD
337 @deftypefun int setregid (int @var{rgid}, int @var{egid})
338 This function sets the real group ID of the process to @var{rgid} and
339 the effective group ID to @var{egid}.
340
341 The @code{setregid} function is provided for compatibility with 4.2 BSD
342 Unix, which does not support saved IDs.  You can use this function to
343 swap the effective and real group IDs of the process.  (Privileged
344 processes are not limited to this usage.)  If saved IDs are supported,
345 you should use that feature instead of using this function.
346 @xref{Enable/Disable Setuid}.
347
348 The return values and error conditions for @code{setregid} are the same
349 as those for @code{setreuid}.
350 @end deftypefun
351
352 The GNU system also lets privileged processes change their supplementary 
353 group IDs.  To use @code{setgroups} or @code{initgroups}, your programs
354 should include the header file @file{grp.h}.
355 @pindex grp.h
356
357 @comment grp.h
358 @comment BSD
359 @deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups})
360 This function sets the process's supplementary group IDs.  It can only
361 be called from privileged processes.  The @var{count} argument specifies
362 the number of group IDs in the array @var{groups}.
363
364 This function returns @code{0} if successful and @code{-1} on error.
365 The following @code{errno} error conditions are defined for this
366 function:
367
368 @table @code
369 @item EPERM
370 The calling process is not privileged.
371 @end table
372 @end deftypefun
373
374 @comment grp.h
375 @comment BSD
376 @deftypefun int initgroups (const char *@var{user}, gid_t @var{gid})
377 The @code{initgroups} function effectively calls @code{setgroups} to
378 set the process's supplementary group IDs to be the normal default for
379 the user name @var{user}.  The group ID @var{gid} is also included.
380 @end deftypefun
381
382 @node Enable/Disable Setuid
383 @section Enabling and Disabling Setuid Access
384
385 A typical setuid program does not need its special access all of the
386 time.  It's a good idea to turn off this access when it isn't needed,
387 so it can't possibly give unintended access.
388
389 If the system supports the saved user ID feature, you can accomplish
390 this with @code{setuid}.  When the game program starts, its real user ID
391 is @code{jdoe}, its effective user ID is @code{games}, and its saved
392 user ID is also @code{games}.  The program should record both user ID
393 values once at the beginning, like this:
394
395 @example
396 user_user_id = getuid ();
397 game_user_id = geteuid ();
398 @end example
399
400 Then it can turn off game file access with 
401
402 @example
403 setuid (user_user_id);
404 @end example
405
406 @noindent
407 and turn it on with 
408
409 @example
410 setuid (game_user_id);
411 @end example
412
413 @noindent
414 Throughout this process, the real user ID remains @code{jdoe} and the
415 saved user ID remains @code{games}, so the program can always set its
416 effective user ID to either one.
417
418 On other systems that don't support the saved user ID feature, you can
419 turn setuid access on and off by using @code{setreuid} to swap the real
420 and effective user IDs of the process, as follows:
421
422 @example
423 setreuid (geteuid (), getuid ());
424 @end example
425
426 @noindent
427 This special case is always allowed---it cannot fail.
428
429 Why does this have the effect of toggling the setuid access?  Suppose a
430 game program has just started, and its real user ID is @code{jdoe} while
431 its effective user ID is @code{games}.  In this state, the game can
432 write the scores file.  If it swaps the two uids, the real becomes
433 @code{games} and the effective becomes @code{jdoe}; now the program has
434 only @code{jdoe} to access.  Another swap brings @code{games} back to
435 the effective user ID and restores access to the scores file.
436
437 In order to handle both kinds of systems, test for the saved user ID
438 feature with a preprocessor conditional, like this:
439
440 @example
441 #ifdef _POSIX_SAVED_IDS
442   setuid (user_user_id);
443 #else
444   setreuid (geteuid (), getuid ());
445 @end example
446
447 @node Setuid Program Example
448 @section Setuid Program Example
449
450 Here's an example showing how to set up a program that changes its
451 effective user ID.
452
453 This is part of a game program called @code{caber-toss} that
454 manipulates a file @file{scores} that should be writable only by the game
455 program itself.  The program assumes that its executable
456 file will be installed with the set-user-ID bit set and owned by the
457 same user as the @file{scores} file.  Typically, a system
458 administrator will set up an account like @code{games} for this purpose.
459
460 The executable file is given mode @code{4755}, so that doing an 
461 @samp{ls -l} on it produces output like:
462
463 @example
464 -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
465 @end example
466
467 @noindent
468 The set-user-ID bit shows up in the file modes as the @samp{s}.
469
470 The scores file is given mode @code{644}, and doing an @samp{ls -l} on
471 it shows:
472
473 @example
474 -rw-r--r--  1 games           0 Jul 31 15:33 scores
475 @end example
476
477 Here are the parts of the program that show how to set up the changed
478 user ID.  This program is conditionalized so that it makes use of the
479 saved IDs feature if it is supported, and otherwise uses @code{setreuid}
480 to swap the effective and real user IDs.
481
482 @example
483 #include <stdio.h>
484 #include <sys/types.h>
485 #include <unistd.h>
486 #include <stdlib.h>
487
488
489 /* @r{Save the effective and real UIDs.} */
490
491 uid_t euid, ruid;
492
493
494 /* @r{Restore the effective UID to its original value.} */
495
496 void
497 do_setuid ()
498 @{
499   int status;
500
501 #ifdef _POSIX_SAVED_IDS
502   status = setuid (euid);
503 #else
504   status = setreuid (ruid, euid);
505 #endif
506   if (status < 0) @{
507     fprintf (stderr, "Couldn't set uid.\n");
508     exit (status);
509     @}
510 @}
511
512
513 /* @r{Set the effective UID to the real UID.} */
514
515 void
516 undo_setuid ()
517 @{
518   int status;
519
520 #ifdef _POSIX_SAVED_IDS
521   status = setuid (ruid);
522 #else
523   status = setreuid (euid, ruid);
524 #endif
525   if (status < 0) @{
526     fprintf (stderr, "Couldn't set uid.\n");
527     exit (status);
528     @}
529 @}
530
531
532 /* @r{Main program.} */
533
534 int
535 main ()
536 @{
537   /* @r{Save the real and effective user IDs.}  */
538   ruid = getuid ();
539   euid = geteuid ();
540   undo_setuid ();
541
542   /* @r{Do the game and record the score.}  */
543   @dots{}
544 @}
545 @end example
546
547 Notice how the first thing the @code{main} function does is to set the
548 effective user ID back to the real user ID.  This is so that any other
549 file accesses that are performed while the user is playing the game use
550 the real user ID for determining permissions.  Only when the program
551 needs to open the scores file does it switch back to the original
552 effective user ID, like this:
553
554 @example
555 /* @r{Record the score.} */
556
557 int
558 record_score (int score)
559 @{
560   FILE *stream;
561   char *myname;
562
563   /* @r{Open the scores file.} */
564   do_setuid ();
565   stream = fopen (SCORES_FILE, "a");
566   undo_setuid ();
567
568   /* @r{Write the score to the file.} */
569   if (stream) @{
570     myname = cuserid (NULL);
571     if (score < 0)
572       fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
573     else
574       fprintf (stream, "%10s: %d feet.\n", myname, score);
575     fclose (stream);
576     return 0;
577     @}
578   else
579     return -1;
580 @}
581 @end example
582
583 @node Tips for Setuid
584 @section Tips for Writing Setuid Programs
585
586 It is easy for setuid programs to give the user access that isn't 
587 intended---in fact, if you want to avoid this, you need to be careful.
588 Here are some guidelines for preventing unintended access and
589 minimizing its consequences when it does occur:
590
591 @itemize @bullet
592 @item
593 Don't have @code{setuid} programs with privileged user IDs such as
594 @code{root} unless it is absolutely necessary.  If the resource is
595 specific to your particular program, it's better to define a new,
596 nonprivileged user ID or group ID just to manage that resource.
597
598 @item
599 Be cautious about using the @code{system} and @code{exec} functions in
600 combination with changing the effective user ID.  Don't let users of
601 your program execute arbitrary programs under a changed user ID.
602 Executing a shell is especially bad news.  Less obviously, the
603 @code{execlp} and @code{execvp} functions are a potential risk (since
604 the program they execute depends on the user's @code{PATH} environment
605 variable).
606
607 If you must @code{exec} another program under a changed ID, specify an
608 absolute file name (@pxref{File Name Resolution}) for the executable,
609 and make sure that the protections on that executable and @emph{all}
610 containing directories are such that ordinary users cannot replace it
611 with some other program.
612
613 @item
614 Only use the user ID controlling the resource in the part of the program
615 that actually uses that resource.  When you're finished with it, restore
616 the effective user ID back to the actual user's user ID.
617 @xref{Enable/Disable Setuid}.
618
619 @item
620 If the @code{setuid} part of your program needs to access other files
621 besides the controlled resource, it should verify that the real user
622 would ordinarily have permission to access those files.  You can use the
623 @code{access} function (@pxref{Access Permission}) to check this; it
624 uses the real user and group IDs, rather than the effective IDs.
625 @end itemize
626
627 @node Who Logged In
628 @section Identifying Who Logged In
629 @cindex login name, determining
630 @cindex user ID, determining
631
632 You can use the functions listed in this section to determine the login
633 name of the user who is running a process, and the name of the user who
634 logged in the current session.  See also the function @code{getuid} and
635 friends (@pxref{Reading Persona}).
636
637 The @code{getlogin} function is declared in @file{unistd.h}, while
638 @code{cuserid} and @code{L_cuserid} are declared in @file{stdio.h}.
639 @pindex stdio.h
640 @pindex unistd.h
641
642 @comment unistd.h
643 @comment POSIX.1
644 @deftypefun {char *} getlogin ()
645 The @code{getlogin} function returns a pointer to string containing the
646 name of the user logged in on the controlling terminal of the process,
647 or a null pointer if this information cannot be determined.  The string
648 is statically allocated and might be overwritten on subsequent calls to
649 this function or to @code{cuserid}.
650 @end deftypefun
651
652 @comment stdio.h
653 @comment POSIX.1
654 @deftypefun {char *} cuserid (@var{string})
655 The @code{cuserid} function returns a pointer to a string containing a
656 user name associated with the effective ID of the process.  If
657 @var{string} is not a null pointer, it should be an array that can hold
658 at least @code{L_cuserid} characters; the string is returned in this
659 array.  Otherwise, a pointer to a string in a static area is returned.
660 This string is statically allocated and might be overwritten on
661 subsequent calls to this function or to @code{getlogin}.
662 @end deftypefun
663
664 @comment stdio.h
665 @comment POSIX.1
666 @deftypevr Macro int L_cuserid
667 An integer constant that indicates how long an array you might need to
668 store a user name.
669 @end deftypevr
670
671 These functions let your program identify positively the user who is
672 running or the user who logged in this session.  (These can differ when
673 setuid programs are involved; @xref{Controlling Access Privileges}.)
674 The user cannot do anything to fool these functions.
675
676 For most purposes, it is more useful to use the environment variable
677 @code{LOGNAME} to find out who the user is.  This is more flexible
678 precisely because the user can set @code{LOGNAME} arbitrarily.
679 @xref{Standard Environment}.
680
681 @node User Database
682 @section User Database
683 @cindex user database
684 @cindex password database
685 @pindex /etc/passwd
686
687 This section describes all about now to search and scan the database of
688 registered users.  The database itself is kept in the file
689 @file{/etc/passwd} on most systems, but on some systems a special
690 network server gives access to it.
691
692 @menu
693 * User Data Structure::         What each user record contains.
694 * Lookup User::                 How to look for a particular user.
695 * Scanning All Users::          Scanning the list of all users, one by one.
696 * Writing a User Entry::        How a program can rewrite a user's record.
697 @end menu
698
699 @node User Data Structure
700 @subsection The Data Structure that Describes a User
701
702 The functions and data structures for accessing the system user database
703 are declared in the header file @file{pwd.h}.
704 @pindex pwd.h
705
706 @comment pwd.h
707 @comment POSIX.1
708 @deftp {struct Type} passwd
709 The @code{passwd} data structure is used to hold information about 
710 entries in the system user data base.  It has at least the following members:
711
712 @table @code
713 @item char *pw_name
714 The user's login name.
715
716 @item char *pw_passwd.
717 The encrypted password string.
718
719 @item uid_t pw_uid
720 The user ID number.
721
722 @item gid_t pw_gid
723 The user's default group ID number.
724
725 @item char *pw_gecos
726 A string typically containing the user's real name, and possibly other
727 information such as a phone number.
728
729 @item char *pw_dir
730 The user's home directory, or initial working directory.  This might be
731 a null pointer, in which case the interpretation is system-dependent.
732
733 @item char *pw_shell
734 The user's default shell, or the initial program run when the user logs in.
735 This might be a null pointer, indicating that the system default should
736 be used.
737 @end table
738 @end deftp
739
740 @node Lookup User
741 @subsection Looking Up One User
742 @cindex converting user ID to user name
743 @cindex converting user name to user ID
744
745 You can search the system user database for information about a
746 specific user using @code{getpwuid} or @code{getpwnam}.  These
747 functions are declared in @file{pwd.h}.
748
749 @comment pwd.h
750 @comment POSIX.1
751 @deftypefun {struct passwd *} getpwuid (uid_t @var{uid})
752 This function returns a pointer to a statically-allocated structure
753 containing information about the user whose user ID is @var{uid}.  This
754 structure may be overwritten on subsequent calls to @code{getpwuid}.
755
756 A null pointer value indicates there is no user in the data base with
757 user ID @var{uid}.
758 @end deftypefun
759
760 @comment pwd.h
761 @comment POSIX.1
762 @deftypefun {struct passwd *} getpwnam (const char *@var{name})
763 This function returns a pointer to a statically-allocated structure
764 containing information about the user whose user name is @var{name}.
765 This structure may be overwritten on subsequent calls to
766 @code{getpwnam}.
767
768 A null pointer value indicates there is no user named @var{name}.
769 @end deftypefun
770
771 @node Scanning All Users
772 @subsection Scanning the List of All Users
773 @cindex scanning the user list
774
775 This section explains how a program can read the list of all users in
776 the system, one user at a time.  The functions described here are
777 declared in @file{pwd.h}.
778
779 The recommended way to scan the users is to open the user file and
780 then call @code{fgetgrent} for each successive user:
781
782 @comment pwd.h
783 @comment SVID
784 @deftypefun {struct passwd *} fgetpwent (FILE *@var{stream})
785 This function reads the next user entry from @var{stream} and returns a
786 pointer to the entry.  The structure is statically allocated and is
787 rewritten on subsequent calls to @code{getpwent}.  You must copy the
788 contents of the structure if you wish to save the information.
789
790 This stream must correspond to a file in the same format as the standard
791 password database file.  This function comes from System V.
792 @end deftypefun
793
794 Another way to scan all the entries in the group database is with
795 @code{setpwent}, @code{getpwent}, and @code{endpwent}.  But this method
796 is less robust than @code{fgetpwent}, so we provide it only for
797 compatibility with SVID.  In particular, these functions are not
798 reentrant and are not suitable for use in programs with multiple threads
799 of control.  Calling @code{getpwgid} or @code{getpwnam} can also confuse
800 the internal state of these functions.
801
802 @comment pwd.h
803 @comment SVID, BSD
804 @deftypefun void setpwent ()
805 This function initializes a stream which @code{getpwent} uses to read
806 the user database.
807 @end deftypefun
808
809 @comment pwd.h
810 @comment SVID, BSD
811 @deftypefun {struct passwd *} getpwent ()
812 The @code{getpwent} function reads the next entry from the stream
813 initialized by @code{setpwent}.  It returns a pointer to the entry.  The
814 structure is statically allocated and is rewritten on subsequent calls
815 to @code{getpwent}.  You must copy the contents of the structure if you
816 wish to save the information.
817 @end deftypefun
818
819 @comment pwd.h
820 @comment SVID, BSD
821 @deftypefun void endpwent ()
822 This function closes the internal stream used by @code{getpwent}.
823 @end deftypefun
824
825 @node Writing a User Entry
826 @subsection Writing a User Entry
827
828 @comment pwd.h
829 @comment SVID
830 @deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream})
831 This function writes the user entry @code{*@var{p}} to the stream
832 @var{stream}, in the format used for the standard user database
833 file.  The return value is zero on success and non-zero on failure.
834
835 This function exists for compatibility with SVID.  We recommend that you
836 avoid using it, because it makes sense only on the assumption that the
837 @code{struct passwd} structure has no members except the standard ones;
838 on a system which merges the traditional Unix data base with other
839 extended information about users, adding an entry using this function
840 would inevitably leave out much of the important information.
841
842 The function @code{putpwent} is declared in @file{pwd.h}.
843 @end deftypefun
844
845 @node Group Database
846 @section Group Database
847 @cindex group database
848 @pindex /etc/group
849
850 This section describes all about now to search and scan the database of
851 registered groups.  The database itself is kept in the file
852 @file{/etc/group} on most systems, but on some systems a special network
853 service provides access to it.
854
855 @menu
856 * Group Data Structure::        What each group record contains.
857 * Lookup Group::                How to look for a particular group.
858 * Scanning All Groups::         Scanning the list of all groups.
859 @end menu
860
861 @node Group Data Structure
862 @subsection The Data Structure for a Group
863
864 The functions and data structures for accessing the system group
865 database are declared in the header file @file{grp.h}.
866 @pindex grp.h
867
868 @comment grp.h
869 @comment POSIX.1
870 @deftp {Data Type} {struct group} 
871 The @code{group} structure is used to hold information about an entry in
872 the system group database.  It has at least the following members:
873
874 @table @code
875 @item char *gr_name
876 The name of the group.
877
878 @item gid_t gr_gid
879 The group ID of the group.
880
881 @item char **gr_mem
882 A vector of pointers to the names of users in the group.  Each user name
883 is a null-terminated string, and the vector itself is terminated by a
884 null pointer.
885 @end table
886 @end deftp
887
888 @node Lookup Group
889 @subsection Looking Up One Group
890 @cindex converting group name to group ID
891 @cindex converting group ID to group name
892
893 You can search the group database for information about a specific
894 group using @code{getgrgid} or @code{getgrnam}.  These functions are
895 declared in @file{grp.h}.
896
897 @comment grp.h
898 @comment POSIX.1
899 @deftypefun {struct group *} getgrgid (gid_t @var{gid})
900 This function returns a pointer to a statically-allocated structure
901 containing information about the group whose group ID is @var{gid}.
902 This structure may be overwritten by subsequent calls to
903 @code{getgrgid}.
904
905 A null pointer indicates there is no group with ID @var{gid}.
906 @end deftypefun
907
908 @comment grp.h
909 @comment POSIX.1
910 @deftypefun {struct group *} getgrnam (const char *@var{name})
911 This function returns a pointer to a statically-allocated structure
912 containing information about the group whose group name is @var{name}.
913 This structure may be overwritten by subsequent calls to
914 @code{getgrnam}.
915
916 A null pointer indicates there is no group named @var{name}.
917 @end deftypefun
918
919 @node Scanning All Groups
920 @subsection Scanning the List of All Groups
921 @cindex scanning the group list
922
923 This section explains how a program can read the list of all groups in
924 the system, one group at a time.  The functions described here are
925 declared in @file{grp.h}.
926
927 The recommended way to scan the groups is to open the group file and
928 then call @code{fgetgrent} for each successive group:
929
930 @comment grp.h
931 @comment SVID
932 @deftypefun {struct group *} fgetgrent (FILE *@var{stream})
933 The @code{fgetgrent} function reads the next entry from @var{stream}.
934 It returns a pointer to the entry.  The structure is statically
935 allocated and is rewritten on subsequent calls to @code{getgrent}.  You
936 must copy the contents of the structure if you wish to save the
937 information.
938
939 The stream must correspond to a file in the same format as the standard
940 group database file.
941 @end deftypefun
942
943 Another way to scan all the entries in the group database is with
944 @code{setgrent}, @code{getgrent}, and @code{endgrent}.  But this method
945 is less robust than @code{fgetgrent}, so we provide it only for
946 compatibility with SVID.  In particular, these functions are not
947 reentrant and are not suitable for use in programs with multiple threads
948 of control.  Calling @code{getgrgid} or @code{getgrnam} can also confuse
949 the internal state of these functions.
950
951 @comment grp.h
952 @comment SVID, BSD
953 @deftypefun void setgrent ()
954 This function initializes a stream for reading from the group data base.
955 You use this stream by calling @code{getgrent}.
956 @end deftypefun
957
958 @comment grp.h
959 @comment SVID, BSD
960 @deftypefun {struct group *} getgrent ()
961 The @code{getgrent} function reads the next entry from the stream
962 initialized by @code{setgrent}.  It returns a pointer to the entry.  The
963 structure is statically allocated and is rewritten on subsequent calls
964 to @code{getgrent}.  You must copy the contents of the structure if you
965 wish to save the information.
966 @end deftypefun
967
968 @comment grp.h
969 @comment SVID, BSD
970 @deftypefun void endgrent ()
971 This function closes the internal stream used by @code{getgrent}.
972 @end deftypefun
973
974 @node Database Example
975 @section User and Group Database Example
976
977 Here is an example program showing the use of the system database inquiry
978 functions.  The program prints some information about the user running
979 the program.
980
981 @example
982 @include db.c.texi
983 @end example
984
985 Here is some output from this program:
986
987 @example
988 My login name is snurd.
989 My uid is 31093.
990 My home directory is /home/fsg/snurd.
991 My default shell is /bin/sh.
992 My default group is guest (12).
993 The members of this group are:
994   friedman
995   @dots{}
996 @end example