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.\" %sccs.include.redist.man% 7.\" 8.\" @(#)funopen.3 8.1 (Berkeley) 06/09/93 9.\" 10.Dd 11.Dt FUNOPEN 3 12.Os 13.Sh NAME 14.Nm funopen , 15.Nm fropen , 16.Nm fwopen 17.Nd open a stream 18.Sh SYNOPSIS 19.Fd #include <stdio.h> 20.Ft FILE * 21.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 *)" 22.Ft FILE * 23.Fn fropen "void *cookie" "int (*readfn)(void *, char *, int)" 24.Ft FILE * 25.Fn fwopen "void *cookie" "int (*writefn)(void *, char *, int)" 26.Sh DESCRIPTION 27The 28.Fn funopen 29function 30associates a stream with up to four 31.Dq Tn I/O No functions . 32Either 33.Fa readfn 34or 35.Fa writefn 36must be specified; 37the others can be given as an appropriately-typed 38.Dv NULL 39pointer. 40These 41.Tn I/O 42functions will be used to read, write, seek and 43close the new stream. 44.Pp 45In general, omitting a function means that any attempt to perform the 46associated operation on the resulting stream will fail. 47If the close function is omitted, closing the stream will flush 48any buffered output and then succeed. 49.Pp 50The calling conventions of 51.Fa readfn , 52.Fa writefn , 53.Fa seekfn 54and 55.Fa closefn 56must match those, respectively, of 57.Xr read 2 , 58.Xr write 2 , 59.Xr seek 2 , 60and 61.Xr close 2 62with the single exception that they are passed the 63.Fa cookie 64argument specified to 65.Fn funopen 66in place of the traditional file descriptor argument. 67.Pp 68Read and write 69.Tn I/O 70functions are allowed to change the underlying buffer 71on fully buffered or line buffered streams by calling 72.Xr setvbuf 3 . 73They are also not required to completely fill or empty the buffer. 74They are not, however, allowed to change streams from unbuffered to buffered 75or to change the state of the line buffering flag. 76They must also be prepared to have read or write calls occur on buffers other 77than the one most recently specified. 78.Pp 79All user 80.Tn I/O 81functions can report an error by returning \-1. 82Additionally, all of the functions should set the external variable 83.Va errno 84appropriately if an error occurs. 85.Pp 86An error on 87.Fn closefn 88does not keep the stream open. 89.Pp 90As a convenience, the include file 91.Aq Pa stdio.h 92defines the macros 93.Fn fropen 94and 95.Fn fwopen 96as calls to 97.Fn funopen 98with only a read or write function specified. 99.Sh RETURN VALUES 100Upon successful completion, 101.Fn funopen 102returns a 103.Dv FILE 104pointer. 105Otherwise, 106.Dv NULL 107is returned and the global variable 108.Va errno 109is set to indicate the error. 110.Sh ERRORS 111.Bl -tag -width [EINVAL] 112.It Bq Er EINVAL 113The 114.Fn funopen 115function 116was called without either a read or write function. 117The 118.Fn funopen 119function 120may also fail and set 121.Va errno 122for any of the errors 123specified for the routine 124.Xr malloc 3 . 125.El 126.Sh SEE ALSO 127.Xr fcntl 2 , 128.Xr open 2 , 129.Xr fclose 3 , 130.Xr fopen 3 , 131.Xr fseek 3 , 132.Xr setbuf 3 133.Sh HISTORY 134The 135.Fn funopen 136functions first appeared in 4.4BSD. 137.Sh BUGS 138The 139.Fn funopen 140function 141may not be portable to systems other than 142.Bx . 143