BIO_ctrl(3)BIO_ctrl(3)NAME
BIO_ctrl, BIO_callback_ctrl, BIO_ctrl_wpending, BIO_wpending, BIO_eof,
BIO_flush, BIO_get_close, BIO_get_info_callback, BIO_set_info_callback,
BIO_int_ctrl, BIO_pending, BIO_ptr_ctrl, BIO_reset, BIO_seek,
BIO_set_close, BIO_tell - BIO control operations
SYNOPSIS
#include <openssl/bio.h>
long BIO_ctrl(
BIO *bp,
int cmd,
long larg,
void *parg ); long BIO_callback_ctrl(
BIO *b,
int cmd,
void (*fp)(struct bio_st *,
int,
const char *,
int,
long,
long) ); char * BIO_ptr_ctrl(
BIO *bp,
int cmd,
long larg ); long BIO_int_ctrl(
BIO *bp,
int cmd,
long larg,
int iarg ); int BIO_reset(
BIO *b ); int BIO_seek(
BIO *b,
int ofs ); int BIO_tell(
BIO *b ); int BIO_flush(
BIO *b ); int BIO_eof(
BIO *b ); int BIO_set_close(
BIO *b,
long flag ); int BIO_get_close(
BIO *b ); int BIO_pending(
BIO *b ); int BIO_wpending(
BIO *b ); size_t BIO_ctrl_pending(
BIO *b ); size_t BIO_ctrl_wpending(
BIO *b ); int BIO_get_info_callback(
BIO *b,
bio_info_cb **cbp ); int BIO_set_info_callback(
BIO *b,
bio_info_cb *cb ); typedef void bio_info_cb(
BIO *b,
int oper,
const char *ptr,
int arg1,
long arg2,
long arg3 );
DESCRIPTION
The BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl(), and BIO_int_ctrl()
functions are BIO control operations taking arguments of various types.
These functions are not usually called directly; various macros are
used instead. The standard macros are described below. Macros specific
to a particular type of BIO are described in the specific BIO's refer‐
ence page, as well as any special features of the standard calls.
The BIO_reset()function typically resets a BIO to some initial state.
In the case of file related BIOs, for example, it rewinds the file
pointer to the start of the file.
The BIO_seek() function resets a file related BIO's (its file descrip‐
tor and FILE BIOs) file position pointer to ofs bytes from start of
file.
The BIO_tell() function returns the current file position of a file
related BIO.
The BIO_flush() function normally writes out any internally buffered
data, in some cases it is used to signal EOF and that no more data will
be written.
The BIO_eof() function returns 1 if the BIO has read EOF, the precise
meaning of EOF varies according to the BIO type.
The BIO_set_close() function sets the BIO b close flag to flag. flag
can take the value BIO_CLOSE or BIO_NOCLOSE. Typically BIO_CLOSE is
used in a source/sink BIO to indicate that the underlying I/O stream
should be closed when the BIO is freed.
The BIO_get_close() function returns the BIO's close flag.
The BIO_pending(), BIO_ctrl_pending(), BIO_wpending(), and
BIO_ctrl_wpending() functions return the number of pending characters
in the BIO's read and write buffers. Not all BIOs support these calls.
The BIO_ctrl_pending() and BIO_ctrl_wpending() functions return a
size_t type and are functions. BIO_pending() and BIO_wpending() are
macros which call BIO_ctrl().
NOTES
The BIO_flush() function, because it can write data, might return 0 or
-1 indicating that the call should be retried later in a similar manner
to BIO_write(). The BIO_should_retry() function should be used and
appropriate action taken if the call fails.
The return values of the BIO_pending() and BIO_wpending() functions
might not reliably determine the amount of pending data in all cases.
For example, in the case of a file BIO some data may be available in
the FILE structure's internal buffers but it is not possible to deter‐
mine this in a portably way. For other types of BIO they might not be
supported.
Filter BIOs, if they do not internally handle a particular BIO_ctrl()
operation, usually pass the operation to the next BIO in the chain.
This often means there is no need to locate the required BIO for a par‐
ticular operation. It can be called on a chain and it will be automati‐
cally passed to the relevant BIO. However, this can cause unexpected
results. For example, no current filter BIOs implement BIO_seek(), but
this might still succeed if the chain ends in a FILE or file descriptor
BIO.
Source/sink BIOs return a 0 if they do not recognize the BIO_ctrl()
operation.
RESTRICTIONS
Some of the return values are ambiguous and care should be taken. In
particular a return value of 0 can be returned if an operation is not
supported, if an error occurred, if EOF has not been reached, and - in
the case of BIO_seek() - on a file BIO for a successful operation.
RETURN VALUESBIO_reset() normally returns 1 for success and 0 or -1 for failure.
File BIOs are an exception, they return 0 for success and -1 for fail‐
ure.
BIO_seek() and BIO_tell() both return the current file position on suc‐
cess and -1 for failure, except file BIOs which for BIO_seek() always
return 0 for success and -1 for failure.
BIO_flush() returns 1 for success and 0 or -1 for failure.
BIO_eof() returns 1 if EOF has been reached 0 otherwise.
BIO_set_close() always returns 1.
BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
The BIO_pending(), BIO_ctrl_pending(), BIO_wpending(), and
BIO_ctrl_wpending() functions return the amount of pending data.
SEE ALSO
TBA
BIO_ctrl(3)