xref: /freebsd/lib/libc/stdio/funopen.3 (revision 60d717baf2144cf344ec9b47d715ce837b5d46d4)
1 .\" Copyright (c) 1990, 1991, 1993
2 .\"	The Regents of the University of California.  All rights reserved.
3 .\"
4 .\" This code is derived from software contributed to Berkeley by
5 .\" Chris Torek.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\"    may be used to endorse or promote products derived from this software
16 .\"    without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .Dd May 9, 2016
31 .Dt FUNOPEN 3
32 .Os
33 .Sh NAME
34 .Nm funopen ,
35 .Nm fropen ,
36 .Nm fwopen
37 .Nd open a stream
38 .Sh LIBRARY
39 .Lb libc
40 .Sh SYNOPSIS
41 .In stdio.h
42 .Ft FILE *
43 .Fn funopen "const void *cookie" "int (*readfn)(void *, char *, int)" "int (*writefn)(void *, const char *, int)" "fpos_t (*seekfn)(void *, fpos_t, int)" "int (*closefn)(void *)"
44 .Ft FILE *
45 .Fn fropen "void *cookie" "int (*readfn)(void *, char *, int)"
46 .Ft FILE *
47 .Fn fwopen "void *cookie" "int (*writefn)(void *, const char *, int)"
48 .Sh DESCRIPTION
49 The
50 .Fn funopen
51 function
52 associates a stream with up to four
53 .Dq Tn I/O No functions .
54 Either
55 .Fa readfn
56 or
57 .Fa writefn
58 must be specified;
59 the others can be given as an appropriately-typed
60 .Dv NULL
61 pointer.
62 These
63 .Tn I/O
64 functions will be used to read, write, seek and
65 close the new stream.
66 .Pp
67 In general, omitting a function means that any attempt to perform the
68 associated operation on the resulting stream will fail.
69 If the close function is omitted, closing the stream will flush
70 any buffered output and then succeed.
71 .Pp
72 The calling conventions of
73 .Fa readfn ,
74 .Fa writefn ,
75 .Fa seekfn
76 and
77 .Fa closefn
78 must match those, respectively, of
79 .Xr read 2 ,
80 .Xr write 2 ,
81 .Xr lseek 2 ,
82 and
83 .Xr close 2
84 with the single exception that they are passed the
85 .Fa cookie
86 argument specified to
87 .Fn funopen
88 in place of the traditional file descriptor argument.
89 .Pp
90 Read and write
91 .Tn I/O
92 functions are allowed to change the underlying buffer
93 on fully buffered or line buffered streams by calling
94 .Xr setvbuf 3 .
95 They are also not required to completely fill or empty the buffer.
96 They are not, however, allowed to change streams from unbuffered to buffered
97 or to change the state of the line buffering flag.
98 They must also be prepared to have read or write calls occur on buffers other
99 than the one most recently specified.
100 .Pp
101 All user
102 .Tn I/O
103 functions can report an error by returning \-1.
104 Additionally, all of the functions should set the external variable
105 .Va errno
106 appropriately if an error occurs.
107 .Pp
108 An error on
109 .Fn closefn
110 does not keep the stream open.
111 .Pp
112 As a convenience, the include file
113 .In stdio.h
114 defines the macros
115 .Fn fropen
116 and
117 .Fn fwopen
118 as calls to
119 .Fn funopen
120 with only a read or write function specified.
121 .Sh RETURN VALUES
122 Upon successful completion,
123 .Fn funopen
124 returns a
125 .Dv FILE
126 pointer.
127 Otherwise,
128 .Dv NULL
129 is returned and the global variable
130 .Va errno
131 is set to indicate the error.
132 .Sh ERRORS
133 .Bl -tag -width Er
134 .It Bq Er EINVAL
135 The
136 .Fn funopen
137 function
138 was called without either a read or write function.
139 The
140 .Fn funopen
141 function
142 may also fail and set
143 .Va errno
144 for any of the errors
145 specified for the routine
146 .Xr malloc 3 .
147 .El
148 .Sh SEE ALSO
149 .Xr fcntl 2 ,
150 .Xr open 2 ,
151 .Xr fclose 3 ,
152 .Xr fopen 3 ,
153 .Xr fopencookie 3 ,
154 .Xr fseek 3 ,
155 .Xr setbuf 3
156 .Sh HISTORY
157 The
158 .Fn funopen
159 functions first appeared in
160 .Bx 4.4 .
161 .Sh BUGS
162 The
163 .Fn funopen
164 function
165 may not be portable to systems other than
166 .Bx .
167 .Pp
168 The
169 .Fn funopen
170 interface erroneously assumes that
171 .Vt fpos_t
172 is an integral type; see
173 .Xr fseek 3
174 for a discussion of this issue.
175