linux-pam/doc/man/pam_set_item.3.xml

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="pam_set_item">

  <refmeta>
    <refentrytitle>pam_set_item</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo class="source">Linux-PAM</refmiscinfo>
    <refmiscinfo class="manual">Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv xml:id="pam_set_item-name">
    <refname>pam_set_item</refname>
    <refpurpose>
       set and update PAM information
    </refpurpose>
  </refnamediv>


<!-- body begins here -->

  <refsynopsisdiv>

   <funcsynopsis xml:id="pam_set_item-synopsis">
     <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
     <funcprototype>
       <funcdef>int <function>pam_set_item</function></funcdef>
       <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
       <paramdef>int <parameter>item_type</parameter></paramdef>
       <paramdef>const void *<parameter>item</parameter></paramdef>
     </funcprototype>
   </funcsynopsis>

  </refsynopsisdiv>


  <refsect1 xml:id="pam_set_item-description">
    <title>DESCRIPTION</title>
    <para>
      The <function>pam_set_item</function> function allows applications
      and PAM service modules to access and to update PAM information
      of <emphasis>item_type</emphasis>. For this a copy
      of the object pointed to by the <emphasis>item</emphasis> argument
      is created. The following <emphasis>item_type</emphasis>s are
      supported:
   </para>

   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_item_types_std.inc.xml"/>

   <para>
     The following additional items are specific to Linux-PAM and should not be used in
     portable applications:
   </para>

   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_item_types_ext.inc.xml"/>

    <para>
      For all <emphasis>item_type</emphasis>s, other than PAM_CONV and
      PAM_FAIL_DELAY, <emphasis>item</emphasis> is a pointer to a &lt;NUL&gt;
      terminated character string. In the case of PAM_CONV,
      <emphasis>item</emphasis> points to an initialized
      <emphasis>pam_conv</emphasis> structure. In the case of
      PAM_FAIL_DELAY, <emphasis>item</emphasis> is a function pointer:
      <function>void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)</function>
    </para>

    <para>
      Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reset before
      returning to the application. Which means an application is not
      able to access the authentication tokens.
    </para>

  </refsect1>

  <refsect1 xml:id="pam_set_item-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_BAD_ITEM</term>
        <listitem>
           <para>
             The application attempted to set an undefined or inaccessible
             item.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_BUF_ERR</term>
        <listitem>
           <para>
              Memory buffer error.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
           <para>
             Data was successful updated.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SYSTEM_ERR</term>
        <listitem>
           <para>
             The <emphasis>pam_handle_t</emphasis> passed as first
             argument was invalid.
          </para>
        </listitem>
       </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 xml:id="pam_set_item-see_also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
    </para>
  </refsect1>

</refentry>