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