pam_start(3)

NAME
     pam_start, pam_end - authentication transaction routines for PAM


SYNOPSIS
     cc [ flag ... ] file ...  -lpam [ library ... ]

     #include <security/pam_appl.h>

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

     int pam_end(pam_handle_t *pamh, int status);


DESCRIPTION
     pam_start()  is  called  to   initiate   an   authentication   transaction.
     pam_start()  takes  as  arguments the name of the current service, service,
     the name of the user to be authenticated, user, the address of the  conver-
     sation  structure,  pam_conv,  and the address of a variable to be assigned
     the authentication handle, pamh.  Upon successful completion, pamh will re-
     fer to a PAM handle for use with subsequent calls to the authentication li-
     brary.

     The pam_conv structure, pam_conv, contains the address of the  conversation
     function  provided  by  the application.  The underlying service module in-
     vokes this function to output information to and retrieve  input  from  the
     user.  The pam_conv structure has the following entries:

            struct pam_conv {
                    int     (*conv)();       /* Conversation function */
                    void    *appdata_ptr;    /* Application data */
            };

          where

                    int conv(int num_msg,
                            const struct pam_message **msg, struct pam_response **resp,
                            void *appdata_ptr);


     The  function  conv() is called by a service module to hold a PAM conversa-
     tion with the application or user.  For window applications,  the  applica-
     tion can create a new pop-up window to be used by the interaction.

     The  parameter  num_msg is the number of messages associated with the call.
     The parameter msg is a pointer  to  an  array  of  length  num_msg  of  the
     pam_message structure.

     The  structure  pam_message  is  used to pass prompt, error message, or any
     text information from the authentication  service  to  the  application  or
     user.   The memory used by pam_message should be allocated and freed by the
     PAM authentication service.  The structure pam_response is used by the  au-
     thentication  service  to get the user's response back from the application
     or user.  The storage used by pam_response should be allocated by  the  ap-
     plication  and  freed  by  the PAM authentication service.  The pam_message
     structure has the following entries:

            struct pam_message{
                    int     msg_style;
                    char    *msg;
            };

     The pam_response structure has the following entries:

            struct pam_response{
                    char    *resp;
                    int     resp_retcode;    /* currently not used, should be set to 0 */
            };

     The message style, msg_style, can be set to one of the following values:

            PAM_PROMPT_ECHO_OFF       prompt user, disabling echoing of response

            PAM_PROMPT_ECHO_ON        prompt user, enabling echoing of response

            PAM_ERROR_MSG             print error message

            PAM_TEXT_INFO             print general text information

     appdata_ptr is an application data pointer which is passed by the  applica-
     tion  to  the  PAM  service  modules.   Since  the PAM modules pass it back
     through the conversation function, the applications can use this pointer to
     point to any application-specific data.

     pam_end() is called to terminate the authentication transaction  identified
     by  pamh  and to free any storage area allocated by the authentication mod-
     ule.  The argument, status, is passed  to  the  cleanup()  function  stored
     within  the pam handle, and is used to determine what module specific state
     must be purged.  A cleanup function is attached to the handle by the under-
     lying PAM modules through a call to pam_set_item(3) to free module specific
     data.


RETURN VALUES
     Refer to pam(3) for information on error related return values.

SEE ALSO
     pam_authenticate(3),   pam_set_item(3),   pam_acct_mgmt(3),   pam_open_ses-
     sion(3), pam_setcred(3), pam_chauthtok(3), pam_strerror(3), pam(3)