summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorAndrew G. Morgan <morgan@kernel.org>2002-01-19 06:13:53 +0000
committerAndrew G. Morgan <morgan@kernel.org>2002-01-19 06:13:53 +0000
commit14d7d6bc3cec5cb6d971e452c5370eb8644da55e (patch)
treef11654d0589b59c8da23f03dcc7caf770018cb81 /doc
parent2d1c82bb519e5fd9c09baaf8f43db1998c4f575f (diff)
Relevant BUGIDs: task 43507
Purpose of commit: documentation Commit summary: --------------- a little background on the msg argument of the conversation function.
Diffstat (limited to 'doc')
-rw-r--r--doc/pam_appl.sgml47
1 files changed, 40 insertions, 7 deletions
diff --git a/doc/pam_appl.sgml b/doc/pam_appl.sgml
index 87c9e6e3..e730280f 100644
--- a/doc/pam_appl.sgml
+++ b/doc/pam_appl.sgml
@@ -994,6 +994,40 @@ things come at once: a windows based application can then present a
single form with many messages/prompts on at once.
<p>
+In passing, it is worth noting that there is a descrepency between the
+way Linux-PAM handles the <tt/const struct pam_message **msg/
+conversation function argument from the way that Solaris' PAM (and
+derivitives, known to include HP/UX, <em/are there others?/)
+does. Linux-PAM interprets the <tt/msg/ argument as entirely
+equivalent to the following prototype <tt/const struct pam_message
+*msg[]/ (which, in spirit, is consistent with the commonly used
+prototypes for <tt/argv/ argument to the familiar <tt/main()/
+function: <tt/char **argv/; and <tt/char *argv[]/). Said another way
+Linux-PAM interprets the <tt/msg/ argument as a pointer to an array of
+<tt/num_meg/ read only 'struct pam_message' <em/pointers/. Solaris'
+PAM implementation interprets this argument as a pointer to a pointer
+to an array of <tt/num_meg/ <tt/pam_message/ structures. Fortunately,
+perhaps, for most module/application developers when <tt/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>
+For what its worth the two known module writer work-arounds for trying
+to maintain source level compatibility with both PAM implementations
+are:
+<itemize>
+<item> never call the conversation function with <tt/num_msg/ greater
+than one.
+<item> set up <tt/msg/ as doubly referenced so both types of
+conversation function can find the messages. That is, make
+<p><tscreen>
+<verb>
+msg[n] = & (( *msg )[n])
+</verb>
+</tscreen>
+</itemize>
+<p>
The response (from the application to the module) passing structure is
defined by including <tt>&lt;security/pam_appl.h&gt;</tt> as:
@@ -1018,13 +1052,12 @@ called. This meant that it was not always necessary for the module to
to display some text.
<p>
-Post Linux-PAM-0.59 (and in the interests of compatibility with
-Sunsoft). The number of responses is always equal to the <tt/num_msg/
-conversation function argument. This is slightly easier to program
-but does require that the response array is <tt/free(3)/'d after every
-call to the conversation function. The index of the responses
-corresponds directly to the prompt index in the <tt/pam_message/
-array.
+Post Linux-PAM-0.59. The number of responses is always equal to the
+<tt/num_msg/ conversation function argument. This is slightly easier
+to program but does require that the response array is <tt/free(3)/'d
+after every call to the conversation function. The index of the
+responses corresponds directly to the prompt index in the
+<tt/pam_message/ array.
<p>
The maximum length of the <tt/pam_msg.msg/ and <tt/pam_response.resp/