OPEN_MEMSTREAM(3C) Standard C Library Functions OPEN_MEMSTREAM(3C)

open_memstream, open_wmemstream
open a memory stream

#include <stdio.h>

open_memstream(char **bufp, size_t *sizep);

#include <wchar.h>

open_wmemstream(wchar_t **bufp, size_t *sizep);

The open_memstream() and open_wmemstream() functions create an I/O stream that is backed by a dynamic memory buffer which will grow as needed. The stream is seekable and writable. The stream is not readable. The stream is byte-oriented in the case of the open_memstream() function or it is wide-oriented in the case of the open_wmemstream() function.

Memory for the stream is dynamically allocated and reallocated as though a call to malloc(3C). As the stream is written to, flushed, or closed, the underlying buffer will be grown automatically as required. After the stream is flushed or closed, the bufp argument will be filled in with a pointer to the current buffer. The sizep argument will be filled in with the smaller of the current buffer length and the current position in bytes (open_memstream()) or wide characters (open_wmemstream()), excluding a NUL character. Note, because the current position is taken into account, the actual size of the buffer may be larger than is found in sizep; however data should not be accessed beyond the indicated size. The values stored in the bufp and sizep arguments are only valid until the next write operation on the stream or a call to fclose(3C).

The stream maintains both the current position and the current length of the stream. Both the initial position and length of the buffer are set to zero. Whenever a write at the current position exceeds the current length of the buffer, the current length is increased and a NUL character, ‘\0’ (open_memstream()) or NUL wide character, ‘L\0’ (open_wmemstream()) will be added to the buffer. If the stream is seeked beyond the current length and a subsequent write occurs, intervening characters will be filled with the corresponding NUL character for the stream.

To release the stream, the caller must call the fclose(3C) function. The corresponding dynamically allocated memory will be disassociated from the stream and will become owned by the caller. The caller must eventually release the memory buffer pointed to in the bufp argument with a call to free(3C).

open_wmemstream(), fseek(3C), fsetops(3C,) and ftell(3C)

The specification for the open_wmemstream() function causes the fseek(3C) and ftell(3C) families of functions to operate differently. Traditionally, these functions always return units in bytes, regardless of whether the underlying stream is byte- or wide-oriented. However, when used against a stream created by the open_wmemstream() function these now count in terms of units of wide characters. While this is different from the traditional behavior, this does mean that the units will be the same as tracked in sizep.

open_wmemstream(and, byte-oriented, functions)

Unlike other streams, streams created by open_wmemstream() are not only wide-oriented, but operate in terms of the wchar_t data type. When normal bytes are written to the stream, an implicit multi-byte conversion state is maintained. Writing byte sequences that don't correspond to valid byte sequences in the locale can cause I/O errors to occur when using write functions such as fputc(3C) or fwrite(3C), or when buffered data is flushed through functions like fflush(3C) or fclose(3C).

The same problem can occur when explicitly using wide characters, for example, fputwc(3C), if the wide character represents a code point that is not valid in the current locale. To avoid these errors when flushing or closing, one can disable buffering by passing _IONBF as the buffering type with setvbuf(3C).

It is not recommended to change the locale of such a stream while writing a byte sequence that represents valid wide characters. The behavior of using byte-oriented functions is not standardized and not all systems will behave the same way.

Upon successful completion, the open_memstream() and open_wmemstream() functions returns a pointer to a stream. Otherwise, NULL is returned and errno is set to indicate the error.

The fmemopen() function will fail if:
Either of the bufp or sizep arguments are NULL.
{FOPEN_MAX} streams are currently open in the calling process.

{STREAM_MAX} streams are currently open in the calling process.

The system was unable to allocate memory for the stream or its backing memory buffer.



fclose(3C), fflush(3C), fmemopen(3C), free(3C), malloc(3C), setvbuf(3C)
March 25, 2020 OmniOS