lib/libcrypto/man/BIO_push.3

   1 .\"     $OpenBSD: BIO_push.3,v 1.5 2016/12/06 12:54:19 schwarze Exp $
   2 .\"     OpenSSL doc/man3/BIO_push.pod 76ed5a42 Jun 29 13:38:55 2014 +0100
   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, 2014 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: December 6 2016 $
  53 .Dt BIO_PUSH 3
  54 .Os
  55 .Sh NAME
  56 .Nm BIO_push ,
  57 .Nm BIO_pop
  58 .Nd add and remove BIOs from a chain
  59 .Sh SYNOPSIS
  60 .In openssl/bio.h
  61 .Ft BIO *
  62 .Fo BIO_push
  63 .Fa "BIO *b"
  64 .Fa "BIO *append"
  65 .Fc
  66 .Ft BIO *
  67 .Fo BIO_pop
  68 .Fa "BIO *b"
  69 .Fc
  70 .Sh DESCRIPTION
  71 BIOs can be joined together to form chains.
  72 A chain normally consist of one or more filter BIOs
  73 and one source/sink BIO at the end.
  74 Data read from or written to the first BIO traverses the chain
  75 to the end.
  76 A single BIO can be regarded as a chain with one component.
  77 .Pp
  78 The
  79 .Fn BIO_push
  80 function appends the BIO
  81 .Fa append
  82 to
  83 .Fa b
  84 and returns
  85 .Fa b .
  86 .Pp
  87 .Fn BIO_pop
  88 removes the BIO
  89 .Fa b
  90 from a chain and returns the next BIO in the chain, or
  91 .Dv NULL
  92 if there is no next BIO.
  93 The removed BIO then becomes a single BIO with no association with the
  94 original chain.
  95 it can thus be freed or attached to a different chain.
  96 .Pp
  97 The names of these functions are perhaps a little misleading.
  98 .Fn BIO_push
  99 joins two BIO chains whereas
 100 .Fn BIO_pop
 101 deletes a single BIO from a chain;
 102 the deleted BIO does not need to be at the end of a chain.
 103 .Pp
 104 The process of calling
 105 .Fn BIO_push
 106 and
 107 .Fn BIO_pop
 108 on a BIO may have additional consequences: a
 109 .Xr BIO_ctrl 3
 110 call is made to the affected BIOs.
 111 Any effects will be noted in the descriptions of individual BIOs.
 112 .Sh RETURN VALUES
 113 .Fn BIO_push
 114 returns the beginning of the chain,
 115 .Fa b .
 116 .Pp
 117 .Fn BIO_pop
 118 returns the next BIO in the chain, or
 119 .Dv NULL
 120 if there is no next BIO.
 121 .Sh EXAMPLES
 122 For these examples suppose
 123 .Sy md1
 124 and
 125 .Sy md2
 126 are digest BIOs,
 127 .Sy b64
 128 is a Base64 BIO and
 129 .Sy f
 130 is a file BIO.
 131 .Pp
 132 If the call
 133 .Pp
 134 .Dl BIO_push(b64, f);
 135 .Pp
 136 is made then the new chain will be
 137 .Sy b64-f .
 138 After making the calls
 139 .Bd -literal -offset indent
 140 BIO_push(md2, b64);
 141 BIO_push(md1, md2);
 142 .Ed
 143 .Pp
 144 the new chain is
 145 .Sy md1-md2-b64-f .
 146 Data written to
 147 .Sy md1
 148 will be digested
 149 by
 150 .Sy md1
 151 and
 152 .Sy md2 ,
 153 Base64-encoded and written to
 154 .Sy f .
 155 .Pp
 156 It should be noted that reading causes data to pass
 157 in the reverse direction.
 158 That is, data is read from
 159 .Sy f ,
 160 Base64-decoded and digested by
 161 .Sy md1
 162 and
 163 .Sy md2 .
 164 If this call is made:
 165 .Pp
 166 .Dl BIO_pop(md2);
 167 .Pp
 168 The call will return
 169 .Sy b64
 170 and the new chain will be
 171 .Sy md1-b64-f ;
 172 data can be written to
 173 .Sy md1
 174 as before.
 175 .Sh SEE ALSO
 176 .Xr BIO_find_type 3 ,
 177 .Xr BIO_new 3 ,
 178 .Xr BIO_read 3