granicus.if.org Git - linux-pam/blob - doc/man/pam_get_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_get_item'>
  11
  12   <refmeta>
  13     <refentrytitle>pam_get_item</refentrytitle>
  14     <manvolnum>3</manvolnum>
  15     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  16   </refmeta>
  17
  18   <refnamediv id='pam_get_item-name'>
  19     <refname>pam_get_item</refname>
  20     <refpurpose>
  21        getting PAM informations
  22     </refpurpose>
  23   </refnamediv>
  24
  25
  26 <!-- body begins here -->
  27
  28   <refsynopsisdiv>
  29
  30    <funcsynopsis id="pam_get_item-synopsis">
  31      <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  32      <funcprototype>
  33        <funcdef>int <function>pam_get_item</function></funcdef>
  34        <paramdef>const 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_get_item-description">
  44     <title>DESCRIPTION</title>
  45     <para>
  46       The <function>pam_get_item</function> function allows applications
  47       and PAM service modules to access and retrieve PAM informations
  48       of <emphasis>item_type</emphasis>. Upon successful return,
  49       <emphasis>item</emphasis> contains a pointer to the value of the
  50       corresponding item. Note, this is a pointer to the
  51       <emphasis>actual</emphasis> data and should
  52       <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
  53       over-written! The following values are supported for
  54       <emphasis>item_type</emphasis>:
  55    </para>
  56
  57    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
  58       href="pam_item_types.inc.xml"/>
  59
  60     <para>
  61       If a service module wishes to obtain the name of the user,
  62       it should not use this function, but instead perform a call to
  63       <citerefentry>
  64         <refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
  65       </citerefentry>.
  66     </para>
  67     <para>
  68       Only a service module is privileged to read the
  69       authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK.
  70     </para>
  71
  72   </refsect1>
  73
  74   <refsect1 id="pam_get_item-return_values">
  75     <title>RETURN VALUES</title>
  76     <variablelist>
  77       <varlistentry>
  78         <term>PAM_BAD_ITEM</term>
  79         <listitem>
  80            <para>
  81              The application attempted to set an undefined or inaccessible
  82              item.
  83           </para>
  84         </listitem>
  85       </varlistentry>
  86       <varlistentry>
  87         <term>PAM_BUF_ERR</term>
  88         <listitem>
  89            <para>
  90               Memory buffer error.
  91           </para>
  92         </listitem>
  93       </varlistentry>
  94       <varlistentry>
  95         <term>PAM_PERM_DENIED</term>
  96         <listitem>
  97            <para>
  98              The value of <emphasis>item</emphasis> was NULL.
  99           </para>
 100         </listitem>
 101       </varlistentry>
 102       <varlistentry>
 103         <term>PAM_SUCCESS</term>
 104         <listitem>
 105            <para>
 106              Data was successful updated.
 107           </para>
 108         </listitem>
 109       </varlistentry>
 110       <varlistentry>
 111         <term>PAM_SYSTEM_ERR</term>
 112         <listitem>
 113            <para>
 114              The <emphasis>pam_handle_t</emphasis> passed as first
 115              argument was invalid.
 116           </para>
 117         </listitem>
 118        </varlistentry>
 119     </variablelist>
 120   </refsect1>
 121
 122   <refsect1 id="pam_get_item-see_also">
 123     <title>SEE ALSO</title>
 124     <para>
 125       <citerefentry>
 126         <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
 127       </citerefentry>,
 128       <citerefentry>
 129         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 130       </citerefentry>
 131     </para>
 132   </refsect1>
 133
 134 </refentry>