PAM_START(3)

🎀 NAME 🎀

okay so bestie, welcome to PAM_START(3) — this is the Linux-PAM page for pam_start, pam_start_confdir, and it's literally all about initialization of PAM transaction ✨ like the setup era before the main character plot begins 💅

---

🌸 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 💖

so pam_start creates the PAM context and initiates the PAM transaction — it's the first of the PAM functions that needs to be called by an application, no cap 👑 The transaction state is contained entirely within the structure identified by this handle, which means you can have multiple transactions in parallel, iconic. But bestie, listen: it is not possible to use the same handle for different transactions — a new one is needed for every new context, periodt 🫶

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. iykyk, that's just how the policy girlies work 💅

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 — so don't stress, it's giving "we'll figure it out" energy 😌

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 — it's literally the group chat between them 💬

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 🙈 so like, don't go poking at it.

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) — use those, bestie, that's the whole vibe 🌈 The PAM handle cannot be used for multiple authentications at the same time as long as pam_end was not called on it before. like, one main character arc at a time, okay? 💀

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. slay, flexible queen ✨

---

🔥 RETURN VALUES 🔥

• PAM_ABORT — General failure. it's giving "everything is on fire" 😭
• PAM_BUF_ERR — Memory buffer error. the buffer said nah 💀
• PAM_SUCCESS — Transaction was successfully started. ate and left no crumbs 👑
• PAM_SYSTEM_ERR — System error, for example a NULL pointer was submitted instead of a pointer to data. bestie, check your pointers fr fr 🙈

---

🦋 SEE ALSO 🦋

• pam_get_data(3)
• pam_set_data(3)
• pam_end(3)
• pam_strerror(3)

---

this whole page is from Linux-PAM, dated 07/08/2026, and it's literally titled PAM_START(3) — okay love you, go start that transaction responsibly 💖✨🎀