'\" te
.\"  Copyright (c) 1998, 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_SET_DATA 3PAM "Oct 13, 1998"
.SH NAME
pam_set_data, pam_get_data \- PAM routines to maintain module specific state
.SH SYNOPSIS
.LP
.nf
\fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
#include <security/pam_appl.h>



\fBint\fR \fBpam_set_data\fR(\fBpam_handle_t *\fR\fIpamh\fR,
     \fBconst char *\fR\fImodule_data_name\fR, \fBvoid *\fR\fIdata\fR,
     \fBvoid  (*\fR\fIcleanup\fR) (pam_handle_t *\fIpamh\fR, \fBvoid *\fR\fIdata\fR,
     \fBint\fR \fIpam_end_status\fR));
.fi

.LP
.nf
\fBint\fR \fBpam_get_data\fR(\fBconst pam_handle_t *\fR\fIpamh\fR,
     \fBconst char *\fR\fImodule_data_name\fR, \fBconst void **\fR\fIdata\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBpam_set_data()\fR and \fBpam_get_data()\fR functions allow \fBPAM\fR
service modules to access and update module specific information as needed.
These functions should not be used by applications.
.sp
.LP
The \fBpam_set_data()\fR function stores module specific data within the
\fBPAM\fR handle \fIpamh\fR. The \fImodule_data_name\fR argument uniquely
identifies the data, and the \fIdata\fR argument represents the actual data.
The \fImodule_data_name\fR argument should be unique across all services.
.sp
.LP
The \fIcleanup\fR function frees up any memory used by the \fIdata\fR after it
is no longer needed, and is invoked by \fBpam_end()\fR. The \fIcleanup\fR
function takes as its arguments a pointer to the  \fBPAM\fR handle, \fIpamh\fR,
a pointer to the actual data, \fIdata\fR, and a status code,
\fIpam_end_status\fR. The status code determines exactly what state information
needs to be  purged.
.sp
.LP
If \fBpam_set_data()\fR is called and module data already exists  from a prior
call to  \fBpam_set_data()\fR under the same \fImodule_data_name\fR, then the
existing \fIdata\fR is replaced by the new \fIdata\fR, and the existing
\fIcleanup\fR function is replaced by the new \fIcleanup\fR function.
.sp
.LP
The \fBpam_get_data()\fR function retrieves module-specific data stored in the
\fBPAM\fR handle, \fIpamh\fR, identified by the unique name,
\fImodule_data_name\fR. The \fIdata\fR argument is assigned the address of the
requested data. The  \fIdata\fR retrieved by \fBpam_get_data()\fR should not be
modified or freed.  The \fIdata\fR will be released by \fBpam_end()\fR.
.SH RETURN VALUES
.sp
.LP
In addition to the return values listed in \fBpam\fR(3PAM), the following value
may also be returned:
.sp
.ne 2
.na
\fB\fBPAM_NO_MODULE_DATA\fR\fR
.ad
.RS 22n
No module specific data is present.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for description 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
\fBpam\fR(3PAM), \fBpam_end\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.