#use wml::openssl-macros area=docs page=BIO_new

<title>Documents, BIO_new(3)</title>

<h1>BIO_new(3)</h1>

#use wml::imp::generic

{:
## What's this? [[s|(<STRONG>[^<].+?)</A>(</STRONG><DD>)|$1$2|sg]]
[[s|<P>\s+<P>|<P>|sg]]
[[s|<P>\s+</|</|sg]]
[[s|<DD>\s*<DT>|<DD>&nbsp;<DT>|sg]]
[[s|<DD>\s*</DL>|<DD>&nbsp;</DL>|sg]]
[[s|\[|&#91;|sg]]
[[s|\]|&#93;|sg]]

<!-- INDEX BEGIN -->

<UL>

	<LI><A HREF="#NAME">NAME</A>
	<LI><A HREF="#SYNOPSIS">SYNOPSIS</A>
	<LI><A HREF="#DESCRIPTION">DESCRIPTION</A>
	<LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
	<LI><A HREF="#NOTES">NOTES</A>
	<LI><A HREF="#EXAMPLE">EXAMPLE</A>
	<LI><A HREF="#SEE_ALSO">SEE ALSO</A>
</UL>
<!-- INDEX END -->

<HR>
<P>
<HR>
<H1><A NAME="NAME">NAME</A></H1>
<P>
BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and
freeing functions

</P>
<P>
<HR>
<H1><A NAME="SYNOPSIS">SYNOPSIS</A></H1>
<PRE> #include &lt;openssl/bio.h&gt;
</PRE>
<PRE> 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);
</PRE>
<P>
<HR>
<H1><A NAME="DESCRIPTION">DESCRIPTION</A></H1>
<P>
The <CODE>BIO_new()</CODE> function returns a new BIO using method <STRONG>type</STRONG>.

</P>
<P>
<CODE>BIO_set()</CODE> sets the method of an already existing BIO.

</P>
<P>
<CODE>BIO_free()</CODE> frees up a single BIO, <CODE>BIO_vfree()</CODE>
also frees up a single BIO but it does not return a value. Calling
<CODE>BIO_free()</CODE> 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 BIO_METHOD
descriptions.

</P>
<P>
<CODE>BIO_free_all()</CODE> frees up an entire BIO chain, it does not halt
if an error occurs freeing up an individual BIO in the chain.

</P>
<P>
<HR>
<H1><A NAME="RETURN_VALUES">RETURN VALUES</A></H1>
<P>
<CODE>BIO_new()</CODE> returns a newly created BIO or NULL if the call
fails.

</P>
<P>
<CODE>BIO_set(),</CODE> <CODE>BIO_free()</CODE> return 1 for success and 0
for failure.

</P>
<P>
<CODE>BIO_free_all()</CODE> and <CODE>BIO_vfree()</CODE> do not return
values.

</P>
<P>
<HR>
<H1><A NAME="NOTES">NOTES</A></H1>
<P>
Some BIOs (such as memory BIOs) can be used immediately after calling
<CODE>BIO_new().</CODE> Others (such as file BIOs) need some additional
initialization, and frequently a utility function exists to create and
initialize such BIOs.

</P>
<P>
If <CODE>BIO_free()</CODE> is called on a BIO chain it will only free one
BIO resulting in a memory leak.

</P>
<P>
Calling <CODE>BIO_free_all()</CODE> a single BIO has the same effect as
calling <CODE>BIO_free()</CODE> on it other than the discarded return
value.

</P>
<P>
Normally the <STRONG>type</STRONG> argument is supplied by a function which returns a pointer to a BIO_METHOD.
There is a naming convention for such functions: a source/sink BIO is
normally called BIO_s_*() and a filter BIO BIO_f_*();

</P>
<P>
<HR>
<H1><A NAME="EXAMPLE">EXAMPLE</A></H1>
<P>
Create a memory BIO:

</P>
<PRE> BIO *mem = BIO_new(BIO_s_mem());
</PRE>
<P>
<HR>
<H1><A NAME="SEE_ALSO">SEE ALSO</A></H1>
<P>
TBA
</P>
:}