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