| blob | a32ed80da7db8fc6407970de2bea9d2d058fde96 |
1 .\" $OpenBSD: BIO_ctrl.3,v 1.13 2018/03/22 16:06:33 schwarze Exp $
2 .\" OpenSSL b055fceb Thu Oct 20 09:56:18 2016 +0100
3 .\"
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 2000, 2016 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: March 22 2018 $
52 .Dt BIO_CTRL 3
53 .Os
54 .Sh NAME
55 .Nm BIO_ctrl ,
56 .Nm BIO_callback_ctrl ,
57 .Nm BIO_ptr_ctrl ,
58 .Nm BIO_int_ctrl ,
59 .Nm BIO_reset ,
60 .Nm BIO_seek ,
61 .Nm BIO_tell ,
62 .Nm BIO_flush ,
63 .Nm BIO_eof ,
64 .Nm BIO_set_close ,
65 .Nm BIO_get_close ,
66 .Nm BIO_pending ,
67 .Nm BIO_wpending ,
68 .Nm BIO_ctrl_pending ,
69 .Nm BIO_ctrl_wpending ,
70 .Nm BIO_get_info_callback ,
71 .Nm BIO_set_info_callback ,
72 .Nm bio_info_cb
73 .Nd BIO control operations
74 .Sh SYNOPSIS
75 .In openssl/bio.h
76 .Ft long
77 .Fo BIO_ctrl
78 .Fa "BIO *bp"
79 .Fa "int cmd"
80 .Fa "long larg"
81 .Fa "void *parg"
82 .Fc
83 .Ft long
84 .Fo BIO_callback_ctrl
85 .Fa "BIO *b"
86 .Fa "int cmd"
87 .Fa "bio_info_cb cb"
88 .Fc
89 .Ft char *
90 .Fo BIO_ptr_ctrl
91 .Fa "BIO *bp"
92 .Fa "int cmd"
93 .Fa "long larg"
94 .Fc
95 .Ft long
96 .Fo BIO_int_ctrl
97 .Fa "BIO *bp"
98 .Fa "int cmd"
99 .Fa "long larg"
100 .Fa "int iarg"
101 .Fc
102 .Ft int
103 .Fo BIO_reset
104 .Fa "BIO *b"
105 .Fc
106 .Ft int
107 .Fo BIO_seek
108 .Fa "BIO *b"
109 .Fa "int ofs"
110 .Fc
111 .Ft int
112 .Fo BIO_tell
113 .Fa "BIO *b"
114 .Fc
115 .Ft int
116 .Fo BIO_flush
117 .Fa "BIO *b"
118 .Fc
119 .Ft int
120 .Fo BIO_eof
121 .Fa "BIO *b"
122 .Fc
123 .Ft int
124 .Fo BIO_set_close
125 .Fa "BIO *b"
126 .Fa "long flag"
127 .Fc
128 .Ft int
129 .Fo BIO_get_close
130 .Fa "BIO *b"
131 .Fc
132 .Ft int
133 .Fo BIO_pending
134 .Fa "BIO *b"
135 .Fc
136 .Ft int
137 .Fo BIO_wpending
138 .Fa "BIO *b"
139 .Fc
140 .Ft size_t
141 .Fo BIO_ctrl_pending
142 .Fa "BIO *b"
143 .Fc
144 .Ft size_t
145 .Fo BIO_ctrl_wpending
146 .Fa "BIO *b"
147 .Fc
148 .Ft int
149 .Fo BIO_get_info_callback
150 .Fa "BIO *b"
151 .Fa "bio_info_cb **cbp"
152 .Fc
153 .Ft int
154 .Fo BIO_set_info_callback
155 .Fa "BIO *b"
156 .Fa "bio_info_cb *cb"
157 .Fc
158 .Ft typedef void
159 .Fo bio_info_cb
160 .Fa "BIO *b"
161 .Fa "int oper"
162 .Fa "const char *ptr"
163 .Fa "int arg1"
164 .Fa "long arg2"
165 .Fa "long arg3"
166 .Fc
167 .Sh DESCRIPTION
168 .Fn BIO_ctrl ,
169 .Fn BIO_callback_ctrl ,
170 .Fn BIO_ptr_ctrl ,
171 and
172 .Fn BIO_int_ctrl
173 are BIO "control" operations taking arguments of various types.
174 These functions are not normally called directly -
175 various macros are used instead.
176 The standard macros are described below.
177 Macros specific to a particular type of BIO
178 are described in the specific BIO's manual page
179 as well as any special features of the standard calls.
180 .Pp
181 .Fn BIO_reset
182 typically resets a BIO to some initial state.
183 In the case of file related BIOs, for example,
184 it rewinds the file pointer to the start of the file.
185 .Pp
186 .Fn BIO_seek
187 resets a file related BIO's (that is file descriptor and
188 FILE BIOs) file position pointer to
189 .Fa ofs
190 bytes from start of file.
191 .Pp
192 .Fn BIO_tell
193 returns the current file position of a file related BIO.
194 .Pp
195 .Fn BIO_flush
196 normally writes out any internally buffered data.
197 In some cases it is used to signal EOF and that no more data will be written.
198 .Pp
199 .Fn BIO_eof
200 returns 1 if the BIO has read EOF.
201 The precise meaning of "EOF" varies according to the BIO type.
202 .Pp
203 .Fn BIO_set_close
204 sets the BIO
205 .Fa b
206 close flag to
207 .Fa flag .
208 .Fa flag
209 can take the value
210 .Dv BIO_CLOSE
211 or
212 .Dv BIO_NOCLOSE .
213 Typically
214 .Dv BIO_CLOSE
215 is used in a source/sink BIO to indicate that the underlying I/O stream
216 should be closed when the BIO is freed.
217 .Pp
218 .Fn BIO_get_close
219 returns the BIO's close flag.
220 .Pp
221 .Fn BIO_pending ,
222 .Fn BIO_ctrl_pending ,
223 .Fn BIO_wpending ,
224 and
225 .Fn BIO_ctrl_wpending
226 return the number of pending characters in the BIO's read and write buffers.
227 Not all BIOs support these calls.
228 .Fn BIO_ctrl_pending
229 and
230 .Fn BIO_ctrl_wpending
231 return a
232 .Vt size_t
233 type and are functions.
234 .Fn BIO_pending
235 and
236 .Fn BIO_wpending
237 are macros which call
238 .Fn BIO_ctrl .
239 .Sh RETURN VALUES
240 .Fn BIO_reset
241 normally returns 1 for success and 0 or -1 for failure.
242 File BIOs are an exception, returning 0 for success and -1 for failure.
243 .Pp
244 .Fn BIO_seek
245 and
246 .Fn BIO_tell
247 both return the current file position on success
248 and -1 for failure, except file BIOs which for
249 .Fn BIO_seek
250 always return 0 for success and -1 for failure.
251 .Pp
252 .Fn BIO_flush
253 returns 1 for success and 0 or -1 for failure.
254 .Pp
255 .Fn BIO_eof
256 returns 1 if EOF has been reached or 0 otherwise.
257 .Pp
258 .Fn BIO_set_close
259 always returns 1.
260 .Pp
261 .Fn BIO_get_close
262 returns the close flag value
263 .Dv BIO_CLOSE
264 or
265 .Dv BIO_NOCLOSE .
266 .Pp
267 .Fn BIO_pending ,
268 .Fn BIO_ctrl_pending ,
269 .Fn BIO_wpending ,
270 and
271 .Fn BIO_ctrl_wpending
272 return the amount of pending data.
273 .Sh NOTES
274 Because it can write data,
275 .Fn BIO_flush
276 may return 0 or -1 indicating that the call should be retried later
277 in a similar manner to
278 .Xr BIO_write 3 .
279 The
280 .Xr BIO_should_retry 3
281 call should be used and appropriate action taken if the call fails.
282 .Pp
283 The return values of
284 .Fn BIO_pending
285 and
286 .Fn BIO_wpending
287 may not reliably determine the amount of pending data in all cases.
288 For example in the case of a file BIO some data may be available in the
289 .Vt FILE
290 structure's internal buffers but it is not possible
291 to determine this in a portable way.
292 For other types of BIO they may not be supported.
293 .Pp
294 If they do not internally handle a particular
295 .Fn BIO_ctrl
296 operation, filter BIOs usually pass the operation
297 to the next BIO in the chain.
298 This often means there is no need to locate the required BIO for
299 a particular operation: it can be called on a chain and it will
300 be automatically passed to the relevant BIO.
301 However this can cause unexpected results.
302 For example no current filter BIOs implement
303 .Fn BIO_seek ,
304 but this may still succeed if the chain ends
305 in a FILE or file descriptor BIO.
306 .Pp
307 Source/sink BIOs return an 0 if they do not recognize the
308 .Fn BIO_ctrl
309 operation.
310 .Sh SEE ALSO
311 .Xr BIO_meth_new 3 ,
312 .Xr BIO_new 3
313 .Sh HISTORY
314 .Fn BIO_ctrl ,
315 .Fn BIO_reset ,
316 .Fn BIO_flush ,
317 .Fn BIO_eof ,
318 .Fn BIO_set_close ,
319 .Fn BIO_get_close ,
320 .Fn BIO_pending ,
321 and
322 .Fn BIO_wpending
323 appeared in SSLeay 0.8.1b or earlier.
324 .Fn BIO_ptr_ctrl ,
325 .Fn BIO_int_ctrl ,
326 .Fn BIO_get_info_callback
327 and
328 .Fn BIO_set_info_callback
329 first appeared in SSLeay 0.9.0.
330 All these functions have been available since
331 .Ox 2.4 .
332 .Pp
333 .Fn BIO_seek
334 and
335 .Fn BIO_tell
336 first appeared in SSLeay 0.9.1.
337 .Fn BIO_ctrl_pending
338 and
339 .Fn BIO_ctrl_wpending
340 first appeared in OpenSSL 0.9.4.
341 These functions have been available since
342 .Ox 2.6 .
343 .Pp
344 .Fn BIO_callback_ctrl
345 first appeared in OpenSSL 0.9.5 and has been available since
346 .Ox 2.7 .
347 .Sh BUGS
348 Some of the return values are ambiguous and care should be taken.
349 In particular a return value of 0 can be returned if an operation
350 is not supported, if an error occurred, if EOF has not been reached
351 and in the case of
352 .Fn BIO_seek
353 on a file BIO for a successful operation.