Gecko [ nbspublicschool.com ]

Name	Size	Permission
Linux-PAM_ADG.html	8.41 KB	-rw-r--r--
Linux-PAM_MWG.html	8.59 KB	-rw-r--r--
adg-author.html	3.02 KB	-rw-r--r--
adg-copyright.html	3.54 KB	-rw-r--r--
adg-example.html	3.59 KB	-rw-r--r--
adg-files.html	2.18 KB	-rw-r--r--
adg-glossary.html	3.21 KB	-rw-r--r--
adg-interface-by-app-expected....	61.01 KB	-rw-r--r--
adg-interface-of-app-expected....	8.26 KB	-rw-r--r--
adg-interface-programming-note...	2.55 KB	-rw-r--r--
adg-interface.html	4.9 KB	-rw-r--r--
adg-introduction-description.h...	3.29 KB	-rw-r--r--
adg-introduction-synopsis.html	2.62 KB	-rw-r--r--
adg-introduction.html	2.01 KB	-rw-r--r--
adg-libpam-functions.html	13.13 KB	-rw-r--r--
adg-libpam_misc.html	3.34 KB	-rw-r--r--
adg-overview.html	8.16 KB	-rw-r--r--
adg-porting.html	4.2 KB	-rw-r--r--
adg-security-conv-function.htm...	2.29 KB	-rw-r--r--
adg-security-library-calls.htm...	3.13 KB	-rw-r--r--
adg-security-resources.html	2.83 KB	-rw-r--r--
adg-security-service-name.html	4.43 KB	-rw-r--r--
adg-security-user-identity.htm...	5.38 KB	-rw-r--r--
adg-security.html	3.73 KB	-rw-r--r--
adg-see-also.html	2.16 KB	-rw-r--r--
mwg-author.html	3 KB	-rw-r--r--
mwg-copyright.html	3.52 KB	-rw-r--r--
mwg-example.html	1.96 KB	-rw-r--r--
mwg-expected-by-module-item.ht...	45.36 KB	-rw-r--r--
mwg-expected-by-module-other.h...	8.15 KB	-rw-r--r--
mwg-expected-by-module.html	4.02 KB	-rw-r--r--
mwg-expected-of-module-acct.ht...	6.05 KB	-rw-r--r--
mwg-expected-of-module-auth.ht...	10.73 KB	-rw-r--r--
mwg-expected-of-module-chautht...	7.8 KB	-rw-r--r--
mwg-expected-of-module-overvie...	6.28 KB	-rw-r--r--
mwg-expected-of-module-session...	6.98 KB	-rw-r--r--
mwg-expected-of-module.html	4.27 KB	-rw-r--r--
mwg-introduction-description.h...	3.88 KB	-rw-r--r--
mwg-introduction-synopsis.html	1.98 KB	-rw-r--r--
mwg-introduction.html	1.98 KB	-rw-r--r--
mwg-see-also.html	2.18 KB	-rw-r--r--
mwg-see-options.html	2.92 KB	-rw-r--r--
mwg-see-programming-libs.html	2.94 KB	-rw-r--r--
mwg-see-programming-sec.html	8.92 KB	-rw-r--r--
mwg-see-programming-syslog.htm...	4.63 KB	-rw-r--r--
mwg-see-programming.html	3 KB	-rw-r--r--

Code Editor : adg-interface-of-app-expected.html

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>3.2. What is expected of an application</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="Linux-PAM_ADG.html" title="The Linux-PAM Application Developers' Guide"><link rel="up" href="adg-interface.html" title="Chapter 3.  The public interface to Linux-PAM"><link rel="prev" href="adg-interface-by-app-expected.html" title="3.1. What can be expected by the application"><link rel="next" href="adg-interface-programming-notes.html" title="3.3. Programming notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.2. What is expected of an application</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="adg-interface-by-app-expected.html">Prev</a> </td><th width="60%" align="center">Chapter 3. 
      The public interface to <span class="emphasis"><em>Linux-PAM</em></span>
    </th><td width="20%" align="right"> <a accesskey="n" href="adg-interface-programming-notes.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="adg-interface-of-app-expected"></a>3.2. What is expected of an application</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="adg-pam_conv"></a>3.2.1. The conversation function</h3></div></div></div><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;security/pam_appl.h&gt;</pre></div><pre class="programlisting">
struct pam_message {
    int msg_style;
    const char *msg;
};

struct pam_response {
    char *resp;
    int resp_retcode;
};

struct pam_conv {
    int (*conv)(int num_msg, const struct pam_message **msg,
                struct pam_response **resp, void *appdata_ptr);
    void *appdata_ptr;
};
  </pre><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="adg-pam_conv-description"></a>3.2.1.1. DESCRIPTION</h4></div></div></div><p>
      The PAM library uses an application-defined callback to allow
      a direct communication between a loaded module and the application.
      This callback is specified by the
      <span class="emphasis"><em>struct pam_conv</em></span> passed to
      <span class="citerefentry"><span class="refentrytitle">pam_start</span>(3)</span>
      at the start of the transaction.
    </p><p>
      When a module calls the referenced conv() function, the argument
      <span class="emphasis"><em>appdata_ptr</em></span> is set to the second element of
      this structure.
    </p><p>
      The other arguments of a call to conv() concern the information
      exchanged by module and application. That is to say,
      <span class="emphasis"><em>num_msg</em></span> holds the length of the array of
      pointers, <span class="emphasis"><em>msg</em></span>. After a successful return, the
      pointer <span class="emphasis"><em>resp</em></span> points to an array of pam_response
      structures, holding the application supplied text. The
      <span class="emphasis"><em>resp_retcode</em></span> member of this struct is unused and
      should be set to zero. It is the caller's responsibility to release
      both, this array and the responses themselves, using
      <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>. Note, <span class="emphasis"><em>*resp</em></span> is a
      <span class="emphasis"><em>struct pam_response</em></span> array and not an array of
      pointers.
    </p><p>
      The number of responses is always equal to the
      <span class="emphasis"><em>num_msg</em></span> conversation function argument.
      This does require that the response array is
      <span class="citerefentry"><span class="refentrytitle">free</span>(3)</span>'d after
      every call to the conversation function.  The index of the
      responses corresponds directly to the prompt index in the
      pam_message array.
    </p><p>
      On failure, the conversation function should release any resources
      it has allocated, and return one of the predefined PAM error codes.
    </p><p>
      Each message can have one of four types, specified by the
      <span class="emphasis"><em>msg_style</em></span> member of
      <span class="emphasis"><em>struct pam_message</em></span>:
    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term">PAM_PROMPT_ECHO_OFF</span></dt><dd><p>
             Obtain a string without echoing any text.
          </p></dd><dt><span class="term">PAM_PROMPT_ECHO_ON</span></dt><dd><p>
            Obtain a string whilst echoing text.
          </p></dd><dt><span class="term">PAM_ERROR_MSG</span></dt><dd><p>
            Display an error message.
          </p></dd><dt><span class="term">PAM_TEXT_INFO</span></dt><dd><p>
            Display some text.
          </p></dd></dl></div><p>
      The point of having an array of messages is that it becomes possible
      to pass a number of things to the application in a single call from
      the module. It can also be convenient for the application that related
      things come at once: a windows based application can then present a
      single form with many messages/prompts on at once.
    </p><p>
      In passing, it is worth noting that there is a descrepency between
      the way Linux-PAM handles the const struct pam_message **msg
      conversation function argument from the way that Solaris' PAM
      (and derivitives, known to include HP/UX, are there others?) does.
      Linux-PAM interprets the msg argument as entirely equivalent to the
      following prototype
  const struct pam_message *msg[] (which, in spirit, is consistent with
  the commonly used prototypes for argv argument to the familiar main()
  function: char **argv; and char *argv[]). Said another way Linux-PAM
  interprets the msg argument as a pointer to an array of num_msg read
  only 'struct pam_message' pointers.  Solaris' PAM implementation
  interprets this argument as a pointer to a pointer to an array of
  num_msg pam_message structures.  Fortunately, perhaps, for most
  module/application developers when num_msg has a value of one these
  two definitions are entirely equivalent. Unfortunately, casually
  raising this number to two has led to unanticipated compatibility
  problems.
    </p><p>
  For what its worth the two known module writer work-arounds for trying
  to maintain source level compatibility with both PAM implementations
  are:
    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
          never call the conversation function with num_msg greater than one.
        </p></li><li class="listitem"><p>
          set up msg as doubly referenced so both types of conversation
          function can find the messages. That is, make
        </p><pre class="programlisting">
       msg[n] = &amp; (( *msg )[n])
       </pre></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="adg-pam_conv-return_values"></a>3.2.1.2. RETURN VALUES</h4></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">PAM_BUF_ERR</span></dt><dd><p>
             Memory buffer error.
          </p></dd><dt><span class="term">PAM_CONV_ERR</span></dt><dd><p>
             Conversation failure. The application should not set
             <span class="emphasis"><em>*resp</em></span>.
          </p></dd><dt><span class="term">PAM_SUCCESS</span></dt><dd><p>
             Success.
          </p></dd></dl></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="adg-interface-by-app-expected.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="adg-interface.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="adg-interface-programming-notes.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.1. What can be expected by the application </td><td width="20%" align="center"><a accesskey="h" href="Linux-PAM_ADG.html">Home</a></td><td width="40%" align="right" valign="top"> 3.3. Programming notes</td></tr></table></div></body></html>

${this.title}

Code Editor : adg-interface-of-app-expected.html