<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id='pam_set_data'>
<refmeta>
<refentrytitle>pam_set_data</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
</refmeta>
<refnamediv id='pam_set_data-name'>
<refname>pam_set_data</refname>
<refpurpose>
set module internal data
</refpurpose>
</refnamediv>
<!-- body begins here -->
<refsynopsisdiv>
<funcsynopsis id="pam_set_data-synopsis">
<funcsynopsisinfo>#include <security/pam_modules.h></funcsynopsisinfo>
<funcprototype>
<funcdef>int <function>pam_set_data</function></funcdef>
<paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
<paramdef>const char *<parameter>module_data_name</parameter></paramdef>
<paramdef>void *<parameter>data</parameter></paramdef>
<paramdef>void <parameter>(*cleanup)(pam_handle_t *pamh, void *data, int error_status)</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 id="pam_set_data-description">
<title>DESCRIPTION</title>
<para>
The <function>pam_set_data</function> function associates a pointer
to an object with the (hopefully) unique string
<emphasis>module_data_name</emphasis> in the PAM context specified
by the <emphasis>pamh</emphasis> argument.
</para>
<para>
PAM modules may be dynamically loadable objects. In general such files
should not contain <emphasis>static</emphasis> variables. This function
and its counterpart
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
provide a mechanism for a module to associate some data with
the handle <emphasis>pamh</emphasis>. Typically a module will call the
<function>pam_set_data</function> function to register some data
under a (hopefully) unique <emphasis>module_data_name</emphasis>.
The data is available for use by other modules too but
<emphasis>not</emphasis> by an application. Since this functions
stores only a pointer to the <emphasis>data</emphasis>, the module
should not modify or free the content of it.
</para>
<para>
The function <function>cleanup()</function> is associated with the
<emphasis>data</emphasis> and, if non-NULL, it is called when this
data is over-written or following a call to
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
<para>
The <emphasis>error_status</emphasis> 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
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
is called by the module, the <emphasis>error_status</emphasis>
carries the return value of the
<citerefentry>
<refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
or other <emphasis>libpam</emphasis> function as appropriate. Based
on this value the Kerberos module may choose to delete the ticket file
(<emphasis>authentication failure</emphasis>) or leave it in place.
</para>
<para>
The <emphasis>error_status</emphasis> may have been logically
OR'd with either of the following two values:
</para>
<variablelist>
<varlistentry>
<term>PAM_DATA_REPLACE</term>
<listitem>
<para>
When a data item is being replaced (through a second call to
<function>pam_set_data</function>) this mask is used.
Otherwise, the call is assumed to be from
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_DATA_SILENT</term>
<listitem>
<para>
Which indicates that the process would prefer to perform the
<function>cleanup()</function> quietly. That is, discourages
logging/messages to the user.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="pam_set_data-return_values">
<title>RETURN VALUES</title>
<variablelist>
<varlistentry>
<term>PAM_BUF_ERR</term>
<listitem>
<para>
Memory buffer error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SUCCESS</term>
<listitem>
<para>
Data was successful stored.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PAM_SYSTEM_ERR</term>
<listitem>
<para>
A NULL pointer was submitted as PAM handle or the
function was called by an application.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id="pam_set_data-see_also">
<title>SEE ALSO</title>
<para>
<citerefentry>
<refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>,
<citerefentry>
<refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>