.\" $XConsortium: pam_setcred.3 /main/5 1996/10/29 15:19:22 drk $
.\" Sccs id goes here
'\"macro stdmacro
.\" Copyright (c) 1995, Sun Microsystems, Inc. 
.\" All Rights Reserved
.nr X
.TH pam_setcred 3 "9 Jan 1996"
.SH NAME
pam_setcred \- modify\/delete user credentials for 
an authentication service
.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_setcred(pam_handle_t " "*pamh" ,
.\" .BI "int " flags");
\fBint pam_setcred(pam_handle_t \fI*pamh\fB, int \fIflags\fB);
.SH DESCRIPTION
.IX "pam_setcred" "" "\fLpam_setcred\fP \(em request setting credentials"
.B pam_setcred(\|)
is used to establish, modify, or delete user credentials.
.B pam_setcred(\|)
is typically called after the user has been authenticated
and after a session has been opened (refer to
.BR pam_authenticate (3),
.BR pam_acct_mgmt (3),
and
.BR pam_open_session (3)).
.LP
The user is specified by a prior call to
.B pam_start(\|)
or
.B pam_set_item(\|),
and is referenced by the authentication handle,
.IR pamh.
The following flags may be set in the
.IR flags
field.  Note that the first four flags are mutually exclusive:
.RS
.IP "PAM_CRED_ESTABLISH" 26
Set user credentials for an authentication service
.IP "PAM_CRED_DELETE" 26
Delete user credentials associated with an authentication service
.IP "PAM_CRED_REINITIALIZE" 26
Reinitialize user credentials
.IP "PAM_CRED_REFRESH" 26
Extend lifetime of user credentials
.IP "PAM_SILENT" 26
Authentication service should not generate any messages
.RE
.LP
If none of the flags are set, PAM_CRED_ESTABLISH
is used as the default.
.SH "RETURN VALUES"
.PP
Upon success,
.B pam_setcred(\|)
returns PAM_SUCCESS.
In addition to the error return values described in
.BR pam (3),
the following values may be returned upon error:
.RS
.IP PAM_CRED_UNAVAIL 25
Underlying authentication service can not retrieve user credentials unavailable
.IP PAM_CRED_EXPIRED 25
User credentials expired
.IP PAM_USER_UNKNOWN 25
User unknown to underlying authentication service
.IP PAM_CRED_ERR 25
Failure setting user credentials
.RE
.SH "SEE ALSO"
.BR pam (3),
.BR pam_start (3),
.BR pam_authenticate (3),
.BR pam_acct_mgmt (3),
.BR pam_open_session (3)