From: schwarze <schwarze@openbsd.org>
Date: Sun, 18 Dec 2022 17:40:55 +0000 (+0000)
Subject: document BIO_number_read(3) and BIO_number_written(3)
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=d6a42141e764dbee662a7f3f98f22c8cdf37d5f7;p=openbsd

document BIO_number_read(3) and BIO_number_written(3)
---

diff --git a/lib/libcrypto/man/BIO_read.3 b/lib/libcrypto/man/BIO_read.3
index ac809bc7822..5fea9f728a5 100644
--- a/lib/libcrypto/man/BIO_read.3
+++ b/lib/libcrypto/man/BIO_read.3
@@ -1,10 +1,10 @@
-.\" $OpenBSD: BIO_read.3,v 1.10 2021/12/08 16:31:10 schwarze Exp $
+.\" $OpenBSD: BIO_read.3,v 1.11 2022/12/18 17:40:55 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2021, 2022 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
@@ -65,15 +65,17 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 8 2021 $
+.Dd $Mdocdate: December 18 2022 $
 .Dt BIO_READ 3
 .Os
 .Sh NAME
 .Nm BIO_read ,
+.Nm BIO_number_read ,
 .Nm BIO_gets ,
 .Nm BIO_write ,
 .Nm BIO_puts ,
-.Nm BIO_indent
+.Nm BIO_indent ,
+.Nm BIO_number_written
 .Nd BIO I/O functions
 .Sh SYNOPSIS
 .In openssl/bio.h
@@ -83,6 +85,10 @@
 .Fa "void *buf"
 .Fa "int len"
 .Fc
+.Ft unsigned long
+.Fo BIO_number_read
+.Fa "BIO *b"
+.Fc
 .Ft int
 .Fo BIO_gets
 .Fa "BIO *b"
@@ -106,6 +112,10 @@
 .Fa "int indent"
 .Fa "int max"
 .Fc
+.Ft unsigned long
+.Fo BIO_number_written
+.Fa "BIO *b"
+.Fc
 .Sh DESCRIPTION
 .Fn BIO_read
 attempts to read
@@ -115,6 +125,26 @@ bytes from
 and places the data in
 .Fa buf .
 .Pp
+.Fn BIO_number_read
+returns the grand total of bytes read from
+.Fa b
+using
+.Fn BIO_read
+so far.
+Bytes read with
+.Fn BIO_gets
+do
+.Sy not
+count.
+.Xr BIO_new 3
+and
+.Xr BIO_set 3
+initialize the counter to 0.
+When reading very large amounts of data,
+the counter will eventually wrap around from
+.Dv ULONG_MAX
+to 0.
+.Pp
 .Fn BIO_gets
 performs the BIOs "gets" operation and places the data in
 .Fa buf .
@@ -152,6 +182,24 @@ but not more than
 .Fa max
 characters.
 .Pp
+.Fn BIO_number_written
+returns the grand total of bytes written to
+.Fa b
+using
+.Fn BIO_write ,
+.Fn BIO_puts ,
+and
+.Fn BIO_indent
+so far.
+.Xr BIO_new 3
+and
+.Xr BIO_set 3
+initialize the counter to 0.
+When writing very large amounts of data,
+the counter will eventually wrap around from
+.Dv ULONG_MAX
+to 0.
+.Pp
 One technique sometimes used with blocking sockets
 is to use a system call (such as
 .Xr select 2 ,
@@ -189,6 +237,15 @@ to the chain.
 returns 1 if successful, even if nothing was written,
 or 0 if writing fails.
 .Pp
+.Fn BIO_number_read
+and
+.Fn BIO_number_written
+return a number of bytes or 0 if
+.Fa b
+is a
+.Dv NULL
+pointer.
+.Pp
 The other functions return either the amount of data successfully
 read or written (if the return value is positive) or that no data
 was successfully read or written if the result is 0 or \-1.
@@ -211,7 +268,12 @@ the application should retry the operation later.
 .Fn BIO_write ,
 and
 .Fn BIO_puts
-first appeared in SSLeay 0.6.0 and have been available since
+first appeared in SSLeay 0.6.0.
+.Fn BIO_number_read
+and
+.Fn BIO_number_written
+first appeared in SSLeay 0.6.5.
+These functions have been available since
 .Ox 2.4 .
 .Pp
 .Fn BIO_indent