Debian Codegraph @

upstream/debian-unstable/man3/open_memstream.3

raw
1 '\" t
2 .\" Copyright 2005-2016, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-1.0-or-later
6 .\"
7 .TH open_memstream 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 open_memstream, open_wmemstream \- open a dynamic memory buffer stream
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <stdio.h>
16 .P
17 .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
18 .P
19 .B #include <wchar.h>
20 .P
21 .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
22 .fi
23 .P
24 .RS -4
25 Feature Test Macro Requirements for glibc (see
26 .BR feature_test_macros (7)):
27 .RE
28 .P
29 .BR open_memstream (),
30 .BR open_wmemstream ():
31 .nf
32 Since glibc 2.10:
33 _POSIX_C_SOURCE >= 200809L
34 Before glibc 2.10:
35 _GNU_SOURCE
36 .fi
37 .SH DESCRIPTION
38 The
39 .BR open_memstream ()
40 function opens a stream for writing to a memory buffer.
41 The function dynamically allocates the buffer,
42 and the buffer automatically grows as needed.
43 Initially, the buffer has a size of zero.
44 After closing the stream, the caller should
45 .BR free (3)
46 this buffer.
47 .P
48 The locations pointed to by
49 .I ptr
50 and
51 .I sizeloc
52 are used to report, respectively,
53 the current location and the size of the buffer.
54 The locations referred to by these pointers are updated
55 each time the stream is flushed
56 .RB ( fflush (3))
57 and when the stream is closed
58 .RB ( fclose (3)).
59 These values remain valid only as long as the caller
60 performs no further output on the stream.
61 If further output is performed, then the stream
62 must again be flushed before trying to access these values.
63 .P
64 A null byte is maintained at the end of the buffer.
65 This byte is
66 .I not
67 included in the size value stored at
68 .IR sizeloc .
69 .P
70 The stream maintains the notion of a current position,
71 which is initially zero (the start of the buffer).
72 Each write operation implicitly adjusts the buffer position.
73 The stream's buffer position can be explicitly changed with
74 .BR fseek (3)
75 or
76 .BR fseeko (3).
77 Moving the buffer position past the end
78 of the data already written fills the intervening space with
79 null characters.
80 .P
81 The
82 .BR open_wmemstream ()
83 is similar to
84 .BR open_memstream (),
85 but operates on wide characters instead of bytes.
86 .SH RETURN VALUE
87 Upon successful completion,
88 .BR open_memstream ()
89 and
90 .BR open_wmemstream ()
91 return a
92 .I FILE
93 pointer.
94 Otherwise, NULL is returned and
95 .I errno
96 is set to indicate the error.
97 .SH ATTRIBUTES
98 For an explanation of the terms used in this section, see
99 .BR attributes (7).
100 .TS
101 allbox;
102 lbx lb lb
103 l l l.
104 Interface Attribute Value
105 T{
106 .na
107 .nh
108 .BR open_memstream (),
109 .BR open_wmemstream ()
110 T} Thread safety MT-Safe
111 .TE
112 .SH STANDARDS
113 POSIX.1-2008.
114 .SH HISTORY
115 .TP
116 .BR open_memstream ()
117 glibc 1.0.x.
118 .TP
119 .BR open_wmemstream ()
120 glibc 2.4.
121 .SH NOTES
122 There is no file descriptor associated with the file stream
123 returned by these functions
124 (i.e.,
125 .BR fileno (3)
126 will return an error if called on the returned stream).
127 .SH BUGS
128 Before glibc 2.7,
129 seeking past the end of a stream created by
130 .BR open_memstream ()
131 does not enlarge the buffer;
132 instead the
133 .BR fseek (3)
134 call fails, returning \-1.
135 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
136 .SH EXAMPLES
137 See
138 .BR fmemopen (3).
139 .SH SEE ALSO
140 .BR fmemopen (3),
141 .BR fopen (3),
142 .BR setbuf (3)