From 9ded8d02221c1adca94ff07000acc1f64366220d Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 24 Feb 2018 15:03:35 +0000 Subject: [PATCH] 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. --- lib/libcrypto/man/BIO_get_data.3 | 69 +++++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 5 deletions(-) diff --git a/lib/libcrypto/man/BIO_get_data.3 b/lib/libcrypto/man/BIO_get_data.3 index 2a7543960c2..aa2707de825 100644 --- 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 +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2018 Ingo Schwarze +.\" +.\" 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 . .\" 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. -- 2.20.1