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