contrib/libpam/doc/man/pam_start.3

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