path: root/doc/man/pam_start.3
diff options
Diffstat (limited to 'doc/man/pam_start.3')
1 files changed, 67 insertions, 93 deletions
diff --git a/doc/man/pam_start.3 b/doc/man/pam_start.3
index 9c11fd73..ac6454b7 100644
--- a/doc/man/pam_start.3
+++ b/doc/man/pam_start.3
@@ -1,98 +1,72 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <>
-.TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual"
-pam_start, pam_end \- activating Linux-PAM
-.B #include <security/pam_appl.h>
-.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");"
-.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");"
-.sp 2
+.\" ** You probably do not want to edit this file directly **
+.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
+.\" Instead of manually editing it, you probably should edit the DocBook XML
+.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
+.TH "PAM_START" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.\" disable justification (adjust text to left margin only) l
+pam_start \- initialization of PAM transaction
+\fB#include <security/pam_appl.h>\fR
+.HP 14
+\fBint\ \fBpam_start\fR\fR\fB(\fR\fBconst\ char\ *\fR\fB\fIservice_name\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fIuser\fR\fR\fB, \fR\fBconst\ struct\ pam_conv\ *\fR\fB\fIpam_conversation\fR\fR\fB, \fR\fBpam_handle_t\ **\fR\fB\fIpamh\fR\fR\fB);\fR
+function creates the PAM context and initiates the PAM transaction. It is the first of the PAM functions that needs to be called by an application.
+argument specifies the name of the service to apply and will be stored as PAM_SERVICE item in the new context. The policy for the service will be read from the file
+or, if that file does not exist, from
+argument can specify the name of the target user and will be stored as PAM_USER item. If the argument is NULL, the module has to ask for this item if necessary.
+argument points to a
+\fIstruct pam_conv\fR
+describing the conversation function to use. An application must provide this for direct communication between a loaded module and the application.
+Following a successful return (PAM_SUCCESS) the contents of
+is a handle that contains the PAM context for successive calls to the PAM functions. In an error case is the content of
+is a blind structure and the application should not attempt to probe it directly for information. Instead the PAM library provides the functions
+\fBpam_get_item\fR(3). The PAM handle cannot be used for mulitiple authentications at the same time as long as
+was not called on it before.
-.B pam_start
-Initialize the
-.I Linux-PAM
-library. Identifying the application with a particular
-.IR service
-name. The
-.IR user "name"
-can take the value
-.IR NULL ", "
-if not known at the time the interface is initialized. The
-conversation structure is passed to the library via the
-.IR conv
-argument. (For a complete description of this and other structures
-the reader is directed to the more verbose
-.IR Linux-PAM
-application developers' guide). Upon successful initialization, an
-opaque pointer-handle for future access to the library is returned
-through the contents of the
-.IR pamh_p
+General failure.
-.B pam_end
-Terminate the
-.B Linux-PAM
-library. The service application associated with the
-.IR pamh
-handle, is terminated. The argument,
-.IR pam_status ", "
-passes the value most recently returned to the application from the
-library; it indicates the manner in which the library should be
-shutdown. Besides carrying a return value, this argument may be
-logically OR'd with
-to indicate that the module should not treat the call too
-seriously. It is generally used to indicate that the current closing
-of the library is in a
-.IR fork "(2)ed"
-process, and that the parent will take care of cleaning up things that
-exist outside of the current process space (files etc.).
+Memory buffer error.
-.B pam_start
+Transaction was successful created.
-.B pam_end
-On success,
-is returned
-May be translated to text with
-.BR pam_strerror "(3). "
-DCE-RFC 86.0, October 1995.
-Note, the
-flag is pending acceptance with the DCE (as of 1996/12/4).
-.sp 2
-None known.
+System error, for example a NULL pointer was submitted instead of a pointer to data.
-.BR fork "(2), "
-.BR pam_authenticate "(3), "
-.BR pam_acct_mgmt "(3), "
-.BR pam_open_session "(3), "
-.BR pam_chauthtok "(3)."
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-.BR "application developers" ". "