Tribblix: 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