illumos: manual page: open

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-Safe

INTERFACE STABILITY