share/man/man3pam/pam_set_data.3pam

   1 '\" te
   2 .\"  Copyright (c) 1998, 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_SET_DATA 3PAM "Oct 13, 1998"
   7 .SH NAME
   8 pam_set_data, pam_get_data \- PAM routines to maintain module specific state
   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_set_data\fR(\fBpam_handle_t *\fR\fIpamh\fR,
  18      \fBconst char *\fR\fImodule_data_name\fR, \fBvoid *\fR\fIdata\fR,
  19      \fBvoid  (*\fR\fIcleanup\fR) (pam_handle_t *\fIpamh\fR, \fBvoid *\fR\fIdata\fR,
  20      \fBint\fR \fIpam_end_status\fR));
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBpam_get_data\fR(\fBconst pam_handle_t *\fR\fIpamh\fR,
  26      \fBconst char *\fR\fImodule_data_name\fR, \fBconst void **\fR\fIdata\fR);
  27 .fi
  28
  29 .SH DESCRIPTION
  30 .sp
  31 .LP
  32 The \fBpam_set_data()\fR and \fBpam_get_data()\fR functions allow \fBPAM\fR
  33 service modules to access and update module specific information as needed.
  34 These functions should not be used by applications.
  35 .sp
  36 .LP
  37 The \fBpam_set_data()\fR function stores module specific data within the
  38 \fBPAM\fR handle \fIpamh\fR. The \fImodule_data_name\fR argument uniquely
  39 identifies the data, and the \fIdata\fR argument represents the actual data.
  40 The \fImodule_data_name\fR argument should be unique across all services.
  41 .sp
  42 .LP
  43 The \fIcleanup\fR function frees up any memory used by the \fIdata\fR after it
  44 is no longer needed, and is invoked by \fBpam_end()\fR. The \fIcleanup\fR
  45 function takes as its arguments a pointer to the  \fBPAM\fR handle, \fIpamh\fR,
  46 a pointer to the actual data, \fIdata\fR, and a status code,
  47 \fIpam_end_status\fR. The status code determines exactly what state information
  48 needs to be  purged.
  49 .sp
  50 .LP
  51 If \fBpam_set_data()\fR is called and module data already exists  from a prior
  52 call to  \fBpam_set_data()\fR under the same \fImodule_data_name\fR, then the
  53 existing \fIdata\fR is replaced by the new \fIdata\fR, and the existing
  54 \fIcleanup\fR function is replaced by the new \fIcleanup\fR function.
  55 .sp
  56 .LP
  57 The \fBpam_get_data()\fR function retrieves module-specific data stored in the
  58 \fBPAM\fR handle, \fIpamh\fR, identified by the unique name,
  59 \fImodule_data_name\fR. The \fIdata\fR argument is assigned the address of the
  60 requested data. The  \fIdata\fR retrieved by \fBpam_get_data()\fR should not be
  61 modified or freed.  The \fIdata\fR will be released by \fBpam_end()\fR.
  62 .SH RETURN VALUES
  63 .sp
  64 .LP
  65 In addition to the return values listed in \fBpam\fR(3PAM), the following value
  66 may also be returned:
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fBPAM_NO_MODULE_DATA\fR\fR
  71 .ad
  72 .RS 22n
  73 No module specific data is present.
  74 .RE
  75
  76 .SH ATTRIBUTES
  77 .sp
  78 .LP
  79 See \fBattributes\fR(5) for description of the following attributes:
  80 .sp
  81
  82 .sp
  83 .TS
  84 box;
  85 c | c
  86 l | l .
  87 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  88 _
  89 Interface Stability      Stable
  90 _
  91 MT-Level        MT-Safe with exceptions
  92 .TE
  93
  94 .SH SEE ALSO
  95 .sp
  96 .LP
  97 \fBpam\fR(3PAM), \fBpam_end\fR(3PAM), \fBlibpam\fR(3LIB), \fBattributes\fR(5)
  98 .SH NOTES
  99 .sp
 100 .LP
 101 The interfaces in  \fBlibpam\fR are MT-Safe only if each thread within the
 102 multithreaded application uses its own  \fBPAM\fR handle.