1.\" $OpenBSD: BIO_ctrl.3,v 1.6 2016/12/06 14:45:08 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: December 6 2016 $ 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.Nd BIO control operations 73.Sh SYNOPSIS 74.In openssl/bio.h 75.Ft long 76.Fo BIO_ctrl 77.Fa "BIO *bp" 78.Fa "int cmd" 79.Fa "long larg" 80.Fa "void *parg" 81.Fc 82.Ft long 83.Fo BIO_callback_ctrl 84.Fa "BIO *b" 85.Fa "int cmd" 86.Fa "bio_info_cb cb" 87.Fc 88.Ft char * 89.Fo BIO_ptr_ctrl 90.Fa "BIO *bp" 91.Fa "int cmd" 92.Fa "long larg" 93.Fc 94.Ft long 95.Fo BIO_int_ctrl 96.Fa "BIO *bp" 97.Fa "int cmd" 98.Fa "long larg" 99.Fa "int iarg" 100.Fc 101.Ft int 102.Fo BIO_reset 103.Fa "BIO *b" 104.Fc 105.Ft int 106.Fo BIO_seek 107.Fa "BIO *b" 108.Fa "int ofs" 109.Fc 110.Ft int 111.Fo BIO_tell 112.Fa "BIO *b" 113.Fc 114.Ft int 115.Fo BIO_flush 116.Fa "BIO *b" 117.Fc 118.Ft int 119.Fo BIO_eof 120.Fa "BIO *b" 121.Fc 122.Ft int 123.Fo BIO_set_close 124.Fa "BIO *b" 125.Fa "long flag" 126.Fc 127.Ft int 128.Fo BIO_get_close 129.Fa "BIO *b" 130.Fc 131.Ft int 132.Fo BIO_pending 133.Fa "BIO *b" 134.Fc 135.Ft int 136.Fo BIO_wpending 137.Fa "BIO *b" 138.Fc 139.Ft size_t 140.Fo BIO_ctrl_pending 141.Fa "BIO *b" 142.Fc 143.Ft size_t 144.Fo BIO_ctrl_wpending 145.Fa "BIO *b" 146.Fc 147.Ft int 148.Fo BIO_get_info_callback 149.Fa "BIO *b" 150.Fa "bio_info_cb **cbp" 151.Fc 152.Ft int 153.Fo BIO_set_info_callback 154.Fa "BIO *b" 155.Fa "bio_info_cb *cb" 156.Fc 157.Ft typedef void 158.Fo bio_info_cb 159.Fa "BIO *b" 160.Fa "int oper" 161.Fa "const char *ptr" 162.Fa "int arg1" 163.Fa "long arg2" 164.Fa "long arg3" 165.Fc 166.Sh DESCRIPTION 167.Fn BIO_ctrl , 168.Fn BIO_callback_ctrl , 169.Fn BIO_ptr_ctrl , 170and 171.Fn BIO_int_ctrl 172are BIO "control" operations taking arguments of various types. 173These functions are not normally called directly - 174various macros are used instead. 175The standard macros are described below. 176Macros specific to a particular type of BIO 177are described in the specific BIO's manual page 178as well as any special features of the standard calls. 179.Pp 180.Fn BIO_reset 181typically resets a BIO to some initial state. 182In the case of file related BIOs, for example, 183it rewinds the file pointer to the start of the file. 184.Pp 185.Fn BIO_seek 186resets a file related BIO's (that is file descriptor and 187FILE BIOs) file position pointer to 188.Fa ofs 189bytes from start of file. 190.Pp 191.Fn BIO_tell 192returns the current file position of a file related BIO. 193.Pp 194.Fn BIO_flush 195normally writes out any internally buffered data. 196In some cases it is used to signal EOF and that no more data will be written. 197.Pp 198.Fn BIO_eof 199returns 1 if the BIO has read EOF. 200The precise meaning of "EOF" varies according to the BIO type. 201.Pp 202.Fn BIO_set_close 203sets the BIO 204.Fa b 205close flag to 206.Fa flag . 207.Fa flag 208can take the value 209.Dv BIO_CLOSE 210or 211.Dv BIO_NOCLOSE . 212Typically 213.Dv BIO_CLOSE 214is used in a source/sink BIO to indicate that the underlying I/O stream 215should be closed when the BIO is freed. 216.Pp 217.Fn BIO_get_close 218returns the BIO's close flag. 219.Pp 220.Fn BIO_pending , 221.Fn BIO_ctrl_pending , 222.Fn BIO_wpending , 223and 224.Fn BIO_ctrl_wpending 225return the number of pending characters in the BIO's read and write buffers. 226Not all BIOs support these calls. 227.Fn BIO_ctrl_pending 228and 229.Fn BIO_ctrl_wpending 230return a 231.Vt size_t 232type and are functions. 233.Fn BIO_pending 234and 235.Fn BIO_wpending 236are macros which call 237.Fn BIO_ctrl . 238.Sh RETURN VALUES 239.Fn BIO_reset 240normally returns 1 for success and 0 or -1 for failure. 241File BIOs are an exception, returning 0 for success and -1 for failure. 242.Pp 243.Fn BIO_seek 244and 245.Fn BIO_tell 246both return the current file position on success 247and -1 for failure, except file BIOs which for 248.Fn BIO_seek 249always return 0 for success and -1 for failure. 250.Pp 251.Fn BIO_flush 252returns 1 for success and 0 or -1 for failure. 253.Pp 254.Fn BIO_eof 255returns 1 if EOF has been reached or 0 otherwise. 256.Pp 257.Fn BIO_set_close 258always returns 1. 259.Pp 260.Fn BIO_get_close 261returns the close flag value 262.Dv BIO_CLOSE 263or 264.Dv BIO_NOCLOSE . 265.Pp 266.Fn BIO_pending , 267.Fn BIO_ctrl_pending , 268.Fn BIO_wpending , 269and 270.Fn BIO_ctrl_wpending 271return the amount of pending data. 272.Sh NOTES 273Because it can write data, 274.Fn BIO_flush 275may return 0 or -1 indicating that the call should be retried later 276in a similar manner to 277.Xr BIO_write 3 . 278The 279.Xr BIO_should_retry 3 280call should be used and appropriate action taken if the call fails. 281.Pp 282The return values of 283.Fn BIO_pending 284and 285.Fn BIO_wpending 286may not reliably determine the amount of pending data in all cases. 287For example in the case of a file BIO some data may be available in the 288.Vt FILE 289structure's internal buffers but it is not possible 290to determine this in a portable way. 291For other types of BIO they may not be supported. 292.Pp 293If they do not internally handle a particular 294.Fn BIO_ctrl 295operation, filter BIOs usually pass the operation 296to the next BIO in the chain. 297This often means there is no need to locate the required BIO for 298a particular operation: it can be called on a chain and it will 299be automatically passed to the relevant BIO. 300However this can cause unexpected results. 301For example no current filter BIOs implement 302.Fn BIO_seek , 303but this may still succeed if the chain ends 304in a FILE or file descriptor BIO. 305.Pp 306Source/sink BIOs return an 0 if they do not recognize the 307.Fn BIO_ctrl 308operation. 309.Sh SEE ALSO 310.Xr BIO_new 3 311.Sh BUGS 312Some of the return values are ambiguous and care should be taken. 313In particular a return value of 0 can be returned if an operation 314is not supported, if an error occurred, if EOF has not been reached 315and in the case of 316.Fn BIO_seek 317on a file BIO for a successful operation. 318