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
13 fmemopen — open a memory buffer stream
14
16 #include <stdio.h>
17 FILE *fmemopen(void *restrict buf, size_t size,
19 const char *restrict mode);
20
22 The fmemopen() function shall associate the buffer given by the buf and
23 size arguments with a stream. The buf argument shall be either a null
24 pointer or point to a buffer that is at least size bytes long.
25 The mode argument points to a string. If the string is one of the fol‐
27 lowing, the stream shall be opened in the indicated mode. Otherwise,
28 the behavior is undefined.
29 r Open the stream for reading.
31 w Open the stream for writing.
33 a Append; open the stream for writing at the first null byte.
35 r+ Open the stream for update (reading and writing).
37 w+ Open the stream for update (reading and writing). Truncate the
39 buffer contents.
40 a+ Append; open the stream for update (reading and writing); the
42 initial position is at the first null byte.
43 Implementations shall accept all mode strings allowed by fopen(), but
45 the use of the character 'b' shall produce implementation-defined
46 results, where the resulting FILE * need not behave the same as if 'b'
47 were omitted.
48 If a null pointer is specified as the buf argument, fmemopen() shall
50 allocate size bytes of memory as if by a call to malloc(). This buffer
51 shall be automatically freed when the stream is closed. Because this
52 feature is only useful when the stream is opened for updating (because
53 there is no way to get a pointer to the buffer) the fmemopen() call may
54 fail if the mode argument does not include a '+'.
55 The stream shall maintain a current position in the buffer. This posi‐
57 tion shall be initially set to either the beginning of the buffer (for
58 r and w modes) or to the first null byte in the buffer (for a modes).
59 If no null byte is found in append mode, the initial position shall be
60 set to one byte after the end of the buffer.
61 If buf is a null pointer, the initial position shall always be set to
63 the beginning of the buffer.
64 The stream shall also maintain the size of the current buffer contents;
66 use of fseek() or fseeko() on the stream with SEEK_END shall seek rela‐
67 tive to this size. For modes r and r+ the size shall be set to the
68 value given by the size argument. For modes w and w+ the initial size
69 shall be zero and for modes a and a+ the initial size shall be either
70 the position of the first null byte in the buffer or the value of the
71 size argument if no null byte is found.
72 A read operation on the stream shall not advance the current buffer
74 position beyond the current buffer size. Reaching the buffer size in a
75 read operation shall count as ``end-of-file''. Null bytes in the buffer
76 shall have no special meaning for reads. The read operation shall start
77 at the current buffer position of the stream.
78 A write operation shall start either at the current position of the
80 stream (if mode has not specified 'a' as the first character) or at the
81 current size of the stream (if mode had 'a' as the first character). If
82 the current position at the end of the write is larger than the current
83 buffer size, the current buffer size shall be set to the current posi‐
84 tion. A write operation on the stream shall not advance the current
85 buffer size beyond the size given in the size argument.
86 When a stream open for writing is flushed or closed, a null byte shall
88 be written at the current position or at the end of the buffer, depend‐
89 ing on the size of the contents. If a stream open for update is flushed
90 or closed and the last write has advanced the current buffer size, a
91 null byte shall be written at the end of the buffer if it fits.
92 An attempt to seek a memory buffer stream to a negative position or to
94 a position larger than the buffer size given in the size argument shall
95 fail.
96
98 Upon successful completion, fmemopen() shall return a pointer to the
99 object controlling the stream. Otherwise, a null pointer shall be
100 returned, and errno shall be set to indicate the error.
101
103 The fmemopen() function shall fail if:
104 EINVAL The size argument specifies a buffer size of zero.
106 The fmemopen() function may fail if:
108 EINVAL The value of the mode argument is not valid.
110 EINVAL The buf argument is a null pointer and the mode argument does
112 not include a '+' character.
113 ENOMEM The buf argument is a null pointer and the allocation of a buf‐
115 fer of length size has failed.
116 EMFILE {FOPEN_MAX} streams are currently open in the calling process.
118 The following sections are informative.
120
122 #include <stdio.h>
123 #include <string.h>
124 static char buffer[] = "foobar";
126 int
128 main (void)
129 {
130 int ch;
131 FILE *stream;
132 stream = fmemopen(buffer, strlen (buffer), "r");
134 if (stream == NULL)
135 /* handle error */;
136 while ((ch = fgetc(stream)) != EOF)
138 printf("Got %c\n", ch);
139 fclose(stream);
141 return (0);
142 }
143 This program produces the following output:
145 Got f
147 Got o
148 Got o
149 Got b
150 Got a
151 Got r
152
154 None.
155
157 This interface has been introduced to eliminate many of the errors
158 encountered in the construction of strings, notably overflowing of
159 strings. This interface prevents overflow.
160
162 A future revision of this standard may mandate specific behavior when
163 the mode argument includes 'b'.
164
166 fdopen(), fopen(), freopen(), fseek(), malloc(), open_memstream()
167 The Base Definitions volume of POSIX.1‐2008, <stdio.h>
169
171 Portions of this text are reprinted and reproduced in electronic form
172 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
173 -- Portable Operating System Interface (POSIX), The Open Group Base
174 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
175 cal and Electronics Engineers, Inc and The Open Group. (This is
176 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
177 event of any discrepancy between this version and the original IEEE and
178 The Open Group Standard, the original IEEE and The Open Group Standard
179 is the referee document. The original Standard can be obtained online
180 at http://www.unix.org/online.html .
181 Any typographical or formatting errors that appear in this page are
183 most likely to have been introduced during the conversion of the source
184 files to man page format. To report such errors, see https://www.ker‐
185 nel.org/doc/man-pages/reporting_bugs.html .
186IEEE/The Open Group 2013 FMEMOPEN(3P)