--- name: "libressl-BIO_new" section: "3" platform: "linux" package: "libressl" version: "4.4.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/libressl-BIO_new" --- # libressl-BIO\_new(3) construct and destruct I/O abstraction objects ## NAME **BIO\_new**, **BIO\_up\_ref**, **BIO\_set**, **BIO\_free**, **BIO\_vfree**, **BIO\_free\_all** – construct and destruct I/O abstraction objects ## SYNOPSIS Crypto Library (libcrypto, -lcrypto) **#include \** *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 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\_accept(3), BIO\_ctrl(3), BIO\_dump(3), BIO\_dup\_chain(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\_datagram(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)](/crypto/3.md) ## 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.