 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
getpwent(3)
NAME
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
SYNOPSIS
#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 );
LIBRARY
Standard C Library (libc)
STANDARDS
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.
PARAMETERS
uid Specifies the ID of the user for which the attributes are to be read.
name
Specifies the name of the user for which the attributes are to be read.
pwd Specifies the location where the retrieved passwd structure is to be
placed.
passwd
Specifies the password structure that contains the user attributes that
are to be written.
file
Specifies a stream open for writing to a file.
result
Upon successful return, points to the retrieved passwd structure. Upon
unsuccessful return, the result is set to NULL.
buffer
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.
len 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.
f Specifies a file that contains the next passwd structure. (This is for
the fgetpwent() and fgetpwent_r() functions.)
pw_fp
Points to a file stream open for reading password entries.
filename
Specifies a new default password file rather than using the default
/etc/passwd file.
DESCRIPTION
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:
pw_name
The name of the user.
pw_passwd
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.
pw_uid
The ID of the user.
pw_gid
The group ID of the principle group of the user.
pw_gecos
The personal information about the user.
pw_dir
The home directory of the user.
pw_shell
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.
NOTES
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.
RETURN VALUES
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.
ERRORS
If any of the following conditions occurs, the getpwnam_r(), and
getpwuid_r() functions set errno to the corresponding value:
[ERANGE]
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.
FILES
/etc/passwd
/etc/passwd.dir
/etc/passwd.pag
SEE ALSO
Functions: getgrent(3), sia_getpasswd(3)
Standards: standards(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|