BUF_MEM_NEW(3) | Library Functions Manual | BUF_MEM_NEW(3)

# NAME

`BUF_MEM_new`, `BUF_MEM_free`, `BUF_MEM_grow`, `BUF_MEM_grow_clean` — simple character arrays structure

# SYNOPSIS

library “libcrypto”
`#include <openssl/buffer.h>`

BUF_MEM *
`BUF_MEM_new`(void);

void
`BUF_MEM_free`(BUF_MEM *a);

int
`BUF_MEM_grow`(BUF_MEM *str, size_t len);

int
`BUF_MEM_grow_clean`(BUF_MEM *str, size_t len);

# DESCRIPTION

The buffer library handles simple character arrays. Buffers are used for various purposes in the library, most notably memory BIOs.

The library uses the BUF_MEM structure defined in buffer.h:

    typedef struct buf_mem_st {
    	size_t length;	/* current number of bytes */
    	char *data;
    	size_t max;	/* size of buffer */
    } BUF_MEM;

length is the current size of the buffer in bytes; max is the amount of memory allocated to the buffer. There are three functions which handle these and one miscellaneous function.

`BUF_MEM_new`() allocates a new buffer of zero size.

`BUF_MEM_free`() frees up an already existing buffer. The data is zeroed before freeing up in case the buffer contains sensitive data. If a is a `NULL` pointer, no action occurs.

`BUF_MEM_grow`() changes the size of an already existing buffer to len. Any data already in the buffer is preserved if it increases in size.

`BUF_MEM_grow_clean`() is similar to `BUF_MEM_grow`(), but it sets any freed or additionally allocated memory to zero.

# RETURN VALUES

`BUF_MEM_new`() returns the buffer or `NULL` on error.

`BUF_MEM_grow`() and `BUF_MEM_grow_clean`() return zero on error or the new size (i.e. len).

# SEE ALSO

BIO_new(3), BIO_s_mem(3)

# HISTORY

`BUF_MEM_new`(), `BUF_MEM_free`(), and `BUF_MEM_grow`() first appeared in SSLeay 0.6.0. All these functions have been available since OpenBSD 2.4.

`BUF_MEM_grow_clean`() first appeared in OpenSSL 0.9.7 and has been available since OpenBSD 3.2.

June 8, 2025 | Debian