From: Matt Caswell Date: Tue, 25 Oct 2016 22:46:27 +0000 (+0100) Subject: Clarify the return values for SSL_read_ex()/SSL_write_ex() X-Git-Tag: OpenSSL_1_1_1-pre1~3192 X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=commitdiff_plain;h=740bfebaf6d879f051da625d3c583f7cbba8944f Clarify the return values for SSL_read_ex()/SSL_write_ex() Give more detail on what constitutes success/failure. Reviewed-by: Rich Salz --- diff --git a/doc/man3/SSL_read.pod b/doc/man3/SSL_read.pod index 8ef2db57c0..c87024ad90 100644 --- a/doc/man3/SSL_read.pod +++ b/doc/man3/SSL_read.pod @@ -87,8 +87,13 @@ with the same arguments. =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 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: diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod index 98d691a26c..6c9b28832e 100644 --- a/doc/man3/SSL_write.pod +++ b/doc/man3/SSL_write.pod @@ -71,8 +71,16 @@ 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 to find out +the reason and if the call is retryable or not. For SSL_write() the following return values can occur: