| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
|
|---|
| 6 |
|
|---|
| 7 | =head1 SYNOPSIS
|
|---|
| 8 |
|
|---|
| 9 | #include <openssl/bio.h>
|
|---|
| 10 |
|
|---|
| 11 | BIO *BIO_push(BIO *b, BIO *append);
|
|---|
| 12 | BIO *BIO_pop(BIO *b);
|
|---|
| 13 | void BIO_set_next(BIO *b, BIO *next);
|
|---|
| 14 |
|
|---|
| 15 | =head1 DESCRIPTION
|
|---|
| 16 |
|
|---|
| 17 | The BIO_push() function appends the BIO B<append> to B<b>, it returns
|
|---|
| 18 | B<b>.
|
|---|
| 19 |
|
|---|
| 20 | BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
|
|---|
| 21 | in the chain, or NULL if there is no next BIO. The removed BIO then
|
|---|
| 22 | becomes a single BIO with no association with the original chain,
|
|---|
| 23 | it can thus be freed or attached to a different chain.
|
|---|
| 24 |
|
|---|
| 25 | BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
|
|---|
| 26 | by B<next>. The new chain may include some of the same BIOs from the old chain
|
|---|
| 27 | or it may be completely different.
|
|---|
| 28 |
|
|---|
| 29 | =head1 NOTES
|
|---|
| 30 |
|
|---|
| 31 | The names of these functions are perhaps a little misleading. BIO_push()
|
|---|
| 32 | joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
|
|---|
| 33 | the deleted BIO does not need to be at the end of a chain.
|
|---|
| 34 |
|
|---|
| 35 | The process of calling BIO_push() and BIO_pop() on a BIO may have additional
|
|---|
| 36 | consequences (a control call is made to the affected BIOs) any effects will
|
|---|
| 37 | be noted in the descriptions of individual BIOs.
|
|---|
| 38 |
|
|---|
| 39 | =head1 RETURN VALUES
|
|---|
| 40 |
|
|---|
| 41 | BIO_push() returns the end of the chain, B<b>.
|
|---|
| 42 |
|
|---|
| 43 | BIO_pop() returns the next BIO in the chain, or NULL if there is no next
|
|---|
| 44 | BIO.
|
|---|
| 45 |
|
|---|
| 46 | =head1 EXAMPLES
|
|---|
| 47 |
|
|---|
| 48 | For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
|
|---|
| 49 | a base64 BIO and B<f> is a file BIO.
|
|---|
| 50 |
|
|---|
| 51 | If the call:
|
|---|
| 52 |
|
|---|
| 53 | BIO_push(b64, f);
|
|---|
| 54 |
|
|---|
| 55 | is made then the new chain will be B<b64-f>. After making the calls
|
|---|
| 56 |
|
|---|
| 57 | BIO_push(md2, b64);
|
|---|
| 58 | BIO_push(md1, md2);
|
|---|
| 59 |
|
|---|
| 60 | the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
|
|---|
| 61 | by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
|
|---|
| 62 |
|
|---|
| 63 | It should be noted that reading causes data to pass in the reverse
|
|---|
| 64 | direction, that is data is read from B<f>, B<base64> decoded and digested
|
|---|
| 65 | by B<md2> and B<md1>. If the call:
|
|---|
| 66 |
|
|---|
| 67 | BIO_pop(md2);
|
|---|
| 68 |
|
|---|
| 69 | The call will return B<b64> and the new chain will be B<md1-b64-f> data can
|
|---|
| 70 | be written to B<md1> as before.
|
|---|
| 71 |
|
|---|
| 72 | =head1 SEE ALSO
|
|---|
| 73 |
|
|---|
| 74 | L<bio>
|
|---|
| 75 |
|
|---|
| 76 | =head1 HISTORY
|
|---|
| 77 |
|
|---|
| 78 | The BIO_set_next() function was added in OpenSSL 1.1.0.
|
|---|
| 79 |
|
|---|
| 80 | =head1 COPYRIGHT
|
|---|
| 81 |
|
|---|
| 82 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 83 |
|
|---|
| 84 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 85 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 86 | in the file LICENSE in the source distribution or at
|
|---|
| 87 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 88 |
|
|---|
| 89 | =cut
|
|---|
