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