| OPEN_MEMSTREAM(3C) | Standard C Library Functions | OPEN_MEMSTREAM(3C) |
open_memstream,
open_wmemstream — open a
memory stream
#include
<stdio.h>
FILE *
open_memstream(char **bufp,
size_t *sizep);
#include
<wchar.h>
FILE *
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:
fclose(3C), fflush(3C), fmemopen(3C), free(3C), malloc(3C), setvbuf(3C)
| March 25, 2020 | OmniOS |