0c3c595d6bd0195ee49b2c1c1e4e0cbcdfaac1e1
[dragonfly.git] / contrib / libpam / doc / man / pam_authenticate.3
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 $
4 .\" $DragonFly: src/contrib/libpam/doc/man/Attic/pam_authenticate.3,v 1.2 2003/06/17 04:24:02 dillon Exp $
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
9 pam_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
20 Use this function to authenticate an applicant user.  It is linked
21 .I dynamically
22 to the authentication modules by
23 .BR PAM ". "
24 It is the task of these module to perform such an authentication.  The
25 specific nature of the authentication is not the concern of the
26 application.
27
28 .br
29 Following successful completion, the
30 .BR name
31 of the authenticated user will be present in the
32 .BR PAM
33 item
34 .BR PAM_USER ". "
35 This item may be recovered with a call to
36 .BR pam_get_item "(3)."
37
38 .br
39 The application developer should note that the modules may request
40 that the user enter their username via the conversation mechanism (see
41 .BR pam_start "(3))."
42 Should this be the case, the user-prompt string can be set via
43 the
44 .BR PAM_USER_PROMPT
45 item (see
46 .BR pam_set_item "(3))."
47
48 .SH "RETURN VALUE"
49 On success
50 .BR PAM_SUCCESS
51 is returned.  All other returns should be considered
52 authentication failures and will be
53 .I delayed
54 by an amount specified with prior calls to
55 .BR pam_fail_delay "(3). "
56 Specific failures that demand special attention are the following:
57 .TP
58 .B PAM_ABORT
59 the application should exit immediately. Of course,
60 .BR pam_end "(3)"
61 should be called first.
62
63 .TP
64 .B PAM_MAXTRIES
65 the application has tried too many times to authenticate the
66 user, authentication should not be attempted again.
67
68 .SH ERRORS
69 May be translated to text with
70 .BR pam_strerror "(3). "
71
72 .SH "CONFORMING TO"
73 DCE-RFC 86.0, October 1995.
74
75 .SH BUGS
76 .sp 2
77 none known.
78
79 .SH "SEE ALSO"
80
81 .BR pam_start "(3), "
82 .BR pam_get_item "(3) "
83 .BR pam_fail_delay "(3) "
84 and
85 .BR pam_strerror "(3). "
86
87 Also, see the three
88 .BR PAM
89 Guides, for
90 .BR "System administrators" ", "
91 .BR "module developers" ", "
92 and
93 .BR "application developers" ". "