NAME
BIO_new, BIO_set,
BIO_free, BIO_vfree,
BIO_free_all —
construct and destruct I/O abstraction
objects
SYNOPSIS
#include
<openssl/bio.h>
BIO *
BIO_new(BIO_METHOD *type);
int
BIO_set(BIO *a,
BIO_METHOD *type);
int
BIO_free(BIO *a);
void
BIO_vfree(BIO *a);
void
BIO_free_all(BIO *a);
DESCRIPTION
A BIO is an I/O abstraction object, hiding many of the underlying I/O details from an application. If an application uses BIOs for its I/O, it can transparently handle SSL connections, unencrypted network connections, and file I/O.
The
BIO_new()
function constructs a new BIO using the method
type. There are two groups of BIO types, source/sink
BIOs and filter BIOs.
Source/sink BIOs provide input or consume output. Examples include socket BIOs and file BIOs.
Filter BIOs take data from one BIO and pass it through to another, or to the application, forming a chain of BIOs. The data may be left unmodified (for example by a message digest BIO) or translated (for example by an encryption BIO). The effect of a filter BIO may change according to the I/O operation it is performing: for example an encryption BIO will encrypt data if it is written to and decrypt data if it is read from.
Some BIOs (such as memory BIOs) can be used
immediately after calling
BIO_new().
Others (such as file BIOs) need some additional initialization, and utility
functions exists to construct and initialize such BIOs.
Normally the type argument is
supplied by a function which returns a pointer to a
BIO_METHOD. There is a naming convention for such
functions: the methods for source/sink BIOs are called
BIO_s_*()
and those for filter BIOs
BIO_f_*().
BIO_set()
sets the method of an already existing BIO.
BIO_free()
and
BIO_vfree()
destruct a single BIO, which may also have some effect on the underlying I/O
structure, for example it may close the file being referred to under certain
circumstances. If a is a NULL
pointer, no action occurs. If BIO_free() is called
on a BIO chain, it will only destruct one BIO, resulting in a memory
leak.
BIO_free_all()
destructs an entire BIO chain. It does not halt if an error occurs
destructing an individual BIO in the chain. If a is a
NULL pointer, no action occurs. Calling
BIO_free_all() on a single BIO has the same effect
as BIO_vfree().
Common I/O functions are documented in BIO_read(3). Forming chains is explained in BIO_push(3); inspecting them is explained in BIO_find_type(3). For more details about the different kinds of BIOs, see the individual BIO_METHOD manual pages.
RETURN VALUES
BIO_new() returns a newly constructed
BIO object or NULL on
failure.
BIO_set() and
BIO_free() return 1 for success or 0 for
failure.
EXAMPLES
Create a memory BIO:
BIO *mem =
BIO_new(BIO_s_mem());SEE ALSO
BIO_ctrl(3), BIO_f_base64(3), BIO_f_buffer(3), BIO_f_cipher(3), BIO_f_md(3), BIO_f_null(3), BIO_f_ssl(3), BIO_find_type(3), BIO_get_ex_new_index(3), BIO_printf(3), BIO_push(3), BIO_read(3), BIO_s_accept(3), BIO_s_bio(3), BIO_s_connect(3), BIO_s_fd(3), BIO_s_file(3), BIO_s_mem(3), BIO_s_null(3), BIO_s_socket(3), BIO_set_callback(3), BIO_should_retry(3)