Ubuntu manuals

Provided by: manpages-dev_2.17-1_all

NAME

       getpwent, setpwent, endpwent - get password file entry

SYNOPSIS

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

       struct passwd *getpwent(void);

       void setpwent(void);

       void endpwent(void);

DESCRIPTION

       The getpwent() function returns a pointer to a structure containing the
       broken-out fields of a record from the  password  database  (e.g.,  the
       local  password file /etc/passwd, NIS, and LDAP).  The first time it is
       called it returns the first entry; thereafter,  it  returns  successive
       entries.

       The  setpwent()  function  rewinds  to  the  beginning  of the password
       database.

       The endpwent() function is used to close the  password  database  after
       all processing has been performed.

       The passwd structure is defined in <pwd.h> as follows:

          struct passwd {
              char   *pw_name;       /* user name */
              char   *pw_passwd;     /* user password */
              uid_t   pw_uid;        /* user ID */
              gid_t   pw_gid;        /* group ID */
              char   *pw_gecos;      /* real name */
              char   *pw_dir;        /* home directory */
              char   *pw_shell;      /* shell program */
          };

       When  shadow(5)  passwords  are  enabled  (which  is  default  on  many
       GNU/Linux installations) the content of pw_passwd is usually  not  very
       useful.  In such a case most passwords are stored in a separate file.

       The  variable  pw_shell  may  be  empty,  in which case the system will
       execute the default shell (/bin/sh) for the user.

RETURN VALUE

       The getpwent() function returns a pointer to  a  passwd  structure,  or
       NULL  if  there  are  no more entries or an error occured.  If an error
       occurs, errno is set appropriately.  If one wants to check errno  after
       the call, it should be set to zero before the call.

ERRORS

       EINTR  A signal was caught.

       EIO    I/O error.

       EMFILE The  maximum  number (OPEN_MAX) of files was open already in the
              alling process.

       ENFILE The maximum number of files was open already in the system.

       ENOMEM Insufficient memory to allocate passwd structure.

       ERANGE Insufficient buffer space supplied.

FILES

       /etc/passwd
              local password database file

CONFORMING TO

       SVID 3, 4.3BSD

SEE ALSO

       fgetpwent(3),  getpw(3),   getpwent_r(3),   getpwnam(3),   getpwuid(3),
       putpwent(3), shadow(5), passwd(5)