BIO_S_MEM(3)               Library Functions Manual               BIO_S_MEM(3)

NAME
     BIO_s_mem, BIO_set_mem_eof_return, BIO_get_mem_data, BIO_set_mem_buf,
     BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO

SYNOPSIS
     #include <openssl/bio.h>

     const BIO_METHOD *
     BIO_s_mem(void);

     long
     BIO_set_mem_eof_return(BIO *b, int v);

     long
     BIO_get_mem_data(BIO *b, char **pp);

     long
     BIO_set_mem_buf(BIO *b, BUF_MEM *bm, int c);

     long
     BIO_get_mem_ptr(BIO *b, BUF_MEM **pp);

     BIO *
     BIO_new_mem_buf(const void *buf, int len);

DESCRIPTION
     BIO_s_mem() returns the memory BIO method function.

     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 BUF_MEM structure which is
     extended as appropriate to accommodate the stored data.

     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.  To find out whether a memory BIO is read only,
     BIO_test_flags(3) can be called with an argument of BIO_FLAGS_MEM_RDONLY.

     Memory BIOs support BIO_gets(3) and BIO_puts(3).

     If the BIO_CLOSE flag is set when a memory BIO is freed, the underlying
     BUF_MEM structure is also freed.

     Calling 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.

     BIO_eof(3) is true if no data is in the BIO.

     BIO_ctrl_pending(3) returns the number of bytes currently stored.

     BIO_set_mem_eof_return() sets the behaviour of memory BIO b when it is
     empty.  If v is zero, then an empty memory BIO will return EOF: it will
     return zero and BIO_should_retry() will be false.  If v is non-zero then
     it will return v when it is empty and it will set the read retry flag:
     BIO_read_retry() is true.  To avoid ambiguity with a normal positive
     return value v should be set to a negative value, typically -1.

     BIO_get_mem_data() sets *pp to a pointer to the start of the memory BIO's
     data and returns the total amount of data available.

     BIO_set_mem_buf() sets the internal BUF_MEM structure to bm and sets the
     close flag to c.  That is, c should be either BIO_CLOSE or BIO_NOCLOSE.

     BIO_get_mem_ptr() places the underlying BUF_MEM structure in *pp.

     BIO_new_mem_buf() creates a memory BIO using len bytes of data at buf.
     If len is -1, then buf is assumed to be NUL terminated and its length is
     determined by 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 not copied
     first, so the supplied area of memory must be unchanged until the BIO is
     freed.

     Writes to memory BIOs will always succeed if memory is available: their
     size can grow indefinitely.

     BIO_ctrl(3) cmd arguments correspond to macros as follows:

        cmd constant                    corresponding macro
        BIO_C_GET_BUF_MEM_PTR           BIO_get_mem_ptr()
        BIO_C_SET_BUF_MEM               BIO_set_mem_buf()
        BIO_C_SET_BUF_MEM_EOF_RETURN    BIO_set_mem_eof_return()
        BIO_CTRL_EOF                    BIO_eof(3)
        BIO_CTRL_GET_CLOSE              BIO_get_close(3)
        BIO_CTRL_INFO                   BIO_get_mem_data()
        BIO_CTRL_PENDING                BIO_pending(3)
        BIO_CTRL_RESET                  BIO_reset(3)
        BIO_CTRL_SET_CLOSE              BIO_set_close(3)
        BIO_CTRL_WPENDING               BIO_wpending(3)

RETURN VALUES
     BIO_s_mem() returns a pointer to a static object.

     When called on a memory BIO object, BIO_method_type(3) returns the
     constant BIO_TYPE_MEM and BIO_method_name(3) returns a pointer to the
     static string "memory buffer".

     BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf(), and
     BIO_get_mem_ptr() return 1 on success or a value less than or equal to 0
     if an error occurred.

     BIO_new_mem_buf() returns a newly allocated BIO object on success or NULL
     on error.

EXAMPLES
     Create a memory BIO and write some data to it:

           BIO *mem = BIO_new(BIO_s_mem());
           BIO_puts(mem, "Hello World\n");

     Create a read only memory BIO:

           char data[] = "Hello World";
           BIO *mem;
           mem = BIO_new_mem_buf(data, -1);

     Extract the BUF_MEM structure from a memory BIO and then free up the BIO:

           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);

SEE ALSO
     BIO_new(3), BUF_MEM_new(3)

HISTORY
     BIO_s_mem() first appeared in SSLeay 0.6.0.  BIO_set_mem_buf() and
     BIO_get_mem_ptr() first appeared in SSLeay 0.6.5.  These functions have
     been available since OpenBSD 2.4.

     BIO_set_mem_eof_return() and BIO_get_mem_data() first appeared in SSLeay
     0.9.1 and have been available since OpenBSD 2.6.

     BIO_new_mem_buf() first appeared in OpenSSL 0.9.5 and has been available
     since OpenBSD 2.7.

CAVEATS
     Do not manually switch a writable memory BIO to read-only mode: calling
     BIO_set_flags(3) with an argument of BIO_FLAGS_MEM_RDONLY will ultimately
     result in a memory leak when the BIO object is finally handed to
     BIO_free(3).  It might also cause security issues because it prevents
     BIO_reset(3) from clearing the data.

BUGS
     There should be an option to set the maximum size of a memory BIO.

     There should be a way to "rewind" a read/write BIO without destroying its
     contents.

Linux 6.8.2-arch2-1            November 16, 2023           Linux 6.8.2-arch2-1