Add Copyright and license.

Wording improvements and a bit of additional information from OpenSSL.

1 files changed, 82 insertions, 21 deletions

diff --git a/lib/libssl/man/SSL_pending.3 b/lib/libssl/man/SSL_pending.3
index dadeec4b92e..1f8493b87c2 100644
--- a/lib/libssl/man/SSL_pending.3
+++ b/lib/libssl/man/SSL_pending.3
@@ -1,7 +1,56 @@
+.\"	$OpenBSD: SSL_pending.3,v 1.2 2016/12/04 12:26:05 schwarze Exp $
+.\"	OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
 .\"
-.\"	$OpenBSD: SSL_pending.3,v 1.1 2016/11/05 15:32:20 schwarze Exp $
+.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>,
+.\" Bodo Moeller <bodo@openssl.org>, and Matt Caswell <matt@openssl.org>.
+.\" Copyright (c) 2000, 2005, 2015, 2016 The OpenSSL Project.
+.\" All rights reserved.
 .\"
-.Dd $Mdocdate: November 5 2016 $
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 4 2016 $
 .Dt SSL_PENDING 3
 .Os
 .Sh NAME
@@ -12,33 +61,45 @@
 .Ft int
 .Fn SSL_pending "const SSL *ssl"
 .Sh DESCRIPTION
+Data is received in whole blocks known as records from the peer.
+A whole record is processed, for example decrypted, in one go and
+is buffered until it is read by the application via a call to
+.Xr SSL_read 3 .
+.Pp
 .Fn SSL_pending
 returns the number of bytes which are available inside
 .Fa ssl
 for immediate read.
-.Sh NOTES
-Data are received in blocks from the peer.
-Therefore data can be buffered inside
-.Fa ssl
-and are ready for immediate retrieval with
-.Xr SSL_read 3 .
+.Pp
+.Fn SSL_pending
+takes into account only bytes from the TLS/SSL record that is
+currently being processed (if any).
+If the
+.Fa ssl->read_ahead
+flag is set (see
+.Xr 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.
+These additional bytes will be buffered but will remain unprocessed
+until they are needed.
+As these bytes are still in an unprocessed state,
+.Fn SSL_pending
+will ignore them.
+Therefore it is possible for no more bytes to be readable from the
+underlying BIO (because the library has already read them) and for
+.Fn SSL_pending
+to return 0, even though readable application data bytes are available
+(because the data is in unprocessed buffered records).
 .Sh RETURN VALUES
-The number of bytes pending is returned.
+.Fn SSL_pending
+returns the number of buffered and processed application data
+bytes that are pending and are available for immediate read.
 .Sh SEE ALSO
 .Xr ssl 3 ,
+.Xr SSL_CTX_set_read_ahead 3 ,
 .Xr SSL_read 3
 .Sh BUGS
-.Fn SSL_pending
-takes into account only bytes from the TLS/SSL record that is currently being
-processed (if any).
-If the
-.Vt SSL
-object's
-.Em read_ahead
-flag is set, additional protocol bytes may have been read containing more
-TLS/SSL records; these are ignored by
-.Fn SSL_pending .
-.Pp
 Up to OpenSSL 0.9.6,
 .Fn SSL_pending
-does not check if the record type of pending data is application data.
+did not check if the record type of pending data is application data.