113d40330Schristos=pod 213d40330Schristos 313d40330Schristos=head1 NAME 413d40330Schristos 513d40330SchristosBIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, 613d40330SchristosBIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, 713d40330SchristosBIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, 8*b0d17251SchristosBIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send, 9*b0d17251SchristosBIO_get_ktls_recv 1013d40330Schristos- BIO control operations 1113d40330Schristos 1213d40330Schristos=head1 SYNOPSIS 1313d40330Schristos 1413d40330Schristos #include <openssl/bio.h> 1513d40330Schristos 1613d40330Schristos typedef int BIO_info_cb(BIO *b, int state, int res); 1713d40330Schristos 1813d40330Schristos long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg); 1913d40330Schristos long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb); 20d3425df3Schristos void *BIO_ptr_ctrl(BIO *bp, int cmd, long larg); 2113d40330Schristos long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg); 2213d40330Schristos 2313d40330Schristos int BIO_reset(BIO *b); 2413d40330Schristos int BIO_seek(BIO *b, int ofs); 2513d40330Schristos int BIO_tell(BIO *b); 2613d40330Schristos int BIO_flush(BIO *b); 2713d40330Schristos int BIO_eof(BIO *b); 2813d40330Schristos int BIO_set_close(BIO *b, long flag); 2913d40330Schristos int BIO_get_close(BIO *b); 3013d40330Schristos int BIO_pending(BIO *b); 3113d40330Schristos int BIO_wpending(BIO *b); 3213d40330Schristos size_t BIO_ctrl_pending(BIO *b); 3313d40330Schristos size_t BIO_ctrl_wpending(BIO *b); 3413d40330Schristos 3513d40330Schristos int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp); 3613d40330Schristos int BIO_set_info_callback(BIO *b, BIO_info_cb *cb); 3713d40330Schristos 38*b0d17251Schristos int BIO_get_ktls_send(BIO *b); 39*b0d17251Schristos int BIO_get_ktls_recv(BIO *b); 40*b0d17251Schristos 4113d40330Schristos=head1 DESCRIPTION 4213d40330Schristos 4313d40330SchristosBIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() 4413d40330Schristosare BIO "control" operations taking arguments of various types. 4513d40330SchristosThese functions are not normally called directly, various macros 4613d40330Schristosare used instead. The standard macros are described below, macros 4713d40330Schristosspecific to a particular type of BIO are described in the specific 4813d40330SchristosBIOs manual page as well as any special features of the standard 4913d40330Schristoscalls. 5013d40330Schristos 5113d40330SchristosBIO_reset() typically resets a BIO to some initial state, in the case 5213d40330Schristosof file related BIOs for example it rewinds the file pointer to the 5313d40330Schristosstart of the file. 5413d40330Schristos 5513d40330SchristosBIO_seek() resets a file related BIO's (that is file descriptor and 5613d40330SchristosFILE BIOs) file position pointer to B<ofs> bytes from start of file. 5713d40330Schristos 5813d40330SchristosBIO_tell() returns the current file position of a file related BIO. 5913d40330Schristos 6013d40330SchristosBIO_flush() normally writes out any internally buffered data, in some 6113d40330Schristoscases it is used to signal EOF and that no more data will be written. 6213d40330Schristos 6313d40330SchristosBIO_eof() returns 1 if the BIO has read EOF, the precise meaning of 6413d40330Schristos"EOF" varies according to the BIO type. 6513d40330Schristos 6613d40330SchristosBIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can 6713d40330Schristostake the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used 6813d40330Schristosin a source/sink BIO to indicate that the underlying I/O stream should 6913d40330Schristosbe closed when the BIO is freed. 7013d40330Schristos 7113d40330SchristosBIO_get_close() returns the BIOs close flag. 7213d40330Schristos 7313d40330SchristosBIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() 7413d40330Schristosreturn the number of pending characters in the BIOs read and write buffers. 7513d40330SchristosNot all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() 7613d40330Schristosreturn a size_t type and are functions, BIO_pending() and BIO_wpending() are 7713d40330Schristosmacros which call BIO_ctrl(). 7813d40330Schristos 79*b0d17251SchristosBIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for 80*b0d17251Schristossending. Otherwise, it returns zero. 81*b0d17251SchristosBIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for 82*b0d17251Schristosreceiving. Otherwise, it returns zero. 83*b0d17251Schristos 8413d40330Schristos=head1 RETURN VALUES 8513d40330Schristos 86*b0d17251SchristosBIO_reset() normally returns 1 for success and <=0 for failure. File 8713d40330SchristosBIOs are an exception, they return 0 for success and -1 for failure. 8813d40330Schristos 8913d40330SchristosBIO_seek() and BIO_tell() both return the current file position on success 9013d40330Schristosand -1 for failure, except file BIOs which for BIO_seek() always return 0 9113d40330Schristosfor success and -1 for failure. 9213d40330Schristos 93*b0d17251SchristosBIO_flush() returns 1 for success and <=0 for failure. 9413d40330Schristos 95*b0d17251SchristosBIO_eof() returns 1 if EOF has been reached, 0 if not, or negative values for failure. 9613d40330Schristos 97*b0d17251SchristosBIO_set_close() returns 1 on success or <=0 for failure. 9813d40330Schristos 99*b0d17251SchristosBIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. It also 100*b0d17251Schristosreturns other negative values if an error occurs. 10113d40330Schristos 10213d40330SchristosBIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() 103*b0d17251Schristosreturn the amount of pending data. BIO_pending() and BIO_wpending() return 104*b0d17251Schristosnegative value or 0 on error. BIO_ctrl_pending() and BIO_ctrl_wpending() return 105*b0d17251Schristos0 on error. 106*b0d17251Schristos 107*b0d17251SchristosBIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for 108*b0d17251Schristossending. Otherwise, it returns zero. 109*b0d17251SchristosBIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for 110*b0d17251Schristosreceiving. Otherwise, it returns zero. 11113d40330Schristos 11213d40330Schristos=head1 NOTES 11313d40330Schristos 11413d40330SchristosBIO_flush(), because it can write data may return 0 or -1 indicating 11513d40330Schristosthat the call should be retried later in a similar manner to BIO_write_ex(). 11613d40330SchristosThe BIO_should_retry() call should be used and appropriate action taken 11713d40330Schristosis the call fails. 11813d40330Schristos 11913d40330SchristosThe return values of BIO_pending() and BIO_wpending() may not reliably 12013d40330Schristosdetermine the amount of pending data in all cases. For example in the 12113d40330Schristoscase of a file BIO some data may be available in the FILE structures 12213d40330Schristosinternal buffers but it is not possible to determine this in a 12313d40330Schristosportably way. For other types of BIO they may not be supported. 12413d40330Schristos 12513d40330SchristosFilter BIOs if they do not internally handle a particular BIO_ctrl() 12613d40330Schristosoperation usually pass the operation to the next BIO in the chain. 12713d40330SchristosThis often means there is no need to locate the required BIO for 12813d40330Schristosa particular operation, it can be called on a chain and it will 129f30e0929Schristosbe automatically passed to the relevant BIO. However, this can cause 13013d40330Schristosunexpected results: for example no current filter BIOs implement 13113d40330SchristosBIO_seek(), but this may still succeed if the chain ends in a FILE 13213d40330Schristosor file descriptor BIO. 13313d40330Schristos 13413d40330SchristosSource/sink BIOs return an 0 if they do not recognize the BIO_ctrl() 13513d40330Schristosoperation. 13613d40330Schristos 13713d40330Schristos=head1 BUGS 13813d40330Schristos 13913d40330SchristosSome of the return values are ambiguous and care should be taken. In 14013d40330Schristosparticular a return value of 0 can be returned if an operation is not 14113d40330Schristossupported, if an error occurred, if EOF has not been reached and in 14213d40330Schristosthe case of BIO_seek() on a file BIO for a successful operation. 14313d40330Schristos 144*b0d17251SchristosIn older versions of OpenSSL the BIO_ctrl_pending() and 145*b0d17251SchristosBIO_ctrl_wpending() could return values greater than INT_MAX on error. 146*b0d17251Schristos 147*b0d17251Schristos=head1 HISTORY 148*b0d17251Schristos 149*b0d17251SchristosThe BIO_get_ktls_send() and BIO_get_ktls_recv() macros were added in 150*b0d17251SchristosOpenSSL 3.0. They were modified to never return -1 in OpenSSL 3.0.4. 151*b0d17251Schristos 15213d40330Schristos=head1 COPYRIGHT 15313d40330Schristos 154d3425df3SchristosCopyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. 15513d40330Schristos 156*b0d17251SchristosLicensed under the Apache License 2.0 (the "License"). You may not use 15713d40330Schristosthis file except in compliance with the License. You can obtain a copy 15813d40330Schristosin the file LICENSE in the source distribution or at 15913d40330SchristosL<https://www.openssl.org/source/license.html>. 16013d40330Schristos 16113d40330Schristos=cut 162