   This file documents the GNU C library.

   This is Edition 0.08 DRAFT, last updated 11 Jan 1999, of `The GNU C
Library Reference Manual', for Version 2.1 Beta.

   Copyright (C) 1993, '94, '95, '96, '97, '98, '99 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

Setting the Group IDs
=====================

   This section describes the functions for altering the group IDs (real
and effective) of a process.  To use these facilities, you must include
the header files `sys/types.h' and `unistd.h'.

 - Function: int setegid (gid_t NEWGID)
     This function sets the effective group ID of the process to
     NEWGID, provided that the process is allowed to change its group
     ID.  Just as with `seteuid', if the process is privileged it may
     change its effective group ID to any value; if it isn't, but it
     has a file group ID, then it may change to its real group ID or
     file group ID; otherwise it may not change its effective group ID.

     Note that a process is only privileged if its effective _user_ ID
     is zero.  The effective group ID only affects access permissions.

     The return values and error conditions for `setegid' are the same
     as those for `seteuid'.

     This function is only present if `_POSIX_SAVED_IDS' is defined.

 - Function: int setgid (gid_t NEWGID)
     This function sets both the real and effective group ID of the
     process to NEWGID, provided that the process is privileged.  It
     also deletes the file group ID, if any.

     If the process is not privileged, then `setgid' behaves like
     `setegid'.

     The return values and error conditions for `setgid' are the same
     as those for `seteuid'.

 - Function: int setregid (gid_t RGID, gid_t EGID)
     This function sets the real group ID of the process to RGID and
     the effective group ID to EGID.  If RGID is `-1', it means not to
     change the real group ID; likewise if EGID is `-1', it means not
     to change the effective group ID.

     The `setregid' function is provided for compatibility with 4.3 BSD
     Unix, which does not support file IDs.  You can use this function
     to swap the effective and real group IDs of the process.
     (Privileged processes are not limited to this usage.)  If file IDs
     are supported, you should use that feature instead of using this
     function.  See Enable/Disable Setuid.

     The return values and error conditions for `setregid' are the same
     as those for `setreuid'.

   `setuid' and `setgid' behave differently depending on whether the
effective user ID at the time is zero.  If it is not zero, they behave
like `seteuid' and `setegid'.  If it is, they change both effective and
real IDs and delete the file ID.  To avoid confusion, we recommend you
always use `seteuid' and `setegid' except when you know the effective
user ID is zero and your intent is to change the persona permanently.
This case is rare--most of the programs that need it, such as `login'
and `su', have already been written.

   Note that if your program is setuid to some user other than `root',
there is no way to drop privileges permanently.

   The system also lets privileged processes change their supplementary
group IDs.  To use `setgroups' or `initgroups', your programs should
include the header file `grp.h'.

 - Function: int setgroups (size_t COUNT, gid_t *GROUPS)
     This function sets the process's supplementary group IDs.  It can
     only be called from privileged processes.  The COUNT argument
     specifies the number of group IDs in the array GROUPS.

     This function returns `0' if successful and `-1' on error.  The
     following `errno' error conditions are defined for this function:

    `EPERM'
          The calling process is not privileged.

 - Function: int initgroups (const char *USER, gid_t GID)
     The `initgroups' function sets the process's supplementary group
     IDs to be the normal default for the user name USER. If GID is not
     -1, it includes that group also.

     This function works by scanning the group database for all the
     groups USER belongs to.  It then calls `setgroups' with the list it
     has constructed.

     The return values and error conditions are the same as for
     `setgroups'.

Enabling and Disabling Setuid Access
====================================

   A typical setuid program does not need its special access all of the
time.  It's a good idea to turn off this access when it isn't needed,
so it can't possibly give unintended access.

   If the system supports the `_POSIX_SAVED_IDS' feature, you can
accomplish this with `seteuid'.  When the game program starts, its real
user ID is `jdoe', its effective user ID is `games', and its saved user
ID is also `games'.  The program should record both user ID values once
at the beginning, like this:

     user_user_id = getuid ();
     game_user_id = geteuid ();

   Then it can turn off game file access with

     seteuid (user_user_id);

and turn it on with

     seteuid (game_user_id);

Throughout this process, the real user ID remains `jdoe' and the file
user ID remains `games', so the program can always set its effective
user ID to either one.

   On other systems that don't support file user IDs, you can turn
setuid access on and off by using `setreuid' to swap the real and
effective user IDs of the process, as follows:

     setreuid (geteuid (), getuid ());

This special case is always allowed--it cannot fail.

   Why does this have the effect of toggling the setuid access?
Suppose a game program has just started, and its real user ID is `jdoe'
while its effective user ID is `games'.  In this state, the game can
write the scores file.  If it swaps the two uids, the real becomes
`games' and the effective becomes `jdoe'; now the program has only
`jdoe' access.  Another swap brings `games' back to the effective user
ID and restores access to the scores file.

   In order to handle both kinds of systems, test for the saved user ID
feature with a preprocessor conditional, like this:

     #ifdef _POSIX_SAVED_IDS
       setuid (user_user_id);
     #else
       setreuid (geteuid (), getuid ());
     #endif

Setuid Program Example
======================

   Here's an example showing how to set up a program that changes its
effective user ID.

   This is part of a game program called `caber-toss' that manipulates
a file `scores' that should be writable only by the game program
itself.  The program assumes that its executable file will be installed
with the setuid bit set and owned by the same user as the `scores'
file.  Typically, a system administrator will set up an account like
`games' for this purpose.

   The executable file is given mode `4755', so that doing an `ls -l'
on it produces output like:

     -rwsr-xr-x   1 games    184422 Jul 30 15:17 caber-toss

The setuid bit shows up in the file modes as the `s'.

   The scores file is given mode `644', and doing an `ls -l' on it
shows:

     -rw-r--r--  1 games           0 Jul 31 15:33 scores

   Here are the parts of the program that show how to set up the changed
user ID.  This program is conditionalized so that it makes use of the
file IDs feature if it is supported, and otherwise uses `setreuid' to
swap the effective and real user IDs.

     #include <stdio.h>
     #include <sys/types.h>
     #include <unistd.h>
     #include <stdlib.h>

     /* Remember the effective and real UIDs. */

     static uid_t euid, ruid;

     /* Restore the effective UID to its original value. */

     void
     do_setuid (void)
     {
       int status;

     #ifdef _POSIX_SAVED_IDS
       status = seteuid (euid);
     #else
       status = setreuid (ruid, euid);
     #endif
       if (status < 0) {
         fprintf (stderr, "Couldn't set uid.\n");
         exit (status);
         }
     }

     /* Set the effective UID to the real UID. */

     void
     undo_setuid (void)
     {
       int status;

     #ifdef _POSIX_SAVED_IDS
       status = seteuid (ruid);
     #else
       status = setreuid (euid, ruid);
     #endif
       if (status < 0) {
         fprintf (stderr, "Couldn't set uid.\n");
         exit (status);
         }
     }

     /* Main program. */

     int
     main (void)
     {
       /* Remember the real and effective user IDs.  */
       ruid = getuid ();
       euid = geteuid ();
       undo_setuid ();

       /* Do the game and record the score.  */
       ...
     }

   Notice how the first thing the `main' function does is to set the
effective user ID back to the real user ID.  This is so that any other
file accesses that are performed while the user is playing the game use
the real user ID for determining permissions.  Only when the program
needs to open the scores file does it switch back to the file user ID,
like this:

     /* Record the score. */

     int
     record_score (int score)
     {
       FILE *stream;
       char *myname;

       /* Open the scores file. */
       do_setuid ();
       stream = fopen (SCORES_FILE, "a");
       undo_setuid ();

       /* Write the score to the file. */
       if (stream)
         {
           myname = cuserid (NULL);
           if (score < 0)
             fprintf (stream, "%10s: Couldn't lift the caber.\n", myname);
           else
             fprintf (stream, "%10s: %d feet.\n", myname, score);
           fclose (stream);
           return 0;
         }
       else
         return -1;
     }

Tips for Writing Setuid Programs
================================

   It is easy for setuid programs to give the user access that isn't
intended--in fact, if you want to avoid this, you need to be careful.
Here are some guidelines for preventing unintended access and
minimizing its consequences when it does occur:

   * Don't have `setuid' programs with privileged user IDs such as
     `root' unless it is absolutely necessary.  If the resource is
     specific to your particular program, it's better to define a new,
     nonprivileged user ID or group ID just to manage that resource.
     It's better if you can write your program to use a special group
     than a special user.

   * Be cautious about using the `exec' functions in combination with
     changing the effective user ID.  Don't let users of your program
     execute arbitrary programs under a changed user ID.  Executing a
     shell is especially bad news. Less obviously, the `execlp' and
     `execvp' functions are a potential risk (since the program they
     execute depends on the user's `PATH' environment variable).

     If you must `exec' another program under a changed ID, specify an
     absolute file name (see File Name Resolution) for the
     executable, and make sure that the protections on that executable
     and _all_ containing directories are such that ordinary users
     cannot replace it with some other program.

     You should also check the arguments passed to the program to make
     sure they do not have unexpected effects.  Likewise, you should
     examine the environment variables.  Decide which arguments and
     variables are safe, and reject all others.

     You should never use `system' in a privileged program, because it
     invokes a shell.

   * Only use the user ID controlling the resource in the part of the
     program that actually uses that resource.  When you're finished
     with it, restore the effective user ID back to the actual user's
     user ID.  See Enable/Disable Setuid.

   * If the `setuid' part of your program needs to access other files
     besides the controlled resource, it should verify that the real
     user would ordinarily have permission to access those files.  You
     can use the `access' function (see Access Permission) to check
     this; it uses the real user and group IDs, rather than the
     effective IDs.

Identifying Who Logged In
=========================

   You can use the functions listed in this section to determine the
login name of the user who is running a process, and the name of the
user who logged in the current session.  See also the function `getuid'
and friends (see Reading Persona).  How this information is
collected by the system and how to control/add/remove information from
the background storage is described in User Accounting Database.

   The `getlogin' function is declared in `unistd.h', while `cuserid'
and `L_cuserid' are declared in `stdio.h'.

 - Function: char * getlogin (void)
     The `getlogin' function returns a pointer to a string containing
     the name of the user logged in on the controlling terminal of the
     process, or a null pointer if this information cannot be
     determined.  The string is statically allocated and might be
     overwritten on subsequent calls to this function or to `cuserid'.

 - Function: char * cuserid (char *STRING)
     The `cuserid' function returns a pointer to a string containing a
     user name associated with the effective ID of the process.  If
     STRING is not a null pointer, it should be an array that can hold
     at least `L_cuserid' characters; the string is returned in this
     array.  Otherwise, a pointer to a string in a static area is
     returned.  This string is statically allocated and might be
     overwritten on subsequent calls to this function or to `getlogin'.

     The use of this function is deprecated since it is marked to be
     withdrawn in XPG4.2 and has already been removed from newer
     revisions of POSIX.1.

 - Macro: int L_cuserid
     An integer constant that indicates how long an array you might
     need to store a user name.

   These functions let your program identify positively the user who is
running or the user who logged in this session.  (These can differ when
setuid programs are involved; see Process Persona.)  The user
cannot do anything to fool these functions.

   For most purposes, it is more useful to use the environment variable
`LOGNAME' to find out who the user is.  This is more flexible precisely
because the user can set `LOGNAME' arbitrarily.  See Standard Environment.

The User Accounting Database
============================

   Most Unix-like operating systems keep track of logged in users by
maintaining a user accounting database.  This user accounting database
stores for each terminal, who has logged on, at what time, the process
ID of the user's login shell, etc., etc., but also stores information
about the run level of the system, the time of the last system reboot,
and possibly more.

   The user accounting database typically lives in `/etc/utmp',
`/var/adm/utmp' or `/var/run/utmp'.  However, these files should
*never* be accessed directly.  For reading information from and writing
information to the user accounting database, the functions described in
this section should be used.

Manipulating the User Accounting Database
-----------------------------------------

   These functions and the corresponding data structures are declared in
the header file `utmp.h'.

 - Data Type: struct exit_status
     The `exit_status' data structure is used to hold information about
     the exit status of processes marked as `DEAD_PROCESS' in the user
     accounting database.

    `short int e_termination'
          The exit status of the process.

    `short int e_exit'
          The exit status of the process.

 - Data Type: struct utmp
     The `utmp' data structure is used to hold information about entries
     in the user accounting database.  On the GNU system it has the
     following members:

    `short int ut_type'
          Specifies the type of login; one of `EMPTY', `RUN_LVL',
          `BOOT_TIME', `OLD_TIME', `NEW_TIME', `INIT_PROCESS',
          `LOGIN_PROCESS', `USER_PROCESS', `DEAD_PROCESS' or
          `ACCOUNTING'.

    `pid_t ut_pid'
          The process ID number of the login process.

    `char ut_line[]'
          The device name of the tty (without `/dev/').

    `char ut_id[]'
          The inittab ID of the process.

    `char ut_user[]'
          The user's login name.

    `char ut_host[]'
          The name of the host from which the user logged in.

    `struct exit_status ut_exit'
          The exit status of a process marked as `DEAD_PROCESS'.

    `long ut_session'
          The Session ID, used for windowing.

    `struct timeval ut_tv'
          Time the entry was made.  For entries of type `OLD_TIME' this
          is the time when the system clock changed, and for entries of
          type `NEW_TIME' this is the time the system clock was set to.

    `int32_t ut_addr_v6[4]'
          The Internet address of a remote host.

   The `ut_type', `ut_pid', `ut_id', `ut_tv', and `ut_host' fields are
not available on all systems.  Portable applications therefore should
be prepared for these situations.  To help doing this the `utmp.h'
header provides macros `_HAVE_UT_TYPE', `_HAVE_UT_PID', `_HAVE_UT_ID',
`_HAVE_UT_TV', and `_HAVE_UT_HOST' if the respective field is
available.  The programmer can handle the situations by using `#ifdef'
in the program code.

   The following macros are defined for use as values for the `ut_type'
member of the `utmp' structure.  The values are integer constants.

`EMPTY'
     This macro is used to indicate that the entry contains no valid
     user accounting information.

`RUN_LVL'
     This macro is used to identify the systems runlevel.

`BOOT_TIME'
     This macro is used to identify the time of system boot.

`OLD_TIME'
     This macro is used to identify the time when the system clock
     changed.

`NEW_TIME'
     This macro is used to identify the time after the system changed.

`INIT_PROCESS'
     This macro is used to identify a process spawned by the init
     process.

`LOGIN_PROCESS'
     This macro is used to identify the session leader of a logged in
     user.

`USER_PROCESS'
     This macro is used to identify a user process.

`DEAD_PROCESS'
     This macro is used to identify a terminated process.

`ACCOUNTING'
     ???

   The size of the `ut_line', `ut_id', `ut_user' and `ut_host' arrays
can be found using the `sizeof' operator.

   Many older systems have, instead of an `ut_tv' member, an `ut_time'
member, usually of type `time_t', for representing the time associated
with the entry.  Therefore, for backwards compatibility only, `utmp.h'
defines `ut_time' as an alias for `ut_tv.tv_sec'.

 - Function: void setutent (void)
     This function opens the user accounting database to begin scanning
     it.  You can then call `getutent', `getutid' or `getutline' to
     read entries and `pututline' to write entries.

     If the database is already open, it resets the input to the
     beginning of the database.

 - Function: struct utmp * getutent (void)
     The `getutent' function reads the next entry from the user
     accounting database.  It returns a pointer to the entry, which is
     statically allocated and may be overwritten by subsequent calls to
     `getutent'.  You must copy the contents of the structure if you
     wish to save the information or you can use the `getutent_r'
     function which stores the data in a user-provided buffer.

     A null pointer is returned in case no further entry is available.

 - Function: void endutent (void)
     This function closes the user accounting database.

 - Function: struct utmp * getutid (const struct utmp *ID)
     This function searches forward from the current point in the
     database for an entry that matches ID.  If the `ut_type' member of
     the ID structure is one of `RUN_LVL', `BOOT_TIME', `OLD_TIME' or
     `NEW_TIME' the entries match if the `ut_type' members are
     identical.  If the `ut_type' member of the ID structure is
     `INIT_PROCESS', `LOGIN_PROCESS', `USER_PROCESS' or `DEAD_PROCESS',
     the entries match if the `ut_type' member of the entry read from
     the database is one of these four, and the `ut_id' members match.
     However if the `ut_id' member of either the ID structure or the
     entry read from the database is empty it checks if the `ut_line'
     members match instead.  If a matching entry is found, `getutid'
     returns a pointer to the entry, which is statically allocated, and
     may be overwritten by a subsequent call to `getutent', `getutid'
     or `getutline'.  You must copy the contents of the structure if
     you wish to save the information.

     A null pointer is returned in case the end of the database is
     reached without a match.

     The `getutid' function may cache the last read entry.  Therefore,
     if you are using `getutid' to search for multiple occurrences, it
     is necessary to zero out the static data after each call.
     Otherwise `getutid' could just return a pointer to the same entry
     over and over again.

 - Function: struct utmp * getutline (const struct utmp *LINE)
     This function searches forward from the current point in the
     database until it finds an entry whose `ut_type' value is
     `LOGIN_PROCESS' or `USER_PROCESS', and whose `ut_line' member
     matches the `ut_line' member of the LINE structure.  If it finds
     such an entry, it returns a pointer to the entry which is
     statically allocated, and may be overwritten by a subsequent call
     to `getutent', `getutid' or `getutline'.  You must copy the
     contents of the structure if you wish to save the information.

     A null pointer is returned in case the end of the database is
     reached without a match.

     The `getutline' function may cache the last read entry.  Therefore
     if you are using `getutline' to search for multiple occurrences, it
     is necessary to zero out the static data after each call.
     Otherwise `getutline' could just return a pointer to the same
     entry over and over again.

 - Function: struct utmp * pututline (const struct utmp *UTMP)
     The `pututline' function inserts the entry `*UTMP' at the
     appropriate place in the user accounting database.  If it finds
     that it is not already at the correct place in the database, it
     uses `getutid' to search for the position to insert the entry,
     however this will not modify the static structure returned by
     `getutent', `getutid' and `getutline'.  If this search fails, the
     entry is appended to the database.

     The `pututline' function returns a pointer to a copy of the entry
     inserted in the user accounting database, or a null pointer if the
     entry could not be added.  The following `errno' error conditions
     are defined for this function:

    `EPERM'
          The process does not have the appropriate privileges; you
          cannot modify the user accounting database.

   All the `get*' functions mentioned before store the information they
return in a static buffer.  This can be a problem in multi-threaded
programs since the data return for the request is overwritten be the
return value data in another thread.  Therefore the GNU C Library
provides as extensions three more functions which return the data in a
user-provided buffer.

 - Function: int getutent_r (struct utmp *BUFFER, struct utmp **RESULT)
     The `getutent_r' is equivalent to the `getutent' function.  It
     returns the next entry from the database.  But instead of storing
     the information in a static buffer it stores it in the buffer
     pointed to by the parameter BUFFER.

     If the call was successful, the function returns `0' and the
     pointer variable pointed to by the parameter RESULT contains a
     pointer to the buffer which contains the result (this is most
     probably the same value as BUFFER).  If something went wrong
     during the execution of `getutent_r' the function returns `-1'.

     This function is a GNU extension.

 - Function: int getutid_r (const struct utmp *ID, struct utmp *BUFFER,
          struct utmp **RESULT)
     This function retrieves just like `getutid' the next entry matching
     the information stored in ID.  But the result is stored in the
     buffer pointed to by the parameter BUFFER.

     If successful the function returns `0' and the pointer variable
     pointed to by the parameter RESULT contains a pointer to the
     buffer with the result (probably the same as RESULT.  If not
     successful the function return `-1'.

     This function is a GNU extension.

 - Function: int getutline_r (const struct utmp *LINE, struct utmp
          *BUFFER, struct utmp **RESULT)
     This function retrieves just like `getutline' the next entry
     matching the information stored in LINE.  But the result is stored
     in the buffer pointed to by the parameter BUFFER.

     If successful the function returns `0' and the pointer variable
     pointed to by the parameter RESULT contains a pointer to the
     buffer with the result (probably the same as RESULT.  If not
     successful the function return `-1'.

     This function is a GNU extension.

   In addition to the user accounting database, most systems keep a
number of similar databases.  For example most systems keep a log file
with all previous logins (usually in `/etc/wtmp' or `/var/log/wtmp').

   For specifying which database to examine, the following function
should be used.

 - Function: int utmpname (const char *FILE)
     The `utmpname' function changes the name of the database to be
     examined to FILE, and closes any previously opened database.  By
     default `getutent', `getutid', `getutline' and `pututline' read
     from and write to the user accounting database.

     The following macros are defined for use as the FILE argument:

      - Macro: char * _PATH_UTMP
          This macro is used to specify the user accounting database.

      - Macro: char * _PATH_WTMP
          This macro is used to specify the user accounting log file.

     The `utmpname' function returns a value of `0' if the new name was
     successfully stored, and a value of `-1' to indicate an error.
     Note that `utmpname' does not try to open the database, and that
     therefore the return value does not say anything about whether the
     database can be successfully opened.

   Specially for maintaining log-like databases the GNU C Library
provides the following function:

 - Function: void updwtmp (const char *WTMP_FILE, const struct utmp
          *UTMP)
     The `updwtmp' function appends the entry *UTMP to the database
     specified by WTMP_FILE.  For possible values for the WTMP_FILE
     argument see the `utmpname' function.

   *Portability Note:* Although many operating systems provide a subset
of these functions, they are not standardized.  There are often subtle
differences in the return types, and there are considerable differences
between the various definitions of `struct utmp'.  When programming for
the GNU system, it is probably best to stick with the functions
described in this section.  If however, you want your program to be
portable, consider using the XPG functions described in XPG Functions,
or take a look at the BSD compatible functions in
Logging In and Out.

XPG User Accounting Database Functions
--------------------------------------

   These functions, described in the X/Open Portability Guide, are
declared in the header file `utmpx.h'.

 - Data Type: struct utmpx
     The `utmpx' data structure contains at least the following members:

    `short int ut_type'
          Specifies the type of login; one of `EMPTY', `RUN_LVL',
          `BOOT_TIME', `OLD_TIME', `NEW_TIME', `INIT_PROCESS',
          `LOGIN_PROCESS', `USER_PROCESS' or `DEAD_PROCESS'.

    `pid_t ut_pid'
          The process ID number of the login process.

    `char ut_line[]'
          The device name of the tty (without `/dev/').

    `char ut_id[]'
          The inittab ID of the process.

    `char ut_user[]'
          The user's login name.

    `struct timeval ut_tv'
          Time the entry was made.  For entries of type `OLD_TIME' this
          is the time when the system clock changed, and for entries of
          type `NEW_TIME' this is the time the system clock was set to.
     On the GNU system, `struct utmpx' is identical to `struct utmp'
     except for the fact that including `utmpx.h' does not make visible
     the declaration of `struct exit_status'.

   The following macros are defined for use as values for the `ut_type'
member of the `utmpx' structure.  The values are integer constants and
are, on the GNU system, identical to the definitions in `utmp.h'.

`EMPTY'
     This macro is used to indicate that the entry contains no valid
     user accounting information.

`RUN_LVL'
     This macro is used to identify the systems runlevel.

`BOOT_TIME'
     This macro is used to identify the time of system boot.

`OLD_TIME'
     This macro is used to identify the time when the system clock
     changed.

`NEW_TIME'
     This macro is used to identify the time after the system changed.

`INIT_PROCESS'
     This macro is used to identify a process spawned by the init
     process.

`LOGIN_PROCESS'
     This macro is used to identify the session leader of a logged in
     user.

`USER_PROCESS'
     This macro is used to identify a user process.

`DEAD_PROCESS'
     This macro is used to identify a terminated process.

   The size of the `ut_line', `ut_id' and `ut_user' arrays can be found
using the `sizeof' operator.

 - Function: void setutxent (void)
     This function is similar to `setutent'.  On the GNU system it is
     simply an alias for `setutent'.

 - Function: struct utmpx * getutxent (void)
     The `getutxent' function is similar to `getutent', but returns a
     pointer to a `struct utmpx' instead of `struct utmp'.  On the GNU
     system it simply is an alias for `getutent'.

 - Function: void endutxent (void)
     This function is similar to `endutent'.  On the GNU system it is
     simply an alias for `endutent'.

 - Function: struct utmpx * getutxid (const struct utmpx *ID)
     This function is similar to `getutid', but uses `struct utmpx'
     instead of `struct utmp'.  On the GNU system it is simply an alias
     for `getutid'.

 - Function: struct utmpx * getutxline (const struct utmpx *LINE)
     This function is similar to `getutid', but uses `struct utmpx'
     instead of `struct utmp'.  On the GNU system it is simply an alias
     for `getutline'.

 - Function: struct utmpx * pututxline (const struct utmpx *UTMP)
     The `pututxline' function provides functionality identical to
     `pututline', but uses `struct utmpx' instead of `struct utmp'.  On
     the GNU system `pututxline' is simply an alias for `pututline'.

Logging In and Out
------------------

   These functions, derived from BSD, are available in the separate
`libutil' library, and declared in `utmp.h'.

   Note that the `ut_user' member of `struct utmp' is called `ut_name'
in BSD.  Therefore, `ut_name' is defined as an alias for `ut_user' in
`utmp.h'.

 - Function: int login_tty (int FILEDES)
     This function makes FILEDES the controlling terminal of the
     current process, redirects standard input, standard output and
     standard error output to this terminal, and closes FILEDES.

     This function returns `0' on successful completion, and `-1' on
     error.

 - Function: void login (const struct utmp *ENTRY)
     The `login' functions inserts an entry into the user accounting
     database.  The `ut_line' member is set to the name of the terminal
     on standard input.  If standard input is not a terminal `login'
     uses standard output or standard error output to determine the
     name of the terminal.  If `struct utmp' has a `ut_type' member,
     `login' sets it to `USER_PROCESS', and if there is an `ut_pid'
     member, it will be set to the process ID of the current process.
     The remaining entries are copied from ENTRY.

     A copy of the entry is written to the user accounting log file.

 - Function: int logout (const char *UT_LINE)
     This function modifies the user accounting database to indicate
     that the user on UT_LINE has logged out.

     The `logout' function returns `1' if the entry was successfully
     written to the database, or `0' on error.

 - Function: void logwtmp (const char *UT_LINE, const char *UT_NAME,
          const char *UT_HOST)
     The `logwtmp' function appends an entry to the user accounting log
     file, for the current time and the information provided in the
     UT_LINE, UT_NAME and UT_HOST arguments.

   *Portability Note:* The BSD `struct utmp' only has the `ut_line',
`ut_name', `ut_host' and `ut_time' members.  Older systems do not even
have the `ut_host' member.

User Database
=============

   This section describes how to search and scan the database of
registered users.  The database itself is kept in the file
`/etc/passwd' on most systems, but on some systems a special network
server gives access to it.

The Data Structure that Describes a User
----------------------------------------

   The functions and data structures for accessing the system user
database are declared in the header file `pwd.h'.

 - Data Type: struct passwd
     The `passwd' data structure is used to hold information about
     entries in the system user data base.  It has at least the
     following members:

    `char *pw_name'
          The user's login name.

    `char *pw_passwd.'
          The encrypted password string.

    `uid_t pw_uid'
          The user ID number.

    `gid_t pw_gid'
          The user's default group ID number.

    `char *pw_gecos'
          A string typically containing the user's real name, and
          possibly other information such as a phone number.

    `char *pw_dir'
          The user's home directory, or initial working directory.
          This might be a null pointer, in which case the
          interpretation is system-dependent.

    `char *pw_shell'
          The user's default shell, or the initial program run when the
          user logs in.  This might be a null pointer, indicating that
          the system default should be used.

Looking Up One User
-------------------

   You can search the system user database for information about a
specific user using `getpwuid' or `getpwnam'.  These functions are
declared in `pwd.h'.

 - Function: struct passwd * getpwuid (uid_t UID)
     This function returns a pointer to a statically-allocated structure
     containing information about the user whose user ID is UID.  This
     structure may be overwritten on subsequent calls to `getpwuid'.

     A null pointer value indicates there is no user in the data base
     with user ID UID.

 - Function: int getpwuid_r (uid_t UID, struct passwd *RESULT_BUF, char
          *BUFFER, size_t BUFLEN, struct passwd **RESULT)
     This function is similar to `getpwuid' in that it returns
     information about the user whose user ID is UID.  However, it
     fills the user supplied structure pointed to by RESULT_BUF with
     the information instead of using a static buffer.  The first
     BUFLEN bytes of the additional buffer pointed to by BUFFER are
     used to contain additional information, normally strings which are
     pointed to by the elements of the result structure.

     If a user with ID UID is found, the pointer returned in RESULT
     points to the record which contains the wanted data (i.e., RESULT
     contains the value RESULT_BUF).  If no user is found or if an
     error occurred, the pointer returned in RESULT is a null pointer.
     The function returns zero or an error code.  If the buffer BUFFER
     is too small to contain all the needed information, the error code
     `ERANGE' is returned and ERRNO is set to `ERANGE'.

 - Function: struct passwd * getpwnam (const char *NAME)
     This function returns a pointer to a statically-allocated structure
     containing information about the user whose user name is NAME.
     This structure may be overwritten on subsequent calls to
     `getpwnam'.

     A null pointer return indicates there is no user named NAME.

 - Function: int getpwnam_r (const char *NAME, struct passwd
          *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct passwd
          **RESULT)
     This function is similar to `getpwnam' in that is returns
     information about the user whose user name is NAME.  However, like
     `getpwuid_r', it fills the user supplied buffers in RESULT_BUF and
     BUFFER with the information instead of using a static buffer.

     The return values are the same as for `getpwuid_r'.

Scanning the List of All Users
------------------------------

   This section explains how a program can read the list of all users in
the system, one user at a time.  The functions described here are
declared in `pwd.h'.

   You can use the `fgetpwent' function to read user entries from a
particular file.

 - Function: struct passwd * fgetpwent (FILE *STREAM)
     This function reads the next user entry from STREAM and returns a
     pointer to the entry.  The structure is statically allocated and is
     rewritten on subsequent calls to `fgetpwent'.  You must copy the
     contents of the structure if you wish to save the information.

     The stream must correspond to a file in the same format as the
     standard password database file.

 - Function: int fgetpwent_r (FILE *STREAM, struct passwd *RESULT_BUF,
          char *BUFFER, size_t BUFLEN, struct passwd **RESULT)
     This function is similar to `fgetpwent' in that it reads the next
     user entry from STREAM.  But the result is returned in the
     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
     additional buffer pointed to by BUFFER are used to contain
     additional information, normally strings which are pointed to by
     the elements of the result structure.

     The stream must correspond to a file in the same format as the
     standard password database file.

     If the function returns zero RESULT points to the structure with
     the wanted data (normally this is in RESULT_BUF).  If errors
     occurred the return value is nonzero and RESULT contains a null
     pointer.

   The way to scan all the entries in the user database is with
`setpwent', `getpwent', and `endpwent'.

 - Function: void setpwent (void)
     This function initializes a stream which `getpwent' and
     `getpwent_r' use to read the user database.

 - Function: struct passwd * getpwent (void)
     The `getpwent' function reads the next entry from the stream
     initialized by `setpwent'.  It returns a pointer to the entry.  The
     structure is statically allocated and is rewritten on subsequent
     calls to `getpwent'.  You must copy the contents of the structure
     if you wish to save the information.

     A null pointer is returned when no more entries are available.

 - Function: int getpwent_r (struct passwd *RESULT_BUF, char *BUFFER,
          int BUFLEN, struct passwd **RESULT)
     This function is similar to `getpwent' in that it returns the next
     entry from the stream initialized by `setpwent'.  Like
     `fgetpwent_r', it uses the user-supplied buffers in RESULT_BUF and
     BUFFER to return the information requested.

     The return values are the same as for `fgetpwent_r'.

 - Function: void endpwent (void)
     This function closes the internal stream used by `getpwent' or
     `getpwent_r'.

Writing a User Entry
--------------------

 - Function: int putpwent (const struct passwd *P, FILE *STREAM)
     This function writes the user entry `*P' to the stream STREAM, in
     the format used for the standard user database file.  The return
     value is zero on success and nonzero on failure.

     This function exists for compatibility with SVID.  We recommend
     that you avoid using it, because it makes sense only on the
     assumption that the `struct passwd' structure has no members
     except the standard ones; on a system which merges the traditional
     Unix data base with other extended information about users, adding
     an entry using this function would inevitably leave out much of
     the important information.

     The function `putpwent' is declared in `pwd.h'.

Group Database
==============

   This section describes how to search and scan the database of
registered groups.  The database itself is kept in the file
`/etc/group' on most systems, but on some systems a special network
service provides access to it.

The Data Structure for a Group
------------------------------

   The functions and data structures for accessing the system group
database are declared in the header file `grp.h'.

 - Data Type: struct group
     The `group' structure is used to hold information about an entry in
     the system group database.  It has at least the following members:

    `char *gr_name'
          The name of the group.

    `gid_t gr_gid'
          The group ID of the group.

    `char **gr_mem'
          A vector of pointers to the names of users in the group.
          Each user name is a null-terminated string, and the vector
          itself is terminated by a null pointer.

Looking Up One Group
--------------------

   You can search the group database for information about a specific
group using `getgrgid' or `getgrnam'.  These functions are declared in
`grp.h'.

 - Function: struct group * getgrgid (gid_t GID)
     This function returns a pointer to a statically-allocated structure
     containing information about the group whose group ID is GID.
     This structure may be overwritten by subsequent calls to
     `getgrgid'.

     A null pointer indicates there is no group with ID GID.

 - Function: int getgrgid_r (gid_t GID, struct group *RESULT_BUF, char
          *BUFFER, size_t BUFLEN, struct group **RESULT)
     This function is similar to `getgrgid' in that it returns
     information about the group whose group ID is GID.  However, it
     fills the user supplied structure pointed to by RESULT_BUF with
     the information instead of using a static buffer.  The first
     BUFLEN bytes of the additional buffer pointed to by BUFFER are
     used to contain additional information, normally strings which are
     pointed to by the elements of the result structure.

     If a group with ID GID is found, the pointer returned in RESULT
     points to the record which contains the wanted data (i.e., RESULT
     contains the value RESULT_BUF).  If no group is found or if an
     error occurred, the pointer returned in RESULT is a null pointer.
     The function returns zero or an error code.  If the buffer BUFFER
     is too small to contain all the needed information, the error code
     `ERANGE' is returned and ERRNO is set to `ERANGE'.

 - Function: struct group * getgrnam (const char *NAME)
     This function returns a pointer to a statically-allocated structure
     containing information about the group whose group name is NAME.
     This structure may be overwritten by subsequent calls to
     `getgrnam'.

     A null pointer indicates there is no group named NAME.

 - Function: int getgrnam_r (const char *NAME, struct group
          *RESULT_BUF, char *BUFFER, size_t BUFLEN, struct group
          **RESULT)
     This function is similar to `getgrnam' in that is returns
     information about the group whose group name is NAME.  Like
     `getgrgid_r', it uses the user supplied buffers in RESULT_BUF and
     BUFFER, not a static buffer.

     The return values are the same as for `getgrgid_r' `ERANGE'.

Scanning the List of All Groups
-------------------------------

   This section explains how a program can read the list of all groups
in the system, one group at a time.  The functions described here are
declared in `grp.h'.

   You can use the `fgetgrent' function to read group entries from a
particular file.

 - Function: struct group * fgetgrent (FILE *STREAM)
     The `fgetgrent' function reads the next entry from STREAM.  It
     returns a pointer to the entry.  The structure is statically
     allocated and is overwritten on subsequent calls to `fgetgrent'.
     You must copy the contents of the structure if you wish to save the
     information.

     The stream must correspond to a file in the same format as the
     standard group database file.

 - Function: int fgetgrent_r (FILE *STREAM, struct group *RESULT_BUF,
          char *BUFFER, size_t BUFLEN, struct group **RESULT)
     This function is similar to `fgetgrent' in that it reads the next
     user entry from STREAM.  But the result is returned in the
     structure pointed to by RESULT_BUF.  The first BUFLEN bytes of the
     additional buffer pointed to by BUFFER are used to contain
     additional information, normally strings which are pointed to by
     the elements of the result structure.

     This stream must correspond to a file in the same format as the
     standard group database file.

     If the function returns zero RESULT points to the structure with
     the wanted data (normally this is in RESULT_BUF).  If errors
     occurred the return value is non-zero and RESULT contains a null
     pointer.

   The way to scan all the entries in the group database is with
`setgrent', `getgrent', and `endgrent'.

 - Function: void setgrent (void)
     This function initializes a stream for reading from the group data
     base.  You use this stream by calling `getgrent' or `getgrent_r'.

 - Function: struct group * getgrent (void)
     The `getgrent' function reads the next entry from the stream
     initialized by `setgrent'.  It returns a pointer to the entry.  The
     structure is statically allocated and is overwritten on subsequent
     calls to `getgrent'.  You must copy the contents of the structure
     if you wish to save the information.

 - Function: int getgrent_r (struct group *RESULT_BUF, char *BUFFER,
          size_t BUFLEN, struct group **RESULT)
     This function is similar to `getgrent' in that it returns the next
     entry from the stream initialized by `setgrent'.  Like
     `fgetgrent_r', it places the result in user-supplied buffers
     pointed to RESULT_BUF and BUFFER.

     If the function returns zero RESULT contains a pointer to the data
     (normally equal to RESULT_BUF).  If errors occurred the return
     value is non-zero and RESULT contains a null pointer.

 - Function: void endgrent (void)
     This function closes the internal stream used by `getgrent' or
     `getgrent_r'.