]>
Commit | Line | Data |
---|---|---|
8190a9ee | 1 | .\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
09ffd9ca | 2 | .\" |
95fb8859 | 3 | .\" SPDX-License-Identifier: GPL-1.0-or-later |
09ffd9ca MK |
4 | .\" |
5 | .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream() | |
6 | .\" | |
4c1c5274 | 7 | .TH open_memstream 3 (date) "Linux man-pages (unreleased)" |
09ffd9ca MK |
8 | .SH NAME |
9 | open_memstream, open_wmemstream \- open a dynamic memory buffer stream | |
c18d2221 AC |
10 | .SH LIBRARY |
11 | Standard C library | |
8fc3b2cf | 12 | .RI ( libc ", " \-lc ) |
09ffd9ca MK |
13 | .SH SYNOPSIS |
14 | .nf | |
15 | .B #include <stdio.h> | |
f90f031e | 16 | .PP |
09ffd9ca | 17 | .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); |
eaa18d3c | 18 | .PP |
09ffd9ca | 19 | .B #include <wchar.h> |
f90f031e | 20 | .PP |
09ffd9ca MK |
21 | .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc ); |
22 | .fi | |
68e4db0a | 23 | .PP |
d39ad78f | 24 | .RS -4 |
09ffd9ca MK |
25 | Feature Test Macro Requirements for glibc (see |
26 | .BR feature_test_macros (7)): | |
d39ad78f | 27 | .RE |
68e4db0a | 28 | .PP |
09ffd9ca MK |
29 | .BR open_memstream (), |
30 | .BR open_wmemstream (): | |
9d2adbae MK |
31 | .nf |
32 | Since glibc 2.10: | |
5c10d2c5 | 33 | _POSIX_C_SOURCE >= 200809L |
9d2adbae MK |
34 | Before glibc 2.10: |
35 | _GNU_SOURCE | |
36 | .fi | |
09ffd9ca MK |
37 | .SH DESCRIPTION |
38 | The | |
39 | .BR open_memstream () | |
207f4520 MK |
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. | |
e3d1b1b7 | 43 | Initially, the buffer has a size of zero. |
09ffd9ca MK |
44 | After closing the stream, the caller should |
45 | .BR free (3) | |
46 | this buffer. | |
847e0d88 | 47 | .PP |
09ffd9ca | 48 | The locations pointed to by |
1ae6b2c7 | 49 | .I ptr |
09ffd9ca MK |
50 | and |
51 | .I sizeloc | |
207f4520 MK |
52 | are used to report, respectively, |
53 | the current location and the size of the buffer. | |
2c767761 | 54 | The locations referred to by these pointers are updated |
207f4520 MK |
55 | each time the stream is flushed |
56 | .RB ( fflush (3)) | |
57 | and when the stream is closed | |
58 | .RB ( fclose (3)). | |
09ffd9ca MK |
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 | |
207f4520 | 62 | must again be flushed before trying to access these values. |
847e0d88 | 63 | .PP |
09ffd9ca MK |
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 . | |
847e0d88 | 69 | .PP |
31a3c488 MK |
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 | |
09ffd9ca MK |
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 | |
207f4520 | 79 | null characters. |
847e0d88 | 80 | .PP |
09ffd9ca MK |
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 VERSIONS | |
98 | .BR open_memstream () | |
99 | was already available in glibc 1.0.x. | |
100 | .BR open_wmemstream () | |
101 | is available since glibc 2.4. | |
102 | .SH ATTRIBUTES | |
103 | For an explanation of the terms used in this section, see | |
104 | .BR attributes (7). | |
c466875e MK |
105 | .ad l |
106 | .nh | |
09ffd9ca MK |
107 | .TS |
108 | allbox; | |
c466875e | 109 | lbx lb lb |
09ffd9ca MK |
110 | l l l. |
111 | Interface Attribute Value | |
112 | T{ | |
113 | .BR open_memstream (), | |
4cc91169 | 114 | .BR open_wmemstream () |
09ffd9ca MK |
115 | T} Thread safety MT-Safe |
116 | .TE | |
c466875e MK |
117 | .hy |
118 | .ad | |
847e0d88 | 119 | .sp 1 |
3113c7f3 | 120 | .SH STANDARDS |
09ffd9ca MK |
121 | POSIX.1-2008. |
122 | These functions are not specified in POSIX.1-2001, | |
123 | and are not widely available on other systems. | |
124 | .SH NOTES | |
125 | There is no file descriptor associated with the file stream | |
126 | returned by these functions | |
127 | (i.e., | |
128 | .BR fileno (3) | |
129 | will return an error if called on the returned stream). | |
130 | .SH BUGS | |
131 | In glibc before version 2.7, seeking past the end of a stream created by | |
132 | .BR open_memstream () | |
133 | does not enlarge the buffer; instead the | |
134 | .BR fseek (3) | |
135 | call fails, returning \-1. | |
136 | .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996 | |
a14af333 | 137 | .SH EXAMPLES |
09ffd9ca MK |
138 | See |
139 | .BR fmemopen (3). | |
140 | .SH SEE ALSO | |
141 | .BR fmemopen (3), | |
77c73ca4 MK |
142 | .BR fopen (3), |
143 | .BR setbuf (3) |