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