granicus.if.org Git - linux-pam/blob - doc/man/pam_set_item.3.xml

   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"
   4 [
   5 <!--
   6 <!ENTITY accessconf SYSTEM "pam_item_types.inc.xml">
   7 -->
   8 ]>
   9
  10 <refentry id='pam_set_item'>
  11
  12   <refmeta>
  13     <refentrytitle>pam_set_item</refentrytitle>
  14     <manvolnum>3</manvolnum>
  15     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  16   </refmeta>
  17
  18   <refnamediv id='pam_set_item-name'>
  19     <refname>pam_set_item</refname>
  20     <refpurpose>
  21        set and update PAM informations
  22     </refpurpose>
  23   </refnamediv>
  24
  25
  26 <!-- body begins here -->
  27
  28   <refsynopsisdiv>
  29
  30    <funcsynopsis id="pam_set_item-synopsis">
  31      <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  32      <funcprototype>
  33        <funcdef>int <function>pam_set_item</function></funcdef>
  34        <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
  35        <paramdef>int <parameter>item_type</parameter></paramdef>
  36        <paramdef>const void *<parameter>item</parameter></paramdef>
  37      </funcprototype>
  38    </funcsynopsis>
  39
  40   </refsynopsisdiv>
  41
  42
  43   <refsect1 id="pam_set_item-description">
  44     <title>DESCRIPTION</title>
  45     <para>
  46       The <function>pam_set_item</function> function allows applications
  47       and PAM service modules to access and to update PAM informations
  48       of <emphasis>item_type</emphasis>. For this a copy
  49       of the object pointed to by the <emphasis>item</emphasis> argument
  50       is created. The following <emphasis>item_type</emphasis>s are
  51       supported:
  52    </para>
  53
  54    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
  55       href="pam_item_types.inc.xml"/>
  56
  57     <para>
  58       For all <emphasis>item_type</emphasis>s, other than PAM_CONV and
  59       PAM_FAIL_DELAY, <emphasis>item</emphasis> is a pointer to a &lt;NUL&gt;
  60       terminated character string. In the case of PAM_CONV,
  61       <emphasis>item</emphasis> points to an initialized
  62       <emphasis>pam_conv</emphasis> structure. In the case of
  63       PAM_FAIL_DELAY, <emphasis>item</emphasis> is a function pointer:
  64       <function>void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)</function>
  65     </para>
  66
  67     <para>
  68       Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before
  69       returning to the application. Which means an application is not
  70       able to access the authentication tokens.
  71     </para>
  72
  73   </refsect1>
  74
  75   <refsect1 id="pam_set_item-return_values">
  76     <title>RETURN VALUES</title>
  77     <variablelist>
  78       <varlistentry>
  79         <term>PAM_BAD_ITEM</term>
  80         <listitem>
  81            <para>
  82              The application attempted to set an undefined or inaccessible
  83              item.
  84           </para>
  85         </listitem>
  86       </varlistentry>
  87       <varlistentry>
  88         <term>PAM_BUF_ERR</term>
  89         <listitem>
  90            <para>
  91               Memory buffer error.
  92           </para>
  93         </listitem>
  94       </varlistentry>
  95       <varlistentry>
  96         <term>PAM_SUCCESS</term>
  97         <listitem>
  98            <para>
  99              Data was successful updated.
 100           </para>
 101         </listitem>
 102       </varlistentry>
 103       <varlistentry>
 104         <term>PAM_SYSTEM_ERR</term>
 105         <listitem>
 106            <para>
 107              The <emphasis>pam_handle_t</emphasis> passed as first
 108              argument was invalid.
 109           </para>
 110         </listitem>
 111        </varlistentry>
 112     </variablelist>
 113   </refsect1>
 114
 115   <refsect1 id="pam_set_item-see_also">
 116     <title>SEE ALSO</title>
 117     <para>
 118       <citerefentry>
 119         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
 120       </citerefentry>,
 121       <citerefentry>
 122         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 123       </citerefentry>
 124     </para>
 125   </refsect1>
 126
 127 </refentry>