document BIO_indent(3);

while here, improve some of the existing text in minor ways

1 files changed, 53 insertions, 12 deletions

diff --git a/src/lib/libcrypto/man/BIO_read.3 b/src/lib/libcrypto/man/BIO_read.3
index 3f059b5d54..ac809bc782 100644
--- a/src/lib/libcrypto/man/BIO_read.3
+++ b/src/lib/libcrypto/man/BIO_read.3
@@ -1,7 +1,24 @@
-.\"     $OpenBSD: BIO_read.3,v 1.9 2021/11/14 13:40:16 schwarze Exp $
-.\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\" $OpenBSD: BIO_read.3,v 1.10 2021/12/08 16:31:10 schwarze Exp $
+.\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
-.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2021 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
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2016 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,14 +65,15 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 14 2021 $
+.Dd $Mdocdate: December 8 2021 $
 .Dt BIO_READ 3
 .Os
 .Sh NAME
 .Nm BIO_read ,
 .Nm BIO_gets ,
 .Nm BIO_write ,
-.Nm BIO_puts
+.Nm BIO_puts ,
+.Nm BIO_indent
 .Nd BIO I/O functions
 .Sh SYNOPSIS
 .In openssl/bio.h
@@ -80,13 +98,19 @@
 .Ft int
 .Fo BIO_puts
 .Fa "BIO *b"
-.Fa "const char *buf"
+.Fa "const char *string"
+.Fc
+.Ft int
+.Fo BIO_indent
+.Fa "BIO *b"
+.Fa "int indent"
+.Fa "int max"
 .Fc
 .Sh DESCRIPTION
 .Fn BIO_read
 attempts to read
 .Fa len
-bytes from BIO
+bytes from
 .Fa b
 and places the data in
 .Fa buf .
@@ -110,15 +134,24 @@ attempts to write
 .Fa len
 bytes from
 .Fa buf
-to BIO
+to
 .Fa b .
 .Pp
 .Fn BIO_puts
-attempts to write a null terminated string
-.Fa buf
-to BIO
+attempts to write the NUL-terminated
+.Fa string
+to
 .Fa b .
 .Pp
+.Fn BIO_indent
+attempts to write
+.Fa indent
+space characters to
+.Fa b ,
+but not more than
+.Fa max
+characters.
+.Pp
 One technique sometimes used with blocking sockets
 is to use a system call (such as
 .Xr select 2 ,
@@ -152,7 +185,11 @@ work around this by adding a buffering BIO
 .Xr BIO_f_buffer 3
 to the chain.
 .Sh RETURN VALUES
-All these functions return either the amount of data successfully
+.Fn BIO_indent
+returns 1 if successful, even if nothing was written,
+or 0 if writing fails.
+.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.
 If the return value is \-2, then the operation is not implemented
@@ -176,3 +213,7 @@ and
 .Fn BIO_puts
 first appeared in SSLeay 0.6.0 and have been available since
 .Ox 2.4 .
+.Pp
+.Fn BIO_indent
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.4 .