Document Next Protocol Negotiation APIs

[openssl.git] / doc / man3 / SSL_write.pod

diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod
index 98d691a26cceb38b33823961ef36bd8cf96283bd..2a751107bb95af8ce38d64d2cb2586234554bf7c 100644 (file)
--- a/doc/man3/SSL_write.pod
+++ b/doc/man3/SSL_write.pod
@@ -71,30 +71,35 @@ undefined.
 
 =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 which indicates whether the call is retryable or not.
 
 For SSL_write() the following return values can occur:
 
 =over 4
 
-=item E<gt>0
+=item E<gt> 0
 
 The write operation was successful, the return value is the number of
 bytes actually written to the TLS/SSL connection.
 
-=item Z<>0
+=item Z<><= 0
 
-The write operation was not successful. Probably the underlying connection
-was closed. Call SSL_get_error() with the return value B<ret> to find out,
-whether an error occurred or the connection was shut down cleanly
-(SSL_ERROR_ZERO_RETURN).
+The write operation was not successful, because either the connection was
+closed, an error occurred or action must be taken by the calling process.
+Call SSL_get_error() with the return value B<ret> to find out the reason.
 
-=item E<lt>0
-
-The write operation was not successful, because either an error occurred
-or action must be taken by the calling process. Call SSL_get_error() with the
-return value B<ret> to find out the reason.
+Old documentation indicated a difference between 0 and -1, and that -1 was
+retryable.
+You should instead call SSL_get_error() to find out if it's retryable.
 
 =back
 
@@ -104,7 +109,7 @@ L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>
 L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
 L<SSL_connect(3)>, L<SSL_accept(3)>
 L<SSL_set_connect_state(3)>,
-L<ssl(3)>, L<bio(3)>
+L<ssl(7)>, L<bio(7)>
 
 =head1 COPYRIGHT