1FMEMOPEN(3P) POSIX Programmer's Manual FMEMOPEN(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 fmemopen — open a memory buffer stream
13
15 #include <stdio.h>
16 FILE *fmemopen(void *restrict buf, size_t size,
18 const char *restrict mode);
19
21 The fmemopen() function shall associate the buffer given by the buf and
22 size arguments with a stream. The buf argument shall be either a null
23 pointer or point to a buffer that is at least size bytes long.
24 The mode argument points to a string. If the string is one of the fol‐
26 lowing, the stream shall be opened in the indicated mode. Otherwise,
27 the behavior is undefined.
28 r Open the stream for reading.
30 w Open the stream for writing.
32 a Append; open the stream for writing at the first null byte.
34 r+ Open the stream for update (reading and writing).
36 w+ Open the stream for update (reading and writing). Truncate the
38 buffer contents.
39 a+ Append; open the stream for update (reading and writing); the
41 initial position is at the first null byte.
42 Implementations shall accept all mode strings allowed by fopen(), but
44 the use of the character 'b' shall produce implementation-defined
45 results, where the resulting FILE * need not behave the same as if 'b'
46 were omitted.
47 If a null pointer is specified as the buf argument, fmemopen() shall
49 allocate size bytes of memory as if by a call to malloc(). This buffer
50 shall be automatically freed when the stream is closed. Because this
51 feature is only useful when the stream is opened for updating (because
52 there is no way to get a pointer to the buffer) the fmemopen() call may
53 fail if the mode argument does not include a '+'.
54 The stream shall maintain a current position in the buffer. This posi‐
56 tion shall be initially set to either the beginning of the buffer (for
57 r and w modes) or to the first null byte in the buffer (for a modes).
58 If no null byte is found in append mode, the initial position shall be
59 set to one byte after the end of the buffer.
60 If buf is a null pointer, the initial position shall always be set to
62 the beginning of the buffer.
63 The stream shall also maintain the size of the current buffer contents;
65 use of fseek() or fseeko() on the stream with SEEK_END shall seek rela‐
66 tive to this size. For modes r and r+ the size shall be set to the
67 value given by the size argument. For modes w and w+ the initial size
68 shall be zero and for modes a and a+ the initial size shall be:
69 * Zero, if buf is a null pointer
71 * The position of the first null byte in the buffer, if one is found
73 * The value of the size argument, if buf is not a null pointer and no
75 null byte is found
76 A read operation on the stream shall not advance the current buffer
78 position beyond the current buffer size. Reaching the buffer size in a
79 read operation shall count as ``end-of-file''. Null bytes in the buffer
80 shall have no special meaning for reads. The read operation shall start
81 at the current buffer position of the stream.
82 A write operation shall start either at the current position of the
84 stream (if mode has not specified 'a' as the first character) or at the
85 current size of the stream (if mode had 'a' as the first character). If
86 the current position at the end of the write is larger than the current
87 buffer size, the current buffer size shall be set to the current posi‐
88 tion. A write operation on the stream shall not advance the current
89 buffer size beyond the size given in the size argument.
90 When a stream open for writing is flushed or closed, a null byte shall
92 be written at the current position or at the end of the buffer, depend‐
93 ing on the size of the contents. If a stream open for update is flushed
94 or closed and the last write has advanced the current buffer size, a
95 null byte shall be written at the end of the buffer if it fits.
96 An attempt to seek a memory buffer stream to a negative position or to
98 a position larger than the buffer size given in the size argument shall
99 fail.
100
102 Upon successful completion, fmemopen() shall return a pointer to the
103 object controlling the stream. Otherwise, a null pointer shall be
104 returned, and errno shall be set to indicate the error.
105
107 The fmemopen() function shall fail if:
108 EMFILE {STREAM_MAX} streams are currently open in the calling process.
110 The fmemopen() function may fail if:
112 EINVAL The value of the mode argument is not valid.
114 EINVAL The buf argument is a null pointer and the mode argument does
116 not include a '+' character.
117 EINVAL The size argument specifies a buffer size of zero and the imple‐
119 mentation does not support this.
120 ENOMEM The buf argument is a null pointer and the allocation of a buf‐
122 fer of length size has failed.
123 EMFILE {FOPEN_MAX} streams are currently open in the calling process.
125 The following sections are informative.
127
129 #include <stdio.h>
130 #include <string.h>
131 static char buffer[] = "foobar";
133 int
135 main (void)
136 {
137 int ch;
138 FILE *stream;
139 stream = fmemopen(buffer, strlen (buffer), "r");
141 if (stream == NULL)
142 /* handle error */;
143 while ((ch = fgetc(stream)) != EOF)
145 printf("Got %c\n", ch);
146 fclose(stream);
148 return (0);
149 }
150 This program produces the following output:
152 Got f
155 Got o
156 Got o
157 Got b
158 Got a
159 Got r
160
162 None.
163
165 This interface has been introduced to eliminate many of the errors
166 encountered in the construction of strings, notably overflowing of
167 strings. This interface prevents overflow.
168
170 A future version of this standard may mandate specific behavior when
171 the mode argument includes 'b'.
172 A future version of this standard may require support of zero-length
174 buffer streams explicitly.
175
177 fdopen(), fopen(), freopen(), fseek(), malloc(), open_memstream()
178 The Base Definitions volume of POSIX.1‐2017, <stdio.h>
180
182 Portions of this text are reprinted and reproduced in electronic form
183 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
184 table Operating System Interface (POSIX), The Open Group Base Specifi‐
185 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
186 Electrical and Electronics Engineers, Inc and The Open Group. In the
187 event of any discrepancy between this version and the original IEEE and
188 The Open Group Standard, the original IEEE and The Open Group Standard
189 is the referee document. The original Standard can be obtained online
190 at http://www.opengroup.org/unix/online.html .
191 Any typographical or formatting errors that appear in this page are
193 most likely to have been introduced during the conversion of the source
194 files to man page format. To report such errors, see https://www.ker‐
195 nel.org/doc/man-pages/reporting_bugs.html .
196IEEE/The Open Group 2017 FMEMOPEN(3P)