--- name: "pam" section: "3" platform: "linux" package: "pam" version: "1.7.3-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/pam/3" --- # pam(3) Pluggable Authentication Modules Library ## NAME pam - Pluggable Authentication Modules Library ## SYNOPSIS ``` #include ``` ``` #include ``` ``` #include ``` ## DESCRIPTION **PAM** is a system of libraries that handle the authentication tasks of applications (services) on the system. The library provides a stable general interface (Application Programming Interface - API) that privilege granting programs (such as [**login**(1)](/login/1.md) and [**su**(1)](/su/1.md)) defer to to perform standard authentication tasks. ### Initialization and Cleanup The [**pam\_start**(3)](/pam_start/3.md) 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 [**pam\_end**(3)](/pam_end/3.md) function terminates the PAM transaction and is the last function an application 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. ### Authentication The [**pam\_authenticate**(3)](/pam_authenticate/3.md) function is used to authenticate the user. The user is required to provide an authentication token depending upon the authentication service, usually this is a password, but could also be a finger print. The [**pam\_setcred**(3)](/pam_setcred/3.md) function manages the user's credentials. ### Account Management The [**pam\_acct\_mgmt**(3)](/pam_acct_mgmt/3.md) 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 is typically called after the user has been authenticated. ### Password Management The [**pam\_chauthtok**(3)](/pam_chauthtok/3.md) function is used to change the authentication token for a given user on request or because the token has expired. ### Session Management The [**pam\_open\_session**(3)](/pam_open_session/3.md) 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)](/pam_close_session/3.md). ### Conversation The PAM library uses an application-defined callback to allow a direct communication between a loaded module and the application. This callback is specified by the *struct pam\_conv* passed to [**pam\_start**(3)](/pam_start/3.md) at the start of the transaction. See [**pam\_conv**(3)](/pam_conv/3.md) for details. ### Data Objects The [**pam\_set\_item**(3)](/pam_set_item/3.md) and [**pam\_get\_item**(3)](/pam_get_item/3.md) functions allow applications and PAM service modules to set and retrieve PAM information. The [**pam\_get\_user**(3)](/pam_get_user/3.md) function is the preferred method to obtain the username. The [**pam\_set\_data**(3)](/pam_set_data/3.md) and [**pam\_get\_data**(3)](/pam_get_data/3.md) function allows PAM service modules to set and retrieve free-form data from one invocation to another. ### Environment and Error Management The [**pam\_putenv**(3)](/pam_putenv/3.md), [**pam\_getenv**(3)](/pam_getenv/3.md) and [**pam\_getenvlist**(3)](/pam_getenvlist/3.md) functions are for maintaining a set of private environment variables. The [**pam\_strerror**(3)](/pam_strerror/3.md) function returns a pointer to a string describing the given PAM error code. ## RETURN VALUES The following return codes are known by PAM: PAM\_ABORT Critical error, immediate abort. PAM\_ACCT\_EXPIRED User account has expired. 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. PAM\_BUF\_ERR Memory buffer error. PAM\_CONV\_ERR Conversation failure. 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. PAM\_MAXTRIES Have exhausted maximum number of retries for service. PAM\_MODULE\_UNKNOWN Module is unknown. 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. PAM\_SERVICE\_ERR Error in service module. PAM\_SESSION\_ERR Cannot make/remove an entry for the specified session. PAM\_SUCCESS Success. 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. ## SEE ALSO [**pam\_acct\_mgmt**(3)](/pam_acct_mgmt/3.md), [**pam\_authenticate**(3)](/pam_authenticate/3.md), [**pam\_chauthtok**(3)](/pam_chauthtok/3.md), [**pam\_close\_session**(3)](/pam_close_session/3.md), [**pam\_conv**(3)](/pam_conv/3.md), [**pam\_end**(3)](/pam_end/3.md), [**pam\_get\_data**(3)](/pam_get_data/3.md), [**pam\_getenv**(3)](/pam_getenv/3.md), [**pam\_getenvlist**(3)](/pam_getenvlist/3.md), [**pam\_get\_item**(3)](/pam_get_item/3.md), [**pam\_get\_user**(3)](/pam_get_user/3.md), [**pam\_open\_session**(3)](/pam_open_session/3.md), [**pam\_putenv**(3)](/pam_putenv/3.md), [**pam\_set\_data**(3)](/pam_set_data/3.md), [**pam\_set\_item**(3)](/pam_set_item/3.md), [**pam\_setcred**(3)](/pam_setcred/3.md), [**pam\_start**(3)](/pam_start/3.md), [**pam\_strerror**(3)](/pam_strerror/3.md) ## NOTES The *libpam* interfaces are only thread-safe if each thread within the multithreaded application uses its own PAM handle.