.Dd $Mdocdate: September 9 2015 $
.Dt BIO_NEW 3
.Os
.Sh NAME
.Nm BIO_new ,
.Nm BIO_set ,
.Nm BIO_free ,
.Nm BIO_vfree ,
.Nm BIO_free_all
.Nd BIO allocation and freeing functions
.Sh SYNOPSIS
.In openssl/bio.h
.Ft BIO *
.Fo BIO_new
.Fa "BIO_METHOD *type"
.Fc
.Ft int
.Fo BIO_set
.Fa "BIO *a"
.Fa "BIO_METHOD *type"
.Fc
.Ft int
.Fo BIO_free
.Fa "BIO *a"
.Fc
.Ft void
.Fo BIO_vfree
.Fa "BIO *a"
.Fc
.Ft void
.Fo BIO_free_all
.Fa "BIO *a"
.Fc
.Sh DESCRIPTION
The
.Fn BIO_new
function returns a new BIO using method
.Fa type .
.Pp
.Fn BIO_set
sets the method of an already existing BIO.
.Pp
.Fn BIO_free
frees up a single BIO,
.Fn BIO_vfree
also frees up a single BIO, but it does not return a value.
Calling
.Fn BIO_free
may also have some effect on the underlying I/O structure,
for example it may close the file being
referred to under certain circumstances.
For more details see the individual
.Vt BIO_METHOD
descriptions.
.Pp
.Fn BIO_free_all
frees up an entire BIO chain.
It does not halt if an error occurs
freeing up an individual BIO in the chain.
.Sh RETURN VALUES
.Fn BIO_new
returns a newly created BIO or
.Dv NULL
if the call fails.
.Pp
.Fn BIO_set
and
.Fn BIO_free
return 1 for success and 0 for failure.
.Pp
.Fn BIO_free_all
and
.Fn BIO_vfree
do not return values.
.Sh NOTES
Some BIOs (such as memory BIOs) can be used immediately after calling
.Fn BIO_new .
Others (such as file BIOs) need some additional initialization, and
frequently a utility function exists to create and initialize such BIOs.
.Pp
If
.Fn BIO_free
is called on a BIO chain, it will only free one BIO,
resulting in a memory leak.
.Pp
Calling
.Fn BIO_free_all
on a single BIO has the same effect as calling
.Fn BIO_free
on it other than the discarded return value.
.Pp
Normally the
.Fa type
argument is supplied by a function which returns a pointer to a
.Vt BIO_METHOD .
There is a naming convention for such functions:
a source/sink BIO is normally called
.Fn BIO_s_*
and a filter BIO
.Fn BIO_f_* .
.Sh EXAMPLES
Create a memory BIO:
.Pp
.Dl BIO *mem = BIO_new(BIO_s_mem());