update documentation on GNUTLS_AUTO_REAUTH and gnutls_record_get_direction [ci skip]

That clarifiesthe intention, and adds warning of using this flag when
multiple threads are involved. Based on suggestion by Michael Catanzaro.

Relates: #615

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

2 files changed, 14 insertions, 9 deletions

diff --git a/lib/includes/gnutls/gnutls.h.in b/lib/includes/gnutls/gnutls.h.in
index 789e374315..73141a3a3b 100644
--- a/lib/includes/gnutls/gnutls.h.in
+++ b/lib/includes/gnutls/gnutls.h.in
@@ -425,9 +425,11 @@ typedef enum {
  * @GNUTLS_AUTO_REAUTH: Enable transparent re-authentication in client side when the server
  *    requests to. That is, reauthentication is handled within gnutls_record_recv(), and
  *    the %GNUTLS_E_REHANDSHAKE or %GNUTLS_E_REAUTH_REQUEST are not returned. This must be
- *    enabled with %GNUTLS_POST_HANDSHAKE_AUTH for TLS1.3, and it requires to restore interrupted
- *    calls to gnutls_record_recv() based on the output of gnutls_record_get_direction(), i.e.,
- *    gnutls_record_recv() could also be interrupted when sending when this flag is enabled.
+ *    enabled with %GNUTLS_POST_HANDSHAKE_AUTH for TLS1.3. Enabling this flag requires to restore
+ *    interrupted calls to gnutls_record_recv() based on the output of gnutls_record_get_direction(),
+ *    since gnutls_record_recv() could be interrupted when sending when this flag is enabled.
+ *    Note this flag may not be used if you are using the same session for sending and receiving
+ *    in different threads.
  *
  * Enumeration of different flags for gnutls_init() function. All the flags
  * can be combined except @GNUTLS_SERVER and @GNUTLS_CLIENT which are mutually
diff --git a/lib/state.c b/lib/state.c
index 01288ad474..5364d5e727 100644
--- a/lib/state.c
+++ b/lib/state.c
@@ -1052,12 +1052,15 @@ void
  * gnutls_record_get_direction:
  * @session: is a #gnutls_session_t type.
  *
- * This function provides information about the internals of the
- * record protocol and is only useful if a prior gnutls function call,
- * e.g.  gnutls_handshake(), was interrupted for some reason. That
- * is, if a function returned %GNUTLS_E_INTERRUPTED or
- * %GNUTLS_E_AGAIN. In such a case, you might want to call select()
- * or poll() before restoring the interrupted gnutls function.
+ * This function is useful to determine whether a GnuTLS function was interrupted
+ * while sending or receiving, so that select() or poll() may be called appropriately.
+ *
+ * It provides information about the internals of the record
+ * protocol and is only useful if a prior gnutls function call,
+ * e.g.  gnutls_handshake(), was interrupted and returned
+ * %GNUTLS_E_INTERRUPTED or %GNUTLS_E_AGAIN. After such an interrupt
+ * applications may call select() or poll() before restoring the
+ * interrupted GnuTLS function.
  *
  * This function's output is unreliable if you are using the same
  * @session in different threads, for sending and receiving.