granicus.if.org Git - linux-pam/blob - doc/man/pam_open_session.3

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\" $Id$
   3 .\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
   4 .TH PAM_OPEN_SESSION 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
   5 .SH NAME
   6
   7 pam_open/close_session \- PAM session management
   8
   9 .SH SYNOPSIS
  10 .B #include <security/pam_appl.h>
  11 .sp
  12 .BI "int pam_open_session(pam_handle_t " *pamh ", int  " flags ");"
  13 .sp
  14 .BI "int pam_close_session(pam_handle_t " *pamh ", int  " flags ");"
  15 .sp 2
  16 .SH DESCRIPTION
  17
  18 PAM provides management-hooks for the initialization and termination
  19 of a session.
  20
  21 .TP
  22 .B pam_open_session
  23 .br
  24 Use this function to signal that an authenticated user session has
  25 begun. It should be called only after the user is properly identified
  26 and (where necessary) has been granted their credentials with
  27 .BR pam_authenticate "(3)"
  28 and
  29 .BR pam_setcred "(3)"
  30 respectively.
  31
  32 .br
  33 Some types of functions associated with session
  34 initialization are logging for the purposes of system-audit and
  35 mounting directories (the user's home directory for example). These
  36 should not concern the application. It should be noted that the
  37 .I effective
  38 uid,
  39 .BR geteuid "(2),"
  40 of the application should be of sufficient privilege to perform such
  41 tasks.
  42
  43 .TP
  44 .B pam_close_session
  45 .br
  46 Use this function to signal that a user session has
  47 terminated. In general this function may not need to be located in the
  48 same application as the initialization function,
  49 .BR pam_open_session "."
  50
  51 .br
  52 Typically, this function will undo the actions of
  53 .BR pam_open_session "."
  54 That is, log audit information concerning the end of the user session
  55 or unmount the user's home directory. Apart from having sufficient
  56 privilege the details of the session termination should not concern
  57 the calling application. It is good programming practice, however, to
  58 cease acting on behalf of the user on returning from this call.
  59
  60 .SH RETURN VALUE
  61 A successful return from the session management functions will be
  62 indicated with
  63 .BR PAM_SUCCESS "."
  64
  65 .br
  66 The specific error indicating a failure to open or close a session is
  67 .BR PAM_SESSION_ERR "."
  68 In general other return values may be returned. They should be treated
  69 as indicating failure.
  70
  71 .SH ERRORS
  72 May be translated to text with
  73 .BR pam_strerror "(3). "
  74
  75 .SH "CONFORMING TO"
  76 OSF-RFC 86.0, October 1995.
  77
  78 .SH BUGS
  79 .sp 2
  80 none known.
  81
  82 .SH "SEE ALSO"
  83
  84 .BR pam_start "(3), "
  85 .BR pam_authenticate "(3), "
  86 .BR pam_setcred "(3), "
  87 .BR pam_get_item "(3), "
  88 .BR pam_strerror "(3) "
  89 and
  90 .BR pam "(3)."
  91
  92 .br
  93 Also, see the three
  94 .BR Linux-PAM
  95 Guides, for
  96 .BR "System administrators" ", "
  97 .BR "module developers" ", "
  98 and
  99 .BR "application developers" ". "