Debian Codegraph @

upstream/debian-unstable/man3/pam_start.3

raw
1 '\" t
2 .\" Title: pam_start
3 .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
5 .\" Date: 06/29/2025
6 .\" Manual: Linux-PAM Manual
7 .\" Source: Linux-PAM
8 .\" Language: English
9 .\"
10 .TH "PAM_START" "3" "06/29/2025" "Linux\-PAM" "Linux\-PAM Manual"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 pam_start, pam_start_confdir \- initialization of PAM transaction
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <security/pam_appl\&.h>
37 .fi
38 .ft
39 .HP \w'int\ pam_start('u
40 .BI "int pam_start(const\ char\ *" "service_name" ", const\ char\ *" "user" ", const\ struct\ pam_conv\ *" "pam_conversation" ", pam_handle_t\ **" "pamh" ");"
41 .HP \w'int\ pam_start_confdir('u
42 .BI "int pam_start_confdir(const\ char\ *" "service_name" ", const\ char\ *" "user" ", const\ struct\ pam_conv\ *" "pam_conversation" ", const\ char\ *" "confdir" ", pam_handle_t\ **" "pamh" ");"
43 .SH "DESCRIPTION"
44 .PP
45 The
46 \fBpam_start\fR
47 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\&. The transaction state is contained entirely within the structure identified by this handle, so it is possible to have multiple transactions in parallel\&. But it is not possible to use the same handle for different transactions, a new one is needed for every new context\&.
48 .PP
49 The
50 \fIservice_name\fR
51 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
52 /etc/pam\&.d/service_name
53 or, if that file does not exist, from
54 /etc/pam\&.conf\&.
55 .PP
56 The
57 \fIuser\fR
58 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\&.
59 .PP
60 The
61 \fIpam_conversation\fR
62 argument points to a
63 \fIstruct pam_conv\fR
64 describing the conversation function to use\&. An application must provide this for direct communication between a loaded module and the application\&.
65 .PP
66 Following a successful return (PAM_SUCCESS) the contents of
67 \fIpamh\fR
68 is a handle that contains the PAM context for successive calls to the PAM functions\&. In an error case is the content of
69 \fIpamh\fR
70 undefined\&.
71 .PP
72 The
73 \fIpam_handle_t\fR
74 is a blind structure and the application should not attempt to probe it directly for information\&. Instead the PAM library provides the functions
75 \fBpam_set_item\fR(3)
76 and
77 \fBpam_get_item\fR(3)\&. The PAM handle cannot be used for multiple authentications at the same time as long as
78 \fBpam_end\fR
79 was not called on it before\&.
80 .PP
81 The
82 \fBpam_start_confdir\fR
83 function behaves like the
84 \fBpam_start\fR
85 function but it also allows setting
86 \fIconfdir\fR
87 argument with a path to a directory to override the default (/etc/pam\&.d) path for service policy files\&. If the
88 \fIconfdir\fR
89 is NULL, the function works exactly the same as
90 \fBpam_start\fR\&.
91 .SH "RETURN VALUES"
92 .PP
93 PAM_ABORT
94 .RS 4
95 General failure\&.
96 .RE
97 .PP
98 PAM_BUF_ERR
99 .RS 4
100 Memory buffer error\&.
101 .RE
102 .PP
103 PAM_SUCCESS
104 .RS 4
105 Transaction was successfully started\&.
106 .RE
107 .PP
108 PAM_SYSTEM_ERR
109 .RS 4
110 System error, for example a NULL pointer was submitted instead of a pointer to data\&.
111 .RE
112 .SH "SEE ALSO"
113 .PP
114 \fBpam_get_data\fR(3),
115 \fBpam_set_data\fR(3),
116 \fBpam_end\fR(3),
117 \fBpam_strerror\fR(3)