Changes user passwords.
Standard C Library (libc.a)
Thread Safe Security Library (libs_r.a)
int chpass (UserName, Response, Reenter, Message)
char *UserName;
char *Response;
int *Reenter;
char **Message;The chpass subroutine maintains the requirements that the user must meet to change a password. This subroutine is the basic building block for changing passwords and handles password changes for local, NIS, and DCE user passwords.
The Message parameter provides a series of messages asking for old and new passwords, or providing informational messages, such as the reason for a password change failing. The first Message prompt is a prompt for the old password. This parameter does not prompt for the old password if the user has a real user ID of 0 (zero) and is changing a local user, or if the user has no current password. The chpass subroutine does not prompt a user with root authority for an old password. It informs the program that no message was sent and that it should invoke chpass again. If the user satisfies the first Message parameter's prompt, the system prompts the user to enter the new password. Each message is contained in the Message parameter and is displayed to the user. The Response parameter returns the user's response to the chpass subroutine.
The Reenter parameter indicates when a user has satisfied all prompt messages. The parameter remains nonzero until a user has passed all prompts. After the returned value of Reenter is 0, the return code signals whether the password change has succeeded or failed. When progressing through prompts for a user, the value of Reenter must be maintained by the caller between invocations of chpass.
The chpass subroutine maintains internal state information concerning the next prompt message to present to the user. If the calling program supplies a different user name before all prompt messages are complete for the user, the internal state information is reset and prompt messages begin again. State information is also kept in the Reenter variable. The calling program must maintain the value of Reenter between calls to chpass.
The chpass subroutine determines the administration domain to use during password changes. It determines if the user is defined locally, defined in Network Information Service (NIS), or defined in Distributed Computing Environment (DCE). Password changes occur only in these domains. System administrators may override this convention with the registry value in the /etc/security/user file. If the registry value is defined, the password change can only occur in the specified domain. System administrators can use this registry value if the user is administered on a remote machine that periodically goes down. If the user is allowed to log in through some other authentication method while the server is down, password changes remain to follow only the primary server.
The chpass subroutine allows the user to change passwords in two ways. For normal (non-administrative) password changes, the user must supply the old password, either on the first call to the chpass subroutine or in response to the first message from chpass. If the user is root, real user ID of 0, local administrative password changes are handled by supplying a null pointer for the Response parameter during the initial call
Users that are not administered locally are always queried for their old password.
Any step in the above process can result in the chpass subroutine terminating the dialog. This is signalled when the reenter variable is set to 0. The return code indicates the nature of the failure.
| Item | Description |
|---|---|
| UserName | Specifies the user's name whose password is to be changed. |
| Response | Specifies a character string containing the user's response to the last prompt. |
| Reenter | Points to a Boolean value used to signal whether the chpass subroutine has completed processing. If the Reenter parameter is a nonzero value, the chpass subroutine expects the user to satisfy the prompt message provided by the Message parameter. If the Reenter parameter is 0, the chpass subroutine has completed processing. |
| Message | Points to a pointer that the chpass subroutine allocates memory for and fills in. This replacement string is then suitable for printing and issues challenge messages (if the Reenter parameter is a nonzero value). The string can also issue informational messages such as why the user failed to change the password (if the Reenter parameter is 0). The calling application is responsible for freeing this memory. |
Upon successful completion, the chpass subroutine returns a value of 0. If the chpass subroutine is unsuccessful, it returns the following values:
| Item | Description |
|---|---|
| -1 | Indicates the call failed in the thread safe library libs_r.a. ERRNO will indicate the failure code. |
| 1 | Indicates that the password change was unsuccessful and the user should attempt again. This return value occurs if a password restriction is not met, such as if the password is not long enough. |
| 2 | Indicates that the password change was unsuccessful and the user should not attempt again. This return value occurs if the user enters an incorrect old password or if the network is down (the password change cannot occur). |
The chpass subroutine is unsuccessful if one of the following values is true:
| Item | Description |
|---|---|
| ENOENT | Indicates that the user cannot be found. |
| ESAD | Indicates that the user did not meet the criteria to change the password. |
| EPERM | Indicates that the user did not have permission to change the password. |
| EINVAL | Indicates that the parameters are not valid. |
| ENOMEM | Indicates that memory allocation (malloc) failed. |