1.\" $OpenBSD: BIO_s_mem.3,v 1.19 2023/11/16 20:19:23 schwarze Exp $ 2.\" full merge up to: OpenSSL 8711efb4 Mon Apr 20 11:33:12 2009 +0000 3.\" selective merge up to: OpenSSL 36359cec Mar 7 14:37:23 2018 +0100 4.\" 5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 6.\" Copyright (c) 2000 The OpenSSL Project. All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in 17.\" the documentation and/or other materials provided with the 18.\" distribution. 19.\" 20.\" 3. All advertising materials mentioning features or use of this 21.\" software must display the following acknowledgment: 22.\" "This product includes software developed by the OpenSSL Project 23.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 24.\" 25.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 26.\" endorse or promote products derived from this software without 27.\" prior written permission. For written permission, please contact 28.\" openssl-core@openssl.org. 29.\" 30.\" 5. Products derived from this software may not be called "OpenSSL" 31.\" nor may "OpenSSL" appear in their names without prior written 32.\" permission of the OpenSSL Project. 33.\" 34.\" 6. Redistributions of any form whatsoever must retain the following 35.\" acknowledgment: 36.\" "This product includes software developed by the OpenSSL Project 37.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 38.\" 39.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 40.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 41.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 42.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 43.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 44.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 45.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 46.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 47.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 48.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 49.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 50.\" OF THE POSSIBILITY OF SUCH DAMAGE. 51.\" 52.Dd $Mdocdate: November 16 2023 $ 53.Dt BIO_S_MEM 3 54.Os 55.Sh NAME 56.Nm BIO_s_mem , 57.Nm BIO_set_mem_eof_return , 58.Nm BIO_get_mem_data , 59.Nm BIO_set_mem_buf , 60.Nm BIO_get_mem_ptr , 61.Nm BIO_new_mem_buf 62.Nd memory BIO 63.Sh SYNOPSIS 64.In openssl/bio.h 65.Ft const BIO_METHOD * 66.Fo BIO_s_mem 67.Fa "void" 68.Fc 69.Ft long 70.Fo BIO_set_mem_eof_return 71.Fa "BIO *b" 72.Fa "int v" 73.Fc 74.Ft long 75.Fo BIO_get_mem_data 76.Fa "BIO *b" 77.Fa "char **pp" 78.Fc 79.Ft long 80.Fo BIO_set_mem_buf 81.Fa "BIO *b" 82.Fa "BUF_MEM *bm" 83.Fa "int c" 84.Fc 85.Ft long 86.Fo BIO_get_mem_ptr 87.Fa "BIO *b" 88.Fa "BUF_MEM **pp" 89.Fc 90.Ft BIO * 91.Fo BIO_new_mem_buf 92.Fa "const void *buf" 93.Fa "int len" 94.Fc 95.Sh DESCRIPTION 96.Fn BIO_s_mem 97returns the memory BIO method function. 98.Pp 99A memory BIO is a source/sink BIO which uses memory for its I/O. 100Data written to a memory BIO is stored in a 101.Vt BUF_MEM 102structure which is extended as appropriate to accommodate the stored data. 103.Pp 104Any data written to a memory BIO can be recalled by reading from it. 105Unless the memory BIO is read only, 106any data read from it is deleted from the BIO. 107To find out whether a memory BIO is read only, 108.Xr BIO_test_flags 3 109can be called with an argument of 110.Dv BIO_FLAGS_MEM_RDONLY . 111.Pp 112Memory BIOs support 113.Xr BIO_gets 3 114and 115.Xr BIO_puts 3 . 116.Pp 117If the 118.Dv BIO_CLOSE 119flag is set when a memory BIO is freed, the underlying 120.Dv BUF_MEM 121structure is also freed. 122.Pp 123Calling 124.Xr BIO_reset 3 125on a read/write memory BIO clears any data in it. 126On a read only BIO it restores the BIO to its original state 127and the read only data can be read again. 128.Pp 129.Xr BIO_eof 3 130is true if no data is in the BIO. 131.Pp 132.Xr BIO_ctrl_pending 3 133returns the number of bytes currently stored. 134.Pp 135.Fn BIO_set_mem_eof_return 136sets the behaviour of memory BIO 137.Fa b 138when it is empty. 139If 140.Fa v 141is zero, then an empty memory BIO will return EOF: 142it will return zero and 143.Fn BIO_should_retry 144will be false. 145If 146.Fa v 147is non-zero then it will return 148.Fa v 149when it is empty and it will set the read retry flag: 150.Fn BIO_read_retry 151is true. 152To avoid ambiguity with a normal positive return value 153.Fa v 154should be set to a negative value, typically -1. 155.Pp 156.Fn BIO_get_mem_data 157sets 158.Pf * Fa pp 159to a pointer to the start of the memory BIO's data 160and returns the total amount of data available. 161.Pp 162.Fn BIO_set_mem_buf 163sets the internal BUF_MEM structure to 164.Fa bm 165and sets the close flag to 166.Fa c . 167That is, 168.Fa c 169should be either 170.Dv BIO_CLOSE 171or 172.Dv BIO_NOCLOSE . 173.Pp 174.Fn BIO_get_mem_ptr 175places the underlying 176.Vt BUF_MEM 177structure in 178.Pf * Fa pp . 179.Pp 180.Fn BIO_new_mem_buf 181creates a memory BIO using 182.Fa len 183bytes of data at 184.Fa buf . 185If 186.Fa len 187is -1, then 188.Fa buf 189is assumed to be NUL terminated and its length is determined by 190.Xr strlen 3 . 191The BIO is set to a read only state and as a result cannot be written to. 192This is useful when some data needs to be made available 193from a static area of memory in the form of a BIO. 194The supplied data is read directly from the supplied buffer: 195it is 196.Em not 197copied first, so the supplied area of memory must be unchanged 198until the BIO is freed. 199.Pp 200Writes to memory BIOs will always succeed if memory is available: 201their size can grow indefinitely. 202.Pp 203.Xr BIO_ctrl 3 204.Fa cmd 205arguments correspond to macros as follows: 206.Bl -column BIO_C_SET_BUF_MEM_EOF_RETURN BIO_set_mem_eof_return() -offset 3n 207.It Fa cmd No constant Ta corresponding macro 208.It Dv BIO_C_GET_BUF_MEM_PTR Ta Fn BIO_get_mem_ptr 209.It Dv BIO_C_SET_BUF_MEM Ta Fn BIO_set_mem_buf 210.It Dv BIO_C_SET_BUF_MEM_EOF_RETURN Ta Fn BIO_set_mem_eof_return 211.It Dv BIO_CTRL_EOF Ta Xr BIO_eof 3 212.It Dv BIO_CTRL_GET_CLOSE Ta Xr BIO_get_close 3 213.It Dv BIO_CTRL_INFO Ta Fn BIO_get_mem_data 214.It Dv BIO_CTRL_PENDING Ta Xr BIO_pending 3 215.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3 216.It Dv BIO_CTRL_SET_CLOSE Ta Xr BIO_set_close 3 217.It Dv BIO_CTRL_WPENDING Ta Xr BIO_wpending 3 218.El 219.Sh RETURN VALUES 220.Fn BIO_s_mem 221returns a pointer to a static object. 222.Pp 223When called on a memory BIO object, 224.Xr BIO_method_type 3 225returns the constant 226.Dv BIO_TYPE_MEM 227and 228.Xr BIO_method_name 3 229returns a pointer to the static string 230.Qq memory buffer . 231.Pp 232.Fn BIO_set_mem_eof_return , 233.Fn BIO_get_mem_data , 234.Fn BIO_set_mem_buf , 235and 236.Fn BIO_get_mem_ptr 237return 1 on success or a value less than or equal to 0 if an error occurred. 238.Pp 239.Fn BIO_new_mem_buf 240returns a newly allocated 241.Vt BIO 242object on success or 243.Dv NULL 244on error. 245.Sh EXAMPLES 246Create a memory BIO and write some data to it: 247.Bd -literal -offset indent 248BIO *mem = BIO_new(BIO_s_mem()); 249BIO_puts(mem, "Hello World\en"); 250.Ed 251.Pp 252Create a read only memory BIO: 253.Bd -literal -offset indent 254char data[] = "Hello World"; 255BIO *mem; 256mem = BIO_new_mem_buf(data, -1); 257.Ed 258.Pp 259Extract the 260.Vt BUF_MEM 261structure from a memory BIO and then free up the BIO: 262.Bd -literal -offset indent 263BUF_MEM *bptr; 264BIO_get_mem_ptr(mem, &bptr); 265/* Make sure BIO_free() leaves BUF_MEM alone. */ 266BIO_set_close(mem, BIO_NOCLOSE); 267BIO_free(mem); 268.Ed 269.Sh SEE ALSO 270.Xr BIO_new 3 , 271.Xr BUF_MEM_new 3 272.Sh HISTORY 273.Fn BIO_s_mem 274first appeared in SSLeay 0.6.0. 275.Fn BIO_set_mem_buf 276and 277.Fn BIO_get_mem_ptr 278first appeared in SSLeay 0.6.5. 279These functions have been available since 280.Ox 2.4 . 281.Pp 282.Fn BIO_set_mem_eof_return 283and 284.Fn BIO_get_mem_data 285first appeared in SSLeay 0.9.1 and have been available since 286.Ox 2.6 . 287.Pp 288.Fn BIO_new_mem_buf 289first appeared in OpenSSL 0.9.5 and has been available since 290.Ox 2.7 . 291.Sh CAVEATS 292Do not manually switch a writable memory BIO to read-only mode: calling 293.Xr BIO_set_flags 3 294with an argument of 295.Dv BIO_FLAGS_MEM_RDONLY 296will ultimately result in a memory leak when the BIO object is 297finally handed to 298.Xr BIO_free 3 . 299It might also cause security issues because it prevents 300.Xr BIO_reset 3 301from clearing the data. 302.Sh BUGS 303There should be an option to set the maximum size of a memory BIO. 304.Pp 305There should be a way to "rewind" a read/write BIO without destroying 306its contents. 307