Relevant BUGIDs:

Purpose of commit: new feature

Commit summary:
---------------
2007-12-06  Eamon Walsh <ewalsh@tycho.nsa.gov>

        * libpam/include/security/_pam_macros.h: Add _pam_overwrite_n()
        macro.
        * libpam/include/security/_pam_types.h: Add PAM_XDISPLAY,
        PAM_XAUTHDATA items, pam_xauth_data struct.
        * libpam/pam_item.c (pam_set_item, pam_get_item): Handle
        PAM_XDISPLAY and PAM_XAUTHDATA items.
        * libpam/pam_end.c (pam_end): Destroy the new items.
        * libpam/pam_private.h (pam_handle): Add data members for new
        items. Add prototype for _pam_memdup.
        * libpam/pam_misc.c: Add _pam_memdup.
        * doc/man/Makefile.am: Add pam_xauth_data.3. Replace
        pam_item_types.inc.xml with pam_item_types_std.inc.xml and
        pam_item_types_ext.inc.xml.
        * doc/man/pam_get_item.3.xml: Replace pam_item_types.inc.xml
        with pam_item_types_std.inc.xml and pam_item_types_ext.inc.xml.
        * doc/man/pam_set_item.3.xml: Likewise.
        * doc/man/pam_item_types.inc.xml: Removed file.
        * doc/man/pam_item_types_ext.inc.xml: New file.
        * doc/man/pam_item_types_std.inc.xml: New file.

5 files changed, 72 insertions, 22 deletions

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 7d17a439..926f1ae5 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -10,7 +10,7 @@ man_MANS = pam.3 PAM.8 pam.8 pam.conf.5 pam.d.5 \
 	pam_acct_mgmt.3 pam_authenticate.3 \
 	pam_chauthtok.3 pam_close_session.3 pam_conv.3 \
 	pam_end.3 pam_error.3 \
-	pam_fail_delay.3 \
+	pam_fail_delay.3 pam_xauth_data.3 \
 	pam_get_data.3 pam_get_item.3 pam_get_user.3 pam_getenv.3 \
 	pam_getenvlist.3 \
 	pam_info.3 \
@@ -27,7 +27,7 @@ XMLS = pam.3.xml pam.8.xml \
 	pam_acct_mgmt.3.xml pam_authenticate.3.xml \
 	pam_chauthtok.3.xml pam_close_session.3.xml pam_conv.3.xml \
 	pam_end.3.xml pam_error.3.xml \
-	pam_fail_delay.3.xml \
+	pam_fail_delay.3.xml pam_xauth_data.3 \
 	pam_get_data.3.xml pam_get_item.3.xml pam_get_user.3.xml \
 	pam_getenv.3.xml pam_getenvlist.3.xml \
         pam_info.3.xml \
@@ -38,14 +38,14 @@ XMLS = pam.3.xml pam.8.xml \
 	pam_sm_close_session.3.xml pam_sm_open_session.3.xml \
 	pam_sm_setcred.3.xml pam_start.3.xml pam_strerror.3.xml \
 	pam_sm_chauthtok.3.xml \
-	pam_item_types.inc.xml \
+	pam_item_types_std.inc.xml pam_item_types_ext.inc.xml \
 	pam.conf-desc.xml pam.conf-dir.xml pam.conf-syntax.xml \
 	misc_conv.3.xml pam_misc_paste_env.3.xml pam_misc_drop_env.3.xml \
 	pam_misc_setenv.3.xml
 
 if ENABLE_REGENERATE_MAN
-pam_get_item.3: pam_item_types.inc.xml
-pam_set_data.3: pam_item_types.inc.xml
+pam_get_item.3: pam_item_types_std.inc.xml pam_item_types_ext.inc.xml
+pam_set_data.3: pam_item_types_std.inc.xml pam_item_types_ext.inc.xml
 pam.conf.5: pam.conf-desc.xml pam.conf-dir.xml pam.conf-syntax.xml
 -include $(top_srcdir)/Make.xml.rules
 endif
diff --git a/doc/man/pam_get_item.3.xml b/doc/man/pam_get_item.3.xml
index e5806d11..d07862e0 100644
--- a/doc/man/pam_get_item.3.xml
+++ b/doc/man/pam_get_item.3.xml
@@ -3,7 +3,8 @@
                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
 [
 <!--
-<!ENTITY accessconf SYSTEM "pam_item_types.inc.xml">
+<!ENTITY accessconf SYSTEM "pam_item_types_std.inc.xml">
+<!ENTITY accessconf SYSTEM "pam_item_types_ext.inc.xml">
 -->
 ]>
 
@@ -55,7 +56,15 @@
    </para>
 
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
-      href="pam_item_types.inc.xml"/>
+      href="pam_item_types_std.inc.xml"/>
+
+   <para>
+     The following additional items are specific to Linux-PAM and should not be used in
+     portable applications:
+   </para>
+
+   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_item_types_ext.inc.xml"/>
 
     <para>
       If a service module wishes to obtain the name of the user,
diff --git a/doc/man/pam_item_types_ext.inc.xml b/doc/man/pam_item_types_ext.inc.xml
new file mode 100644
index 00000000..0c72f699
--- /dev/null
+++ b/doc/man/pam_item_types_ext.inc.xml
@@ -0,0 +1,45 @@
+<!-- this file is included by pam_set_item and pam_get_item -->
+
+    <variablelist>
+      <varlistentry>
+        <term>PAM_FAIL_DELAY</term>
+        <listitem>
+          <para>
+            A function pointer to redirect centrally managed
+            failure delays. See
+            <citerefentry>
+              <refentrytitle>pam_fail_delay</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PAM_XDISPLAY</term>
+        <listitem>
+          <para>
+            The name of the X display.  For graphical, X-based applications the
+	    value for this item should be the <emphasis>$DISPLAY</emphasis>
+	    variable.  This value should be used instead of
+	    <emphasis>PAM_TTY</emphasis> for passing the
+	    name of the display where possible.
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PAM_XAUTHDATA</term>
+        <listitem>
+          <para>
+            A pointer to a structure containing the X authentication data
+	    required to make a connection to the display specified by
+	    <emphasis>PAM_XDISPLAY</emphasis>, if such information is
+	    necessary.  See
+            <citerefentry>
+              <refentrytitle>pam_xauth_data</refentrytitle><manvolnum>3</manvolnum>
+            </citerefentry>.
+          </para>
+        </listitem>
+      </varlistentry>
+
+    </variablelist>
diff --git a/doc/man/pam_item_types.inc.xml b/doc/man/pam_item_types_std.inc.xml
index 9d70087b..81f240b0 100644
--- a/doc/man/pam_item_types.inc.xml
+++ b/doc/man/pam_item_types_std.inc.xml
@@ -135,17 +135,4 @@
         </listitem>
       </varlistentry>
 
-      <varlistentry>
-        <term>PAM_FAIL_DELAY</term>
-        <listitem>
-          <para>
-            A function pointer to redirect centrally managed
-            failure delays. See
-            <citerefentry>
-              <refentrytitle>pam_fail_delay</refentrytitle><manvolnum>3</manvolnum>
-            </citerefentry>.
-          </para>
-        </listitem>
-      </varlistentry>
-
     </variablelist>
diff --git a/doc/man/pam_set_item.3.xml b/doc/man/pam_set_item.3.xml
index cbac8413..39758313 100644
--- a/doc/man/pam_set_item.3.xml
+++ b/doc/man/pam_set_item.3.xml
@@ -3,7 +3,8 @@
                    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"
 [
 <!--
-<!ENTITY accessconf SYSTEM "pam_item_types.inc.xml">
+<!ENTITY accessconf SYSTEM "pam_item_types_std.inc.xml">
+<!ENTITY accessconf SYSTEM "pam_item_types_ext.inc.xml">
 -->
 ]>
 
@@ -52,7 +53,15 @@
    </para>
 
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
-      href="pam_item_types.inc.xml"/>
+      href="pam_item_types_std.inc.xml"/>
+
+   <para>
+     The following additional items are specific to Linux-PAM and should not be used in
+     portable applications:
+   </para>
+
+   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_item_types_ext.inc.xml"/>
 
     <para>
       For all <emphasis>item_type</emphasis>s, other than PAM_CONV and