usr/src/man/man3pam/pam_putenv.3pam

   1 '\" te
   2 .\"  Copyright (c) 2004, Sun Microsystems, Inc.   All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH PAM_PUTENV 3PAM "Mar 1, 2004"
   7 .SH NAME
   8 pam_putenv \- change or add a value to the PAM environment
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
  13 #include <security/pam_appl.h>
  14
  15
  16
  17 \fBint\fR \fBpam_putenv\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBconst char *\fR\fIname_value\fR);
  18 .fi
  19
  20 .SH DESCRIPTION
  21 .sp
  22 .LP
  23 The  \fBpam_putenv()\fR function sets the value of the \fBPAM\fR environment
  24 variable \fIname\fR equal to \fIvalue\fR either by altering an existing
  25 \fBPAM\fR variable or by creating a new one.
  26 .sp
  27 .LP
  28 The \fIname_value\fR argument points to a string of the form
  29 \fIname\fR\fB=\fR\fIvalue\fR. A call to \fBpam_putenv()\fR does not immediately
  30 change the environment. All \fIname_value\fR pairs are stored in the \fBPAM\fR
  31 handle \fIpamh\fR. An application such as  \fBlogin\fR(1) may make a call to
  32 \fBpam_getenv\fR(3PAM) or \fBpam_getenvlist\fR(3PAM) to retrieve the \fBPAM\fR
  33 environment variables saved in the \fBPAM\fR handle and set them in the
  34 environment if appropriate. \fBlogin\fR will not set \fBPAM\fR environment
  35 values which overwrite the values for  \fBSHELL\fR, \fBHOME\fR, \fBLOGNAME\fR,
  36 \fBMAIL\fR,\fB CDPATH\fR, \fBIFS\fR, and  \fBPATH\fR. Nor will \fBlogin\fR set
  37 \fBPAM\fR environment values which overwrite any value that begins with
  38 \fBLD_\fR.
  39 .sp
  40 .LP
  41 If \fIname_value\fR equals  \fBNAME=\fR, then the value associated with
  42 \fBNAME\fR in the \fBPAM\fR handle will be set to an empty value.  If
  43 \fIname_value\fR equals  \fBNAME\fR, then the environment variable  \fBNAME\fR
  44 will be removed from the \fBPAM\fR handle.
  45 .SH RETURN VALUES
  46 .sp
  47 .LP
  48 The \fBpam_putenv()\fR function may return one of the following values:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fBPAM_SUCCESS\fR\fR
  53 .ad
  54 .RS 19n
  55 The function returned successfully.
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fBPAM_OPEN_ERR\fR\fR
  62 .ad
  63 .RS 19n
  64 \fBdlopen()\fR failed when dynamically loading a service module.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBPAM_SYMBOL_ERR\fR\fR
  71 .ad
  72 .RS 19n
  73 Symbol not found.
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fBPAM_SERVICE_ERR\fR\fR
  80 .ad
  81 .RS 19n
  82 Error in service module.
  83 .RE
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBPAM_SYSTEM_ERR\fR\fR
  89 .ad
  90 .RS 19n
  91 System error.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBPAM_BUF_ERR\fR\fR
  98 .ad
  99 .RS 19n
 100 Memory buffer error.
 101 .RE
 102
 103 .sp
 104 .ne 2
 105 .na
 106 \fB\fBPAM_CONV_ERR\fR\fR
 107 .ad
 108 .RS 19n
 109 Conversation failure.
 110 .RE
 111
 112 .sp
 113 .ne 2
 114 .na
 115 \fB\fBPAM_PERM_DENIED\fR\fR
 116 .ad
 117 .RS 19n
 118 Permission denied.
 119 .RE
 120
 121 .SH ATTRIBUTES
 122 .sp
 123 .LP
 124 See \fBattributes\fR(5) for descriptions of the following attributes:
 125 .sp
 126
 127 .sp
 128 .TS
 129 box;
 130 c | c
 131 l | l .
 132 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 133 _
 134 Interface Stability      Stable
 135 _
 136 MT-Level        MT-Safe with exceptions
 137 .TE
 138
 139 .SH SEE ALSO
 140 .sp
 141 .LP
 142 \fBdlopen\fR(3C), \fBpam\fR(3PAM), \fBpam_getenv\fR(3PAM),
 143 \fBpam_getenvlist\fR(3PAM), \fBlibpam\fR(3LIB), \fBattributes\fR(5)
 144 .SH NOTES
 145 .sp
 146 .LP
 147 The interfaces in  \fBlibpam\fR are MT-Safe only if each thread within the
 148 multithreaded application uses its own \fBPAM\fR handle.