Tribblix: manual page: getpwnam.3c

GETPWNAM(3C) Standard C Library Functions GETPWNAM(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);

Standard conforming

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(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
enumerate 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 getpwent(). Calls to getpwnam() and getpwuid() leave the
enumeration position 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-
reentrant 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
setpwent() function can be used in a multithreaded 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 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(), getpwnam_r(), getpwuid(), and getpwuid_r() 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.

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

The standard-conforming functions getpwnam_r() and getpwuid_r() can
return 0 even on an error, particularly in the case where the
requested entry is not found. The application needs to check the
return value and that the pwd 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
multithreaded 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 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 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:
getpwuid(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:

+--------------------+------------------------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+------------------------------------------+
|Interface Stability | Committed |
+--------------------+------------------------------------------+
|MT-Level | See Reentrant Interfaces in DESCRIPTION. |
+--------------------+------------------------------------------+
|Standard | See below. |
+--------------------+------------------------------------------+

For endpwent(), getpwent(), getpwnam(), getpwnam_r(), getpwuid(),
getpwuid_r(), and setpwent(), see standards(7).

NOTES

When compiling multithreaded programs, see Intro(3).

Use of the enumeration interfaces getpwent() and getpwent_r() is
discouraged; 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 nsswitch.conf(5).

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 might not be supported in future
releases.

If required, the `+/-' functionality can still be obtained for NIS by
specifying compat as the source for passwd. See nsswitch.conf(5).

If the `+/-' is used, both /etc/shadow and /etc/passwd should have
the same `+' and `-' entries to ensure consistency 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 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).

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 might not be supported in future releases. New
applications and libraries should use the standard-conforming
interface.

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

February 25, 2017 GETPWNAM(3C)