1OPEN_MEMSTREAM(3P)         POSIX Programmer's Manual        OPEN_MEMSTREAM(3P)
2
3
4

PROLOG

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

NAME

12       open_memstream, open_wmemstream — open a dynamic memory buffer stream
13

SYNOPSIS

15       #include <stdio.h>
16
17       FILE *open_memstream(char **bufp, size_t *sizep);
18
19       #include <wchar.h>
20
21       FILE *open_wmemstream(wchar_t **bufp, size_t *sizep);
22

DESCRIPTION

24       The open_memstream() and open_wmemstream() functions  shall  create  an
25       I/O  stream  associated with a dynamically allocated memory buffer. The
26       stream shall be opened for writing and shall be seekable.
27
28       The stream associated with a call to open_memstream()  shall  be  byte-
29       oriented.
30
31       The  stream  associated with a call to open_wmemstream() shall be wide-
32       oriented.
33
34       The stream shall maintain a current position in  the  allocated  buffer
35       and  a  current  buffer  length. The position shall be initially set to
36       zero (the start of the buffer). Each write to the stream shall start at
37       the  current  position and move this position by the number of success‐
38       fully written bytes for open_memstream() or the number of  successfully
39       written  wide  characters  for  open_wmemstream().  The length shall be
40       initially set to zero. If a write moves the position to a value  larger
41       than  the current length, the current length shall be set to this posi‐
42       tion. In this case a null character for open_memstream() or a null wide
43       character  for  open_wmemstream() shall be appended to the current buf‐
44       fer. For both functions the terminating null is  not  included  in  the
45       calculation of the buffer length.
46
47       After a successful fflush() or fclose(), the pointer referenced by bufp
48       shall contain the address of the buffer, and the variable pointed to by
49       sizep  shall  contain  the smaller of the current buffer length and the
50       number of bytes for open_memstream(), or the number of wide  characters
51       for open_wmemstream(), between the beginning of the buffer and the cur‐
52       rent file position indicator.
53
54       After a successful fflush() the pointer  referenced  by  bufp  and  the
55       variable  referenced  by  sizep  remain valid only until the next write
56       operation on the stream or a call to fclose().
57
58       After a successful fclose(), the pointer  referenced  by  bufp  can  be
59       passed to free().
60

RETURN VALUE

62       Upon  successful  completion, these functions shall return a pointer to
63       the object controlling the stream. Otherwise, a null pointer  shall  be
64       returned, and errno shall be set to indicate the error.
65

ERRORS

67       These functions shall fail if:
68
69       EMFILE {STREAM_MAX} streams are currently open in the calling process.
70
71       These functions may fail if:
72
73       EINVAL bufp or sizep are NULL.
74
75       EMFILE {FOPEN_MAX} streams are currently open in the calling process.
76
77       ENOMEM Memory for the stream or the buffer could not be allocated.
78
79       The following sections are informative.
80

EXAMPLES

82           #include <stdio.h>
83           #include <stdlib.h>
84
85           int
86           main (void)
87           {
88               FILE *stream;
89               char *buf;
90               size_t len;
91               off_t eob;
92
93               stream = open_memstream (&buf, &len);
94               if (stream == NULL)
95                   /* handle error */ ;
96               fprintf (stream, "hello my world");
97               fflush (stream);
98               printf ("buf=%s, len=%zu\n", buf, len);
99               eob = ftello(stream);
100               fseeko (stream, 0, SEEK_SET);
101               fprintf (stream, "good-bye");
102               fseeko (stream, eob, SEEK_SET);
103               fclose (stream);
104               printf ("buf=%s, len=%zu\n", buf, len);
105               free (buf);
106               return 0;
107           }
108
109       This program produces the following output:
110
111
112           buf=hello my world, len=14
113           buf=good-bye world, len=14
114

APPLICATION USAGE

116       The  buffer  created by these functions should be freed by the applica‐
117       tion after closing the stream, by means of a call to free().
118

RATIONALE

120       These functions are similar to fmemopen() except  that  the  memory  is
121       always  allocated dynamically by the function, and the stream is opened
122       only for output.
123

FUTURE DIRECTIONS

125       None.
126

SEE ALSO

128       fclose(), fdopen(), fflush(), fmemopen(), fopen(), free(), freopen()
129
130       The Base Definitions volume of POSIX.1‐2017, <stdio.h>, <wchar.h>
131
133       Portions of this text are reprinted and reproduced in  electronic  form
134       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
135       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
136       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
137       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
138       event of any discrepancy between this version and the original IEEE and
139       The Open Group Standard, the original IEEE and The Open Group  Standard
140       is  the  referee document. The original Standard can be obtained online
141       at http://www.opengroup.org/unix/online.html .
142
143       Any typographical or formatting errors that appear  in  this  page  are
144       most likely to have been introduced during the conversion of the source
145       files to man page format. To report such errors,  see  https://www.ker
146       nel.org/doc/man-pages/reporting_bugs.html .
147
148
149
150IEEE/The Open Group                  2017                   OPEN_MEMSTREAM(3P)
Impressum