Add the DragonFly cvs id and perform general cleanups on cvs/rcs/sccs ids. Most
[dragonfly.git] / contrib / libpam / doc / man / pam_authenticate.3
CommitLineData
984263bc
MD
1.\" Hey Emacs! This file is -*- nroff -*- source.
2.\" $Id: pam_authenticate.3,v 1.2 1997/02/15 18:39:59 morgan Exp $
3.\" $FreeBSD: src/contrib/libpam/doc/man/pam_authenticate.3,v 1.2.6.2 2001/06/11 15:28:11 markm Exp $
1de703da 4.\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_authenticate.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
984263bc
MD
5.\" Copyright (c) Andrew G. Morgan 1996-7 <morgan@parc.power.net>
6.TH PAM_AUTHENTICATE 3 "1996 Dec 9" "PAM 0.55" "App. Programmers' Manual"
7.SH NAME
8
9pam_authenticate \- authenticate a user
10
11.SH SYNOPSIS
12.B #include <security/pam_appl.h>
13.sp
14.BI "int pam_authenticate(pam_handle_t " *pamh ", int " flags ");"
15.sp 2
16.SH DESCRIPTION
17.B pam_authenticate
18
19.br
20Use this function to authenticate an applicant user. It is linked
21.I dynamically
22to the authentication modules by
23.BR PAM ". "
24It is the task of these module to perform such an authentication. The
25specific nature of the authentication is not the concern of the
26application.
27
28.br
29Following successful completion, the
30.BR name
31of the authenticated user will be present in the
32.BR PAM
33item
34.BR PAM_USER ". "
35This item may be recovered with a call to
36.BR pam_get_item "(3)."
37
38.br
39The application developer should note that the modules may request
40that the user enter their username via the conversation mechanism (see
41.BR pam_start "(3))."
42Should this be the case, the user-prompt string can be set via
43the
44.BR PAM_USER_PROMPT
45item (see
46.BR pam_set_item "(3))."
47
48.SH "RETURN VALUE"
49On success
50.BR PAM_SUCCESS
51is returned. All other returns should be considered
52authentication failures and will be
53.I delayed
54by an amount specified with prior calls to
55.BR pam_fail_delay "(3). "
56Specific failures that demand special attention are the following:
57.TP
58.B PAM_ABORT
59the application should exit immediately. Of course,
60.BR pam_end "(3)"
61should be called first.
62
63.TP
64.B PAM_MAXTRIES
65the application has tried too many times to authenticate the
66user, authentication should not be attempted again.
67
68.SH ERRORS
69May be translated to text with
70.BR pam_strerror "(3). "
71
72.SH "CONFORMING TO"
73DCE-RFC 86.0, October 1995.
74
75.SH BUGS
76.sp 2
77none known.
78
79.SH "SEE ALSO"
80
81.BR pam_start "(3), "
82.BR pam_get_item "(3) "
83.BR pam_fail_delay "(3) "
84and
85.BR pam_strerror "(3). "
86
87Also, see the three
88.BR PAM
89Guides, for
90.BR "System administrators" ", "
91.BR "module developers" ", "
92and
93.BR "application developers" ". "