usr/src/man/man3pam/pam_open_session.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_OPEN_SESSION 3PAM "Oct 13, 1998"
   7 .SH NAME
   8 pam_open_session, pam_close_session \- perform PAM session creation and
   9 termination operations
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lpam\fR [ \fIlibrary\fR ... ]
  14 #include <security/pam_appl.h>
  15
  16
  17
  18 \fBint\fR \fBpam_open_session\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIflags\fR);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBpam_close_session\fR(\fBpam_handle_t *\fR\fIpamh\fR, \fBint\fR \fIflags\fR);
  24 .fi
  25
  26 .SH DESCRIPTION
  27 .sp
  28 .LP
  29 The \fBpam_open_session()\fR function is called after a user has been
  30 successfully authenticated. See  \fBpam_authenticate\fR(3PAM) and
  31 \fBpam_acct_mgmt\fR(3PAM). It is used to notify the session modules that a new
  32 session  has been initiated.  All programs that use the  \fBpam\fR(3PAM)
  33 library should invoke \fBpam_open_session()\fR when beginning a new session.
  34 Upon termination of this activity, \fBpam_close_session()\fR should be invoked
  35 to inform \fBpam\fR(3PAM) that the session has terminated.
  36 .sp
  37 .LP
  38 The \fIpamh\fR argument is an authentication handle obtained by a prior call to
  39 \fBpam_start()\fR. The following flag may be set in the \fIflags\fR field for
  40 \fBpam_open_session()\fR and \fBpam_close_session()\fR:
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBPAM_SILENT\fR\fR
  45 .ad
  46 .RS 14n
  47 The session service should not generate any messages.
  48 .RE
  49
  50 .SH RETURN VALUES
  51 .sp
  52 .LP
  53 Upon successful completion,  \fBPAM_SUCCESS\fR is returned.  In addition to the
  54 return values defined in \fBpam\fR(3PAM), the following value may be returned
  55 on error:
  56 .sp
  57 .ne 2
  58 .na
  59 \fB\fBPAM_SESSION_ERR\fR\fR
  60 .ad
  61 .RS 19n
  62 Cannot make or remove an entry for the specified session.
  63 .RE
  64
  65 .SH ATTRIBUTES
  66 .sp
  67 .LP
  68 See \fBattributes\fR(5) for description of the following attributes:
  69 .sp
  70
  71 .sp
  72 .TS
  73 box;
  74 c | c
  75 l | l .
  76 ATTRIBUTE TYPE  ATTRIBUTE VALUE
  77 _
  78 Interface Stability      Stable
  79 _
  80 MT-Level        MT-Safe with exceptions
  81 .TE
  82
  83 .SH SEE ALSO
  84 .sp
  85 .LP
  86 \fBgetutxent\fR(3C), \fBpam\fR(3PAM), \fBpam_acct_mgmt\fR(3PAM),
  87 \fBpam_authenticate\fR(3PAM), \fBpam_start\fR(3PAM), \fBattributes\fR(5)
  88 .SH NOTES
  89 .sp
  90 .LP
  91 In many instances, the \fBpam_open_session()\fR and \fBpam_close_session()\fR
  92 calls may be made by different processes. For example, in UNIX the \fBlogin\fR
  93 process opens a session, while the \fBinit\fR process closes the session.  In
  94 this case, \fBUTMP/WTMP\fR entries may be used to link the call to
  95 \fBpam_close_session()\fR with an earlier call to \fBpam_open_session()\fR.
  96 This is possible because \fBUTMP/WTMP\fR entries are uniquely identified by a
  97 combination of attributes, including the user login name and device name, which
  98 are accessible through the  \fBPAM\fR handle, \fIpamh\fR. The call to
  99 \fBpam_open_session()\fR should precede  \fBUTMP/WTMP\fR entry management, and
 100 the call to \fBpam_close_session()\fR should follow  \fBUTMP/WTMP\fR exit
 101 management.
 102 .sp
 103 .LP
 104 The interfaces in  \fBlibpam\fR are MT-Safe only if each thread within the
 105 multithreaded application uses its own  \fBPAM\fR handle.