]>
Commit | Line | Data |
---|---|---|
47770c4d DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
bb9ad09e | 5 | BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain |
47770c4d DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/bio.h> | |
10 | ||
aebb9aac | 11 | BIO *BIO_push(BIO *b, BIO *append); |
85556b4d MC |
12 | BIO *BIO_pop(BIO *b); |
13 | void BIO_set_next(BIO *b, BIO *next); | |
47770c4d DSH |
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 | ||
85556b4d MC |
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 | ||
47770c4d DSH |
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 | ||
4564e77a PY |
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 | ||
47770c4d DSH |
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 | ||
76ed5a42 | 55 | is made then the new chain will be B<b64-f>. After making the calls |
47770c4d DSH |
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>, base64 B<decoded> and digested | |
65 | by B<md1> and B<md2>. 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 | ||
47770c4d DSH |
72 | =head1 SEE ALSO |
73 | ||
85556b4d MC |
74 | L<bio> |
75 | ||
76 | =head1 HISTORY | |
77 | ||
e90fc053 | 78 | The BIO_set_next() function was added in OpenSSL 1.1.0. |
85556b4d | 79 | |
e2f92610 RS |
80 | =head1 COPYRIGHT |
81 | ||
82 | Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved. | |
83 | ||
4746f25a | 84 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
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 |