passwdexpiredx Subroutine

Purpose

Checks the user's password to determine whether it is expired, in multiple methods.

Syntax

passwdexpiredx (UserName, Message, State)
char *UserName;
char **Message;
char **State;

Description

The passwdexpiredx subroutine checks a user's password to determine whether it is expired. The subroutine uses the user's SYSTEM attribute to find out which administrative domains are used for password authentication.

The passwdexpiredx subroutine can pass back informational messages, such as how many days remain until password expiration.

The State parameter can contain information about the results of the authentication process. The State parameter from an earlier call to the authenticatex subroutine can be used to control how password expiration checking is performed. Authentication mechanisms that were not used to authenticate a user are not examined for expired passwords. The State parameter must be initialized to reference a null pointer if the State parameter from an earlier call to the authenticatex subroutine is not used.

Parameters

Table 1. Parameters
Item	Description
`UserName`	Specifies the user's name whose password is to be checked.
`Message`	Points to a pointer that the passwdexpiredx subroutine allocates memory for and completes. This string is suitable for printing, and it issues messages, such as an alert that indicates how many days are left before the password expires.
`State`	Points to a pointer that the passwdexpiredx subroutine allocates memory for and completes. The `State` parameter can also be the result of an earlier call to the authenticatex subroutine. The `State` parameter contains information about the results of the password expiration examination process for each term in the user's `SYSTEM` attribute. The calling application is responsible for freeing this memory when it is no longer needed for a subsequent call to the chpassx subroutine.

Return Values

Upon successful completion, the passwdexpiredx subroutine returns a value of 0. If this subroutine fails, it returns one of the following values:

Table 2. Return Values
Item	Description
-1	Indicates that an internal error is occurred, such as a memory allocation (malloc) failure or database corruption.
1	Indicates that one or more passwords are expired, and the user must change it. None of the expired passwords require system administrator intervention to be changed.
2	Indicates that one or more passwords are expired, at least one of which must be changed by the user and at least one of which requires system administrator intervention to be changed.
3	Indicates that all expired passwords require system administrator intervention to be changed.

Error Codes

The passwdexpiredx subroutine fails if one or more of the following values is true:

Table 3. Error Codes
Item	Description
`EACCES`	The user did not have permission to access the password attributes required to check password expiration.
`EINVAL`	The parameters are not valid.
`ENOENT`	The user might not be found.
`ENOMEM`	Memory allocation (malloc) failed.