Finish gettext section.
[kopensolaris-gnu/glibc.git] / manual / users.texi
1 @node Users and Groups
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 Accounting Database::    Keeping information about users and various
46                                  actions in databases.
47
48 * User Database::               Functions and data structures for
49                                  accessing the user database.
50 * Group Database::              Functions and data structures for
51                                  accessing the group database.
52 * Netgroup Database::           Functions for accessing the netgroup database.
53 * Database Example::            Example program showing use of database
54                                  inquiry functions.
55 @end menu
56
57 @node User and Group IDs
58 @section User and Group IDs
59
60 @cindex login name
61 @cindex user name
62 @cindex user ID
63 Each user account on a computer system is identified by a @dfn{user
64 name} (or @dfn{login name}) and @dfn{user ID}.  Normally, each user name
65 has a unique user ID, but it is possible for several login names to have
66 the same user ID.  The user names and corresponding user IDs are stored
67 in a data base which you can access as described in @ref{User Database}.
68
69 @cindex group name
70 @cindex group ID
71 Users are classified in @dfn{groups}.  Each user name also belongs to
72 one or more groups, and has one @dfn{default group}.  Users who are
73 members of the same group can share resources (such as files) that are
74 not accessible to users who are not a member of that group.  Each group
75 has a @dfn{group name} and @dfn{group ID}.  @xref{Group Database},
76 for how to find information about a group ID or group name.
77
78 @node Process Persona
79 @section The Persona of a Process
80 @cindex persona
81 @cindex effective user ID
82 @cindex effective group ID
83
84 @c !!! bogus; not single ID.  set of effective group IDs (and, in GNU,
85 @c set of effective UIDs) determines privilege.  lying here and then
86 @c telling the truth below is confusing.
87 At any time, each process has a single user ID and a group ID which
88 determine the privileges of the process.  These are collectively called
89 the @dfn{persona} of the process, because they determine ``who it is''
90 for purposes of access control.  These IDs are also called the
91 @dfn{effective user ID} and @dfn{effective group ID} of the process.
92
93 Your login shell starts out with a persona which consists of your user
94 ID and your default group ID.
95 @c !!! also supplementary group IDs.
96 In normal circumstances, all your other processes inherit these values.
97
98 @cindex real user ID
99 @cindex real group ID
100 A process also has a @dfn{real user ID} which identifies the user who
101 created the process, and a @dfn{real group ID} which identifies that
102 user's default group.  These values do not play a role in access
103 control, so we do not consider them part of the persona.  But they are
104 also important.
105
106 Both the real and effective user ID can be changed during the lifetime
107 of a process.  @xref{Why Change Persona}.
108
109 @cindex supplementary group IDs
110 In addition, a user can belong to multiple groups, so the persona
111 includes @dfn{supplementary group IDs} that also contribute to access
112 permission.
113
114 For details on how a process's effective user IDs and group IDs affect
115 its permission to access files, see @ref{Access Permission}.
116
117 The user ID of a process also controls permissions for sending signals
118 using the @code{kill} function.  @xref{Signaling Another Process}.
119
120 @node Why Change Persona
121 @section Why Change the Persona of a Process?
122
123 The most obvious situation where it is necessary for a process to change
124 its user and/or group IDs is the @code{login} program.  When
125 @code{login} starts running, its user ID is @code{root}.  Its job is to
126 start a shell whose user and group IDs are those of the user who is
127 logging in.  (To accomplish this fully, @code{login} must set the real
128 user and group IDs as well as its persona.  But this is a special case.)
129
130 The more common case of changing persona is when an ordinary user
131 program needs access to a resource that wouldn't ordinarily be
132 accessible to the user actually running it.
133
134 For example, you may have a file that is controlled by your program but
135 that shouldn't be read or modified directly by other users, either
136 because it implements some kind of locking protocol, or because you want
137 to preserve the integrity or privacy of the information it contains.
138 This kind of restricted access can be implemented by having the program
139 change its effective user or group ID to match that of the resource.
140
141 Thus, imagine a game program that saves scores in a file.  The game
142 program itself needs to be able to update this file no matter who is
143 running it, but if users can write the file without going through the
144 game, they can give themselves any scores they like.  Some people
145 consider this undesirable, or even reprehensible.  It can be prevented
146 by creating a new user ID and login name (say, @code{games}) to own the
147 scores file, and make the file writable only by this user.  Then, when
148 the game program wants to update this file, it can change its effective
149 user ID to be that for @code{games}.  In effect, the program must
150 adopt the persona of @code{games} so it can write the scores file.
151
152 @node How Change Persona
153 @section How an Application Can Change Persona
154 @cindex @code{setuid} programs
155
156 The ability to change the persona of a process can be a source of
157 unintentional privacy violations, or even intentional abuse.  Because of
158 the potential for problems, changing persona is restricted to special
159 circumstances.
160
161 You can't arbitrarily set your user ID or group ID to anything you want;
162 only privileged processes can do that.  Instead, the normal way for a
163 program to change its persona is that it has been set up in advance to
164 change to a particular user or group.  This is the function of the setuid
165 and setgid bits of a file's access mode.  @xref{Permission Bits}.
166
167 When the setuid bit of an executable file is set, executing that file
168 automatically changes the effective user ID to the user that owns the
169 file.  Likewise, executing a file whose setgid bit is set changes the
170 effective group ID to the group of the file.  @xref{Executing a File}.
171 Creating a file that changes to a particular user or group ID thus
172 requires full access to that user or group ID.
173
174 @xref{File Attributes}, for a more general discussion of file modes and
175 accessibility.
176
177 A process can always change its effective user (or group) ID back to its
178 real ID.  Programs do this so as to turn off their special privileges
179 when they are not needed, which makes for more robustness.
180
181 @c !!! talk about _POSIX_SAVED_IDS
182
183 @node Reading Persona
184 @section Reading the Persona of a Process
185
186 Here are detailed descriptions of the functions for reading the user and
187 group IDs of a process, both real and effective.  To use these
188 facilities, you must include the header files @file{sys/types.h} and
189 @file{unistd.h}.
190 @pindex unistd.h
191 @pindex sys/types.h
192
193 @comment sys/types.h
194 @comment POSIX.1
195 @deftp {Data Type} uid_t
196 This is an integer data type used to represent user IDs.  In the GNU
197 library, this is an alias for @code{unsigned int}.
198 @end deftp
199
200 @comment sys/types.h
201 @comment POSIX.1
202 @deftp {Data Type} gid_t
203 This is an integer data type used to represent group IDs.  In the GNU
204 library, this is an alias for @code{unsigned int}.
205 @end deftp
206
207 @comment unistd.h
208 @comment POSIX.1
209 @deftypefun uid_t getuid (void)
210 The @code{getuid} function returns the real user ID of the process.
211 @end deftypefun
212
213 @comment unistd.h
214 @comment POSIX.1
215 @deftypefun gid_t getgid (void)
216 The @code{getgid} function returns the real group ID of the process.
217 @end deftypefun
218
219 @comment unistd.h
220 @comment POSIX.1
221 @deftypefun uid_t geteuid (void)
222 The @code{geteuid} function returns the effective user ID of the process.
223 @end deftypefun
224
225 @comment unistd.h
226 @comment POSIX.1
227 @deftypefun gid_t getegid (void)
228 The @code{getegid} function returns the effective group ID of the process.
229 @end deftypefun
230
231 @comment unistd.h
232 @comment POSIX.1
233 @deftypefun int getgroups (int @var{count}, gid_t *@var{groups})
234 The @code{getgroups} function is used to inquire about the supplementary
235 group IDs of the process.  Up to @var{count} of these group IDs are
236 stored in the array @var{groups}; the return value from the function is
237 the number of group IDs actually stored.  If @var{count} is smaller than
238 the total number of supplementary group IDs, then @code{getgroups}
239 returns a value of @code{-1} and @code{errno} is set to @code{EINVAL}.
240
241 If @var{count} is zero, then @code{getgroups} just returns the total
242 number of supplementary group IDs.  On systems that do not support
243 supplementary groups, this will always be zero.
244
245 Here's how to use @code{getgroups} to read all the supplementary group
246 IDs:
247
248 @smallexample
249 @group
250 gid_t *
251 read_all_groups (void)
252 @{
253   int ngroups = getgroups (0, NULL);
254   gid_t *groups
255     = (gid_t *) xmalloc (ngroups * sizeof (gid_t));
256   int val = getgroups (ngroups, groups);
257   if (val < 0)
258     @{
259       free (groups);
260       return NULL;
261     @}
262   return groups;
263 @}
264 @end group
265 @end smallexample
266 @end deftypefun
267
268 @node Setting User ID
269 @section Setting the User ID
270
271 This section describes the functions for altering the user ID (real
272 and/or effective) of a process.  To use these facilities, you must
273 include the header files @file{sys/types.h} and @file{unistd.h}.
274 @pindex unistd.h
275 @pindex sys/types.h
276
277 @comment unistd.h
278 @comment POSIX.1
279 @deftypefun int setuid (uid_t @var{newuid})
280 This function sets both the real and effective user ID of the process
281 to @var{newuid}, provided that the process has appropriate privileges.
282 @c !!! also sets saved-id
283
284 If the process is not privileged, then @var{newuid} must either be equal
285 to the real user ID or the saved user ID (if the system supports the
286 @code{_POSIX_SAVED_IDS} feature).  In this case, @code{setuid} sets only
287 the effective user ID and not the real user ID.
288 @c !!! xref to discussion of _POSIX_SAVED_IDS
289
290 The @code{setuid} function returns a value of @code{0} to indicate
291 successful completion, and a value of @code{-1} to indicate an error.
292 The following @code{errno} error conditions are defined for this
293 function:
294
295 @table @code
296 @item EINVAL
297 The value of the @var{newuid} argument is invalid.
298
299 @item EPERM
300 The process does not have the appropriate privileges; you do not
301 have permission to change to the specified ID.
302 @end table
303 @end deftypefun
304
305 @comment unistd.h
306 @comment BSD
307 @deftypefun int setreuid (uid_t @var{ruid}, uid_t @var{euid})
308 This function sets the real user ID of the process to @var{ruid} and the
309 effective user ID to @var{euid}.  If @var{ruid} is @code{-1}, it means
310 not to change the real user ID; likewise if @var{euid} is @code{-1}, it
311 means not to change the effective user ID.
312
313 The @code{setreuid} function exists for compatibility with 4.3 BSD Unix,
314 which does not support saved IDs.  You can use this function to swap the
315 effective and real user IDs of the process.  (Privileged processes are
316 not limited to this particular usage.)  If saved IDs are supported, you
317 should use that feature instead of this function.  @xref{Enable/Disable
318 Setuid}.
319
320 The return value is @code{0} on success and @code{-1} on failure.
321 The following @code{errno} error conditions are defined for this
322 function:
323
324 @table @code
325 @item EPERM
326 The process does not have the appropriate privileges; you do not
327 have permission to change to the specified ID.
328 @end table
329 @end deftypefun
330
331 @node Setting Groups
332 @section Setting the Group IDs
333
334 This section describes the functions for altering the group IDs (real
335 and effective) of a process.  To use these facilities, you must include
336 the header files @file{sys/types.h} and @file{unistd.h}.
337 @pindex unistd.h
338 @pindex sys/types.h
339
340 @comment unistd.h
341 @comment POSIX.1
342 @deftypefun int setgid (gid_t @var{newgid})
343 This function sets both the real and effective group ID of the process
344 to @var{newgid}, provided that the process has appropriate privileges.
345 @c !!! also sets saved-id
346
347 If the process is not privileged, then @var{newgid} must either be equal
348 to the real group ID or the saved group ID.  In this case, @code{setgid}
349 sets only the effective group ID and not the real group ID.
350
351 The return values and error conditions for @code{setgid} are the same
352 as those for @code{setuid}.
353 @end deftypefun
354
355 @comment unistd.h
356 @comment BSD
357 @deftypefun int setregid (gid_t @var{rgid}, fid_t @var{egid})
358 This function sets the real group ID of the process to @var{rgid} and
359 the effective group ID to @var{egid}.  If @var{rgid} is @code{-1}, it
360 means not to change the real group ID; likewise if @var{egid} is
361 @code{-1}, it means not to change the effective group ID.
362
363 The @code{setregid} function is provided for compatibility with 4.3 BSD
364 Unix, which does not support saved IDs.  You can use this function to
365 swap the effective and real group IDs of the process.  (Privileged
366 processes are not limited to this usage.)  If saved IDs are supported,
367 you should use that feature instead of using this function.
368 @xref{Enable/Disable Setuid}.
369
370 The return values and error conditions for @code{setregid} are the same
371 as those for @code{setreuid}.
372 @end deftypefun
373
374 The GNU system also lets privileged processes change their supplementary
375 group IDs.  To use @code{setgroups} or @code{initgroups}, your programs
376 should include the header file @file{grp.h}.
377 @pindex grp.h
378
379 @comment grp.h
380 @comment BSD
381 @deftypefun int setgroups (size_t @var{count}, gid_t *@var{groups})
382 This function sets the process's supplementary group IDs.  It can only
383 be called from privileged processes.  The @var{count} argument specifies
384 the number of group IDs in the array @var{groups}.
385
386 This function returns @code{0} if successful and @code{-1} on error.
387 The following @code{errno} error conditions are defined for this
388 function:
389
390 @table @code
391 @item EPERM
392 The calling process is not privileged.
393 @end table
394 @end deftypefun
395
396 @comment grp.h
397 @comment BSD
398 @deftypefun int initgroups (const char *@var{user}, gid_t @var{gid})
399 The @code{initgroups} function effectively calls @code{setgroups} to
400 set the process's supplementary group IDs to be the normal default for
401 the user name @var{user}.  The group ID @var{gid} is also included.
402 @c !!! explain that this works by reading the group file looking for
403 @c groups USER is a member of.
404 @end deftypefun
405
406 @node Enable/Disable Setuid
407 @section Enabling and Disabling Setuid Access
408
409 A typical setuid program does not need its special access all of the
410 time.  It's a good idea to turn off this access when it isn't needed,
411 so it can't possibly give unintended access.
412
413 If the system supports the saved user ID feature, you can accomplish
414 this with @code{setuid}.  When the game program starts, its real user ID
415 is @code{jdoe}, its effective user ID is @code{games}, and its saved
416 user ID is also @code{games}.  The program should record both user ID
417 values once at the beginning, like this:
418
419 @smallexample
420 user_user_id = getuid ();
421 game_user_id = geteuid ();
422 @end smallexample
423
424 Then it can turn off game file access with
425
426 @smallexample
427 setuid (user_user_id);
428 @end smallexample
429
430 @noindent
431 and turn it on with
432
433 @smallexample
434 setuid (game_user_id);
435 @end smallexample
436
437 @noindent
438 Throughout this process, the real user ID remains @code{jdoe} and the
439 saved user ID remains @code{games}, so the program can always set its
440 effective user ID to either one.
441
442 On other systems that don't support the saved user ID feature, you can
443 turn setuid access on and off by using @code{setreuid} to swap the real
444 and effective user IDs of the process, as follows:
445
446 @smallexample
447 setreuid (geteuid (), getuid ());
448 @end smallexample
449
450 @noindent
451 This special case is always allowed---it cannot fail.
452
453 Why does this have the effect of toggling the setuid access?  Suppose a
454 game program has just started, and its real user ID is @code{jdoe} while
455 its effective user ID is @code{games}.  In this state, the game can
456 write the scores file.  If it swaps the two uids, the real becomes
457 @code{games} and the effective becomes @code{jdoe}; now the program has
458 only @code{jdoe} access.  Another swap brings @code{games} back to
459 the effective user ID and restores access to the scores file.
460
461 In order to handle both kinds of systems, test for the saved user ID
462 feature with a preprocessor conditional, like this:
463
464 @smallexample
465 #ifdef _POSIX_SAVED_IDS
466   setuid (user_user_id);
467 #else
468   setreuid (geteuid (), getuid ());
469 #endif
470 @end smallexample
471
472 @node Setuid Program Example
473 @section Setuid Program Example
474
475 Here's an example showing how to set up a program that changes its
476 effective user ID.
477
478 This is part of a game program called @code{caber-toss} that
479 manipulates a file @file{scores} that should be writable only by the game
480 program itself.  The program assumes that its executable
481 file will be installed with the set-user-ID bit set and owned by the
482 same user as the @file{scores} file.  Typically, a system
483 administrator will set up an account like @code{games} for this purpose.
484
485 The executable file is given mode @code{4755}, so that doing an
486 @samp{ls -l} on it produces output like:
487
488 @smallexample
489 -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss
490 @end smallexample
491
492 @noindent
493 The set-user-ID bit shows up in the file modes as the @samp{s}.
494
495 The scores file is given mode @code{644}, and doing an @samp{ls -l} on
496 it shows:
497
498 @smallexample
499 -rw-r--r--  1 games           0 Jul 31 15:33 scores
500 @end smallexample
501
502 Here are the parts of the program that show how to set up the changed
503 user ID.  This program is conditionalized so that it makes use of the
504 saved IDs feature if it is supported, and otherwise uses @code{setreuid}
505 to swap the effective and real user IDs.
506
507 @smallexample
508 #include <stdio.h>
509 #include <sys/types.h>
510 #include <unistd.h>
511 #include <stdlib.h>
512
513
514 /* @r{Save the effective and real UIDs.} */
515
516 static uid_t euid, ruid;
517
518
519 /* @r{Restore the effective UID to its original value.} */
520
521 void
522 do_setuid (void)
523 @{
524   int status;
525
526 #ifdef _POSIX_SAVED_IDS
527   status = setuid (euid);
528 #else
529   status = setreuid (ruid, euid);
530 #endif
531   if (status < 0) @{
532     fprintf (stderr, "Couldn't set uid.\n");
533     exit (status);
534     @}
535 @}
536
537
538 @group
539 /* @r{Set the effective UID to the real UID.} */
540
541 void
542 undo_setuid (void)
543 @{
544   int status;
545
546 #ifdef _POSIX_SAVED_IDS
547   status = setuid (ruid);
548 #else
549   status = setreuid (euid, ruid);
550 #endif
551   if (status < 0) @{
552     fprintf (stderr, "Couldn't set uid.\n");
553     exit (status);
554     @}
555 @}
556 @end group
557
558 /* @r{Main program.} */
559
560 int
561 main (void)
562 @{
563   /* @r{Save the real and effective user IDs.}  */
564   ruid = getuid ();
565   euid = geteuid ();
566   undo_setuid ();
567
568   /* @r{Do the game and record the score.}  */
569   @dots{}
570 @}
571 @end smallexample
572
573 Notice how the first thing the @code{main} function does is to set the
574 effective user ID back to the real user ID.  This is so that any other
575 file accesses that are performed while the user is playing the game use
576 the real user ID for determining permissions.  Only when the program
577 needs to open the scores file does it switch back to the original
578 effective user ID, like this:
579
580 @smallexample
581 /* @r{Record the score.} */
582
583 int
584 record_score (int score)
585 @{
586   FILE *stream;
587   char *myname;
588
589   /* @r{Open the scores file.} */
590   do_setuid ();
591   stream = fopen (SCORES_FILE, "a");
592   undo_setuid ();
593
594 @group
595   /* @r{Write the score to the file.} */
596   if (stream)
597     @{
598       myname = cuserid (NULL);
599       if (score < 0)
600         fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
601       else
602         fprintf (stream, "%10s: %d feet.\n", myname, score);
603       fclose (stream);
604       return 0;
605     @}
606   else
607     return -1;
608 @}
609 @end group
610 @end smallexample
611
612 @node Tips for Setuid
613 @section Tips for Writing Setuid Programs
614
615 It is easy for setuid programs to give the user access that isn't
616 intended---in fact, if you want to avoid this, you need to be careful.
617 Here are some guidelines for preventing unintended access and
618 minimizing its consequences when it does occur:
619
620 @itemize @bullet
621 @item
622 Don't have @code{setuid} programs with privileged user IDs such as
623 @code{root} unless it is absolutely necessary.  If the resource is
624 specific to your particular program, it's better to define a new,
625 nonprivileged user ID or group ID just to manage that resource.
626
627 @item
628 Be cautious about using the @code{system} and @code{exec} functions in
629 combination with changing the effective user ID.  Don't let users of
630 your program execute arbitrary programs under a changed user ID.
631 Executing a shell is especially bad news.  Less obviously, the
632 @code{execlp} and @code{execvp} functions are a potential risk (since
633 the program they execute depends on the user's @code{PATH} environment
634 variable).
635
636 If you must @code{exec} another program under a changed ID, specify an
637 absolute file name (@pxref{File Name Resolution}) for the executable,
638 and make sure that the protections on that executable and @emph{all}
639 containing directories are such that ordinary users cannot replace it
640 with some other program.
641
642 @item
643 Only use the user ID controlling the resource in the part of the program
644 that actually uses that resource.  When you're finished with it, restore
645 the effective user ID back to the actual user's user ID.
646 @xref{Enable/Disable Setuid}.
647
648 @item
649 If the @code{setuid} part of your program needs to access other files
650 besides the controlled resource, it should verify that the real user
651 would ordinarily have permission to access those files.  You can use the
652 @code{access} function (@pxref{Access Permission}) to check this; it
653 uses the real user and group IDs, rather than the effective IDs.
654 @end itemize
655
656 @node Who Logged In
657 @section Identifying Who Logged In
658 @cindex login name, determining
659 @cindex user ID, determining
660
661 You can use the functions listed in this section to determine the login
662 name of the user who is running a process, and the name of the user who
663 logged in the current session.  See also the function @code{getuid} and
664 friends (@pxref{Reading Persona}).  How this information is collected by
665 the system and how to control/add/remove information from the background
666 storage is described in @ref{User Accounting Database}.
667
668 The @code{getlogin} function is declared in @file{unistd.h}, while
669 @code{cuserid} and @code{L_cuserid} are declared in @file{stdio.h}.
670 @pindex stdio.h
671 @pindex unistd.h
672
673 @comment unistd.h
674 @comment POSIX.1
675 @deftypefun {char *} getlogin (void)
676 The @code{getlogin} function returns a pointer to a string containing the
677 name of the user logged in on the controlling terminal of the process,
678 or a null pointer if this information cannot be determined.  The string
679 is statically allocated and might be overwritten on subsequent calls to
680 this function or to @code{cuserid}.
681 @end deftypefun
682
683 @comment stdio.h
684 @comment POSIX.1
685 @deftypefun {char *} cuserid (char *@var{string})
686 The @code{cuserid} function returns a pointer to a string containing a
687 user name associated with the effective ID of the process.  If
688 @var{string} is not a null pointer, it should be an array that can hold
689 at least @code{L_cuserid} characters; the string is returned in this
690 array.  Otherwise, a pointer to a string in a static area is returned.
691 This string is statically allocated and might be overwritten on
692 subsequent calls to this function or to @code{getlogin}.
693
694 The use of this function is deprecated since it is marked to be
695 withdrawn in XPG4.2 and it is already removed in POSIX.1.
696 @end deftypefun
697
698 @comment stdio.h
699 @comment POSIX.1
700 @deftypevr Macro int L_cuserid
701 An integer constant that indicates how long an array you might need to
702 store a user name.
703 @end deftypevr
704
705 These functions let your program identify positively the user who is
706 running or the user who logged in this session.  (These can differ when
707 setuid programs are involved; @xref{Process Persona}.)  The user cannot
708 do anything to fool these functions.
709
710 For most purposes, it is more useful to use the environment variable
711 @code{LOGNAME} to find out who the user is.  This is more flexible
712 precisely because the user can set @code{LOGNAME} arbitrarily.
713 @xref{Standard Environment}.
714
715
716 @node User Accounting Database
717 @section The User Accounting Database
718 @cindex user accounting database
719
720 Most Unix-like operating systems keep track of logged in users by
721 maintaining a user accounting database.  This user accounting database
722 stores for each terminal, who has logged on, at what time, the process
723 ID of the user's login shell, etc., etc., but also stores information
724 about the run level of the system, the time of the last system reboot,
725 and possibly more.
726
727 The user accounting database typically lives in @file{/etc/utmp},
728 @file{/var/adm/utmp} or @file{/var/run/utmp}.  However, these files
729 should @strong{never} be accessed directly.  For reading information
730 from and writing information to the user accounting database, the
731 functions described in this section should be used.
732
733
734 @menu
735 * Manipulating the Database::   Scanning and modifying the user
736                                  accounting database.
737 * XPG Functions::               A standardized way for doing the same thing.
738 * Logging In and Out::          Functions from BSD that modify the user
739                                  accounting database.
740 @end menu
741
742 @node Manipulating the Database
743 @subsection Manipulating the User Accounting Database
744
745 These functions and the corresponding data structures are declared in
746 the header file @file{utmp.h}.
747 @pindex utmp.h
748
749 @comment utmp.h
750 @comment SVID
751 @deftp {Data Type} {struct exit_status}
752 The @code{exit_status} data structure is used to hold information about
753 the exit status of processes marked as @code{DEAD_PROCESS} in the user
754 accounting database.
755
756 @table @code
757 @item short int e_termination
758 The exit status of the process.
759
760 @item short int e_exit
761 The exit status of the process.
762 @end table
763 @end deftp
764
765 @deftp {Data Type} {struct utmp}
766 The @code{utmp} data structure is used to hold information about entries
767 in the user accounting database.  On the GNU system it has the following
768 members:
769
770 @table @code
771 @item short int ut_type
772 Specifies the type of login; one of @code{EMPTY}, @code{RUN_LVL},
773 @code{BOOT_TIME}, @code{OLD_TIME}, @code{NEW_TIME}, @code{INIT_PROCESS},
774 @code{LOGIN_PROCESS}, @code{USER_PROCESS}, @code{DEAD_PROCESS} or
775 @code{ACCOUNTING}.
776
777 @item pid_t ut_pid
778 The process ID number of the login process.
779
780 @item char ut_line[]
781 The device name of the tty (without @file{/dev/}).
782
783 @item char ut_id[]
784 The inittab ID of the process.
785
786 @item char ut_user[]
787 The user's login name.
788
789 @item char ut_host[]
790 The name of the host from which the user logged in.
791
792 @item struct exit_status ut_exit
793 The exit status of a process marked as @code{DEAD_PROCESS}.
794
795 @item long ut_session
796 The Session ID, used for windowing.
797
798 @item struct timeval ut_tv
799 Time the entry was made.  For entries of type @code{OLD_TIME} this is
800 the time when the system clock changed, and for entries of type
801 @code{NEW_TIME} this is the time the system clock was set to.
802
803 @item int32_t ut_addr_v6[4]
804 The Internet address of a remote host.
805 @end table
806 @end deftp
807
808 The @code{ut_type}, @code{ut_pid}, @code{ut_id}, @code{ut_tv}, and
809 @code{ut_host} fields are not available on all systems.  Portable
810 applications therefore should be prepared for these situations.  To help
811 doing this the @file{utmp.h} header provides macros
812 @code{_HAVE_UT_TYPE}, @code{_HAVE_UT_PID}, @code{_HAVE_UT_ID},
813 @code{_HAVE_UT_TV}, and @code{_HAVE_UT_HOST} if the respective field is
814 available.  The programmer can handle the situations by using
815 @code{#ifdef} in the program code.
816
817 The following macros are defined for use as values for the
818 @code{ut_type} member of the @code{utmp} structure.  The values are
819 integer constants.
820
821 @table @code
822 @comment utmp.h
823 @comment SVID
824 @vindex EMPTY
825 @item EMPTY
826 This macro is used to indicate that the entry contains no valid user
827 accounting information.
828
829 @comment utmp.h
830 @comment SVID
831 @vindex RUN_LVL
832 @item RUN_LVL
833 This macro is used to identify the systems runlevel.
834
835 @comment utmp.h
836 @comment SVID
837 @vindex BOOT_TIME
838 @item BOOT_TIME
839 This macro is used to identify the time of system boot.
840
841 @comment utmp.h
842 @comment SVID
843 @vindex OLD_TIME
844 @item OLD_TIME
845 This macro is used to identify the time when the system clock changed.
846
847 @comment utmp.h
848 @comment SVID
849 @vindex NEW_TIME
850 @item NEW_TIME
851 This macro is used to identify the time after the system changed.
852
853 @comment utmp.h
854 @comment SVID
855 @vindex INIT_PROCESS
856 @item INIT_PROCESS
857 This macro is used to identify a process spawned by the init process.
858
859 @comment utmp.h
860 @comment SVID
861 @vindex LOGIN_PROCESS
862 @item LOGIN_PROCESS
863 This macro is used to identify the session leader of a logged in user.
864
865 @comment utmp.h
866 @comment SVID
867 @vindex USER_PROCESS
868 @item USER_PROCESS
869 This macro is used to identify a user process.
870
871 @comment utmp.h
872 @comment SVID
873 @vindex DEAD_PROCESS
874 @item DEAD_PROCESS
875 This macro is used to identify a terminated process.
876
877 @comment utmp.h
878 @comment SVID
879 @vindex ACCOUNTING
880 @item ACCOUNTING
881 ???
882 @end table
883
884 The size of the @code{ut_line}, @code{ut_id}, @code{ut_user} and
885 @code{ut_host} arrays can be found using the @code{sizeof} operator.
886
887 Many older systems have, instead of an @code{ut_tv} member, an
888 @code{ut_time} member, usually of type @code{time_t}, for representing
889 the time associated with the entry.  Therefore, for backwards
890 compatibility only, @file{utmp.h} defines @code{ut_time} as an alias for
891 @code{ut_tv.tv_sec}.
892
893 @comment utmp.h
894 @comment SVID
895 @deftypefun void setutent (void)
896 This function opens the user accounting database to begin scanning it.
897 You can then call @code{getutent}, @code{getutid} or @code{getutline} to
898 read entries and @code{pututline} to write entries.
899
900 If the database is already open, it resets the input to the beginning of
901 the database.
902 @end deftypefun
903
904 @comment utmp.h
905 @comment SVID
906 @deftypefun {struct utmp *} getutent (void)
907 The @code{getutent} function reads the next entry from the user
908 accounting database.  It returns a pointer to the entry, which is
909 statically allocated and may be overwritten by subsequent calls to
910 @code{getutent}.  You must copy the contents of the structure if you
911 wish to save the information or you can use the @code{getutent_r}
912 function which stores the data in a user-provided buffer.
913
914 A null pointer is returned in case no further entry is available.
915 @end deftypefun
916
917 @comment utmp.h
918 @comment SVID
919 @deftypefun void endutent (void)
920 This function closes the user accounting database.
921 @end deftypefun
922
923 @comment utmp.h
924 @comment SVID
925 @deftypefun {struct utmp *} getutid (const struct utmp *@var{id})
926 This function searches forward from the current point in the database
927 for an entry that matches @var{id}.  If the @code{ut_type} member of the
928 @var{id} structure is one of @code{RUN_LVL}, @code{BOOT_TIME},
929 @code{OLD_TIME} or @code{NEW_TIME} the entries match if the
930 @code{ut_type} members are identical.  If the @code{ut_type} member of
931 the @var{id} structure is @code{INIT_PROCESS}, @code{LOGIN_PROCESS},
932 @code{USER_PROCESS} or @code{DEAD_PROCESS}, the entries match if the the
933 @code{ut_type} member of the entry read from the database is one of
934 these four, and the @code{ut_id} members match.  However if the
935 @code{ut_id} member of either the @var{id} structure or the entry read
936 from the database is empty it checks if the @code{ut_line} members match
937 instead.  If a matching entry is found, @code{getutid} returns a pointer
938 to the entry, which is statically allocated, and may be overwritten by a
939 subsequent call to @code{getutent}, @code{getutid} or @code{getutline}.
940 You must copy the contents of the structure if you wish to save the
941 information.
942
943 A null pointer is returned in case the end of the database is reached
944 without a match.
945
946 The @code{getutid} function may cache the last read entry.  Therefore,
947 if you are using @code{getutid} to search for multiple occurrences, it
948 is necessary to zero out the static data after each call.  Otherwise
949 @code{getutid} could just return a pointer to the same entry over and
950 over again.
951 @end deftypefun
952
953 @comment utmp.h
954 @comment SVID
955 @deftypefun {struct utmp *} getutline (const struct utmp *@var{line})
956 This function searches forward from the current point in the database
957 until it finds an entry whose @code{ut_type} value is
958 @code{LOGIN_PROCESS} or @code{USER_PROCESS}, and whose @code{ut_line}
959 member matches the @code{ut_line} member of the @var{line} structure.
960 If it finds such an entry, it returns a pointer to the entry which is
961 statically allocated, and may be overwritten by a subsequent call to
962 @code{getutent}, @code{getutid} or @code{getutline}.  You must copy the
963 contents of the structure if you wish to save the information.
964
965 A null pointer is returned in case the end of the database is reached
966 without a match.
967
968 The @code{getutline} function may cache the last read entry.  Therefore
969 if you are using @code{getutline} to search for multiple occurrences, it
970 is necessary to zero out the static data after each call.  Otherwise
971 @code{getutline} could just return a pointer to the same entry over and
972 over again.
973 @end deftypefun
974
975 @comment utmp.h
976 @comment SVID
977 @deftypefun {struct utmp *} pututline (const struct utmp *@var{utmp})
978 The @code{pututline} function inserts the entry @code{*@var{utmp}} at
979 the appropriate place in the user accounting database.  If it finds that
980 it is not already at the correct place in the database, it uses
981 @code{getutid} to search for the position to insert the entry, however
982 this will not modify the static structure returned by @code{getutent},
983 @code{getutid} and @code{getutline}.  If this search fails, the entry
984 is appended to the database.
985
986 The @code{pututline} function returns a pointer to a copy of the entry
987 inserted in the user accounting database, or a null pointer if the entry
988 could not be added.  The following @code{errno} error conditions are
989 defined for this function:
990
991 @table @code
992 @item EPERM
993 The process does not have the appropriate privileges; you cannot modify
994 the user accounting database.
995 @end table
996 @end deftypefun
997
998 All the @code{get*} functions mentioned before store the information
999 they return in a static buffer.  This can be a problem in multi-threaded
1000 programs since the data return for the request is overwritten be the
1001 return value data in another thread.  Therefore the GNU C Library
1002 provides as extensions three more functions which return the data in a
1003 user-provided buffer.
1004
1005 @comment utmp.h
1006 @comment GNU
1007 @deftypefun int getutent_r (struct utmp *@var{buffer}, struct utmp **@var{result})
1008 The @code{getutent_r} is equivalent to the @code{getutent} function.  It
1009 returns the next entry from the database.  But instead of storing the
1010 information in a static buffer it stores it in the buffer pointed to by
1011 the parameter @var{buffer}.
1012
1013 If the call was successful, the function returns @code{0} and the
1014 pointer variable pointed to by the parameter @var{result} contains a
1015 pointer to the buffer which contains the result (this is most probably
1016 the same value as @var{buffer}).  If something went wrong during the
1017 execution of @code{getutent_r} the function returns @code{-1}.
1018
1019 This function is a GNU extension.
1020 @end deftypefun
1021
1022 @comment utmp.h
1023 @comment GNU
1024 @deftypefun int getutid_r (const struct utmp *@var{id}, struct utmp *@var{buffer}, struct utmp **@var{result})
1025 This function retrieves just like @code{getutid} the next entry matching
1026 the information stored in @var{id}.  But the result is stored in the
1027 buffer pointed to by the parameter @var{buffer}.
1028
1029 If successful the function returns @code{0} and the pointer variable
1030 pointed to by the parameter @var{result} contains a pointer to the
1031 buffer with the result (probably the same as @var{result}.  If not
1032 successful the function return @code{-1}.
1033
1034 This function is a GNU extension.
1035 @end deftypefun
1036
1037 @comment utmp.h
1038 @comment GNU
1039 @deftypefun int getutline_r (const struct utmp *@var{line}, struct utmp *@var{buffer}, struct utmp **@var{result})
1040 This function retrieves just like @code{getutline} the next entry
1041 matching the information stored in @var{line}.  But the result is stored
1042 in the buffer pointed to by the parameter @var{buffer}.
1043
1044 If successful the function returns @code{0} and the pointer variable
1045 pointed to by the parameter @var{result} contains a pointer to the
1046 buffer with the result (probably the same as @var{result}.  If not
1047 successful the function return @code{-1}.
1048
1049 This function is a GNU extension.
1050 @end deftypefun
1051
1052
1053 In addition to the user accounting database, most systems keep a number
1054 of similar databases.  For example most systems keep a log file with all
1055 previous logins (usually in @file{/etc/wtmp} or @file{/var/log/wtmp}).
1056
1057 For specifying which database to examine, the following function should
1058 be used.
1059
1060 @comment utmp.h
1061 @comment SVID
1062 @deftypefun int utmpname (const char *@var{file})
1063 The @code{utmpname} function changes the name of the database to be
1064 examined to @var{file}, and closes any previously opened database.  By
1065 default @code{getutent}, @code{getutid}, @code{getutline} and
1066 @code{pututline} read from and write to the user accounting database.
1067
1068 The following macros are defined for use as the @var{file} argument:
1069
1070 @deftypevr Macro {char *} _PATH_UTMP
1071 This macro is used to specify the user accounting database.
1072 @end deftypevr
1073
1074 @deftypevr Macro {char *} _PATH_WTMP
1075 This macro is used to specify the user accounting log file.
1076 @end deftypevr
1077
1078 The @code{utmpname} function returns a value of @code{0} if the new name
1079 was successfully stored, and a value of @code{-1} to indicate an error.
1080 Note that @code{utmpname} does not try open the database, and that
1081 therefore the return value does not say anything about whether the
1082 database can be successfully opened.
1083 @end deftypefun
1084
1085 Specially for maintaining log-like databases the GNU C Library provides
1086 the following function:
1087
1088 @comment utmp.h
1089 @comment SVID
1090 @deftypefun void updwtmp (const char *@var{wtmp_file}, const struct utmp *@var{utmp})
1091 The @code{updwtmp} function appends the entry *@var{utmp} to the
1092 database specified by @var{wtmp_file}.  For possible values for the
1093 @var{wtmp_file} argument see the @code{utmpname} function.
1094 @end deftypefun
1095
1096 @strong{Portability Note:} Although many operating systems provide a
1097 subset of these functions, they are not standardized.  There are often
1098 subtle differences in the return types, and there are considerable
1099 differences between the various definitions of @code{struct utmp}.  When
1100 programming for the GNU system, it is probably probably best to stick
1101 with the functions described in this section.  If however, you want your
1102 program to be portable, consider using the XPG functions described in
1103 @ref{XPG Functions}, or take a look at the BSD compatible functions in
1104 @ref{Logging In and Out}.
1105
1106
1107 @node XPG Functions
1108 @subsection XPG User Accounting Database Functions
1109
1110 These functions, described in the X/Open Portability Guide, are declared
1111 in the header file @file{utmpx.h}.
1112 @pindex utmpx.h
1113
1114 @deftp {Data Type} {struct utmpx}
1115 The @code{utmpx} data structure contains at least the following members:
1116
1117 @table @code
1118 @item short int ut_type
1119 Specifies the type of login; one of @code{EMPTY}, @code{RUN_LVL},
1120 @code{BOOT_TIME}, @code{OLD_TIME}, @code{NEW_TIME}, @code{INIT_PROCESS},
1121 @code{LOGIN_PROCESS}, @code{USER_PROCESS} or @code{DEAD_PROCESS}.
1122
1123 @item pid_t ut_pid
1124 The process ID number of the login process.
1125
1126 @item char ut_line[]
1127 The device name of the tty (without @file{/dev/}).
1128
1129 @item char ut_id[]
1130 The inittab ID of the process.
1131
1132 @item char ut_user[]
1133 The user's login name.
1134
1135 @item struct timeval ut_tv
1136 Time the entry was made.  For entries of type @code{OLD_TIME} this is
1137 the time when the system clock changed, and for entries of type
1138 @code{NEW_TIME} this is the time the system clock was set to.
1139 @end table
1140 On the GNU system, @code{struct utmpx} is identical to @code{struct
1141 utmp} except for the fact that including @file{utmpx.h} does not make
1142 visible the declaration of @code{struct exit_status}.
1143 @end deftp
1144
1145 The following macros are defined for use as values for the
1146 @code{ut_type} member of the @code{utmpx} structure.  The values are
1147 integer constants and are, on the GNU system, identical to the
1148 definitions in @file{utmp.h}.
1149
1150 @table @code
1151 @comment utmpx.h
1152 @comment XPG4.2
1153 @vindex EMPTY
1154 @item EMPTY
1155 This macro is used to indicate that the entry contains no valid user
1156 accounting information.
1157
1158 @comment utmpx.h
1159 @comment XPG4.2
1160 @vindex RUN_LVL
1161 @item RUN_LVL
1162 This macro is used to identify the systems runlevel.
1163
1164 @comment utmpx.h
1165 @comment XPG4.2
1166 @vindex BOOT_TIME
1167 @item BOOT_TIME
1168 This macro is used to identify the time of system boot.
1169
1170 @comment utmpx.h
1171 @comment XPG4.2
1172 @vindex OLD_TIME
1173 @item OLD_TIME
1174 This macro is used to identify the time when the system clock changed.
1175
1176 @comment utmpx.h
1177 @comment XPG4.2
1178 @vindex NEW_TIME
1179 @item NEW_TIME
1180 This macro is used to identify the time after the system changed.
1181
1182 @comment utmpx.h
1183 @comment XPG4.2
1184 @vindex INIT_PROCESS
1185 @item INIT_PROCESS
1186 This macro is used to identify a process spawned by the init process.
1187
1188 @comment utmpx.h
1189 @comment XPG4.2
1190 @vindex LOGIN_PROCESS
1191 @item LOGIN_PROCESS
1192 This macro is used to identify the session leader of a logged in user.
1193
1194 @comment utmpx.h
1195 @comment XPG4.2
1196 @vindex USER_PROCESS
1197 @item USER_PROCESS
1198 This macro is used to identify a user process.
1199
1200 @comment utmpx.h
1201 @comment XPG4.2
1202 @vindex DEAD_PROCESS
1203 @item DEAD_PROCESS
1204 This macro is used to identify a terminated process.
1205 @end table
1206
1207 The size of the @code{ut_line}, @code{ut_id} and @code{ut_user} arrays
1208 can be found using the @code{sizeof} operator.
1209
1210 @comment utmpx.h
1211 @comment XPG4.2
1212 @deftypefun void setutxent (void)
1213 This function is similar to @code{setutent}.  On the GNU system it is
1214 simply an alias for @code{setutent}.
1215 @end deftypefun
1216
1217 @comment utmpx.h
1218 @comment XPG4.2
1219 @deftypefun {struct utmpx *} getutxent (void)
1220 The @code{getutxent} function is similar to @code{getutent}, but returns
1221 a pointer to a @code{struct utmpx} instead of @code{struct utmp}.  On
1222 the GNU system it simply is an alias for @code{getutent}.
1223 @end deftypefun
1224
1225 @comment utmpx.h
1226 @comment XPG4.2
1227 @deftypefun void endutxent (void)
1228 This function is similar to @code{endutent}.  On the GNU system it is
1229 simply an alias for @code{endutent}.
1230 @end deftypefun
1231
1232 @comment utmpx.h
1233 @comment XPG4.2
1234 @deftypefun {struct utmpx *} getutxid (const struct utmpx *@var{id})
1235 This function is similar to @code{getutid}, but uses @code{struct utmpx}
1236 instead of @code{struct utmp}.  On the GNU system it is simply an alias
1237 for @code{getutid}.
1238 @end deftypefun
1239
1240 @comment utmpx.h
1241 @comment XPG4.2
1242 @deftypefun {struct utmpx *} getutxline (const struct utmpx *@var{line})
1243 This function is similar to @code{getutid}, but uses @code{struct utmpx}
1244 instead of @code{struct utmp}.  On the GNU system it is simply an alias
1245 for @code{getutline}.
1246 @end deftypefun
1247
1248 @comment utmpx.h
1249 @comment XPG4.2
1250 @deftypefun {struct utmpx *} pututxline (const struct utmpx *@var{utmp})
1251 The @code{pututxline} function provides functionality identical to
1252 @code{pututline}, but uses @code{struct utmpx} instead of @code{struct
1253 utmp}.  On the GNU system @code{pututxline} is simply an alias for
1254 @code{pututline}.
1255 @end deftypefun
1256
1257
1258 @node Logging In and Out
1259 @subsection Logging In and Out
1260
1261 These functions, derived from BSD, are available in the separate
1262 @file{libutil} library, and declared in @file{utmp.h}.
1263 @pindex utmp.h
1264
1265 Note that the @code{ut_user} member of @code{struct utmp} is called
1266 @code{ut_name} in BSD.  Therefore, @code{ut_name} is defined as an alias
1267 for @code{ut_user} in @file{utmp.h}.
1268
1269 @comment utmp.h
1270 @comment BSD
1271 @deftypefun int login_tty (int @var{filedes})
1272 This function makes @var{filedes} the controlling terminal of the
1273 current process, redirects standard input, standard output and
1274 standard error output to this terminal, and closes @var{filedes}.
1275
1276 This function returns @code{0} on successful completion, and @code{-1}
1277 on error.
1278 @end deftypefun
1279
1280 @comment utmp.h
1281 @comment BSD
1282 @deftypefun void login (const struct utmp *@var{entry})
1283 The @code{login} functions inserts an entry into the user accounting
1284 database.  The @code{ut_line} member is set to the name of the terminal
1285 on standard input.  If standard input is not a terminal @code{login}
1286 uses standard output or standard error output to determine the name of
1287 the terminal.  If @code{struct utmp} has a @code{ut_type} member,
1288 @code{login} sets it to @code{USER_PROCESS}, and if there is an
1289 @code{ut_pid} member, it will be set to the process ID of the current
1290 process.  The remaining entries are copied from @var{entry}.
1291
1292 A copy of the entry is written to the user accounting log file.
1293 @end deftypefun
1294
1295 @comment utmp.h
1296 @comment BSD
1297 @deftypefun int logout (const char *@var{ut_line})
1298 This function modifies the user accounting database to indicate that the
1299 user on @var{ut_line} has logged out.
1300
1301 The @code{logout} function returns @code{1} if the entry was successfully
1302 written to the database, or @code{0} on error.
1303 @end deftypefun
1304
1305 @comment utmp.h
1306 @comment BSD
1307 @deftypefun void logwtmp (const char *@var{ut_line}, const char *@var{ut_name}, const char *@var{ut_host})
1308 The @code{logwtmp} function appends an entry to the user accounting log
1309 file, for the current time and the information provided in the
1310 @var{ut_line}, @var{ut_name} and @var{ut_host} arguments.
1311 @end deftypefun
1312
1313 @strong{Portability Note:} The BSD @code{struct utmp} only has the
1314 @code{ut_line}, @code{ut_name}, @code{ut_host} and @code{ut_time}
1315 members.  Older systems do not even have the @code{ut_host} member.
1316
1317
1318 @node User Database
1319 @section User Database
1320 @cindex user database
1321 @cindex password database
1322 @pindex /etc/passwd
1323
1324 This section describes all about how to search and scan the database of
1325 registered users.  The database itself is kept in the file
1326 @file{/etc/passwd} on most systems, but on some systems a special
1327 network server gives access to it.
1328
1329 @menu
1330 * User Data Structure::         What each user record contains.
1331 * Lookup User::                 How to look for a particular user.
1332 * Scanning All Users::          Scanning the list of all users, one by one.
1333 * Writing a User Entry::        How a program can rewrite a user's record.
1334 @end menu
1335
1336 @node User Data Structure
1337 @subsection The Data Structure that Describes a User
1338
1339 The functions and data structures for accessing the system user database
1340 are declared in the header file @file{pwd.h}.
1341 @pindex pwd.h
1342
1343 @comment pwd.h
1344 @comment POSIX.1
1345 @deftp {Data Type} {struct passwd}
1346 The @code{passwd} data structure is used to hold information about
1347 entries in the system user data base.  It has at least the following members:
1348
1349 @table @code
1350 @item char *pw_name
1351 The user's login name.
1352
1353 @item char *pw_passwd.
1354 The encrypted password string.
1355
1356 @item uid_t pw_uid
1357 The user ID number.
1358
1359 @item gid_t pw_gid
1360 The user's default group ID number.
1361
1362 @item char *pw_gecos
1363 A string typically containing the user's real name, and possibly other
1364 information such as a phone number.
1365
1366 @item char *pw_dir
1367 The user's home directory, or initial working directory.  This might be
1368 a null pointer, in which case the interpretation is system-dependent.
1369
1370 @item char *pw_shell
1371 The user's default shell, or the initial program run when the user logs in.
1372 This might be a null pointer, indicating that the system default should
1373 be used.
1374 @end table
1375 @end deftp
1376
1377 @node Lookup User
1378 @subsection Looking Up One User
1379 @cindex converting user ID to user name
1380 @cindex converting user name to user ID
1381
1382 You can search the system user database for information about a
1383 specific user using @code{getpwuid} or @code{getpwnam}.  These
1384 functions are declared in @file{pwd.h}.
1385
1386 @comment pwd.h
1387 @comment POSIX.1
1388 @deftypefun {struct passwd *} getpwuid (uid_t @var{uid})
1389 This function returns a pointer to a statically-allocated structure
1390 containing information about the user whose user ID is @var{uid}.  This
1391 structure may be overwritten on subsequent calls to @code{getpwuid}.
1392
1393 A null pointer value indicates there is no user in the data base with
1394 user ID @var{uid}.
1395 @end deftypefun
1396
1397 @comment pwd.h
1398 @comment POSIX.1c
1399 @deftypefun int getpwuid_r (uid_t @var{uid}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
1400 This function is similar to @code{getpwuid} in that is returns
1401 information about the user whose user ID is @var{uid}.  But the result
1402 is not placed in a static buffer.  Instead the user supplied structure
1403 pointed to by @var{result_buf} is filled with the information.  The
1404 first @var{buflen} bytes of the additional buffer pointed to by
1405 @var{buffer} are used to contain additional information, normally
1406 strings which are pointed to by the elements of the result structure.
1407
1408 If the return value is @code{0} the pointer returned in @var{result}
1409 points to the record which contains the wanted data (i.e., @var{result}
1410 contains the value @var{result_buf}).  In case the return value is non
1411 null there is no user in the data base with user ID @var{uid} or the
1412 buffer @var{buffer} is too small to contain all the needed information.
1413 In the later case the global @var{errno} variable is set to
1414 @code{ERANGE}.
1415 @end deftypefun
1416
1417
1418 @comment pwd.h
1419 @comment POSIX.1
1420 @deftypefun {struct passwd *} getpwnam (const char *@var{name})
1421 This function returns a pointer to a statically-allocated structure
1422 containing information about the user whose user name is @var{name}.
1423 This structure may be overwritten on subsequent calls to
1424 @code{getpwnam}.
1425
1426 A null pointer value indicates there is no user named @var{name}.
1427 @end deftypefun
1428
1429 @comment pwd.h
1430 @comment POSIX.1c
1431 @deftypefun int getpwnam_r (const char *@var{name}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
1432 This function is similar to @code{getpwnam} in that is returns
1433 information about the user whose user name is @var{name}.  But the result
1434 is not placed in a static buffer.  Instead the user supplied structure
1435 pointed to by @var{result_buf} is filled with the information.  The
1436 first @var{buflen} bytes of the additional buffer pointed to by
1437 @var{buffer} are used to contain additional information, normally
1438 strings which are pointed to by the elements of the result structure.
1439
1440 If the return value is @code{0} the pointer returned in @var{result}
1441 points to the record which contains the wanted data (i.e., @var{result}
1442 contains the value @var{result_buf}).  In case the return value is non
1443 null there is no user in the data base with user name @var{name} or the
1444 buffer @var{buffer} is too small to contain all the needed information.
1445 In the later case the global @var{errno} variable is set to
1446 @code{ERANGE}.
1447 @end deftypefun
1448
1449
1450 @node Scanning All Users
1451 @subsection Scanning the List of All Users
1452 @cindex scanning the user list
1453
1454 This section explains how a program can read the list of all users in
1455 the system, one user at a time.  The functions described here are
1456 declared in @file{pwd.h}.
1457
1458 You can use the @code{fgetpwent} function to read user entries from a
1459 particular file.
1460
1461 @comment pwd.h
1462 @comment SVID
1463 @deftypefun {struct passwd *} fgetpwent (FILE *@var{stream})
1464 This function reads the next user entry from @var{stream} and returns a
1465 pointer to the entry.  The structure is statically allocated and is
1466 rewritten on subsequent calls to @code{fgetpwent}.  You must copy the
1467 contents of the structure if you wish to save the information.
1468
1469 This stream must correspond to a file in the same format as the standard
1470 password database file.  This function comes from System V.
1471 @end deftypefun
1472
1473 @comment pwd.h
1474 @comment GNU
1475 @deftypefun int fgetpwent_r (FILE *@var{stream}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
1476 This function is similar to @code{fgetpwent} in that it reads the next
1477 user entry from @var{stream}.  But the result is returned in the
1478 structure pointed to by @var{result_buf}.  The
1479 first @var{buflen} bytes of the additional buffer pointed to by
1480 @var{buffer} are used to contain additional information, normally
1481 strings which are pointed to by the elements of the result structure.
1482
1483 This stream must correspond to a file in the same format as the standard
1484 password database file.
1485
1486 If the function returns null @var{result} points to the structure with
1487 the wanted data (normally this is in @var{result_buf}).  If errors
1488 occurred the return value is non-null and @var{result} contains a null
1489 pointer.
1490 @end deftypefun
1491
1492 The way to scan all the entries in the user database is with
1493 @code{setpwent}, @code{getpwent}, and @code{endpwent}.
1494
1495 @comment pwd.h
1496 @comment SVID, BSD
1497 @deftypefun void setpwent (void)
1498 This function initializes a stream which @code{getpwent} and
1499 @code{getpwent_r} use to read the user database.
1500 @end deftypefun
1501
1502 @comment pwd.h
1503 @comment POSIX.1
1504 @deftypefun {struct passwd *} getpwent (void)
1505 The @code{getpwent} function reads the next entry from the stream
1506 initialized by @code{setpwent}.  It returns a pointer to the entry.  The
1507 structure is statically allocated and is rewritten on subsequent calls
1508 to @code{getpwent}.  You must copy the contents of the structure if you
1509 wish to save the information.
1510
1511 A null pointer is returned in case no further entry is available.
1512 @end deftypefun
1513
1514 @comment pwd.h
1515 @comment GNU
1516 @deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, int @var{buflen}, struct passwd **@var{result})
1517 This function is similar to @code{getpwent} in that it returns the next
1518 entry from the stream initialized by @code{setpwent}.  But in contrast
1519 to the @code{getpwent} function this function is reentrant since the
1520 result is placed in the user supplied structure pointed to by
1521 @var{result_buf}.  Additional data, normally the strings pointed to by
1522 the elements of the result structure, are placed in the additional
1523 buffer or length @var{buflen} starting at @var{buffer}.
1524
1525 If the function returns zero @var{result} points to the structure with
1526 the wanted data (normally this is in @var{result_buf}).  If errors
1527 occurred the return value is non-zero and @var{result} contains a null
1528 pointer.
1529 @end deftypefun
1530
1531 @comment pwd.h
1532 @comment SVID, BSD
1533 @deftypefun void endpwent (void)
1534 This function closes the internal stream used by @code{getpwent} or
1535 @code{getpwent_r}.
1536 @end deftypefun
1537
1538 @node Writing a User Entry
1539 @subsection Writing a User Entry
1540
1541 @comment pwd.h
1542 @comment SVID
1543 @deftypefun int putpwent (const struct passwd *@var{p}, FILE *@var{stream})
1544 This function writes the user entry @code{*@var{p}} to the stream
1545 @var{stream}, in the format used for the standard user database
1546 file.  The return value is zero on success and nonzero on failure.
1547
1548 This function exists for compatibility with SVID.  We recommend that you
1549 avoid using it, because it makes sense only on the assumption that the
1550 @code{struct passwd} structure has no members except the standard ones;
1551 on a system which merges the traditional Unix data base with other
1552 extended information about users, adding an entry using this function
1553 would inevitably leave out much of the important information.
1554
1555 The function @code{putpwent} is declared in @file{pwd.h}.
1556 @end deftypefun
1557
1558 @node Group Database
1559 @section Group Database
1560 @cindex group database
1561 @pindex /etc/group
1562
1563 This section describes all about how to search and scan the database of
1564 registered groups.  The database itself is kept in the file
1565 @file{/etc/group} on most systems, but on some systems a special network
1566 service provides access to it.
1567
1568 @menu
1569 * Group Data Structure::        What each group record contains.
1570 * Lookup Group::                How to look for a particular group.
1571 * Scanning All Groups::         Scanning the list of all groups.
1572 @end menu
1573
1574 @node Group Data Structure
1575 @subsection The Data Structure for a Group
1576
1577 The functions and data structures for accessing the system group
1578 database are declared in the header file @file{grp.h}.
1579 @pindex grp.h
1580
1581 @comment grp.h
1582 @comment POSIX.1
1583 @deftp {Data Type} {struct group}
1584 The @code{group} structure is used to hold information about an entry in
1585 the system group database.  It has at least the following members:
1586
1587 @table @code
1588 @item char *gr_name
1589 The name of the group.
1590
1591 @item gid_t gr_gid
1592 The group ID of the group.
1593
1594 @item char **gr_mem
1595 A vector of pointers to the names of users in the group.  Each user name
1596 is a null-terminated string, and the vector itself is terminated by a
1597 null pointer.
1598 @end table
1599 @end deftp
1600
1601 @node Lookup Group
1602 @subsection Looking Up One Group
1603 @cindex converting group name to group ID
1604 @cindex converting group ID to group name
1605
1606 You can search the group database for information about a specific
1607 group using @code{getgrgid} or @code{getgrnam}.  These functions are
1608 declared in @file{grp.h}.
1609
1610 @comment grp.h
1611 @comment POSIX.1
1612 @deftypefun {struct group *} getgrgid (gid_t @var{gid})
1613 This function returns a pointer to a statically-allocated structure
1614 containing information about the group whose group ID is @var{gid}.
1615 This structure may be overwritten by subsequent calls to
1616 @code{getgrgid}.
1617
1618 A null pointer indicates there is no group with ID @var{gid}.
1619 @end deftypefun
1620
1621 @comment grp.h
1622 @comment POSIX.1c
1623 @deftypefun int getgrgid_r (gid_t @var{gid}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
1624 This function is similar to @code{getgrgid} in that is returns
1625 information about the group whose group ID is @var{gid}.  But the result
1626 is not placed in a static buffer.  Instead the user supplied structure
1627 pointed to by @var{result_buf} is filled with the information.  The
1628 first @var{buflen} bytes of the additional buffer pointed to by
1629 @var{buffer} are used to contain additional information, normally
1630 strings which are pointed to by the elements of the result structure.
1631
1632 If the return value is @code{0} the pointer returned in @var{result}
1633 points to the record which contains the wanted data (i.e., @var{result}
1634 contains the value @var{result_buf}).  If the return value is non-zero
1635 there is no group in the data base with group ID @var{gid} or the
1636 buffer @var{buffer} is too small to contain all the needed information.
1637 In the later case the global @var{errno} variable is set to
1638 @code{ERANGE}.
1639 @end deftypefun
1640
1641 @comment grp.h
1642 @comment SVID, BSD
1643 @deftypefun {struct group *} getgrnam (const char *@var{name})
1644 This function returns a pointer to a statically-allocated structure
1645 containing information about the group whose group name is @var{name}.
1646 This structure may be overwritten by subsequent calls to
1647 @code{getgrnam}.
1648
1649 A null pointer indicates there is no group named @var{name}.
1650 @end deftypefun
1651
1652 @comment grp.h
1653 @comment POSIX.1c
1654 @deftypefun int getgrnam_r (const char *@var{name}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
1655 This function is similar to @code{getgrnam} in that is returns
1656 information about the group whose group name is @var{name}.  But the result
1657 is not placed in a static buffer.  Instead the user supplied structure
1658 pointed to by @var{result_buf} is filled with the information.  The
1659 first @var{buflen} bytes of the additional buffer pointed to by
1660 @var{buffer} are used to contain additional information, normally
1661 strings which are pointed to by the elements of the result structure.
1662
1663 If the return value is @code{0} the pointer returned in @var{result}
1664 points to the record which contains the wanted data (i.e., @var{result}
1665 contains the value @var{result_buf}).  If the return value is non-zero
1666 there is no group in the data base with group name @var{name} or the
1667 buffer @var{buffer} is too small to contain all the needed information.
1668 In the later case the global @var{errno} variable is set to
1669 @code{ERANGE}.
1670 @end deftypefun
1671
1672 @node Scanning All Groups
1673 @subsection Scanning the List of All Groups
1674 @cindex scanning the group list
1675
1676 This section explains how a program can read the list of all groups in
1677 the system, one group at a time.  The functions described here are
1678 declared in @file{grp.h}.
1679
1680 You can use the @code{fgetgrent} function to read group entries from a
1681 particular file.
1682
1683 @comment grp.h
1684 @comment SVID
1685 @deftypefun {struct group *} fgetgrent (FILE *@var{stream})
1686 The @code{fgetgrent} function reads the next entry from @var{stream}.
1687 It returns a pointer to the entry.  The structure is statically
1688 allocated and is rewritten on subsequent calls to @code{fgetgrent}.  You
1689 must copy the contents of the structure if you wish to save the
1690 information.
1691
1692 The stream must correspond to a file in the same format as the standard
1693 group database file.
1694 @end deftypefun
1695
1696 @comment grp.h
1697 @comment GNU
1698 @deftypefun int fgetgrent_r (FILE *@var{stream}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
1699 This function is similar to @code{fgetgrent} in that it reads the next
1700 user entry from @var{stream}.  But the result is returned in the
1701 structure pointed to by @var{result_buf}.  The
1702 first @var{buflen} bytes of the additional buffer pointed to by
1703 @var{buffer} are used to contain additional information, normally
1704 strings which are pointed to by the elements of the result structure.
1705
1706 This stream must correspond to a file in the same format as the standard
1707 group database file.
1708
1709 If the function returns zero @var{result} points to the structure with
1710 the wanted data (normally this is in @var{result_buf}).  If errors
1711 occurred the return value is non-zero and @var{result} contains a null
1712 pointer.
1713 @end deftypefun
1714
1715 The way to scan all the entries in the group database is with
1716 @code{setgrent}, @code{getgrent}, and @code{endgrent}.
1717
1718 @comment grp.h
1719 @comment SVID, BSD
1720 @deftypefun void setgrent (void)
1721 This function initializes a stream for reading from the group data base.
1722 You use this stream by calling @code{getgrent} or @code{getgrent_r}.
1723 @end deftypefun
1724
1725 @comment grp.h
1726 @comment SVID, BSD
1727 @deftypefun {struct group *} getgrent (void)
1728 The @code{getgrent} function reads the next entry from the stream
1729 initialized by @code{setgrent}.  It returns a pointer to the entry.  The
1730 structure is statically allocated and is rewritten on subsequent calls
1731 to @code{getgrent}.  You must copy the contents of the structure if you
1732 wish to save the information.
1733 @end deftypefun
1734
1735 @comment grp.h
1736 @comment GNU
1737 @deftypefun int getgrent_r (struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
1738 This function is similar to @code{getgrent} in that it returns the next
1739 entry from the stream initialized by @code{setgrent}.  But in contrast
1740 to the @code{getgrent} function this function is reentrant since the
1741 result is placed in the user supplied structure pointed to by
1742 @var{result_buf}.  Additional data, normally the strings pointed to by
1743 the elements of the result structure, are placed in the additional
1744 buffer or length @var{buflen} starting at @var{buffer}.
1745
1746 If the function returns zero @var{result} points to the structure with
1747 the wanted data (normally this is in @var{result_buf}).  If errors
1748 occurred the return value is non-zero and @var{result} contains a null
1749 pointer.
1750 @end deftypefun
1751
1752 @comment grp.h
1753 @comment SVID, BSD
1754 @deftypefun void endgrent (void)
1755 This function closes the internal stream used by @code{getgrent} or
1756 @code{getgrent_r}.
1757 @end deftypefun
1758
1759 @node Netgroup Database
1760 @section Netgroup Database
1761
1762 @menu
1763 * Netgroup Data::                  Data in the Netgroup database and where
1764                                    it comes from.
1765 * Lookup Netgroup::                How to look for a particular netgroup.
1766 * Netgroup Membership::            How to test for netgroup membership.
1767 @end menu
1768
1769 @node Netgroup Data
1770 @subsection Netgroup Data
1771
1772 @cindex Netgroup
1773 Sometimes it is useful group users according to other criterias like the
1774 ones used in the @xref{Group Database}.  E.g., it is useful to associate
1775 a certain group of users with a certain machine.  On the other hand
1776 grouping of host names is not supported so far.
1777
1778 In Sun Microsystems SunOS appeared a new kind of database, the netgroup
1779 database.  It allows to group hosts, users, and domain freely, giving
1780 them individual names.  More concrete: a netgroup is a list of triples
1781 consisting of a host name, a user name, and a domain name, where any of
1782 the entries can be a wildcard entry, matching all inputs.  A last
1783 possibility is that names of other netgroups can also be given in the
1784 list specifying a netgroup.  So one can construct arbitrary hierarchies
1785 without loops.
1786
1787 Sun's implementation allows netgroups only for the @code{nis} or
1788 @code{nisplus} service @pxref{Services in the NSS configuration}.  The
1789 implementation in the GNU C library has no such restriction.  An entry
1790 in either of the input services must have the following form:
1791
1792 @smallexample
1793 @var{groupname} ( @var{groupname} | @code{(}@var{hostname}@code{,}@var{username}@code{,}@code{domainname}@code{)} )+
1794 @end smallexample
1795
1796 Any of the fields in the triple can be empty which means anything
1797 matches.  While describing the functions we will see that the opposite
1798 case is useful as well.  I.e., there may be entries which will not
1799 match any input.  For entries like a name consisting of the single
1800 character @code{-} shall be used.
1801
1802 @node Lookup Netgroup
1803 @subsection Looking up one Netgroup
1804
1805 The lookup functions for netgroups are a bit different to all other
1806 system database handling functions.  Since a single netgroup can contain
1807 many entries a two-step process is needed.  First a single netgroup is
1808 selected and then one can iterate over all entries in this netgroup.
1809 These functions are declared in @file{netdb.h}.
1810
1811 @comment netdb.h
1812 @deftypefun int setnetgrent (const char *@var{netgroup})
1813 A call to this function initializes the internal state of the library to
1814 allow following calls of the @code{getnetgrent} iterate over all entries
1815 in the netgroup with name @var{netgroup}.
1816
1817 When the call is successful (i.e., when a netgroup with this name exist)
1818 the return value is @code{1}.  When the return value is @code{0} no
1819 netgroup of this name is known or some other error occurred.
1820 @end deftypefun
1821
1822 It is important to remember that there is only one single state for
1823 iterating the netgroups.  Even if the programmer uses the
1824 @code{getnetgrent_r} function the result is not really reentrant since
1825 always only one single netgroup at a time can be processed.  If the
1826 program needs to process more than one netgroup simultaneously she
1827 must protect this by using external locking.  This problem was
1828 introduced in the original netgroups implementation in SunOS and since
1829 we must stay compatible it is not possible to change this.
1830
1831 Some other functions also use the netgroups state.  Currently these are
1832 the @code{innetgr} function and parts of the implementation of the
1833 @code{compat} service part of the NSS implementation.
1834
1835 @comment netdb.h
1836 @deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp})
1837 This function returns the next unprocessed entry of the currently
1838 selected netgroup.  The string pointers, which addresses are passed in
1839 the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain
1840 after a successful call pointers to appropriate strings.  If the string
1841 in the next entry is empty the pointer has the value @code{NULL}.
1842 The returned string pointers are only valid unless no of the netgroup
1843 related functions are called.
1844
1845 The return value is @code{1} if the next entry was successfully read.  A
1846 value of @code{0} means no further entries exist or internal errors occurred.
1847 @end deftypefun
1848
1849 @comment netdb.h
1850 @deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, int @var{buflen})
1851 This function is similar to @code{getnetgrent} with only one exception:
1852 the strings the three string pointers @var{hostp}, @var{userp}, and
1853 @var{domainp} point to, are placed in the buffer of @var{buflen} bytes
1854 starting at @var{buffer}.  This means the returned values are valid
1855 even after other netgroup related functions are called.
1856
1857 The return value is @code{1} if the next entry was successfully read and
1858 the buffer contains enough room to place the strings in it.  @code{0} is
1859 returned in case no more entries are found, the buffer is too small, or
1860 internal errors occurred.
1861
1862 This function is a GNU extension.  The original implementation in the
1863 SunOS libc does not provide this function.
1864 @end deftypefun
1865
1866 @comment netdb.h
1867 @deftypefun void endnetgrent (void)
1868 This function free all buffers which were allocated to process the last
1869 selected netgroup.  As a result all string pointers returned by calls
1870 to @code{getnetgrent} are invalid afterwards.
1871 @end deftypefun
1872
1873 @node Netgroup Membership
1874 @subsection Testing for Netgroup Membership
1875
1876 It is often not necessary to scan the whole netgroup since often the
1877 only interesting question is whether a given entry is part of the
1878 selected netgroup.
1879
1880 @comment netdb.h
1881 @deftypefun int innetgr (const char *@var{netgroup}, const char *@var{host}, const char *@var{user}, const char *@var{domain})
1882 This function tests whether the triple specified by the parameters
1883 @var{hostp}, @var{userp}, and @var{domainp} is part of the netgroup
1884 @var{netgroup}.  Using this function has the advantage that
1885
1886 @enumerate
1887 @item
1888 no other netgroup function can use the global netgroup state since
1889 internal locking is used and
1890 @item
1891 the function is implemented more efficiently than successive calls
1892 to the other @code{set}/@code{get}/@code{endnetgrent} functions.
1893 @end enumerate
1894
1895 Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be
1896 @code{NULL} which means any value is excepted in this position.  This is
1897 also true for the name @code{-} which should not match any other string
1898 otherwise.
1899
1900 The return value is @code{1} if an entry matching the given triple is
1901 found in the netgroup.  The return value is @code{0} if the netgroup
1902 itself is not found, the netgroup does not contain the triple or
1903 internal errors occurred.
1904 @end deftypefun
1905
1906 @node Database Example
1907 @section User and Group Database Example
1908
1909 Here is an example program showing the use of the system database inquiry
1910 functions.  The program prints some information about the user running
1911 the program.
1912
1913 @smallexample
1914 @include db.c.texi
1915 @end smallexample
1916
1917 Here is some output from this program:
1918
1919 @smallexample
1920 I am Throckmorton Snurd.
1921 My login name is snurd.
1922 My uid is 31093.
1923 My home directory is /home/fsg/snurd.
1924 My default shell is /bin/sh.
1925 My default group is guest (12).
1926 The members of this group are:
1927   friedman
1928   tami
1929 @end smallexample