getuserpwx Subroutine

Purpose

Accesses the user authentication data.

Library

Security Library (libc.a)

Syntax

#include <userpw.h>

struct userpwx *getuserpwx (User) char * User;

Description

The getuserpwx subroutine accesses user authentication information. Because of its greater granularity and extensibility, use it instead of the getpwent routines.

The getuserpwx subroutine reads the user's password information from the local administrative domain or from a loadable authentication module that supports the required user attributes.

The getuserpw subroutine opens the authentication database read-only if no other access has taken place, but the program should call setpwdb (S_READ) followed by endpwdb after access to the authentication database is no longer required.

The data returned by getuserpwx is stored in allocated memory and must be freed by the caller when the data is no longer required. The entire structure can be freed by invoking the free subroutine with the pointer returned by getuserpwx.

Parameters

Item	Description
User	Specifies the name of the user for which password information is read.

Security

Files accessed:

Item	Description
Mode	File
r	/etc/passwd
r	/etc/security/passwd

Return Values

If successful, the getuserpwx subroutine returns a valid pointer to a userpwx structure. Otherwise, a null pointer is returned and the errno global variable is set to indicate the error. The fields in a userpwx structure are defined in the userpw.h file, and they include the following members:

Item	Description
upw_name	Specifies the user's name.
upw_passwd	Specifies the user's encrypted password.
upw_lastupdate	Specifies the time, in seconds, since the epoch (that is, 00:00:00 GMT, 1 January 1970), when the password was last updated.
upw_flags	Specifies attributes of the password. This member is a bit mask of one or more of the following values, defined in the userpw.h file: PW_NOCHECK Specifies that new passwords need not meet password restrictions in effect for the system. PW_ADMCHG Specifies that the password was last set by an administrator and must be changed at the next successful use of the login or su command. PW_ADMIN Specifies that password information for this user can only be changed by the root user.
upw_authdb	Specifies the administrative domain containing the authentication data.

Error Codes

The getuserpwx subroutine fails if one of the following values is true:

Item	Description
EACCES	The user is not able to open the files that contain the password attributes.
ENOENT	The user does not have an entry in the /etc/security/passwd file or other administrative domain.

Subroutines invoked by the getuserpwx subroutine can also set errors.

Files

Item	Description
/etc/security/passwd	Contains user passwords.