OPEN_MEMSTREAM(3C) Standard C Library Functions OPEN_MEMSTREAM(3C)
NAME
open_memstream,
open_wmemstream - open a memory 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
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.
RETURN VALUES
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.
ERRORS
The
fmemopen() function will fail if:
EINVAL Either of the
bufp or
sizep arguments are NULL.
EMFILE {FOPEN_MAX} streams are currently open in the calling
process.
{STREAM_MAX} streams are currently open in the calling
process.
ENOMEM The system was unable to allocate memory for the stream
or its backing memory buffer.
MT-LEVEL MT-SafeINTERFACE STABILITY
CommittedSEE ALSO
fclose(3C),
fflush(3C),
fmemopen(3C),
free(3C),
malloc(3C),
setvbuf(3C)OmniOS March 25, 2020 OmniOS