1PAM_START(3) Linux-PAM Manual PAM_START(3)
2
3
4
6 pam_start, pam_start_confdir - initialization of PAM transaction
7
9 #include <security/pam_appl.h>
10
11 int pam_start(const char *service_name, const char *user,
12 const struct pam_conv *pam_conversation,
13 pam_handle_t **pamh);
14
15 int pam_start_confdir(const char *service_name, const char *user,
16 const struct pam_conv *pam_conversation,
17 const char *confdir, pam_handle_t **pamh);
18
20 The pam_start function creates the PAM context and initiates the PAM
21 transaction. It is the first of the PAM functions that needs to be
22 called by an application. The transaction state is contained entirely
23 within the structure identified by this handle, so it is possible to
24 have multiple transactions in parallel. But it is not possible to use
25 the same handle for different transactions, a new one is needed for
26 every new context.
27
28 The service_name argument specifies the name of the service to apply
29 and will be stored as PAM_SERVICE item in the new context. The policy
30 for the service will be read from the file /etc/pam.d/service_name or,
31 if that file does not exist, from /etc/pam.conf.
32
33 The user argument can specify the name of the target user and will be
34 stored as PAM_USER item. If the argument is NULL, the module has to ask
35 for this item if necessary.
36
37 The pam_conversation argument points to a struct pam_conv describing
38 the conversation function to use. An application must provide this for
39 direct communication between a loaded module and the application.
40
41 Following a successful return (PAM_SUCCESS) the contents of pamh is a
42 handle that contains the PAM context for successive calls to the PAM
43 functions. In an error case is the content of pamh undefined.
44
45 The pam_handle_t is a blind structure and the application should not
46 attempt to probe it directly for information. Instead the PAM library
47 provides the functions pam_set_item(3) and pam_get_item(3). The PAM
48 handle cannot be used for multiple authentications at the same time as
49 long as pam_end was not called on it before.
50
51 The pam_start_confdir function behaves like the pam_start function but
52 it also allows setting confdir argument with a path to a directory to
53 override the default (/etc/pam.d) path for service policy files. If the
54 confdir is NULL, the function works exactly the same as pam_start.
55
57 PAM_ABORT
58 General failure.
59
60 PAM_BUF_ERR
61 Memory buffer error.
62
63 PAM_SUCCESS
64 Transaction was successfully started.
65
66 PAM_SYSTEM_ERR
67 System error, for example a NULL pointer was submitted instead of a
68 pointer to data.
69
71 pam_get_data(3), pam_set_data(3), pam_end(3), pam_strerror(3)
72
73
74
75Linux-PAM Manual 09/03/2021 PAM_START(3)