1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
5 <refentry id='pam_start'>
8 <refentrytitle>pam_start</refentrytitle>
9 <manvolnum>3</manvolnum>
10 <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
13 <refnamediv id="pam_start-name">
14 <refname>pam_start</refname>
15 <refpurpose>initialization of PAM transaction</refpurpose>
18 <!-- body begins here -->
20 <refsynopsisdiv id="pam_start-synopsis">
22 <funcsynopsisinfo>#include <security/pam_appl.h></funcsynopsisinfo>
24 <funcdef>int <function>pam_start</function></funcdef>
25 <paramdef>const char *<parameter>service_name</parameter></paramdef>
26 <paramdef>const char *<parameter>user</parameter></paramdef>
27 <paramdef>const struct pam_conv *<parameter>pam_conversation</parameter></paramdef>
28 <paramdef>pam_handle_t **<parameter>pamh</parameter></paramdef>
34 <refsect1 id="pam_start-description">
35 <title>DESCRIPTION</title>
37 The <function>pam_start</function> function creates the PAM context
38 and initiates the PAM transaction. It is the first of the PAM
39 functions that needs to be called by an application.
43 The <emphasis>service_name</emphasis> argument specifies the name
44 of the service to apply and will be stored as PAM_SERVICE item in
45 the new context. The policy for the service will be read from the
46 file <filename>/etc/pam.d/service_name</filename> or, if that file
47 does not exist, from <filename>/etc/pam.conf</filename>.
51 The <emphasis>user</emphasis> argument can specify the name
52 of the target user and will be stored as PAM_USER item. If
53 the argument is NULL, the module has to ask for this item if
58 The <emphasis>pam_conversation</emphasis> argument points to
59 a <emphasis>struct pam_conv</emphasis> describing the
60 conversation function to use. An application must provide this
61 for direct communication between a loaded module and the
66 Following a successful return (PAM_SUCCESS) the contents of
67 <emphasis>pamh</emphasis> is a handle that contains the PAM
68 context for successive calls to the PAM functions. In an error
69 case is the content of <emphasis>pamh</emphasis> undefined.
73 The <emphasis>pam_handle_t</emphasis> is a blind structure and
74 the application should not attempt to probe it directly for
75 information. Instead the PAM library provides the functions
77 <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
80 <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
82 The PAM handle cannot be used for mulitiple authentications at the
83 same time as long as <function>pam_end</function> was not called on
87 <refsect1 id="pam_start-return_values">
88 <title>RETURN VALUES</title>
91 <term>PAM_ABORT</term>
99 <term>PAM_BUF_ERR</term>
107 <term>PAM_SUCCESS</term>
110 Transaction was successful created.
115 <term>PAM_SYSTEM_ERR</term>
118 System error, for example a NULL pointer was submitted
119 instead of a pointer to data.
126 <refsect1 id="pam_start-see_also">
127 <title>SEE ALSO</title>
130 <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
133 <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
136 <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
139 <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>