Clarify the return values for SSL_read_ex()/SSL_write_ex()
authorMatt Caswell <matt@openssl.org>
Tue, 25 Oct 2016 22:46:27 +0000 (23:46 +0100)
committerMatt Caswell <matt@openssl.org>
Fri, 4 Nov 2016 12:09:46 +0000 (12:09 +0000)
Give more detail on what constitutes success/failure.

Reviewed-by: Rich Salz <rsalz@openssl.org>
doc/man3/SSL_read.pod
doc/man3/SSL_write.pod

index 8ef2db57c0d299fda60adf898a1a5e7df44ab70f..c87024ad90ffe1ccd148b9a892de6e91c593cb9e 100644 (file)
@@ -87,8 +87,13 @@ with the same arguments.
 
 =head1 RETURN VALUES
 
 
 =head1 RETURN VALUES
 
-SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for failure. In
-the event of a failure call SSL_get_error() to find out the reason.
+SSL_read_ex() and SSL_peek_ex() will return 1 for success or 0 for failure.
+Success means that 1 or more application data bytes have been read from the SSL
+connection. Failure means that no bytes could be read from the SSL connection.
+Failures can be retryable (e.g. we are waiting for more bytes to
+be delivered by the network) or non-retryable (e.g. a fatal network error). In
+the event of a failure call L<SSL_get_error(3)> to find out the reason and if
+the call is retryable or not.
 
 For SSL_read() and SSL_peek() the following return values can occur:
 
 
 For SSL_read() and SSL_peek() the following return values can occur:
 
index 98d691a26cceb38b33823961ef36bd8cf96283bd..6c9b28832ee37235fdda1a787057d4e9b47b7156 100644 (file)
@@ -71,8 +71,16 @@ undefined.
 
 =head1 RETURN VALUES
 
 
 =head1 RETURN VALUES
 
-SSL_write_ex() will return 1 for success or 0 for failure. In the event of a
-failure call SSL_get_error() to find out the reason.
+SSL_write_ex() will return 1 for success or 0 for failure. Success means that
+all requested application data bytes have been written to the SSL connection or,
+if SSL_MODE_ENABLE_PARTIAL_WRITE is in use, at least 1 application data byte has
+been written to the SSL connection. Failure means that not all the requested
+bytes have been written yet (if SSL_MODE_ENABLE_PARTIAL_WRITE is not in use) or
+no bytes could be written to the SSL connection (if
+SSL_MODE_ENABLE_PARTIAL_WRITE is in use). Failures can be retryable (e.g. the
+network write buffer has temporarily filled up) or non-retryable (e.g. a fatal
+network error). In the event of a failure call L<SSL_get_error(3)> to find out
+the reason and if the call is retryable or not.
 
 For SSL_write() the following return values can occur:
 
 
 For SSL_write() the following return values can occur: