]> git.saurik.com Git - apple/libc.git/blame - stdio/FreeBSD/open_memstream.3
Libc-1272.200.26.tar.gz
[apple/libc.git] / stdio / FreeBSD / open_memstream.3
CommitLineData
b061a43b
A
1.\" Copyright (c) 2013 Hudson River Trading LLC
2.\" Written by: John H. Baldwin <jhb@FreeBSD.org>
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\" notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\" notice, this list of conditions and the following disclaimer in the
12.\" documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd August 1, 2015
29.Dt OPEN_MEMSTREAM 3
30.Os
31.Sh NAME
32.Nm open_memstream ,
33.Nm open_wmemstream
34.Nd dynamic memory buffer stream open functions
35.Sh LIBRARY
36.Lb libc
37.Sh SYNOPSIS
38.In stdio.h
39.Ft FILE *
40.Fn open_memstream "char **bufp" "size_t *sizep"
41.In wchar.h
42.Ft FILE *
43.Fn open_wmemstream "wchar_t **bufp" "size_t *sizep"
44.Sh DESCRIPTION
45The
46.Fn open_memstream
47and
48.Fn open_wmemstream
49functions create a write-only, seekable stream backed by a dynamically
50allocated memory buffer.
51The
52.Fn open_memstream
53function creates a byte-oriented stream,
54while the
55.Fn open_wmemstream
56function creates a wide-oriented stream.
57.Pp
58Each stream maintains a current position and size.
59Initially,
60the position and size are set to zero.
61Each write begins at the current position and advances it the number of
62successfully written bytes for
63.Fn open_memstream
64or wide characters for
65.Fn open_wmemstream .
66If a write moves the current position beyond the length of the buffer,
67the length of the buffer is extended and a null character is appended to the
68buffer.
69.Pp
70A stream's buffer always contains a null character at the end of the buffer
71that is not included in the current length.
72.Pp
73If a stream's current position is moved beyond the current length via a
74seek operation and a write is performed,
75the characters between the current length and the current position are filled
76with null characters before the write is performed.
77.Pp
78After a successful call to
79.Xr fclose 3
80or
81.Xr fflush 3 ,
82the pointer referenced by
83.Fa bufp
84will contain the start of the memory buffer and the variable referenced by
85.Fa sizep
86will contain the smaller of the current position and the current buffer length.
87.Pp
88After a successful call to
89.Xr fflush 3 ,
90the pointer referenced by
91.Fa bufp
92and the variable referenced by
93.Fa sizep
94are only valid until the next write operation or a call to
95.Xr fclose 3 .
96.Pp
97Once a stream is closed,
98the allocated buffer referenced by
99.Fa bufp
100should be released via a call to
101.Xr free 3
102when it is no longer needed.
103.Sh IMPLEMENTATION NOTES
104Internally all I/O streams are effectively byte-oriented,
105so using wide-oriented operations to write to a stream opened via
106.Fn open_wmemstream
107results in wide characters being expanded to a stream of multibyte characters
108in stdio's internal buffers.
109These multibyte characters are then converted back to wide characters when
110written into the stream.
111As a result,
112the wide-oriented streams maintain an internal multibyte character conversion
113state that is cleared on any seek opertion that changes the current position.
114This should have no effect as long as wide-oriented output operations are used
115on a wide-oriented stream.
116.Sh RETURN VALUES
117Upon successful completion,
118.Fn open_memstream
119and
120.Fn open_wmemstream
121return a
122.Tn FILE
123pointer.
124Otherwise,
125.Dv NULL
126is returned and the global variable
127.Va errno
128is set to indicate the error.
129.Sh ERRORS
130.Bl -tag -width Er
131.It Bq Er EINVAL
132The
133.Fa bufp
134or
135.Fa sizep
136argument was
137.Dv NULL .
138.It Bq Er ENOMEM
139Memory for the stream or buffer could not be allocated.
140.El
141.Sh SEE ALSO
142.Xr fclose 3 ,
143.Xr fflush 3 ,
144.Xr fopen 3 ,
145.Xr free 3 ,
146.Xr fseek 3 ,
147.Xr stdio 3 ,
148.Xr sbuf 9
149.Sh STANDARDS
150The
151.Fn open_memstream
152and
153.Fn open_wmemstream
154functions conform to
155.St -p1003.1-2008 .