|BIO_NEW(3)||Library Functions Manual||BIO_NEW(3)|
const BIO_METHOD *type);
BIO_new() function constructs a new
BIO using the method type and
sets its reference count to 1. 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 encrypts data if it is written to and decrypts data if it is read from.
Some BIOs (such as memory BIOs) can be used immediately after
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_up_ref() increments the reference
count of a by 1.
BIO_set() is a deprecated function to
initialize an unused BIO structure located in static
memory or on the stack, to set its method to type, and
to set its reference count to 1. It must not be called on
BIO objects created with
BIO_new(), nor on objects that were already
BIO_vfree() decrement the reference count of
a by 1, and if the refenece count reaches 0, they
destruct the single BIO a, 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
BIO_free() is called on a BIO chain, it
destructs at most one BIO, resulting in a memory leak.
BIO_free() on a and on all
following BIO objects in the chain. As soon as the
reference count of a BIO is still non-zero after
BIO_free() on it, the function
BIO_free_all() returns right away and refrains from
freeing the remaining BIO objects in the 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
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.
BIO_new() returns a newly constructed BIO object or
return 1 for success or 0 for failure.
BIO *mem = BIO_new(BIO_s_mem());
BIO_free() first appeared in SSLeay 0.6.0.
BIO_free_all() first appeared in SSLeay 0.6.6. All these functions have been available since OpenBSD 2.4.
BIO_vfree() first appeared in OpenSSL
0.9.6 and has been available since OpenBSD 2.9.
BIO_up_ref() first appeared in OpenSSL
1.1.0 and has been available since OpenBSD 6.3.
|June 10, 2019||OpenBSD-current|