1FMEMOPEN(3)                Linux Programmer's Manual               FMEMOPEN(3)
2
3
4

NAME

6       fmemopen -  open memory as stream
7

SYNOPSIS

9       #include <stdio.h>
10
11       FILE *fmemopen(void *buf, size_t size, const char *mode);
12
13   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14
15       fmemopen():
16           Since glibc 2.10:
17               _POSIX_C_SOURCE >= 200809L
18           Before glibc 2.10:
19               _GNU_SOURCE
20

DESCRIPTION

22       The  fmemopen()  function opens a stream that permits the access speci‐
23       fied by mode.  The stream allows I/O to be performed on the  string  or
24       memory buffer pointed to by buf.
25
26       The  mode argument specifies the semantics of I/O on the stream, and is
27       one of the following:
28
29       r      The stream is opened for reading.
30
31       w      The stream is opened for writing.
32
33       a      Append; open the stream for writing, with the initial buffer po‐
34              sition set to the first null byte.
35
36       r+     Open the stream for reading and writing.
37
38       w+     Open  the  stream  for reading and writing.  The buffer contents
39              are truncated (i.e., '\0' is placed in the  first  byte  of  the
40              buffer).
41
42       a+     Append;  open  the stream for reading and writing, with the ini‐
43              tial buffer position set to the first null byte.
44
45       The stream maintains the notion of a  current  position,  the  location
46       where  the  next I/O operation will be performed.  The current position
47       is implicitly updated by I/O operations.  It can be explicitly  updated
48       using fseek(3), and determined using ftell(3).  In all modes other than
49       append, the initial position is set to the start of the buffer.  In ap‐
50       pend mode, if no null byte is found within the buffer, then the initial
51       position is size+1.
52
53       If buf is specified as NULL, then fmemopen() allocates a buffer of size
54       bytes.  This is useful for an application that wants to write data to a
55       temporary buffer and then read it back again.  The initial position  is
56       set to the start of the buffer.  The buffer is automatically freed when
57       the stream is closed.  Note that the caller has  no  way  to  obtain  a
58       pointer  to  the  temporary  buffer  allocated  by  this  call (but see
59       open_memstream(3)).
60
61       If buf is not NULL, then it should point to a buffer of  at  least  len
62       bytes allocated by the caller.
63
64       When  a  stream that has been opened for writing is flushed (fflush(3))
65       or closed (fclose(3)), a null byte is written at the end of the  buffer
66       if  there  is  space.   The  caller should ensure that an extra byte is
67       available in the buffer (and that size counts that byte) to  allow  for
68       this.
69
70       In  a stream opened for reading, null bytes ('\0') in the buffer do not
71       cause read operations to return an end-of-file indication.  A read from
72       the buffer will indicate end-of-file only when the current buffer posi‐
73       tion advances size bytes past the start of the buffer.
74
75       Write operations take place either at the current position  (for  modes
76       other  than  append),  or at the current size of the stream (for append
77       modes).
78
79       Attempts to write more than size bytes to the buffer result in  an  er‐
80       ror.   By default, such errors will be visible (by the absence of data)
81       only when the stdio buffer is flushed.  Disabling  buffering  with  the
82       following  call may be useful to detect errors at the time of an output
83       operation:
84
85           setbuf(stream, NULL);
86

RETURN VALUE

88       Upon successful completion, fmemopen() returns a FILE pointer.   Other‐
89       wise, NULL is returned and errno is set to indicate the error.
90

VERSIONS

92       fmemopen() was already available in glibc 1.0.x.
93

ATTRIBUTES

95       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
96       tributes(7).
97
98       ┌────────────────────────────────────────────┬───────────────┬─────────┐
99Interface                                   Attribute     Value   
100       ├────────────────────────────────────────────┼───────────────┼─────────┤
101fmemopen(),                                 │ Thread safety │ MT-Safe │
102       └────────────────────────────────────────────┴───────────────┴─────────┘
103

CONFORMING TO

105       POSIX.1-2008.  This function is not specified in POSIX.1-2001,  and  is
106       not widely available on other systems.
107
108       POSIX.1-2008  specifies  that  'b'  in mode shall be ignored.  However,
109       Technical Corrigendum 1 adjusts the standard to  allow  implementation-
110       specific  treatment  for this case, thus permitting the glibc treatment
111       of 'b'.
112

NOTES

114       There is no file descriptor associated with the file stream returned by
115       this  function  (i.e.,  fileno(3) will return an error if called on the
116       returned stream).
117
118       With version 2.22, binary mode (see below) was removed, many longstand‐
119       ing bugs in the implementation of fmemopen() were fixed, and a new ver‐
120       sioned symbol was created for this interface.
121
122   Binary mode
123       From version 2.9 to 2.21, the glibc implementation of  fmemopen()  sup‐
124       ported  a  "binary"  mode,  enabled by specifying the letter 'b' as the
125       second character in mode.  In this mode, writes don't implicitly add  a
126       terminating  null byte, and fseek(3) SEEK_END is relative to the end of
127       the buffer (i.e., the value specified by  the  size  argument),  rather
128       than the current string length.
129
130       An  API bug afflicted the implementation of binary mode: to specify bi‐
131       nary mode, the 'b' must be the second character in mode.  Thus, for ex‐
132       ample,  "wb+"  has the desired effect, but "w+b" does not.  This is in‐
133       consistent with the treatment of mode by fopen(3).
134
135       Binary mode was removed in glibc 2.22; a 'b' specified in mode  has  no
136       effect.
137

BUGS

139       In  versions of glibc before 2.22, if size is specified as zero, fmemo‐
140       pen() fails with the error EINVAL.  It would be more consistent if this
141       case  successfully  created  a stream that then returned end-of-file on
142       the first attempt at reading; since version 2.22, the glibc implementa‐
143       tion provides that behavior.
144
145       In  versions of glibc before 2.22, specifying append mode ("a" or "a+")
146       for fmemopen() sets the initial buffer position to the first null byte,
147       but  (if the current position is reset to a location other than the end
148       of the stream) does not force subsequent writes to append at the end of
149       the stream.  This bug is fixed in glibc 2.22.
150
151       In  versions  of  glibc before 2.22, if the mode argument to fmemopen()
152       specifies append ("a" or "a+"), and the size argument does not cover  a
153       null  byte  in buf, then, according to POSIX.1-2008, the initial buffer
154       position should be set to the next byte after the end  of  the  buffer.
155       However,  in this case the glibc fmemopen() sets the buffer position to
156       -1.  This bug is fixed in glibc 2.22.
157
158       In versions of glibc before 2.22, when a call to fseek(3) with a whence
159       value  of SEEK_END was performed on a stream created by fmemopen(), the
160       offset was subtracted from the end-of-stream position, instead of being
161       added.  This bug is fixed in glibc 2.22.
162
163       The glibc 2.9 addition of "binary" mode for fmemopen() silently changed
164       the ABI: previously, fmemopen() ignored 'b' in mode.
165

EXAMPLES

167       The program  below  uses  fmemopen()  to  open  an  input  buffer,  and
168       open_memstream(3)  to open a dynamically sized output buffer.  The pro‐
169       gram scans its input string (taken from the  program's  first  command-
170       line  argument) reading integers, and writes the squares of these inte‐
171       gers to the output buffer.  An example of the output produced  by  this
172       program is the following:
173
174           $ ./a.out '1 23 43'
175           size=11; ptr=1 529 1849
176
177   Program source
178
179       #define _GNU_SOURCE
180       #include <string.h>
181       #include <stdio.h>
182       #include <stdlib.h>
183
184       #define handle_error(msg) \
185           do { perror(msg); exit(EXIT_FAILURE); } while (0)
186
187       int
188       main(int argc, char *argv[])
189       {
190           FILE *out, *in;
191           int v, s;
192           size_t size;
193           char *ptr;
194
195           if (argc != 2) {
196               fprintf(stderr, "Usage: %s '<num>...'\n", argv[0]);
197               exit(EXIT_FAILURE);
198           }
199
200           in = fmemopen(argv[1], strlen(argv[1]), "r");
201           if (in == NULL)
202               handle_error("fmemopen");
203
204           out = open_memstream(&ptr, &size);
205           if (out == NULL)
206               handle_error("open_memstream");
207
208           for (;;) {
209               s = fscanf(in, "%d", &v);
210               if (s <= 0)
211                   break;
212
213               s = fprintf(out, "%d ", v * v);
214               if (s == -1)
215                   handle_error("fprintf");
216           }
217
218           fclose(in);
219           fclose(out);
220
221           printf("size=%zu; ptr=%s\n", size, ptr);
222
223           free(ptr);
224           exit(EXIT_SUCCESS);
225       }
226

SEE ALSO

228       fopen(3), fopencookie(3), open_memstream(3)
229

COLOPHON

231       This  page  is  part of release 5.13 of the Linux man-pages project.  A
232       description of the project, information about reporting bugs,  and  the
233       latest     version     of     this    page,    can    be    found    at
234       https://www.kernel.org/doc/man-pages/.
235
236
237
238GNU                               2021-03-22                       FMEMOPEN(3)
Impressum