path: root/lib/libcrypto/man/BIO_s_mem.3

.\" $OpenBSD: BIO_s_mem.3,v 1.13 2018/05/12 20:12:17 schwarze Exp $
.\" full merge up to: OpenSSL 8711efb4 Mon Apr 20 11:33:12 2009 +0000
.\" selective merge up to: OpenSSL 36359cec Mar 7 14:37:23 2018 +0100
.\"
.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
.\" Copyright (c) 2000 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 12 2018 $
.Dt BIO_S_MEM 3
.Os
.Sh NAME
.Nm BIO_s_mem ,
.Nm BIO_set_mem_eof_return ,
.Nm BIO_get_mem_data ,
.Nm BIO_set_mem_buf ,
.Nm BIO_get_mem_ptr ,
.Nm BIO_new_mem_buf
.Nd memory BIO
.Sh SYNOPSIS
.In openssl/bio.h
.Ft const BIO_METHOD *
.Fo BIO_s_mem
.Fa "void"
.Fc
.Ft long
.Fo BIO_set_mem_eof_return
.Fa "BIO *b"
.Fa "int v"
.Fc
.Ft long
.Fo BIO_get_mem_data
.Fa "BIO *b"
.Fa "char **pp"
.Fc
.Ft long
.Fo BIO_set_mem_buf
.Fa "BIO *b"
.Fa "BUF_MEM *bm"
.Fa "int c"
.Fc
.Ft long
.Fo BIO_get_mem_ptr
.Fa "BIO *b"
.Fa "BUF_MEM **pp"
.Fc
.Ft BIO *
.Fo BIO_new_mem_buf
.Fa "const void *buf"
.Fa "int len"
.Fc
.Sh DESCRIPTION
.Fn BIO_s_mem
returns the memory BIO method function.
.Pp
A memory BIO is a source/sink BIO which uses memory for its I/O.
Data written to a memory BIO is stored in a
.Vt BUF_MEM
structure which is extended as appropriate to accommodate the stored data.
.Pp
Any data written to a memory BIO can be recalled by reading from it.
Unless the memory BIO is read only,
any data read from it is deleted from the BIO.
.Pp
Memory BIOs support
.Xr BIO_gets 3
and
.Xr BIO_puts 3 .
.Pp
If the
.Dv BIO_CLOSE
flag is set when a memory BIO is freed, the underlying
.Dv BUF_MEM
structure is also freed.
.Pp
Calling
.Xr BIO_reset 3
on a read/write memory BIO clears any data in it.
On a read only BIO it restores the BIO to its original state
and the read only data can be read again.
.Pp
.Xr BIO_eof 3
is true if no data is in the BIO.
.Pp
.Xr BIO_ctrl_pending 3
returns the number of bytes currently stored.
.Pp
.Fn BIO_set_mem_eof_return
sets the behaviour of memory BIO
.Fa b
when it is empty.
If
.Fa v
is zero, then an empty memory BIO will return EOF:
it will return zero and
.Fn BIO_should_retry
will be false.
If
.Fa v
is non-zero then it will return
.Fa v
when it is empty and it will set the read retry flag:
.Fn BIO_read_retry
is true.
To avoid ambiguity with a normal positive return value
.Fa v
should be set to a negative value, typically -1.
.Pp
.Fn BIO_get_mem_data
sets
.Pf * Fa pp
to a pointer to the start of the memory BIO's data
and returns the total amount of data available.
It is implemented as a macro.
.Pp
.Fn BIO_set_mem_buf
sets the internal BUF_MEM structure to
.Fa bm
and sets the close flag to
.Fa c .
That is,
.Fa c
should be either
.Dv BIO_CLOSE
or
.Dv BIO_NOCLOSE .
.Fn BIO_set_mem_buf
is a macro.
.Pp
.Fn BIO_get_mem_ptr
places the underlying
.Vt BUF_MEM
structure in
.Pf * Fa pp .
It is a macro.
.Pp
.Fn BIO_new_mem_buf
creates a memory BIO using
.Fa len
bytes of data at
.Fa buf .
If
.Fa len
is -1, then
.Fa buf
is assumed to be NUL terminated and its length is determined by
.Xr strlen 3 .
The BIO is set to a read only state and as a result cannot be written to.
This is useful when some data needs to be made available
from a static area of memory in the form of a BIO.
The supplied data is read directly from the supplied buffer:
it is
.Em not
copied first, so the supplied area of memory must be unchanged
until the BIO is freed.
.Pp
Writes to memory BIOs will always succeed if memory is available:
their size can grow indefinitely.
.Pp
Every read from a read/write memory BIO will remove the data just read
with an internal copy operation.
If a BIO contains a lot of data and it is read in small chunks,
the operation can be very slow.
The use of a read only memory BIO avoids this problem.
If the BIO must be read/write then adding a buffering BIO
to the chain will speed up the process.
.Sh RETURN VALUES
.Fn BIO_s_mem
returns a pointer to a static object.
.Pp
.Fn BIO_set_mem_eof_return ,
.Fn BIO_get_mem_data ,
.Fn BIO_set_mem_buf ,
and
.Fn BIO_get_mem_ptr
return 1 on success or a value less than or equal to 0 if an error occurred.
.Pp
.Fn BIO_new_mem_buf
returns a newly allocated
.Vt BIO
object on success or
.Dv NULL
on error.
.Sh EXAMPLES
Create a memory BIO and write some data to it:
.Bd -literal -offset indent
BIO *mem = BIO_new(BIO_s_mem());
BIO_puts(mem, "Hello World\en");
.Ed
.Pp
Create a read only memory BIO:
.Bd -literal -offset indent
char data[] = "Hello World";
BIO *mem;
mem = BIO_new_mem_buf(data, -1);
.Ed
.Pp
Extract the
.Vt BUF_MEM
structure from a memory BIO and then free up the BIO:
.Bd -literal -offset indent
BUF_MEM *bptr;
BIO_get_mem_ptr(mem, &bptr);
/* Make sure BIO_free() leaves BUF_MEM alone. */
BIO_set_close(mem, BIO_NOCLOSE);
BIO_free(mem);
.Ed
.Sh SEE ALSO
.Xr BIO_new 3
.Sh HISTORY
.Fn BIO_s_mem
first appeared in SSLeay 0.6.0.
.Fn BIO_set_mem_buf
and
.Fn BIO_get_mem_ptr
first appeared in SSLeay 0.6.5.
These functions have been available since
.Ox 2.4 .
.Pp
.Fn BIO_set_mem_eof_return
and
.Fn BIO_get_mem_data
first appeared in SSLeay 0.9.1 and have been available since
.Ox 2.6 .
.Pp
.Fn BIO_new_mem_buf
first appeared in OpenSSL 0.9.5 and has been available since
.Ox 2.7 .
.Sh BUGS
There should be an option to set the maximum size of a memory BIO.
.Pp
There should be a way to "rewind" a read/write BIO without destroying
its contents.
.Pp
The copying operation should not occur after every small read
of a large BIO to improve efficiency.