'\" te
.\"  Copyright (c) 2004, Sun Microsystems, Inc.   All Rights Reserved
.TH pam_putenv 3PAM "1 Mar 2004" "SunOS 5.11" "PAM Library Functions"
.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
.mk
.na
\fB\fBPAM_SUCCESS\fR\fR
.ad
.RS 19n
.rt  
The function returned successfully.
.RE

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

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

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

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

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

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

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

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

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelMT-Safe with exceptions
.TE

.SH SEE ALSO
.sp
.LP
\fBdlopen\fR(3C), \fBpam\fR(3PAM), \fBpam_getenv\fR(3PAM), \fBpam_getenvlist\fR(3PAM), \fBlibpam\fR(3LIB), \fBattributes\fR(5)
.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.