Initial revision

1 files changed, 91 insertions, 0 deletions

diff --git a/doc/man/pam_authenticate.3 b/doc/man/pam_authenticate.3
new file mode 100644
index 00000000..ba1bc52e
--- /dev/null
+++ b/doc/man/pam_authenticate.3
@@ -0,0 +1,91 @@
+.\" 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:
+.TP
+.B PAM_ABORT
+the application should exit immediately. Of course,
+.BR pam_end "(3)"
+should be called first.
+
+.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.
+
+.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" ". "