Relevant BUGIDs:

Purpose of commit: new feature

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

Convert manual page to xml and add missing sections.

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

        * modules/pam_echo/pam_echo.8.xml: New.
        * modules/pam_echo/pam_echo.8: Regenerated from xml file.
        * modules/pam_echo/Makefile.am: Include Make.xml.rules.
        * modules/pam_echo/pam_echo.c: Fix return value.

6 files changed, 337 insertions, 41 deletions

diff --git a/modules/pam_echo/Makefile.am b/modules/pam_echo/Makefile.am
index 03818d37..0bd3f2b4 100644
--- a/modules/pam_echo/Makefile.am
+++ b/modules/pam_echo/Makefile.am
@@ -1,13 +1,15 @@
 #
-# Copyright (c) 2005 Thorsten Kukuk <kukuk@suse.de>
+# Copyright (c) 2005, 2006 Thorsten Kukuk <kukuk@thkukuk.de>
 #
 
 CLEANFILES = *~
 
-EXTRA_DIST = $(MANS)
+EXTRA_DIST = README $(MANS) $(XMLS)
 
 man_MANS = pam_echo.8
 
+XMLS = README.xml pam_echo.8.xml
+
 securelibdir = $(SECUREDIR)
 secureconfdir = $(SCONFIGDIR)
 
@@ -19,3 +21,10 @@ if HAVE_VERSIONING
 endif
 
 securelib_LTLIBRARIES = pam_echo.la
+
+
+if ENABLE_REGENERATE_MAN
+noinst_DATA = README
+README: pam_echo.8.xml
+-include $(top_srcdir)/Make.xml.rules
+endif
diff --git a/modules/pam_echo/README b/modules/pam_echo/README
new file mode 100644
index 00000000..103e0b03
--- /dev/null
+++ b/modules/pam_echo/README
@@ -0,0 +1,50 @@
+pam_echo — PAM module for printing text messages
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+DESCRIPTION
+
+The pam_echo PAM module is for printing text messages to inform user about
+special things. Sequences starting with the % character are interpreted in the
+following way:
+
+%H
+
+    The name of the remote host (PAM_RHOST).
+
+%h
+
+    The name of the local host.
+
+%s
+
+    The service name (PAM_SERVICE).
+
+%t
+
+    The name of the controlling terminal (PAM_TTY).
+
+%U
+
+    The remote user name (PAM_RUSER).
+
+%u
+
+    The local user name (PAM_USER).
+
+All other sequences beginning with % expands to the characters following the %
+character.
+
+EXAMPLES
+
+For an example of the use of this module, we show how it may be used to print
+informations about good passwords:
+
+password optional pam_echo.so file=/usr/share/doc/good-password.txt
+password required pam_unix.so
+
+
+AUTHOR
+
+Thorsten Kukuk <kukuk@suse.de>
+
diff --git a/modules/pam_echo/README.xml b/modules/pam_echo/README.xml
new file mode 100644
index 00000000..b1556e38
--- /dev/null
+++ b/modules/pam_echo/README.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.docbook.org/xml/4.3/docbookx.dtd"
+[
+<!--
+<!ENTITY pamaccess SYSTEM "pam_echo.8.xml">
+-->
+]>
+
+<article>
+
+  <articleinfo>
+
+    <title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_echo.8.xml" xpointer='xpointer(//refnamediv[@id = "pam_echo-name"]/*)'/>
+    </title>
+
+  </articleinfo>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_echo.8.xml" xpointer='xpointer(//refsect1[@id = "pam_echo-description"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_echo.8.xml" xpointer='xpointer(//refsect1[@id = "pam_echo-examples"]/*)'/>
+  </section>
+
+  <section>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+      href="pam_echo.8.xml" xpointer='xpointer(//refsect1[@id = "pam_echo-author"]/*)'/>
+  </section>
+
+</article>
diff --git a/modules/pam_echo/pam_echo.8 b/modules/pam_echo/pam_echo.8
index 6834ae01..dd19e950 100644
--- a/modules/pam_echo/pam_echo.8
+++ b/modules/pam_echo/pam_echo.8
@@ -1,52 +1,82 @@
-.\" -*- nroff -*-
-.\" Copyright (c) 2005 Thorsten Kukuk kukuk@suse.de
-.\"
-.TH pam_echo 8 "September 2005" "pam_echo" "Reference Manual"
-.SH NAME
-pam_echo - PAM module for printing text messages
-.SH DESCRIPTION
+.\" ** 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_ECHO" "8" "02/13/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_echo \- PAM module for printing text messages
+.SH "SYNOPSIS"
+.HP 12
+\fBpam_echo.so\fR [file=\fI/path/message\fR]
+.SH "DESCRIPTION"
+.PP
 The
-.B pam_echo
-PAM module is for printing text messages to inform user about
-special things. Sequences starting with the
-.B %
+\fIpam_echo\fR
+PAM module is for printing text messages to inform user about special things. Sequences starting with the
+\fI%\fR
 character are interpreted in the following way:
 .TP
-.B %H
+\fI%H\fR
 The name of the remote host (PAM_RHOST).
 .TP
-.B %h
+\fI%h\fR
 The name of the local host.
 .TP
-.B %s
+\fI%s\fR
 The service name (PAM_SERVICE).
 .TP
-.B %t
+\fI%t\fR
 The name of the controlling terminal (PAM_TTY).
 .TP
-.B %U
+\fI%U\fR
 The remote user name (PAM_RUSER).
 .TP
-.B %u
+\fI%u\fR
 The local user name (PAM_USER).
 .PP
 All other sequences beginning with
-.B %
+\fI%\fR
 expands to the characters following the
-.B %
+\fI%\fR
 character.
-.SH OPTIONS
-The following options may be passed to all types of management
-groups:
-.TP
-.BR "file=" "message"
-.B pam_echo
-will print the content of the file
-.B message
-with the PAM conversion function as PAM_TEXT_INFO.
+.SH "OPTIONS"
+.TP
+\fBfile=\fR\fB\fI/path/message\fR\fR
+The content of the file
+\fI/path/message\fR
+will be printed with the PAM conversion function as PAM_TEXT_INFO.
+.SH "MODULE SERVICES PROVIDED"
+.PP
+All services are supported.
+.SH "RETURN VALUES"
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_SUCCESS
+Message was successful printed.
+.TP
+PAM_IGNORE
+PAM_SILENT flag was given or message file does not exist, no message printed.
+.SH "EXAMPLES"
+.PP
+For an example of the use of this module, we show how it may be used to print informations about good passwords:
+.sp
+.nf
+password optional pam_echo.so file=/usr/share/doc/good\-password.txt
+password required pam_unix.so
+      
+.fi
+.sp
 .SH "SEE ALSO"
-.BR pam.conf (8),
-.BR pam.d (8),
-.BR pam (8)
-.SH AUTHOR
+.PP
+\fBpam.conf\fR(8),
+\fBpam.d\fR(8),
+\fBpam\fR(8)
+.SH "AUTHOR"
+.PP
 Thorsten Kukuk <kukuk@suse.de>
diff --git a/modules/pam_echo/pam_echo.8.xml b/modules/pam_echo/pam_echo.8.xml
new file mode 100644
index 00000000..3619dd34
--- /dev/null
+++ b/modules/pam_echo/pam_echo.8.xml
@@ -0,0 +1,168 @@
+<?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_echo'>
+  <refmeta>
+    <refentrytitle>pam_echo</refentrytitle>
+    <manvolnum>8</manvolnum>
+    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+  </refmeta>
+
+  <refnamediv id='pam_echo-name'>
+    <refname>pam_echo</refname>
+    <refpurpose>PAM module for printing text messages</refpurpose>
+  </refnamediv>
+
+<!-- body begins here -->
+
+  <refsynopsisdiv>
+    <cmdsynopsis id="pam_echo-cmdsynopsis">
+      <command>pam_echo.so</command>
+      <arg choice="opt">
+        file=<replaceable>/path/message</replaceable>
+      </arg>
+    </cmdsynopsis>
+  </refsynopsisdiv>
+
+  <refsect1 id='pam_echo-description'>
+    <title>DESCRIPTION</title>
+    <para>
+      The <emphasis>pam_echo</emphasis> PAM module is for printing
+      text messages to inform user about special things. Sequences
+      starting with the <emphasis>%</emphasis> character are
+      interpreted in the following way:
+    </para>
+    <variablelist>
+      <varlistentry>
+        <term><emphasis>%H</emphasis></term>
+        <listitem>
+          <para>The name of the remote host (PAM_RHOST).</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><emphasis remap='B'>%h</emphasis></term>
+        <listitem>
+          <para>The name of the local host.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><emphasis>%s</emphasis></term>
+        <listitem>
+          <para>The service name (PAM_SERVICE).</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><emphasis>%t</emphasis></term>
+        <listitem>
+          <para>The name of the controlling terminal (PAM_TTY).</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><emphasis>%U</emphasis></term>
+        <listitem>
+          <para>The remote user name (PAM_RUSER).</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term><emphasis>%u</emphasis></term>
+        <listitem>
+          <para>The local user name (PAM_USER).</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>
+      All other sequences beginning with <emphasis>%</emphasis>
+      expands to the characters following the <emphasis>%</emphasis>
+      character.
+    </para>
+  </refsect1>
+
+  <refsect1 id='pam_echo-options'>
+    <title>OPTIONS</title>
+    <variablelist>
+      <varlistentry>
+        <term>
+          <option>file=<replaceable>/path/message</replaceable></option>
+        </term>
+        <listitem>
+          <para>
+            The content of the file <filename>/path/message</filename>
+            will be printed with the PAM conversion function as PAM_TEXT_INFO.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id="pam_echo-services">
+    <title>MODULE SERVICES PROVIDED</title>
+    <para>
+      All services are supported.
+    </para>
+  </refsect1>
+
+
+  <refsect1 id="pam_access-return_values">
+    <title>RETURN VALUES</title>
+    <variablelist>
+      <varlistentry>
+        <term>PAM_BUF_ERR</term>
+        <listitem>
+           <para>
+             Memory buffer error.
+          </para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>PAM_SUCCESS</term>
+        <listitem>
+           <para>
+             Message was successful printed.
+          </para>
+        </listitem>
+      </varlistentry>
+          <varlistentry>
+        <term>PAM_IGNORE</term>
+        <listitem>
+           <para>
+             PAM_SILENT flag was given or message file does not
+             exist, no message printed.
+          </para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </refsect1>
+
+  <refsect1 id='pam_echo-examples'>
+    <title>EXAMPLES</title>
+    <para>
+      For an example of the use of this module, we show how it may be
+      used to print informations about good passwords:
+      <programlisting>
+password optional pam_echo.so file=/usr/share/doc/good-password.txt
+password required pam_unix.so
+      </programlisting>
+    </para>
+  </refsect1>
+
+
+  <refsect1 id='pam_echo-see_also'><title>SEE ALSO</title>
+  <para>
+    <citerefentry>
+      <refentrytitle>pam.conf</refentrytitle><manvolnum>8</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>pam.d</refentrytitle><manvolnum>8</manvolnum>
+    </citerefentry>,
+    <citerefentry>
+      <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+    </citerefentry></para>
+  </refsect1>
+
+  <refsect1 id='pam_echo-author'>
+    <title>AUTHOR</title>
+    <para>Thorsten Kukuk &lt;kukuk@suse.de&gt;</para>
+  </refsect1>
+</refentry>
diff --git a/modules/pam_echo/pam_echo.c b/modules/pam_echo/pam_echo.c
index aa5d9285..e138c3df 100644
--- a/modules/pam_echo/pam_echo.c
+++ b/modules/pam_echo/pam_echo.c
@@ -76,7 +76,7 @@ replace_and_print (pam_handle_t *pamh, const char *mesg)
   if (output == NULL)
     {
       pam_syslog (pamh, LOG_ERR, "running out of memory");
-      return PAM_IGNORE;
+      return PAM_BUF_ERR;
     }
 
   for (p = mesg, len = 0; *p != '\0' && len < length - 1; ++p)
@@ -139,6 +139,7 @@ pam_echo (pam_handle_t *pamh, int flags, int argc, const char **argv)
   int orig_argc = argc;
   const char **orig_argv = argv;
   const char *file = NULL;
+  int retval;
 
   if (flags & PAM_SILENT)
     return PAM_IGNORE;
@@ -166,7 +167,7 @@ pam_echo (pam_handle_t *pamh, int flags, int argc, const char **argv)
 	}
       msg[len] = '\0';
 
-      replace_and_print (pamh, msg);
+      retval = replace_and_print (pamh, msg);
     }
   else if ((fd = open (file, O_RDONLY, 0)) >= 0)
     {
@@ -179,7 +180,7 @@ pam_echo (pam_handle_t *pamh, int flags, int argc, const char **argv)
 
       mtmp = malloc (st.st_size + 1);
       if (!mtmp)
-	return PAM_IGNORE;
+	return PAM_BUF_ERR;
 
       if (read (fd, mtmp, st.st_size) == -1)
 	{
@@ -194,13 +195,15 @@ pam_echo (pam_handle_t *pamh, int flags, int argc, const char **argv)
 	mtmp[st.st_size] = '\0';
 
       close (fd);
-      replace_and_print (pamh, mtmp);
+      retval = replace_and_print (pamh, mtmp);
       free (mtmp);
     }
   else
-    pam_syslog (pamh, LOG_ERR, "Cannot open %s: %m", file);
-
-  return PAM_IGNORE;
+    {
+       pam_syslog (pamh, LOG_ERR, "Cannot open %s: %m", file);
+       retval = PAM_IGNORE;
+    }
+  return retval;
 }
 
 int