sasl_client_start() can return SASL_OK with some authentication methods
(PLAIN for example), but the documentation is not very consistent about it.
Sometimes it implies that client code only needs to deal with SASL_CONTINUE
and SASL_INTERACT, sometimes it handles SASL_OK in addition to these 2 values.
This commit tries to make the documentation for this return value
consistent.
---
doc/programming.html | 6 +++---
man/sasl_client_start.3 | 9 ++++++---
2 files changed, 9 insertions(+), 6 deletions(-)
diff --git a/doc/programming.html b/doc/programming.html
index 00fac38..bd30b1c 100644
--- a/doc/programming.html
+++ b/doc/programming.html
@@ -340,7 +340,7 @@ begin the authentication process.
} while (result==SASL_INTERACT); /* the mechanism may ask us to fill
in things many times. result is
SASL_CONTINUE on success */
- if (result!=SASL_CONTINUE) [failure]
+ if (result!=SASL_CONTINUE && result!=SASL_OK) [failure]
</pre>
@@ -391,8 +391,8 @@ in IMAP.</li>
</ol>
Convert the continuation data to binary format (for example, this
-may include base64 decoding it). Perform another step in the
-authentication.
+may include base64 decoding it). If sasl_client_start() returned
+SASL_CONTINUE, perform another step in the authentication.
<pre>
do {
diff --git a/man/sasl_client_start.3 b/man/sasl_client_start.3
index a37cff7..533abb5 100644
--- a/man/sasl_client_start.3
+++ b/man/sasl_client_start.3
@@ -64,6 +64,9 @@ upon the security preferences specified earlier. The list of
mechanisms is typically a list of mechanisms the server supports
acquired from a capability request.
+It returns SASL_OK if no more authentication steps are needed, and
+SASL_CONTINUE if at least one more step is needed.
+
If SASL_INTERACT is returned the library needs some values to be
filled in before it can proceed. The prompt_need structure will be
filled in with requests. The application should fulfill these requests
@@ -102,9 +105,9 @@ contains the name of the chosen SASL mechanism (on success)
sasl_client_start returns an integer which corresponds to one of the
following codes. SASL_CONTINUE indicates success and that there are
-more steps needed in the authentication. All other return codes
-indicate errors and should either be handled or the authentication
-session should be quit.
+more steps needed in the authentication. SASL_OK indicates that the
+authentication is complete. All other return codes indicate errors and
+should either be handled or the authentication session should be quit.
.SH "CONFORMING TO"
RFC 4422
--
1.8.4.2
