--- name: "getpwuid" section: "3" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/getpwnam" --- # getpwuid(3) get password file entry Part of [getpwnam(3)](/getpwnam/3.md). ## NAME getpwnam, getpwnam\_r, getpwuid, getpwuid\_r - get password file entry ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #include #include ``` **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)](/feature_test_macros/7.md)): **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 *\* 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)](/passwd/5.md) 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)](/getpwent/3.md), **getpwnam**(), or **getpwuid**(). (Do not pass the returned pointer to [**free**(3)](/free/3.md).) 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)](/signal/7.md). - **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)](/attributes/7.md). | | | | | --- | --- | --- | | **Interface** | **Attribute** | **Value** | | **getpwnam**() | Thread safety | MT-Unsafe race:pwnam locale | | **getpwuid**() | Thread safety | MT-Unsafe race:pwuid locale | | **getpwnam\_r**(), **getpwuid\_r**() | Thread safety | MT-Safe locale | ## VERSIONS The *pw\_gecos* field is not specified in POSIX, but is present on most implementations. ## STANDARDS POSIX.1-2008. ## HISTORY POSIX.1-2001, SVr4, 4.3BSD. ## 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 #include #include #include #include #include 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); } ``` ## SEE ALSO [**endpwent**(3)](/endpwent/3.md), [**fgetpwent**(3)](/fgetpwent/3.md), [**getgrnam**(3)](/getgrnam/3.md), [**getpw**(3)](/getpw/3.md), [**getpwent**(3)](/getpwent/3.md), [**getspnam**(3)](/getspnam/3.md), [**putpwent**(3)](/putpwent/3.md), [**setpwent**(3)](/setpwent/3.md), [**passwd**(5)](/passwd/5.md)