getpwent(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨 페이지 이름
검색(S)

getpwent(3c)

Standard C Library Functions                                      getpwnam(3C)



NAME
       getpwnam, getpwnam_r, getpwent, getpwent_r, getpwuid, getpwuid_r, setp‐
       went, endpwent, fgetpwent, fgetpwent_r - get password entry

SYNOPSIS
       #include <pwd.h>

       struct passwd *getpwnam(const char *name);


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


       struct passwd *getpwent(void);


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


       struct passwd *getpwuid(uid_t uid);


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


       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.1c Draft 6
           cc [ flag...] file... -D__USE_DRAFT6_PROTOTYPES__ [ library... ]

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



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

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(5)).


       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 uid parameter.


       The setpwent(), getpwent(), and endpwent() functions are used  to  enu‐
       merate password entries from the database. The setpwent() function sets
       (or resets) the enumeration to the beginning of  the  set  of  password
       entries.  This function should be called before the first call to getp‐
       went(). Calls to getpwnam() and getpwuid() leave the enumeration  posi‐
       tion  in  an indeterminate state. Successive calls to getpwent() return
       either successive entries or a null pointer, indicating the end of  the
       enumeration.


       The  endpwent()  function  may  be  called  to indicate that the caller
       expects to do no further password retrieval operations; the system  may
       then close the password file, deallocate 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 but reads and parses the next line from the stream f,
       which is assumed to have the format of the passwd file. See passwd(5).

   Reentrant Interfaces
       The  getpwnam(),  getpwuid(), getpwent(), and fgetpwent() functions use
       thread-specific data storage that is reused in  each  call  to  one  of
       these  functions  by  the  same thread, making them safe to use but not
       recommended for multithreaded applications.


       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-reen‐
       trant counterpart, named by removing the  "_r"  suffix.  The  reentrant
       interfaces,  however,  use  buffers  supplied  by  the  caller to store
       returned results instead of using  thread-specific  data  that  can  be
       overwritten by each call. They are safe for use in both single-threaded
       and multithreaded applications.


       Each reentrant interface takes the same parameters as its non-reentrant
       counterpart,  as  well  as the following additional parameters. The pwd
       parameter must be a pointer to a struct passwd structure  allocated  by
       the caller. On successful 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 pointers within the returned  struct  passwd   pwd  point  to  data
       stored  within this buffer; see passwd Structure below. The buffer must
       be large enough to hold all  the  data  associated  with  the  password
       entry.  The  parameter  buflen  (or bufsize for the standard-conforming
       versions; see standards(7)) should give the size in  bytes  of  buffer.
       The  maximum  size  needed  for  this buffer can be determined with the
       {_SC_GETPW_R_SIZE_MAX} sysconf(3C) parameter.  The  standard-conforming
       versions  place  a  pointer to the modified pwd structure in the result
       parameter, instead of returning a pointer to  this  structure.  A  null
       pointer is returned at the location pointed to by result on error or if
       the requested entry is not found.


       For enumeration in multithreaded applications, the position within  the
       enumeration is a process-wide property shared by all threads. The setp‐
       went() function can be used in a multithreaded application  but  resets
       the  enumeration  position  for all threads. If multiple threads inter‐
       leave calls to getpwent_r(), the threads will enumerate  disjoint  sub‐
       sets of the password database.


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

   passwd Structure
       Password entries are represented by the struct passwd structure 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).

RETURN VALUES
       The getpwnam() and getpwuid() functions each  return  a  pointer  to  a
       struct  passwd  if they successfully locate the requested entry. A null
       pointer is returned if the requested entry is not found,  or  an  error
       occurs.  On error, errno is set to indicate the error. The getpwnam_r()
       and getpwuid_r() functions return 0 upon success or an error number  in
       case of failure and do not set errno.


       Applications  wishing to check for error situations should set errno to
       0 before  calling  getpwnam(),  getpwuid(),  getpwent(),  getpwent_r(),
       fgetpwent(),  and  fgetpwent_r().  If  these  functions  return  a null
       pointer and errno is non-zero, an error occurred.


       The getpwnam_r() and getpwuid_r() functions can return 0  in  the  case
       where  the requested entry is not found. The application needs to check
       the return value and that the result pointer is non-null. Otherwise, an
       error value 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 a null pointer on end-of-file or error.
       On error, errno is set to indicate the error.


       See Intro(2) for the proper usage and interpretation of errno in multi‐
       threaded applications.


       The  getpwnam(),  getpwuid(), getpwent(), and fgetpwent() functions use
       thread-specific data 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 getpwent_r() and
       fgetpwent_r() is non-null, it is always equal to the pwd  pointer  that
       was supplied by the caller.

ERRORS
       The  getpwent_r(),  fgetpwent(),  and fgetpwent_r() functions will fail
       if:

       EIO       An I/O error has occurred.


       ERANGE    Insufficient storage was supplied by buffer  and  bufsize  to
                 contain  the  data  to  be referenced by the resulting passwd
                 structure.



       The getpwent_r() function will fail if:

       EMFILE    There are {OPEN_MAX} file descriptors currently open  in  the
                 calling process.


       ENFILE    The  maximum  allowable  number of files is currently open in
                 the system.



       The getpwnam(),  getpwnam_r(),  getpwuid(),  getpwuid_r(),  getpwent(),
       setpwent(), and endpwent() functions may fail if:

       EIO    An I/O error has occurred.



       The getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), getpwent(), and
       setpwent() functions may fail if:

       EMFILE    There are {OPEN_MAX} file descriptors currently open  in  the
                 calling process.


       ENFILE    The  maximum  allowable  number of files is currently open in
                 the system.



       The getpwnam(), getpwnam_r(), getpwuid(),  and  getpwuid_r()  functions
       may fail if:

       EINTR    A signal was caught during the execution of the function call.



       The getpwnam_r() and getpwuid_r() functions may fail if:

       ERANGE    Insufficient  storage  was  supplied by buffer and bufsize to
                 contain the data to be referenced  by  the  resulting  passwd
                 structure.


USAGE
       Three names associated with the current process can be determined: get‐
       pwuid(geteuid()) returns the name associated with the effective user ID
       of the process; getlogin() returns the name associated with the current
       login activity; and getpwuid(getuid()) returns the name associated with
       the real user ID of the process.

ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       tab()  box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
       TRIBUTE VALUE _ Interface StabilityCommitted  _  MT-LevelSee  Reentrant
       Interfaces in DESCRIPTION.  _ StandardSee below.



       For endpwent(), getpwent(), getpwnam(), getpwnam_r(), getpwuid(), getp‐
       wuid_r(), and setpwent(), see standards(7).

SEE ALSO
       passwd(1), yppasswd(1),  Intro(2),  cuserid(3C),  getgrnam(3C),  getlo‐
       gin(3C),    getspnam(3C),   nsswitch.conf(5),   passwd(5),   shadow(5),
       attributes(7), standards(7)

NOTES
       Use of the enumeration interfaces getpwent() and getpwent_r()  is  dis‐
       couraged;  enumeration is supported for the passwd file and NIS, but in
       general is not efficient and might not be supported  for  all  database
       sources.  The  semantics  of  enumeration are discussed further in nss‐
       witch.conf(5).


       If a password entry from any of the sources contains an  empty  uid  or
       gid field, that entry will be ignored by the files and NIS name service
       switch backends, causing 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).


       Prior  to Oracle Solaris 11.4, the default compilation environment pro‐
       vided definitions of the getpwnam_r()  and  getpwuid_r()  functions  as
       specified  in POSIX.1c Draft 6. The final POSIX.1c standard changed the
       interfaces for getpwnam_r() and  getpwuid_r().  To  allow  applications
       that were written to use the obsolete Draft-6 interfaces to continue to
       be compiled  and  run,  the  __USE_DRAFT6_PROTOTYPES__  macro  must  be
       defined:

         cc -D__USE_DRAFT6_PROTOTYPES__ ...



       Support for the Draft-6 interfaces is provided for source compatibility
       only and might not be supported in future  releases.  Old  applications
       should be converted to use the standard definitions.



Oracle Solaris 11.4               17 Aug 2018                     getpwnam(3C)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3