documentation updates

4 files changed, 47 insertions, 55 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index d7df236e5c..8d18e4147e 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -136,8 +136,10 @@ The credentials used for the key exchange method, such as certificates
 or usernames and passwords should also be associated with the session
 current session using @funcref{gnutls_credentials_set} (see @ref{Authentication methods}). 
 
+@subsection Setting up the transport layer
+
 The next step is to setup the underlying transport layer details. The
-Berkeley sockets for TCP are implicitly used by default in GnuTLS, thus a
+Berkeley sockets are implicitly used by GnuTLS, thus a
 call to @funcref{gnutls_transport_set_ptr2} would be sufficient to
 specify the socket descriptor.
 
@@ -152,15 +154,40 @@ the following functions have to be specified.
 @showfuncdesc{gnutls_transport_set_vec_push_function}
 @showfuncdesc{gnutls_transport_set_pull_function}
 
-In the case of DTLS it is also desirable to override the
-functions above with functions that emulate the operation
+The functions above accept a callback function which
+should return the number of bytes written, or -1 on
+error and should set @code{errno} appropriately.
+In some environments, setting @code{errno} is unreliable. For example
+Windows have several errno variables in different CRTs, or in other
+systems it may be a non thread-local variable.  If this is a concern to
+you, call @funcref{gnutls_transport_set_errno} with the intended errno
+value instead of setting @code{errno} directly.
+
+@showfuncdesc{gnutls_transport_set_errno}
+
+@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
+values and returns the corresponding @acronym{GnuTLS} error codes:
+@itemize
+@item @code{GNUTLS_E_INTERRUPTED} 
+@item @code{GNUTLS_E_AGAIN}
+@end itemize
+The EINTR and EAGAIN values are returned by interrupted system calls, 
+or when non blocking IO is used.  All @acronym{GnuTLS} functions can be 
+resumed (called again), if any of the above error codes is returned.  
+
+In the case of DTLS it is also desirable to override the generic 
+transport functions with functions that emulate the operation
 of @code{recvfrom} and @code{sendto}. In addition
-the following function must also be called to specify a 
-callback that will receive data from within a specified
-time limit.
+@acronym{DTLS} requires timers during the receive of a handshake
+message. This requires the following function to be used.
 
 @showfuncdesc{gnutls_transport_set_pull_timeout_function}
 
+To avoid @acronym{GnuTLS} from blocking in a DTLS handshake on
+a timer, the @funcref{gnutls_init} can be called with the
+@code{GNUTLS_NONBLOCK} flag (see @ref{TLS and DTLS sessions}).
+
+
 @subsection Handshake
 Once a session has been initialized and a network
 connection has been set up, TLS and DTLS protocols
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index ae22d5790a..3cc7941deb 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -64,45 +64,10 @@ protocol.  The protocol layering in TLS is shown in @ref{fig:tls-layers}.
 @acronym{TLS} is not limited to any transport layer and can be used
 above any transport layer, as long as it is a reliable one.  @acronym{DTLS}
 can be used over reliable and unreliable transport layers.
-A set of functions is provided and their purpose is to load to @acronym{GnuTLS} the
-required callbacks to access the transport layer.
-
-@showfuncE{gnutls_transport_set_push_function,gnutls_transport_set_vec_push_function,gnutls_transport_set_pull_timeout_function,gnutls_transport_set_pull_function,gnutls_transport_set_ptr}
-
-The function @funcref{gnutls_transport_set_pull_timeout_function} is only applicable
-to @acronym{DTLS} sessions.
-All those functions accept a callback function as a parameter.  The
-callback functions should return the number of bytes written, or -1 on
-error and should set @code{errno} appropriately.
-
-In some environments, setting @code{errno} is unreliable, for example
-Windows have several errno variables in different CRTs, or it may be
-that errno is not a thread-local variable.  If this is a concern to
-you, call @funcref{gnutls_transport_set_errno} with the intended errno
-value instead of setting @code{errno} directly.
-
-@showfuncA{gnutls_transport_set_errno}
-
-@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
-values and returns the corresponding @acronym{GnuTLS} error codes:
-@itemize
-@item @code{GNUTLS_E_INTERRUPTED} 
-@item @code{GNUTLS_E_AGAIN}
-@end itemize
-These values are usually returned by interrupted system calls, or when non blocking
-IO is used.  All @acronym{GnuTLS} functions can be resumed (called
-again), if any of these error codes is returned.  The error codes
-above refer to the system call, not the @acronym{GnuTLS} function,
-since signals do not interrupt @acronym{GnuTLS}' functions.
-
-@acronym{DTLS} however deviates from this rule. Because it requires
-timers and waiting for peer's messages during the handshake process,
-@acronym{GnuTLS} will block and might be interrupted by signals. The
-blocking operation of @acronym{GnuTLS} during @acronym{DTLS} handshake
-can be changed using the appropriate flags in @funcref{gnutls_init} (see
-@ref{TLS and DTLS sessions}).
-By default, if the transport functions are not set, @acronym{GnuTLS}
-will use the Berkeley sockets. 
+@acronym{GnuTLS} supports TCP and UDP layers transparently using
+the Berkeley sockets API. However, any transport layer can be used
+by providing callbacks for @acronym{GnuTLS} to access the transport layer 
+(for details see @ref{TLS and DTLS sessions}).
 
 @node The TLS record protocol
 @section The TLS record protocol
diff --git a/lib/gnutls_record.c b/lib/gnutls_record.c
index 6c1f72e4ea..72e3f76845 100644
--- a/lib/gnutls_record.c
+++ b/lib/gnutls_record.c
@@ -103,9 +103,9 @@ gnutls_record_disable_padding (gnutls_session_t session)
  * @session: is a #gnutls_session_t structure.
  * @ptr: is the value.
  *
- * Used to set the first argument of the transport function (like PUSH
- * and PULL).  In berkeley style sockets this function will set the
- * connection handle.
+ * Used to set the first argument of the transport function (for push
+ * and pull callbacks). In berkeley style sockets this function will set the
+ * connection descriptor.
  **/
 void
 gnutls_transport_set_ptr (gnutls_session_t session,
@@ -121,9 +121,9 @@ gnutls_transport_set_ptr (gnutls_session_t session,
  * @recv_ptr: is the value for the pull function
  * @send_ptr: is the value for the push function
  *
- * Used to set the first argument of the transport function (like PUSH
- * and PULL). In berkeley style sockets this function will set the
- * connection handle.  With this function you can use two different
+ * Used to set the first argument of the transport function (for push
+ * and pull callbacks). In berkeley style sockets this function will set the
+ * connection descriptor.  With this function you can use two different
  * pointers for receiving and sending.
  **/
 void
diff --git a/lib/system_override.c b/lib/system_override.c
index 82463d087e..7b5db63b3e 100644
--- a/lib/system_override.c
+++ b/lib/system_override.c
@@ -49,10 +49,10 @@
  * for @err is EAGAIN and EINTR, other values are treated will be
  * treated as real errors in the push/pull function.
  *
- * This function is useful in replacement push/pull functions set by
- * gnutls_transport_set_push_function and
- * gnutls_transport_set_pullpush_function under Windows, where the
- * replacement push/pull may not have access to the same @errno
+ * This function is useful in replacement push and pull functions set by
+ * gnutls_transport_set_push_function() and
+ * gnutls_transport_set_pull_function() under Windows, where the
+ * replacements may not have access to the same @errno
  * variable that is used by GnuTLS (e.g., the application is linked to
  * msvcr71.dll and gnutls is linked to msvcrt.dll).
  *