# getpwnam

## NAME



           getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file
           entry
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <sys/types.h>**
           **#include <pwd.h>**
    
           **struct passwd *getpwnam(const char ***_name_**);**
           **struct passwd *getpwuid(uid_t** _uid_**);**
    
           **int getpwnam_r(** size_t size;
                          **const char *restrict** _name_**, struct passwd *restrict** _pwd_**,**
                          **char** _buf_**[restrict** _size_**], size_t** _size_**,**
                          **struct passwd **restrict** _result_**);**
           **int getpwuid_r(** size_t size;
                          **uid_t** _uid_**, struct passwd *restrict** _pwd_**,**
                          **char** _buf_**[restrict** _size_**], size_t** _size_**,**
                          **struct passwd **restrict** _result_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **getpwnam_r**(), **getpwuid_r**():
               _POSIX_C_SOURCE
                   || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
    


## DESCRIPTION



           The **getpwnam**() function returns a pointer to a structure
           containing the broken-out fields of the record in the password
           database (e.g., the local password file _/etc/passwd_ , NIS, and
           LDAP) that matches the username _name_.
    
           The **getpwuid**() function returns a pointer to a structure
           containing the broken-out fields of the record in the password
           database that matches the user ID _uid_.
    
           The _passwd_ structure is defined in _< pwd.h>_ as follows:
    
               struct passwd {
                   char   *pw_name;       /* username */
                   char   *pw_passwd;     /* user password */
                   uid_t   pw_uid;        /* user ID */
                   gid_t   pw_gid;        /* group ID */
                   char   *pw_gecos;      /* user information */
                   char   *pw_dir;        /* home directory */
                   char   *pw_shell;      /* shell program */
               };
    
           See passwd(5) for more information about these fields.
    
           The **getpwnam_r**() and **getpwuid_r**() functions obtain the same
           information as **getpwnam**() and **getpwuid**(), but store the retrieved
           _passwd_ structure in the space pointed to by _pwd_.  The string
           fields pointed to by the members of the _passwd_ structure are
           stored in the buffer _buf_ of size _size_.  A pointer to the result
           (in case of success) or NULL (in case no entry was found or an
           error occurred) is stored in _*result_.
    
           The call
    
               sysconf(_SC_GETPW_R_SIZE_MAX)
    
           returns either -1, without changing _errno_ , or an initial suggested
           size for _buf_.  (If this size is too small, the call fails with
           **ERANGE** , in which case the caller can retry with a larger buffer.)
    


## RETURN VALUE



           The **getpwnam**() and **getpwuid**() functions return a pointer to a
           _passwd_ structure, or NULL if the matching entry is not found or an
           error occurs.  If an error occurs, _errno_ is set to indicate the
           error.  If one wants to check _errno_ after the call, it should be
           set to zero before the call.
    
           The return value may point to a static area, and may be
           overwritten by subsequent calls to getpwent(3), **getpwnam**(), or
           **getpwuid**().  (Do not pass the returned pointer to free(3).)
    
           On success, **getpwnam_r**() and **getpwuid_r**() return zero, and set
           _*result_ to _pwd_.  If no matching password record was found, these
           functions return 0 and store NULL in _*result_.  In case of error,
           an error number is returned, and NULL is stored in _*result_.
    


## ERRORS



           **0** or **ENOENT** or **ESRCH** or **EBADF** or **EPERM** or ...
                  The given _name_ or _uid_ was not found.
    
           **EINTR** A signal was caught; see signal(7).
    
           **EIO** I/O error.
    
           **EMFILE** The per-process limit on the number of open file
                  descriptors has been reached.
    
           **ENFILE** The system-wide limit on the total number of open files has
                  been reached.
    
           **ENOMEM** Insufficient memory to allocate _passwd_ structure.
    
           **ERANGE** Insufficient buffer space supplied.
    


## FILES



           _/etc/passwd_
                  local password database file
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌───────────────┬───────────────┬────────────────────────────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├───────────────┼───────────────┼────────────────────────────────┤
           │ **getpwnam**()    │ Thread safety │ MT-Unsafe race:pwnam locale    │
           ├───────────────┼───────────────┼────────────────────────────────┤
           │ **getpwuid**()    │ Thread safety │ MT-Unsafe race:pwuid locale    │
           ├───────────────┼───────────────┼────────────────────────────────┤
           │ **getpwnam_r**(), │ Thread safety │ MT-Safe locale                 │
           │ **getpwuid_r**()  │               │                                │
           └───────────────┴───────────────┴────────────────────────────────┘
    


## VERSIONS



           The _pw_gecos_ field is not specified in POSIX, but is present on
           most implementations.
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           The formulation given above under "RETURN VALUE" is from
           POSIX.1-2001.  It does not call "not found" an error, and hence
           does not specify what value _errno_ might have in this situation.
           But that makes it impossible to recognize errors.  One might argue
           that according to POSIX _errno_ should be left unchanged if an entry
           is not found.  Experiments on various UNIX-like systems show that
           lots of different values occur in this situation: 0, ENOENT,
           EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
    
           The _pw_dir_ field contains the name of the initial working
           directory of the user.  Login programs use the value of this field
           to initialize the **HOME** environment variable for the login shell.
           An application that wants to determine its user's home directory
           should inspect the value of **HOME**(rather than the value
           _getpwuid(getuid())- >pw_dir_) since this allows the user to modify
           their notion of "the home directory" during a login session.  To
           determine the (initial) home directory of another user, it is
           necessary to use _getpwnam("username")- >pw_dir_ or similar.
    


## EXAMPLES



           The program below demonstrates the use of **getpwnam_r**() to find the
           full username and user ID for the username supplied as a command-
           line argument.
    
           #include <errno.h>
           #include <pwd.h>
           #include <stdint.h>
           #include <stdio.h>
           #include <stdlib.h>
           #include <unistd.h>
    
           int
           main(int argc, char *argv[])
           {
               struct passwd pwd;
               struct passwd *result;
               char *buf;
               long bufsize;
               int s;
    
               if (argc != 2) {
                   fprintf(stderr, "Usage: %s username\n", argv[0]);
                   exit(EXIT_FAILURE);
               }
    
               bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
               if (bufsize == -1)          /* Value was indeterminate */
                   bufsize = 16384;        /* Should be more than enough */
    
               buf = malloc(bufsize);
               if (buf == NULL) {
                   perror("malloc");
                   exit(EXIT_FAILURE);
               }
    
               s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
               if (result == NULL) {
                   if (s == 0)
                       printf("Not found\n");
                   else {
                       errno = s;
                       perror("getpwnam_r");
                   }
                   exit(EXIT_FAILURE);
               }
    
               printf("Name: %s; UID: %jd\n", pwd.pw_gecos,
                      (intmax_t) pwd.pw_uid);
               exit(EXIT_SUCCESS);
           }
    


* * *