putuserpwx Subroutine

Purpose

Accesses the user authentication data.

Library

Security Library (libc.a)

Syntax

#include <userpw.h>

int putuserpwx  (Password)
struct userpwx *Password;

Description

The putuserpwx subroutine modifies user authentication information. It can be used with those administrative domains that support modifying the user's encrypted password with the putuserattrs subroutine. The chpassx subroutine must be used to modify authentication information for administrative domains that do not support that functionality.

The putuserpwx subroutine updates or creates password authentication data for the user who is defined in the Password parameter in the administrative domain that is specified. The password entry that is created by the putuserpwx subroutine is used only if there is an ! (Exclamation point) in the user's password (S_PWD) attribute. The user application can use the putuserattrs subroutine to add an ! to this field.

The putuserpwx subroutine opens the authentication database read-write if no other access has taken place, but the program must call setpwdb (S_READ | S_WRITE) before calling the putuserpwx subroutine and endpwdb when access to the authentication information is no longer required.

The administrative domain that is specified in the upw_authdb field is set by the getuserpwx subroutine. It must be specified by the application program if the getuserpwx subroutine is not used to produce the Password parameter.

Parameters

Table 1. Parameters
Item	Description
`Password`	Specifies the password structure that is used to update the password information for this user. The fields in a `userpwx` structure are defined in the userpw.h file and contains the following members: 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 the attributes of the password. This member is a bit mask of one or more of the following values, which are defined in the userpw.h file: PW_NOCHECK Specifies that new passwords need not to 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.

Security

Files accessed

Table 2. Files Accessed
Mode	File
rw	/etc/security/passwd

Return Values

If successful, the putuserpwx subroutine returns a value of 0. If the subroutine failed to update or create the password information, the putuserpwx subroutine returns a nonzero value.

Error Codes

The getuserpwx subroutine fails if the following value is true:

Table 3. Error Codes
Item	Description
`ENOENT`	The user does not have an entry in the /etc/security/passwd file.

Subroutines that are invoked by the putuserpwx subroutine can also set errors.

Files

Table 4. Files
Item	Description
/etc/security/passwd	Contains user passwords.