summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ChangeLog40
-rw-r--r--Make.xml.rules8
-rw-r--r--NEWS1
-rw-r--r--configure.in2
-rw-r--r--doc/Makefile.am11
-rw-r--r--doc/man/.cvsignore2
-rw-r--r--doc/man/Makefile.am33
-rw-r--r--doc/man/pam.8535
-rw-r--r--doc/man/pam.8.xml392
-rw-r--r--doc/man/pam_acct_mgmt.360
-rw-r--r--doc/man/pam_acct_mgmt.3.xml145
-rw-r--r--doc/man/pam_authenticate.3153
-rw-r--r--doc/man/pam_authenticate.3.xml169
-rw-r--r--doc/man/pam_chauthtok.3160
-rw-r--r--doc/man/pam_chauthtok.3.xml164
-rw-r--r--doc/man/pam_close_session.348
-rw-r--r--doc/man/pam_close_session.3.xml115
-rw-r--r--doc/man/pam_end.353
-rw-r--r--doc/man/pam_end.3.xml109
-rw-r--r--doc/man/pam_fail_delay.3216
-rw-r--r--doc/man/pam_fail_delay.3.xml175
-rw-r--r--doc/man/pam_get_data.352
-rw-r--r--doc/man/pam_get_data.3.xml108
-rw-r--r--doc/man/pam_get_item.3117
-rw-r--r--doc/man/pam_get_item.3.xml134
-rw-r--r--doc/man/pam_item_types.inc.xml151
-rw-r--r--doc/man/pam_open_session.3140
-rw-r--r--doc/man/pam_open_session.3.xml115
-rw-r--r--doc/man/pam_set_data.385
-rw-r--r--doc/man/pam_set_data.3.xml172
-rw-r--r--doc/man/pam_set_item.3164
-rw-r--r--doc/man/pam_set_item.3.xml127
-rw-r--r--doc/man/pam_setcred.3139
-rw-r--r--doc/man/pam_setcred.3.xml173
-rw-r--r--doc/man/pam_start.3160
-rw-r--r--doc/man/pam_start.3.xml143
-rw-r--r--doc/man/pam_strerror.377
-rw-r--r--doc/man/pam_strerror.3.xml58
-rw-r--r--doc/man/template-man52
39 files changed, 3690 insertions, 1068 deletions
diff --git a/ChangeLog b/ChangeLog
index e42cdbed..36a975e7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,43 @@
+2006-02-12 Thorsten Kukuk <kukuk@thkukuk.de>
+
+ * configure.in: Add doc/man/Makefile.
+ * Make.xml.rules: Enable xincludes for manual pages.
+ * doc/Makefile.am (EXRA_DIST): Remove manual pages.
+ (SUBDIR): Add man subdirectory.
+ * doc/man/Makefile.am: New.
+ * doc/man/pam_acct_mgmt.3: New.
+ * doc/man/pam_acct_mgmt.3.xml: New.
+ * doc/man/pam_get_data.3: New.
+ * doc/man/pam_get_data.3.xml: New.
+ * doc/man/pam_set_data.3: New.
+ * doc/man/pam_set_data.3.xml: New.
+ * doc/man/pam.8.xml: New.
+ * doc/man/pam.8: Regenerated from xml file.
+ * doc/man/pam_authenticate.3.xml: New.
+ * doc/man/pam_authenticate.3: Regenerated from xml file.
+ * doc/man/pam_chauthtok.3.xml: New.
+ * doc/man/pam_chauthtok.3: Regenerated from xml file.
+ * doc/man/pam_close_session.3.xml: New.
+ * doc/man/pam_close_session.3: Regenerated from xml file.
+ * doc/man/pam_end.3.xml: New.
+ * doc/man/pam_end.3: Regenerated from xml file.
+ * doc/man/pam_fail_delay.3.xml: New.
+ * doc/man/pam_fail_delay.3: Regenerated from xml file.
+ * doc/man/pam_get_item.3.xml: New.
+ * doc/man/pam_get_item.3: Regenerated from xml file.
+ * doc/man/pam_item_types.inc.xml: New.
+ * doc/man/pam_open_session.3.xml: New.
+ * doc/man/pam_open_session.3: Regenerated from xml file.
+ * doc/man/pam_set_item.3.xml: New.
+ * doc/man/pam_set_item.3: Regenerated from xml file.
+ * doc/man/pam_setcred.3.xml: New.
+ * doc/man/pam_setcred.3: Regenerated from xml file.
+ * doc/man/pam_start.3.xml: New.
+ * doc/man/pam_start.3: Regenerated from xml file.
+ * doc/man/pam_strerror.3.xml: New.
+ * doc/man/pam_strerror.3: Regenerated from xml file.
+ * doc/man/template-man: Removed.
+
2006-02-10 Thorsten Kukuk <kukuk@thkukuk.de>
* configure.in: Remove pam_pwdb support.
diff --git a/Make.xml.rules b/Make.xml.rules
index 208640b0..6e9dccc9 100644
--- a/Make.xml.rules
+++ b/Make.xml.rules
@@ -7,19 +7,19 @@ README: README.xml
%.1: %.1.xml
$(XMLLINT) --nonet --xinclude --postvalid --noout $<
- $(XSLTPROC) -o $(srcdir)/$@ --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+ $(XSLTPROC) -o $(srcdir)/$@ --path $(srcdir) --xinclude --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
%.3: %.3.xml
$(XMLLINT) --nonet --xinclude --postvalid --noout $<
- $(XSLTPROC) -o $(srcdir)/$@ --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+ $(XSLTPROC) -o $(srcdir)/$@ --path $(srcdir) --xinclude --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
%.5: %.5.xml
$(XMLLINT) --nonet --xinclude --postvalid --noout $<
- $(XSLTPROC) -o $(srcdir)/$@ --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+ $(XSLTPROC) -o $(srcdir)/$@ --path $(srcdir) --xinclude --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
%.8: %.8.xml
$(XMLLINT) --nonet --xinclude --postvalid --noout $<
- $(XSLTPROC) -o $(srcdir)/$@ --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
+ $(XSLTPROC) -o $(srcdir)/$@ --path $(srcdir) --xinclude --nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
#CLEANFILES += $(man_MANS) README
diff --git a/NEWS b/NEWS
index 0ae0bd54..0ccd6fdc 100644
--- a/NEWS
+++ b/NEWS
@@ -8,6 +8,7 @@ Linux-PAM NEWS -- history of user-visible changes.
* pam_access: Add network(address) / netmask and IPv6 support
* Add manual pages for pam_cracklib, pam_deny and pam_access
* pam_pwdb: This deprecated module was removed
+* Manual pages: Major rewrite/cleanup
Release 0.99.3.0
diff --git a/configure.in b/configure.in
index c5bda955..f5c72eaf 100644
--- a/configure.in
+++ b/configure.in
@@ -469,4 +469,4 @@ AC_OUTPUT(Makefile libpam/Makefile libpamc/Makefile libpamc/test/Makefile \
modules/pam_unix/Makefile modules/pam_userdb/Makefile \
modules/pam_warn/Makefile modules/pam_wheel/Makefile \
modules/pam_xauth/Makefile doc/Makefile doc/specs/Makefile \
- examples/Makefile)
+ doc/man/Makefile examples/Makefile)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index db76481f..dd4cb520 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,8 +1,8 @@
#
-# Copyright (c) 2005 Thorsten Kukuk <kukuk@suse.de>
+# Copyright (c) 2005, 2006 Thorsten Kukuk <kukuk@suse.de>
#
-SUBDIRS = specs
+SUBDIRS = man specs
FILES=pam pam_appl pam_modules
FSRCS=$(srcdir)/pam_appl.sgml $(srcdir)/pam_modules.sgml
@@ -18,15 +18,10 @@ CLEANFILES = *~ */*~ $(TEXTS) $(PSFILES) $(PDFFILES) html/pam*.html \
ps/missfont.log MODULES-SGML pam.sgml
EXTRA_DIST = $(FSRCS) CREDITS NOTES figs/pam_orient.txt pdf/README \
- ps/README html/index.html txts/README man/template-man $(MANS) \
+ ps/README html/index.html txts/README \
pam_source.sgml $(MODULES) modules/module.sgml-template \
modules/README
-man_MANS = $(addprefix man/, pam.8 pam.conf.5 pam.d.5 pam_authenticate.3 \
- pam_chauthtok.3 pam_close_session.3 pam_end.3 pam_fail_delay.3 \
- pam_get_item.3 pam_open_session.3 pam_set_item.3 pam_setcred.3 \
- pam_start.3 pam_strerror.3)
-
#######################################################
all: html text postscript pdf
diff --git a/doc/man/.cvsignore b/doc/man/.cvsignore
new file mode 100644
index 00000000..282522db
--- /dev/null
+++ b/doc/man/.cvsignore
@@ -0,0 +1,2 @@
+Makefile
+Makefile.in
diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
new file mode 100644
index 00000000..49eefacc
--- /dev/null
+++ b/doc/man/Makefile.am
@@ -0,0 +1,33 @@
+#
+# Copyright (c) 2006 Thorsten Kukuk <kukuk@thkukuk.de>
+#
+
+CLEANFILES = *~
+
+EXTRA_DIST = $(MANS) $(XMLS)
+
+man_MANS = pam.8 pam.conf.5 pam.d.5 \
+ pam_acct_mgmt.3 pam_authenticate.3 \
+ pam_chauthtok.3 pam_close_session.3 \
+ pam_end.3 \
+ pam_fail_delay.3 \
+ pam_get_data.3 pam_get_item.3 \
+ pam_open_session.3 \
+ pam_set_data.3 pam_set_item.3 \
+ pam_setcred.3 pam_start.3 pam_strerror.3
+XMLS = pam.8.xml \
+ pam_acct_mgmt.3.xml pam_authenticate.3.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_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 \
+ pam_item_types.inc.xml
+
+if ENABLE_REGENERATE_MAN
+pam_get_item.3: pam_item_types.inc.xml
+pam_set_data.3: pam_item_types.inc.xml
+-include $(top_srcdir)/Make.xml.rules
+endif
diff --git a/doc/man/pam.8 b/doc/man/pam.8
index fc032bcc..3e511174 100644
--- a/doc/man/pam.8
+++ b/doc/man/pam.8
@@ -1,375 +1,246 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7,2001 <morgan@kernel.org>
-.TH PAM 8 "2005 Oct 27" "Linux-PAM 1.0" "Linux-PAM Manual"
-.SH NAME
-
-Linux-PAM \- Pluggable Authentication Modules for Linux
-
-.SH SYNOPSIS
-.B /etc/pam.conf
-.sp 2
-.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" "8" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam \- Pluggable Authentication Modules for Linux
+.SH "DESCRIPTION"
+.PP
This manual is intended to offer a quick introduction to
-.BR Linux-PAM ". "
-For more information the reader is directed to the
-.BR "Linux-PAM system administrators' guide".
-
-.sp
-.BR Linux-PAM
-Is a system of libraries that handle the authentication tasks of
-applications (services) on the system. The library provides a stable
-general interface (Application Programming Interface - API) that
-privilege granting programs (such as
-.BR login "(1) "
+\fILinux\-PAM\fR. For more information the reader is directed to the
+\fILinux\-PAM system administrators' guide\fR.
+.PP
+\fILinux\-PAM\fR
+Is a system of libraries that handle the authentication tasks of applications (services) on the system. The library provides a stable general interface (Application Programming Interface \- API) that privilege granting programs (such as
+\fBlogin\fR(1)
and
-.BR su "(1)) "
-defer to to perform standard authentication tasks.
-
-.sp
-The principal feature of the PAM approach is that the nature of the
-authentication is dynamically configurable. In other words, the
-system administrator is free to choose how individual
-service-providing applications will authenticate users. This dynamic
-configuration is set by the contents of the single
-.BR Linux-PAM
+\fBsu\fR(1)) defer to to perform standard authentication tasks.
+.PP
+The principal feature of the PAM approach is that the nature of the authentication is dynamically configurable. In other words, the system administrator is free to choose how individual service\-providing applications will authenticate users. This dynamic configuration is set by the contents of the single
+\fILinux\-PAM\fR
configuration file
-.BR /etc/pam.conf "."
-Alternatively, the configuration can be set by individual
-configuration files located in the
-.B /etc/pam.d/
+\fI/etc/pam.conf\fR. Alternatively, the configuration can be set by individual configuration files located in the
+\fI/etc/pam.d/\fR
directory.
-.IB "The presence of this directory will cause " Linux-PAM " to ignore"
-.BI /etc/pam.conf "."
-
-.sp
-From the point of view of the system administrator, for whom this
-manual is provided, it is not of primary importance to understand the
-internal behavior of the
-.BR Linux-PAM
-library. The important point to recognize is that the configuration
-file(s)
-.I define
+\fIThe presence of this directory will cause \fR\fILinux\-PAM\fR\fI to ignore\fR\fI/etc/pam.conf\fR.
+.PP
+From the point of view of the system administrator, for whom this manual is provided, it is not of primary importance to understand the internal behavior of the
+\fILinux\-PAM\fR
+library. The important point to recognize is that the configuration file(s)
+\fIdefine\fR
the connection between applications
-.BR "" "(" services ")"
-and the pluggable authentication modules
-.BR "" "(" PAM "s)"
-that perform the actual authentication tasks.
-
-.sp
-.BR Linux-PAM
+(\fIservices\fR) and the pluggable authentication modules
+(\fIPAM\fRs) that perform the actual authentication tasks.
+.PP
+\fILinux\-PAM\fR
separates the tasks of
-.I authentication
+\fIauthentication\fR
into four independent management groups:
-.BR "account" " management; "
-.BR "auth" "entication management; "
-.BR "password" " management; "
-and
-.BR "session" " management."
-(We highlight the abbreviations used for these groups in the
-configuration file.)
-
-.sp
-Simply put, these groups take care of different aspects of a typical
-user's request for a restricted service:
-
-.sp
-.BR account " - "
-provide account verification types of service: has the user's password
-expired?; is this user permitted access to the requested service?
-
-.br
-.BR auth "entication - "
-authenticate a user and set up user credentials. Typically this is via
-some challenge-response request that the user must satisfy: if you are
-who you claim to be please enter your password. Not all authentications
-are of this type, there exist hardware based authentication schemes
-(such as the use of smart-cards and biometric devices), with suitable
-modules, these may be substituted seamlessly for more standard
-approaches to authentication - such is the flexibility of
-.BR Linux-PAM "."
-
-.br
-.BR password " - "
-this group's responsibility is the task of updating authentication
-mechanisms. Typically, such services are strongly coupled to those of
-the
-.BR auth
-group. Some authentication mechanisms lend themselves well to being
-updated with such a function. Standard UN*X password-based access is
-the obvious example: please enter a replacement password.
-
-.br
-.BR session " - "
-this group of tasks cover things that should be done prior to a
-service being given and after it is withdrawn. Such tasks include the
-maintenance of audit trails and the mounting of the user's home
-directory. The
-.BR session
-management group is important as it provides both an opening and
-closing hook for modules to affect the services available to a user.
-
-.SH The configuration file(s)
-
+\fIaccount\fR
+management;
+\fIauth\fRentication management;
+\fIpassword\fR
+management; and
+\fIsession\fR
+management. (We highlight the abbreviations used for these groups in the configuration file.)
+.PP
+Simply put, these groups take care of different aspects of a typical user's request for a restricted service:
+.PP
+\fIaccount\fR
+\- provide account verification types of service: has the user's password expired?; is this user permitted access to the requested service?
+.PP
+\fIauth\fRentication \- authenticate a user and set up user credentials. Typically this is via some challenge\-response request that the user must satisfy: if you are who you claim to be please enter your password. Not all authentications are of this type, there exist hardware based authentication schemes (such as the use of smart\-cards and biometric devices), with suitable modules, these may be substituted seamlessly for more standard approaches to authentication \- such is the flexibility of
+\fILinux\-PAM\fR.
+.PP
+\fIpassword\fR
+\- this group's responsibility is the task of updating authentication mechanisms. Typically, such services are strongly coupled to those of the
+\fIauth\fR
+group. Some authentication mechanisms lend themselves well to being updated with such a function. Standard UN*X password\-based access is the obvious example: please enter a replacement password.
+.PP
+\fIsession\fR
+\- this group of tasks cover things that should be done prior to a service being given and after it is withdrawn. Such tasks include the maintenance of audit trails and the mounting of the user's home directory. The
+\fIsession\fR
+management group is important as it provides both an opening and closing hook for modules to affect the services available to a user.
+.SH "THE CONFIGURATION FILE(S)"
+.PP
When a
-.BR Linux-PAM
-aware privilege granting application is started, it activates its
-attachment to the PAM-API. This activation performs a number of
-tasks, the most important being the reading of the configuration file(s):
-.BR /etc/pam.conf "."
-Alternatively, this may be the contents of the
-.BR /etc/pam.d/
+\fILinux\-PAM\fR
+aware privilege granting application is started, it activates its attachment to the PAM\-API. This activation performs a number of tasks, the most important being the reading of the configuration file(s):
+\fI/etc/pam.conf\fR. Alternatively, this may be the contents of the
+\fI/etc/pam.d/\fR
directory.
-
+.PP
These files list the
-.BR PAM "s"
-that will do the authentication tasks required by this service, and
-the appropriate behavior of the PAM-API in the event that individual
-.BR PAM "s "
-fail.
-
-.sp
+\fIPAM\fRs that will do the authentication tasks required by this service, and the appropriate behavior of the PAM\-API in the event that individual
+\fIPAM\fRs fail.
+.PP
The syntax of the
-.B /etc/pam.conf
-configuration file is as follows. The file is made
-up of a list of rules, each rule is typically placed on a single line,
-but may be extended with an escaped end of line: `\\<LF>'. Comments
-are preceded with `#' marks and extend to the next end of line.
-
-.sp
-The format of each rule is a space separated collection of tokens, the
-first three being case-insensitive:
-
-.sp
-.br
-.BR " service type control module-path module-arguments"
-
-.sp
+\fI/etc/pam.conf\fR
+configuration file is as follows. The file is made up of a list of rules, each rule is typically placed on a single line, but may be extended with an escaped end of line: `\\<LF>'. Comments are preceded with `#' marks and extend to the next end of line.
+.PP
+The format of each rule is a space separated collection of tokens, the first three being case\-insensitive:
+.PP
+\fI service type control module\-path module\-arguments\fR
+.PP
The syntax of files contained in the
-.B /etc/pam.d/
+\fI/etc/pam.d/\fR
directory, are identical except for the absence of any
-.I service
+\fIservice\fR
field. In this case, the
-.I service
+\fIservice\fR
is the name of the file in the
-.B /etc/pam.d/
+\fI/etc/pam.d/\fR
directory. This filename must be in lower case.
-
-.sp
+.PP
An important feature of
-.BR Linux-PAM ", "
-is that a number of rules may be
-.I stacked
-to combine the services of a number of PAMs for a given authentication
-task.
-
-.sp
+\fILinux\-PAM\fR, is that a number of rules may be
+\fIstacked\fR
+to combine the services of a number of PAMs for a given authentication task.
+.PP
The
-.BR service
+\fIservice\fR
is typically the familiar name of the corresponding application:
-.BR login
+\fIlogin\fR
and
-.BR su
+\fIsu\fR
are good examples. The
-.BR service "-name, " other ", "
-is reserved for giving
-.I default
-rules. Only lines that mention the current service (or in the absence
-of such, the
-.BR other
-entries) will be associated with the given service-application.
-
-.sp
+\fIservice\fR\-name,
+\fIother\fR, is reserved for giving
+\fIdefault\fR
+rules. Only lines that mention the current service (or in the absence of such, the
+\fIother\fR
+entries) will be associated with the given service\-application.
+.PP
The
-.BR type
-is the management group that the rule corresponds to. It is used to
-specify which of the management groups the subsequent module is to
-be associated with. Valid entries are:
-.BR account "; "
-.BR auth "; "
-.BR password "; "
-and
-.BR session "."
-The meaning of each of these tokens was explained above.
-
-.sp
+\fItype\fR
+is the management group that the rule corresponds to. It is used to specify which of the management groups the subsequent module is to be associated with. Valid entries are:
+\fIaccount\fR;
+\fIauth\fR;
+\fIpassword\fR; and
+\fIsession\fR. The meaning of each of these tokens was explained above.
+.PP
The third field,
-.BR control ", "
-indicates the behavior of the PAM-API should the module fail to
-succeed in its authentication task. There are two types of syntax for
-this control field: the simple one has a single simple keyword; the
-more complicated one involves a square-bracketed selection of
-.B value=action
+\fIcontrol\fR, indicates the behavior of the PAM\-API should the module fail to succeed in its authentication task. There are two types of syntax for this control field: the simple one has a single simple keyword; the more complicated one involves a square\-bracketed selection of
+\fIvalue=action\fR
pairs.
-
-.sp
+.PP
For the simple (historical) syntax valid
-.BR control
+\fIcontrol\fR
values are:
-.BR requisite
-- failure of such a PAM results in the immediate termination of the
-authentication process;
-.BR required
-- failure of such a PAM will ultimately lead to the PAM-API returning
-failure but only after the remaining
-.I stacked
+\fIrequisite\fR
+\- failure of such a PAM results in the immediate termination of the authentication process;
+\fIrequired\fR
+\- failure of such a PAM will ultimately lead to the PAM\-API returning failure but only after the remaining
+\fIstacked\fR
modules (for this
-.BR service
+\fIservice\fR
and
-.BR type ")"
-have been invoked;
-.BR sufficient
-- success of such a module is enough to satisfy the authentication
-requirements of the stack of modules (if a prior
-.BR required
+\fItype\fR) have been invoked;
+\fIsufficient\fR
+\- success of such a module is enough to satisfy the authentication requirements of the stack of modules (if a prior
+\fIrequired\fR
module has failed the success of this one is
-.IR ignored "); "
-.BR optional
-- the success or failure of this module is only important if it is the
-only module in the stack associated with this
-.BR service "+" type "."
-
-.sp
+\fIignored\fR);
+\fIoptional\fR
+\- the success or failure of this module is only important if it is the only module in the stack associated with this
+\fIservice\fR+\fItype\fR.
+.PP
New control directive first introduced in ALT Linux is
-.BR include
-- include all lines of given type from the configuration
-file specified as an argument to this control.
-
-.sp
+\fIinclude\fR
+\- include all lines of given type from the configuration file specified as an argument to this control.
+.PP
For the more complicated syntax valid
-.B control
+\fIcontrol\fR
values have the following form:
-.sp
-.RB [value1=action1 value2=action2 ...]
-.sp
+.PP
+[value1=action1\fIvalue2=action2\fR...]
+.PP
Where
-.B valueN
-corresponds to the return code from the function invoked in the module
-for which the line is defined. It is selected from one of these:
-.BR success ;
-.BR open_err ;
-.BR symbol_err ;
-.BR service_err ;
-.BR system_err ;
-.BR buf_err ;
-.BR perm_denied ;
-.BR auth_err ;
-.BR cred_insufficient ;
-.BR authinfo_unavail ;
-.BR user_unknown ;
-.BR maxtries ;
-.BR new_authtok_reqd ;
-.BR acct_expired ;
-.BR session_err ;
-.BR cred_unavail ;
-.BR cred_expired ;
-.BR cred_err ;
-.BR no_module_data ;
-.BR conv_err ;
-.BR authtok_err ;
-.BR authtok_recover_err ;
-.BR authtok_lock_busy ;
-.BR authtok_disable_aging ;
-.BR try_again ;
-.BR ignore ;
-.BR abort ;
-.BR authtok_expired ;
-.BR module_unknown ;
-.BR bad_item "; and"
-.BR default .
-The last of these,
-.BR default ,
-implies 'all
-.BR valueN 's
-not mentioned explicitly. Note, the full list of PAM errors is
-available in /usr/include/security/_pam_types.h . The
-.B actionN
+\fIvalueN\fR
+corresponds to the return code from the function invoked in the module for which the line is defined. It is selected from one of these:
+\fIsuccess\fR;
+\fIopen_err\fR;
+\fIsymbol_err\fR;
+\fIservice_err\fR;
+\fIsystem_err\fR;
+\fIbuf_err\fR;
+\fIperm_denied\fR;
+\fIauth_err\fR;
+\fIcred_insufficient\fR;
+\fIauthinfo_unavail\fR;
+\fIuser_unknown\fR;
+\fImaxtries\fR;
+\fInew_authtok_reqd\fR;
+\fIacct_expired\fR;
+\fIsession_err\fR;
+\fIcred_unavail\fR;
+\fIcred_expired\fR;
+\fIcred_err\fR;
+\fIno_module_data\fR;
+\fIconv_err\fR;
+\fIauthtok_err\fR;
+\fIauthtok_recover_err\fR;
+\fIauthtok_lock_busy\fR;
+\fIauthtok_disable_aging\fR;
+\fItry_again\fR;
+\fIignore\fR;
+\fIabort\fR;
+\fIauthtok_expired\fR;
+\fImodule_unknown\fR;
+\fIbad_item\fR; and
+\fIdefault\fR. The last of these,
+\fIdefault\fR, implies 'all
+\fIvalueN\fR's not mentioned explicitly. Note, the full list of PAM errors is available in /usr/include/security/_pam_types.h . The
+\fIactionN\fR
can be: an unsigned integer,
-.BR J ,
-signifying an action of 'jump over the next J modules in the stack';
-or take one of the following forms:
-.br
-.B ignore
-- when used with a stack of modules, the module's return status will
-not contribute to the return code the application obtains;
-.br
-.B bad
-- this action indicates that the return code should be thought of as
-indicative of the module failing. If this module is the first in the
-stack to fail, its status value will be used for that of the whole
-stack.
-.br
-.B die
-- equivalent to bad with the side effect of terminating the module
-stack and PAM immediately returning to the application.
-.br
-.B ok
-- this tells PAM that the administrator thinks this return code
-should contribute directly to the return code of the full stack of
-modules. In other words, if the former state of the stack would lead
-to a return of
-.BR PAM_SUCCESS ,
-the module's return code will override this value. Note, if the former
-state of the stack holds some value that is indicative of a modules
-failure, this 'ok' value will not be used to override that value.
-.br
-.B done
-- equivalent to ok with the side effect of terminating the module
-stack and PAM immediately returning to the application.
-.br
-.B reset
-- clear all memory of the state of the module stack and start again
-with the next stacked module.
-
-.sp
-.BR module-path
-- this is either the full filename of the PAM to be used by the
-application (it begins with a '/'), or a relative pathname from the
-default module location:
-.BR /lib/security/ .
-
-.sp
-.BR module-arguments
-- these are a space separated list of tokens that can be used to
-modify the specific behavior of the given PAM. Such arguments will be
-documented for each individual module.
-
+\fIJ\fR, signifying an action of 'jump over the next J modules in the stack'; or take one of the following forms:\fIignore\fR
+\- when used with a stack of modules, the module's return status will not contribute to the return code the application obtains;\fIbad\fR
+\- this action indicates that the return code should be thought of as indicative of the module failing. If this module is the first in the stack to fail, its status value will be used for that of the whole stack.\fIdie\fR
+\- equivalent to bad with the side effect of terminating the module stack and PAM immediately returning to the application.\fIok\fR
+\- this tells PAM that the administrator thinks this return code should contribute directly to the return code of the full stack of modules. In other words, if the former state of the stack would lead to a return of
+\fIPAM_SUCCESS\fR, the module's return code will override this value. Note, if the former state of the stack holds some value that is indicative of a modules failure, this 'ok' value will not be used to override that value.\fIdone\fR
+\- equivalent to ok with the side effect of terminating the module stack and PAM immediately returning to the application.\fIreset\fR
+\- clear all memory of the state of the module stack and start again with the next stacked module.
+.PP
+\fImodule\-path\fR
+\- this is either the full filename of the PAM to be used by the application (it begins with a '/'), or a relative pathname from the default module location:
+\fI/lib/security/\fR.
+.PP
+\fImodule\-arguments\fR
+\- these are a space separated list of tokens that can be used to modify the specific behavior of the given PAM. Such arguments will be documented for each individual module.
.SH "FILES"
-.BR /etc/pam.conf " - the configuration file"
-.br
-.BR /etc/pam.d/ " - the"
-.BR Linux-PAM
+.PP
+\fI/etc/pam.conf\fR
+\- the configuration file\fI/etc/pam.d/\fR
+\- the
+\fILinux\-PAM\fR
configuration directory. Generally, if this directory is present, the
-.B /etc/pam.conf
-file is ignored.
-.br
-.BR /lib/libpam.so.X " - the dynamic library"
-.br
-.BR /lib/security/*.so " - the PAMs
-
-.SH ERRORS
+\fI/etc/pam.conf\fR
+file is ignored.\fI/lib/libpam.so.X\fR
+\- the dynamic library\fI/lib/security/*.so\fR
+\- the PAMs
+.SH "ERRORS"
+.PP
Typically errors generated by the
-.BR Linux-PAM
+\fILinux\-PAM\fR
system of libraries, will be written to
-.BR syslog "(3)."
-
+\fBsyslog\fR(3).
.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-.br
-Contains additional features, but remains backwardly compatible with
-this RFC.
-
-.SH BUGS
-.sp 2
+.PP
+DCE\-RFC 86.0, October 1995.Contains additional features, but remains backwardly compatible with this RFC.
+.SH "BUGS"
+.PP
None known.
-
.SH "SEE ALSO"
-
+.PP
The three
-.BR Linux-PAM
+\fILinux\-PAM\fR
Guides, for
-.BR "system administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+\fIsystem administrators\fR,
+\fImodule developers\fR, and
+\fIapplication developers\fR.
diff --git a/doc/man/pam.8.xml b/doc/man/pam.8.xml
new file mode 100644
index 00000000..e8a78234
--- /dev/null
+++ b/doc/man/pam.8.xml
@@ -0,0 +1,392 @@
+<?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'>
+<refmeta>
+<refentrytitle>pam</refentrytitle>
+<manvolnum>8</manvolnum>
+<refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>pam</refname>
+<refpurpose>Pluggable Authentication Modules for Linux</refpurpose>
+</refnamediv>
+<!-- body begins here -->
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+<para>This manual is intended to offer a quick introduction to
+<emphasis remap='B'>Linux-PAM</emphasis>.
+For more information the reader is directed to the
+<emphasis remap='B'>Linux-PAM system administrators' guide</emphasis>.</para>
+
+
+<para><emphasis remap='B'>Linux-PAM</emphasis>
+Is a system of libraries that handle the authentication tasks of
+applications (services) on the system. The library provides a stable
+general interface (Application Programming Interface - API) that
+privilege granting programs (such as
+<citerefentry><refentrytitle>login</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+and
+<citerefentry><refentrytitle>su</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
+defer to to perform standard authentication tasks.</para>
+
+
+<para>The principal feature of the PAM approach is that the nature of the
+authentication is dynamically configurable. In other words, the
+system administrator is free to choose how individual
+service-providing applications will authenticate users. This dynamic
+configuration is set by the contents of the single
+<emphasis remap='B'>Linux-PAM</emphasis>
+configuration file
+<filename>/etc/pam.conf</filename>.
+Alternatively, the configuration can be set by individual
+configuration files located in the
+<filename>/etc/pam.d/</filename>
+directory.
+<emphasis remap='I'>The presence of this directory will cause </emphasis><emphasis remap='B'>Linux-PAM</emphasis><emphasis remap='I'> to ignore</emphasis>
+<filename>/etc/pam.conf</filename><literal>.</literal></para>
+
+
+<para>From the point of view of the system administrator, for whom this
+manual is provided, it is not of primary importance to understand the
+internal behavior of the
+<emphasis remap='B'>Linux-PAM</emphasis>
+library. The important point to recognize is that the configuration
+file(s)
+<emphasis remap='I'>define</emphasis>
+the connection between applications
+<emphasis remap='B'></emphasis>(<emphasis remap='B'>services</emphasis>)
+and the pluggable authentication modules
+<emphasis remap='B'></emphasis>(<emphasis remap='B'>PAM</emphasis>s)
+that perform the actual authentication tasks.</para>
+
+
+<para><emphasis remap='B'>Linux-PAM</emphasis>
+separates the tasks of
+<emphasis remap='I'>authentication</emphasis>
+into four independent management groups:
+<emphasis remap='B'>account</emphasis> management;
+<emphasis remap='B'>auth</emphasis>entication management;
+<emphasis remap='B'>password</emphasis> management;
+and
+<emphasis remap='B'>session</emphasis> management.
+(We highlight the abbreviations used for these groups in the
+configuration file.)</para>
+
+
+<para>Simply put, these groups take care of different aspects of a typical
+user's request for a restricted service:</para>
+
+
+<para><emphasis remap='B'>account</emphasis> -
+provide account verification types of service: has the user's password
+expired?; is this user permitted access to the requested service?</para>
+
+<!-- .br -->
+<para><emphasis remap='B'>auth</emphasis>entication -
+authenticate a user and set up user credentials. Typically this is via
+some challenge-response request that the user must satisfy: if you are
+who you claim to be please enter your password. Not all authentications
+are of this type, there exist hardware based authentication schemes
+(such as the use of smart-cards and biometric devices), with suitable
+modules, these may be substituted seamlessly for more standard
+approaches to authentication - such is the flexibility of
+<emphasis remap='B'>Linux-PAM</emphasis>.</para>
+
+<!-- .br -->
+<para><emphasis remap='B'>password</emphasis> -
+this group's responsibility is the task of updating authentication
+mechanisms. Typically, such services are strongly coupled to those of
+the
+<emphasis remap='B'>auth</emphasis>
+group. Some authentication mechanisms lend themselves well to being
+updated with such a function. Standard UN*X password-based access is
+the obvious example: please enter a replacement password.</para>
+
+<!-- .br -->
+<para><emphasis remap='B'>session</emphasis> -
+this group of tasks cover things that should be done prior to a
+service being given and after it is withdrawn. Such tasks include the
+maintenance of audit trails and the mounting of the user's home
+directory. The
+<emphasis remap='B'>session</emphasis>
+management group is important as it provides both an opening and
+closing hook for modules to affect the services available to a user.</para>
+
+</refsect1>
+
+<refsect1 id='the_configuration_files'><title>The configuration file(s)</title>
+<para>When a
+<emphasis remap='B'>Linux-PAM</emphasis>
+aware privilege granting application is started, it activates its
+attachment to the PAM-API. This activation performs a number of
+tasks, the most important being the reading of the configuration file(s):
+<filename>/etc/pam.conf</filename>.
+Alternatively, this may be the contents of the
+<filename>/etc/pam.d/</filename>
+directory.</para>
+
+<para>These files list the
+<emphasis remap='B'>PAM</emphasis>s
+that will do the authentication tasks required by this service, and
+the appropriate behavior of the PAM-API in the event that individual
+<emphasis remap='B'>PAM</emphasis>s
+fail.</para>
+
+
+<para>The syntax of the
+<filename>/etc/pam.conf</filename>
+configuration file is as follows. The file is made
+up of a list of rules, each rule is typically placed on a single line,
+but may be extended with an escaped end of line: `\&lt;LF&gt;'. Comments
+are preceded with `#' marks and extend to the next end of line.</para>
+
+
+<para>The format of each rule is a space separated collection of tokens, the
+first three being case-insensitive:</para>
+
+
+<!-- .br -->
+<para><emphasis remap='B'> service type control module-path module-arguments</emphasis></para>
+
+
+<para>The syntax of files contained in the
+<filename>/etc/pam.d/</filename>
+directory, are identical except for the absence of any
+<emphasis remap='I'>service</emphasis>
+field. In this case, the
+<emphasis remap='I'>service</emphasis>
+is the name of the file in the
+<filename>/etc/pam.d/</filename>
+directory. This filename must be in lower case.</para>
+
+
+<para>An important feature of
+<emphasis remap='B'>Linux-PAM</emphasis>,
+is that a number of rules may be
+<emphasis remap='I'>stacked</emphasis>
+to combine the services of a number of PAMs for a given authentication
+task.</para>
+
+
+<para>The
+<emphasis remap='B'>service</emphasis>
+is typically the familiar name of the corresponding application:
+<emphasis remap='B'>login</emphasis>
+and
+<emphasis remap='B'>su</emphasis>
+are good examples. The
+<emphasis remap='B'>service</emphasis>-name, <emphasis remap='B'>other</emphasis>,
+is reserved for giving
+<emphasis remap='I'>default</emphasis>
+rules. Only lines that mention the current service (or in the absence
+of such, the
+<emphasis remap='B'>other</emphasis>
+entries) will be associated with the given service-application.</para>
+
+
+<para>The
+<emphasis remap='B'>type</emphasis>
+is the management group that the rule corresponds to. It is used to
+specify which of the management groups the subsequent module is to
+be associated with. Valid entries are:
+<emphasis remap='B'>account</emphasis>;
+<emphasis remap='B'>auth</emphasis>;
+<emphasis remap='B'>password</emphasis>;
+and
+<emphasis remap='B'>session</emphasis>.
+The meaning of each of these tokens was explained above.</para>
+
+
+<para>The third field,
+<emphasis remap='B'>control</emphasis>,
+indicates the behavior of the PAM-API should the module fail to
+succeed in its authentication task. There are two types of syntax for
+this control field: the simple one has a single simple keyword; the
+more complicated one involves a square-bracketed selection of
+<emphasis remap='B'>value=action</emphasis>
+pairs.</para>
+
+
+<para>For the simple (historical) syntax valid
+<emphasis remap='B'>control</emphasis>
+values are:
+<emphasis remap='B'>requisite</emphasis>
+- failure of such a PAM results in the immediate termination of the
+authentication process;
+<emphasis remap='B'>required</emphasis>
+- failure of such a PAM will ultimately lead to the PAM-API returning
+failure but only after the remaining
+<emphasis remap='I'>stacked</emphasis>
+modules (for this
+<emphasis remap='B'>service</emphasis>
+and
+<emphasis remap='B'>type</emphasis>)
+have been invoked;
+<emphasis remap='B'>sufficient</emphasis>
+- success of such a module is enough to satisfy the authentication
+requirements of the stack of modules (if a prior
+<emphasis remap='B'>required</emphasis>
+module has failed the success of this one is
+<emphasis remap='I'>ignored</emphasis>);
+<emphasis remap='B'>optional</emphasis>
+- the success or failure of this module is only important if it is the
+only module in the stack associated with this
+<emphasis remap='B'>service</emphasis>+<emphasis remap='B'>type</emphasis>.</para>
+
+
+<para>New control directive first introduced in ALT Linux is
+<emphasis remap='B'>include</emphasis>
+- include all lines of given type from the configuration
+file specified as an argument to this control.</para>
+
+
+<para>For the more complicated syntax valid
+<emphasis remap='B'>control</emphasis>
+values have the following form:</para>
+
+<para>[value1=action1<emphasis remap='B'>value2=action2</emphasis>...]</para>
+
+<para>Where
+<emphasis remap='B'>valueN</emphasis>
+corresponds to the return code from the function invoked in the module
+for which the line is defined. It is selected from one of these:
+<emphasis remap='B'>success</emphasis>;
+<emphasis remap='B'>open_err</emphasis>;
+<emphasis remap='B'>symbol_err</emphasis>;
+<emphasis remap='B'>service_err</emphasis>;
+<emphasis remap='B'>system_err</emphasis>;
+<emphasis remap='B'>buf_err</emphasis>;
+<emphasis remap='B'>perm_denied</emphasis>;
+<emphasis remap='B'>auth_err</emphasis>;
+<emphasis remap='B'>cred_insufficient</emphasis>;
+<emphasis remap='B'>authinfo_unavail</emphasis>;
+<emphasis remap='B'>user_unknown</emphasis>;
+<emphasis remap='B'>maxtries</emphasis>;
+<emphasis remap='B'>new_authtok_reqd</emphasis>;
+<emphasis remap='B'>acct_expired</emphasis>;
+<emphasis remap='B'>session_err</emphasis>;
+<emphasis remap='B'>cred_unavail</emphasis>;
+<emphasis remap='B'>cred_expired</emphasis>;
+<emphasis remap='B'>cred_err</emphasis>;
+<emphasis remap='B'>no_module_data</emphasis>;
+<emphasis remap='B'>conv_err</emphasis>;
+<emphasis remap='B'>authtok_err</emphasis>;
+<emphasis remap='B'>authtok_recover_err</emphasis>;
+<emphasis remap='B'>authtok_lock_busy</emphasis>;
+<emphasis remap='B'>authtok_disable_aging</emphasis>;
+<emphasis remap='B'>try_again</emphasis>;
+<emphasis remap='B'>ignore</emphasis>;
+<emphasis remap='B'>abort</emphasis>;
+<emphasis remap='B'>authtok_expired</emphasis>;
+<emphasis remap='B'>module_unknown</emphasis>;
+<emphasis remap='B'>bad_item</emphasis>; and
+<emphasis remap='B'>default</emphasis>.
+The last of these,
+<emphasis remap='B'>default</emphasis>,
+implies 'all
+<emphasis remap='B'>valueN</emphasis>'s
+not mentioned explicitly. Note, the full list of PAM errors is
+available in /usr/include/security/_pam_types.h . The
+<emphasis remap='B'>actionN</emphasis>
+can be: an unsigned integer,
+<emphasis remap='B'>J</emphasis>,
+signifying an action of 'jump over the next J modules in the stack';
+or take one of the following forms:
+<!-- .br -->
+<emphasis remap='B'>ignore</emphasis>
+- when used with a stack of modules, the module's return status will
+not contribute to the return code the application obtains;
+<!-- .br -->
+<emphasis remap='B'>bad</emphasis>
+- this action indicates that the return code should be thought of as
+indicative of the module failing. If this module is the first in the
+stack to fail, its status value will be used for that of the whole
+stack.
+<!-- .br -->
+<emphasis remap='B'>die</emphasis>
+- equivalent to bad with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+<!-- .br -->
+<emphasis remap='B'>ok</emphasis>
+- this tells PAM that the administrator thinks this return code
+should contribute directly to the return code of the full stack of
+modules. In other words, if the former state of the stack would lead
+to a return of
+<emphasis remap='B'>PAM_SUCCESS</emphasis>,
+the module's return code will override this value. Note, if the former
+state of the stack holds some value that is indicative of a modules
+failure, this 'ok' value will not be used to override that value.
+<!-- .br -->
+<emphasis remap='B'>done</emphasis>
+- equivalent to ok with the side effect of terminating the module
+stack and PAM immediately returning to the application.
+<!-- .br -->
+<emphasis remap='B'>reset</emphasis>
+- clear all memory of the state of the module stack and start again
+with the next stacked module.</para>
+
+
+<para><emphasis remap='B'>module-path</emphasis>
+- this is either the full filename of the PAM to be used by the
+application (it begins with a '/'), or a relative pathname from the
+default module location:
+<filename>/lib/security/</filename>.</para>
+
+
+<para><emphasis remap='B'>module-arguments</emphasis>
+- these are a space separated list of tokens that can be used to
+modify the specific behavior of the given PAM. Such arguments will be
+documented for each individual module.</para>
+
+</refsect1>
+
+<refsect1 id='files'><title>FILES</title>
+<para><filename>/etc/pam.conf</filename> - the configuration file
+<!-- .br -->
+<filename>/etc/pam.d/</filename> - the
+<emphasis remap='B'>Linux-PAM</emphasis>
+configuration directory. Generally, if this directory is present, the
+<filename>/etc/pam.conf</filename>
+file is ignored.
+<!-- .br -->
+<filename>/lib/libpam.so.X</filename> - the dynamic library
+<!-- .br -->
+<filename>/lib/security/*.so</filename> - the PAMs</para>
+
+</refsect1>
+
+<refsect1 id='errors'><title>ERRORS</title>
+<para>Typically errors generated by the
+<emphasis remap='B'>Linux-PAM</emphasis>
+system of libraries, will be written to
+<citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
+
+</refsect1>
+
+<refsect1 id='conforming_to'><title>CONFORMING TO</title>
+<para>DCE-RFC 86.0, October 1995.
+<!-- .br -->
+Contains additional features, but remains backwardly compatible with
+this RFC.</para>
+
+</refsect1>
+
+<refsect1 id='bugs'><title>BUGS</title>
+
+
+<para>None known.</para>
+
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>The three
+<emphasis remap='B'>Linux-PAM</emphasis>
+Guides, for
+<emphasis remap='B'>system administrators</emphasis>,
+<emphasis remap='B'>module developers</emphasis>,
+and
+<emphasis remap='B'>application developers</emphasis>. </para>
+</refsect1>
+</refentry>
+
diff --git a/doc/man/pam_acct_mgmt.3 b/doc/man/pam_acct_mgmt.3
new file mode 100644
index 00000000..6ac39ab1
--- /dev/null
+++ b/doc/man/pam_acct_mgmt.3
@@ -0,0 +1,60 @@
+.\" ** 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_ACCT_MGMT" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_acct_mgmt \- PAM account validation management
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 18
+\fBint\ \fBpam_acct_mgmt\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_acct_mgmt\fR
+function is used to determine if the users account is valid. It checks for authentication token and account expiration and verifies access restrictions. It is typically called after the user has been authenticated.
+.PP
+The
+\fIpamh\fR
+argument is an authentication handle obtained by a prior call to pam_start(). The flags argument is the binary or of zero or more of the following values:
+.TP
+PAM_SILENT
+Do not emit any messages.
+.TP
+PAM_DISALLOW_NULL_AUTHTOK
+The PAM module service should return PAM_NEW_AUTHTOK_REQD if the user has a null authentication token.
+.SH "RETURN VALUES"
+.TP
+PAM_ACCT_EXPIRED
+User account has expired.
+.TP
+PAM_AUTH_ERR
+Authentication failure.
+.TP
+PAM_NEW_AUTHTOK_REQD
+The user account is valid but their authentication token is
+\fIexpired\fR. The correct response to this return\-value is to require that the user satisfies the
+\fBpam_chauthtok()\fR
+function before obtaining service. It may not be possible for some applications to do this. In such cases, the user should be denied access until such time as they can update their password.
+.TP
+PAM_PERM_DENIED
+Permission denied.
+.TP
+PAM_SUCCESS
+The authentication token was successfully updated.
+.TP
+PAM_USER_UNKNOWN
+User unknown to password service.
+.SH "SEE ALSO"
+.PP
+\fBpam_start\fR(3),
+\fBpam_authenticate\fR(3),
+\fBpam_chauthtok\fR(3),
+\fBpam_strerror\fR(3),
+\fBpam\fR(8)
diff --git a/doc/man/pam_acct_mgmt.3.xml b/doc/man/pam_acct_mgmt.3.xml
new file mode 100644
index 00000000..e1f6492f
--- /dev/null
+++ b/doc/man/pam_acct_mgmt.3.xml
@@ -0,0 +1,145 @@
+<?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_acct_mgmt'>
+ <refmeta>
+ <refentrytitle>pam_acct_mgmt</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_acct_mgmt-name">
+ <refname>pam_acct_mgmt</refname>
+ <refpurpose>PAM account validation management</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id='pam_acct_mgmt-synopsis'>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_acct_mgmt</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id='pam_acct_mgmt-description'>
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_acct_mgmt</function> function is used to determine
+ if the users account is valid. It checks for authentication token
+ and account expiration and verifies access restrictions. It is
+ typically called after the user has been authenticated.
+ </para>
+ <para>
+ The <emphasis>pamh</emphasis> argument is an authentication
+ handle obtained by a prior call to pam_start().
+ The flags argument is the binary or of zero or more of the
+ following values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SILENT</term>
+ <listitem>
+ <para>
+ Do not emit any messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_DISALLOW_NULL_AUTHTOK</term>
+ <listitem>
+ <para>
+ The PAM module service should return PAM_NEW_AUTHTOK_REQD
+ if the user has a null authentication token.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_start-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_ACCT_EXPIRED</term>
+ <listitem>
+ <para>
+ User account has expired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_AUTH_ERR</term>
+ <listitem>
+ <para>
+ Authentication failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_NEW_AUTHTOK_REQD</term>
+ <listitem>
+ <para>
+ The user account is valid but their authentication token
+ is <emphasis>expired</emphasis>. The correct response to
+ this return-value is to require that the user satisfies
+ the <function>pam_chauthtok()</function> function before
+ obtaining service. It may not be possible for some
+ applications to do this. In such cases, the user should be
+ denied access until such time as they can update their password.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_PERM_DENIED</term>
+ <listitem>
+ <para>
+ Permission denied.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ The authentication token was successfully updated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_USER_UNKNOWN</term>
+ <listitem>
+ <para>
+ User unknown to password service.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id='pam_acct_mgmt-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_authenticate.3 b/doc/man/pam_authenticate.3
index ba1bc52e..b0385a39 100644
--- a/doc/man/pam_authenticate.3
+++ b/doc/man/pam_authenticate.3
@@ -1,91 +1,68 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
-.TH PAM_AUTHENTICATE 3 "1996 Dec 9" "Linux-PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_authenticate \- authenticate a user
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_authenticate(pam_handle_t " *pamh ", int " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_authenticate
-
-.br
-Use this function to authenticate an applicant user. It is linked
-.I dynamically
-to the authentication modules by
-.BR Linux-PAM ". "
-It is the task of these module to perform such an authentication. The
-specific nature of the authentication is not the concern of the
-application.
-
-.br
-Following successful completion, the
-.BR name
-of the authenticated user will be present in the
-.BR Linux-PAM
-item
-.BR PAM_USER ". "
-This item may be recovered with a call to
-.BR pam_get_item "(3)."
-
-.br
-The application developer should note that the modules may request
-that the user enter their username via the conversation mechanism (see
-.BR pam_start "(3))."
-Should this be the case, the user-prompt string can be set via
-the
-.BR PAM_USER_PROMPT
-item (see
-.BR pam_set_item "(3))."
-
-.SH "RETURN VALUE"
-On success
-.BR PAM_SUCCESS
-is returned. All other returns should be considered
-authentication failures and will be
-.I delayed
-by an amount specified with prior calls to
-.BR pam_fail_delay "(3). "
-Specific failures that demand special attention are the following:
+.\" ** 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_AUTHENTICATE" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_authenticate \- account authentication
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 21
+\fBint\ \fBpam_authenticate\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_authenticate\fR
+function is used to authenticate the user. The user is required to provide an authentication token depending upon the authentication service, usually this is a password, but could also be a finger print.
+.PP
+The PAM service module may request that the user enter their username vio the the conversation mechanism (see
+\fBpam_start\fR(3)
+and
+\fBpam_conv\fR(3)). The name of the authenticated user will be present in the PAM item PAM_USER. This item may be recovered with a call to
+\fBpam_get_item\fR(3).
+.PP
+The
+\fIpamh\fR
+argument is an authentication handle obtained by a prior call to pam_start(). The flags argument is the binary or of zero or more of the following values:
+.TP
+PAM_SILENT
+Do not emit any messages.
+.TP
+PAM_DISALLOW_NULL_AUTHTOK
+The PAM module service should return PAM_AUTH_ERR if the user does not have a registered authentication token.
+.SH "RETURN VALUES"
+.TP
+PAM_ABORT
+The application should exit immediately after calling
+\fBpam_end\fR(3)
+first.
+.TP
+PAM_AUTH_ERR
+The user was not authenticated.
.TP
-.B PAM_ABORT
-the application should exit immediately. Of course,
-.BR pam_end "(3)"
-should be called first.
-
+PAM_CRED_INSUFFICIENT
+For some reason the application does not have sufficient credentials to authenticate the user.
.TP
-.B PAM_MAXTRIES
-the application has tried too many times to authenticate the
-user, authentication should not be attempted again.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
+PAM_AUTHINFO_UNVAIL
+The modules were not able to access the authentication information. This might be due to a network or hardware failure etc.
+.TP
+PAM_MAXTRIES
+One or more of the authentication modules has reached its limit of tries authenticating the user. Do not try again.
+.TP
+PAM_SUCCESS
+The user was successfully authenticated.
+.TP
+PAM_USER_UNKNOWN
+User unknown to authentication service.
.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_get_item "(3) "
-.BR pam_fail_delay "(3) "
-and
-.BR pam_strerror "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+.PP
+\fBpam_start\fR(3),
+\fBpam_setcred\fR(3),
+\fBpam_chauthtok\fR(3),
+\fBpam_strerror\fR(3),
+\fBpam\fR(8)
diff --git a/doc/man/pam_authenticate.3.xml b/doc/man/pam_authenticate.3.xml
new file mode 100644
index 00000000..c5ed777b
--- /dev/null
+++ b/doc/man/pam_authenticate.3.xml
@@ -0,0 +1,169 @@
+<?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_authenticate'>
+ <refmeta>
+ <refentrytitle>pam_authenticate</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_authenticate-name">
+ <refname>pam_authenticate</refname>
+ <refpurpose>account authentication</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id='pam_authenticate-synopsis'>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_authenticate</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id='pam_authenticate-description'>
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_authenticate</function> function is used to
+ authenticate the user. The user is required to provide an
+ authentication token depending upon the authentication service,
+ usually this is a password, but could also be a finger print.
+ </para>
+ <para>
+ The PAM service module may request that the user enter their
+ username vio the the conversation mechanism (see
+ <citerefentry>
+ <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>). The name of the authenticated user
+ will be present in the PAM item PAM_USER. This item may be
+ recovered with a call to
+ <citerefentry>
+ <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ <para>
+ The <emphasis>pamh</emphasis> argument is an authentication
+ handle obtained by a prior call to pam_start().
+ The flags argument is the binary or of zero or more of the
+ following values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SILENT</term>
+ <listitem>
+ <para>
+ Do not emit any messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_DISALLOW_NULL_AUTHTOK</term>
+ <listitem>
+ <para>
+ The PAM module service should return PAM_AUTH_ERR
+ if the user does not have a registered authentication token.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_start-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_ABORT</term>
+ <listitem>
+ <para>
+ The application should exit immediately after calling
+ <citerefentry>
+ <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> first.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_AUTH_ERR</term>
+ <listitem>
+ <para>
+ The user was not authenticated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_CRED_INSUFFICIENT</term>
+ <listitem>
+ <para>
+ For some reason the application does not have sufficient
+ credentials to authenticate the user.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_AUTHINFO_UNVAIL</term>
+ <listitem>
+ <para>
+ The modules were not able to access the authentication
+ information. This might be due to a network or hardware
+ failure etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_MAXTRIES</term>
+ <listitem>
+ <para>
+ One or more of the authentication modules has reached its
+ limit of tries authenticating the user. Do not try again.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ The user was successfully authenticated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_USER_UNKNOWN</term>
+ <listitem>
+ <para>
+ User unknown to authentication service.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id='pam_authenticate-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_chauthtok.3 b/doc/man/pam_chauthtok.3
index 63904da3..8264da14 100644
--- a/doc/man/pam_chauthtok.3
+++ b/doc/man/pam_chauthtok.3
@@ -1,101 +1,65 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_CHAUTHTOK 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
+.\" ** 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_CHAUTHTOK" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
pam_chauthtok \- updating authentication tokens
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_chauthtok(pam_handle_t " *pamh ", int " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_chauthtok
-
-.br
-Use this function to rejuvenate the authentication tokens (passwords
-etc.) of an applicant user.
-
-.br
-Note, the application should not pre-authenticate the user, as this is
-performed (if required) by the
-.BR Linux-PAM
-framework.
-
-.br
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 18
+\fBint\ \fBpam_chauthtok\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
The
-.I flags
-argument can
-.I optionally
-take the value,
-.BR PAM_CHANGE_EXPIRED_AUTHTOK "."
-In such cases the framework is only required to update those
-authentication tokens that have expired. Without this argument, the
-framework will attempt to obtain new tokens for all configured
-authentication mechanisms. The details of the types and number of such
-schemes should not concern the calling application.
-
-.SH RETURN VALUE
-A successful return from this function will be indicated with
-.BR PAM_SUCCESS "."
-
-.br
-Specific errors of special interest when calling this function are
-
-.br
-.BR PAM_AUTHTOK_ERROR
-- a valid new token was not obtained
-
-.br
-.BR PAM_AUTHTOK_RECOVERY_ERR
-- old authentication token was not available
-
-.br
-.BR PAM_AUTHTOK_LOCK_BUSY
-- a resource needed to update the token was locked (try again later)
-
-.br
-.BR PAM_AUTHTOK_DISABLE_AGING
-- one or more of the authentication modules does not honor
-authentication token aging
-
-.br
-.BR PAM_TRY_AGAIN
-- one or more authentication mechanism is not prepared to update a
-token at this time
-
-.br
-In general other return values may be returned. They should be treated
-as indicating failure.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
+\fBpam_chauthtok\fR
+function is used to change the authentication token for a given user (as indicated by the state associated with the handle
+\fIpamh\fR.
+.PP
+The
+\fIpamh\fR
+argument is an authentication handle obtained by a prior call to pam_start(). The flags argument is the binary or of zero or more of the following values:
+.TP
+PAM_SILENT
+Do not emit any messages.
+.TP
+PAM_CHANGE_EXPIRED_AUTHTOK
+This argument indicates to the modules that the users authentication token (password) should only be changed if it has expired. If this argument is not passed, the application requires that all authentication tokens are to be changed.
+.SH "RETURN VALUES"
+.TP
+PAM_AUTHTOK_ERR
+A module was unable to obtain the new authentication token.
+.TP
+PAM_AUTHTOK_RECOVERY_ERR
+A module was unable to obtain the old authentication token.
+.TP
+PAM_AUTHTOK_LOCK_BUSY
+One or more of the modules was unable to change the authentication token since it is currently locked.
+.TP
+PAM_AUTHTOK_DISABLE_AGING
+Authentication token aging has been disabled for at least one of the modules.
+.TP
+PAM_PERM_DENIED
+Permission denied.
+.TP
+PAM_SUCCESS
+The authentication token was successfully updated.
+.TP
+PAM_TRY_AGAIN
+Not all of the modules were in a position to update the authentication token(s). In such a case none of the user's authentication tokens are updated.
+.TP
+PAM_USER_UNKNOWN
+User unknown to password service.
.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_authenticate "(3), "
-.BR pam_setcred "(3), "
-.BR pam_get_item "(3), "
-.BR pam_strerror "(3) "
-and
-.BR pam "(8)."
-
-.br
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+.PP
+\fBpam_start\fR(3),
+\fBpam_authenticate\fR(3),
+\fBpam_setcred\fR(3),
+\fBpam_get_item\fR(3),
+\fBpam_strerror\fR(3),
+\fBpam\fR(8)
diff --git a/doc/man/pam_chauthtok.3.xml b/doc/man/pam_chauthtok.3.xml
new file mode 100644
index 00000000..e1bf67d0
--- /dev/null
+++ b/doc/man/pam_chauthtok.3.xml
@@ -0,0 +1,164 @@
+<?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_chauthtok'>
+ <refmeta>
+ <refentrytitle>pam_chauthtok</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_chauthtok-name">
+ <refname>pam_chauthtok</refname>
+ <refpurpose>updating authentication tokens</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id='pam_chauthtok-synopsis'>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_chauthtok</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id='pam_chauthtok-description'>
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_chauthtok</function> function is used to change the
+ authentication token for a given user (as indicated by the state
+ associated with the handle <emphasis>pamh</emphasis>.
+ </para>
+ <para>
+ The <emphasis>pamh</emphasis> argument is an authentication
+ handle obtained by a prior call to pam_start().
+ The flags argument is the binary or of zero or more of the
+ following values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SILENT</term>
+ <listitem>
+ <para>
+ Do not emit any messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_CHANGE_EXPIRED_AUTHTOK</term>
+ <listitem>
+ <para>
+ This argument indicates to the modules that the users
+ authentication token (password) should only be changed
+ if it has expired.
+ If this argument is not passed, the application requires
+ that all authentication tokens are to be changed.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_start-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_AUTHTOK_ERR</term>
+ <listitem>
+ <para>
+ A module was unable to obtain the new authentication token.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_AUTHTOK_RECOVERY_ERR</term>
+ <listitem>
+ <para>
+ A module was unable to obtain the old authentication token.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_AUTHTOK_LOCK_BUSY</term>
+ <listitem>
+ <para>
+ One or more of the modules was unable to change the
+ authentication token since it is currently locked.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_AUTHTOK_DISABLE_AGING</term>
+ <listitem>
+ <para>
+ Authentication token aging has been disabled for at least
+ one of the modules.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_PERM_DENIED</term>
+ <listitem>
+ <para>
+ Permission denied.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ The authentication token was successfully updated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_TRY_AGAIN</term>
+ <listitem>
+ <para>
+ Not all of the modules were in a position to update the
+ authentication token(s). In such a case none of the user's
+ authentication tokens are updated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_USER_UNKNOWN</term>
+ <listitem>
+ <para>
+ User unknown to password service.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id='pam_chauthtok-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_setcred</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_close_session.3 b/doc/man/pam_close_session.3
index c809a0e4..0c10aa32 100644
--- a/doc/man/pam_close_session.3
+++ b/doc/man/pam_close_session.3
@@ -1 +1,47 @@
-.so man3/pam_open_session.3
+.\" ** 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_CLOSE_SESSION" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_close_session \- terminating PAM session management
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 22
+\fBint\ \fBpam_close_session\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_close_session\fR
+function is used to indicate that an authenticated session has ended. The session should have been created with a call to
+\fBpam_open_session\fR(3).
+.PP
+It should be noted that the effective uid,
+\fBgeteuid\fR(2). of the application should be of sufficient privilege to perform such tasks as unmounting the user's home directory for example.
+.PP
+The flags argument is the binary or of zero or more of the following values:
+.TP
+PAM_SILENT
+Do not emit any messages.
+.SH "RETURN VALUES"
+.TP
+PAM_ABORT
+General failure.
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_SESSION_ERR
+Session failure.
+.TP
+PAM_SUCCESS
+Session was successful terminated.
+.SH "SEE ALSO"
+.PP
+\fBpam_open_session\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_close_session.3.xml b/doc/man/pam_close_session.3.xml
new file mode 100644
index 00000000..bfc29b2e
--- /dev/null
+++ b/doc/man/pam_close_session.3.xml
@@ -0,0 +1,115 @@
+<?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_send'>
+
+ <refmeta>
+ <refentrytitle>pam_close_session</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_close_session-name">
+ <refname>pam_close_session</refname>
+ <refpurpose>terminating PAM session management</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id="pam_close_session-synopsis">
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_close_session</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_close_session-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_close_session</function> function is used
+ to indicate that an authenticated session has ended.
+ The session should have been created with a call to
+ <citerefentry>
+ <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ <para>
+ It should be noted that the effective uid,
+ <citerefentry>
+ <refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry>. of the application should be of sufficient
+ privilege to perform such tasks as unmounting the
+ user's home directory for example.
+ </para>
+ <para>
+ The flags argument is the binary or of zero or more of the
+ following values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SILENT</term>
+ <listitem>
+ <para>
+ Do not emit any messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_close_session-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_ABORT</term>
+ <listitem>
+ <para>
+ General failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory buffer error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SESSION_ERR</term>
+ <listitem>
+ <para>
+ Session failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Session was successful terminated.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_close_session-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_end.3 b/doc/man/pam_end.3
index 06fdabb9..e074c6c5 100644
--- a/doc/man/pam_end.3
+++ b/doc/man/pam_end.3
@@ -1 +1,52 @@
-.so man3/pam_start.3
+.\" ** 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_END" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_end \- termination of PAM transaction
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 12
+\fBint\ \fBpam_end\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIpam_status\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_end\fR
+function terminates the PAM transaction and is the last function an application should call in the PAM contenxt. Upon return the handle
+\fIpamh\fR
+is no longer valid and all memory associated with it will be invalid.
+.PP
+The
+\fIpam_status\fR
+argument should be set to the value returned to the application by the last PAM library call.
+.PP
+The value taken by
+\fIpam_status\fR
+is used as an argument to the module specific callback function,
+\fBcleanup()\fR
+(See
+\fBpam_set_data\fR(3)
+and
+\fBpam_get_data\fR(3)). In this way the module can be given notification of the pass/fail nature of the tear\-down process, and perform any last minute tasks that are appropriate to the module before it is unlinked. This argument can be logically OR'd with
+\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.).
+.SH "RETURN VALUES"
+.TP
+PAM_SUCCESS
+Transaction was successful terminated.
+.TP
+PAM_SYSTEM_ERR
+System error, for example a NULL pointer was submitted as PAM handle or the function was called by a module.
+.SH "SEE ALSO"
+.PP
+\fBpam_get_data\fR(3),
+\fBpam_set_data\fR(3),
+\fBpam_start\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_end.3.xml b/doc/man/pam_end.3.xml
new file mode 100644
index 00000000..64dd3900
--- /dev/null
+++ b/doc/man/pam_end.3.xml
@@ -0,0 +1,109 @@
+<?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_end'>
+
+ <refmeta>
+ <refentrytitle>pam_end</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_end-name">
+ <refname>pam_end</refname>
+ <refpurpose>termination of PAM transaction</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id="pam_end-synopsis">
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_end</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>pam_status</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_end-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_end</function> function terminates the PAM
+ transaction and is the last function an application should call
+ in the PAM contenxt. Upon return the handle <emphasis>pamh</emphasis>
+ is no longer valid and all memory associated with it will be
+ invalid.
+ </para>
+ <para>
+ The <emphasis>pam_status</emphasis> argument should be set to
+ the value returned to the application by the last PAM
+ library call.
+ </para>
+ <para>
+ The value taken by <emphasis>pam_status</emphasis> is used as
+ an argument to the module specific callback function,
+ <function>cleanup()</function>
+ (See <citerefentry>
+ <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>). In this way the module can be given notification
+ of the pass/fail nature of the tear-down process, and perform any
+ last minute tasks that are appropriate to the module before it is
+ unlinked. This argument can be logically OR'd with
+ <emphasis>PAM_DATA_SILENT</emphasis> 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
+ <citerefentry>
+ <refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry>ed
+ process, and that the parent will take care of cleaning up things
+ that exist outside of the current process space (files etc.).
+ </para>
+ </refsect1>
+ <refsect1 id="pam_end-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Transaction was successful terminated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SYSTEM_ERR</term>
+ <listitem>
+ <para>
+ System error, for example a NULL pointer was submitted
+ as PAM handle or the function was called by a module.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_end-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_fail_delay.3 b/doc/man/pam_fail_delay.3
index f6cd238a..8e1cd09d 100644
--- a/doc/man/pam_fail_delay.3
+++ b/doc/man/pam_fail_delay.3
@@ -1,130 +1,108 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_FAIL_DELAY 3 "1997 Jan 12" "Linux-PAM 0.56" "Programmers' Manual"
-.SH NAME
-
+.\" ** 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_FAIL_DELAY" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
pam_fail_delay \- request a delay on failure
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or,
-.br
-.B #include <security/pam_modules.h>
-.sp
-.BI "int pam_fail_delay(pam_handle_t " "*pamh" ", unsigned int " "usec" ");"
-.sp 2
-.SH DESCRIPTION
-.br
-It is often possible to attack an authentication scheme by exploiting
-the time it takes the scheme to deny access to an applicant user. In
-cases of
-.I short
-timeouts, it may prove possible to attempt a
-.I brute force
-dictionary attack -- with an automated process, the attacker tries all
-possible passwords to gain access to the system. In other cases,
-where individual failures can take measurable amounts of time
-(indicating the nature of the failure), an attacker can obtain useful
-information about the authentication process. These latter attacks
-make use of procedural delays that constitute a
-.I covert channel
-of useful information.
-
-.br
-To minimize the effectiveness of such attacks, it is desirable to
-introduce a random delay in a failed authentication process.
-.B Linux-PAM
-provides such a facility. The delay occurs upon failure of the
-.BR pam_authenticate "(3) "
-and
-.BR pam_chauthtok "(3) "
-functions. It occurs
-.I after
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 19
+\fBint\ \fBpam_fail_delay\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBunsigned\ int\ \fR\fB\fIusec\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_fail_delay\fR
+function provides a mechanism by which an application or module can suggest a minimum delay of
+\fIusec\fR
+micro\-seconds. The function keeps a record of the longest time requested with this function. Should
+\fBpam_authenticate\fR(3)
+fail, the failing return to the application is delayed by an amount of time randomly distributed (by up to 25%) about this longest value.
+.PP
+Independent of success, the delay time is reset to its zero default value when the PAM service module returns control to the application. The delay occurs
+\fIafter\fR
all authentication modules have been called, but
-.I before
+\fIbefore\fR
control is returned to the service application.
-
-.br
-The function,
-.BR pam_fail_delay "(3),"
-is used to specify a required minimum for the length of the
-failure-delay; the
-.I usec
-argument. This function can be called by the service application
-and/or the authentication modules, both may have an interest in
-delaying a reapplication for service by the user. The length of the
-delay is computed at the time it is required. Its length is
-pseudo-gausianly distributed about the
-.I maximum
-requested value; the resultant delay will differ by as much as 25% of
-this maximum requested value (both up and down).
-
-.br
-On return from
-.BR pam_authenticate "(3) or " pam_chauthtok "(3),"
-independent of success or failure, the new requested delay is reset to
-its default value: zero.
-
-.SH EXAMPLE
-.br
-For example, a
-.B login
-application may require a failure delay of roughly 3 seconds. It will
-contain the following code:
+.PP
+When using this function the application programmer should check if it is available with:
.sp
-.br
-.B " pam_fail_delay(pamh, 3000000 /* micro-seconds */ );"
-.br
-.B " pam_authenticate(pamh, 0);"
+.nf
+#ifdef PAM_FAIL_DELAY
+ ....
+#endif /* PAM_FAIL_DELAY */
+
+.fi
+.PP
+For applications written with a single thread that are event driven in nature, generating this delay may be undesirable. Instead, the application may want to register the delay in some other way. For example, in a single threaded server that serves multiple authentication requests from a single event loop, the application might want to simply mark a given connection as blocked until an application timer expires. For this reason the delay function can be changed with the
+\fIPAM_FAIL_DELAY\fR
+item. It can be queried and set with
+\fBpam_get_item\fR(3)
+and
+\fBpam_set_item \fR(3)
+respectively. The value used to set it should be a function pointer of the following prototype:
.sp
-.br
-if the modules do not request a delay, the failure delay will be
-between 2.25 and 3.75 seconds.
-
-.br
-However, the modules, invoked in the authentication process, may
-also request delays:
+.nf
+void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
+
+.fi
.sp
-.br
-.RB " (module #1) " "pam_fail_delay(pamh, 2000000);"
+The arguments being the
+\fIretval\fR
+return code of the module stack, the
+\fIusec_delay\fR
+micro\-second delay that libpam is requesting and the
+\fIappdata_ptr\fR
+that the application has associated with the current
+\fIpamh\fR. This last value was set by the application when it called
+\fBpam_start\fR(3)
+or explicitly with
+\fBpam_set_item\fR(3). Note, if PAM_FAIL_DELAY is unset (or set to NULL), then no delay will be performed.
+.SH "RATIONALE"
+.PP
+It is often possible to attack an authentication scheme by exploiting the time it takes the scheme to deny access to an applicant user. In cases of
+\fIshort\fR
+timeouts, it may prove possible to attempt a
+\fIbrute force\fR
+dictionary attack \-\- with an automated process, the attacker tries all possible passwords to gain access to the system. In other cases, where individual failures can take measurable amounts of time (indicating the nature of the failure), an attacker can obtain useful information about the authentication process. These latter attacks make use of procedural delays that constitute a
+\fIcovert channel\fR
+of useful information.
+.PP
+To minimize the effectiveness of such attacks, it is desirable to introduce a random delay in a failed authentication process.
+.SH "EXAMPLE"
+.PP
+For example, a login application may require a failure delay of roughly 3 seconds. It will contain the following code:
.sp
-.br
-.RB " (module #2) " "pam_fail_delay(pamh, 4000000);"
+.nf
+ pam_fail_delay (pamh, 3000000 /* micro\-seconds */ );
+ pam_authenticate (pamh, 0);
+
+.fi
+.PP
+if the modules do not request a delay, the failure delay will be between 2.25 and 3.75 seconds.
+.PP
+However, the modules, invoked in the authentication process, may also request delays:
.sp
-.br
-in this case, it is the largest requested value that is used to
-compute the actual failed delay: here between 3 and 5 seconds.
-
+.nf
+module #1: pam_fail_delay (pamh, 2000000);
+module #2: pam_fail_delay (pamh, 4000000);
+
+.fi
+.PP
+in this case, it is the largest requested value that is used to compute the actual failed delay: here between 3 and 5 seconds.
.SH "RETURN VALUE"
+.PP
Following a successful call to
-.BR pam_fail_delay "(3), " PAM_SUCCESS
-is returned. All other returns should be considered serious failures.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-Under consideration by the X/Open group for future inclusion in the
-PAM RFC. 1996/1/10
-
-.SH BUGS
-.sp 2
-none known.
-
+\fBpam_fail_delay\fR(3),
+\fIPAM_SUCCESS\fR
+is returned. All other returns should be considered serious failures.
.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_get_item "(3) "
-and
-.BR pam_strerror "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+.PP
+\fBpam_start\fR(3),
+\fBpam_get_item\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_fail_delay.3.xml b/doc/man/pam_fail_delay.3.xml
new file mode 100644
index 00000000..86d1fff4
--- /dev/null
+++ b/doc/man/pam_fail_delay.3.xml
@@ -0,0 +1,175 @@
+<?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_fail_delay">
+
+ <refmeta>
+ <refentrytitle>pam_fail_delay</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_fail_delay-name">
+ <refname>pam_fail_delay</refname>
+ <refpurpose>request a delay on failure</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id="pam_fail_delay-synopsis">
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_fail_delay</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>unsigned int <parameter>usec</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+ <refsect1 id='pam_fail_delay-description'>
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_fail_delay</function> function provides a
+ mechanism by which an application or module can suggest a minimum
+ delay of <emphasis>usec</emphasis> micro-seconds. The
+ function keeps a record of the longest time requested with this
+ function. Should
+ <citerefentry>
+ <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> fail, the failing return to the application is
+ delayed by an amount of time randomly distributed (by up to 25%)
+ about this longest value.
+ </para>
+ <para>
+ Independent of success, the delay time is reset to its zero
+ default value when the PAM service module returns control to
+ the application. The delay occurs <emphasis>after</emphasis> all
+ authentication modules have been called, but <emphasis>before</emphasis>
+ control is returned to the service application.
+ </para>
+ <para>
+ When using this function the application programmer should check if
+ it is available with:
+ </para>
+ <programlisting>
+#ifdef PAM_FAIL_DELAY
+ ....
+#endif /* PAM_FAIL_DELAY */
+ </programlisting>
+
+ <para>
+ For applications written with a single thread that are event
+ driven in nature, generating this delay may be undesirable.
+ Instead, the application may want to register the delay in some
+ other way. For example, in a single threaded server that serves
+ multiple authentication requests from a single event loop, the
+ application might want to simply mark a given connection as
+ blocked until an application timer expires. For this reason
+ the delay function can be changed with the
+ <emphasis>PAM_FAIL_DELAY</emphasis> item. It can be queried and
+ set with
+ <citerefentry>
+ <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ and
+ <citerefentry>
+ <refentrytitle>pam_set_item </refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> respectively. The value used to set it should be
+ a function pointer of the following prototype:
+ <programlisting>
+void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr);
+ </programlisting>
+ The arguments being the <emphasis>retval</emphasis> return code
+ of the module stack, the <emphasis>usec_delay</emphasis>
+ micro-second delay that libpam is requesting and the
+ <emphasis>appdata_ptr</emphasis> that the application has associated
+ with the current <emphasis>pamh</emphasis>. This last value was set
+ by the application when it called
+ <citerefentry>
+ <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> or explicitly with
+ <citerefentry>
+ <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ Note, if PAM_FAIL_DELAY is unset (or set to NULL), then no delay
+ will be performed.
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_fail_delay-rationale'>
+ <title>RATIONALE</title>
+ <para>
+ It is often possible to attack an authentication scheme by exploiting
+ the time it takes the scheme to deny access to an applicant user. In
+ cases of <emphasis>short</emphasis> timeouts, it may prove possible
+ to attempt a <emphasis>brute force</emphasis> dictionary attack --
+ with an automated process, the attacker tries all possible passwords
+ to gain access to the system. In other cases, where individual
+ failures can take measurable amounts of time (indicating the nature
+ of the failure), an attacker can obtain useful information about the
+ authentication process. These latter attacks make use of procedural
+ delays that constitute a <emphasis>covert channel</emphasis>
+ of useful information.
+ </para>
+ <para>
+ To minimize the effectiveness of such attacks, it is desirable to
+ introduce a random delay in a failed authentication process.
+ </para>
+ </refsect1>
+
+ <refsect1 id='pam_fail_delay-example'>
+ <title>EXAMPLE</title>
+ <para>
+ For example, a login application may require a failure delay of
+ roughly 3 seconds. It will contain the following code:
+ </para>
+ <programlisting>
+ pam_fail_delay (pamh, 3000000 /* micro-seconds */ );
+ pam_authenticate (pamh, 0);
+ </programlisting>
+
+ <para>
+ if the modules do not request a delay, the failure delay will be
+ between 2.25 and 3.75 seconds.
+ </para>
+
+ <para>
+ However, the modules, invoked in the authentication process, may
+ also request delays:
+ </para>
+
+ <programlisting>
+module #1: pam_fail_delay (pamh, 2000000);
+module #2: pam_fail_delay (pamh, 4000000);
+ </programlisting>
+
+ <para>
+ in this case, it is the largest requested value that is used to
+ compute the actual failed delay: here between 3 and 5 seconds.
+ </para>
+ </refsect1>
+
+<refsect1 id='return_value'><title>RETURN VALUE</title>
+<para>Following a successful call to
+<citerefentry><refentrytitle>pam_fail_delay</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <emphasis remap='B'>PAM_SUCCESS</emphasis>
+is returned. All other returns should be considered serious failures.</para>
+
+</refsect1>
+
+ <refsect1 id='pam_fail_delay-see_also'>
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_start</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_get_data.3 b/doc/man/pam_get_data.3
new file mode 100644
index 00000000..30901564
--- /dev/null
+++ b/doc/man/pam_get_data.3
@@ -0,0 +1,52 @@
+.\" ** 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_DATA" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_get_data \- get module internal data
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_modules.h>\fR
+.HP 17
+\fBint\ \fBpam_get_data\fR\fR\fB(\fR\fBconst\ pam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fImodule_data_name\fR\fR\fB, \fR\fBconst\ void\ **\fR\fB\fIdata\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+This function together with the
+\fBpam_set_data\fR(3)
+function is useful to manage module\-specific data meaningful only to the calling PAM module.
+.PP
+The
+\fBpam_get_data\fR
+function looks up the object associated with the (hopefully) unique string
+\fImodule_data_name\fR
+in the PAM context specified by the
+\fIpamh\fR
+argument. A successful call to
+\fBpam_get_data\fR
+will result in
+\fIdata\fR
+pointing to the object. Note, this data is
+\fInot\fR
+a copy and should be treated as
+\fIconstant\fR
+by the module.
+.SH "RETURN VALUES"
+.TP
+PAM_SUCCESS
+Data was successful retrieved.
+.TP
+PAM_SYSTEM_ERR
+A NULL pointer was submitted as PAM handle or the function was called by an application.
+.TP
+PAM_NO_MODULE_DATA
+Module data not found or there is an entry, but it has the value NULL.
+.SH "SEE ALSO"
+.PP
+\fBpam_end\fR(3),
+\fBpam_set_data\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_get_data.3.xml b/doc/man/pam_get_data.3.xml
new file mode 100644
index 00000000..d0c77321
--- /dev/null
+++ b/doc/man/pam_get_data.3.xml
@@ -0,0 +1,108 @@
+<?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_data'>
+
+ <refmeta>
+ <refentrytitle>pam_get_data</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id='pam_get_data-name'>
+ <refname>pam_get_data</refname>
+ <refpurpose>
+ get module internal data
+ </refpurpose>
+ </refnamediv>
+
+
+<!-- body begins here -->
+
+ <refsynopsisdiv>
+
+ <funcsynopsis id="pam_get_data-synopsis">
+ <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_get_data</function></funcdef>
+ <paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>const char *<parameter>module_data_name</parameter></paramdef>
+ <paramdef>const void **<parameter>data</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_get_data-description">
+ <title>DESCRIPTION</title>
+ <para>
+ This function together with the
+ <citerefentry>
+ <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> function
+ is useful to manage module-specific data meaningful only to
+ the calling PAM module.
+ </para>
+ <para>
+ The <function>pam_get_data</function> function looks up the
+ object associated with the (hopefully) unique string
+ <emphasis>module_data_name</emphasis> in the PAM context
+ specified by the <emphasis>pamh</emphasis> argument.
+ A successful call to
+ <function>pam_get_data</function> will result in
+ <emphasis>data</emphasis> pointing to the object. Note,
+ this data is <emphasis>not</emphasis> a copy and should be
+ treated as <emphasis>constant</emphasis> by the module.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pam_get_data-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Data was successful retrieved.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SYSTEM_ERR</term>
+ <listitem>
+ <para>
+ A NULL pointer was submitted as PAM handle or the
+ function was called by an application.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_NO_MODULE_DATA</term>
+ <listitem>
+ <para>
+ Module data not found or there is an entry, but it has
+ the value NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_get_data-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/doc/man/pam_get_item.3 b/doc/man/pam_get_item.3
index 06df97bb..12ce870e 100644
--- a/doc/man/pam_get_item.3
+++ b/doc/man/pam_get_item.3
@@ -1 +1,116 @@
-.so man3/pam_set_item.3
+.\" ** 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_ITEM" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_get_item \- getting PAM informations
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_modules.h>\fR
+.HP 17
+\fBint\ \fBpam_get_item\fR\fR\fB(\fR\fBconst\ pam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIitem_type\fR\fR\fB, \fR\fBconst\ void\ **\fR\fB\fIitem\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_get_item\fR
+function allows applications and PAM service modules to access and retrieve PAM informations of
+\fIitem_type\fR. Upon successful return,
+\fIitem\fR
+contains a pointer to the value of the corresponding item. Note, this is a pointer to the
+\fIactual\fR
+data and should
+\fInot\fR
+be
+\fIfree()\fR'ed or over\-written! The following values are supported for
+\fIitem_type\fR:
+.TP
+PAM_SERVICE
+The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program).
+.TP
+PAM_USER
+The username of the entity under whose identity service will be given. That is, following authentication,
+\fIPAM_USER\fR
+identifies the local entity that gets to use the service. Note, this value can be mapped from something (eg., "anonymous") to something else (eg. "guest119") by any module in the PAM stack. As such an application should consult the value of
+\fIPAM_USER\fR
+after each call to a PAM function.
+.TP
+PAM_USER_PROMPT
+The string used when prompting for a user's name. The default value for this string is a localized version of "login: ".
+.TP
+PAM_TTY
+The terminal name: prefixed by
+\fI/dev/\fR
+if it is a device file; for graphical, X\-based, applications the value for this item should be the
+\fI$DISPLAY\fR
+variable.
+.TP
+PAM_RUSER
+The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user.
+.sp
+Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator.
+.sp
+\fIPAM_RUSER@PAM_RHOST\fR
+should always identify the requesting user. In some cases,
+\fIPAM_RUSER\fR
+may be NULL. In such situations, it is unclear who the requesting entity is.
+.TP
+PAM_RHOST
+The requesting hostname (the hostname of the machine from which the
+\fIPAM_RUSER\fR
+entity is requesting service). That is
+\fIPAM_RUSER@PAM_RHOST\fR
+does identify the requesting user. In some applications,
+\fIPAM_RHOST\fR
+may be NULL. In such situations, it is unclear where the authentication request is originating from.
+.TP
+PAM_AUTHTOK
+The authentication token (often a password). This token should be ignored by all module functions besides
+\fBpam_sm_authenticate\fR(3)
+and
+\fBpam_sm_chauthtok\fR(3). In the former function it is used to pass the most recent authentication token from one stacked module to another. In the latter function the token is used for another purpose. It contains the currently active authentication token.
+.TP
+PAM_OLDAUTHTOK
+The old authentication token. This token should be ignored by all module functions except
+\fBpam_sm_chauthtok\fR(3).
+.TP
+PAM_CONV
+The pam_conv structure. See
+\fBpam_conv\fR(3).
+.TP
+PAM_FAIL_DELAY
+A function pointer to redirect centrally managed failure delays. See
+\fBpam_fail_delay\fR(3).
+.PP
+If a service module wishes to obtain the name of the user, it should not use this function, but instead perform a call to
+\fBpam_get_user\fR(3).
+.PP
+Only a service module is privileged to read the authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK.
+.SH "RETURN VALUES"
+.TP
+PAM_BAD_ITEM
+The application attempted to set an undefined or inaccessible item.
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_PERM_DENIED
+The value of
+\fIitem\fR
+was NULL.
+.TP
+PAM_SUCCESS
+Data was successful updated.
+.TP
+PAM_SYSTEM_ERR
+The
+\fIpam_handle_t\fR
+passed as first argument was invalid.
+.SH "SEE ALSO"
+.PP
+\fBpam_set_item\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_get_item.3.xml b/doc/man/pam_get_item.3.xml
new file mode 100644
index 00000000..2f7fca5b
--- /dev/null
+++ b/doc/man/pam_get_item.3.xml
@@ -0,0 +1,134 @@
+<?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"
+[
+<!--
+<!ENTITY accessconf SYSTEM "pam_item_types.inc.xml">
+-->
+]>
+
+<refentry id='pam_get_item'>
+
+ <refmeta>
+ <refentrytitle>pam_get_item</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id='pam_get_item-name'>
+ <refname>pam_get_item</refname>
+ <refpurpose>
+ getting PAM informations
+ </refpurpose>
+ </refnamediv>
+
+
+<!-- body begins here -->
+
+ <refsynopsisdiv>
+
+ <funcsynopsis id="pam_get_item-synopsis">
+ <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_get_item</function></funcdef>
+ <paramdef>const pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>item_type</parameter></paramdef>
+ <paramdef>const void **<parameter>item</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_get_item-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_get_item</function> function allows applications
+ and PAM service modules to access and retrieve PAM informations
+ of <emphasis>item_type</emphasis>. Upon successful return,
+ <emphasis>item</emphasis> contains a pointer to the value of the
+ corresponding item. Note, this is a pointer to the
+ <emphasis>actual</emphasis> data and should
+ <emphasis remap="B">not</emphasis> be <emphasis>free()</emphasis>'ed or
+ over-written! The following values are supported for
+ <emphasis>item_type</emphasis>:
+ </para>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_item_types.inc.xml"/>
+
+ <para>
+ If a service module wishes to obtain the name of the user,
+ it should not use this function, but instead perform a call to
+ <citerefentry>
+ <refentrytitle>pam_get_user</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ <para>
+ Only a service module is privileged to read the
+ authentication tokens, PAM_AUTHTOK and PAM_OLDAUTHTOK.
+ </para>
+
+ </refsect1>
+
+ <refsect1 id="pam_get_item-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_BAD_ITEM</term>
+ <listitem>
+ <para>
+ The application attempted to set an undefined or inaccessible
+ item.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory buffer error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_PERM_DENIED</term>
+ <listitem>
+ <para>
+ The value of <emphasis>item</emphasis> was NULL.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Data was successful updated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SYSTEM_ERR</term>
+ <listitem>
+ <para>
+ The <emphasis>pam_handle_t</emphasis> passed as first
+ argument was invalid.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_get_item-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/doc/man/pam_item_types.inc.xml b/doc/man/pam_item_types.inc.xml
new file mode 100644
index 00000000..9d70087b
--- /dev/null
+++ b/doc/man/pam_item_types.inc.xml
@@ -0,0 +1,151 @@
+<!-- this file is included by pam_set_item and pam_get_item -->
+
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SERVICE</term>
+ <listitem>
+ <para>
+ The service name (which identifies that PAM stack that
+ the PAM functions will use to authenticate the program).
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_USER</term>
+ <listitem>
+ <para>
+ The username of the entity under whose identity service
+ will be given. That is, following authentication,
+ <emphasis>PAM_USER</emphasis> identifies the local entity
+ that gets to use the service. Note, this value can be mapped
+ from something (eg., "anonymous") to something else (eg.
+ "guest119") by any module in the PAM stack. As such an
+ application should consult the value of
+ <emphasis>PAM_USER</emphasis> after each call to a PAM function.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_USER_PROMPT</term>
+ <listitem>
+ <para>
+ The string used when prompting for a user's name. The default
+ value for this string is a localized version of "login: ".
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_TTY</term>
+ <listitem>
+ <para>
+ The terminal name: prefixed by <filename>/dev/</filename> if
+ it is a device file; for graphical, X-based, applications the
+ value for this item should be the
+ <emphasis>$DISPLAY</emphasis> variable.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_RUSER</term>
+ <listitem>
+ <para>
+ The requesting user name: local name for a locally
+ requesting user or a remote user name for a remote
+ requesting user.
+ </para>
+ <para>
+ Generally an application or module will attempt to supply
+ the value that is most strongly authenticated (a local account
+ before a remote one. The level of trust in this value is
+ embodied in the actual authentication stack associated with
+ the application, so it is ultimately at the discretion of the
+ system administrator.
+ </para>
+ <para>
+ <emphasis>PAM_RUSER@PAM_RHOST</emphasis> should always identify
+ the requesting user. In some cases,
+ <emphasis>PAM_RUSER</emphasis> may be NULL. In such situations,
+ it is unclear who the requesting entity is.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_RHOST</term>
+ <listitem>
+ <para>
+ The requesting hostname (the hostname of the machine from
+ which the <emphasis>PAM_RUSER</emphasis> entity is requesting
+ service). That is <emphasis>PAM_RUSER@PAM_RHOST</emphasis>
+ does identify the requesting user. In some applications,
+ <emphasis>PAM_RHOST</emphasis> may be NULL. In such situations,
+ it is unclear where the authentication request is originating
+ from.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_AUTHTOK</term>
+ <listitem>
+ <para>
+ The authentication token (often a password). This token
+ should be ignored by all module functions besides
+ <citerefentry>
+ <refentrytitle>pam_sm_authenticate</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ In the former function it is used to pass the most recent
+ authentication token from one stacked module to another. In
+ the latter function the token is used for another purpose.
+ It contains the currently active authentication token.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_OLDAUTHTOK</term>
+ <listitem>
+ <para>
+ The old authentication token. This token should be ignored
+ by all module functions except
+ <citerefentry>
+ <refentrytitle>pam_sm_chauthtok</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+
+ <varlistentry>
+ <term>PAM_CONV</term>
+ <listitem>
+ <para>
+ The pam_conv structure. See
+ <citerefentry>
+ <refentrytitle>pam_conv</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ </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_open_session.3 b/doc/man/pam_open_session.3
index 4e63b5c4..ef6d545d 100644
--- a/doc/man/pam_open_session.3
+++ b/doc/man/pam_open_session.3
@@ -1,99 +1,47 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_OPEN_SESSION 3 "1997 Jan 4" "Linux-PAM 0.55" "App. Programmers' Manual"
-.SH NAME
-
-pam_open/close_session \- PAM session management
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_open_session(pam_handle_t " *pamh ", int " flags ");"
-.sp
-.BI "int pam_close_session(pam_handle_t " *pamh ", int " flags ");"
-.sp 2
-.SH DESCRIPTION
-
-PAM provides management-hooks for the initialization and termination
-of a session.
-
+.\" ** 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_OPEN_SESSION" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_open_session \- start PAM session management
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 21
+\fBint\ \fBpam_open_session\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_open_session\fR
+function sets up a user session for a previously successful authenticated user. The session should later be terminated with a call to
+\fBpam_close_session\fR(3).
+.PP
+It should be noted that the effective uid,
+\fBgeteuid\fR(2). of the application should be of sufficient privilege to perform such tasks as creating or mounting the user's home directory for example.
+.PP
+The flags argument is the binary or of zero or more of the following values:
.TP
-.B pam_open_session
-.br
-Use this function to signal that an authenticated user session has
-begun. It should be called only after the user is properly identified
-and (where necessary) has been granted their credentials with
-.BR pam_authenticate "(3)"
-and
-.BR pam_setcred "(3)"
-respectively.
-
-.br
-Some types of functions associated with session
-initialization are logging for the purposes of system-audit and
-mounting directories (the user's home directory for example). These
-should not concern the application. It should be noted that the
-.I effective
-uid,
-.BR geteuid "(2),"
-of the application should be of sufficient privilege to perform such
-tasks.
-
+PAM_SILENT
+Do not emit any messages.
+.SH "RETURN VALUES"
.TP
-.B pam_close_session
-.br
-Use this function to signal that a user session has
-terminated. In general this function may not need to be located in the
-same application as the initialization function,
-.BR pam_open_session "."
-
-.br
-Typically, this function will undo the actions of
-.BR pam_open_session "."
-That is, log audit information concerning the end of the user session
-or unmount the user's home directory. Apart from having sufficient
-privilege the details of the session termination should not concern
-the calling application. It is good programming practice, however, to
-cease acting on behalf of the user on returning from this call.
-
-.SH RETURN VALUE
-A successful return from the session management functions will be
-indicated with
-.BR PAM_SUCCESS "."
-
-.br
-The specific error indicating a failure to open or close a session is
-.BR PAM_SESSION_ERR "."
-In general other return values may be returned. They should be treated
-as indicating failure.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-OSF-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
+PAM_ABORT
+General failure.
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_SESSION_ERR
+Session failure.
+.TP
+PAM_SUCCESS
+Session was successful created.
.SH "SEE ALSO"
-
-.BR pam_start "(3), "
-.BR pam_authenticate "(3), "
-.BR pam_setcred "(3), "
-.BR pam_get_item "(3), "
-.BR pam_strerror "(3) "
-and
-.BR pam "(3)."
-
-.br
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+.PP
+\fBpam_close_session\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_open_session.3.xml b/doc/man/pam_open_session.3.xml
new file mode 100644
index 00000000..3ae05877
--- /dev/null
+++ b/doc/man/pam_open_session.3.xml
@@ -0,0 +1,115 @@
+<?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_send'>
+
+ <refmeta>
+ <refentrytitle>pam_open_session</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_open_session-name">
+ <refname>pam_open_session</refname>
+ <refpurpose>start PAM session management</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id="pam_open_session-synopsis">
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_open_session</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_open_session-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_open_session</function> function sets up a
+ user session for a previously successful authenticated user.
+ The session should later be terminated with a call to
+ <citerefentry>
+ <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ <para>
+ It should be noted that the effective uid,
+ <citerefentry>
+ <refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry>. of the application should be of sufficient
+ privilege to perform such tasks as creating or mounting the
+ user's home directory for example.
+ </para>
+ <para>
+ The flags argument is the binary or of zero or more of the
+ following values:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_SILENT</term>
+ <listitem>
+ <para>
+ Do not emit any messages.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_open_session-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_ABORT</term>
+ <listitem>
+ <para>
+ General failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory buffer error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SESSION_ERR</term>
+ <listitem>
+ <para>
+ Session failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Session was successful created.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_open_session-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_close_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_set_data.3 b/doc/man/pam_set_data.3
new file mode 100644
index 00000000..55fdeb9c
--- /dev/null
+++ b/doc/man/pam_set_data.3
@@ -0,0 +1,85 @@
+.\" ** 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_SET_DATA" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_set_data \- set module internal data
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_modules.h>\fR
+.HP 17
+\fBint\ \fBpam_set_data\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fImodule_data_name\fR\fR\fB, \fR\fBvoid\ *\fR\fB\fIdata\fR\fR\fB, \fR\fBvoid\ \fR\fB\fI(*cleanup)(pam_handle_t\ *pamh,\ void\ *data,\ int\ error_status)\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_set_data\fR
+function associates a pointer to an object with the (hopefully) unique string
+\fImodule_data_name\fR
+in the PAM context specified by the
+\fIpamh\fR
+argument.
+.PP
+PAM modules may be dynamically loadable objects. In general such files should not contain
+\fIstatic\fR
+variables. This function and its counterpart
+\fBpam_get_data\fR(3), provide a mechanism for a module to associate some data with the handle
+\fIpamh\fR. Typically a module will call the
+\fBpam_set_data\fR
+function to register some data under a (hopefully) unique
+\fImodule_data_name\fR. The data is available for use by other modules too but
+\fInot\fR
+by an application. Since this functions stores only a pointer to the
+\fIdata\fR, the module should not modify or free the content of it.
+.PP
+The function
+\fBcleanup()\fR
+is associated with the
+\fIdata\fR
+and, if non\-NULL, it is called when this data is over\-written or following a call to
+\fBpam_end\fR(3).
+.PP
+The
+\fIerror_status\fR
+argument is used to indicate to the module the sort of action it is to take in cleaning this data item. As an example, Kerberos creates a ticket file during the authentication phase, this file might be associated with a data item. When
+\fBpam_end\fR(3)
+is called by the module, the
+\fIerror_status\fR
+carries the return value of the
+\fBpam_authenticate\fR(3)
+or other
+\fIlibpam\fR
+function as appropriate. Based on this value the Kerberos module may choose to delete the ticket file (\fIauthentication failure\fR) or leave it in place.
+.PP
+The
+\fIerror_status\fR
+may have been logically OR'd with either of the following two values:
+.TP
+PAM_DATA_REPLACE
+When a data item is being replaced (through a second call to
+\fBpam_set_data\fR) this mask is used. Otherwise, the call is assumed to be from
+\fBpam_end\fR(3).
+.TP
+PAM_DATA_SILENT
+Which indicates that the process would prefer to perform the
+\fBcleanup()\fR
+quietly. That is, discourages logging/messages to the user.
+.SH "RETURN VALUES"
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_SUCCESS
+Data was successful stored.
+.TP
+PAM_SYSTEM_ERR
+A NULL pointer was submitted as PAM handle or the function was called by an application.
+.SH "SEE ALSO"
+.PP
+\fBpam_end\fR(3),
+\fBpam_get_data\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_set_data.3.xml b/doc/man/pam_set_data.3.xml
new file mode 100644
index 00000000..bc2f05b3
--- /dev/null
+++ b/doc/man/pam_set_data.3.xml
@@ -0,0 +1,172 @@
+<?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_set_data'>
+
+ <refmeta>
+ <refentrytitle>pam_set_data</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id='pam_set_data-name'>
+ <refname>pam_set_data</refname>
+ <refpurpose>
+ set module internal data
+ </refpurpose>
+ </refnamediv>
+
+
+<!-- body begins here -->
+
+ <refsynopsisdiv>
+
+ <funcsynopsis id="pam_set_data-synopsis">
+ <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_set_data</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>const char *<parameter>module_data_name</parameter></paramdef>
+ <paramdef>void *<parameter>data</parameter></paramdef>
+ <paramdef>void <parameter>(*cleanup)(pam_handle_t *pamh, void *data, int error_status)</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_set_data-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_set_data</function> function associates a pointer
+ to an object with the (hopefully) unique string
+ <emphasis>module_data_name</emphasis> in the PAM context specified
+ by the <emphasis>pamh</emphasis> argument.
+ </para>
+
+ <para>
+ PAM modules may be dynamically loadable objects. In general such files
+ should not contain <emphasis>static</emphasis> variables. This function
+ and its counterpart
+ <citerefentry>
+ <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ provide a mechanism for a module to associate some data with
+ the handle <emphasis>pamh</emphasis>. Typically a module will call the
+ <function>pam_set_data</function> function to register some data
+ under a (hopefully) unique <emphasis>module_data_name</emphasis>.
+ The data is available for use by other modules too but
+ <emphasis>not</emphasis> by an application. Since this functions
+ stores only a pointer to the <emphasis>data</emphasis>, the module
+ should not modify or free the content of it.
+ </para>
+
+ <para>
+ The function <function>cleanup()</function> is associated with the
+ <emphasis>data</emphasis> and, if non-NULL, it is called when this
+ data is over-written or following a call to
+ <citerefentry>
+ <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+
+ <para>
+ The <emphasis>error_status</emphasis> argument is used to indicate
+ to the module the sort of action it is to take in cleaning this data
+ item. As an example, Kerberos creates a ticket file during the
+ authentication phase, this file might be associated with a data item.
+ When
+ <citerefentry>
+ <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ is called by the module, the <emphasis>error_status</emphasis>
+ carries the return value of the
+ <citerefentry>
+ <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ or other <emphasis>libpam</emphasis> function as appropriate. Based
+ on this value the Kerberos module may choose to delete the ticket file
+ (<emphasis>authentication failure</emphasis>) or leave it in place.
+ </para>
+
+ <para>
+ The <emphasis>error_status</emphasis> may have been logically
+ OR'd with either of the following two values:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>PAM_DATA_REPLACE</term>
+ <listitem>
+ <para>
+ When a data item is being replaced (through a second call to
+ <function>pam_set_data</function>) this mask is used.
+ Otherwise, the call is assumed to be from
+ <citerefentry>
+ <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PAM_DATA_SILENT</term>
+ <listitem>
+ <para>
+ Which indicates that the process would prefer to perform the
+ <function>cleanup()</function> quietly. That is, discourages
+ logging/messages to the user.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_set_data-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>
+ Data was successful stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SYSTEM_ERR</term>
+ <listitem>
+ <para>
+ A NULL pointer was submitted as PAM handle or the
+ function was called by an application.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_set_data-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/doc/man/pam_set_item.3 b/doc/man/pam_set_item.3
index b0582778..0fe861c6 100644
--- a/doc/man/pam_set_item.3
+++ b/doc/man/pam_set_item.3
@@ -1,55 +1,115 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@kernel.org>
-.TH PAM_SET_ITEM 3 "2001 Jan 21" "Linux-PAM" "App. Programmers' Manual"
-.SH NAME
-
-pam_set_item, pam_get_item \- item manipulation under PAM
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or
-.br
-.B #include <secruity/pam_modules.h>
+.\" ** 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_SET_ITEM" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_set_item \- set and update PAM informations
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_modules.h>\fR
+.HP 17
+\fBint\ \fBpam_set_item\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIitem_type\fR\fR\fB, \fR\fBconst\ void\ *\fR\fB\fIitem\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_set_item\fR
+function allows applications and PAM service modules to access and to update PAM informations of
+\fIitem_type\fR. For this a copy of the object pointed to by the
+\fIitem\fR
+argument is created. The following
+\fIitem_type\fRs are supported:
+.TP
+PAM_SERVICE
+The service name (which identifies that PAM stack that the PAM functions will use to authenticate the program).
+.TP
+PAM_USER
+The username of the entity under whose identity service will be given. That is, following authentication,
+\fIPAM_USER\fR
+identifies the local entity that gets to use the service. Note, this value can be mapped from something (eg., "anonymous") to something else (eg. "guest119") by any module in the PAM stack. As such an application should consult the value of
+\fIPAM_USER\fR
+after each call to a PAM function.
+.TP
+PAM_USER_PROMPT
+The string used when prompting for a user's name. The default value for this string is a localized version of "login: ".
+.TP
+PAM_TTY
+The terminal name: prefixed by
+\fI/dev/\fR
+if it is a device file; for graphical, X\-based, applications the value for this item should be the
+\fI$DISPLAY\fR
+variable.
+.TP
+PAM_RUSER
+The requesting user name: local name for a locally requesting user or a remote user name for a remote requesting user.
.sp
-.BI "int pam_set_item(pam_handle_t " *pamh ", int " item_type ", void " *item ");"
+Generally an application or module will attempt to supply the value that is most strongly authenticated (a local account before a remote one. The level of trust in this value is embodied in the actual authentication stack associated with the application, so it is ultimately at the discretion of the system administrator.
.sp
-.BI "int pam_get_item(const pam_handle_t " *pamh ", int " item_type ", const void " **item_p ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_set_item
-.sp
-.B pam_set_item
-
-These functions are currently undocumented in a man page, but see the
-end of this man page for more information (the PAM guides).
-
-On success
-.BR PAM_SUCCESS
-is returned, all other return values should be treated as errors.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam (8)
+\fIPAM_RUSER@PAM_RHOST\fR
+should always identify the requesting user. In some cases,
+\fIPAM_RUSER\fR
+may be NULL. In such situations, it is unclear who the requesting entity is.
+.TP
+PAM_RHOST
+The requesting hostname (the hostname of the machine from which the
+\fIPAM_RUSER\fR
+entity is requesting service). That is
+\fIPAM_RUSER@PAM_RHOST\fR
+does identify the requesting user. In some applications,
+\fIPAM_RHOST\fR
+may be NULL. In such situations, it is unclear where the authentication request is originating from.
+.TP
+PAM_AUTHTOK
+The authentication token (often a password). This token should be ignored by all module functions besides
+\fBpam_sm_authenticate\fR(3)
and
-.BR pam_strerror "(3)."
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+\fBpam_sm_chauthtok\fR(3). In the former function it is used to pass the most recent authentication token from one stacked module to another. In the latter function the token is used for another purpose. It contains the currently active authentication token.
+.TP
+PAM_OLDAUTHTOK
+The old authentication token. This token should be ignored by all module functions except
+\fBpam_sm_chauthtok\fR(3).
+.TP
+PAM_CONV
+The pam_conv structure. See
+\fBpam_conv\fR(3).
+.TP
+PAM_FAIL_DELAY
+A function pointer to redirect centrally managed failure delays. See
+\fBpam_fail_delay\fR(3).
+.PP
+For all
+\fIitem_type\fRs, other than PAM_CONV and PAM_FAIL_DELAY,
+\fIitem\fR
+is a pointer to a <NUL> terminated character string. In the case of PAM_CONV,
+\fIitem\fR
+points to an initialized
+\fIpam_conv\fR
+structure. In the case of PAM_FAIL_DELAY,
+\fIitem\fR
+is a function pointer:
+\fBvoid (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)\fR
+.PP
+Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before returning to the application. Which means an application is not able to access the authentication tokens.
+.SH "RETURN VALUES"
+.TP
+PAM_BAD_ITEM
+The application attempted to set an undefined or inaccessible item.
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_SUCCESS
+Data was successful updated.
+.TP
+PAM_SYSTEM_ERR
+The
+\fIpam_handle_t\fR
+passed as first argument was invalid.
+.SH "SEE ALSO"
+.PP
+\fBpam_get_item\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_set_item.3.xml b/doc/man/pam_set_item.3.xml
new file mode 100644
index 00000000..8390ab95
--- /dev/null
+++ b/doc/man/pam_set_item.3.xml
@@ -0,0 +1,127 @@
+<?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"
+[
+<!--
+<!ENTITY accessconf SYSTEM "pam_item_types.inc.xml">
+-->
+]>
+
+<refentry id='pam_set_item'>
+
+ <refmeta>
+ <refentrytitle>pam_set_item</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id='pam_set_item-name'>
+ <refname>pam_set_item</refname>
+ <refpurpose>
+ set and update PAM informations
+ </refpurpose>
+ </refnamediv>
+
+
+<!-- body begins here -->
+
+ <refsynopsisdiv>
+
+ <funcsynopsis id="pam_set_item-synopsis">
+ <funcsynopsisinfo>#include &lt;security/pam_modules.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_set_item</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>item_type</parameter></paramdef>
+ <paramdef>const void *<parameter>item</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_set_item-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_set_item</function> function allows applications
+ and PAM service modules to access and to update PAM informations
+ of <emphasis>item_type</emphasis>. For this a copy
+ of the object pointed to by the <emphasis>item</emphasis> argument
+ is created. The following <emphasis>item_type</emphasis>s are
+ supported:
+ </para>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
+ href="pam_item_types.inc.xml"/>
+
+ <para>
+ For all <emphasis>item_type</emphasis>s, other than PAM_CONV and
+ PAM_FAIL_DELAY, <emphasis>item</emphasis> is a pointer to a &lt;NUL&gt;
+ terminated character string. In the case of PAM_CONV,
+ <emphasis>item</emphasis> points to an initialized
+ <emphasis>pam_conv</emphasis> structure. In the case of
+ PAM_FAIL_DELAY, <emphasis>item</emphasis> is a function pointer:
+ <function>void (*delay_fn)(int retval, unsigned usec_delay, void *appdata_ptr)</function>
+ </para>
+
+ <para>
+ Both, PAM_AUTHTOK and PAM_OLDAUTHTOK, will be reseted before
+ returning to the application. Which means an application is not
+ able to access the authentication tokens.
+ </para>
+
+ </refsect1>
+
+ <refsect1 id="pam_set_item-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_BAD_ITEM</term>
+ <listitem>
+ <para>
+ The application attempted to set an undefined or inaccessible
+ item.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory buffer error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Data was successful updated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SYSTEM_ERR</term>
+ <listitem>
+ <para>
+ The <emphasis>pam_handle_t</emphasis> passed as first
+ argument was invalid.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_set_item-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+
+</refentry>
diff --git a/doc/man/pam_setcred.3 b/doc/man/pam_setcred.3
index 8c00fe71..22c728fb 100644
--- a/doc/man/pam_setcred.3
+++ b/doc/man/pam_setcred.3
@@ -1,79 +1,74 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996,1997 <morgan@parc.power.net>
-.TH PAM_SETCRED 3 "1997 July 6" "Linux-PAM 0.58" "App. Programmers' Manual"
-.SH NAME
-
-pam_setcred \- set the credentials for the user
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_setcred(pam_handle_t " *pamh ", int " flags ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_setcred
-
-This function is used to establish, maintain and delete the
-credentials of a user. It should be called after a user has been
-authenticated and before a session is opened for the user (with
-.BR pam_open_session "(3))."
-
-It should be noted that credentials come in many forms. Examples
-include: group memberships; ticket-files; and Linux-PAM environment
-variables. For this reason, it is important that the basic identity
-of the user is established, by the application, prior to a call to
-this function. For example, the default
-.BR Linux-PAM
-environment variables should be set and also
-.BR initgroups "(2) "
+.\" ** 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_SETCRED" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_setcred \- establish / delete user credentials
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 16
+\fBint\ \fBpam_setcred\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIflags\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_setcred\fR
+function is used to establish, maintain and delete the credentials of a user. It should be called after a user has been authenticated and before a session is opened for the user (with
+\fBpam_open_session\fR(3)).
+.PP
+A credential is something that the user possesses. It is some property, such as a
+\fIKerberos\fR
+ticket, or a supplementary group membership that make up the uniqueness of a given user. On a Linux system the user's
+\fIUID\fR
+and
+\fIGID\fR's are credentials too. However, it has been decided that these properties (along with the default supplementary groups of which the user is a member) are credentials that should be set directly by the application and not by PAM. Such credentials should be established, by the application, prior to a call to this function. For example,
+\fBinitgroups\fR(2)
(or equivalent) should have been performed.
-
-.SH "VALID FLAGS"
+.PP
+Valid
+\fIflags\fR, any one of which, may be logically OR'd with
+\fBPAM_SILENT\fR, are:
.TP
-.BR PAM_ESTABLISH_CRED
-initialize the credentials for the user.
-
+PAM_ESTABLISH_CRED
+Initialize the credentials for the user.
.TP
-.BR PAM_DELETE_CRED
-delete the user's credentials.
-
+PAM_DELETE_CRED
+Delete the user's credentials.
.TP
-.BR PAM_REINITIALIZE_CRED
-delete and then initialize the user's credentials.
-
+PAM_REINITIALIZE_CRED
+Fully reinitialize the user's credentials.
.TP
-.BR PAM_REFRESH_CRED
-extend the lifetime of the existing credentials.
-
+PAM_REFRESH_CRED
+Extend the lifetime of the existing credentials.
.SH "RETURN VALUE"
-
-On success
-.BR PAM_SUCCESS
-is returned, all other return values should be treated as errors.
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
+.TP
+PAM_BUF_ERR
+Memory buffer error.
+.TP
+PAM_CRED_ERR
+Failed to set user credentials.
+.TP
+PAM_CRED_EXPIRED
+User credentials are expired.
+.TP
+PAM_CRED_UNAVAIL
+Failed to retrieve user credentials.
+.TP
+PAM_SUCCESS
+Data was successful stored.
+.TP
+PAM_SYSTEM_ERR
+A NULL pointer was submitted as PAM handle, the function was called by a module or another system error occured.
+.TP
+PAM_USER_UNKNOWN
+User is not known to an authentication module.
.SH "SEE ALSO"
-
-.BR pam_authenticate "(3), "
-.BR pam_strerror "(3)"
-and
-.BR pam_open_session "(3). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+.PP
+\fBpam_authenticate\fR(3),
+\fBpam_open_session\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_setcred.3.xml b/doc/man/pam_setcred.3.xml
new file mode 100644
index 00000000..5ecbeec5
--- /dev/null
+++ b/doc/man/pam_setcred.3.xml
@@ -0,0 +1,173 @@
+<?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_setcred">
+
+ <refmeta>
+ <refentrytitle>pam_setcred</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_setcred-name">
+ <refname>pam_setcred</refname>
+ <refpurpose>
+ establish / delete user credentials
+ </refpurpose>
+ </refnamediv>
+
+ <!-- body begins here -->
+ <refsynopsisdiv id='synopsis'>
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_setcred</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>flags</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id='pam_setcred-description'>
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_setcred</function> function is used to establish,
+ maintain and delete the credentials of a user. It should be called
+ after a user has been authenticated and before a session is opened
+ for the user (with
+ <citerefentry>
+ <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>).
+ </para>
+
+ <para>
+ A credential is something that the user possesses. It is some
+ property, such as a <emphasis>Kerberos</emphasis> ticket, or a
+ supplementary group membership that make up the uniqueness of a
+ given user. On a Linux system the user's <emphasis>UID</emphasis>
+ and <emphasis>GID</emphasis>'s are credentials too. However, it
+ has been decided that these properties (along with the default
+ supplementary groups of which the user is a member) are credentials
+ that should be set directly by the application and not by PAM.
+ Such credentials should be established, by the application, prior
+ to a call to this function. For example,
+ <citerefentry>
+ <refentrytitle>initgroups</refentrytitle><manvolnum>2</manvolnum>
+ </citerefentry> (or equivalent) should have been performed.
+ </para>
+
+ <para>
+ Valid <emphasis>flags</emphasis>, any one of which, may be
+ logically OR'd with <option>PAM_SILENT</option>, are:
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>PAM_ESTABLISH_CRED</term>
+ <listitem>
+ <para>Initialize the credentials for the user.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_DELETE_CRED</term>
+ <listitem>
+ <para>Delete the user's credentials.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_REINITIALIZE_CRED</term>
+ <listitem>
+ <para>Fully reinitialize the user's credentials.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_REFRESH_CRED</term>
+ <listitem>
+ <para>Extend the lifetime of the existing credentials.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id='pam_setcred-return_value'>
+ <title>RETURN VALUE</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory buffer error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_CRED_ERR</term>
+ <listitem>
+ <para>
+ Failed to set user credentials.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_CRED_EXPIRED</term>
+ <listitem>
+ <para>
+ User credentials are expired.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_CRED_UNAVAIL</term>
+ <listitem>
+ <para>
+ Failed to retrieve user credentials.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Data was successful stored.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SYSTEM_ERR</term>
+ <listitem>
+ <para>
+ A NULL pointer was submitted as PAM handle, the
+ function was called by a module or another system
+ error occured.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_USER_UNKNOWN</term>
+ <listitem>
+ <para>
+ User is not known to an authentication module.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_set_data-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_authenticate</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_open_session</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_start.3 b/doc/man/pam_start.3
index 9c11fd73..ac6454b7 100644
--- a/doc/man/pam_start.3
+++ b/doc/man/pam_start.3
@@ -1,98 +1,72 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
-.TH PAM_START 3 "1997 Feb 15" "Linux-PAM 0.56" "Application Programmers' Manual"
-.SH NAME
-
-pam_start, pam_end \- activating Linux-PAM
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.sp
-.BI "int pam_start(const char " *service ", const char " *user ", const struct pam_conv " *conv ", pam_handle_t " **pamh_p ");"
-.sp
-.BI "int pam_end(pam_handle_t " *pamh ", int " pam_status ");"
-.sp 2
-.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_START" "3" "02/12/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_start \- initialization of PAM transaction
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 14
+\fBint\ \fBpam_start\fR\fR\fB(\fR\fBconst\ char\ *\fR\fB\fIservice_name\fR\fR\fB, \fR\fBconst\ char\ *\fR\fB\fIuser\fR\fR\fB, \fR\fBconst\ struct\ pam_conv\ *\fR\fB\fIpam_conversation\fR\fR\fB, \fR\fBpam_handle_t\ **\fR\fB\fIpamh\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_start\fR
+function creates the PAM context and initiates the PAM transaction. It is the first of the PAM functions that needs to be called by an application.
+.PP
+The
+\fIservice_name\fR
+argument specifies the name of the service to apply and will be stored as PAM_SERVICE item in the new context. The policy for the service will be read from the file
+\fI/etc/pam.d/service_name\fR
+or, if that file does not exist, from
+\fI/etc/pam.conf\fR.
+.PP
+The
+\fIuser\fR
+argument can specify the name of the target user and will be stored as PAM_USER item. If the argument is NULL, the module has to ask for this item if necessary.
+.PP
+The
+\fIpam_conversation\fR
+argument points to a
+\fIstruct pam_conv\fR
+describing the conversation function to use. An application must provide this for direct communication between a loaded module and the application.
+.PP
+Following a successful return (PAM_SUCCESS) the contents of
+\fIpamh\fR
+is a handle that contains the PAM context for successive calls to the PAM functions. In an error case is the content of
+\fIpamh\fR
+undefined.
+.PP
+The
+\fIpam_handle_t\fR
+is a blind structure and the application should not attempt to probe it directly for information. Instead the PAM library provides the functions
+\fBpam_set_item\fR(3)
+and
+\fBpam_get_item\fR(3). The PAM handle cannot be used for mulitiple authentications at the same time as long as
+\fBpam_end\fR
+was not called on it before.
+.SH "RETURN VALUES"
.TP
-.B pam_start
-Initialize the
-.I Linux-PAM
-library. Identifying the application with a particular
-.IR service
-name. The
-.IR user "name"
-can take the value
-.IR NULL ", "
-if not known at the time the interface is initialized. The
-conversation structure is passed to the library via the
-.IR conv
-argument. (For a complete description of this and other structures
-the reader is directed to the more verbose
-.IR Linux-PAM
-application developers' guide). Upon successful initialization, an
-opaque pointer-handle for future access to the library is returned
-through the contents of the
-.IR pamh_p
-pointer.
-
+PAM_ABORT
+General failure.
.TP
-.B pam_end
-Terminate the
-.B Linux-PAM
-library. The service application associated with the
-.IR pamh
-handle, is terminated. The argument,
-.IR pam_status ", "
-passes the value most recently returned to the application from the
-library; it indicates the manner in which the library should be
-shutdown. Besides carrying a return value, this argument may be
-logically OR'd with
-.IR PAM_DATA_SILENT
-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
-.IR fork "(2)ed"
-process, and that the parent will take care of cleaning up things that
-exist outside of the current process space (files etc.).
-
-.SH "RETURN VALUE"
+PAM_BUF_ERR
+Memory buffer error.
.TP
-.B pam_start
+PAM_SUCCESS
+Transaction was successful created.
.TP
-.B pam_end
-On success,
-.BR PAM_SUCCESS
-is returned
-
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(3). "
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-.sp
-Note, the
-.BR PAM_DATA_SILENT
-flag is pending acceptance with the DCE (as of 1996/12/4).
-
-.SH BUGS
-.sp 2
-None known.
-
+PAM_SYSTEM_ERR
+System error, for example a NULL pointer was submitted instead of a pointer to data.
.SH "SEE ALSO"
-
-.BR fork "(2), "
-.BR pam_authenticate "(3), "
-.BR pam_acct_mgmt "(3), "
-.BR pam_open_session "(3), "
-and
-.BR pam_chauthtok "(3)."
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+.PP
+\fBpam_get_data\fR(3),
+\fBpam_set_data\fR(3),
+\fBpam_end\fR(3),
+\fBpam_strerror\fR(3)
diff --git a/doc/man/pam_start.3.xml b/doc/man/pam_start.3.xml
new file mode 100644
index 00000000..2850b15d
--- /dev/null
+++ b/doc/man/pam_start.3.xml
@@ -0,0 +1,143 @@
+<?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_start'>
+
+ <refmeta>
+ <refentrytitle>pam_start</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_start-name">
+ <refname>pam_start</refname>
+ <refpurpose>initialization of PAM transaction</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id="pam_start-synopsis">
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>int <function>pam_start</function></funcdef>
+ <paramdef>const char *<parameter>service_name</parameter></paramdef>
+ <paramdef>const char *<parameter>user</parameter></paramdef>
+ <paramdef>const struct pam_conv *<parameter>pam_conversation</parameter></paramdef>
+ <paramdef>pam_handle_t **<parameter>pamh</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_start-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_start</function> function creates the PAM context
+ and initiates the PAM transaction. It is the first of the PAM
+ functions that needs to be called by an application.
+ </para>
+
+ <para>
+ The <emphasis>service_name</emphasis> argument specifies the name
+ of the service to apply and will be stored as PAM_SERVICE item in
+ the new context. The policy for the service will be read from the
+ file <filename>/etc/pam.d/service_name</filename> or, if that file
+ does not exist, from <filename>/etc/pam.conf</filename>.
+ </para>
+
+ <para>
+ The <emphasis>user</emphasis> argument can specify the name
+ of the target user and will be stored as PAM_USER item. If
+ the argument is NULL, the module has to ask for this item if
+ necessary.
+ </para>
+
+ <para>
+ The <emphasis>pam_conversation</emphasis> argument points to
+ a <emphasis>struct pam_conv</emphasis> describing the
+ conversation function to use. An application must provide this
+ for direct communication between a loaded module and the
+ application.
+ </para>
+
+ <para>
+ Following a successful return (PAM_SUCCESS) the contents of
+ <emphasis>pamh</emphasis> is a handle that contains the PAM
+ context for successive calls to the PAM functions. In an error
+ case is the content of <emphasis>pamh</emphasis> undefined.
+ </para>
+
+ <para>
+ The <emphasis>pam_handle_t</emphasis> is a blind structure and
+ the application should not attempt to probe it directly for
+ information. Instead the PAM library provides the functions
+ <citerefentry>
+ <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry> and
+ <citerefentry>
+ <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>.
+ The PAM handle cannot be used for mulitiple authentications at the
+ same time as long as <function>pam_end</function> was not called on
+ it before.
+ </para>
+ </refsect1>
+ <refsect1 id="pam_start-return_values">
+ <title>RETURN VALUES</title>
+ <variablelist>
+ <varlistentry>
+ <term>PAM_ABORT</term>
+ <listitem>
+ <para>
+ General failure.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_BUF_ERR</term>
+ <listitem>
+ <para>
+ Memory buffer error.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SUCCESS</term>
+ <listitem>
+ <para>
+ Transaction was successful created.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PAM_SYSTEM_ERR</term>
+ <listitem>
+ <para>
+ System error, for example a NULL pointer was submitted
+ instead of a pointer to data.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+
+ <refsect1 id="pam_start-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>,
+ <citerefentry>
+ <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/pam_strerror.3 b/doc/man/pam_strerror.3
index 01ee0635..1a096baf 100644
--- a/doc/man/pam_strerror.3
+++ b/doc/man/pam_strerror.3
@@ -1,51 +1,28 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" ripped off from Rick Faith's getgroups man page
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@linux.kernel.org>
-.TH PAM_STRERROR 3 "1999 Oct 4" "Linux-PAM 0.70" "Programmers' Manual"
-.SH NAME
-
-pam_strerror \- return a textual description of a Linux-PAM error
-
-.SH SYNOPSIS
-.B #include <security/pam_appl.h>
-.br
-or,
-.br
-.B #include <security/pam_modules.h>
-.sp
-.BI "const char * pam_strerror( pam_handle_t " "*pamh" ", int " pam_error ");"
-.sp 2
-.SH DESCRIPTION
-.B pam_strerror
-
-This function returns some text describing the
-.BR Linux-PAM
-error associated with the
-.B pam_error
-argument.
-
-.SH "RETURN VALUE"
-
-On success this function returns a description of the indicated
-error. Should the function not recognize the error, ``Unknown
-Linux-PAM error'' is returned.
-
-.SH "CONFORMING TO"
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-This function should be internationalized.
-
+.\" ** 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_STRERROR" "3" "02/08/2006" "Linux\-PAM Manual" "Linux\-PAM Manual"
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.SH "NAME"
+pam_strerror \- return string describing PAM error code
+.SH "SYNOPSIS"
+.PP
+\fB#include <security/pam_appl.h>\fR
+.HP 25
+\fBconst\ char\ *\fBpam_strerror\fR\fR\fB(\fR\fBpam_handle_t\ *\fR\fB\fIpamh\fR\fR\fB, \fR\fBint\ \fR\fB\fIerrnum\fR\fR\fB);\fR
+.SH "DESCRIPTION"
+.PP
+The
+\fBpam_strerror\fR
+function returns a pointer to a string describing the error code passed in the argument
+\fIerrnum\fR, possibly using the LC_MESSAGES part of the current locale to select the appropriate language. This string must not be modified by the application. No library function will modify this string.
+.SH "RETURN VALUES"
+.PP
+This function returns always a pointer to a string.
.SH "SEE ALSO"
-
-.BR pam "(8). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "
+.PP
+\fBpam\fR(8)
diff --git a/doc/man/pam_strerror.3.xml b/doc/man/pam_strerror.3.xml
new file mode 100644
index 00000000..bc488a21
--- /dev/null
+++ b/doc/man/pam_strerror.3.xml
@@ -0,0 +1,58 @@
+<?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_strerror'>
+
+ <refmeta>
+ <refentrytitle>pam_strerror</refentrytitle>
+ <manvolnum>3</manvolnum>
+ <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
+ </refmeta>
+
+ <refnamediv id="pam_strerror-name">
+ <refname>pam_strerror</refname>
+ <refpurpose>return string describing PAM error code</refpurpose>
+ </refnamediv>
+
+<!-- body begins here -->
+
+ <refsynopsisdiv id="pam_strerror-synopsis">
+ <funcsynopsis>
+ <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
+ <funcprototype>
+ <funcdef>const char *<function>pam_strerror</function></funcdef>
+ <paramdef>pam_handle_t *<parameter>pamh</parameter></paramdef>
+ <paramdef>int <parameter>errnum</parameter></paramdef>
+ </funcprototype>
+ </funcsynopsis>
+ </refsynopsisdiv>
+
+
+ <refsect1 id="pam_strerror-description">
+ <title>DESCRIPTION</title>
+ <para>
+ The <function>pam_strerror</function> function returns a pointer to
+ a string describing the error code passed in the argument
+ <emphasis>errnum</emphasis>, possibly using the LC_MESSAGES part of
+ the current locale to select the appropriate language. This string
+ must not be modified by the application. No library function will
+ modify this string.
+ </para>
+ </refsect1>
+ <refsect1 id="pam_strerror-return_values">
+ <title>RETURN VALUES</title>
+ <para>
+ This function returns always a pointer to a string.
+ </para>
+ </refsect1>
+
+ <refsect1 id="pam_strerror-see_also">
+ <title>SEE ALSO</title>
+ <para>
+ <citerefentry>
+ <refentrytitle>pam</refentrytitle><manvolnum>8</manvolnum>
+ </citerefentry>
+ </para>
+ </refsect1>
+</refentry>
diff --git a/doc/man/template-man b/doc/man/template-man
deleted file mode 100644
index b8159eb6..00000000
--- a/doc/man/template-man
+++ /dev/null
@@ -1,52 +0,0 @@
-.\" Hey Emacs! This file is -*- nroff -*- source.
-.\" $Id$
-.\" Copyright (c) Andrew G. Morgan 1997 <morgan@parc.power.net>
-.TH PAM_???? 2 "1997 Jan 4" "Linux-PAM 0.55" "Application Programmers' Manual"
-.SH NAME
-
-function names \- brief summary of function
-
-.SH SYNOPSIS
-.B #include <security/pam_????.h>
-.sp
-.BI "int pam_???(pam_handle_t " pamh ", int " flags);
-.sp 2
-.SH DESCRIPTION
-.TP
-.B pam_???
-Here goes the
-.I explanation
-it may be quite
-.IR long .
-.TP
-.SH "RETURN VALUE"
-.B pam_???
-On success...
-.BR PAM_SUCCESS
-is returned
-.TP
-.SH ERRORS
-May be translated to text with
-.BR pam_strerror "(2). "
-
-.SH "CONFORMING TO"
-.B pam_???
-DCE-RFC 86.0, October 1995.
-
-.SH BUGS
-.sp 2
-none known.
-
-.SH "SEE ALSO"
-
-.BR pam_??? "(2), "
-and
-.BR pam_??? "(2). "
-
-Also, see the three
-.BR Linux-PAM
-Guides, for
-.BR "System administrators" ", "
-.BR "module developers" ", "
-and
-.BR "application developers" ". "