Unix/Linux Go Back    


BSD 2.11 - man page for getpwent (bsd section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


GETPWENT(3)									      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  bro-
       ken-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 func-
       tionality 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 func-
       tionality 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 password.  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.   Getp-
       went,  getpwnam,  and getpwuid will use the ndbm files in preference to the ``real'' pass-
       word 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 pass-
       word file itself is protected, and the ndbm files are not, this makes the password  avail-
       able 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  net-
       worked environment and should be avoided, if possible.

7th Edition				February 23, 1989			      GETPWENT(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 05:25 AM.