1 .\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .TH FMEMOPEN 3 2021-03-22 "GNU" "Linux Programmer's Manual"
7 fmemopen \- open memory as stream
10 .RI ( libc ", " \-lc )
15 .BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"
19 Feature Test Macro Requirements for glibc (see
20 .BR feature_test_macros (7)):
26 _POSIX_C_SOURCE >= 200809L
33 function opens a stream that permits the access specified by
35 The stream allows I/O to be performed on the string or memory buffer
41 argument specifies the semantics of I/O on the stream,
42 and is one of the following:
45 The stream is opened for reading.
48 The stream is opened for writing.
51 Append; open the stream for writing,
52 with the initial buffer position set to the first null byte.
55 Open the stream for reading and writing.
58 Open the stream for reading and writing.
59 The buffer contents are truncated
60 (i.e., \(aq\e0\(aq is placed in the first byte of the buffer).
63 Append; open the stream for reading and writing,
64 with the initial buffer position set to the first null byte.
66 The stream maintains the notion of a current position,
67 the location where the next I/O operation will be performed.
68 The current position is implicitly updated by I/O operations.
69 It can be explicitly updated using
73 In all modes other than append,
74 the initial position is set to the start of the buffer.
75 In append mode, if no null byte is found within the buffer,
76 then the initial position is
81 is specified as NULL, then
86 This is useful for an application that wants to write data to
87 a temporary buffer and then read it back again.
88 The initial position is set to the start of the buffer.
89 The buffer is automatically freed when the stream is closed.
90 Note that the caller has no way to obtain a pointer to the
91 temporary buffer allocated by this call (but see
92 .BR open_memstream (3)).
96 is not NULL, then it should point to a buffer of at least
98 bytes allocated by the caller.
100 When a stream that has been opened for writing is flushed
104 a null byte is written at the end of the buffer if there is space.
105 The caller should ensure that an extra byte is available in the
112 In a stream opened for reading,
113 null bytes (\(aq\e0\(aq) in the buffer do not cause read
114 operations to return an end-of-file indication.
115 A read from the buffer will indicate end-of-file
116 only when the current buffer position advances
118 bytes past the start of the buffer.
120 Write operations take place either at the current position
121 (for modes other than append), or at the current size of the stream
124 Attempts to write more than
126 bytes to the buffer result in an error.
127 By default, such errors will be visible
128 (by the absence of data) only when the
131 Disabling buffering with the following call
132 may be useful to detect errors at the time of an output operation:
136 setbuf(stream, NULL);
140 Upon successful completion,
145 Otherwise, NULL is returned and
147 is set to indicate the error.
150 was already available in glibc 1.0.x.
152 For an explanation of the terms used in this section, see
160 Interface Attribute Value
163 T} Thread safety MT-Safe
170 This function is not specified in POSIX.1-2001,
171 and is not widely available on other systems.
173 POSIX.1-2008 specifies that \(aqb\(aq in
176 However, Technical Corrigendum 1
177 .\" http://austingroupbugs.net/view.php?id=396
178 adjusts the standard to allow implementation-specific treatment for this case,
179 thus permitting the glibc treatment of \(aqb\(aq.
181 There is no file descriptor associated with the file stream
182 returned by this function
185 will return an error if called on the returned stream).
187 With version 2.22, binary mode (see below) was removed,
188 many longstanding bugs in the implementation of
190 were fixed, and a new versioned symbol was created for this interface.
193 From version 2.9 to 2.21, the glibc implementation of
195 supported a "binary" mode,
196 enabled by specifying the letter \(aqb\(aq as the second character in
199 writes don't implicitly add a terminating null byte, and
202 is relative to the end of the buffer (i.e., the value specified by the
204 argument), rather than the current string length.
206 An API bug afflicted the implementation of binary mode:
207 to specify binary mode, the \(aqb\(aq must be the
211 Thus, for example, "wb+" has the desired effect, but "w+b" does not.
212 This is inconsistent with the treatment of
213 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12836
218 Binary mode was removed in glibc 2.22; a \(aqb\(aq specified in
222 In versions of glibc before 2.22, if
224 is specified as zero,
228 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=11216
229 It would be more consistent if this case successfully created
230 a stream that then returned end-of-file on the first attempt at reading;
231 since version 2.22, the glibc implementation provides that behavior.
233 In versions of glibc before 2.22,
234 specifying append mode ("a" or "a+") for
236 sets the initial buffer position to the first null byte, but
237 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=13152
238 (if the current position is reset to a location other than
239 the end of the stream)
240 does not force subsequent writes to append at the end of the stream.
241 This bug is fixed in glibc 2.22.
243 In versions of glibc before 2.22, if the
247 specifies append ("a" or "a+"), and the
249 argument does not cover a null byte in
251 then, according to POSIX.1-2008,
252 the initial buffer position should be set to
253 the next byte after the end of the buffer.
254 However, in this case the glibc
255 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=13151
257 sets the buffer position to \-1.
258 This bug is fixed in glibc 2.22.
260 In versions of glibc before 2.22,
261 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292
268 was performed on a stream created by
274 from the end-of-stream position, instead of being added.
275 This bug is fixed in glibc 2.22.
277 The glibc 2.9 addition of "binary" mode for
279 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
280 silently changed the ABI: previously,
285 The program below uses
287 to open an input buffer, and
288 .BR open_memstream (3)
289 to open a dynamically sized output buffer.
290 The program scans its input string (taken from the program's
291 first command-line argument) reading integers,
292 and writes the squares of these integers to the output buffer.
293 An example of the output produced by this program is the following:
297 .RB "$" " ./a.out \(aq1 23 43\(aq"
298 size=11; ptr=1 529 1849
309 #define handle_error(msg) \e
310 do { perror(msg); exit(EXIT_FAILURE); } while (0)
313 main(int argc, char *argv[])
321 fprintf(stderr, "Usage: %s \(aq<num>...\(aq\en", argv[0]);
325 in = fmemopen(argv[1], strlen(argv[1]), "r");
327 handle_error("fmemopen");
329 out = open_memstream(&ptr, &size);
331 handle_error("open_memstream");
334 s = fscanf(in, "%d", &v);
338 s = fprintf(out, "%d ", v * v);
340 handle_error("fprintf");
346 printf("size=%zu; ptr=%s\en", size, ptr);
355 .BR open_memstream (3)