xref: /dflybsd-src/lib/libc/stdio/fopencookie.3 (revision a431bfe52a2aad0a18cf535124e1b488f6d7ce06)
1a765cedfSAntonio Huete Jimenez.\" Copyright (c) 2016, EMC / Isilon Storage Division
2a765cedfSAntonio Huete Jimenez.\" All rights reserved.
3a765cedfSAntonio Huete Jimenez.\"
4a765cedfSAntonio Huete Jimenez.\" Redistribution and use in source and binary forms, with or without
5a765cedfSAntonio Huete Jimenez.\" modification, are permitted provided that the following conditions
6a765cedfSAntonio Huete Jimenez.\" are met:
7a765cedfSAntonio Huete Jimenez.\" 1. Redistributions of source code must retain the above copyright
8a765cedfSAntonio Huete Jimenez.\"    notice, this list of conditions and the following disclaimer.
9a765cedfSAntonio Huete Jimenez.\" 2. Redistributions in binary form must reproduce the above copyright
10a765cedfSAntonio Huete Jimenez.\"    notice, this list of conditions and the following disclaimer in the
11a765cedfSAntonio Huete Jimenez.\"    documentation and/or other materials provided with the distribution.
12a765cedfSAntonio Huete Jimenez.\"
13a765cedfSAntonio Huete Jimenez.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS
14a765cedfSAntonio Huete Jimenez.\" IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
15a765cedfSAntonio Huete Jimenez.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16a765cedfSAntonio Huete Jimenez.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
17a765cedfSAntonio Huete Jimenez.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18a765cedfSAntonio Huete Jimenez.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19a765cedfSAntonio Huete Jimenez.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
20a765cedfSAntonio Huete Jimenez.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
21a765cedfSAntonio Huete Jimenez.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
22a765cedfSAntonio Huete Jimenez.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
23a765cedfSAntonio Huete Jimenez.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24a765cedfSAntonio Huete Jimenez.\"
25a765cedfSAntonio Huete Jimenez.\" $FreeBSD$
26a765cedfSAntonio Huete Jimenez.\"
27*a431bfe5SSascha Wildner.Dd February 4, 2023
28a765cedfSAntonio Huete Jimenez.Dt FOPENCOOKIE 3
29a765cedfSAntonio Huete Jimenez.Os
30a765cedfSAntonio Huete Jimenez.Sh NAME
31a765cedfSAntonio Huete Jimenez.Nm fopencookie
32a765cedfSAntonio Huete Jimenez.Nd open a stream
33a765cedfSAntonio Huete Jimenez.Sh LIBRARY
34a765cedfSAntonio Huete Jimenez.Lb libc
35a765cedfSAntonio Huete Jimenez.Sh SYNOPSIS
36a765cedfSAntonio Huete Jimenez.In stdio.h
37a765cedfSAntonio Huete Jimenez.Ft typedef ssize_t
38a765cedfSAntonio Huete Jimenez.Fn (*cookie_read_function_t) "void *cookie" "char *buf" "size_t size"
39a765cedfSAntonio Huete Jimenez.Ft typedef ssize_t
40a765cedfSAntonio Huete Jimenez.Fn (*cookie_write_function_t) "void *cookie" "const char *buf" "size_t size"
41a765cedfSAntonio Huete Jimenez.Ft typedef int
42*a431bfe5SSascha Wildner.Fn (*cookie_seek_function_t) "void *cookie" "off_t *offset" "int whence"
43a765cedfSAntonio Huete Jimenez.Ft typedef int
44a765cedfSAntonio Huete Jimenez.Fn (*cookie_close_function_t) "void *cookie"
45a765cedfSAntonio Huete Jimenez.Bd -literal
46a765cedfSAntonio Huete Jimeneztypedef struct {
47a765cedfSAntonio Huete Jimenez	cookie_read_function_t	*read;
48a765cedfSAntonio Huete Jimenez	cookie_write_function_t	*write;
49a765cedfSAntonio Huete Jimenez	cookie_seek_function_t	*seek;
50a765cedfSAntonio Huete Jimenez	cookie_close_function_t	*close;
51a765cedfSAntonio Huete Jimenez} cookie_io_functions_t;
52a765cedfSAntonio Huete Jimenez.Ed
53a765cedfSAntonio Huete Jimenez.Ft FILE *
54a765cedfSAntonio Huete Jimenez.Fn fopencookie "void *cookie" "const char *mode" "cookie_io_functions_t io_funcs"
55a765cedfSAntonio Huete Jimenez.Sh DESCRIPTION
56a765cedfSAntonio Huete JimenezThe
57a765cedfSAntonio Huete Jimenez.Nm
58a765cedfSAntonio Huete Jimenezfunction
59a765cedfSAntonio Huete Jimenezassociates a stream with up to four
60a765cedfSAntonio Huete Jimenez.Dq Tn I/O No functions .
61a765cedfSAntonio Huete JimenezThese
62a765cedfSAntonio Huete Jimenez.Tn I/O
63a765cedfSAntonio Huete Jimenezfunctions will be used to read, write, seek and
64a765cedfSAntonio Huete Jimenezclose the new stream.
65a765cedfSAntonio Huete Jimenez.Pp
66a765cedfSAntonio Huete JimenezIn general, omitting a function means that any attempt to perform the
67a765cedfSAntonio Huete Jimenezassociated operation on the resulting stream will fail.
68a765cedfSAntonio Huete JimenezIf the write function is omitted, data written to the stream is discarded.
69a765cedfSAntonio Huete JimenezIf the close function is omitted, closing the stream will flush
70a765cedfSAntonio Huete Jimenezany buffered output and then succeed.
71a765cedfSAntonio Huete Jimenez.Pp
72a765cedfSAntonio Huete JimenezThe calling conventions of
73a765cedfSAntonio Huete Jimenez.Fa read ,
74a765cedfSAntonio Huete Jimenez.Fa write ,
75a765cedfSAntonio Huete Jimenezand
76a765cedfSAntonio Huete Jimenez.Fa close
77a765cedfSAntonio Huete Jimenezmust match those, respectively, of
78a765cedfSAntonio Huete Jimenez.Xr read 2 ,
79a765cedfSAntonio Huete Jimenez.Xr write 2 ,
80a765cedfSAntonio Huete Jimenezand
81a765cedfSAntonio Huete Jimenez.Xr close 2
82a765cedfSAntonio Huete Jimenezwith the single exception that they are passed the
83a765cedfSAntonio Huete Jimenez.Fa cookie
84a765cedfSAntonio Huete Jimenezargument specified to
85a765cedfSAntonio Huete Jimenez.Nm
86a765cedfSAntonio Huete Jimenezin place of the traditional file descriptor argument.
87a765cedfSAntonio Huete JimenezThe
88a765cedfSAntonio Huete Jimenez.Fa seek
89a765cedfSAntonio Huete Jimenezfunction updates the current stream offset using
90a765cedfSAntonio Huete Jimenez.Fa *offset
91a765cedfSAntonio Huete Jimenezand
92a765cedfSAntonio Huete Jimenez.Fa whence .
93a765cedfSAntonio Huete JimenezIf
94a765cedfSAntonio Huete Jimenez.Fa *offset
95a765cedfSAntonio Huete Jimenezis non-NULL, it updates
96a765cedfSAntonio Huete Jimenez.Fa *offset
97a765cedfSAntonio Huete Jimenezwith the current stream offset.
98a765cedfSAntonio Huete Jimenez.Pp
99a765cedfSAntonio Huete Jimenez.Nm
100a765cedfSAntonio Huete Jimenezis implemented as a thin shim around the
101a765cedfSAntonio Huete Jimenez.Xr funopen 3
102a765cedfSAntonio Huete Jimenezinterface.
103a765cedfSAntonio Huete JimenezLimitations, possibilities, and requirements of that interface apply to
104a765cedfSAntonio Huete Jimenez.Nm .
105a765cedfSAntonio Huete Jimenez.Sh RETURN VALUES
106a765cedfSAntonio Huete JimenezUpon successful completion,
107a765cedfSAntonio Huete Jimenez.Nm
108a765cedfSAntonio Huete Jimenezreturns a
109a765cedfSAntonio Huete Jimenez.Dv FILE
110a765cedfSAntonio Huete Jimenezpointer.
111a765cedfSAntonio Huete JimenezOtherwise,
112a765cedfSAntonio Huete Jimenez.Dv NULL
113a765cedfSAntonio Huete Jimenezis returned and the global variable
114a765cedfSAntonio Huete Jimenez.Va errno
115a765cedfSAntonio Huete Jimenezis set to indicate the error.
116a765cedfSAntonio Huete Jimenez.Sh ERRORS
117a765cedfSAntonio Huete Jimenez.Bl -tag -width Er
118a765cedfSAntonio Huete Jimenez.It Bq Er EINVAL
119a765cedfSAntonio Huete JimenezA bogus
120a765cedfSAntonio Huete Jimenez.Fa mode
121a765cedfSAntonio Huete Jimenezwas provided to
122a765cedfSAntonio Huete Jimenez.Nm .
123a765cedfSAntonio Huete Jimenez.It Bq Er ENOMEM
124a765cedfSAntonio Huete JimenezThe
125a765cedfSAntonio Huete Jimenez.Nm
126a765cedfSAntonio Huete Jimenezfunction
127a765cedfSAntonio Huete Jimenezmay fail and set
128a765cedfSAntonio Huete Jimenez.Va errno
129a765cedfSAntonio Huete Jimenezfor any of the errors
130a765cedfSAntonio Huete Jimenezspecified for the
131a765cedfSAntonio Huete Jimenez.Xr malloc 3
132a765cedfSAntonio Huete Jimenezroutine.
133a765cedfSAntonio Huete Jimenez.El
134a765cedfSAntonio Huete Jimenez.Sh SEE ALSO
135a765cedfSAntonio Huete Jimenez.Xr fcntl 2 ,
136a765cedfSAntonio Huete Jimenez.Xr open 2 ,
137a765cedfSAntonio Huete Jimenez.Xr fclose 3 ,
138a765cedfSAntonio Huete Jimenez.Xr fopen 3 ,
139a765cedfSAntonio Huete Jimenez.Xr fseek 3 ,
140a765cedfSAntonio Huete Jimenez.Xr funopen 3
141a765cedfSAntonio Huete Jimenez.Sh HISTORY
142a765cedfSAntonio Huete JimenezThe
143a765cedfSAntonio Huete Jimenez.Fn funopen
144a765cedfSAntonio Huete Jimenezfunctions first appeared in
145a765cedfSAntonio Huete Jimenez.Bx 4.4 .
146a765cedfSAntonio Huete JimenezThe
147a765cedfSAntonio Huete Jimenez.Nm
148a765cedfSAntonio Huete Jimenezfunction first appeared in
149a765cedfSAntonio Huete Jimenez.Fx 11 .
150a765cedfSAntonio Huete Jimenez.Sh BUGS
151a765cedfSAntonio Huete JimenezThe
152a765cedfSAntonio Huete Jimenez.Nm
153a765cedfSAntonio Huete Jimenezfunction is a nonstandard glibc extension and may not be portable to systems
154a765cedfSAntonio Huete Jimenezother than
155a765cedfSAntonio Huete Jimenez.Fx
156a765cedfSAntonio Huete Jimenezand Linux.
157