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

NAME
     pam_start, pam_start_confdir - 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_han-
		   dle_t **pamh);

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

DESCRIPTION
     The pam_start function creates the PAM context and initiates the PAM trans-
     action. It is the first of the PAM functions that needs to be called by  an
     application.  The transaction state is contained entirely within the struc-
     ture identified by this handle, so it is possible to have multiple transac-
     tions in parallel. But it is not possible to use the same handle  for  dif-
     ferent 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  han-
     dle  that	contains  the  PAM context for successive calls to the PAM func-
     tions. In an error case is the content of pamh undefined.

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

     The pam_start_confdir function behaves like the pam_start function	 but  it
     also allows setting confdir argument with a path to a directory to override
     the  default  (/etc/pam.d) path for service policy files. If the confdir is
     NULL, the function works exactly the same as pam_start.

RETURN VALUES
     PAM_ABORT
	 General failure.

     PAM_BUF_ERR
	 Memory buffer error.

     PAM_SUCCESS
	 Transaction was successfully started.

     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			   04/09/2024			    PAM_START(3)