<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                   "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">

<refentry id='pam_start'>

  <refmeta>
    <refentrytitle>pam_start</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo class='setdesc'>Linux-PAM Manual</refmiscinfo>
  </refmeta>

  <refnamediv id="pam_start-name">
    <refname>pam_start</refname>
    <refpurpose>initialization of PAM transaction</refpurpose>
  </refnamediv>

<!-- body begins here -->

  <refsynopsisdiv>
    <funcsynopsis id="pam_start-synopsis">
      <funcsynopsisinfo>#include &lt;security/pam_appl.h&gt;</funcsynopsisinfo>
      <funcprototype>
        <funcdef>int <function>pam_start</function></funcdef>
        <paramdef>const char *<parameter>service_name</parameter></paramdef>
        <paramdef>const char *<parameter>user</parameter></paramdef>
        <paramdef>const struct pam_conv *<parameter>pam_conversation</parameter></paramdef>
        <paramdef>pam_handle_t **<parameter>pamh</parameter></paramdef>
      </funcprototype>
    </funcsynopsis>
  </refsynopsisdiv>


  <refsect1 id="pam_start-description">
    <title>DESCRIPTION</title>
    <para>
      The <function>pam_start</function> 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.
    </para>

    <para>
      The <emphasis>service_name</emphasis> 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 <filename>/etc/pam.d/service_name</filename> or, if that file
      does not exist, from <filename>/etc/pam.conf</filename>.
    </para>

    <para>
       The <emphasis>user</emphasis> 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.
    </para>

    <para>
       The <emphasis>pam_conversation</emphasis> argument points to
       a <emphasis>struct pam_conv</emphasis> describing the
       conversation function to use. An application must provide this
       for direct communication between a loaded module and the
       application.
    </para>

    <para>
       Following a successful return (PAM_SUCCESS) the contents of
       <emphasis>pamh</emphasis> is a handle that contains the PAM
       context for successive calls to the PAM functions. In an error
       case is the content of <emphasis>pamh</emphasis> undefined.
    </para>

    <para>
      The <emphasis>pam_handle_t</emphasis> is a blind structure and
      the application should not attempt to probe it directly for
      information. Instead the PAM library provides the functions
      <citerefentry>
        <refentrytitle>pam_set_item</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry> and
      <citerefentry>
        <refentrytitle>pam_get_item</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>.
      The PAM handle cannot be used for mulitiple authentications at the
      same time as long as <function>pam_end</function> was not called on
      it before.
    </para>
  </refsect1>
  <refsect1 id="pam_start-return_values">
    <title>RETURN VALUES</title>
    <variablelist>
      <varlistentry>
        <term>PAM_ABORT</term>
        <listitem>
           <para>
              General failure.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_BUF_ERR</term>
        <listitem>
           <para>
              Memory buffer error.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SUCCESS</term>
        <listitem>
           <para>
             Transaction was successful created.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>PAM_SYSTEM_ERR</term>
        <listitem>
           <para>
              System error, for example a NULL pointer was submitted
              instead of a pointer to data.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1 id="pam_start-see_also">
    <title>SEE ALSO</title>
    <para>
      <citerefentry>
        <refentrytitle>pam_get_data</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_set_data</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_end</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>,
      <citerefentry>
        <refentrytitle>pam_strerror</refentrytitle><manvolnum>3</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>