# pam_start

## 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_handle_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 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 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.
    


* * *