Add documentation for SSL_has_pending()

A previous commit added the SSL_has_pending() function which provides a
method for knowing whether OpenSSL has buffered, but as yet unprocessed
record data.
Reviewed-by: NTim Hudson <tjh@openssl.org>

doc/ssl/SSL_CTX_set_read_ahead.pod

@@ -37,7 +37,9 @@ ahead has been set or not.
 =head1 NOTES
 
 These functions have no impact when used with DTLS. The return values for
-SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS.
+SSL_CTX_get_read_head() and SSL_get_read_ahead() are undefined for DTLS. Setting
+B<read_ahead> can impact the behaviour of the SSL_pending() function
+(see L<SSL_pending()>).
 
 =head1 RETURN VALUES
 
@@ -46,6 +48,6 @@ and non zero otherwise.
 
 =head1 SEE ALSO
 
-L<ssl(3)>
+L<ssl(3)>, L<SSL_pending(3)>
 
 =cut

doc/ssl/SSL_CTX_set_split_send_fragment.pod

@@ -93,7 +93,8 @@ read as much data into the read buffer as the network can provide and will fit
 into the buffer. Without this set data is read into the read buffer one record
 at a time. The more data that can be read, the more opportunity there is for
 parallelising the processing at the cost of increased memory overhead per
-connection.
+connection. Setting B<read_ahead> can impact the behaviour of the SSL_pending()
+function (see L<SSL_pending(3)>).
 
 The SSL_CTX_set_default_read_buffer_len() and SSL_set_default_read_buffer_len()
 functions control the size of the read buffer that will be used. The B<len>
@@ -121,6 +122,6 @@ functions were added in OpenSSL 1.1.0.
 
 =head1 SEE ALSO
 
-L<SSL_CTX_set_read_ahead(3)>
+L<SSL_CTX_set_read_ahead(3)>, L<SSL_pending(3)>
 
 =cut

doc/ssl/SSL_pending.pod

@@ -2,41 +2,58 @@
 
 =head1 NAME
 
-SSL_pending - obtain number of readable bytes buffered in an SSL object
+SSL_pending, SSL_has_pending - check for readable bytes buffered in an
+SSL object
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
  int SSL_pending(const SSL *ssl);
+ int SSL_has_pending(const SSL *s);
 
 =head1 DESCRIPTION
 
-SSL_pending() returns the number of bytes which are available inside
-B<ssl> for immediate read.
-
-=head1 NOTES
-
-Data are received in blocks from the peer. Therefore data can be buffered
-inside B<ssl> and are ready for immediate retrieval with
-L<SSL_read(3)>.
+Data is received in whole blocks known as records from the peer. A whole record
+is processed (e.g. decrypted) in one go and is buffered by OpenSSL until it is
+read by the application via a call to L<SSL_read(3)>.
+
+SSL_pending() returns the number of bytes which have been processed, buffered
+and are available inside B<ssl> for immediate read.
+
+If the B<SSL> object's I<read_ahead> flag is set (see
+L<SSL_CTX_set_read_ahead(3)>), additional protocol bytes (beyond the current
+record) may have been read containing more TLS/SSL records. This also applies to
+DTLS and pipelining (see L<SSL_CTX_set_split_send_fragment(3)>). These
+additional bytes will be buffered by OpenSSL but will remain unprocessed until
+they are needed. As these bytes are still in an unprocessed state SSL_pending()
+will ignore them. Therefore it is possible for no more bytes to be readable from
+the underlying BIO (because OpenSSL has already read them) and for SSL_pending()
+to return 0, even though readable application data bytes are available (because
+the data is in unprocessed buffered records).
+
+SSL_has_pending() returns 1 if B<s> has buffered data (whether processed or
+unprocessed) and 0 otherwise. Note that it is possible for SSL_has_pending() to
+return 1, and then a subsequent call to SSL_read() to return no data because the
+unprocessed buffered data when processed yielded no application data (for
+example this can happend during renegotiation). It is also possible in this
+scenario for SSL_has_pending() to continue to return 1 even after an SSL_read()
+call because the buffered and unprocessed data is not yet processable (e.g.
+because OpenSSL has only received a partial record so far).
 
 =head1 RETURN VALUES
 
-The number of bytes pending is returned.
+SSL_pending() returns the number of buffered and processed application data
+bytes that are pending and are available for immediate read. SSL_has_pending()
+returns 1 if there is buffered record data in the SSL object and 0 otherwise.
 
-=head1 BUGS
+=head1 SEE ALSO
 
-SSL_pending() takes into account only bytes from the TLS/SSL record
-that is currently being processed (if any).  If the B<SSL> object's
-I<read_ahead> flag is set (see
-L<SSL_CTX_set_read_ahead(3)>), additional protocol
-bytes may have been read containing more TLS/SSL records; these are ignored by
-SSL_pending().
+L<SSL_read(3)>, L<SSL_CTX_set_read_ahead(3)>,
+L<SSL_CTX_set_split_send_fragment(3)>, L<ssl(3)>
 
-=head1 SEE ALSO
+=head1 HISTORY
 
-L<SSL_read(3)>,
-L<SSL_CTX_set_read_ahead(3)>, L<ssl(3)>
+The SSL_has_pending() function was added in OpenSSL 1.1.0.
 
 =cut