NAME

fmemopen, open_memstream - open memory as stream

SYNOPSIS

#define _GNU_SOURCE
#include <stdio.h>

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

FILE * open_memstream(char ** ptr, size_t *sizeloc)

DESCRIPTION

The fmemopen() function opens a stream that permits the access specified by mode. This stream allows I/O to be performed on a string or memory buffer, specified in buf. This buffer must be at least size bytes long.

If buf is specified as NULL, then fmemopen() dynamically allocates an array size bytes long. This is only useful if you are going to write things to the buffer and then read them back in again, because there is no way of actually getting a pointer to the buffer (but see the description of open_memstream() below). The buffer is automatically freed when the stream is closed.

The argument mode is the same as for fopen(). If mode specifies an append mode, then the initial file position is set to the first null character ('\0'); otherwise the initial file position is set to the beginning of the buffer.

When a stream that has been opened for writing is flushed or closed, a null character ('\0') is written at the end of the buffer if there is space. You should add an extra byte to the size argument to account for this. Attempts to write more than size bytes to the buffer result in an error.

For a stream open for reading, null characters ('\0') in the buffer do not count as "end of file". Read operations indicate end of file only when the file position advances past size bytes. If you want to read characters from a NUL-terminated string, you should supply the length of the string as the size argument.

The open_memstream() opens a stream for writing to a buffer. The buffer is allocated dynamically (as with malloc(3)), and grown as necessary. After closing the stream, the caller should free(3) this buffer.

When the stream is closed with fclose(3) or flushed with fflush(3) the locations ptr and sizeloc are updated to contain the pointer to the buffer and its size. The values thus stored remain valid only as long as no further output on the stream takes place. If you do more output, you must flush the stream again before trying to access these variables again.

A null character ('\0') is written at the end of the buffer. This character is not included in the size value stored at sizeloc.

RETURN VALUE

Upon successful completion fmemopen() and open_memstream() return a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error.

EXAMPLE

The program below uses fmemopen() to open an input buffer, and open_memstream() to open a dynamically sized output buffer. The program scans its input string (taken from the program's first command-line argument) reading integers, and writes the squares of these integers to the output buffer. An example of the output produded by this program is the following:

$ ./a.out "1 23 43"
size=11; ptr=1 529 1849
#define _GNU_SOURCE
#include <assert.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
int main(int argc, char *argv[])
{

    FILE *out, *in;

    int v, s;

    size_t size;

    char *ptr;

    assert(argc == 2);

    in = fmemopen(argv[1], strlen(argv[1]), "r");

    if (in == NULL) { perror("fmemopen"); exit(EXIT_FAILURE);}

    out = open_memstream(&ptr, &size);

    if (out == NULL) { perror("fmemopen"); exit(EXIT_FAILURE);}

    for (;;) {

        s = fscanf(in, "%d", &v);

        if (s <= 0)

            break;

        s = fprintf(out, "%d ", v * v);

        if (s == -1) { perror("fprintf"); exit(EXIT_FAILURE); }

    }

    fclose(in);

    fclose(out);

    printf("size=%ld; ptr=%s\n", (long) size, ptr);

    free(ptr);

    exit(EXIT_SUCCESS);
}

CONFORMING TO

These functions are GNU extensions.

SEE ALSO

open(3)