pam_set_data (3)
Leading comments
Title: pam_set_data
Author: [FIXME: author] [see http://docbook.sf.net/el/author]
Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
Date: 09/19/2013
Manual: Linux-PAM Manual
Source: Linux-PAM Manual
Language: English
NAME
pam_set_data - set module internal dataSYNOPSIS
#include <security/pam_modules.h>
- int pam_set_data(pam_handle_t *pamh, const char *module_data_name, void *data, void (*cleanup)(pam_handle_t *pamh, void *data, int error_status));
DESCRIPTION
PAM modules may be dynamically loadable objects. In general such files should not contain static variables. This function and its counterpart pam_get_data(3), provide a mechanism for a module to associate some data with the handle pamh. Typically a module will call the pam_set_data function to register some data under a (hopefully) unique module_data_name. The data is available for use by other modules too but not by an application. Since this functions stores only a pointer to the data, the module should not modify or free the content of it.
The function cleanup() is associated with the data and, if non-NULL, it is called when this data is over-written or following a call to pam_end(3).
The error_status argument is used to indicate to the module the sort of action it is to take in cleaning this data item. As an example, Kerberos creates a ticket file during the authentication phase, this file might be associated with a data item. When pam_end(3) is called by the module, the error_status carries the return value of the pam_authenticate(3) or other libpam function as appropriate. Based on this value the Kerberos module may choose to delete the ticket file (authentication failure) or leave it in place.
The error_status may have been logically OR'd with either of the following two values:
PAM_DATA_REPLACE
- When a data item is being replaced (through a second call to pam_set_data) this mask is used. Otherwise, the call is assumed to be from pam_end(3).
PAM_DATA_SILENT
- Which indicates that the process would prefer to perform the cleanup() quietly. That is, discourages logging/messages to the user.
RETURN VALUES
PAM_BUF_ERR
- Memory buffer error.
PAM_SUCCESS
- Data was successful stored.
PAM_SYSTEM_ERR
- A NULL pointer was submitted as PAM handle or the function was called by an application.