endpwent, fgetpwent, getpwent, getpwnam, getpwuid, putpwent,
setpwent, setpwfile, endpwent_r, fgetpwent_r, getpwent_r,
getpwnam_r, getpwuid_r, setpwent_r - Access user
attribute information in the user database
#include <pwd.h>
void endpwent(
void ); struct passwd *fgetpwent(
FILE *f ); struct passwd *getpwent(
void ); struct passwd *getpwnam(
const char *name ); struct passwd *getpwuid(
uid_t uid ); int putpwent(
struct passwd *passwd,
FILE *file ); void setpwent(
void ); void setpwfile(
const char *filename ); void endpwent_r(
FILE **pw_fp ); int fgetpwent_r(
FILE *f,
struct passwd *pwd,
char *buffer,
int len ); int getpwent_r(
struct passwd *pwd,
char *buffer,
int len,
FILE **pw_fp ); int getpwnam_r(
const char *name,
struct passwd *pwd,
char *buffer,
size_t len,
struct passwd **result ); int getpwuid_r(
uid_t uid,
struct passwd *pwd,
char *buffer,
size_t len,
struct passwd **result ); int setpwent_r(
FILE **pw_fp );
The following functions do not conform to industry standards
and are supported only for backward compatibility
reasons. You should not use them in new designs. int setpwent(
void ); int getpwnam_r(
const char *name,
struct passwd *result,
char *buffer,
int len ); int getpwuid_r(
uid_t uid,
struct passwd *result,
char *buffer,
int len );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
endpwent(), getpwent(), getpwnam(), getpwnam_r(), getpwuid(),
getpwuid_r(), setpwent(): XSH5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Specifies the ID of the user for which the attributes are
to be read. Specifies the name of the user for which the
attributes are to be read. Specifies the location where
the retrieved passwd structure is to be placed. Specifies
the password structure that contains the user attributes
that are to be written. Specifies a stream open for writing
to a file. Upon successful return, points to the
retrieved passwd structure. Upon unsuccessful return, the
result is set to NULL. A working buffer for the result
parameter that is able to hold the largest password entry
in /etc/passwd.
[Tru64 UNIX] The minimum buffer size is 1024 bytes
as defined for SIABUFSIZ in /usr/include/sia.h.
Specifies the length of the character array that
buffer points to.
[Tru64 UNIX] The minimum buffer size is 1024 bytes
as defined for SIABUFSIZ in /usr/include/sia.h.
Specifies a file that contains the next passwd
structure. (This is for the fgetpwent() and fgetpwent_r()
functions.) Points to a file stream open
for reading password entries. Specifies a new
default password file rather than using the default
/etc/passwd file.
The endpwent(), fgetpwent(), getpwent(), getpwnam(), getpwuid(),
putpwent(), and setpwent() functions may be used
to access the basic user attributes.
The getpwent(), getpwnam(), and getpwuid() functions
return information about the specified user. The getpwent()
function returns the next user entry in a sequential
search that may use a private file pointer. The getpwnam()
function returns the first user entry in the
database with a pw_name field that matches the name parameter.
The getpwuid() function returns the first user
entry in the database with a pw_uid field that matches the
uid parameter.
The putpwent() function writes a password entry into a
file in the colon-separated format of the /etc/passwd
file.
The setpwent() function ensures that the next call to getpwent()
returns the first entry.
The endpwent() function closes the user database and any
private stream used by getpwent(). When the /etc/passwd
file is updated, it may be necessary to call endpwent() to
ensure that subsequent getpwent() calls will return the
new data.
The user structure, which is returned by the getpwent(),
getpwnam(), and getpwuid() functions and which is written
by the putpwent() function, is defined in the pwd.h file
and has the following members: The name of the user. The
encrypted password of the user. If the password is not
stored in the /etc/passwd file and the invoker does not
have access to the shadow file that contains them, this
field will contain an unencryptable string. The ID of the
user. The group ID of the principle group of the user.
The personal information about the user. The home directory
of the user. The initial program for the user.
The endpwent_r(), fgetpwent_r() getpwent_r(), getpwnam_r(),
getpwuid_r(), and setpwent_r() functions are the
reentrant versions of the endpwent(), fgetpwent() getpwent(),
getpwnam(), getpwuid(), and setpwent() functions,
respectively.
The endpwent_r(), getpwent_r(), and setpwent_r() functions
use the pw_fp parameter to keep track of the calls to the
getpwent_r() function, so that subsequent calls will
return subsequent password entries from the /etc/passwd
file. The setpwent_r() function must be called with the
address of a valid file pointer (which may be NULL). Upon
successful completion, the result is stored in result.
The fgetpwent() and fgetpwent_r() functions get a password
file entry from the file specified by the f parameter,
rather than from the /etc/passwd file. This file must have
the format of the /etc/passwd file.
The setpwfile() function sets the new default password
file to be filename instead of /etc/passwd.
[Tru64 UNIX] The system searches using NIS if NIS is
available and your /etc/passwd file has NIS type entries
(that is, +:, +name, +@netgroup, and -@netgroup). The
fgetpw* routines do not use NIS. The operating system provides
the getpwent_local, getpwuid_local, and getpwnam_local
routines to avoid NIS. The getpw*_local routines
are proprietary and are not in the pwd.h header file.
All information generated by the fgetpwent(), getpwent(),
getpwnam(), and getpwuid() functions is stored in a static
area and will be overwritten on subsequent calls to these
routines. These static areas may include private I/O
streams or network resources.
Password file entries that are too long are ignored.
Note that the pw_fp parameter must be initialized by the
user to NULL before the setpwent_r() function is called
for the first time.
Upon successful completion, the fgetpwent(), getpwent(),
getpwnam(), and getpwuid() functions return a pointer to a
valid password structure. Otherwise, NULL is returned.
Upon successful completion, the getpwnam_r and getpwuid_r
functions return a value of 0 (zero). If the user or group
is not found in the password or group database, these routines
return 0 for the status and a NULL in the returned
"result" pointer.
Upon successful completion, the fgetpwent_r() and getpwent_r()
functions (as well as the obsolete versions of
the getpwnam_r() and getpwuid_r() functions, return a
value of 0 (zero). Otherwise, they return a value of -1
and set errno to indicate the error.
If any of the following conditions occurs, the getpwnam_r(),
and getpwuid_r() functions set errno to the corresponding
value: The amount of storage specified by
buffer and len is too small to contain the data to be referenced
by the resulting struct passwd structure.
SEE ALSO
Functions: getgrent(3), sia_getpasswd(3)
Standards: standards(5)
getpwent(3)
[ Back ] |
