]>
Commit | Line | Data |
---|---|---|
efa25b17 | 1 | .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de), |
360e0be2 | 2 | .\" and Copyright 2005, 2012 Michael Kerrisk <mtk.manpages@gmail.com> |
89c9a314 | 3 | .\" Distributed under the GPL. |
3a0f269d | 4 | .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream() |
86cfe9cb | 5 | .\" |
360e0be2 | 6 | .TH FMEMOPEN 3 2012-04-28 "GNU" "Linux Programmer's Manual" |
86cfe9cb | 7 | .SH NAME |
3a0f269d | 8 | fmemopen, open_memstream, open_wmemstream \- open memory as stream |
86cfe9cb | 9 | .SH SYNOPSIS |
99111b75 | 10 | .nf |
86cfe9cb | 11 | .B #include <stdio.h> |
99111b75 MK |
12 | |
13 | .BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");" | |
14 | ||
52e87bbe | 15 | .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); |
99111b75 | 16 | |
3a0f269d | 17 | .B #include <wchar.h> |
99111b75 | 18 | |
3a0f269d | 19 | .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc ); |
31337f93 MK |
20 | .fi |
21 | .sp | |
22 | .in -4n | |
23 | Feature Test Macro Requirements for glibc (see | |
24 | .BR feature_test_macros (7)): | |
25 | .in | |
26 | .sp | |
27 | .BR fmemopen (), | |
28 | .BR open_memstream (), | |
29 | .BR open_wmemstream (): | |
ea91c3fd MK |
30 | .PD 0 |
31 | .ad l | |
32 | .RS 4 | |
33 | .TP 4 | |
34 | Since glibc 2.10: | |
35 | _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L | |
36 | .TP | |
31337f93 MK |
37 | Before glibc 2.10: |
38 | _GNU_SOURCE | |
ea91c3fd MK |
39 | .RE |
40 | .ad | |
41 | .PD | |
86cfe9cb MK |
42 | .SH DESCRIPTION |
43 | The | |
44 | .BR fmemopen () | |
45 | function opens a stream that permits the access specified by | |
46 | .IR mode . | |
c13182ef | 47 | The stream allows I/O to be performed on the string or memory buffer |
89c9a314 | 48 | pointed to by |
c13182ef | 49 | .IR buf . |
86cfe9cb MK |
50 | This buffer must be at least |
51 | .I size | |
52 | bytes long. | |
53 | .PP | |
86cfe9cb MK |
54 | The argument |
55 | .I mode | |
56 | is the same as for | |
1368e847 | 57 | .BR fopen (3). |
86cfe9cb MK |
58 | If |
59 | .I mode | |
c13182ef | 60 | specifies an append mode, then the initial file position is set to |
16ee3d56 | 61 | the location of the first null byte (\(aq\\0\(aq) in the buffer; |
89c9a314 | 62 | otherwise the initial file position is set to the start of the buffer. |
16ee3d56 | 63 | Since glibc 2.9, |
d8eca585 | 64 | the letter \(aqb\(aq may be specified as the second character in |
363e70d2 MK |
65 | .IR mode . |
66 | This provides "binary" mode: | |
e008cdda | 67 | writes don't implicitly add a terminating null byte, and |
363e70d2 MK |
68 | .BR fseek (3) |
69 | .B SEEK_END | |
70 | is relative to the end of the buffer (i.e., the value specified by the | |
71 | .I size | |
72 | argument), rather than the current string length. | |
86cfe9cb | 73 | .PP |
c13182ef | 74 | When a stream that has been opened for writing is flushed |
89c9a314 MK |
75 | .RB ( fflush (3)) |
76 | or closed | |
77 | .RB ( fclose (3)), | |
78 | a null byte is written at the end of the buffer if there is space. | |
c13182ef | 79 | The caller should ensure that an extra byte is available in the |
89c9a314 MK |
80 | buffer |
81 | (and that | |
0daa9e92 | 82 | .I size |
89c9a314 | 83 | counts that byte) |
c13182ef | 84 | to allow for this. |
89c9a314 | 85 | |
86cfe9cb MK |
86 | Attempts to write more than |
87 | .I size | |
88 | bytes to the buffer result in an error. | |
c13182ef | 89 | (By default, such errors will only be visible when the |
c75ec721 MK |
90 | .I stdio |
91 | buffer is flushed. | |
c13182ef | 92 | Disabling buffering with |
c75ec721 | 93 | .I setbuf(fp,\ NULL) |
97b6cd41 | 94 | may be useful to detect errors at the time of an output operation. |
c13182ef | 95 | Alternatively, the caller can explicitly set |
97b6cd41 MK |
96 | .I buf |
97 | as the stdio stream buffer, at the same time informing stdio | |
c13182ef | 98 | of the buffer's size, using |
97b6cd41 | 99 | .IR "setbuffer(fp, buf, size)" .) |
96a67b11 MK |
100 | .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995 |
101 | .\" and | |
516f0680 | 102 | .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html |
86cfe9cb | 103 | .PP |
c13182ef | 104 | In a stream opened for reading, |
f81fb444 | 105 | null bytes (\(aq\\0\(aq) in the buffer do not cause read |
89c9a314 MK |
106 | operations to return an end-of-file indication. |
107 | A read from the buffer will only indicate end-of-file | |
c13182ef | 108 | when the file pointer advances |
86cfe9cb | 109 | .I size |
89c9a314 MK |
110 | bytes past the start of the buffer. |
111 | .PP | |
c13182ef MK |
112 | If |
113 | .I buf | |
89c9a314 | 114 | is specified as NULL, then |
3cf81850 | 115 | .BR fmemopen () |
89c9a314 | 116 | dynamically allocates a buffer |
86cfe9cb | 117 | .I size |
c13182ef | 118 | bytes long. |
89c9a314 MK |
119 | This is useful for an application that wants to write data to |
120 | a temporary buffer and then read it back again. | |
121 | The buffer is automatically freed when the stream is closed. | |
122 | Note that the caller has no way to obtain a pointer to the | |
123 | temporary buffer allocated by this call (but see | |
124 | .BR open_memstream () | |
125 | below). | |
86cfe9cb MK |
126 | |
127 | The | |
128 | .BR open_memstream () | |
31dec0c7 | 129 | function opens a stream for writing to a buffer. |
86cfe9cb | 130 | The buffer |
c13182ef | 131 | is dynamically allocated (as with |
86cfe9cb | 132 | .BR malloc (3)), |
89c9a314 | 133 | and automatically grows as required. |
86cfe9cb MK |
134 | After closing the stream, the caller should |
135 | .BR free (3) | |
010b1b8e | 136 | this buffer. |
86cfe9cb | 137 | |
c13182ef | 138 | When the stream is closed |
89c9a314 | 139 | .RB ( fclose (3)) |
c13182ef | 140 | or flushed |
89c9a314 MK |
141 | .RB ( fflush (3)), |
142 | the locations pointed to by | |
c13182ef MK |
143 | .I ptr |
144 | and | |
86cfe9cb | 145 | .I sizeloc |
89c9a314 | 146 | are updated to contain, respectively, a pointer to the buffer and the |
c13182ef MK |
147 | current size of the buffer. |
148 | These values remain valid only as long as the caller | |
149 | performs no further output on the stream. | |
150 | If further output is performed, then the stream | |
89c9a314 | 151 | must again be flushed before trying to access these variables. |
86cfe9cb | 152 | |
c13182ef MK |
153 | A null byte is maintained at the end of the buffer. |
154 | This byte is | |
155 | .I not | |
156 | included in the size value stored at | |
86cfe9cb | 157 | .IR sizeloc . |
33b1b47e MK |
158 | |
159 | The stream's file position can be changed with | |
160 | .BR fseek (3) | |
161 | or | |
162 | .BR fseeko (3). | |
163 | Moving the file position past the end | |
164 | of the data already written fills the intervening space with | |
165 | zeros. | |
3a0f269d PB |
166 | |
167 | The | |
168 | .BR open_wmemstream () | |
4f9ea6c3 MK |
169 | is similar to |
170 | .BR open_memstream (), | |
171 | but operates on wide characters instead of bytes. | |
86cfe9cb | 172 | .SH "RETURN VALUE" |
c13182ef | 173 | Upon successful completion |
3a0f269d | 174 | .BR fmemopen (), |
86cfe9cb | 175 | .BR open_memstream () |
3a0f269d PB |
176 | and |
177 | .BR open_wmemstream () | |
86cfe9cb | 178 | return a |
097585ed | 179 | .I FILE |
c13182ef | 180 | pointer. |
28d03ce9 | 181 | Otherwise, NULL is returned and |
c13182ef | 182 | .I errno |
86cfe9cb | 183 | is set to indicate the error. |
45906a48 MK |
184 | .SH VERSIONS |
185 | .BR fmemopen () | |
16625773 | 186 | and |
45906a48 | 187 | .BR open_memstream () |
16625773 | 188 | were already available in glibc 1.0.x. |
45906a48 MK |
189 | .BR open_wmemstream () |
190 | is available since glibc 2.4. | |
2b2581ee | 191 | .SH "CONFORMING TO" |
aed04a0a MK |
192 | POSIX.1-2008. |
193 | These functions are not specified in POSIX.1-2001, | |
194 | and are not widely available on other systems. | |
360e0be2 MK |
195 | |
196 | POSIX.1-2008 specifies that \(aqb\(aq in | |
197 | .IR mode | |
198 | shall be ignored. | |
199 | However, Technical Corrigendum 1 | |
200 | .\" http://austingroupbugs.net/view.php?id=396 | |
201 | adjusts the standard to allow implementation-specific treatment for this case, | |
202 | thus permitting the glibc treatment of \(aqb\(aq. | |
a76ca000 PB |
203 | .SH NOTES |
204 | There is no file descriptor associated with the file stream | |
205 | returned by these functions | |
e80aa4d8 | 206 | (i.e., |
a76ca000 PB |
207 | .BR fileno (3) |
208 | will return an error if called on the returned stream). | |
28c1dc49 PB |
209 | .SH BUGS |
210 | In glibc before version 2.7, seeking past the end of a stream created by | |
211 | .BR open_memstream () | |
212 | does not enlarge the buffer; instead the | |
0b80cf56 | 213 | .BR fseek (3) |
28c1dc49 PB |
214 | call fails, returning \-1. |
215 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996 | |
84133057 | 216 | |
8154f292 MK |
217 | If |
218 | .I size | |
219 | is specified as zero, | |
220 | .BR fmemopen () | |
221 | fails with the error | |
222 | .BR EINVAL . | |
223 | .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=11216 | |
224 | It would be more consistent if this case successfully created | |
225 | a stream that then returned end of file on the first attempt at reading. | |
226 | Furthermore, POSIX.1-2008 does not specify a failure for this case. | |
227 | ||
8f60b371 MK |
228 | Specifying append mode ("a" or "a+") for |
229 | .BR fmemopen () | |
230 | sets the initial file position to the first null byte, but | |
231 | .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=13152 | |
232 | (if the file offset is reset to a location other than | |
233 | the end of the stream) | |
234 | does not force subsequent writes to append at the end of the stream. | |
235 | ||
84133057 MK |
236 | The glibc 2.9 addition of "binary" mode for |
237 | .BR fmemopen () | |
238 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544 | |
239 | silently changed the ABI: previously, | |
240 | .BR fmemopen () | |
241 | ignored \(aqb\(aq in | |
242 | .IR mode . | |
86cfe9cb | 243 | .SH "EXAMPLE" |
c13182ef | 244 | The program below uses |
86cfe9cb MK |
245 | .BR fmemopen () |
246 | to open an input buffer, and | |
247 | .BR open_memstream () | |
248 | to open a dynamically sized output buffer. | |
249 | The program scans its input string (taken from the program's | |
250 | first command-line argument) reading integers, | |
251 | and writes the squares of these integers to the output buffer. | |
89c9a314 | 252 | An example of the output produced by this program is the following: |
54973458 | 253 | .in +4n |
86cfe9cb MK |
254 | .nf |
255 | ||
b43a3b30 | 256 | .RB "$" " ./a.out \(aq1 23 43\(aq" |
86cfe9cb | 257 | size=11; ptr=1 529 1849 |
54973458 MK |
258 | .fi |
259 | .in | |
9c330504 | 260 | .SS Program source |
d84d0300 | 261 | \& |
54973458 | 262 | .nf |
86cfe9cb | 263 | #define _GNU_SOURCE |
86cfe9cb MK |
264 | #include <string.h> |
265 | #include <stdio.h> | |
266 | #include <stdlib.h> | |
267 | ||
6a578b88 MK |
268 | #define handle_error(msg) \\ |
269 | do { perror(msg); exit(EXIT_FAILURE); } while (0) | |
d3b5ab82 | 270 | |
c13182ef | 271 | int |
cf0a9ace | 272 | main(int argc, char *argv[]) |
86cfe9cb MK |
273 | { |
274 | FILE *out, *in; | |
275 | int v, s; | |
276 | size_t size; | |
277 | char *ptr; | |
278 | ||
6b34fb3f MK |
279 | if (argc != 2) { |
280 | fprintf(stderr, "Usage: %s <file>\\n", argv[0]); | |
281 | exit(EXIT_FAILURE); | |
282 | } | |
86cfe9cb MK |
283 | |
284 | in = fmemopen(argv[1], strlen(argv[1]), "r"); | |
d3b5ab82 | 285 | if (in == NULL) |
6a578b88 | 286 | handle_error("fmemopen"); |
86cfe9cb MK |
287 | |
288 | out = open_memstream(&ptr, &size); | |
d3b5ab82 | 289 | if (out == NULL) |
84112433 | 290 | handle_error("open_memstream"); |
86cfe9cb MK |
291 | |
292 | for (;;) { | |
293 | s = fscanf(in, "%d", &v); | |
294 | if (s <= 0) | |
295 | break; | |
296 | ||
297 | s = fprintf(out, "%d ", v * v); | |
29059a65 | 298 | if (s == \-1) |
6a578b88 | 299 | handle_error("fprintf"); |
86cfe9cb MK |
300 | } |
301 | fclose(in); | |
302 | fclose(out); | |
303 | printf("size=%ld; ptr=%s\\n", (long) size, ptr); | |
304 | free(ptr); | |
305 | exit(EXIT_SUCCESS); | |
306 | } | |
307 | .fi | |
86cfe9cb | 308 | .SH "SEE ALSO" |
a5dbb527 | 309 | .BR fopen (3), |
0a4f8b7b | 310 | .BR fopencookie (3) |