1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5 <refentry id='pam_set_data'>
8 <refentrytitle>pam_set_data</refentrytitle>
9 <manvolnum>3</manvolnum>
10 <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
13 <refnamediv id='pam_set_data-name'>
14 <refname>pam_set_data</refname>
16 set module internal data
21 <!-- body begins here -->
25 <funcsynopsis id="pam_set_data-synopsis">
26 <funcsynopsisinfo>#include <security/pam_modules.h></funcsynopsisinfo>
28 <funcdef>int <function>pam_set_data</function></funcdef>
29 <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
30 <paramdef>const char *<parameter>module_data_name</parameter></paramdef>
31 <paramdef>void *<parameter>data</parameter></paramdef>
32 <paramdef>void <parameter>(*cleanup)(pam_handle_t *pamh, void *data, int error_status)</parameter></paramdef>
39 <refsect1 id="pam_set_data-description">
40 <title>DESCRIPTION</title>
42 The <function>pam_set_data</function> function associates a pointer
43 to an object with the (hopefully) unique string
44 <emphasis>module_data_name</emphasis> in the PAM context specified
45 by the <emphasis>pamh</emphasis> argument.
49 PAM modules may be dynamically loadable objects. In general such files
50 should not contain <emphasis>static</emphasis> variables. This function
53 <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
55 provide a mechanism for a module to associate some data with
56 the handle <emphasis>pamh</emphasis>. Typically a module will call the
57 <function>pam_set_data</function> function to register some data
58 under a (hopefully) unique <emphasis>module_data_name</emphasis>.
59 The data is available for use by other modules too but
60 <emphasis>not</emphasis> by an application. Since this functions
61 stores only a pointer to the <emphasis>data</emphasis>, the module
62 should not modify or free the content of it.
66 The function <function>cleanup()</function> is associated with the
67 <emphasis>data</emphasis> and, if non-NULL, it is called when this
68 data is over-written or following a call to
70 <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
75 The <emphasis>error_status</emphasis> argument is used to indicate
76 to the module the sort of action it is to take in cleaning this data
77 item. As an example, Kerberos creates a ticket file during the
78 authentication phase, this file might be associated with a data item.
81 <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
83 is called by the module, the <emphasis>error_status</emphasis>
84 carries the return value of the
86 <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
88 or other <emphasis>libpam</emphasis> function as appropriate. Based
89 on this value the Kerberos module may choose to delete the ticket file
90 (<emphasis>authentication failure</emphasis>) or leave it in place.
94 The <emphasis>error_status</emphasis> may have been logically
95 OR'd with either of the following two values:
100 <term>PAM_DATA_REPLACE</term>
103 When a data item is being replaced (through a second call to
104 <function>pam_set_data</function>) this mask is used.
105 Otherwise, the call is assumed to be from
107 <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
114 <term>PAM_DATA_SILENT</term>
117 Which indicates that the process would prefer to perform the
118 <function>cleanup()</function> quietly. That is, discourages
119 logging/messages to the user.
126 <refsect1 id="pam_set_data-return_values">
127 <title>RETURN VALUES</title>
130 <term>PAM_BUF_ERR</term>
138 <term>PAM_SUCCESS</term>
141 Data was successful stored.
146 <term>PAM_SYSTEM_ERR</term>
149 A NULL pointer was submitted as PAM handle or the
150 function was called by an application.
157 <refsect1 id="pam_set_data-see_also">
158 <title>SEE ALSO</title>
161 <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
164 <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
167 <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>