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