| .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de), |
| .\" Michael Kerrisk <mtk-manpages@gmx.net> |
| .\" Distributed under the GPL. |
| .\" |
| .TH FMEMOPEN 3 2005-12-08 "GNU" "glibc function" |
| .SH NAME |
| fmemopen, open_memstream \- open memory as stream |
| .SH SYNOPSIS |
| .B #define _GNU_SOURCE |
| .br |
| .B #include <stdio.h> |
| .sp |
| .BI "FILE *fmemopen (void *"buf ", size_t "size "," |
| .BI "const char *" mode ");" |
| .sp |
| .BI "FILE * open_memstream(char ** "ptr ", size_t *" sizeloc ) |
| .SH DESCRIPTION |
| The |
| .BR fmemopen () |
| function opens a stream that permits the access specified by |
| .IR mode . |
| The stream allows I/O to be performed on the string or memory buffer |
| pointed to by |
| .IR buf . |
| This buffer must be at least |
| .I size |
| bytes long. |
| .PP |
| The argument |
| .I mode |
| is the same as for |
| .BR fopen (3) . |
| If |
| .I mode |
| specifies an append mode, then the initial file position is set to |
| location of the first null byte ('\\0') in the buffer; |
| otherwise the initial file position is set to the start of the buffer. |
| .PP |
| When a stream that has been opened for writing is flushed |
| .RB ( fflush (3)) |
| or closed |
| .RB ( fclose (3)), |
| a null byte is written at the end of the buffer if there is space. |
| The caller should ensure that an extra byte is available in the |
| buffer |
| (and that |
| .IR size |
| counts that byte) |
| to allow for this. |
| |
| Attempts to write more than |
| .I size |
| bytes to the buffer result in an error. |
| .\" FIXME Attempts to write more than 'size' bytes to the buffer |
| .\" should give an error, but see |
| .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1995 |
| .PP |
| In a stream opened for reading, |
| null bytes ('\\0') in the buffer do not cause read |
| operations to return an end-of-file indication. |
| A read from the buffer will only indicate end-of-file |
| when the file pointer advances |
| .I size |
| bytes past the start of the buffer. |
| .PP |
| If |
| .I buf |
| is specified as NULL, then |
| .BR fmemopen () |
| dynamically allocates a buffer |
| .I size |
| bytes long. |
| This is useful for an application that wants to write data to |
| a temporary buffer and then read it back again. |
| The buffer is automatically freed when the stream is closed. |
| Note that the caller has no way to obtain a pointer to the |
| temporary buffer allocated by this call (but see |
| .BR open_memstream () |
| below). |
| |
| The |
| .BR open_memstream () |
| opens a stream for writing to a buffer. |
| The buffer |
| is dynamically allocated (as with |
| .BR malloc (3)), |
| and automatically grows as required. |
| After closing the stream, the caller should |
| .BR free (3) |
| this buffer. |
| |
| When the stream is closed |
| .RB ( fclose (3)) |
| or flushed |
| .RB ( fflush (3)), |
| the locations pointed to by |
| .I ptr |
| and |
| .I sizeloc |
| are updated to contain, respectively, a pointer to the buffer and the |
| current size of the buffer. |
| These values remain valid only as long as the caller |
| performs no further output on the stream. |
| If further output is performed, then the stream |
| must again be flushed before trying to access these variables. |
| |
| A null byte is maintained at the end of the buffer. |
| This byte is |
| .I not |
| included in the size value stored at |
| .IR sizeloc . |
| .\" |
| .\" FIXME the following is from the glibc info doc, but appears not |
| .\" to be true: http://sourceware.org/bugzilla/show_bug.cgi?id=1996 |
| .\" The stream's file position can be changed with |
| .\" .BR fseek (3) |
| .\" or |
| .\" .BR fseeko (3). |
| .\" Moving the file position past the end |
| .\" of the data already written fills the intervening space with |
| .\" zeroes. |
| .SH "RETURN VALUE" |
| Upon successful completion |
| .BR fmemopen () |
| and |
| .BR open_memstream () |
| return a |
| .B FILE |
| pointer. |
| Otherwise, NULL is returned and the global variable |
| .I errno |
| is set to indicate the error. |
| |
| .SH "EXAMPLE" |
| The program below uses |
| .BR fmemopen () |
| to open an input buffer, and |
| .BR 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 produced by this program is the following: |
| .nf |
| |
| $ ./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); |
| } |
| .fi |
| .sp |
| .SH "CONFORMING TO" |
| These functions are GNU extensions. |
| .\" Jan 06: But they appear to be going up for standardization by |
| .\" POSIX/PASC/IEEE. |
| .SH "SEE ALSO" |
| .BR open (3) |