.\" Hey Emacs! This file is -*- nroff -*- source.
.\" $Id$
.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net>
.TH PAM_SETCRED 3 "1997 July 6" "Linux-PAM 0.58" "App. Programmers' Manual"
.SH NAME

pam_setcred \- set the credentials for the user

.SH SYNOPSIS
.B #include <security/pam_appl.h>
.sp
.BI "int pam_setcred(pam_handle_t " *pamh ", int  " flags ");"
.sp 2
.SH DESCRIPTION
.B pam_setcred

This function is used to establish, maintain and delete the
credentials of a user. It should be called after a user has been
authenticated and before a session is opened for the user (with
.BR pam_open_session "(3))."

It should be noted that credentials come in many forms. Examples
include: group memberships; ticket-files; and Linux-PAM environment
variables.  For this reason, it is important that the basic identity
of the user is established, by the application, prior to a call to
this function.  For example, the default
.BR Linux-PAM
environment variables should be set and also
.BR initgroups "(2) "
(or equivalent) should have been performed.

.SH "VALID FLAGS"
.TP
.BR PAM_ESTABLISH_CRED
initialize the credentials for the user.

.TP
.BR PAM_DELETE_CRED
delete the user's credentials.

.TP
.BR PAM_REINITIALIZE_CRED
delete and then initialize the user's credentials.

.TP
.BR PAM_REFRESH_CRED
extend the lifetime of the existing credentials.

.SH "RETURN VALUE"

On success
.BR PAM_SUCCESS
is returned, all other return values should be treated as errors.

.SH ERRORS
May be translated to text with
.BR pam_strerror "(3). "

.SH "CONFORMING TO"
DCE-RFC 86.0, October 1995.

.SH BUGS
.sp 2
none known.

.SH "SEE ALSO"

.BR pam_authenticate "(3), "
.BR pam_strerror "(3)"
and
.BR pam_open_session "(3). "

Also, see the three
.BR Linux-PAM
Guides, for
.BR "System administrators" ", "
.BR "module developers" ", "
and
.BR "application developers" ". "