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