]>
Commit | Line | Data |
---|---|---|
efa25b17 | 1 | .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de), |
c11b1abf | 2 | .\" and Copyright 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
89c9a314 | 3 | .\" Distributed under the GPL. |
86cfe9cb | 4 | .\" |
0ed55ece | 5 | .TH FMEMOPEN 3 2005-12-08 "GNU" "Linux Programmer's Manual" |
86cfe9cb MK |
6 | .SH NAME |
7 | fmemopen, open_memstream \- open memory as stream | |
8 | .SH SYNOPSIS | |
9 | .B #define _GNU_SOURCE | |
10 | .br | |
11 | .B #include <stdio.h> | |
12 | .sp | |
8073758d | 13 | .BI "FILE *fmemopen(void *"buf ", size_t "size "," |
86cfe9cb MK |
14 | .BI "const char *" mode ");" |
15 | .sp | |
52e87bbe | 16 | .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); |
86cfe9cb MK |
17 | .SH DESCRIPTION |
18 | The | |
19 | .BR fmemopen () | |
20 | function opens a stream that permits the access specified by | |
21 | .IR mode . | |
c13182ef | 22 | The stream allows I/O to be performed on the string or memory buffer |
89c9a314 | 23 | pointed to by |
c13182ef | 24 | .IR buf . |
86cfe9cb MK |
25 | This buffer must be at least |
26 | .I size | |
27 | bytes long. | |
28 | .PP | |
86cfe9cb MK |
29 | The argument |
30 | .I mode | |
31 | is the same as for | |
89c9a314 | 32 | .BR fopen (3) . |
86cfe9cb MK |
33 | If |
34 | .I mode | |
c13182ef | 35 | specifies an append mode, then the initial file position is set to |
89c9a314 MK |
36 | location of the first null byte ('\\0') in the buffer; |
37 | otherwise the initial file position is set to the start of the buffer. | |
86cfe9cb | 38 | .PP |
c13182ef | 39 | When a stream that has been opened for writing is flushed |
89c9a314 MK |
40 | .RB ( fflush (3)) |
41 | or closed | |
42 | .RB ( fclose (3)), | |
43 | a null byte is written at the end of the buffer if there is space. | |
c13182ef | 44 | The caller should ensure that an extra byte is available in the |
89c9a314 MK |
45 | buffer |
46 | (and that | |
0daa9e92 | 47 | .I size |
89c9a314 | 48 | counts that byte) |
c13182ef | 49 | to allow for this. |
89c9a314 | 50 | |
86cfe9cb MK |
51 | Attempts to write more than |
52 | .I size | |
53 | bytes to the buffer result in an error. | |
c13182ef | 54 | (By default, such errors will only be visible when the |
c75ec721 MK |
55 | .I stdio |
56 | buffer is flushed. | |
c13182ef | 57 | Disabling buffering with |
c75ec721 | 58 | .I setbuf(fp,\ NULL) |
97b6cd41 | 59 | may be useful to detect errors at the time of an output operation. |
c13182ef | 60 | Alternatively, the caller can explicitly set |
97b6cd41 MK |
61 | .I buf |
62 | as the stdio stream buffer, at the same time informing stdio | |
c13182ef | 63 | of the buffer's size, using |
97b6cd41 | 64 | .IR "setbuffer(fp, buf, size)" .) |
96a67b11 MK |
65 | .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995 |
66 | .\" and | |
516f0680 | 67 | .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html |
86cfe9cb | 68 | .PP |
c13182ef MK |
69 | In a stream opened for reading, |
70 | null bytes ('\\0') in the buffer do not cause read | |
89c9a314 MK |
71 | operations to return an end-of-file indication. |
72 | A read from the buffer will only indicate end-of-file | |
c13182ef | 73 | when the file pointer advances |
86cfe9cb | 74 | .I size |
89c9a314 MK |
75 | bytes past the start of the buffer. |
76 | .PP | |
c13182ef MK |
77 | If |
78 | .I buf | |
89c9a314 MK |
79 | is specified as NULL, then |
80 | .BR fmemopen () | |
81 | dynamically allocates a buffer | |
86cfe9cb | 82 | .I size |
c13182ef | 83 | bytes long. |
89c9a314 MK |
84 | This is useful for an application that wants to write data to |
85 | a temporary buffer and then read it back again. | |
86 | The buffer is automatically freed when the stream is closed. | |
87 | Note that the caller has no way to obtain a pointer to the | |
88 | temporary buffer allocated by this call (but see | |
89 | .BR open_memstream () | |
90 | below). | |
86cfe9cb MK |
91 | |
92 | The | |
93 | .BR open_memstream () | |
c13182ef | 94 | opens a stream for writing to a buffer. |
86cfe9cb | 95 | The buffer |
c13182ef | 96 | is dynamically allocated (as with |
86cfe9cb | 97 | .BR malloc (3)), |
89c9a314 | 98 | and automatically grows as required. |
86cfe9cb MK |
99 | After closing the stream, the caller should |
100 | .BR free (3) | |
010b1b8e | 101 | this buffer. |
86cfe9cb | 102 | |
c13182ef | 103 | When the stream is closed |
89c9a314 | 104 | .RB ( fclose (3)) |
c13182ef | 105 | or flushed |
89c9a314 MK |
106 | .RB ( fflush (3)), |
107 | the locations pointed to by | |
c13182ef MK |
108 | .I ptr |
109 | and | |
86cfe9cb | 110 | .I sizeloc |
89c9a314 | 111 | are updated to contain, respectively, a pointer to the buffer and the |
c13182ef MK |
112 | current size of the buffer. |
113 | These values remain valid only as long as the caller | |
114 | performs no further output on the stream. | |
115 | If further output is performed, then the stream | |
89c9a314 | 116 | must again be flushed before trying to access these variables. |
86cfe9cb | 117 | |
c13182ef MK |
118 | A null byte is maintained at the end of the buffer. |
119 | This byte is | |
120 | .I not | |
121 | included in the size value stored at | |
86cfe9cb | 122 | .IR sizeloc . |
c13182ef | 123 | .\" |
0e1ad98c | 124 | .\" FIXME . The glibc info doc has text like the following, but it appears |
777f5a9e | 125 | .\" not to be true: http://sourceware.org/bugzilla/show_bug.cgi?id=1996 |
92057f4d | 126 | .\" The stream's file position can be changed with |
c13182ef MK |
127 | .\" .BR fseek (3) |
128 | .\" or | |
86cfe9cb MK |
129 | .\" .BR fseeko (3). |
130 | .\" Moving the file position past the end | |
131 | .\" of the data already written fills the intervening space with | |
132 | .\" zeroes. | |
133 | .SH "RETURN VALUE" | |
c13182ef MK |
134 | Upon successful completion |
135 | .BR fmemopen () | |
86cfe9cb MK |
136 | and |
137 | .BR open_memstream () | |
138 | return a | |
097585ed | 139 | .I FILE |
c13182ef | 140 | pointer. |
86cfe9cb | 141 | Otherwise, NULL is returned and the global variable |
c13182ef | 142 | .I errno |
86cfe9cb | 143 | is set to indicate the error. |
2b2581ee MK |
144 | .SH "CONFORMING TO" |
145 | These functions are GNU extensions. | |
146 | .\" Jan 06: But they appear to be going up for standardization by | |
147 | .\" POSIX/PASC/IEEE. | |
86cfe9cb | 148 | .SH "EXAMPLE" |
c13182ef | 149 | The program below uses |
86cfe9cb MK |
150 | .BR fmemopen () |
151 | to open an input buffer, and | |
152 | .BR open_memstream () | |
153 | to open a dynamically sized output buffer. | |
154 | The program scans its input string (taken from the program's | |
155 | first command-line argument) reading integers, | |
156 | and writes the squares of these integers to the output buffer. | |
89c9a314 | 157 | An example of the output produced by this program is the following: |
86cfe9cb MK |
158 | .nf |
159 | ||
160 | $ ./a.out "1 23 43" | |
161 | size=11; ptr=1 529 1849 | |
162 | ||
163 | #define _GNU_SOURCE | |
164 | #include <assert.h> | |
165 | #include <string.h> | |
166 | #include <stdio.h> | |
167 | #include <stdlib.h> | |
168 | ||
d3b5ab82 MK |
169 | #define die(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0) |
170 | ||
c13182ef | 171 | int |
cf0a9ace | 172 | main(int argc, char *argv[]) |
86cfe9cb MK |
173 | { |
174 | FILE *out, *in; | |
175 | int v, s; | |
176 | size_t size; | |
177 | char *ptr; | |
178 | ||
179 | assert(argc == 2); | |
180 | ||
181 | in = fmemopen(argv[1], strlen(argv[1]), "r"); | |
d3b5ab82 MK |
182 | if (in == NULL) |
183 | die("fmemopen"); | |
86cfe9cb MK |
184 | |
185 | out = open_memstream(&ptr, &size); | |
d3b5ab82 MK |
186 | if (out == NULL) |
187 | die("fmemopen"); | |
86cfe9cb MK |
188 | |
189 | for (;;) { | |
190 | s = fscanf(in, "%d", &v); | |
191 | if (s <= 0) | |
192 | break; | |
193 | ||
194 | s = fprintf(out, "%d ", v * v); | |
29059a65 | 195 | if (s == \-1) |
d3b5ab82 | 196 | die("fprintf"); |
86cfe9cb MK |
197 | } |
198 | fclose(in); | |
199 | fclose(out); | |
200 | printf("size=%ld; ptr=%s\\n", (long) size, ptr); | |
201 | free(ptr); | |
202 | exit(EXIT_SUCCESS); | |
203 | } | |
204 | .fi | |
86cfe9cb | 205 | .SH "SEE ALSO" |
a5dbb527 | 206 | .BR fopen (3), |
0a90178c | 207 | .BR feature_test_macros (7) |