1.Dd $Mdocdate: September 9 2015 $ 2.Dt BIO_NEW 3 3.Os 4.Sh NAME 5.Nm BIO_new , 6.Nm BIO_set , 7.Nm BIO_free , 8.Nm BIO_vfree , 9.Nm BIO_free_all 10.Nd BIO allocation and freeing functions 11.Sh SYNOPSIS 12.In openssl/bio.h 13.Ft BIO * 14.Fo BIO_new 15.Fa "BIO_METHOD *type" 16.Fc 17.Ft int 18.Fo BIO_set 19.Fa "BIO *a" 20.Fa "BIO_METHOD *type" 21.Fc 22.Ft int 23.Fo BIO_free 24.Fa "BIO *a" 25.Fc 26.Ft void 27.Fo BIO_vfree 28.Fa "BIO *a" 29.Fc 30.Ft void 31.Fo BIO_free_all 32.Fa "BIO *a" 33.Fc 34.Sh DESCRIPTION 35The 36.Fn BIO_new 37function returns a new BIO using method 38.Fa type . 39.Pp 40.Fn BIO_set 41sets the method of an already existing BIO. 42.Pp 43.Fn BIO_free 44frees up a single BIO, 45.Fn BIO_vfree 46also frees up a single BIO, but it does not return a value. 47Calling 48.Fn BIO_free 49may also have some effect on the underlying I/O structure, 50for example it may close the file being 51referred to under certain circumstances. 52For more details see the individual 53.Vt BIO_METHOD 54descriptions. 55.Pp 56.Fn BIO_free_all 57frees up an entire BIO chain. 58It does not halt if an error occurs 59freeing up an individual BIO in the chain. 60.Sh RETURN VALUES 61.Fn BIO_new 62returns a newly created BIO or 63.Dv NULL 64if the call fails. 65.Pp 66.Fn BIO_set 67and 68.Fn BIO_free 69return 1 for success and 0 for failure. 70.Pp 71.Fn BIO_free_all 72and 73.Fn BIO_vfree 74do not return values. 75.Sh NOTES 76Some BIOs (such as memory BIOs) can be used immediately after calling 77.Fn BIO_new . 78Others (such as file BIOs) need some additional initialization, and 79frequently a utility function exists to create and initialize such BIOs. 80.Pp 81If 82.Fn BIO_free 83is called on a BIO chain, it will only free one BIO, 84resulting in a memory leak. 85.Pp 86Calling 87.Fn BIO_free_all 88on a single BIO has the same effect as calling 89.Fn BIO_free 90on it other than the discarded return value. 91.Pp 92Normally the 93.Fa type 94argument is supplied by a function which returns a pointer to a 95.Vt BIO_METHOD . 96There is a naming convention for such functions: 97a source/sink BIO is normally called 98.Fn BIO_s_* 99and a filter BIO 100.Fn BIO_f_* . 101.Sh EXAMPLES 102Create a memory BIO: 103.Pp 104.Dl BIO *mem = BIO_new(BIO_s_mem()); 105