Tribblix: manual page: fmemopen.3c

FMEMOPEN(3C) Standard C Library Functions FMEMOPEN(3C)

NAME

fmemopen - open a memory stream

SYNOPSIS

#include <stdio.h>

FILE *
fmemopen(void *restrict buf, size_t size, const char *restrict mode);

DESCRIPTION

The fmemopen() function provides a means of associating a file stream
with a corresponding memory buffer of a fixed size. The resulting
stream can then be used just like any other stream, and when done
should be released by calling the fclose(3C) function.

The stream can either dynamically allocate memory or it can use an
existing memory buffer. If buf is NULL, then a buffer size bytes long
will be allocated for the stream and initialized to zero. This buffer
will be allocated as though a call to malloc(3C) and will be freed when
fclose(3C) is called. When using this mode, the stream must be created
for update (indicated by a `+' character in the mode argument).
Otherwise, it is assumed that buf is at least size bytes long.

The mode argument determines whether the stream is opened for read,
write, or append. The mode argument accepts all the same values as
fopen(3C).

The resulting stream behaves in a similar way to a stream backed by a
file. The stream can be read and written to. The stream is seekable
and can either be byte or wide-character oriented. A NUL byte has no
special meaning when reading.

The stream logically tracks three different values:

1. The current position in the stream.

2. The current size of the stream.

3. The maximum size of the stream.

The current position is where reads or writes take place. When the
stream is opened for read or write (r, r+, w, w+) then the initial
position is set to zero. If the stream is opened for update (a, a+)
then the initial position is set to the first NUL byte in the buffer.

The current size of the stream represents the length of the stream.
Like a file, this starts at a specific size and then can grow over
time. Unlike a file, where the maximum size is determined by the file
system, the maximum size here is determined at the creation of the
stream.

This size is used when using SEEK_END as an argument to functions like
fseek(3C). Reads cannot advance beyond the current size of the stream
and attempting to read beyond it is considered hitting the end-of-file.
Writes beyond the end of the current size will cause the current size
to increase, though it cannot increase beyond the maximum size.

The initial size of the stream varies. It is set depending on the mode
and works as follows:

r, r+ The size is set to the size argument.

w, w+ The initial size is set to zero.

a, a+ The initial size is set according to the following rules:

1. If buf is a NULL pointer, the current size is set to
zero.

2. If a NUL byte is found in the first size bytes of
buf, then the current size is set to the first NUL
byte.

3. The position is set to the size argument (the
maximum size) if no NUL byte was found in buf.

The maximum size of the stream is determined by the size argument.
Writes beyond this size are dropped. Attempts to seek beyond the
maximum size will result in an error.

If the stream was open for writing or update, when the stream is
flushed or closed, a NUL byte will be written to terminate the stream
based on the current position and size of the stream. If the stream
was open for update, if the stream is flushed or closed and the last
write changed the current buffer size, a NUL byte will be written if
there is still space for it within the buffer.

By default, all streams are buffered. This means that writes beyond
the size of the memory buffer could fail, but not be seen until the
stream is flushed or closed. To detect errors right away, one can
explicitly disable buffering with the setvbuf(3C) function or perform
explicit buffer flushes with the fflush(3C) function.

RETURN VALUES

Upon successful completion, the fmemopen() function 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 The value of mode is invalid.

The size argument was zero.

The buf argument is NULL and the mode argument does
not contain a `+' character.

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 buffer.

MT-LEVEL
MT-Safe

INTERFACE STABILITY