1.\" $OpenBSD: BIO_ctrl.3,v 1.23 2023/05/01 07:28:11 tb Exp $ 2.\" full merge up to: OpenSSL 24a535eaf Tue Sep 22 13:14:20 2020 +0100 3.\" selective merge up to: OpenSSL 0c5bc96f Tue Mar 15 13:57:22 2022 +0000 4.\" 5.\" This file is a derived work. 6.\" The changes are covered by the following Copyright and license: 7.\" 8.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 9.\" 10.\" Permission to use, copy, modify, and distribute this software for any 11.\" purpose with or without fee is hereby granted, provided that the above 12.\" copyright notice and this permission notice appear in all copies. 13.\" 14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 21.\" 22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>. 23.\" Copyright (c) 2000, 2016 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: May 1 2023 $ 70.Dt BIO_CTRL 3 71.Os 72.Sh NAME 73.Nm BIO_ctrl , 74.Nm BIO_callback_ctrl , 75.Nm BIO_ptr_ctrl , 76.Nm BIO_int_ctrl , 77.Nm BIO_reset , 78.Nm BIO_seek , 79.Nm BIO_tell , 80.Nm BIO_flush , 81.Nm BIO_eof , 82.Nm BIO_set_close , 83.Nm BIO_get_close , 84.Nm BIO_pending , 85.Nm BIO_wpending , 86.Nm BIO_ctrl_pending , 87.Nm BIO_ctrl_wpending , 88.Nm BIO_get_info_callback , 89.Nm BIO_set_info_callback , 90.Nm BIO_info_cb , 91.Nm bio_info_cb 92.Nd BIO control operations 93.Sh SYNOPSIS 94.In openssl/bio.h 95.Ft long 96.Fo BIO_ctrl 97.Fa "BIO *b" 98.Fa "int cmd" 99.Fa "long larg" 100.Fa "void *parg" 101.Fc 102.Ft long 103.Fo BIO_callback_ctrl 104.Fa "BIO *b" 105.Fa "int cmd" 106.Fa "BIO_info_cb *cb" 107.Fc 108.Ft char * 109.Fo BIO_ptr_ctrl 110.Fa "BIO *b" 111.Fa "int cmd" 112.Fa "long larg" 113.Fc 114.Ft long 115.Fo BIO_int_ctrl 116.Fa "BIO *b" 117.Fa "int cmd" 118.Fa "long larg" 119.Fa "int iarg" 120.Fc 121.Ft int 122.Fo BIO_reset 123.Fa "BIO *b" 124.Fc 125.Ft int 126.Fo BIO_seek 127.Fa "BIO *b" 128.Fa "int ofs" 129.Fc 130.Ft int 131.Fo BIO_tell 132.Fa "BIO *b" 133.Fc 134.Ft int 135.Fo BIO_flush 136.Fa "BIO *b" 137.Fc 138.Ft int 139.Fo BIO_eof 140.Fa "BIO *b" 141.Fc 142.Ft int 143.Fo BIO_set_close 144.Fa "BIO *b" 145.Fa "long flag" 146.Fc 147.Ft int 148.Fo BIO_get_close 149.Fa "BIO *b" 150.Fc 151.Ft int 152.Fo BIO_pending 153.Fa "BIO *b" 154.Fc 155.Ft int 156.Fo BIO_wpending 157.Fa "BIO *b" 158.Fc 159.Ft size_t 160.Fo BIO_ctrl_pending 161.Fa "BIO *b" 162.Fc 163.Ft size_t 164.Fo BIO_ctrl_wpending 165.Fa "BIO *b" 166.Fc 167.Ft int 168.Fo BIO_get_info_callback 169.Fa "BIO *b" 170.Fa "BIO_info_cb **cbp" 171.Fc 172.Ft int 173.Fo BIO_set_info_callback 174.Fa "BIO *b" 175.Fa "BIO_info_cb *cb" 176.Fc 177.Ft typedef int 178.Fo BIO_info_cb 179.Fa "BIO *b" 180.Fa "int state" 181.Fa "int res" 182.Fc 183.Ft typedef int 184.Fo bio_info_cb 185.Fa "BIO *b" 186.Fa "int state" 187.Fa "int res" 188.Fc 189.Sh DESCRIPTION 190.Fn BIO_ctrl , 191.Fn BIO_callback_ctrl , 192.Fn BIO_ptr_ctrl , 193and 194.Fn BIO_int_ctrl 195are BIO "control" operations taking arguments of various types. 196These functions are not normally called directly - 197various macros are used instead. 198The standard macros are described below. 199Macros specific to a particular type of BIO 200are described in the specific BIO's manual page 201as well as any special features of the standard calls. 202.Pp 203Depending on the 204.Fa cmd 205and on the type of 206.Fa b , 207.Fn BIO_ctrl 208may have a read-only effect on 209.Fa b 210or change data in 211.Fa b 212or in its sub-structures. 213It may also have a side effect of changing the memory pointed to by 214.Fa parg . 215.Pp 216.Fn BIO_callback_ctrl 217does not call 218.Fn BIO_ctrl 219but instead requires that the BIO type of 220.Fa b 221provides a dedicated 222.Fa callback_ctrl 223function pointer, which is built into the library for some standard BIO 224types and can be provided with 225.Xr BIO_meth_set_callback_ctrl 3 226for application-defined BIO types. 227The only 228.Fa cmd 229supported by 230.Fn BIO_callback_ctrl 231is 232.Dv BIO_CTRL_SET_CALLBACK . 233.Pp 234.Fn BIO_ptr_ctrl 235calls 236.Fn BIO_ctrl 237with 238.Fa parg 239pointing to the location of a temporary pointer variable initialized to 240.Dv NULL . 241.Pp 242.Fn BIO_int_ctrl 243calls 244.Fn BIO_ctrl 245with 246.Fa parg 247pointing to the location of a temporary 248.Vt int 249variable initialized to 250.Fa iarg . 251If 252.Fn BIO_ctrl 253changes the value stored at 254.Pf * Fa parg , 255the new value is ignored. 256.Pp 257.Fn BIO_reset 258typically resets a BIO to some initial state. 259In the case of file related BIOs, for example, 260it rewinds the file pointer to the start of the file. 261.Pp 262.Fn BIO_seek 263resets a file related BIO's (that is file descriptor and 264FILE BIOs) file position pointer to 265.Fa ofs 266bytes from start of file. 267.Pp 268.Fn BIO_tell 269returns the current file position of a file related BIO. 270.Pp 271.Fn BIO_flush 272normally writes out any internally buffered data. 273In some cases it is used to signal EOF and that no more data will be written. 274.Pp 275.Fn BIO_eof 276returns 1 if the BIO has read EOF. 277The precise meaning of "EOF" varies according to the BIO type. 278.Pp 279.Fn BIO_set_close 280sets the BIO 281.Fa b 282close flag to 283.Fa flag . 284.Fa flag 285can take the value 286.Dv BIO_CLOSE 287or 288.Dv BIO_NOCLOSE . 289Typically 290.Dv BIO_CLOSE 291is used in a source/sink BIO to indicate that the underlying I/O stream 292should be closed when the BIO is freed. 293.Pp 294.Fn BIO_get_close 295returns the BIO's close flag. 296.Pp 297.Fn BIO_pending , 298.Fn BIO_ctrl_pending , 299.Fn BIO_wpending , 300and 301.Fn BIO_ctrl_wpending 302return the number of pending characters in the BIO's read and write buffers. 303Not all BIOs support these calls. 304.Fn BIO_ctrl_pending 305and 306.Fn BIO_ctrl_wpending 307return a 308.Vt size_t 309type and are functions. 310.Fn BIO_pending 311and 312.Fn BIO_wpending 313are macros which call 314.Fn BIO_ctrl . 315.Pp 316.Fn BIO_set_info_callback 317installs the function pointer 318.Fa cb 319as an info callback in 320.Fa b 321by calling 322.Fn BIO_callback_ctrl 323with a command of 324.Dv BIO_CTRL_SET_CALLBACK . 325Among the BIO types built into the library, only 326.Xr BIO_s_connect 3 327and 328.Xr BIO_f_ssl 3 329support this functionality. 330Some filter BIO types forward this control call 331to the next BIO in the chain instead of processing it themselves. 332.Pp 333.Fn BIO_get_info_callback 334places the function pointer to the info callback into 335.Pf * Fa cbp 336if any was installed using 337.Fn BIO_set_info_callback 338or 339.Fn BIO_callback_ctrl . 340If the type of 341.Fa b 342supports setting an info callback but none was installed, it stores a 343.Dv NULL 344pointer in 345.Pf * Fa cbp . 346.Pp 347The function type name 348.Vt bio_info_cb 349is a deprecated synonym for 350.Vt BIO_info_cb 351provided for backward compatibility with some existing application software. 352.Pp 353The following 354.Fa cmd 355constants correspond to macros: 356.Bl -column BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT BIO_set_ssl_renegotiate_timeout(3) 357.It Fa cmd No constant Ta corresponding macro 358.It Dv BIO_C_DESTROY_BIO_PAIR Ta Xr BIO_destroy_bio_pair 3 359.It Dv BIO_C_DO_STATE_MACHINE Ta Xr BIO_do_handshake 3 360.It Dv BIO_C_FILE_SEEK Ta Fn BIO_seek 361.It Dv BIO_C_FILE_TELL Ta Fn BIO_tell 362.It Dv BIO_C_GET_ACCEPT Ta Xr BIO_get_accept_port 3 363.It Dv BIO_C_GET_BIND_MODE Ta Xr BIO_get_bind_mode 3 364.It Dv BIO_C_GET_BUF_MEM_PTR Ta Xr BIO_get_mem_ptr 3 365.It Dv BIO_C_GET_BUFF_NUM_LINES Ta Xr BIO_get_buffer_num_lines 3 366.It Dv BIO_C_GET_CIPHER_CTX Ta Xr BIO_get_cipher_ctx 3 367.It Dv BIO_C_GET_CIPHER_STATUS Ta Xr BIO_get_cipher_status 3 368.It Dv BIO_C_GET_FD Ta Xr BIO_get_fd 3 369.It Dv BIO_C_GET_FILE_PTR Ta Xr BIO_get_fp 3 370.It Dv BIO_C_GET_MD Ta Xr BIO_get_md 3 371.It Dv BIO_C_GET_MD_CTX Ta Xr BIO_get_md_ctx 3 372.It Dv BIO_C_GET_READ_REQUEST Ta Xr BIO_get_read_request 3 373.It Dv BIO_C_GET_SSL Ta Xr BIO_get_ssl 3 374.It Dv BIO_C_GET_SSL_NUM_RENEGOTIATES Ta Xr BIO_get_num_renegotiates 3 375.It Dv BIO_C_GET_WRITE_BUF_SIZE Ta Xr BIO_get_write_buf_size 3 376.It Dv BIO_C_GET_WRITE_GUARANTEE Ta Xr BIO_get_write_guarantee 3 377.It Dv BIO_C_MAKE_BIO_PAIR Ta Xr BIO_make_bio_pair 3 378.It Dv BIO_C_RESET_READ_REQUEST Ta Xr BIO_ctrl_reset_read_request 3 379.It Dv BIO_C_SET_BIND_MODE Ta Xr BIO_set_bind_mode 3 380.It Dv BIO_C_SET_BUF_MEM Ta Xr BIO_set_mem_buf 3 381.It Dv BIO_C_SET_BUF_MEM_EOF_RETURN Ta Xr BIO_set_mem_eof_return 3 382.It Dv BIO_C_SET_BUFF_READ_DATA Ta Xr BIO_set_buffer_read_data 3 383.It Dv BIO_C_SET_FD Ta Xr BIO_set_fd 3 384.It Dv BIO_C_SET_FILE_PTR Ta Xr BIO_set_fp 3 385.It Dv BIO_C_SET_MD Ta Xr BIO_set_md 3 386.It Dv BIO_C_SET_MD_CTX Ta Xr BIO_set_md_ctx 3 387.It Dv BIO_C_SET_NBIO Ta Xr BIO_set_nbio 3 388.It Dv BIO_C_SET_SSL Ta Xr BIO_set_ssl 3 389.It Dv BIO_C_SET_SSL_RENEGOTIATE_BYTES Ta Xr BIO_set_ssl_renegotiate_bytes 3 390.It Dv BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT Ta Xr BIO_set_ssl_renegotiate_timeout 3 391.It Dv BIO_C_SET_WRITE_BUF_SIZE Ta Xr BIO_set_write_buf_size 3 392.It Dv BIO_C_SHUTDOWN_WR Ta Xr BIO_shutdown_wr 3 393.It Dv BIO_C_SSL_MODE Ta Xr BIO_set_ssl_mode 3 394.It Dv BIO_CTRL_DGRAM_CONNECT Ta Xr BIO_ctrl_dgram_connect 3 395.It Dv BIO_CTRL_DGRAM_GET_PEER Ta Xr BIO_dgram_get_peer 3 396.It Dv BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP Ta Xr BIO_dgram_recv_timedout 3 397.It Dv BIO_CTRL_DGRAM_GET_SEND_TIMER_EXP Ta Xr BIO_dgram_send_timedout 3 398.It Dv BIO_CTRL_DGRAM_SET_CONNECTED Ta Xr BIO_ctrl_set_connected 3 399.It Dv BIO_CTRL_DGRAM_SET_PEER Ta Xr BIO_dgram_set_peer 3 400.It Dv BIO_CTRL_DUP Ta Xr BIO_dup_state 3 401.It Dv BIO_CTRL_EOF Ta Fn BIO_eof 402.It Dv BIO_CTRL_FLUSH Ta Fn BIO_flush 403.It Dv BIO_CTRL_GET_CALLBACK Ta Fn BIO_get_info_callback 404.It Dv BIO_CTRL_GET_CLOSE Ta Fn BIO_get_close 405.It Dv BIO_CTRL_INFO Ta Xr BIO_get_mem_data 3 406.It Dv BIO_CTRL_PENDING Ta Fn BIO_pending 407.It Dv BIO_CTRL_RESET Ta Fn BIO_reset 408.It Dv BIO_CTRL_SET_CALLBACK Ta Fn BIO_set_info_callback 409.It Dv BIO_CTRL_SET_CLOSE Ta Fn BIO_set_close 410.It Dv BIO_CTRL_WPENDING Ta Fn BIO_wpending 411.El 412.Pp 413A few 414.Fa cmd 415constants serve more than one macro each 416and are documented in the following manual pages: 417.Bl -column BIO_C_SET_BUFF_SIZE BIO_s_connect(3) -offset 3n 418.It Fa cmd No constant Ta manual page 419.It Dv BIO_C_GET_CONNECT Ta Xr BIO_s_connect 3 420.It Dv BIO_C_SET_ACCEPT Ta Xr BIO_s_accept 3 421.It Dv BIO_C_SET_BUFF_SIZE Ta Xr BIO_f_buffer 3 422.It Dv BIO_C_SET_CONNECT Ta Xr BIO_s_connect 3 423.It Dv BIO_C_SET_FILENAME Ta Xr BIO_s_file 3 424.El 425.Pp 426Some 427.Fa cmd 428constants are not associated with any macros. 429They are documented in the following manual pages: 430.Bl -column BIO_CTRL_DGRAM_SET_RECV_TIMEOUT BIO_dgram_recv_timedout(3)\ 431 -offset 3n 432.It Fa cmd No constant Ta manual page 433.It Dv BIO_C_GET_EX_ARG Ta Xr BIO_f_asn1 3 434.It Dv BIO_C_GET_PREFIX Ta Xr BIO_asn1_get_prefix 3 435.It Dv BIO_C_GET_SUFFIX Ta Xr BIO_asn1_get_suffix 3 436.It Dv BIO_C_SET_EX_ARG Ta Xr BIO_f_asn1 3 437.It Dv BIO_C_SET_PREFIX Ta Xr BIO_asn1_set_prefix 3 438.It Dv BIO_C_SET_SUFFIX Ta Xr BIO_asn1_set_suffix 3 439.It Dv BIO_CTRL_DGRAM_GET_FALLBACK_MTU Ta Xr BIO_dgram_set_peer 3 440.It Dv BIO_CTRL_DGRAM_GET_MTU Ta Xr BIO_dgram_set_peer 3 441.It Dv BIO_CTRL_DGRAM_GET_RECV_TIMEOUT Ta Xr BIO_dgram_recv_timedout 3 442.It Dv BIO_CTRL_DGRAM_GET_SEND_TIMEOUT Ta Xr BIO_dgram_send_timedout 3 443.It Dv BIO_CTRL_DGRAM_SET_MTU Ta Xr BIO_dgram_set_peer 3 444.It Dv BIO_CTRL_DGRAM_SET_NEXT_TIMEOUT Ta Xr BIO_dgram_recv_timedout 3 445.It Dv BIO_CTRL_DGRAM_SET_RECV_TIMEOUT Ta Xr BIO_dgram_recv_timedout 3 446.It Dv BIO_CTRL_DGRAM_SET_SEND_TIMEOUT Ta Xr BIO_dgram_send_timedout 3 447.It Dv BIO_CTRL_DGRAM_MTU_EXCEEDED Ta Xr BIO_s_datagram 3 448.It Dv BIO_CTRL_POP Ta Xr BIO_pop 3 449.It Dv BIO_CTRL_PUSH Ta Xr BIO_push 3 450.El 451.Sh RETURN VALUES 452The meaning of the return values of 453.Fn BIO_ctrl , 454.Fn BIO_callback_ctrl , 455and 456.Fn BIO_int_ctrl 457depends on both the type of 458.Fa b 459and on the 460.Fa cmd . 461If 462.Fa b 463is a 464.Dv NULL 465pointer, no action occurs and 0 is returned. 466The return value \-2 usually indicates a fatal error. 467In particular, it is returned if the 468.Fa cmd 469is unsupported by the type of 470.Fa b . 471.Pp 472.Fn BIO_callback_ctrl 473and 474.Fn BIO_set_info_callback 475return 1 on success, 0 if 476.Fa b 477is 478.Dv NULL 479or to indicate failure of a valid 480.Fa cmd , 481or \-2 if the 482.Fa cmd 483is not supported by 484.Fa b . 485.Pp 486.Fn BIO_ptr_ctrl 487returns 488.Dv NULL 489if the 490.Fn BIO_ctrl 491call returns a negative value or does not change 492.Pf * Fa parg , 493or the pointer it puts into 494.Pf * Fa parg 495otherwise. 496.Pp 497.Fn BIO_int_ctrl 498returns the return value of 499.Fn BIO_ctrl . 500.Pp 501.Fn BIO_reset 502normally returns 1 for success and 0 or -1 for failure. 503File BIOs are an exception, returning 0 for success and -1 for failure. 504.Pp 505.Fn BIO_seek 506and 507.Fn BIO_tell 508both return the current file position on success 509and -1 for failure, except file BIOs which for 510.Fn BIO_seek 511always return 0 for success and -1 for failure. 512.Pp 513.Fn BIO_flush 514returns 1 for success and 0 or -1 for failure. 515.Pp 516.Fn BIO_eof 517returns 1 if EOF has been reached or 0 otherwise. 518.Pp 519.Fn BIO_set_close 520always returns 1. 521.Pp 522.Fn BIO_get_close 523returns the close flag value 524.Dv BIO_CLOSE 525or 526.Dv BIO_NOCLOSE . 527.Pp 528.Fn BIO_pending , 529.Fn BIO_ctrl_pending , 530.Fn BIO_wpending , 531and 532.Fn BIO_ctrl_wpending 533return the amount of pending data. 534.Pp 535.Fn BIO_get_info_callback 536returns 1 on success, including when the type of 537.Fa b 538supports an info callback but none is installed, 5390 if 540.Fa b 541is 542.Dv NULL 543or \-2 if the type of 544.Fa b 545does not support an info callback. 546.Pp 547If a callback was installed in 548.Fa b 549using 550.Xr BIO_set_callback_ex 3 551or 552.Xr BIO_set_callback 3 , 553it can modify the return values of all these functions. 554.Sh NOTES 555Because it can write data, 556.Fn BIO_flush 557may return 0 or -1 indicating that the call should be retried later 558in a similar manner to 559.Xr BIO_write 3 . 560The 561.Xr BIO_should_retry 3 562call should be used and appropriate action taken if the call fails. 563.Pp 564The return values of 565.Fn BIO_pending 566and 567.Fn BIO_wpending 568may not reliably determine the amount of pending data in all cases. 569For example in the case of a file BIO some data may be available in the 570.Vt FILE 571structure's internal buffers but it is not possible 572to determine this in a portable way. 573For other types of BIO they may not be supported. 574.Pp 575If they do not internally handle a particular 576.Fn BIO_ctrl 577operation, filter BIOs usually pass the operation 578to the next BIO in the chain. 579This often means there is no need to locate the required BIO for 580a particular operation: it can be called on a chain and it will 581be automatically passed to the relevant BIO. 582However, this can cause unexpected results. 583For example no current filter BIOs implement 584.Fn BIO_seek , 585but this may still succeed if the chain ends 586in a FILE or file descriptor BIO. 587.Pp 588Source/sink BIOs return a 0 if they do not recognize the 589.Fn BIO_ctrl 590operation. 591.Sh SEE ALSO 592.Xr BIO_meth_new 3 , 593.Xr BIO_new 3 594.Sh HISTORY 595.Fn BIO_ctrl , 596.Fn BIO_reset , 597.Fn BIO_flush , 598.Fn BIO_eof , 599.Fn BIO_set_close , 600.Fn BIO_get_close , 601and 602.Fn BIO_pending 603first appeared in SSLeay 0.6.0. 604.Fn BIO_wpending 605first appeared in SSLeay 0.8.1. 606.Fn BIO_ptr_ctrl , 607.Fn BIO_int_ctrl , 608.Fn BIO_get_info_callback 609and 610.Fn BIO_set_info_callback 611first appeared in SSLeay 0.9.0. 612All these functions have been available since 613.Ox 2.4 . 614.Pp 615.Fn BIO_seek 616and 617.Fn BIO_tell 618first appeared in SSLeay 0.9.1. 619.Fn BIO_ctrl_pending 620and 621.Fn BIO_ctrl_wpending 622first appeared in OpenSSL 0.9.4. 623These functions have been available since 624.Ox 2.6 . 625.Pp 626.Fn BIO_callback_ctrl 627first appeared in OpenSSL 0.9.5 and has been available since 628.Ox 2.7 . 629.Pp 630.Fn bio_info_cb 631first appeared with a more complicated prototype in OpenSSL 0.9.6 632and has been available since 633.Ox 2.9 . 634.Pp 635.Fn BIO_info_cb 636first appeared in OpenSSL 1.1.0h and has been available since 637.Ox 6.3 . 638.Sh BUGS 639Some of the return values are ambiguous and care should be taken. 640In particular a return value of 0 can be returned if an operation 641is not supported, if an error occurred, if EOF has not been reached 642and in the case of 643.Fn BIO_seek 644on a file BIO for a successful operation. 645