Standard C Library Functions getpwnam(3C)
NAME
getpwnam, getpwnamr, getpwent, getpwentr, getpwuid,
getpwuidr, setpwent, endpwent, fgetpwent, fgetpwentr - get
password entry
SYNOPSIS
#include
struct passwd *getpwnam(const char *name);
struct passwd *getpwnamr(const char *name, struct passwd *pwd,
char *buffer, int buflen);
struct passwd *getpwent(void);
struct passwd *getpwentr(struct passwd *pwd, char *buffer,
int buflen);
struct passwd *getpwuid(uidt uid);
struct passwd *getpwuidr(uidt uid, struct passwd *pwd,
char *buffer, int buflen);
void setpwent(void);
void endpwent(void);
struct passwd *fgetpwent(FILE *f);
struct passwd *fgetpwentr(FILE *f, struct passwd *pwd,
char *buffer, int buflen);
Standard conforming
cc [ flag...] file... -DPOSIXPTHREADSEMANTICS [ library... ]
int getpwnamr(const char *name, struct passwd *pwd, char *buffer,
sizet bufsize, struct passwd **result);
int getpwuidr(uidt uid, struct passwd *pwd, char *buffer,
sizet bufsize, struct passwd **result);
SunOS 5.11 Last change: 5 Apr 2004 1
Standard C Library Functions getpwnam(3C)
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(4)).
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, indicat-
ing the end of the enumeration.
The endpwent() function may be called to indicate that the
caller expects to do no further password retrieval opera-
tions; the system may then close the password file, deallo-
cate 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(4).
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, mak-
ing them safe to use but not recommended for multithreaded
applications.
The parallel functions getpwnamr(), getpwuidr(),
getpwentr(), and fgetpwentr() provide reentrant interfaces
for these operations.
SunOS 5.11 Last change: 5 Apr 2004 2
Standard C Library Functions getpwnam(3C)
Each reentrant interface performs the same operation as its
non-reentrant counterpart, named by removing the "r" suf-
fix. 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 mul-
tithreaded applications.
Each reentrant interface takes the same parameters as its
non-reentrant counterpart, as well as the following addi-
tional parameters. The pwd parameter must be a pointer to a
struct passwd structure allocated by the caller. On success-
ful 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(5)) should give the size in bytes of
buffer. The maximum size needed for this buffer can be
determined with the {SCGETPWRSIZEMAX} 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 mul-
tithreaded application but resets the enumeration position
for all threads. If multiple threads interleave calls to
getpwentr(), the threads will enumerate disjoint subsets of
the password database.
Like their non-reentrant counterparts, getpwnamr() and
getpwuidr() leave the enumeration position in an indeter-
minate state.
passwd Structure
Password entries are represented by the struct passwd struc-
ture defined in :
struct passwd {
char *pwname; /* user's login name */
char *pwpasswd; /* no longer used */
uidt pwuid; /* user's uid */
SunOS 5.11 Last change: 5 Apr 2004 3
Standard C Library Functions getpwnam(3C)
gidt pwgid; /* user's gid */
char *pwage; /* not used */
char *pwcomment; /* not used */
char *pwgecos; /* typically user's full name */
char *pwdir; /* user's home dir */
char *pwshell; /* user's login shell */
};
The pwpasswd member should not be used as the encrypted
password for the user; use getspnam() or getspnamr()
instead. See getspnam(3C).
RETURN VALUES
The getpwnam(), getpwnamr(), getpwuid(), and getpwuidr()
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(), getpwnamr(),
getpwuid(), getpwuidr(), getpwent(), getpwentr(),
fgetpwent(), and fgetpwentr(). If these non-reentrant func-
tions return a null pointer and errno is non-zero, an error
occurred.
The standard-conforming functions getpwnamr() and
getpwuidr() can return 0 even on an error, particularly in
the case where the requested entry is not found. The appli-
cation 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(), getpwentr(), fgetpwent(), and fgetpwentr()
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
SunOS 5.11 Last change: 5 Apr 2004 4
Standard C Library Functions getpwnam(3C)
functions if the data is to be saved.
When the pointer returned by the reentrant functions
getpwnamr(), getpwuidr(), getpwentr(), and fgetpwentr()
is non-null, it is always equal to the pwd pointer that was
supplied by the caller.
ERORS
The getpwentr(), fgetpwent(), and fgetpwentr() 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 getpwentr() function will fail if:
EMFILE There are {OPENMAX} file descriptors currently
open in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
The getpwnam(), getpwnamr(), getpwuid(), getpwuidr(),
getpwent(), setpwent(), and endpwent() functions may fail
if:
EIO An I/O error has occurred.
The getpwnam(), getpwnamr(), getpwuid(), getpwuidr(),
getpwent(), and setpwent() functions may fail if:
EMFILE There are {OPENMAX} file descriptors currently
open in the calling process.
ENFILE The maximum allowable number of files is currently
open in the system.
SunOS 5.11 Last change: 5 Apr 2004 5
Standard C Library Functions getpwnam(3C)
The getpwnam(), getpwnamr(), getpwuid(), and getpwuidr()
functions may fail if:
EINTR A signal was caught during the execution of the
function call.
The getpwnamr() and getpwuidr() 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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level See Reentrant Interfaces in DESCRIPTION.
Standard See below.
For endpwent(), getpwent(), getpwnam(), getpwnamr(),
getpwuid(), getpwuidr(), and setpwent(), see standards(5).
SEE ALSO
nispasswd(1), passwd(1), yppasswd(1), Intro(2), Intro(3),
cuserid(3C), getgrnam(3C), getlogin(3C), getspnam(3C),
nsswitch.conf(4), passwd(4), shadow(4), attributes(5), stan-
dards(5)
NOTES
SunOS 5.11 Last change: 5 Apr 2004 6
Standard C Library Functions getpwnam(3C)
When compiling multithreaded programs, see Intro(3).
Use of the enumeration interfaces getpwent() and
getpwentr() is discouraged; enumeration is supported for
the passwd file, NIS, and NIS], but in general is not effi-
cient and might not be supported for all database sources.
The semantics of enumeration are discussed further in
nsswitch.conf(4).
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 sup-
ported in future releases.
If required, the `]/-' functionality can still be obtained
for NIS by specifying compat as the source for passwd.
If the `]/-' functionality is required in conjunction with
NIS], specify both compat as the source for passwd and
nisplus as the source for the pseudo-database passwdcompat.
See passwd(4), shadow(4), and nsswitch.conf(4) for details.
If the `]/-' is used, both /etc/shadow and /etc/passwd
should have the same `]' and `-' entries to ensure con-
sistency 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, NIS, 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 getpwnamr() 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
getpwnamr() and getpwuidr() functions as specified in
POSIX.1c Draft 6. The final POSIX.1c standard changed the
SunOS 5.11 Last change: 5 Apr 2004 7
Standard C Library Functions getpwnam(3C)
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
POSIXPTHREADSEMANTICS and RENTRANT flags are automati-
cally turned on by defining the POSIXCSOURCE flag with a
value >199506L.
SunOS 5.11 Last change: 5 Apr 2004 8
|
