1.\" $OpenBSD: BIO_ctrl.3,v 1.16 2022/08/18 18:42:13 tb 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: August 18 2022 $ 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 int 159.Fo BIO_info_cb 160.Fa "BIO *b" 161.Fa "int state" 162.Fa "int res" 163.Fc 164.Sh DESCRIPTION 165.Fn BIO_ctrl , 166.Fn BIO_callback_ctrl , 167.Fn BIO_ptr_ctrl , 168and 169.Fn BIO_int_ctrl 170are BIO "control" operations taking arguments of various types. 171These functions are not normally called directly - 172various macros are used instead. 173The standard macros are described below. 174Macros specific to a particular type of BIO 175are described in the specific BIO's manual page 176as well as any special features of the standard calls. 177.Pp 178.Fn BIO_reset 179typically resets a BIO to some initial state. 180In the case of file related BIOs, for example, 181it rewinds the file pointer to the start of the file. 182.Pp 183.Fn BIO_seek 184resets a file related BIO's (that is file descriptor and 185FILE BIOs) file position pointer to 186.Fa ofs 187bytes from start of file. 188.Pp 189.Fn BIO_tell 190returns the current file position of a file related BIO. 191.Pp 192.Fn BIO_flush 193normally writes out any internally buffered data. 194In some cases it is used to signal EOF and that no more data will be written. 195.Pp 196.Fn BIO_eof 197returns 1 if the BIO has read EOF. 198The precise meaning of "EOF" varies according to the BIO type. 199.Pp 200.Fn BIO_set_close 201sets the BIO 202.Fa b 203close flag to 204.Fa flag . 205.Fa flag 206can take the value 207.Dv BIO_CLOSE 208or 209.Dv BIO_NOCLOSE . 210Typically 211.Dv BIO_CLOSE 212is used in a source/sink BIO to indicate that the underlying I/O stream 213should be closed when the BIO is freed. 214.Pp 215.Fn BIO_get_close 216returns the BIO's close flag. 217.Pp 218.Fn BIO_pending , 219.Fn BIO_ctrl_pending , 220.Fn BIO_wpending , 221and 222.Fn BIO_ctrl_wpending 223return the number of pending characters in the BIO's read and write buffers. 224Not all BIOs support these calls. 225.Fn BIO_ctrl_pending 226and 227.Fn BIO_ctrl_wpending 228return a 229.Vt size_t 230type and are functions. 231.Fn BIO_pending 232and 233.Fn BIO_wpending 234are macros which call 235.Fn BIO_ctrl . 236.Sh RETURN VALUES 237.Fn BIO_reset 238normally returns 1 for success and 0 or -1 for failure. 239File BIOs are an exception, returning 0 for success and -1 for failure. 240.Pp 241.Fn BIO_seek 242and 243.Fn BIO_tell 244both return the current file position on success 245and -1 for failure, except file BIOs which for 246.Fn BIO_seek 247always return 0 for success and -1 for failure. 248.Pp 249.Fn BIO_flush 250returns 1 for success and 0 or -1 for failure. 251.Pp 252.Fn BIO_eof 253returns 1 if EOF has been reached or 0 otherwise. 254.Pp 255.Fn BIO_set_close 256always returns 1. 257.Pp 258.Fn BIO_get_close 259returns the close flag value 260.Dv BIO_CLOSE 261or 262.Dv BIO_NOCLOSE . 263.Pp 264.Fn BIO_pending , 265.Fn BIO_ctrl_pending , 266.Fn BIO_wpending , 267and 268.Fn BIO_ctrl_wpending 269return the amount of pending data. 270.Sh NOTES 271Because it can write data, 272.Fn BIO_flush 273may return 0 or -1 indicating that the call should be retried later 274in a similar manner to 275.Xr BIO_write 3 . 276The 277.Xr BIO_should_retry 3 278call should be used and appropriate action taken if the call fails. 279.Pp 280The return values of 281.Fn BIO_pending 282and 283.Fn BIO_wpending 284may not reliably determine the amount of pending data in all cases. 285For example in the case of a file BIO some data may be available in the 286.Vt FILE 287structure's internal buffers but it is not possible 288to determine this in a portable way. 289For other types of BIO they may not be supported. 290.Pp 291If they do not internally handle a particular 292.Fn BIO_ctrl 293operation, filter BIOs usually pass the operation 294to the next BIO in the chain. 295This often means there is no need to locate the required BIO for 296a particular operation: it can be called on a chain and it will 297be automatically passed to the relevant BIO. 298However this can cause unexpected results. 299For example no current filter BIOs implement 300.Fn BIO_seek , 301but this may still succeed if the chain ends 302in a FILE or file descriptor BIO. 303.Pp 304Source/sink BIOs return a 0 if they do not recognize the 305.Fn BIO_ctrl 306operation. 307.Sh SEE ALSO 308.Xr BIO_meth_new 3 , 309.Xr BIO_new 3 310.Sh HISTORY 311.Fn BIO_ctrl , 312.Fn BIO_reset , 313.Fn BIO_flush , 314.Fn BIO_eof , 315.Fn BIO_set_close , 316.Fn BIO_get_close , 317and 318.Fn BIO_pending 319first appeared in SSLeay 0.6.0. 320.Fn BIO_wpending 321first appeared in SSLeay 0.8.1. 322.Fn BIO_ptr_ctrl , 323.Fn BIO_int_ctrl , 324.Fn BIO_get_info_callback 325and 326.Fn BIO_set_info_callback 327first appeared in SSLeay 0.9.0. 328All these functions have been available since 329.Ox 2.4 . 330.Pp 331.Fn BIO_seek 332and 333.Fn BIO_tell 334first appeared in SSLeay 0.9.1. 335.Fn BIO_ctrl_pending 336and 337.Fn BIO_ctrl_wpending 338first appeared in OpenSSL 0.9.4. 339These functions have been available since 340.Ox 2.6 . 341.Pp 342.Fn BIO_callback_ctrl 343first appeared in OpenSSL 0.9.5 and has been available since 344.Ox 2.7 . 345.Sh BUGS 346Some of the return values are ambiguous and care should be taken. 347In particular a return value of 0 can be returned if an operation 348is not supported, if an error occurred, if EOF has not been reached 349and in the case of 350.Fn BIO_seek 351on a file BIO for a successful operation. 352