getpwent(3C)




NAME

     getpwnam,  getpwnam_r,   getpwent,   getpwent_r,   getpwuid,
     getpwuid_r, setpwent, endpwent, fgetpwent, fgetpwent_r - get
     password entry


SYNOPSIS

     #include <pwd.h>

     struct passwd *getpwnam(const char *name);

     struct passwd *getpwnam_r(const char  *name,  struct  passwd
     *pwd, char *buffer, int buflen);

     struct passwd *getpwent(void);

     struct passwd *getpwent_r(struct passwd *pwd, char  *buffer,
     int buflen);

     struct passwd *getpwuid(uid_t uid);

     struct passwd *getpwuid_r(uid_t  uid,  struct  passwd  *pwd,
     char *buffer, int buflen);

     void setpwent(void);

     void endpwent(void);

     struct passwd *fgetpwent(FILE *f);

     struct passwd *fgetpwent_r(FILE *f, struct passwd *pwd, char
     *buffer, int buflen);

  POSIX
     cc [ flag...] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]

     int getpwnam_r(const char *name, struct  passwd  *pwd,  char
     *buffer, size_t bufsize, struct passwd **result);

     int getpwuid_r(uid_t uid, struct passwd *pwd, char  *buffer,
     size_t bufsize, struct passwd **result);


DESCRIPTION

     These functions are used to obtain password entries. Entries
     can come from any of the sources for passwd specified in the
     /etc/nsswitch.conf file (see nsswitch.conf(4)).

     The getpwnam() function searches for a password  entry  with
     the  login  name specified by the character string parameter
     name.

     The getpwuid() function searches for a password  entry  with
     the (numeric) user ID specified by the parameter uid.
     The  setpwent(), getpwent(), and  endpwent()  functions  are
     used  to  enumerate  password  entries  from  the  database.
     setpwent() sets (or resets) the enumeration to the beginning
     of  the  set  of  password entries.  This function should be
     called  before  the  first  call  to  getpwent().  Calls  to
     getpwnam()  and getpwuid() leave the enumeration position in
     an  indeterminate  state.  Successive  calls  to  getpwent()
     return either successive entries or NULL, indicating the end
     of the enumeration.

     The endpwent() function may be called to indicate  that  the
     caller  expects  to  do no further password retrieval opera-
     tions; the system may then  close the password file, deallo-
     cate  resources  it  was  using,  and so forth.  It is still
     allowed, but possibly less efficient,  for  the  process  to
     call more password functions after calling endpwent().

     The fgetpwent() function, unlike the other functions  above,
     does  not  use  nsswitch.conf;  it reads and parses the next
     line from the stream f, which is assumed to have the  format
     of the passwd file.  See passwd(4).

  Reentrant Interfaces
     The  functions  getpwnam(),  getpwuid(),   getpwent(),   and
     fgetpwent()  use static storage that is reused in each call,
     making these routines unsafe for use in multithreaded appli-
     cations.

     The   parallel   functions    getpwnam_r(),    getpwuid_r(),
     getpwent_r(), and fgetpwent_r() provide reentrant interfaces
     for these operations.

     Each reentrant interface performs the same operation as  its
     non-reentrant  counterpart,  named by removing the "_r" suf-
     fix.  The reentrant interfaces, however,  use  buffers  sup-
     plied by the caller to store returned results, and  are safe
     for use in both single-threaded and  multithreaded  applica-
     tions.

     Each reentrant interface takes the same  parameters  as  its
     non-reentrant  counterpart,  as  well as the following addi-
     tional parameters.  The parameter pwd must be a pointer to a
     struct  passwd  structure  allocated by the caller.  On suc-
     cessful completion, the function returns the password  entry
     in  this  structure.  The parameter buffer is a pointer to a
     buffer supplied by the caller, used as storage space for the
     password  data.   All  of  the  pointers within the returned
     struct passwd pwd point to data stored within  this  buffer;
     see  RETURN  VALUES. The buffer must be large enough to hold
     all the data associated with the password entry.  The param-
     eter  buflen  (or  bufsize for the POSIX versions; see stan-
     dards(5)) should give the size in bytes of buffer. The POSIX
     versions  place  a  pointer to the modified pwd structure in
     the result parameter, instead of returning a pointer to this
     structure.

     For enumeration in multithreaded applications, the  position
     within  the enumeration is a process-wide property shared by
     all threads. The setpwent() function may be used in  a  mul-
     tithreaded  application  but resets the enumeration position
     for all threads.  If multiple threads  interleave  calls  to
     getpwent_r(), the threads will enumerate disjoint subsets of
     the password database.

     Like  their  non-reentrant  counterparts,  getpwnam_r()  and
     getpwuid_r()  leave  the enumeration position in an indeter-
     minate state.


RETURN VALUES

     Password entries are represented by the struct passwd struc-
     ture defined in <pwd.h>:

     struct passwd {
         char *pw_name;      /* user's login name */
         char *pw_passwd;    /* no longer used */
         uid_t pw_uid;       /* user's uid */
         gid_t pw_gid;       /* user's gid */
         char *pw_age;       /* not used */
         char *pw_comment;   /* not used */
         char *pw_gecos;     /* typically user's full name */
         char *pw_dir;       /* user's home dir */
         char *pw_shell;     /* user's login shell */
     };

     The pw_passwd member should not be  used  as  the  encrypted
     password  for  the  user;  use  getspnam()  or  getspnam_r()
     instead.  See  getspnam(3C).

     The getpwnam(), getpwnam_r(), getpwuid(),  and  getpwuid_r()
     functions  each  return a pointer to a struct passwd if they
     successfully locate  the  requested  entry;  otherwise  they
     return  NULL. Upon successful completion (including the case
     when the requested entry is not found), the POSIX  functions
     getpwnam_r()  and getpwuid_r() return 0. Otherwise, an error
     number is returned to indicate the error.

     The getpwent(), getpwent_r(), fgetpwent(), and fgetpwent_r()
     functions  each  return a pointer to a struct passwd if they
     successfully enumerate an entry; otherwise they return NULL,
     indicating the end of the enumeration.

     The  getpwnam(),  getpwuid(),  getpwent(),  and  fgetpwent()
     functions  use  static  storage,  so  returned  data must be
     copied before a subsequent call to any of these functions if
     the data is to be saved.

     When  the  pointer  returned  by  the  reentrant   functions
     getpwnam_r(),  getpwuid_r(), getpwent_r(), and fgetpwent_r()
     is non-null, it is always equal to the pwd pointer that  was
     supplied by the caller.


ERRORS

     The   reentrant   functions    getpwnam_r(),   getpwuid_r(),
     getpwent_r(),  and  fgetpwent_r()  will  return NULL and set
     errno  to  ERANGE  (or  in  the  case  of  POSIX   functions
     getpwnam_r()  and  getpwuid_r()  return the ERANGE error) if
     the length of the buffer supplied by  caller  is  not  large
     enough  to  store  the  result.  See Intro(2) for the proper
     usage and interpretation of errno in multithreaded  applica-
     tions.


USAGE

     Applications that  use  the  interfaces  described  on  this
     manual page cannot be linked statically, since the implemen-
     tations of these functions employ dynamic loading and  link-
     ing of shared objects at run time.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  MT-Level                   |  See "Reentrant  Interfaces"|
   |                             |  in DESCRIPTION.            |
   |_____________________________|_____________________________|


SEE ALSO

     nispasswd(1), passwd(1),  yppasswd(1),  Intro(2),  Intro(3),
     cuserid(3C),   getgrnam(3C),   getlogin(3C),   getspnam(3C),
     nsswitch.conf(4), passwd(4), shadow(4), attributes(5), stan-
     dards(5)


NOTES

     When compiling multithreaded programs, see  Intro(3),  Notes
     On Multithreaded Applications.

     Use   of   the   enumeration   interfaces   getpwent()   and
     getpwent_r()  is  discouraged;  enumeration is supported for
     the passwd file, NIS, and NIS+, but in general is not  effi-
     cient  and  may  not  be supported for all database sources.
     The  semantics  of  enumeration  are  discussed  further  in
     nsswitch.conf(4).

     Previous releases allowed the use of `+' and `-' entries  in
     /etc/passwd  to selectively include and exclude NIS entries.
     The primary usage of these `+/-' entries  is  superseded  by
     the  name  service switch, so the `+/-' form may not be sup-
     ported in future releases.

     If required, the `+/-' functionality can still  be  obtained
     for NIS by specifying compat as the source for passwd.

     If the `+/-' functionality is required in  conjunction  with
     NIS+,  specify  both  compat  as  the  source for passwd and
     nisplus as the source for the pseudo-database passwd_compat.
     See passwd(4), shadow(4), and nsswitch.conf(4) for details.

     If the `+/-'  is  used,  both  /etc/shadow  and  /etc/passwd
     should  have  the  same  `+'  and `-' entries to ensure con-
     sistency between the password and shadow databases.

     If a password entry from any  of  the  sources  contains  an
     empty  uid  or  gid field, that entry will be ignored by the
     files, NIS , and NIS+ name service  switch  backends.   This
     will cause the user to appear unknown to the system.

     If a password entry contains an empty gecos, home directory,
     or shell field, getpwnam() and getpwnam_r() return a pointer
     to a null string in  the  respective  field  of  the  passwd
     structure.

     If the shell field is empty, login(1) automatically  assigns
     the default shell.  See login(1).

     Solaris 2.4 and earlier releases provided definitions of the
     getpwnam_r()  and  getpwuid_r()  functions  as  specified in
     POSIX.1c Draft 6. The final POSIX.1c  standard  changed  the
     interface  for  these  functions.  Support  for  the Draft 6
     interface is provided for compatibility only and may not  be
     supported in future releases. New applications and libraries
     should use the POSIX standard interface.

     For       POSIX.1c-compliant        applications,        the
     _POSIX_PTHREAD_SEMANTICS  and _REENTRANT flags are automati-
     cally turned on by defining the _POSIX_C_SOURCE flag with  a
     value >= 199506L.


Man(1) output converted with man2html