xref: /minix3/lib/libc/stdio/fmemopen.3 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
1.\"	$NetBSD: fmemopen.3,v 1.9 2015/09/06 03:10:50 pgoyette Exp $
2.\"
3.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Christos Zoulas.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright
13.\"    notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\" 3. Neither the name of The NetBSD Foundation nor the names of its
18.\"    contributors may be used to endorse or promote products derived
19.\"    from this software without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
23.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
24.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
25.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31.\" POSSIBILITY OF SUCH DAMAGE.
32.\"
33.Dd September 5, 2015
34.Dt FMEMOPEN 3
35.Os
36.Sh NAME
37.Nm fmemopen
38.Nd open a stream that points to a memory buffer
39.Sh LIBRARY
40.Lb libc
41.Sh SYNOPSIS
42.In stdio.h
43.Ft FILE *
44.Fn fmemopen "void *restrict buffer" "size_t size" "const char *restrict mode"
45.Sh DESCRIPTION
46The
47.Fn fmemopen
48function
49associates a stream with the given
50.Fa buffer
51and
52.Fa size .
53The
54.Fa buffer
55can be either
56.Dv NULL ,
57or must be of the given
58.Fa size .
59If the
60.Fa buffer
61is
62.Dv NULL ,
63a
64.Fa buffer
65of the given
66.Fa size
67will be dynamically allocated using
68.Xr malloc 3
69and freed when
70.Xr fclose 3
71is called.
72.Pp
73The
74.Fa mode
75argument has the same meaning as in
76.Xr fopen 3 .
77.Pp
78The stream treats the buffer as it would treat a file tracking the current
79position to perform I/O operations.
80For example, in the beginning the stream points to the beginning of the buffer,
81unless
82.Dv a
83was specified in the
84.Fa mode
85argument, and then it points to the first
86.Dv NUL
87byte.
88If a
89.Dv NULL
90.Fa buffer
91was specified, then the stream will always point at the first byte of the
92.Fa buffer .
93.Pp
94The stream also keeps track of the
95.Fa size
96of the
97.Fa buffer .
98The
99.Fa size
100is initialized depending on the mode:
101.Bl -tag -width r/w+
102.It Dv r/r+
103Set to the
104.Fa size
105argument.
106.It Dv w/w+
107Set to
108.Dv 0 .
109.It Dv a/a+
110Set to the first
111.Dv NUL
112byte, or the
113.Fa size
114argument if one is not found.
115.El
116.Pp
117Read or write operations advance the buffer, but not to exceed the given
118.Fa size
119of the
120.Fa buffer .
121Trying to read beyond the
122.Fa size
123of the
124.Fa buffer
125results in
126.Dv EOF
127returned.
128.Dv NUL
129bytes are read normally.
130Trying to write beyond the
131.Fa size
132of the
133.Fa buffer
134has no effect.
135.Pp
136When a stream open for writing is either flushed or closed, a
137.Dv NUL
138byte is written at the current position or at the end of the current
139.Fa size
140as kept internally, if there is room.
141.Sh RETURN VALUES
142Upon successful completion,
143.Fn fmemopen
144returns a
145.Dv FILE
146pointer.
147Otherwise,
148.Dv NULL
149is returned and the global variable
150.Va errno
151is set to indicate the error.
152.Sh ERRORS
153.Bl -tag -width Er
154.It Bq Er EINVAL
155The
156.Fa size
157was
158.Dv 0 ;
159or the
160.Fa mode
161argument is invalid;
162or the
163.Fa buffer
164argument is
165.Dv NULL
166and the
167.Fa mode
168argument does not specify a
169.Dv + .
170.El
171.Pp
172The
173.Fn fmemopen
174function
175may also fail and set
176.Va errno
177for any of the errors
178specified for the routine
179.Xr malloc 3 .
180.Sh SEE ALSO
181.Xr fclose 3 ,
182.Xr fflush 3 ,
183.Xr fopen 3 ,
184.Xr malloc 3
185.Sh STANDARDS
186The
187.Fn fmemopen
188function conforms to
189.St -p1003.1-2008 .
190.Sh HISTORY
191The
192.Fn fmemopen
193function first appeared in
194.Nx 6.0 .
195