GETPWENT(3)						     Library Functions Manual						       GETPWENT(3)

NAME

       getpwent, getpwnam, getpwuid, setpassent, setpwfile, setpwent, endpwent - get password file entries

SYNOPSIS

       #include <sys/types.h>
       #include <pwd.h>

       struct passwd *getpwent()

       struct passwd *getpwnam(login)
       char *login;

       struct passwd *getpwuid(uid)
       uid_t uid;

       int setpassent(stayopen)
       int stayopen;

       void setpwfile(file)
       char *file;

       int setpwent()

       void endpwent()

DESCRIPTION

       Getpwent,  getpwuid,  and  getpwnam  each  return a pointer to a structure containing the broken-out fields of a line in the password file.
       This structure is defined by the include file <pwd.h>, and contains the following fields:

	      struct passwd {
		   char *pw_name;	    /* user name */
		   char *pw_passwd;	    /* encrypted password */
		   uid_t     pw_uid;	    /* user uid */
		   gid_t     pw_gid;	    /* user gid */
		   time_t    pw_change;     /* password change time */
		   char *pw_class;	    /* user access class */
		   char *pw_gecos;	    /* Honeywell login info */
		   char *pw_dir;	    /* home directory */
		   char *pw_shell;	    /* default shell */
		   time_t    pw_expire;     /* account expiration */
	      };

       These fields are more completely described in passwd(5).

       Getpwnam and getpwuid search the password database for a matching user name or user uid, respectively, returning the first one encountered.
       Identical user names or user uids may result in undefined behavior.

       Getpwent sequentially reads the password database and is intended for programs that wish to step through the complete list of users.

       All three routines will open the password file for reading, if necessary.

       Setpwfile changes the default password file to file, thus allowing the use of alternate password files.

       Setpassent  opens  the  file  or  rewinds it if it is already open.  If stayopen is non-zero, file descriptors are left open, significantly
       speeding up subsequent calls.  This functionality is unnecessary for getpwent as it doesn't close its  file  descriptors  by  default.	It
       should  also  be  noted	that  it  is  dangerous for long-running programs to use this functionality as the password file may be updated by
       chpass(1), passwd(1), or vipw(8).

       Setpwent is identical to setpassent with an argument of zero.

       Endpwent closes any open files.

       These routines have been written to ``shadow'' the password file, e.g.  allow only certain programs to have access to the  encrypted  pass-
       word.  This is done by using the mkpasswd(8) program, which creates ndbm(3) databases that correspond to the password file, with the single
       exception that, rather than storing the encrypted password in the database, it stores the offset in the password file where  the  encrypted
       password may be found.  Getpwent, getpwnam, and getpwuid will use the ndbm files in preference to the ``real'' password files, only reading
       the password file itself, to obtain the encrypted password, if the process is running with an effective user id equivalent  to  super-user.
       If  the	password  file	itself	is  protected, and the ndbm files are not, this makes the password available only to programs running with
       super-user privileges.

FILES

       /etc/passwd

SEE ALSO

       getlogin(3), getgrent(3), ndbm(3), passwd(5)

DIAGNOSTICS

       The routines getpwent, getpwnam, and getpwuid, return a null pointer on EOF or error.  Setpassent and setpwent return 0 on failure and 1 on
       success.  Endpwent and setpwfile have no return value.

BUGS

       All information is contained in a static buffer which is overwritten by each new call.  It must be copied elsewhere to be retained.

       Intermixing  calls to getpwent with calls to getpwnam or getpwuid, or intermixing calls to getpwnam and getpwuid, after using setpassent to
       require that file descriptors be left open, may result in undefined behavior.

       The routines getpwent, endpwent, setpassent, and setpwent are fairly useless in a networked environment and should be avoided, if possible.

7th Edition							 February 23, 1989						       GETPWENT(3)