granicus.if.org Git - linux-pam/blob - doc/man/pam_start.3.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   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">
   4
   5 <refentry id='pam_start'>
   6
   7   <refmeta>
   8     <refentrytitle>pam_start</refentrytitle>
   9     <manvolnum>3</manvolnum>
  10     <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv id="pam_start-name">
  14     <refname>pam_start</refname>
  15     <refpurpose>initialization of PAM transaction</refpurpose>
  16   </refnamediv>
  17
  18 <!-- body begins here -->
  19
  20   <refsynopsisdiv>
  21     <funcsynopsis id="pam_start-synopsis">
  22       <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
  23       <funcprototype>
  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>
  29       </funcprototype>
  30     </funcsynopsis>
  31   </refsynopsisdiv>
  32
  33
  34   <refsect1 id="pam_start-description">
  35     <title>DESCRIPTION</title>
  36     <para>
  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. The transaction
  40       state is contained entirely within the structure identified by this
  41       handle, so it is possible to have multiple transactions in parallel.
  42       But it is not possible to use the same handle for different
  43       transactions, a new one is needed for every new context.
  44     </para>
  45
  46     <para>
  47       The <emphasis>service_name</emphasis> argument specifies the name
  48       of the service to apply and will be stored as PAM_SERVICE item in
  49       the new context. The policy for the service will be read from the
  50       file <filename>/etc/pam.d/service_name</filename> or, if that file
  51       does not exist, from <filename>/etc/pam.conf</filename>.
  52     </para>
  53
  54     <para>
  55        The <emphasis>user</emphasis> argument can specify the name
  56        of the target user and will be stored as PAM_USER item. If
  57        the argument is NULL, the module has to ask for this item if
  58        necessary.
  59     </para>
  60
  61     <para>
  62        The <emphasis>pam_conversation</emphasis> argument points to
  63        a <emphasis>struct pam_conv</emphasis> describing the
  64        conversation function to use. An application must provide this
  65        for direct communication between a loaded module and the
  66        application.
  67     </para>
  68
  69     <para>
  70        Following a successful return (PAM_SUCCESS) the contents of
  71        <emphasis>pamh</emphasis> is a handle that contains the PAM
  72        context for successive calls to the PAM functions. In an error
  73        case is the content of <emphasis>pamh</emphasis> undefined.
  74     </para>
  75
  76     <para>
  77       The <emphasis>pam_handle_t</emphasis> is a blind structure and
  78       the application should not attempt to probe it directly for
  79       information. Instead the PAM library provides the functions
  80       <citerefentry>
  81         <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
  82       </citerefentry> and
  83       <citerefentry>
  84         <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
  85       </citerefentry>.
  86       The PAM handle cannot be used for mulitiple authentications at the
  87       same time as long as <function>pam_end</function> was not called on
  88       it before.
  89     </para>
  90   </refsect1>
  91   <refsect1 id="pam_start-return_values">
  92     <title>RETURN VALUES</title>
  93     <variablelist>
  94       <varlistentry>
  95         <term>PAM_ABORT</term>
  96         <listitem>
  97            <para>
  98               General failure.
  99           </para>
 100         </listitem>
 101       </varlistentry>
 102       <varlistentry>
 103         <term>PAM_BUF_ERR</term>
 104         <listitem>
 105            <para>
 106               Memory buffer error.
 107           </para>
 108         </listitem>
 109       </varlistentry>
 110       <varlistentry>
 111         <term>PAM_SUCCESS</term>
 112         <listitem>
 113            <para>
 114              Transaction was successful created.
 115           </para>
 116         </listitem>
 117       </varlistentry>
 118       <varlistentry>
 119         <term>PAM_SYSTEM_ERR</term>
 120         <listitem>
 121            <para>
 122               System error, for example a NULL pointer was submitted
 123               instead of a pointer to data.
 124           </para>
 125         </listitem>
 126       </varlistentry>
 127     </variablelist>
 128   </refsect1>
 129
 130   <refsect1 id="pam_start-see_also">
 131     <title>SEE ALSO</title>
 132     <para>
 133       <citerefentry>
 134         <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
 135       </citerefentry>,
 136       <citerefentry>
 137         <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
 138       </citerefentry>,
 139       <citerefentry>
 140         <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
 141       </citerefentry>,
 142       <citerefentry>
 143         <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
 144       </citerefentry>
 145     </para>
 146   </refsect1>
 147 </refentry>