pam_start(3) — Linux manual page

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_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.

SEE ALSO

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

COLOPHON

       This page is part of the linux-pam (Pluggable Authentication
       Modules for Linux) project.  Information about the project can be
       found at ⟨http://www.linux-pam.org/⟩.  If you have a bug report
       for this manual page, see ⟨//www.linux-pam.org/⟩.  This page was
       obtained from the project's upstream Git repository
       ⟨https://github.com/linux-pam/linux-pam.git⟩ on 2023-12-22.  (At
       that time, the date of the most recent commit that was found in
       the repository was 2023-12-18.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Linux-PAM Manual               12/22/2023                   PAM_START(3)

Pages that refer to this page: pam(3), pam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3), pam_conv(3), pam_end(3), pam_fail_delay(3), pam_getenv(3), pam_getenvlist(3), pam_get_user(3), pam_putenv(3), pam_xauth_data(3), pam.conf(5)

---