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