doc/man/pam_get_user.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 <refentry id='pam_get_user'>
   6
   7   <refmeta>
   8     <refentrytitle>pam_get_user</refentrytitle>
   9     <manvolnum>3</manvolnum>
  10     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id='pam_get_user-name'>
  14     <refname>pam_get_user</refname>
  15     <refpurpose>
  16        get user name
  17     </refpurpose>
  18   </refnamediv>
  19
  20
  21 <!-- body begins here -->
  22
  23   <refsynopsisdiv>
  24
  25    <funcsynopsis id="pam_get_user-synopsis">
  26      <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
  27      <funcprototype>
  28        <funcdef>int <function>pam_get_user</function></funcdef>
  29        <paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
  30        <paramdef>const char **<parameter>user</parameter></paramdef>
  31        <paramdef>const char *<parameter>prompt</parameter></paramdef>
  32      </funcprototype>
  33    </funcsynopsis>
  34
  35   </refsynopsisdiv>
  36
  37
  38   <refsect1 id="pam_get_user-description">
  39     <title>DESCRIPTION</title>
  40     <para>
  41       The <function>pam_get_user</function> function returns the
  42       name of the user specified by
  43       <citerefentry>
  44         <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
  45       </citerefentry>. If no user was specified it what
  46       <function>pam_get_item (pamh, PAM_USER, ... );</function> would
  47       have returned. If this is NULL it obtains the username via the
  48       <citerefentry>
  49         <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
  50       </citerefentry> mechanism, it prompts the user with the first
  51       non-NULL string in the following list:
  52     </para>
  53
  54     <itemizedlist>
  55       <listitem>
  56         <para>
  57           The <emphasis>prompt</emphasis> argument passed to the function.
  58         </para>
  59       </listitem>
  60       <listitem>
  61         <para>
  62           What is returned by pam_get_item (pamh, PAM_USER_PROMPT, ... );
  63         </para>
  64       </listitem>
  65       <listitem>
  66         <para>
  67           The default prompt: "login: "
  68         </para>
  69       </listitem>
  70     </itemizedlist>
  71     <para>
  72       By whatever means the username is obtained, a pointer to it is
  73       returned as the contents of <emphasis>*user</emphasis>. Note,
  74       this memory should <emphasis remap="B">not</emphasis> be
  75       <emphasis>free()</emphasis>'d or <emphasis>modified</emphasis>
  76       by the module.
  77     </para>
  78     <para>
  79       This function sets the <emphasis>PAM_USER</emphasis> item
  80       associated with the
  81       <citerefentry>
  82         <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
  83       </citerefentry> and
  84       <citerefentry>
  85         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
  86       </citerefentry> functions.
  87     </para>
  88   </refsect1>
  89
  90   <refsect1 id="pam_get_user-return_values">
  91     <title>RETURN VALUES</title>
  92     <variablelist>
  93       <varlistentry>
  94         <term>PAM_SUCCESS</term>
  95         <listitem>
  96            <para>
  97              User name was successful retrieved.
  98           </para>
  99         </listitem>
 100       </varlistentry>
 101       <varlistentry>
 102         <term>PAM_SYSTEM_ERR</term>
 103         <listitem>
 104            <para>
 105              A NULL pointer was submitted.
 106           </para>
 107         </listitem>
 108       </varlistentry>
 109       <varlistentry>
 110         <term>PAM_CONV_ERR</term>
 111         <listitem>
 112            <para>
 113              The conversation method supplied by the
 114              application failed to obtain the username.
 115           </para>
 116         </listitem>
 117       </varlistentry>
 118     </variablelist>
 119   </refsect1>
 120
 121   <refsect1 id="pam_get_user-see_also">
 122     <title>SEE ALSO</title>
 123     <para>
 124       <citerefentry>
 125         <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
 126       </citerefentry>,
 127       <citerefentry>
 128         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
 129       </citerefentry>,
 130       <citerefentry>
 131         <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
 132       </citerefentry>,
 133       <citerefentry>
 134         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 135       </citerefentry>
 136     </para>
 137   </refsect1>
 138
 139 </refentry>