lib/libcrypto/man/BIO_new.3

   1 .\"     $OpenBSD: BIO_new.3,v 1.8 2017/03/25 17:15:59 schwarze Exp $
   2 .\"     OpenSSL doc/man3/BIO_new.pod ca3a82c3 Mar 25 11:31:18 2015 -0400
   3 .\"     OpenSSL doc/man7/bio.pod a9c85cea Nov 11 09:33:55 2016 +0100
   4 .\"
   5 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
   6 .\" Copyright (c) 2000, 2015, 2016 The OpenSSL Project.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: March 25 2017 $
  53 .Dt BIO_NEW 3
  54 .Os
  55 .Sh NAME
  56 .Nm BIO_new ,
  57 .Nm BIO_set ,
  58 .Nm BIO_free ,
  59 .Nm BIO_vfree ,
  60 .Nm BIO_free_all
  61 .Nd construct and destruct I/O abstraction objects
  62 .Sh SYNOPSIS
  63 .In openssl/bio.h
  64 .Ft BIO *
  65 .Fo BIO_new
  66 .Fa "BIO_METHOD *type"
  67 .Fc
  68 .Ft int
  69 .Fo BIO_set
  70 .Fa "BIO *a"
  71 .Fa "BIO_METHOD *type"
  72 .Fc
  73 .Ft int
  74 .Fo BIO_free
  75 .Fa "BIO *a"
  76 .Fc
  77 .Ft void
  78 .Fo BIO_vfree
  79 .Fa "BIO *a"
  80 .Fc
  81 .Ft void
  82 .Fo BIO_free_all
  83 .Fa "BIO *a"
  84 .Fc
  85 .Sh DESCRIPTION
  86 A
  87 .Vt BIO
  88 is an I/O abstraction object, hiding many of the underlying I/O
  89 details from an application.
  90 If an application uses BIOs for its I/O, it can transparently handle
  91 SSL connections, unencrypted network connections, and file I/O.
  92 .Pp
  93 The
  94 .Fn BIO_new
  95 function constructs a new
  96 .Vt BIO
  97 using the method
  98 .Fa type .
  99 There are two groups of BIO types, source/sink BIOs and filter BIOs.
 100 .Pp
 101 Source/sink BIOs provide input or consume output.
 102 Examples include socket BIOs and file BIOs.
 103 .Pp
 104 Filter BIOs take data from one BIO and pass it through to another,
 105 or to the application, forming a chain of BIOs.
 106 The data may be left unmodified (for example by a message digest BIO)
 107 or translated (for example by an encryption BIO).
 108 The effect of a filter BIO may change according to the I/O operation
 109 it is performing: for example an encryption BIO will encrypt data
 110 if it is written to and decrypt data if it is read from.
 111 .Pp
 112 Some BIOs (such as memory BIOs) can be used immediately after calling
 113 .Fn BIO_new .
 114 Others (such as file BIOs) need some additional initialization, and
 115 utility functions exists to construct and initialize such BIOs.
 116 .Pp
 117 Normally the
 118 .Fa type
 119 argument is supplied by a function which returns a pointer to a
 120 .Vt BIO_METHOD .
 121 There is a naming convention for such functions:
 122 the methods for source/sink BIOs are called
 123 .Fn BIO_s_*
 124 and those for filter BIOs
 125 .Fn BIO_f_* .
 126 .Pp
 127 .Fn BIO_set
 128 sets the method of an already existing BIO.
 129 .Pp
 130 .Fn BIO_free
 131 and
 132 .Fn BIO_vfree
 133 destruct a single BIO, which may also have some effect on the
 134 underlying I/O structure, for example it may close the file being
 135 referred to under certain circumstances.
 136 If
 137 .Fa a
 138 is a
 139 .Dv NULL
 140 pointer, no action occurs.
 141 If
 142 .Fn BIO_free
 143 is called on a BIO chain, it will only destruct one BIO,
 144 resulting in a memory leak.
 145 .Pp
 146 .Fn BIO_free_all
 147 destructs an entire BIO chain.
 148 It does not halt if an error occurs
 149 destructing an individual BIO in the chain.
 150 If
 151 .Fa a
 152 is a
 153 .Dv NULL
 154 pointer, no action occurs.
 155 Calling
 156 .Fn BIO_free_all
 157 on a single BIO has the same effect as
 158 .Fn BIO_vfree .
 159 .Pp
 160 Common I/O functions are documented in
 161 .Xr BIO_read 3 .
 162 Forming chains is explained in
 163 .Xr BIO_push 3 ;
 164 inspecting them is explained in
 165 .Xr BIO_find_type 3 .
 166 For more details about the different kinds of BIOs, see the individual
 167 .Vt BIO_METHOD
 168 manual pages.
 169 .Sh RETURN VALUES
 170 .Fn BIO_new
 171 returns a newly constructed
 172 .Vt BIO
 173 object or
 174 .Dv NULL
 175 on failure.
 176 .Pp
 177 .Fn BIO_set
 178 and
 179 .Fn BIO_free
 180 return 1 for success or 0 for failure.
 181 .Sh EXAMPLES
 182 Create a memory BIO:
 183 .Pp
 184 .Dl BIO *mem = BIO_new(BIO_s_mem());
 185 .Sh SEE ALSO
 186 .Xr BIO_ctrl 3 ,
 187 .Xr BIO_f_base64 3 ,
 188 .Xr BIO_f_buffer 3 ,
 189 .Xr BIO_f_cipher 3 ,
 190 .Xr BIO_f_md 3 ,
 191 .Xr BIO_f_null 3 ,
 192 .Xr BIO_f_ssl 3 ,
 193 .Xr BIO_find_type 3 ,
 194 .Xr BIO_get_ex_new_index 3 ,
 195 .Xr BIO_printf 3 ,
 196 .Xr BIO_push 3 ,
 197 .Xr BIO_read 3 ,
 198 .Xr BIO_s_accept 3 ,
 199 .Xr BIO_s_bio 3 ,
 200 .Xr BIO_s_connect 3 ,
 201 .Xr BIO_s_fd 3 ,
 202 .Xr BIO_s_file 3 ,
 203 .Xr BIO_s_mem 3 ,
 204 .Xr BIO_s_null 3 ,
 205 .Xr BIO_s_socket 3 ,
 206 .Xr BIO_set_callback 3 ,
 207 .Xr BIO_should_retry 3