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