struct
passwd
*
getpwent(
void
)
int
getpwent_r(
struct passwd *pw
char *buffer
size_t buflen
struct passwd **result
)
struct
passwd
*
getpwnam(
const char *name
)
int
getpwnam_r(
const char *name
struct passwd *pw
char *buffer
size_t buflen
struct passwd **result
)
struct
passwd
*
getpwuid(
uid_t uid
)
int
getpwuid_r(
uid_t uid
struct passwd *pw
char *buffer
size_t buflen
struct passwd **result
)
int
setpassent(
int stayopen
)
void
setpwent(
void
)
void
endpwent(
void
)
pwd.h
>:
struct passwd {
char *pw_name; /* user name */
char *pw_passwd; /* encrypted password */
uid_t pw_uid; /* user uid */
gid_t pw_gid; /* user gid */
time_t pw_change; /* password change time */
char *pw_class; /* user login class */
char *pw_gecos; /* general information */
char *pw_dir; /* home directory */
char *pw_shell; /* default shell */
time_t pw_expire; /* account expiration */
};
The functions
getpwnam()
and
getpwuid(
)
search the password database for the given user name pointed to by
name
or user id pointed to by
uid
respectively, always returning the first one encountered.
Identical user names or user ids may result in undefined behavior.
The
getpwent()
function
sequentially reads the password database and is intended for programs
that wish to process the complete list of users.
The functions
getpwnam_r(),
getpwuid_r(
),
and
getpwent_r(
)
act like their non re-entrant counterparts, updating the contents of
pw
and storing a pointer to that in
result,
and returning
0
.
Storage used by
pw
is allocated from
buffer,
which is
buflen
bytes in size.
If the requested entry cannot be found,
result
will point to
NULL
and
0
will be returned.
If an error occurs,
a non-zero error number will be returned and
result
will point to
NULL
.
Calling
getpwent_r()
from multiple threads will result in each thread reading a disjoint portion
of the password database.
The
setpassent()
function
accomplishes two purposes.
First, it causes
getpwent(
)
to
``rewind''
to the beginning of the database.
Additionally, if
stayopen
is non-zero, file descriptors are left open, significantly speeding
up subsequent accesses for all of the functions.
(This latter functionality is unnecessary for
getpwent()
as it doesn't close its file descriptors by default.)
It is dangerous for long-running programs to keep the file descriptors open as the database will become out of date if it is updated while the program is running.
The
setpwent()
function
is equivalent to
setpassent(
)
with an argument of zero.
The
endpwent()
function
closes any open files.
These functions have been written to ``shadow'' the password file, e.g. allow only certain programs to have access to the encrypted password. If the process which calls them has an effective uid of 0, the encrypted password will be returned, otherwise, the password field of the returned structure will point to the string `*'.
),
getpwnam(
),
and
getpwuid(
),
return a valid pointer to a passwd structure on success
and a
NULL
pointer if the entry was not found or an error occured.
If an error occured, the global variable
errno
is set to indicate the nature of the failure.
The
setpassent(
)
function returns 0 on failure, setting the global variable
errno
to indicate the nature of the failure, and 1 on success.
The
endpwent(
)
and
setpwent(
)
functions
have no return value.
The functions
getpwnam_r(
),
getpwuid_r(
),
and
getpwent_r(
)
return
0
on success or entry not found, and non-zero on failure, setting the global
variable
errno
to indicate the nature of the failure.
EIO
]
EINTR
]
EMFILE
]
ENFILE
]The following error code may be set in errno for getpwent_r, getpwnam_r, and getpwuid_r:
ERANGE
]
struct
passwd
does not fit in the space defined by
buffer
and
buflen
Other
errno
values may be set depending on the specific database backends.
/etc/pwd.db
/etc/spwd.db
/etc/master.passwd
/etc/passwd
)
and
getpwuid(
),
functions conform to
ISO/IEC 9945-1:1990 (``POSIX.1'') .
The
getpwnam_r(
)
and
getpwuid_r(
)
functions conform to
IEEE Std 1003.1c-1995 (``POSIX.1'') .
The
endpwent(
),
getpwent(
),
and
setpwent(
)
functions conform to
X/Open Portability Guide Issue 4, Version 2 (``XPG4.2'')
and
IEEE Std 1003.1-2004 (``POSIX.1'')
(XSI extension).
AT&T UNIX
.
The
setpassent
function appeared in
4.3BSDReno.
The functions
getpwnam_r(
)
and
getpwuid_r(
)
appeared in
NetBSD3.0.
),
getpwnam(
),
and
getpwuid(
),
leave their results in an internal static object and return
a pointer to that object.
Subsequent calls to any of these functions will modify the same object.
The functions
getpwent(),
endpwent(
),
setpassent(
),
and
setpwent(
)
are fairly useless in a networked environment and should be
avoided, if possible.
getpwent(
)
makes no attempt to suppress duplicate information if multiple
sources are specified in
nsswitch.conf(5).
)
which allowed the specification of alternative password databases,
has been deprecated and is no longer available.