Sortix 1.1dev nightly manual
This manual documents Sortix 1.1dev nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.
BIO_NEW(3) | Library Functions Manual | BIO_NEW(3) |
NAME
BIO_new
,
BIO_up_ref
,
BIO_set
,
BIO_free
,
BIO_vfree
,
BIO_free_all
—
construct and destruct I/O abstraction objects
SYNOPSIS
#include
<openssl/bio.h>
BIO *
BIO_new
(const
BIO_METHOD *type);
int
BIO_up_ref
(BIO
*a);
int
BIO_set
(BIO
*a, const 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. TheBIO_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 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_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 used.
BIO_free
() and
BIO_vfree
() decrement the reference count
of a by 1, and if the reference 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 occurs. If
BIO_free
() is called on a BIO chain, it
destructs at most one BIO, resulting in a memory leak.
BIO_free_all
() calls
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 calling 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 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_up_ref
(),
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_dump(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_meth_new(3), BIO_new_CMS(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_set_data(3), BIO_should_retry(3), BUF_MEM_new(3), crypto(3)HISTORY
BIO_new
(),
BIO_set
(), and
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.July 10, 2021 | Debian |