Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Thursday, June 13, 2019
 
 

open_memstream (3C)

Name

open_memstream, open_wmemstream - open a dynamic memory buffer stream

Synopsis

#include <stdio.h>
FILE *open_memstream(char **bufp, size_t *sizep);
#include <wchar.h>
FILE *open_wmemstream(wchar_t **bufp, size_t *sizep);

Description

The open_memstream() and open_wmemstream() functions create an I/O stream associated with a dynamically allocated memory buffer. The stream is opened for writing and is seekable.

The stream associated with a call to open_memstream() is byte-oriented.

The stream associated with a call to open_wmemstream() is wide-oriented.

The stream maintains a current position in the allocated buffer and a current buffer length. The position is initially set to zero (the start of the buffer). Each write to the stream starts at the current position and move this position by the number of successfully written bytes for open_memstream() or the number of successfully written wide characters for open_wmemstream(). The length is initially set to zero. If a write moves the position to a value larger than the current length, the current length is set to this position. In this case, a null character for open_memstream() or a null wide character for open_wmemstream() is appended to the current buffer. For both functions, the terminating null is not included in the calculation of the buffer length.

After a successful fflush() or fclose(), the pointer referenced by bufp contains the address of the buffer, and the variable pointed to by sizep contains the smaller of the current buffer length and the number of bytes for open_memstream(), or the number of wide characters for open_wmemstream(), between the beginning of the buffer and the current file position indicator.

After a successful fflush(), the pointer referenced by bufp() and the variable referenced by sizep remain valid only until the next write operation on the stream or a call to fclose().

Return Values

Upon successful completion, these functions return a pointer to the object controlling the stream. Otherwise, a null pointer shall be returned, and errno shall be set to indicate the error.

Errors

These functions will fail if:

EINVAL

The bufp or sizep argument is NULL.

ENOMEM

Insufficient storage space is available.

Usage

The buffer created by these functions should be freed by the application after closing the stream, by means of a call to free().

Unlike a stream opened by fmemopen(), the mode of a stream opened by open_memstream() or open_wmemstream() cannot be changed by a call to freopen(NULL, mode, stream).

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
MT-Safe
Standard

See Also

fmemopen(3C), fopen(3C), freopen(3C), malloc(3C), attributes(7), standards(7)