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
98 may be useful to detect errors at the time of an output operation.
99 Alternatively, the caller can explicitly set
101 as the stdio stream buffer, at the same time informing stdio
102 of the buffer's size, using
103 .IR "setbuffer(fp, buf, size)" .)
104 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
106 .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
108 In a stream opened for reading,
109 null bytes (\(aq\\0\(aq) in the buffer do not cause read
110 operations to return an end-of-file indication.
111 A read from the buffer will only indicate end-of-file
112 when the file pointer advances
114 bytes past the start of the buffer.
118 is specified as NULL, then
120 dynamically allocates a buffer
123 This is useful for an application that wants to write data to
124 a temporary buffer and then read it back again.
125 The buffer is automatically freed when the stream is closed.
126 Note that the caller has no way to obtain a pointer to the
127 temporary buffer allocated by this call (but see
128 .BR open_memstream ()
132 .BR open_memstream ()
133 function opens a stream for writing to a buffer.
135 is dynamically allocated (as with
137 and automatically grows as required.
138 After closing the stream, the caller should
142 When the stream is closed
146 the locations pointed to by
150 are updated to contain, respectively, a pointer to the buffer and the
151 current size of the buffer.
152 These values remain valid only as long as the caller
153 performs no further output on the stream.
154 If further output is performed, then the stream
155 must again be flushed before trying to access these variables.
157 A null byte is maintained at the end of the buffer.
160 included in the size value stored at
163 The stream's file position can be changed with
167 Moving the file position past the end
168 of the data already written fills the intervening space with
172 .BR open_wmemstream ()
174 .BR open_memstream (),
175 but operates on wide characters instead of bytes.
177 Upon successful completion
179 .BR open_memstream ()
181 .BR open_wmemstream ()
185 Otherwise, NULL is returned and
187 is set to indicate the error.
191 .BR open_memstream ()
192 were already available in glibc 1.0.x.
193 .BR open_wmemstream ()
194 is available since glibc 2.4.
197 These functions are not specified in POSIX.1-2001,
198 and are not widely available on other systems.
200 POSIX.1-2008 specifies that \(aqb\(aq in
203 However, Technical Corrigendum 1
204 .\" http://austingroupbugs.net/view.php?id=396
205 adjusts the standard to allow implementation-specific treatment for this case,
206 thus permitting the glibc treatment of \(aqb\(aq.
208 There is no file descriptor associated with the file stream
209 returned by these functions
212 will return an error if called on the returned stream).
214 In glibc before version 2.7, seeking past the end of a stream created by
215 .BR open_memstream ()
216 does not enlarge the buffer; instead the
218 call fails, returning \-1.
219 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
223 is specified as zero,
227 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=11216
228 It would be more consistent if this case successfully created
229 a stream that then returned end of file on the first attempt at reading.
230 Furthermore, POSIX.1-2008 does not specify a failure for this case.
232 Specifying append mode ("a" or "a+") for
234 sets the initial file position to the first null byte, but
235 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13152
236 (if the file offset is reset to a location other than
237 the end of the stream)
238 does not force subsequent writes to append at the end of the stream.
244 specifies append ("a" or "a+"), and the
246 argument does not cover a null byte in
248 then, according to POSIX.1-2008,
249 the initial file position should be set to
250 the next byte after the end of the buffer.
251 However, in this case the glibc
252 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13151
254 sets the file position to \-1.
256 To specify binary mode for
258 the \(aqb\(aq must be the
262 Thus, for example, "wb+" has the desired effect, but "w+b" does not.
263 This is inconsistent with the treatment of
264 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12836
269 The glibc 2.9 addition of "binary" mode for
271 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
272 silently changed the ABI: previously,
277 The program below uses
279 to open an input buffer, and
280 .BR open_memstream ()
281 to open a dynamically sized output buffer.
282 The program scans its input string (taken from the program's
283 first command-line argument) reading integers,
284 and writes the squares of these integers to the output buffer.
285 An example of the output produced by this program is the following:
289 .RB "$" " ./a.out \(aq1 23 43\(aq"
290 size=11; ptr=1 529 1849
301 #define handle_error(msg) \\
302 do { perror(msg); exit(EXIT_FAILURE); } while (0)
305 main(int argc, char *argv[])
313 fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
317 in = fmemopen(argv[1], strlen(argv[1]), "r");
319 handle_error("fmemopen");
321 out = open_memstream(&ptr, &size);
323 handle_error("open_memstream");
326 s = fscanf(in, "%d", &v);
330 s = fprintf(out, "%d ", v * v);
332 handle_error("fprintf");
336 printf("size=%zu; ptr=%s\\n", size, ptr);