Debian Codegraph @

upstream/debian-unstable/man3/BIO_push.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "BIO_PUSH 3SSL"
58 .TH BIO_PUSH 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 BIO_push, BIO_pop, BIO_set_next \- add and remove BIOs from a chain
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/bio.h>
69 \&
70 \& BIO *BIO_push(BIO *b, BIO *next);
71 \& BIO *BIO_pop(BIO *b);
72 \& void BIO_set_next(BIO *b, BIO *next);
73 .Ve
74 .SH DESCRIPTION
75 .IX Header "DESCRIPTION"
76 \&\fBBIO_push()\fR pushes \fIb\fR on \fInext\fR.
77 If \fIb\fR is NULL the function does nothing and returns \fInext\fR.
78 Otherwise it prepends \fIb\fR, which may be a single BIO or a chain of BIOs,
79 to \fInext\fR (unless \fInext\fR is NULL).
80 It then makes a control call on \fIb\fR and returns \fIb\fR.
81 .PP
82 \&\fBBIO_pop()\fR removes the BIO \fIb\fR from any chain it is part of.
83 If \fIb\fR is NULL the function does nothing and returns NULL.
84 Otherwise it makes a control call on \fIb\fR and
85 returns the next BIO in the chain, or NULL if there is no next BIO.
86 The removed BIO becomes a single BIO with no association with
87 the original chain, it can thus be freed or be made part of a different chain.
88 .PP
89 \&\fBBIO_set_next()\fR replaces the existing next BIO in a chain with the BIO pointed to
90 by \fInext\fR. The new chain may include some of the same BIOs from the old chain
91 or it may be completely different.
92 .SH NOTES
93 .IX Header "NOTES"
94 The names of these functions are perhaps a little misleading. \fBBIO_push()\fR
95 joins two BIO chains whereas \fBBIO_pop()\fR deletes a single BIO from a chain,
96 the deleted BIO does not need to be at the end of a chain.
97 .PP
98 The process of calling \fBBIO_push()\fR and \fBBIO_pop()\fR on a BIO may have additional
99 consequences (a control call is made to the affected BIOs).
100 Any effects will be noted in the descriptions of individual BIOs.
101 .SH "RETURN VALUES"
102 .IX Header "RETURN VALUES"
103 \&\fBBIO_push()\fR returns the head of the chain,
104 which usually is \fIb\fR, or \fInext\fR if \fIb\fR is NULL.
105 .PP
106 \&\fBBIO_pop()\fR returns the next BIO in the chain,
107 or NULL if there is no next BIO.
108 .SH EXAMPLES
109 .IX Header "EXAMPLES"
110 For these examples suppose \fImd1\fR and \fImd2\fR are digest BIOs,
111 \&\fIb64\fR is a base64 BIO and \fIf\fR is a file BIO.
112 .PP
113 If the call:
114 .PP
115 .Vb 1
116 \& BIO_push(b64, f);
117 .Ve
118 .PP
119 is made then the new chain will be \fIb64\-f\fR. After making the calls
120 .PP
121 .Vb 2
122 \& BIO_push(md2, b64);
123 \& BIO_push(md1, md2);
124 .Ve
125 .PP
126 the new chain is \fImd1\-md2\-b64\-f\fR. Data written to \fImd1\fR will be digested
127 by \fImd1\fR and \fImd2\fR, base64 encoded, and finally written to \fIf\fR.
128 .PP
129 It should be noted that reading causes data to pass in the reverse
130 direction, that is data is read from \fIf\fR, base64 decoded,
131 and digested by \fImd2\fR and then \fImd1\fR.
132 .PP
133 The call:
134 .PP
135 .Vb 1
136 \& BIO_pop(md2);
137 .Ve
138 .PP
139 will return \fIb64\fR and the new chain will be \fImd1\-b64\-f\fR.
140 Data can be written to and read from \fImd1\fR as before,
141 except that \fImd2\fR will no more be applied.
142 .SH "SEE ALSO"
143 .IX Header "SEE ALSO"
144 \&\fBbio\fR\|(7)
145 .SH HISTORY
146 .IX Header "HISTORY"
147 The \fBBIO_set_next()\fR function was added in OpenSSL 1.1.0.
148 .SH COPYRIGHT
149 .IX Header "COPYRIGHT"
150 Copyright 2000\-2026 The OpenSSL Project Authors. All Rights Reserved.
151 .PP
152 Licensed under the Apache License 2.0 (the "License"). You may not use
153 this file except in compliance with the License. You can obtain a copy
154 in the file LICENSE in the source distribution or at
155 <https://www.openssl.org/source/license.html>.