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