pam_start(3) [redhat man page]

PAM_START(3)						  Application Programmers' Manual					      PAM_START(3)

NAME

       pam_start, pam_end - activating Linux-PAM

SYNOPSIS

       #include <security/pam_appl.h>

       int pam_start(const char *service, const char *user, const struct pam_conv *conv, pam_handle_t **pamh_p);

       int pam_end(pam_handle_t *pamh, int pam_status);

DESCRIPTION

       pam_start
	      Initialize  the  Linux-PAM  library.   Identifying  the application with a particular service name.  The username can take the value
	      NULL, if not known at the time the interface is initialized.  The conversation structure is passed to the library via the conv argu-
	      ment.   (For  a  complete  description of this and other structures the reader is directed to the more verbose 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 pamh_p pointer.

       pam_end
	      Terminate the Linux-PAM library.	The service application associated with the pamh handle, is terminated.  The argument, 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 PAM_DATA_SILENT 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  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.).

RETURN VALUE

       pam_start

       pam_end
	      On success, PAM_SUCCESS is returned

ERRORS

       May be translated to text with pam_strerror(3).

CONFORMING TO

       DCE-RFC 86.0, October 1995.

       Note, the PAM_DATA_SILENT flag is pending acceptance with the DCE (as of 1996/12/4).

BUGS

       None known.

SEE ALSO

       fork(2), pam_authenticate(3), pam_acct_mgmt(3), pam_open_session(3), and pam_chauthtok(3).

       Also, see the three Linux-PAM Guides, for System administrators, module developers, and application developers.

Linux-PAM 0.56							    1997 Feb 15 						      PAM_START(3)

PAM_START(3)							 Linux-PAM Manual						      PAM_START(3)

NAME

       pam_start - initialization of PAM transaction

SYNOPSIS

       #include <security/pam_appl.h>

       int pam_start(const char *service_name, const char *user, const struct pam_conv *pam_conversation, pam_handle_t **pamh);

DESCRIPTION

       The pam_start 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. The transaction state is contained entirely within the structure identified by this handle, so it is possible to
       have multiple transactions in parallel. But it is not possible to use the same handle for different transactions, a new one is needed for
       every new context.

       The service_name 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 /etc/pam.d/service_name or, if that file does not exist, from /etc/pam.conf.

       The user 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.

       The pam_conversation argument points to a struct pam_conv 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 pamh is a handle that contains the PAM context for successive calls to the PAM
       functions. In an error case is the content of pamh undefined.

       The pam_handle_t is a blind structure and the application should not attempt to probe it directly for information. Instead the PAM library
       provides the functions pam_set_item(3) and pam_get_item(3). The PAM handle cannot be used for mulitiple authentications at the same time as
       long as pam_end was not called on it before.

RETURN VALUES

       PAM_ABORT
	   General failure.

       PAM_BUF_ERR
	   Memory buffer error.

       PAM_SUCCESS
	   Transaction was successful created.

       PAM_SYSTEM_ERR
	   System error, for example a NULL pointer was submitted instead of a pointer to data.

SEE ALSO

       pam_get_data(3), pam_set_data(3), pam_end(3), pam_strerror(3)

Linux-PAM Manual						    09/19/2013							      PAM_START(3)