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

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\" $Id$
   3 .\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
   4 .TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual"
   5 .SH NAME
   6
   7 pam_start, pam_end \- activating Linux-PAM
   8
   9 .SH SYNOPSIS
  10 .B #include <security/pam_appl.h>
  11 .sp
  12 .BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");"
  13 .sp
  14 .BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");"
  15 .sp 2
  16 .SH DESCRIPTION
  17 .TP
  18 .B pam_start
  19 Initialize the
  20 .I Linux-PAM
  21 library.  Identifying the application with a particular
  22 .IR service
  23 name.  The
  24 .IR user "name"
  25 can take the value
  26 .IR NULL ", "
  27 if not known at the time the interface is initialized.  The
  28 conversation structure is passed to the library via the
  29 .IR conv
  30 argument.  (For a complete description of this and other structures
  31 the reader is directed to the more verbose
  32 .IR Linux-PAM
  33 application developers' guide).  Upon successful initialization, an
  34 opaque pointer-handle for future access to the library is returned
  35 through the contents of the
  36 .IR pamh_p
  37 pointer.
  38
  39 .TP
  40 .B pam_end
  41 Terminate the
  42 .B Linux-PAM
  43 library.  The service application associated with the
  44 .IR pamh
  45 handle, is terminated.  The argument,
  46 .IR pam_status ", "
  47 passes the value most recently returned to the application from the
  48 library; it indicates the manner in which the library should be
  49 shutdown.  Besides carrying a return value, this argument may be
  50 logically OR'd with
  51 .IR PAM_DATA_SILENT
  52 to indicate that the module should not treat the call too
  53 seriously. It is generally used to indicate that the current closing
  54 of the library is in a
  55 .IR fork "(2)ed"
  56 process, and that the parent will take care of cleaning up things that
  57 exist outside of the current process space (files etc.).
  58
  59 .SH "RETURN VALUE"
  60 .TP
  61 .B pam_start
  62 .TP
  63 .B pam_end
  64 On success,
  65 .BR PAM_SUCCESS
  66 is returned
  67
  68 .SH ERRORS
  69 May be translated to text with
  70 .BR pam_strerror "(3). "
  71
  72 .SH "CONFORMING TO"
  73 DCE-RFC 86.0, October 1995.
  74 .sp
  75 Note, the
  76 .BR PAM_DATA_SILENT
  77 flag is pending acceptance with the DCE (as of 1996/12/4).
  78
  79 .SH BUGS
  80 .sp 2
  81 None known.
  82
  83 .SH "SEE ALSO"
  84
  85 .BR fork "(2), "
  86 .BR pam_authenticate "(3), "
  87 .BR pam_acct_mgmt "(3), "
  88 .BR pam_open_session "(3), "
  89 and
  90 .BR pam_chauthtok "(3)."
  91
  92 Also, see the three
  93 .BR Linux-PAM
  94 Guides, for
  95 .BR "System administrators" ", "
  96 .BR "module developers" ", "
  97 and
  98 .BR "application developers" ". "