Merge branch 'master' into net80211-update
[dragonfly.git] / secure / lib / libcrypto / man / BIO_push.3
1 .\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sh \" Subsection heading
6 .br
7 .if t .Sp
8 .ne 5
9 .PP
10 \fB\\$1\fR
11 .PP
12 ..
13 .de Sp \" Vertical space (when we can't use .PP)
14 .if t .sp .5v
15 .if n .sp
16 ..
17 .de Vb \" Begin verbatim text
18 .ft CW
19 .nf
20 .ne \\$1
21 ..
22 .de Ve \" End verbatim text
23 .ft R
24 .fi
25 ..
26 .\" Set up some character translations and predefined strings.  \*(-- will
27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
31 .\" nothing in troff, for use with C<>.
32 .tr \(*W-
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
34 .ie n \{\
35 .    ds -- \(*W-
36 .    ds PI pi
37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
39 .    ds L" ""
40 .    ds R" ""
41 .    ds C` ""
42 .    ds C' ""
43 'br\}
44 .el\{\
45 .    ds -- \|\(em\|
46 .    ds PI \(*p
47 .    ds L" ``
48 .    ds R" ''
49 'br\}
50 .\"
51 .\" Escape single quotes in literal strings from groff's Unicode transform.
52 .ie \n(.g .ds Aq \(aq
53 .el       .ds Aq '
54 .\"
55 .\" If the F register is turned on, we'll generate index entries on stderr for
56 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
57 .\" entries marked with X<> in POD.  Of course, you'll have to process the
58 .\" output yourself in some meaningful fashion.
59 .ie \nF \{\
60 .    de IX
61 .    tm Index:\\$1\t\\n%\t"\\$2"
62 ..
63 .    nr % 0
64 .    rr F
65 .\}
66 .el \{\
67 .    de IX
68 ..
69 .\}
70 .\"
71 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
72 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
73 .    \" fudge factors for nroff and troff
74 .if n \{\
75 .    ds #H 0
76 .    ds #V .8m
77 .    ds #F .3m
78 .    ds #[ \f1
79 .    ds #] \fP
80 .\}
81 .if t \{\
82 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
83 .    ds #V .6m
84 .    ds #F 0
85 .    ds #[ \&
86 .    ds #] \&
87 .\}
88 .    \" simple accents for nroff and troff
89 .if n \{\
90 .    ds ' \&
91 .    ds ` \&
92 .    ds ^ \&
93 .    ds , \&
94 .    ds ~ ~
95 .    ds /
96 .\}
97 .if t \{\
98 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
99 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
100 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
101 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
102 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
103 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
104 .\}
105 .    \" troff and (daisy-wheel) nroff accents
106 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
107 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
108 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
109 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
110 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
111 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
112 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
113 .ds ae a\h'-(\w'a'u*4/10)'e
114 .ds Ae A\h'-(\w'A'u*4/10)'E
115 .    \" corrections for vroff
116 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
117 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
118 .    \" for low resolution devices (crt and lpr)
119 .if \n(.H>23 .if \n(.V>19 \
120 \{\
121 .    ds : e
122 .    ds 8 ss
123 .    ds o a
124 .    ds d- d\h'-1'\(ga
125 .    ds D- D\h'-1'\(hy
126 .    ds th \o'bp'
127 .    ds Th \o'LP'
128 .    ds ae ae
129 .    ds Ae AE
130 .\}
131 .rm #[ #] #H #V #F C
132 .\" ========================================================================
133 .\"
134 .IX Title "BIO_push 3"
135 .TH BIO_push 3 "2010-02-27" "0.9.8m" "OpenSSL"
136 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
137 .\" way too many mistakes in technical documents.
138 .if n .ad l
139 .nh
140 .SH "NAME"
141 BIO_push, BIO_pop \- add and remove BIOs from a chain.
142 .SH "SYNOPSIS"
143 .IX Header "SYNOPSIS"
144 .Vb 1
145 \& #include <openssl/bio.h>
146 \&
147 \& BIO *  BIO_push(BIO *b,BIO *append);
148 \& BIO *  BIO_pop(BIO *b);
149 .Ve
150 .SH "DESCRIPTION"
151 .IX Header "DESCRIPTION"
152 The \fIBIO_push()\fR function appends the \s-1BIO\s0 \fBappend\fR to \fBb\fR, it returns
153 \&\fBb\fR.
154 .PP
155 \&\fIBIO_pop()\fR removes the \s-1BIO\s0 \fBb\fR from a chain and returns the next \s-1BIO\s0
156 in the chain, or \s-1NULL\s0 if there is no next \s-1BIO\s0. The removed \s-1BIO\s0 then
157 becomes a single \s-1BIO\s0 with no association with the original chain,
158 it can thus be freed or attached to a different chain.
159 .SH "NOTES"
160 .IX Header "NOTES"
161 The names of these functions are perhaps a little misleading. \fIBIO_push()\fR
162 joins two \s-1BIO\s0 chains whereas \fIBIO_pop()\fR deletes a single \s-1BIO\s0 from a chain,
163 the deleted \s-1BIO\s0 does not need to be at the end of a chain.
164 .PP
165 The process of calling \fIBIO_push()\fR and \fIBIO_pop()\fR on a \s-1BIO\s0 may have additional
166 consequences (a control call is made to the affected BIOs) any effects will
167 be noted in the descriptions of individual BIOs.
168 .SH "EXAMPLES"
169 .IX Header "EXAMPLES"
170 For these examples suppose \fBmd1\fR and \fBmd2\fR are digest BIOs, \fBb64\fR is
171 a base64 \s-1BIO\s0 and \fBf\fR is a file \s-1BIO\s0.
172 .PP
173 If the call:
174 .PP
175 .Vb 1
176 \& BIO_push(b64, f);
177 .Ve
178 .PP
179 is made then the new chain will be \fBb64\-chain\fR. After making the calls
180 .PP
181 .Vb 2
182 \& BIO_push(md2, b64);
183 \& BIO_push(md1, md2);
184 .Ve
185 .PP
186 the new chain is \fBmd1\-md2\-b64\-f\fR. Data written to \fBmd1\fR will be digested
187 by \fBmd1\fR and \fBmd2\fR, \fBbase64\fR encoded and written to \fBf\fR.
188 .PP
189 It should be noted that reading causes data to pass in the reverse
190 direction, that is data is read from \fBf\fR, base64 \fBdecoded\fR and digested
191 by \fBmd1\fR and \fBmd2\fR. If the call:
192 .PP
193 .Vb 1
194 \& BIO_pop(md2);
195 .Ve
196 .PP
197 The call will return \fBb64\fR and the new chain will be \fBmd1\-b64\-f\fR data can
198 be written to \fBmd1\fR as before.
199 .SH "RETURN VALUES"
200 .IX Header "RETURN VALUES"
201 \&\fIBIO_push()\fR returns the end of the chain, \fBb\fR.
202 .PP
203 \&\fIBIO_pop()\fR returns the next \s-1BIO\s0 in the chain, or \s-1NULL\s0 if there is no next
204 \&\s-1BIO\s0.
205 .SH "SEE ALSO"
206 .IX Header "SEE ALSO"
207 \&\s-1TBA\s0