1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosBIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset, 6*4724848cSchristosBIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close, 7*4724848cSchristosBIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending, 8*4724848cSchristosBIO_get_info_callback, BIO_set_info_callback, BIO_info_cb 9*4724848cSchristos- BIO control operations 10*4724848cSchristos 11*4724848cSchristos=head1 SYNOPSIS 12*4724848cSchristos 13*4724848cSchristos #include <openssl/bio.h> 14*4724848cSchristos 15*4724848cSchristos typedef int BIO_info_cb(BIO *b, int state, int res); 16*4724848cSchristos 17*4724848cSchristos long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg); 18*4724848cSchristos long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb); 19*4724848cSchristos void *BIO_ptr_ctrl(BIO *bp, int cmd, long larg); 20*4724848cSchristos long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg); 21*4724848cSchristos 22*4724848cSchristos int BIO_reset(BIO *b); 23*4724848cSchristos int BIO_seek(BIO *b, int ofs); 24*4724848cSchristos int BIO_tell(BIO *b); 25*4724848cSchristos int BIO_flush(BIO *b); 26*4724848cSchristos int BIO_eof(BIO *b); 27*4724848cSchristos int BIO_set_close(BIO *b, long flag); 28*4724848cSchristos int BIO_get_close(BIO *b); 29*4724848cSchristos int BIO_pending(BIO *b); 30*4724848cSchristos int BIO_wpending(BIO *b); 31*4724848cSchristos size_t BIO_ctrl_pending(BIO *b); 32*4724848cSchristos size_t BIO_ctrl_wpending(BIO *b); 33*4724848cSchristos 34*4724848cSchristos int BIO_get_info_callback(BIO *b, BIO_info_cb **cbp); 35*4724848cSchristos int BIO_set_info_callback(BIO *b, BIO_info_cb *cb); 36*4724848cSchristos 37*4724848cSchristos=head1 DESCRIPTION 38*4724848cSchristos 39*4724848cSchristosBIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl() 40*4724848cSchristosare BIO "control" operations taking arguments of various types. 41*4724848cSchristosThese functions are not normally called directly, various macros 42*4724848cSchristosare used instead. The standard macros are described below, macros 43*4724848cSchristosspecific to a particular type of BIO are described in the specific 44*4724848cSchristosBIOs manual page as well as any special features of the standard 45*4724848cSchristoscalls. 46*4724848cSchristos 47*4724848cSchristosBIO_reset() typically resets a BIO to some initial state, in the case 48*4724848cSchristosof file related BIOs for example it rewinds the file pointer to the 49*4724848cSchristosstart of the file. 50*4724848cSchristos 51*4724848cSchristosBIO_seek() resets a file related BIO's (that is file descriptor and 52*4724848cSchristosFILE BIOs) file position pointer to B<ofs> bytes from start of file. 53*4724848cSchristos 54*4724848cSchristosBIO_tell() returns the current file position of a file related BIO. 55*4724848cSchristos 56*4724848cSchristosBIO_flush() normally writes out any internally buffered data, in some 57*4724848cSchristoscases it is used to signal EOF and that no more data will be written. 58*4724848cSchristos 59*4724848cSchristosBIO_eof() returns 1 if the BIO has read EOF, the precise meaning of 60*4724848cSchristos"EOF" varies according to the BIO type. 61*4724848cSchristos 62*4724848cSchristosBIO_set_close() sets the BIO B<b> close flag to B<flag>. B<flag> can 63*4724848cSchristostake the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is used 64*4724848cSchristosin a source/sink BIO to indicate that the underlying I/O stream should 65*4724848cSchristosbe closed when the BIO is freed. 66*4724848cSchristos 67*4724848cSchristosBIO_get_close() returns the BIOs close flag. 68*4724848cSchristos 69*4724848cSchristosBIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() 70*4724848cSchristosreturn the number of pending characters in the BIOs read and write buffers. 71*4724848cSchristosNot all BIOs support these calls. BIO_ctrl_pending() and BIO_ctrl_wpending() 72*4724848cSchristosreturn a size_t type and are functions, BIO_pending() and BIO_wpending() are 73*4724848cSchristosmacros which call BIO_ctrl(). 74*4724848cSchristos 75*4724848cSchristos=head1 RETURN VALUES 76*4724848cSchristos 77*4724848cSchristosBIO_reset() normally returns 1 for success and 0 or -1 for failure. File 78*4724848cSchristosBIOs are an exception, they return 0 for success and -1 for failure. 79*4724848cSchristos 80*4724848cSchristosBIO_seek() and BIO_tell() both return the current file position on success 81*4724848cSchristosand -1 for failure, except file BIOs which for BIO_seek() always return 0 82*4724848cSchristosfor success and -1 for failure. 83*4724848cSchristos 84*4724848cSchristosBIO_flush() returns 1 for success and 0 or -1 for failure. 85*4724848cSchristos 86*4724848cSchristosBIO_eof() returns 1 if EOF has been reached 0 otherwise. 87*4724848cSchristos 88*4724848cSchristosBIO_set_close() always returns 1. 89*4724848cSchristos 90*4724848cSchristosBIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. 91*4724848cSchristos 92*4724848cSchristosBIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() 93*4724848cSchristosreturn the amount of pending data. 94*4724848cSchristos 95*4724848cSchristos=head1 NOTES 96*4724848cSchristos 97*4724848cSchristosBIO_flush(), because it can write data may return 0 or -1 indicating 98*4724848cSchristosthat the call should be retried later in a similar manner to BIO_write_ex(). 99*4724848cSchristosThe BIO_should_retry() call should be used and appropriate action taken 100*4724848cSchristosis the call fails. 101*4724848cSchristos 102*4724848cSchristosThe return values of BIO_pending() and BIO_wpending() may not reliably 103*4724848cSchristosdetermine the amount of pending data in all cases. For example in the 104*4724848cSchristoscase of a file BIO some data may be available in the FILE structures 105*4724848cSchristosinternal buffers but it is not possible to determine this in a 106*4724848cSchristosportably way. For other types of BIO they may not be supported. 107*4724848cSchristos 108*4724848cSchristosFilter BIOs if they do not internally handle a particular BIO_ctrl() 109*4724848cSchristosoperation usually pass the operation to the next BIO in the chain. 110*4724848cSchristosThis often means there is no need to locate the required BIO for 111*4724848cSchristosa particular operation, it can be called on a chain and it will 112*4724848cSchristosbe automatically passed to the relevant BIO. However, this can cause 113*4724848cSchristosunexpected results: for example no current filter BIOs implement 114*4724848cSchristosBIO_seek(), but this may still succeed if the chain ends in a FILE 115*4724848cSchristosor file descriptor BIO. 116*4724848cSchristos 117*4724848cSchristosSource/sink BIOs return an 0 if they do not recognize the BIO_ctrl() 118*4724848cSchristosoperation. 119*4724848cSchristos 120*4724848cSchristos=head1 BUGS 121*4724848cSchristos 122*4724848cSchristosSome of the return values are ambiguous and care should be taken. In 123*4724848cSchristosparticular a return value of 0 can be returned if an operation is not 124*4724848cSchristossupported, if an error occurred, if EOF has not been reached and in 125*4724848cSchristosthe case of BIO_seek() on a file BIO for a successful operation. 126*4724848cSchristos 127*4724848cSchristos=head1 COPYRIGHT 128*4724848cSchristos 129*4724848cSchristosCopyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved. 130*4724848cSchristos 131*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 132*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 133*4724848cSchristosin the file LICENSE in the source distribution or at 134*4724848cSchristosL<https://www.openssl.org/source/license.html>. 135*4724848cSchristos 136*4724848cSchristos=cut 137