1.Dd $Mdocdate: February 16 2015 $ 2.Dt BIO_S_MEM 3 3.Os 4.Sh NAME 5.Nm BIO_s_mem , 6.Nm BIO_set_mem_eof_return , 7.Nm BIO_get_mem_data , 8.Nm BIO_set_mem_buf , 9.Nm BIO_get_mem_ptr , 10.Nm BIO_new_mem_buf 11.Nd memory BIO 12.Sh SYNOPSIS 13.In openssl/bio.h 14.Ft BIO_METHOD * 15.Fo BIO_s_mem 16.Fa "void" 17.Fc 18.Ft long 19.Fo BIO_set_mem_eof_return 20.Fa "BIO *b" 21.Fa "int v" 22.Fc 23.Ft long 24.Fo BIO_get_mem_data 25.Fa "BIO *b" 26.Fa "char **pp" 27.Fc 28.Ft long 29.Fo BIO_set_mem_buf 30.Fa "BIO *b" 31.Fa "BUF_MEM *bm" 32.Fa "int c" 33.Fc 34.Ft long 35.Fo BIO_get_mem_ptr 36.Fa "BIO *b" 37.Fa "BUF_MEM **pp" 38.Fc 39.Ft BIO * 40.Fo BIO_new_mem_buf 41.Fa "void *buf" 42.Fa "int len" 43.Fc 44.Sh DESCRIPTION 45.Fn BIO_s_mem 46returns the memory BIO method function. 47.Pp 48A memory BIO is a source/sink BIO which uses memory for its I/O. 49Data written to a memory BIO is stored in a 50.Vt BUF_MEM 51structure which is extended as appropriate to accommodate the stored data. 52.Pp 53Any data written to a memory BIO can be recalled by reading from it. 54Unless the memory BIO is read only, 55any data read from it is deleted from the BIO. 56.Pp 57Memory BIOs support 58.Xr BIO_gets 3 59and 60.Xr BIO_puts 3 . 61.Pp 62If the 63.Dv BIO_CLOSE 64flag is set when a memory BIO is freed, the underlying 65.Dv BUF_MEM 66structure is also freed. 67.Pp 68Calling 69.Xr BIO_reset 3 70on a read/write memory BIO clears any data in it. 71On a read only BIO it restores the BIO to its original state 72and the read only data can be read again. 73.Pp 74.Xr BIO_eof 3 75is true if no data is in the BIO. 76.Pp 77.Xr BIO_ctrl_pending 3 78returns the number of bytes currently stored. 79.Pp 80.Xr BIO_set_mem_eof_return 3 81sets the behaviour of memory BIO 82.Fa b 83when it is empty. 84If 85.Fa v 86is zero, then an empty memory BIO will return EOF: 87It will return zero and 88.Fn BIO_should_retry 89will be false. 90If 91.Fa v 92is non-zero then it will return 93.Fa v 94when it is empty and it will set the read retry flag: 95.Fn BIO_read_retry 96is true. 97To avoid ambiguity with a normal positive return value 98.Fa v 99should be set to a negative value, typically -1. 100.Pp 101.Fn BIO_get_mem_data 102sets 103.Fa pp 104to a pointer to the start of the memory BIO's data 105and returns the total amount of data available. 106It is implemented as a macro. 107.Pp 108.Fn BIO_set_mem_buf 109sets the internal BUF_MEM structure to 110.Fa bm 111and sets the close flag to 112.Fa c , 113that is 114.Fa c 115should be either 116.Dv BIO_CLOSE 117or 118.Dv BIO_NOCLOSE . 119.Fn BIO_set_mem_buf 120is a macro. 121.Pp 122.Fn BIO_get_mem_ptr 123places the underlying 124.Vt BUF_MEM 125structure in 126.Fa pp . 127It is a macro. 128.Pp 129.Fn BIO_new_mem_buf 130creates a memory BIO using 131.Fa len 132bytes of data at 133.Fa buf . 134If 135.Fa len 136is -1, then 137.Fa buf 138is assumed to be NUL terminated and its length is determined by 139.Xr strlen 3 . 140The BIO is set to a read only state and as a result cannot be written to. 141This is useful when some data needs to be made available 142from a static area of memory in the form of a BIO. 143The supplied data is read directly from the supplied buffer: 144it is 145.Em not 146copied first, so the supplied area of memory must be unchanged 147until the BIO is freed. 148.Sh NOTES 149Writes to memory BIOs will always succeed if memory is available: 150their size can grow indefinitely. 151.Pp 152Every read from a read/write memory BIO will remove the data just read 153with an internal copy operation. 154If a BIO contains a lot of data and it is read in small chunks, 155the operation can be very slow. 156The use of a read only memory BIO avoids this problem. 157If the BIO must be read/write then adding a buffering BIO 158to the chain will speed up the process. 159.Sh EXAMPLES 160Create a memory BIO and write some data to it: 161.Bd -literal -offset indent 162BIO *mem = BIO_new(BIO_s_mem()); 163BIO_puts(mem, "Hello World\en"); 164.Ed 165.Pp 166Create a read only memory BIO: 167.Bd -literal -offset indent 168char data[] = "Hello World"; 169BIO *mem; 170mem = BIO_new_mem_buf(data, -1); 171.Ed 172.Pp 173Extract the 174.Vt BUF_MEM 175structure from a memory BIO and then free up the BIO: 176.Bd -literal -offset indent 177BUF_MEM *bptr; 178BIO_get_mem_ptr(mem, &bptr); 179/* Make sure BIO_free() leaves BUF_MEM alone. */ 180BIO_set_close(mem, BIO_NOCLOSE); 181BIO_free(mem); 182.Ed 183.Sh BUGS 184There should be an option to set the maximum size of a memory BIO. 185.Pp 186There should be a way to "rewind" a read/write BIO without destroying 187its contents. 188.Pp 189The copying operation should not occur after every small read 190of a large BIO to improve efficiency. 191