Seth Woolley's Man Viewer

getpwnam(3) - getpwnam, getpwnam_r, getpwuid, getpwuid_r, getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file entry - man 3 getpwnam

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

GETPWNAM(3)                Linux Programmer's Manual               GETPWNAM(3)



NAME
       getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file(1,n) entry

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

       struct passwd(1,5) *getpwnam(const char *name);

       struct passwd(1,5) *getpwuid(uid_t uid);

       int getpwnam_r(const char *name, struct passwd(1,5) *pwbuf,
               char *buf, size_t buflen, struct passwd(1,5) **pwbufp);

       int getpwuid_r(uid_t uid, struct passwd(1,5) *pwbuf,
               char *buf, size_t buflen, struct passwd(1,5) **pwbufp);

DESCRIPTION
       The getpwnam() function returns a pointer to a structure containing the
       broken out fields of a line from /etc/passwd(1,5) for the entry that matches
       the user name name.

       The getpwuid() function returns a pointer to a structure containing the
       broken out fields of a line from /etc/passwd(1,5) for the entry that matches
       the user uid uid.

       The  getpwnam_r() and getpwuid_r() functions find the same information,
       but store the retrieved passwd(1,5) structure in(1,8) the  space  pointed  to  by
       pwbuf.   This  passwd(1,5) structure contains pointers to strings, and these
       strings are stored in(1,8) the buffer buf of size buflen.  A pointer to  the
       result  (in(1,8)  case of success) or NULL (in(1,8) case no entry was found or an
       error(8,n) occurred) is stored in(1,8) *pwbufp.

       The passwd(1,5) structure is defined in(1,8) <pwd.h> as follows:

              struct passwd(1,5) {
                    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 */
              };

       The maximum needed size for buf can be found using sysconf(3) with  the
       _SC_GETPW_R_SIZE_MAX parameter.

RETURN VALUE
       The  getpwnam() and getpwuid() functions return a pointer to the passwd(1,5)
       structure, or NULL if(3,n) the matching entry  is  not  found  or  an  error(8,n)
       occurs. If an error(8,n) occurs, errno is set(7,n,1 builtins) appropriately. If one wants to
       check errno after the call, it should be set(7,n,1 builtins) to zero before the call.

       The return value may point to static area, and may  be  overwritten  by
       subsequent calls to getpwent(), getpwnam(), or getpwuid().

       The  getpwnam_r() and getpwuid_r() functions return zero on success. In
       case of error(8,n), an error(8,n) value is returned.

ERRORS
       0 or ENOENT or ESRCH or EBADF or EPERM or ...
              The given name or uid was not found.

       EINTR  A signal(2,7) was caught.

       EIO    I/O error.

       EMFILE The maximum number (OPEN_MAX) of files was open(2,3,n) already  in(1,8)  the
              calling process.

       ENFILE The maximum number of files was open(2,3,n) already in(1,8) the system.

       ENOMEM Insufficient memory to allocate passwd(1,5) structure.

       ERANGE Insufficient buffer space supplied.

FILES
       /etc/passwd(1,5)
              password database file(1,n)

CONFORMING TO
       SVID 3, BSD 4.3, POSIX 1003.1-2003

NOTES
       The  formulation  given  above  under  "RETURN  VALUE"  is  from  POSIX
       1003.1-2001.  It does not call "not found" an  error(8,n),  hence  does  not
       specify  what  value errno might have in(1,8) this situation. But that makes
       it impossible to recognize errors. One might argue  that  according  to
       POSIX  errno should be left unchanged if(3,n) an entry is not found. Experi-
       ments on various Unix-like systems shows that lots of different  values
       occur  in(1,8)  this  situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM
       and probably others.

SEE ALSO
       endpwent(3), fgetpwent(3), getgrnam(3),  getpw(3),  getpwent(3),  putp-
       went(3), setpwent(3), passwd(1,5)(5)



GNU                               1996-05-27                       GETPWNAM(3)

References for this manual (incoming links)