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.

5 files changed, 233 insertions, 3 deletions

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 49eefacc..83d1eec5 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -11,7 +11,7 @@ man_MANS = pam.8 pam.conf.5 pam.d.5 \
 	pam_chauthtok.3 pam_close_session.3 \
 	pam_end.3 \
 	pam_fail_delay.3 \
-	pam_get_data.3 pam_get_item.3 \
+	pam_get_data.3 pam_get_item.3 pam_get_user.3 \
 	pam_open_session.3 \
 	pam_set_data.3 pam_set_item.3 \
 	pam_setcred.3 pam_start.3 pam_strerror.3
@@ -20,7 +20,7 @@ XMLS = pam.8.xml \
 	pam_chauthtok.3.xml pam_close_session.3.xml \
 	pam_end.3.xml \
 	pam_fail_delay.3.xml \
-	pam_get_data.3.xml pam_get_item.3.xml \
+	pam_get_data.3.xml pam_get_item.3.xml pam_get_user.3.xml \
 	pam_open_session.3.xml \
 	pam_set_data.3.xml pam_set_item.3.xml \
 	pam_setcred.3.xml pam_start.3.xml pam_strerror.3.xml \
diff --git a/doc/man/pam_end.3 b/doc/man/pam_end.3
index e074c6c5..3b0e3cb7 100644
--- a/doc/man/pam_end.3
+++ b/doc/man/pam_end.3
@@ -2,7 +2,7 @@
 .\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
 .\" Instead of manually editing it, you probably should edit the DocBook XML
 .\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
-.TH "PAM_END" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.TH "PAM_END" "3" "02/14/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
@@ -37,6 +37,15 @@ and
 \fIPAM_DATA_SILENT\fR
 to indicate to indicate that the module should not treat the call too seriously. It is generally used to indicate that the current closing of the library is in a
 \fBfork\fR(2)ed process, and that the parent will take care of cleaning up things that exist outside of the current process space (files etc.).
+.PP
+This function
+\fIfree\fR's all memory for items associated with the
+\fBpam_set_item\fR(3)
+and
+\fBpam_get_item\fR(3)
+functions. Pointers associated with such objects are not valid anymore after
+\fBpam_end\fR
+was called.
 .SH "RETURN VALUES"
 .TP
 PAM_SUCCESS
diff --git a/doc/man/pam_end.3.xml b/doc/man/pam_end.3.xml
index 64dd3900..de317c53 100644
--- a/doc/man/pam_end.3.xml
+++ b/doc/man/pam_end.3.xml
@@ -65,6 +65,19 @@
       process, and that the parent will take care of cleaning up things
       that exist outside of the current process space (files etc.).
     </para>
+
+    <para>
+      This function <emphasis>free</emphasis>'s all memory for items
+      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. Pointers associated with such objects
+      are not valid anymore after <function>pam_end</function> was called.
+    </para>
+
   </refsect1>
   <refsect1 id="pam_end-return_values">
     <title>RETURN VALUES</title>
diff --git a/doc/man/pam_get_user.3 b/doc/man/pam_get_user.3
new file mode 100644
index 00000000..a5bc9ebe
--- /dev/null
+++ b/doc/man/pam_get_user.3
@@ -0,0 +1,69 @@
+.\" ** You probably do not want to edit this file directly **
+.\" It was generated using the DocBook XSL Stylesheets (version 1.69.1).
+.\" Instead of manually editing it, you probably should edit the DocBook XML
+.\" source for it and then use the DocBook XSL Stylesheets to regenerate it.
+.TH "PAM_GET_USER" "3" "02/14/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_get_user \- get user name
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_modules.h>\fR
+.HP 17
+\fBint\ \fBpam_get_user\fR\fR\fB(\fR\fBconst\ pam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBconst\ char\ **\fR\fB\fIuser\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fIprompt\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_get_user\fR
+function returns the name of the user specified by
+\fBpam_start\fR(3). If no user was specified it what
+\fBpam_get_item (pamh, PAM_USER, ... );\fR
+would have returned. If this is NULL it obtains the username via the
+\fBpam_conv\fR(3)
+mechanism, it prompts the user with the first non\-NULL string in the following list:
+.TP 3
+\(bu
+The
+\fIprompt\fR
+argument passed to the function.
+.TP
+\(bu
+What is returned by pam_get_item (pamh, PAM_USER_PROMPT, ... );
+.TP
+\(bu
+The default prompt: "login: "
+.PP
+By whatever means the username is obtained, a pointer to it is returned as the contents of
+\fI*user\fR. Note, this memory should
+\fInot\fR
+be
+\fIfree()\fR'd or
+\fImodified\fR
+by the module.
+.PP
+This function sets the
+\fIPAM_USER\fR
+item associated with the
+\fBpam_set_item\fR(3)
+and
+\fBpam_get_item\fR(3)
+functions.
+.SH "RETURN VALUES"
+.TP
+PAM_SUCCESS
+User name was successful retrieved.
+.TP
+PAM_SYSTEM_ERR
+A NULL pointer was submitted.
+.TP
+PAM_CONV_ERR
+The conversation method supplied by the application failed to obtain the username.
+.SH "SEE ALSO"
+.PP
+\fBpam_end\fR(3),
+\fBpam_get_item\fR(3),
+\fBpam_set_item\fR(3),
+\fBpam_strerror\fR(3)
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>