BIO_free

BIO_NEW(3)                BSD 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.

     The 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 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 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 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_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.

BSD                             November 2, 2019                             BSD