1.\" $OpenBSD: BIO_new.3,v 1.19 2019/11/02 15:27:10 schwarze Exp $ 2.\" full merge up to: 3.\" OpenSSL man3/BIO_new.pod fb46be03 Feb 26 11:51:31 2016 +0000 4.\" OpenSSL man7/bio.pod 631c37be Dec 12 16:56:50 2017 +0100 5.\" partial merge up to: 6.\" OpenSSL man3/BIO_new.pod e9b77246 Jan 20 19:58:49 2017 +0100 7.\" 8.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 9.\" Copyright (c) 2000, 2015, 2016 The OpenSSL Project. All rights reserved. 10.\" 11.\" Redistribution and use in source and binary forms, with or without 12.\" modification, are permitted provided that the following conditions 13.\" are met: 14.\" 15.\" 1. Redistributions of source code must retain the above copyright 16.\" notice, this list of conditions and the following disclaimer. 17.\" 18.\" 2. Redistributions in binary form must reproduce the above copyright 19.\" notice, this list of conditions and the following disclaimer in 20.\" the documentation and/or other materials provided with the 21.\" distribution. 22.\" 23.\" 3. All advertising materials mentioning features or use of this 24.\" software must display the following acknowledgment: 25.\" "This product includes software developed by the OpenSSL Project 26.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 27.\" 28.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 29.\" endorse or promote products derived from this software without 30.\" prior written permission. For written permission, please contact 31.\" openssl-core@openssl.org. 32.\" 33.\" 5. Products derived from this software may not be called "OpenSSL" 34.\" nor may "OpenSSL" appear in their names without prior written 35.\" permission of the OpenSSL Project. 36.\" 37.\" 6. Redistributions of any form whatsoever must retain the following 38.\" acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 41.\" 42.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 43.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 44.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 45.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 46.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 47.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 48.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 49.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 50.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 51.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 53.\" OF THE POSSIBILITY OF SUCH DAMAGE. 54.\" 55.Dd $Mdocdate: November 2 2019 $ 56.Dt BIO_NEW 3 57.Os 58.Sh NAME 59.Nm BIO_new , 60.Nm BIO_up_ref , 61.Nm BIO_set , 62.Nm BIO_free , 63.Nm BIO_vfree , 64.Nm BIO_free_all 65.Nd construct and destruct I/O abstraction objects 66.Sh SYNOPSIS 67.In openssl/bio.h 68.Ft BIO * 69.Fo BIO_new 70.Fa "const BIO_METHOD *type" 71.Fc 72.Ft int 73.Fo BIO_up_ref 74.Fa "BIO *a" 75.Fc 76.Ft int 77.Fo BIO_set 78.Fa "BIO *a" 79.Fa "const BIO_METHOD *type" 80.Fc 81.Ft int 82.Fo BIO_free 83.Fa "BIO *a" 84.Fc 85.Ft void 86.Fo BIO_vfree 87.Fa "BIO *a" 88.Fc 89.Ft void 90.Fo BIO_free_all 91.Fa "BIO *a" 92.Fc 93.Sh DESCRIPTION 94A 95.Vt BIO 96is an I/O abstraction object, hiding many of the underlying I/O 97details from an application. 98If an application uses BIOs for its I/O, it can transparently handle 99SSL connections, unencrypted network connections, and file I/O. 100.Pp 101The 102.Fn BIO_new 103function constructs a new 104.Vt BIO 105using the method 106.Fa type 107and sets its reference count to 1. 108There are two groups of BIO types, source/sink BIOs and filter BIOs. 109.Pp 110Source/sink BIOs provide input or consume output. 111Examples include socket BIOs and file BIOs. 112.Pp 113Filter BIOs take data from one BIO and pass it through to another, 114or to the application, forming a chain of BIOs. 115The data may be left unmodified (for example by a message digest BIO) 116or translated (for example by an encryption BIO). 117The effect of a filter BIO may change according to the I/O operation 118it is performing: for example an encryption BIO encrypts data 119if it is written to and decrypts data if it is read from. 120.Pp 121Some BIOs (such as memory BIOs) can be used immediately after calling 122.Fn BIO_new . 123Others (such as file BIOs) need some additional initialization, and 124utility functions exists to construct and initialize such BIOs. 125.Pp 126Normally the 127.Fa type 128argument is supplied by a function which returns a pointer to a 129.Vt BIO_METHOD . 130There is a naming convention for such functions: 131the methods for source/sink BIOs are called 132.Fn BIO_s_* 133and those for filter BIOs 134.Fn BIO_f_* . 135.Pp 136.Fn BIO_up_ref 137increments the reference count of 138.Fa a 139by 1. 140.Pp 141.Fn BIO_set 142is a deprecated function to initialize an unused 143.Vt BIO 144structure located in static memory or on the stack, 145to set its method to 146.Fa type , 147and to set its reference count to 1. 148It must not be called on 149.Vt BIO 150objects created with 151.Fn BIO_new , 152nor on objects that were already used. 153.Pp 154.Fn BIO_free 155and 156.Fn BIO_vfree 157decrement the reference count of 158.Fa a 159by 1, and if the refenece count reaches 0, they destruct the single 160.Vt BIO 161.Fa a , 162which may also have some effect on the 163underlying I/O structure, for example it may close the file being 164referred to under certain circumstances. 165If 166.Fa a 167is a 168.Dv NULL 169pointer, no action occurs. 170If 171.Fn BIO_free 172is called on a BIO chain, it destructs at most one BIO, 173resulting in a memory leak. 174.Pp 175.Fn BIO_free_all 176calls 177.Fn BIO_free 178on 179.Fa a 180and on all following 181.Vt BIO 182objects in the chain. 183As soon as the reference count of a 184.Vt BIO 185is still non-zero after calling 186.Fn BIO_free 187on it, the function 188.Fn BIO_free_all 189returns right away and refrains from freeing the remaining 190.Vt BIO 191objects in the chain. 192It does not halt if an error occurs 193destructing an individual BIO in the chain. 194If 195.Fa a 196is a 197.Dv NULL 198pointer, no action occurs. 199Calling 200.Fn BIO_free_all 201on a single BIO has the same effect as 202.Fn BIO_vfree . 203.Pp 204Common I/O functions are documented in 205.Xr BIO_read 3 . 206Forming chains is explained in 207.Xr BIO_push 3 ; 208inspecting them is explained in 209.Xr BIO_find_type 3 . 210For more details about the different kinds of BIOs, see the individual 211.Vt BIO_METHOD 212manual pages. 213.Sh RETURN VALUES 214.Fn BIO_new 215returns a newly constructed 216.Vt BIO 217object or 218.Dv NULL 219on failure. 220.Pp 221.Fn BIO_up_ref , 222.Fn BIO_set , 223and 224.Fn BIO_free 225return 1 for success or 0 for failure. 226.Sh EXAMPLES 227Create a memory BIO: 228.Pp 229.Dl BIO *mem = BIO_new(BIO_s_mem()); 230.Sh SEE ALSO 231.Xr BIO_ctrl 3 , 232.Xr BIO_f_base64 3 , 233.Xr BIO_f_buffer 3 , 234.Xr BIO_f_cipher 3 , 235.Xr BIO_f_md 3 , 236.Xr BIO_f_null 3 , 237.Xr BIO_f_ssl 3 , 238.Xr BIO_find_type 3 , 239.Xr BIO_get_ex_new_index 3 , 240.Xr BIO_meth_new 3 , 241.Xr BIO_new_CMS 3 , 242.Xr BIO_printf 3 , 243.Xr BIO_push 3 , 244.Xr BIO_read 3 , 245.Xr BIO_s_accept 3 , 246.Xr BIO_s_bio 3 , 247.Xr BIO_s_connect 3 , 248.Xr BIO_s_fd 3 , 249.Xr BIO_s_file 3 , 250.Xr BIO_s_mem 3 , 251.Xr BIO_s_null 3 , 252.Xr BIO_s_socket 3 , 253.Xr BIO_set_callback 3 , 254.Xr BIO_set_data 3 , 255.Xr BIO_should_retry 3 , 256.Xr BUF_MEM_new 3 , 257.Xr crypto 3 258.Sh HISTORY 259.Fn BIO_new , 260.Fn BIO_set , 261and 262.Fn BIO_free 263first appeared in SSLeay 0.6.0. 264.Fn BIO_free_all 265first appeared in SSLeay 0.6.6. 266All these functions have been available since 267.Ox 2.4 . 268.Pp 269.Fn BIO_vfree 270first appeared in OpenSSL 0.9.6 and has been available since 271.Ox 2.9 . 272.Pp 273.Fn BIO_up_ref 274first appeared in OpenSSL 1.1.0 and has been available since 275.Ox 6.3 . 276