- 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));
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:
- 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).
- Which indicates that the process would prefer to perform the cleanup() quietly. That is, discourages logging/messages to the user.
- Memory buffer error.
- Data was successful stored.
- A NULL pointer was submitted as PAM handle or the function was called by an application.