1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosBIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/bio.h> 10*4724848cSchristos 11*4724848cSchristos BIO *BIO_push(BIO *b, BIO *next); 12*4724848cSchristos BIO *BIO_pop(BIO *b); 13*4724848cSchristos void BIO_set_next(BIO *b, BIO *next); 14*4724848cSchristos 15*4724848cSchristos=head1 DESCRIPTION 16*4724848cSchristos 17*4724848cSchristosBIO_push() pushes I<b> on I<next>. 18*4724848cSchristosIf I<b> is NULL the function does nothing and returns I<next>. 19*4724848cSchristosOtherwise it prepends I<b>, which may be a single BIO or a chain of BIOs, 20*4724848cSchristosto I<next> (unless I<next> is NULL). 21*4724848cSchristosIt then makes a control call on I<b> and returns I<b>. 22*4724848cSchristos 23*4724848cSchristosBIO_pop() removes the BIO I<b> from any chain is is part of. 24*4724848cSchristosIf I<b> is NULL the function does nothing and returns NULL. 25*4724848cSchristosOtherwise it makes a control call on I<b> and 26*4724848cSchristosreturns the next BIO in the chain, or NULL if there is no next BIO. 27*4724848cSchristosThe removed BIO becomes a single BIO with no association with 28*4724848cSchristosthe original chain, it can thus be freed or be made part of a different chain. 29*4724848cSchristos 30*4724848cSchristosBIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to 31*4724848cSchristosby I<next>. The new chain may include some of the same BIOs from the old chain 32*4724848cSchristosor it may be completely different. 33*4724848cSchristos 34*4724848cSchristos=head1 NOTES 35*4724848cSchristos 36*4724848cSchristosThe names of these functions are perhaps a little misleading. BIO_push() 37*4724848cSchristosjoins two BIO chains whereas BIO_pop() deletes a single BIO from a chain, 38*4724848cSchristosthe deleted BIO does not need to be at the end of a chain. 39*4724848cSchristos 40*4724848cSchristosThe process of calling BIO_push() and BIO_pop() on a BIO may have additional 41*4724848cSchristosconsequences (a control call is made to the affected BIOs). 42*4724848cSchristosAny effects will be noted in the descriptions of individual BIOs. 43*4724848cSchristos 44*4724848cSchristos=head1 RETURN VALUES 45*4724848cSchristos 46*4724848cSchristosBIO_push() returns the head of the chain, 47*4724848cSchristoswhich usually is I<b>, or I<next> if I<b> is NULL. 48*4724848cSchristos 49*4724848cSchristosBIO_pop() returns the next BIO in the chain, 50*4724848cSchristosor NULL if there is no next BIO. 51*4724848cSchristos 52*4724848cSchristos=head1 EXAMPLES 53*4724848cSchristos 54*4724848cSchristosFor these examples suppose I<md1> and I<md2> are digest BIOs, 55*4724848cSchristosI<b64> is a base64 BIO and I<f> is a file BIO. 56*4724848cSchristos 57*4724848cSchristosIf the call: 58*4724848cSchristos 59*4724848cSchristos BIO_push(b64, f); 60*4724848cSchristos 61*4724848cSchristosis made then the new chain will be I<b64-f>. After making the calls 62*4724848cSchristos 63*4724848cSchristos BIO_push(md2, b64); 64*4724848cSchristos BIO_push(md1, md2); 65*4724848cSchristos 66*4724848cSchristosthe new chain is I<md1-md2-b64-f>. Data written to I<md1> will be digested 67*4724848cSchristosby I<md1> and I<md2>, base64 encoded, and finally written to I<f>. 68*4724848cSchristos 69*4724848cSchristosIt should be noted that reading causes data to pass in the reverse 70*4724848cSchristosdirection, that is data is read from I<f>, base64 decoded, 71*4724848cSchristosand digested by I<md2> and then I<md1>. 72*4724848cSchristos 73*4724848cSchristosThe call: 74*4724848cSchristos 75*4724848cSchristos BIO_pop(md2); 76*4724848cSchristos 77*4724848cSchristoswill return I<b64> and the new chain will be I<md1-b64-f>. 78*4724848cSchristosData can be written to and read from I<md1> as before, 79*4724848cSchristosexcept that I<md2> will no more be applied. 80*4724848cSchristos 81*4724848cSchristos=head1 SEE ALSO 82*4724848cSchristos 83*4724848cSchristosL<bio> 84*4724848cSchristos 85*4724848cSchristos=head1 HISTORY 86*4724848cSchristos 87*4724848cSchristosThe BIO_set_next() function was added in OpenSSL 1.1.0. 88*4724848cSchristos 89*4724848cSchristos=head1 COPYRIGHT 90*4724848cSchristos 91*4724848cSchristosCopyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 92*4724848cSchristos 93*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 94*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 95*4724848cSchristosin the file LICENSE in the source distribution or at 96*4724848cSchristosL<https://www.openssl.org/source/license.html>. 97*4724848cSchristos 98*4724848cSchristos=cut 99