svcadm(1M)을 검색하려면 섹션에서 1M 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
getpwnam(3c)
Standard C Library Functions getpwnam(3C)
NAME
getpwnam, getpwnam_r, getpwent, getpwent_r, getpwuid, getpwuid_r, setp‐
went, endpwent, fgetpwent, fgetpwent_r - get password entry
SYNOPSIS
#include <pwd.h>
struct passwd *getpwnam(const char *name);
int getpwnam_r(const char *name, struct passwd *pwd, char *buffer,
size_t bufsize, struct passwd **result);
struct passwd *getpwent(void);
struct passwd *getpwent_r(struct passwd *pwd, char *buffer,
int buflen);
struct passwd *getpwuid(uid_t uid);
int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer,
size_t bufsize, struct passwd **result);
void setpwent(void);
void endpwent(void);
struct passwd *fgetpwent(FILE *f);
struct passwd *fgetpwent_r(FILE *f, struct passwd *pwd,
char *buffer, int buflen);
POSIX.1c Draft 6
cc [ flag...] file... -D__USE_DRAFT6_PROTOTYPES__ [ library... ]
struct passwd *getpwnam_r(const char *name, struct passwd *pwd,
char *buffer, int buflen);
struct passwd *getpwuid_r(uid_t uid, struct passwd *pwd,
char *buffer, int buflen);
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 enu‐
merate 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 getp‐
went(). Calls to getpwnam() and getpwuid() leave the enumeration posi‐
tion 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-reen‐
trant 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 setp‐
went() function can be used in a multithreaded application but resets
the enumeration position for all threads. If multiple threads inter‐
leave calls to getpwent_r(), the threads will enumerate disjoint sub‐
sets 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() and getpwuid() 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. The getpwnam_r()
and getpwuid_r() functions return 0 upon success or an error number in
case of failure and do not set errno.
Applications wishing to check for error situations should set errno to
0 before calling getpwnam(), getpwuid(), getpwent(), getpwent_r(),
fgetpwent(), and fgetpwent_r(). If these functions return a null
pointer and errno is non-zero, an error occurred.
The getpwnam_r() and getpwuid_r() functions can return 0 in the case
where the requested entry is not found. The application needs to check
the return value and that the result 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 multi‐
threaded 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 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: get‐
pwuid(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:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelSee Reentrant
Interfaces in DESCRIPTION. _ StandardSee below.
For endpwent(), getpwent(), getpwnam(), getpwnam_r(), getpwuid(), getp‐
wuid_r(), and setpwent(), see standards(7).
SEE ALSO
passwd(1), yppasswd(1), Intro(2), cuserid(3C), getgrnam(3C), getlo‐
gin(3C), getspnam(3C), nsswitch.conf(5), passwd(5), shadow(5),
attributes(7), standards(7)
NOTES
Use of the enumeration interfaces getpwent() and getpwent_r() is dis‐
couraged; 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 nss‐
witch.conf(5).
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).
Prior to Oracle Solaris 11.4, the default compilation environment pro‐
vided definitions of the getpwnam_r() and getpwuid_r() functions as
specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
interfaces for getpwnam_r() and getpwuid_r(). To allow applications
that were written to use the obsolete Draft-6 interfaces to continue to
be compiled and run, the __USE_DRAFT6_PROTOTYPES__ macro must be
defined:
cc -D__USE_DRAFT6_PROTOTYPES__ ...
Support for the Draft-6 interfaces is provided for source compatibility
only and might not be supported in future releases. Old applications
should be converted to use the standard definitions.
Oracle Solaris 11.4 17 Aug 2018 getpwnam(3C)