In bio.h rev. 1.35 2018/02/20 17:55:26, tb@ provided BIO_set_shutdown(3)

and BIO_get_shutdown(3).  Write the documentation from scratch because
what OpenSSL provides doesn't explain the difference to BIO_set_close(3)
and is also worded in a rather confusing way.

diff --git a/lib/libcrypto/man/BIO_get_data.3 b/lib/libcrypto/man/BIO_get_data.3
index 2a75439..aa2707d 100644 (file)
--- a/lib/libcrypto/man/BIO_get_data.3
+++ b/lib/libcrypto/man/BIO_get_data.3
@@ -1,7 +1,24 @@
-.\" $OpenBSD: BIO_get_data.3,v 1.1 2018/02/19 14:08:52 schwarze Exp $
+.\" $OpenBSD: BIO_get_data.3,v 1.2 2018/02/24 15:03:35 schwarze Exp $
 .\" selective merge up to: OpenSSL e90fc053 Jul 15 09:39:45 2017 -0400
 .\"
-.\" This file was written by Matt Caswell <matt@openssl.org>
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2018 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 Matt Caswell <matt@openssl.org>.
 .\" Copyright (c) 2016 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -48,13 +65,15 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: February 19 2018 $
+.Dd $Mdocdate: February 24 2018 $
 .Dt BIO_GET_DATA 3
 .Os
 .Sh NAME
 .Nm BIO_set_data ,
 .Nm BIO_get_data ,
-.Nm BIO_set_init
+.Nm BIO_set_init ,
+.Nm BIO_set_shutdown ,
+.Nm BIO_get_shutdown
 .Nd manage BIO state information
 .Sh SYNOPSIS
 .In openssl/bio.h
@@ -72,6 +91,15 @@
 .Fa "BIO *a"
 .Fa "int init"
 .Fc
+.Ft void
+.Fo BIO_set_shutdown
+.Fa "BIO *a"
+.Fa "int shutdown"
+.Fc
+.Ft int
+.Fo BIO_get_shutdown
+.Fa "BIO *a"
+.Fc
 .Sh DESCRIPTION
 These functions are mainly useful when implementing a custom BIO.
 .Pp
@@ -100,6 +128,30 @@ during initial construction of the BIO.
 For some BIOs however, initialisation may not be complete until
 additional steps have been taken, for example through calling custom
 ctrls.
+.Pp
+The
+.Fn BIO_set_shutdown
+and
+.Fn BIO_get_shutdown
+functions are low-level interfaces to forcefully set and get the
+.Fa shutdown
+flag of
+.Fa a ,
+circumventing type-dependent sanity checks,
+exclusively intended for implementing a new BIO type.
+The
+.Fa shutdown
+argument must be either
+.Dv BIO_CLOSE
+or
+.Dv BIO_NOCLOSE .
+When merely using a
+.Vt BIO
+object, call
+.Xr BIO_set_close 3
+and
+.Xr BIO_get_close 3
+instead.
 .Sh RETURN VALUES
 .Fn BIO_get_data
 returns a pointer to the implementation specific custom data associated
@@ -108,8 +160,15 @@ with
 or
 .Dv NULL
 if none is set.
+.Pp
+.Fn BIO_get_shutdown
+returns the value previously set with
+.Fn BIO_set_shutdown
+or with
+.Xr BIO_set_close 3 .
 .Sh SEE ALSO
 .Xr BIO_meth_new 3 ,
-.Xr BIO_new 3
+.Xr BIO_new 3 ,
+.Xr BIO_set_close 3
 .Sh HISTORY
 These functions first appeared in OpenSSL 1.1.0.