'\" te
.\"  Copyright (c) 2004, Sun Microsystems, Inc.   All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PAM_PUTENV 3PAM "Mar 1, 2004"
.SH NAME
pam_putenv \- change or add a value to the PAM environment
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
#include <security/pam_appl.h>



\fBint\fR \fBpam_putenv\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBconst char *\fR\fIname_value\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The  \fBpam_putenv()\fR function sets the value of the \fBPAM\fR environment
variable \fIname\fR equal to \fIvalue\fR either by altering an existing
\fBPAM\fR variable or by creating a new one.
.sp
.LP
The \fIname_value\fR argument points to a string of the form
\fIname\fR\fB=\fR\fIvalue\fR. A call to \fBpam_putenv()\fR does not immediately
change the environment. All \fIname_value\fR pairs are stored in the \fBPAM\fR
handle \fIpamh\fR. An application such as  \fBlogin\fR(1) may make a call to
\fBpam_getenv\fR(3PAM) or \fBpam_getenvlist\fR(3PAM) to retrieve the \fBPAM\fR
environment variables saved in the \fBPAM\fR handle and set them in the
environment if appropriate. \fBlogin\fR will not set \fBPAM\fR environment
values which overwrite the values for  \fBSHELL\fR, \fBHOME\fR, \fBLOGNAME\fR,
\fBMAIL\fR,\fB CDPATH\fR, \fBIFS\fR, and  \fBPATH\fR. Nor will \fBlogin\fR set
\fBPAM\fR environment values which overwrite any value that begins with
\fBLD_\fR.
.sp
.LP
If \fIname_value\fR equals  \fBNAME=\fR, then the value associated with
\fBNAME\fR in the \fBPAM\fR handle will be set to an empty value.  If
\fIname_value\fR equals  \fBNAME\fR, then the environment variable  \fBNAME\fR
will be removed from the \fBPAM\fR handle.
.SH RETURN VALUES
.sp
.LP
The \fBpam_putenv()\fR function may return one of the following values:
.sp
.ne 2
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 19n
The function returned successfully.
.RE

.sp
.ne 2
.na
\fB\fBPAM_OPEN_ERR\fR\fR
.ad
.RS 19n
\fBdlopen()\fR failed when dynamically loading a service module.
.RE

.sp
.ne 2
.na
\fB\fBPAM_SYMBOL_ERR\fR\fR
.ad
.RS 19n
Symbol not found.
.RE

.sp
.ne 2
.na
\fB\fBPAM_SERVICE_ERR\fR\fR
.ad
.RS 19n
Error in service module.
.RE

.sp
.ne 2
.na
\fB\fBPAM_SYSTEM_ERR\fR\fR
.ad
.RS 19n
System error.
.RE

.sp
.ne 2
.na
\fB\fBPAM_BUF_ERR\fR\fR
.ad
.RS 19n
Memory buffer error.
.RE

.sp
.ne 2
.na
\fB\fBPAM_CONV_ERR\fR\fR
.ad
.RS 19n
Conversation failure.
.RE

.sp
.ne 2
.na
\fB\fBPAM_PERM_DENIED\fR\fR
.ad
.RS 19n
Permission denied.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	 Stable
_
MT-Level	MT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
.BR dlopen (3C),
.BR libpam (3LIB),
.BR pam (3PAM),
.BR pam_getenv (3PAM),
.BR pam_getenvlist (3PAM),
.BR attributes (7)
.SH NOTES
.sp
.LP
The interfaces in  \fBlibpam\fR are MT-Safe only if each thread within the
multithreaded application uses its own \fBPAM\fR handle.