.\" $XConsortium: pam_chauthtok.3 /main/5 1996/10/29 15:18:27 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc. 
.\" All Rights Reserved
.nr X
.TH pam_chauthtok 3 "9 Jan 1996"
.SH NAME
pam_chauthtok
\- perform passord related functions within the PAM framework
.SH SYNOPSIS
.LP
.B cc
.RI "[ " "flag" " \|.\|.\|. ] " "file" " \|.\|.\|."
.B \-lpam
.RI "[ " "library" " \|.\|.\|. ]"
.LP
.nf
.ft 3
#include <security/pam_appl.h>
.ft
.fi
.LP
.BI "int pam_chauthtok(pam_handle_t " "*pamh" ,
.BI "const int" " flags");
.SH DESCRIPTION
.IX "pam_chauthtok" "" "\fLpam_chauthtok\fP \(em request changing authentication token or get/set authentication attributes"
.B pam_chauthtok(\|)
is called to change the authentication token
associated with a particular user
referenced by the authentication handle,
.IR pamh.
.LP
The following flag may be passed in to
.BR pam_chauthtok(\|) :
.RS
.IP PAM_SILENT 30
The password service should not generate any messages
.IP PAM_CHANGE_EXPIRED_AUTHTOK 30
The password service should only update those passwords that have aged.
If this flag is not passed,
all password services should update their passwords.
.RE
.LP
Upon successful completion of the call, the authentication
token of the user will be changed in accordance with the 
password service configured in the system through
.BR pam.conf (4).
.SH NOTES
The flag
.SM PAM_CHANGE_EXPIRED_AUTHTOK
is typically used by a
.B login
application which has determined that the user's password has aged or expired.
Before allowing the user to login, the
.B login
application may invoke
.B pam_chauthtok(\|)
with this flag to allow the user to update the password.
Typically applications such as
.BR passwd (1)
should not use this flag.
.PP
.B pam_chauthtok(\|)
performs a preliminary check before attempting to update
passwords. This check is performed for each
password module in the stack as listed in 
.BR pam.conf (4).
The check may include pinging remote name services to determine
if they are available. If
.B pam_chauthtok(\|)
returns
PAM_TRY_AGAIN,
then the check has failed, and passwords are not updated.
.SH "RETURN VALUES"
.PP
Upon successful completion, PAM_SUCCESS is returned.
In addition to the error return values described in
.BR pam (3),
the following values may be returned:
.RS
.IP PAM_PERM_DENIED 34
No permission
.IP PAM_AUTHTOK_ERR 34
Authentication token manipulation error
.IP PAM_AUTHTOK_RECOVERY_ERR 34
Authentication information cannot be recovered
.IP PAM_AUTHTOK_LOCK_BUSY 34
Authentication token lock busy
.IP PAM_AUTHTOK_DISABLE_AGING 34
Authentication token aging disabled
.IP PAM_USER_UNKNOWN 34
User unknown to password service
.IP PAM_TRY_AGAIN 34
Preliminary check by password service failed
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3),
.BR pam_authenticate (3)