Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------

More manual page updates/new manual pages

2006-02-17  Thorsten Kukuk  <kukuk@thkukuk.de>

        * doc/man/Makefile.am: Add new manual pages.
        * doc/man/pam_end.3: Regenerated from xml file.
        * doc/man/pam_end.3.xml: Document freeing of item data.
        * doc/man/pam_get_user.3: New.
        * doc/man/pam_get_user.3.xml: New.
        * modules/pam_access/access.conf.5.xml: Fix typos.
        * modules/pam_env/Makefile.am: Add new manual pages.
        * modules/pam_env/README: Regenerate from xml file.
        * modules/pam_env/README.xml: New.
        * modules/pam_env/pam_env.8: New.
        * modules/pam_env/pam_env.8.xml: New.
        * modules/pam_env/pam_env.conf.5: New.
        * modules/pam_env/pam_env.conf.5.xml New.

1 files changed, 139 insertions, 0 deletions

diff --git a/doc/man/pam_get_user.3.xml b/doc/man/pam_get_user.3.xml
new file mode 100644
index 00000000..40a6c53b
--- /dev/null
+++ b/doc/man/pam_get_user.3.xml
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+
+<refentry id='pam_get_user'>
+
+  <refmeta>
+    <refentrytitle>pam_get_user</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id='pam_get_user-name'>
+    <refname>pam_get_user</refname>
+    <refpurpose>
+       get user name
+    </refpurpose>
+  </refnamediv>
+
+
+<!-- body begins here -->
+
+  <refsynopsisdiv>
+
+   <funcsynopsis id="pam_get_user-synopsis">
+     <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
+     <funcprototype>
+       <funcdef>int <function>pam_get_user</function></funcdef>
+       <paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
+       <paramdef>const char **<parameter>user</parameter></paramdef>
+       <paramdef>const char *<parameter>prompt</parameter></paramdef>
+     </funcprototype>
+   </funcsynopsis>
+
+  </refsynopsisdiv>
+
+
+  <refsect1 id="pam_get_user-description">
+    <title>DESCRIPTION</title>
+    <para>
+      The <function>pam_get_user</function> function returns the
+      name of the user specified by
+      <citerefentry>
+        <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>. If no user was specified it what 
+      <function>pam_get_item (pamh, PAM_USER, ... );</function> would
+      have returned. If this is NULL it obtains the username via the
+      <citerefentry>
+        <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> mechanism, it prompts the user with the first
+      non-NULL string in the following list:
+    </para>
+
+    <itemizedlist>
+      <listitem>
+        <para>
+          The <emphasis>prompt</emphasis> argument passed to the function.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          What is returned by pam_get_item (pamh, PAM_USER_PROMPT, ... );
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The default prompt: "login: "
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      By whatever means the username is obtained, a pointer to it is
+      returned as the contents of <emphasis>*user</emphasis>. Note, 
+      this memory should <emphasis remap="B">not</emphasis> be 
+      <emphasis>free()</emphasis>'d or <emphasis>modified</emphasis>
+      by the module.
+    </para>
+    <para>
+      This function sets the <emphasis>PAM_USER</emphasis> item
+      associated with the 
+      <citerefentry>
+        <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> and
+      <citerefentry>
+        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry> functions.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pam_get_user-return_values">
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+           <para>
+             User name was successful retrieved.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SYSTEM_ERR</term>
+        <listitem>
+           <para>
+             A NULL pointer was submitted.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_CONV_ERR</term>
+        <listitem>
+           <para>
+             The conversation method supplied by the
+             application failed to obtain the username.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_get_user-see_also">
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+
+</refentry>