PAM(3)

✨ PAM(3) — the Linux-PAM girlies' guide ✨

ok so bestie, welcome to PAM, aka Pluggable Authentication Modules Library — the friend group of libraries that handles all the authentication tasks for applications (services) on the system. literally the backstage crew of your whole login experience 💅

It gives you a stable general interface (Application Programming Interface — API, you know her) that privilege-granting programs (think login(1) and su(1), the classics) defer to when they need to do standard authentication tasks. no cap, they just hand the whole vibe check over to PAM 🫶

---

🌸 SYNOPSIS 🌸

#include <security/pam_appl.h>

#include <security/pam_modules.h>

#include <security/pam_ext.h>

three headers, that's it, that's the whole entry fee 💖

---

🦋 DESCRIPTION 🦋

🎀 Initialization and Cleanup 🎀

The pam_start(3) function creates the PAM context and kicks off the PAM transaction. it's the first of the PAM functions an app needs to call — like, the opening act, the main character entrance, periodt.

The transaction state lives entirely inside the structure identified by this handle, so yes bestie, you can absolutely have multiple transactions in parallel, slay. BUT — and this is the important part 😭 — you can NOT reuse the same handle for different transactions. a new one is needed for every new context. one handle, one transaction, that's the rule 🙈

The pam_end(3) function terminates the PAM transaction and is the last function an app should call in the PAM context. Upon return, the handle pamh is no longer valid and all memory associated with it will be invalid. it can be called at any time to terminate a PAM transaction — anytime, she's flexible like that ✨

🔥 Authentication 🔥

The pam_authenticate(3) function is used to authenticate the user. the user is required to provide an authentication token, which depends on the authentication service — usually this is a password, but it could also be a finger print 👑

The pam_setcred(3) function manages the user's credentials. that's it, that's the job, and she does it well 💜

🧚 Account Management 🧚

The pam_acct_mgmt(3) function is used to determine if the user's account is valid. it checks for authentication token and account expiration and verifies access restrictions. it's typically called after the user has been authenticated — like the vibe check that comes AFTER the password check 💅

🍓 Password Management 🍓

The pam_chauthtok(3) function is used to change the authentication token for a given user — either on request or because the token has expired. expired token? we don't know her, we're changing it 😌

🌈 Session Management 🌈

The pam_open_session(3) function sets up a user session for a previously successfully authenticated user. the session should later be terminated with a call to pam_close_session(3) — open then close, balance, harmony, the way nature intended 🦋

💫 Conversation 💫

The PAM library uses an application-defined callback to allow direct communication between a loaded module and the application. this callback is specified by the struct pam_conv passed to pam_start(3) at the start of the transaction. see pam_conv(3) for details — she has her own whole page, iykyk 🌸

⭐ Data Objects ⭐

The pam_set_item(3) and pam_get_item(3) functions allow applications and PAM service modules to set and retrieve PAM information. setting and getting, the original duo 💖

The pam_get_user(3) function is the preferred method to obtain the username. not me telling you there are other ways — no, just use this one, it's iconic 👑

The pam_set_data(3) and pam_get_data(3) functions allow PAM service modules to set and retrieve free-form data from one invocation to another. free-form, unbothered, living her best life 🎀

🫶 Environment and Error Management 🫶

The pam_putenv(3), pam_getenv(3) and pam_getenvlist(3) functions are for maintaining a set of private environment variables. private, exclusive, invite-only 💅

The pam_strerror(3) function returns a pointer to a string describing the given PAM error code. so when something goes wrong (and bestie, something always goes wrong), this is who you ask 😭

---

💀 RETURN VALUES 💀

ok these are the return codes PAM knows about. there are a LOT of them, so buckle up, we're going through every single one, no skipping, no summarizing, that's not the vibe we're on today 🫡

• PAM_ABORT — Critical error, immediate abort. like, drop everything and run 😭
• PAM_ACCT_EXPIRED — User account has expired. bye bestie 💀
• PAM_AUTHINFO_UNAVAIL — Authentication service cannot retrieve authentication info.
• PAM_AUTHTOK_DISABLE_AGING — Authentication token aging disabled.
• PAM_AUTHTOK_ERR — Authentication token manipulation error.
• PAM_AUTHTOK_EXPIRED — Authentication token expired.
• PAM_AUTHTOK_LOCK_BUSY — Authentication token lock busy.
• PAM_AUTHTOK_RECOVERY_ERR — Authentication information cannot be recovered.
• PAM_AUTH_ERR — Authentication failure. the classic, the icon, the one everyone fears 🙈
• PAM_BUF_ERR — Memory buffer error.
• PAM_CONV_ERR — Conversation failure. the conversation did NOT go well ✨
• PAM_CRED_ERR — Failure setting user credentials.
• PAM_CRED_EXPIRED — User credentials expired.
• PAM_CRED_INSUFFICIENT — Insufficient credentials to access authentication data.
• PAM_CRED_UNAVAIL — Authentication service cannot retrieve user credentials.
• PAM_IGNORE — The return value should be ignored by PAM dispatch. literally just look away 💅
• PAM_MAXTRIES — Have exhausted maximum number of retries for service. you tried, you tried again, that's enough 🫶
• PAM_MODULE_UNKNOWN — Module is unknown. who is she? we don't know her 🌸
• PAM_NEW_AUTHTOK_REQD — Authentication token is no longer valid; new one required.
• PAM_NO_MODULE_DATA — No module specific data is present.
• PAM_OPEN_ERR — Failed to load module.
• PAM_PERM_DENIED — Permission denied. nope, not for you bestie 🚫
• PAM_SERVICE_ERR — Error in service module.
• PAM_SESSION_ERR — Cannot make/remove an entry for the specified session.
• PAM_SUCCESS — Success. 🎉✨👑 THE return code. this is the one you're manifesting.
• PAM_SYMBOL_ERR — Symbol not found.
• PAM_SYSTEM_ERR — System error.
• PAM_TRY_AGAIN — Failed preliminary check by password service.
• PAM_USER_UNKNOWN — User not known to the underlying authentication module. stranger danger 🍓

---

🧚 SEE ALSO 🧚

the whole friend group, all tagged, all linked, all iconic 💜

pam_acct_mgmt(3), pam_authenticate(3), pam_chauthtok(3), pam_close_session(3), pam_conv(3), pam_end(3), pam_get_data(3), pam_getenv(3), pam_getenvlist(3), pam_get_item(3), pam_get_user(3), pam_open_session(3), pam_putenv(3), pam_set_data(3), pam_set_item(3), pam_setcred(3), pam_start(3), pam_strerror(3)

---

⚠️ NOTES ⚠️

The libpam interfaces are only thread-safe if each thread within the multithreaded application uses its own PAM handle. read that again. one handle per thread. no sharing, no borrowing, no "just this once" 😤

---

and that's the whole page bestie, you ate 💅✨

this has been Linux-PAM, dated 07/08/2026, the PAM(3) manual page — go forth and authenticate responsibly 🫶🎀