1 .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
2 .\" and Copyright 2005, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
5 .\" Distributed under the GPL.
8 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
10 .TH FMEMOPEN 3 2014-04-06 "GNU" "Linux Programmer's Manual"
12 fmemopen, open_memstream, open_wmemstream \- open memory as stream
17 .BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"
19 .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
23 .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
27 Feature Test Macro Requirements for glibc (see
28 .BR feature_test_macros (7)):
32 .BR open_memstream (),
33 .BR open_wmemstream ():
39 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
49 function opens a stream that permits the access specified by
51 The stream allows I/O to be performed on the string or memory buffer
54 This buffer must be at least
64 specifies an append mode, then the initial file position is set to
65 the location of the first null byte (\(aq\\0\(aq) in the buffer;
66 otherwise the initial file position is set to the start of the buffer.
68 the letter \(aqb\(aq may be specified as the second character in
70 This provides "binary" mode:
71 writes don't implicitly add a terminating null byte, and
74 is relative to the end of the buffer (i.e., the value specified by the
76 argument), rather than the current string length.
78 When a stream that has been opened for writing is flushed
82 a null byte is written at the end of the buffer if there is space.
83 The caller should ensure that an extra byte is available in the
90 Attempts to write more than
92 bytes to the buffer result in an error.
93 (By default, such errors will be visible only when the
96 Disabling buffering with the following call
97 may be useful to detect errors at the time of an output operation:
99 setbuf(stdream, NULL);
101 Alternatively, the caller can explicitly set
103 as the stdio stream buffer, at the same time informing stdio
104 of the buffer's size, using:
106 setbuffer(stream, buf, size);
108 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
110 .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
112 In a stream opened for reading,
113 null bytes (\(aq\\0\(aq) in the buffer do not cause read
114 operations to return an end-of-file indication.
115 A read from the buffer will only indicate end-of-file
116 when the file pointer advances
118 bytes past the start of the buffer.
122 is specified as NULL, then
124 dynamically allocates a buffer
127 This is useful for an application that wants to write data to
128 a temporary buffer and then read it back again.
129 The buffer is automatically freed when the stream is closed.
130 Note that the caller has no way to obtain a pointer to the
131 temporary buffer allocated by this call (but see
132 .BR open_memstream ()
136 .BR open_memstream ()
137 function opens a stream for writing to a buffer.
139 is dynamically allocated (as with
141 and automatically grows as required.
142 After closing the stream, the caller should
146 When the stream is closed
150 the locations pointed to by
154 are updated to contain, respectively, a pointer to the buffer and the
155 current size of the buffer.
156 These values remain valid only as long as the caller
157 performs no further output on the stream.
158 If further output is performed, then the stream
159 must again be flushed before trying to access these variables.
161 A null byte is maintained at the end of the buffer.
164 included in the size value stored at
167 The stream's file position can be changed with
171 Moving the file position past the end
172 of the data already written fills the intervening space with
176 .BR open_wmemstream ()
178 .BR open_memstream (),
179 but operates on wide characters instead of bytes.
181 Upon successful completion
183 .BR open_memstream ()
185 .BR open_wmemstream ()
189 Otherwise, NULL is returned and
191 is set to indicate the error.
195 .BR open_memstream ()
196 were already available in glibc 1.0.x.
197 .BR open_wmemstream ()
198 is available since glibc 2.4.
201 These functions are not specified in POSIX.1-2001,
202 and are not widely available on other systems.
204 POSIX.1-2008 specifies that \(aqb\(aq in
207 However, Technical Corrigendum 1
208 .\" http://austingroupbugs.net/view.php?id=396
209 adjusts the standard to allow implementation-specific treatment for this case,
210 thus permitting the glibc treatment of \(aqb\(aq.
212 There is no file descriptor associated with the file stream
213 returned by these functions
216 will return an error if called on the returned stream).
218 In glibc before version 2.7, seeking past the end of a stream created by
219 .BR open_memstream ()
220 does not enlarge the buffer; instead the
222 call fails, returning \-1.
223 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
227 is specified as zero,
231 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=11216
232 It would be more consistent if this case successfully created
233 a stream that then returned end of file on the first attempt at reading.
234 Furthermore, POSIX.1-2008 does not specify a failure for this case.
236 Specifying append mode ("a" or "a+") for
238 sets the initial file position to the first null byte, but
239 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13152
240 (if the file offset is reset to a location other than
241 the end of the stream)
242 does not force subsequent writes to append at the end of the stream.
248 specifies append ("a" or "a+"), and the
250 argument does not cover a null byte in
252 then, according to POSIX.1-2008,
253 the initial file position should be set to
254 the next byte after the end of the buffer.
255 However, in this case the glibc
256 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13151
258 sets the file position to \-1.
260 To specify binary mode for
262 the \(aqb\(aq must be the
266 Thus, for example, "wb+" has the desired effect, but "w+b" does not.
267 This is inconsistent with the treatment of
268 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12836
273 The glibc 2.9 addition of "binary" mode for
275 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
276 silently changed the ABI: previously,
281 The program below uses
283 to open an input buffer, and
284 .BR open_memstream ()
285 to open a dynamically sized output buffer.
286 The program scans its input string (taken from the program's
287 first command-line argument) reading integers,
288 and writes the squares of these integers to the output buffer.
289 An example of the output produced by this program is the following:
293 .RB "$" " ./a.out \(aq1 23 43\(aq"
294 size=11; ptr=1 529 1849
305 #define handle_error(msg) \\
306 do { perror(msg); exit(EXIT_FAILURE); } while (0)
309 main(int argc, char *argv[])
317 fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
321 in = fmemopen(argv[1], strlen(argv[1]), "r");
323 handle_error("fmemopen");
325 out = open_memstream(&ptr, &size);
327 handle_error("open_memstream");
330 s = fscanf(in, "%d", &v);
334 s = fprintf(out, "%d ", v * v);
336 handle_error("fprintf");
340 printf("size=%zu; ptr=%s\\n", size, ptr);