--- name: "pam_set_item" 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_set_item" --- # pam\_set\_item(3) set and update PAM information ## NAME pam\_set\_item - set and update PAM information ## SYNOPSIS ``` #include ``` **int pam\_set\_item(pam\_handle\_t \****pamh***, int** *item\_type***, const void \****item***);** ## DESCRIPTION The **pam\_set\_item** function allows applications and PAM service modules to access and to update PAM information of *item\_type*. For this a copy of the object pointed to by the *item* argument is created. The following *item\_type*s are supported: PAM\_SERVICE The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program). PAM\_USER The username of the entity under whose identity service will be given. That is, following authentication, *PAM\_USER* identifies the local entity that gets to use the service. Note, this value can be mapped from something (eg., "anonymous") to something else (eg. "guest119") by any module in the PAM stack. As such an application should consult the value of *PAM\_USER* after each call to a PAM function. PAM\_USER\_PROMPT The string used when prompting for a user's name. The default value for this string is a localized version of "login: ". PAM\_TTY The terminal name prefixed by /dev/ for device files. In the past, graphical X-based applications used to store the *$DISPLAY* variable here, but with the introduction of *PAM\_XDISPLAY* this usage is deprecated. PAM\_RUSER The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user. Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator. *PAM\_RUSER@PAM\_RHOST* should always identify the requesting user. In some cases, *PAM\_RUSER* may be NULL. In such situations, it is unclear who the requesting entity is. PAM\_RHOST The requesting hostname (the hostname of the machine from which the *PAM\_RUSER* entity is requesting service). That is *PAM\_RUSER@PAM\_RHOST* does identify the requesting user. In some applications, *PAM\_RHOST* may be NULL. In such situations, it is unclear where the authentication request is originating from. PAM\_AUTHTOK The authentication token (often a password). This token should be ignored by all module functions besides [**pam\_sm\_authenticate**(3)](/pam_sm_authenticate/3.md) and [**pam\_sm\_chauthtok**(3)](/pam_sm_chauthtok/3.md). In the former function it is used to pass the most recent authentication token from one stacked module to another. In the latter function the token is used for another purpose. It contains the currently active authentication token. PAM\_OLDAUTHTOK The old authentication token. This token should be ignored by all module functions except [**pam\_sm\_chauthtok**(3)](/pam_sm_chauthtok/3.md). PAM\_CONV The pam\_conv structure. See [**pam\_conv**(3)](/pam_conv/3.md). The following additional items are specific to Linux-PAM and should not be used in portable applications: PAM\_FAIL\_DELAY A function pointer to redirect centrally managed failure delays. See [**pam\_fail\_delay**(3)](/pam_fail_delay/3.md). PAM\_XDISPLAY The name of the X display. For graphical, X-based applications the value for this item should be the *$DISPLAY* variable. This value may be used independently of *PAM\_TTY* for passing the name of the display. PAM\_XAUTHDATA A pointer to a structure containing the X authentication data required to make a connection to the display specified by *PAM\_XDISPLAY*, if such information is necessary. See [**pam\_xauth\_data**(3)](/pam_xauth_data/3.md). PAM\_AUTHTOK\_TYPE The default action is for the module to use the following prompts when requesting passwords: "New UNIX password: " and "Retype UNIX password: ". The example word *UNIX* can be replaced with this item, by default it is empty. This item is used by [**pam\_get\_authtok**(3)](/pam_get_authtok/3.md). For all *item\_type*s, other than PAM\_CONV and PAM\_FAIL\_DELAY, *item* is a pointer to a \ terminated character string. In the case of PAM\_CONV, *item* points to an initialized *pam\_conv* structure. In the case of PAM\_FAIL\_DELAY, *item* is a function pointer: **void (\*delay\_fn)(int retval, unsigned usec\_delay, void \*appdata\_ptr)** Both, PAM\_AUTHTOK and PAM\_OLDAUTHTOK, will be reset before returning to the application. Which means an application is not able to access the authentication tokens. ## RETURN VALUES PAM\_BAD\_ITEM The application attempted to set an undefined or inaccessible item. PAM\_BUF\_ERR Memory buffer error. PAM\_SUCCESS Data was successfully updated. PAM\_SYSTEM\_ERR The *pam\_handle\_t* passed as first argument was invalid. ## SEE ALSO [**pam\_get\_item**(3)](/pam_get_item/3.md), [**pam\_strerror**(3)](/pam_strerror/3.md)