1*48351Scael.\" Copyright (c) 1990, 1991 The Regents of the University of California. 247014Sbostic.\" All rights reserved. 347014Sbostic.\" 447014Sbostic.\" This code is derived from software contributed to Berkeley by 547014Sbostic.\" Chris Torek. 647014Sbostic.\" %sccs.include.redist.man% 747014Sbostic.\" 8*48351Scael.\" @(#)funopen.3 5.3 (Berkeley) 04/19/91 947014Sbostic.\" 10*48351Scael.Dd 11*48351Scael.Dt FUNOPEN 3 12*48351Scael.Os 13*48351Scael.Sh NAME 14*48351Scael.Nm funopen , 15*48351Scael.Nm fropen , 16*48351Scael.Nm fwopen 17*48351Scael.Nd open a stream 18*48351Scael.Sh SYNOPSIS 19*48351Scael.Fd #include <stdio.h> 20*48351Scael.Ft FILE * 21*48351Scael.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*48351Scael.Ft FILE * 23*48351Scael.Fn fropen "void *cookie" "int (*readfn)(void *, char *, int)" 24*48351Scael.Ft FILE * 25*48351Scael.Fn fwopen "void *cookie" "int (*writefn)(void *, char *, int)" 26*48351Scael.Sh DESCRIPTION 27*48351ScaelThe 28*48351Scael.Fn funopen 29*48351Scaelfunction 30*48351Scaelassociates a stream with up to four 31*48351Scael.Dq Tn I/O No functions . 3247014SbosticEither 33*48351Scael.Fa readfn 3447014Sbosticor 35*48351Scael.Fa writefn 3647014Sbosticmust be specified; 37*48351Scaelthe others can be given as an appropriately-typed 38*48351Scael.Dv NULL 39*48351Scaelpointer. 40*48351ScaelThese 41*48351Scael.Tn I/O 42*48351Scaelfunctions will be used to read, write, seek and 4347014Sbosticclose the new stream. 44*48351Scael.Pp 4547014SbosticIn general, omitting a function means that any attempt to perform the 4647014Sbosticassociated operation on the resulting stream will fail. 4747014SbosticIf the close function is omitted, closing the stream will flush 4847014Sbosticany buffered output and then succeed. 49*48351Scael.Pp 5047014SbosticThe calling conventions of 51*48351Scael.Fa readfn , 52*48351Scael.Fa writefn , 53*48351Scael.Fa seekfn 5447014Sbosticand 55*48351Scael.Fa closefn 5647014Sbosticmust match those, respectively, of 57*48351Scael.Xr read 2 , 58*48351Scael.Xr write 2 , 59*48351Scael.Xr seek 2 , 6047014Sbosticand 61*48351Scael.Xr close 2 6247014Sbosticwith the single exception that they are passed the 63*48351Scael.Fa cookie 6447014Sbosticargument specified to 65*48351Scael.Fn funopen 6647014Sbosticin place of the traditional file descriptor argument. 67*48351Scael.Pp 68*48351ScaelRead and write 69*48351Scael.Tn I/O 70*48351Scaelfunctions are allowed to change the underlying buffer 7147014Sbosticon fully buffered or line buffered streams by calling 72*48351Scael.Xr setvbuf 3 . 7347014SbosticThey are also not required to completely fill or empty the buffer. 7447014SbosticThey are not, however, allowed to change streams from unbuffered to buffered 7547014Sbosticor to change the state of the line buffering flag. 7647014SbosticThey must also be prepared to have read or write calls occur on buffers other 7747014Sbosticthan the one most recently specified. 78*48351Scael.Pp 79*48351ScaelAll user 80*48351Scael.Tn I/O 81*48351Scaelfunctions can report an error by returning \-1. 8247014SbosticAdditionally, all of the functions should set the external variable 83*48351Scael.Va errno 8447014Sbosticappropriately if an error occurs. 85*48351Scael.Pp 8647014SbosticAn error on 87*48351Scael.Fn closefn 8847014Sbosticdoes not keep the stream open. 89*48351Scael.Pp 90*48351ScaelAs a convenience, the include file 91*48351Scael.Aq Pa stdio.h 92*48351Scaeldefines the macros 93*48351Scael.Fn fropen 9447014Sbosticand 95*48351Scael.Fn fwopen 9647014Sbosticas calls to 97*48351Scael.Fn funopen 9847014Sbosticwith only a read or write function specified. 99*48351Scael.Sh RETURN VALUES 10047014SbosticUpon successful completion, 101*48351Scael.Fn funopen 102*48351Scaelreturns a 103*48351Scael.Dv FILE 104*48351Scaelpointer. 105*48351ScaelOtherwise, 106*48351Scael.Dv NULL 107*48351Scaelis returned and the global variable 108*48351Scael.Va errno 10947014Sbosticis set to indicate the error. 110*48351Scael.Sh ERRORS 111*48351Scael.Bl -tag -width [EINVAL] 112*48351Scael.It Bq Er EINVAL 113*48351ScaelThe 114*48351Scael.Fn funopen 115*48351Scaelfunction 11647014Sbosticwas called without either a read or write function. 117*48351ScaelThe 118*48351Scael.Fn funopen 119*48351Scaelfunction 120*48351Scaelmay also fail and set 121*48351Scael.Va errno 122*48351Scaelfor any of the errors 12347014Sbosticspecified for the routine 124*48351Scael.Xr malloc 3 . 125*48351Scael.El 126*48351Scael.Sh SEE ALSO 127*48351Scael.Xr fcntl 2 , 128*48351Scael.Xr open 2 , 129*48351Scael.Xr fclose 3 , 130*48351Scael.Xr fopen 3 , 131*48351Scael.Xr fseek 3 , 132*48351Scael.Xr setbuf 3 133*48351Scael.Sh HISTORY 134*48351ScaelThese 135*48351Scaelfunctions are 136*48351Scael.Ud . 137*48351Scael.Sh BUGS 138*48351ScaelThe 139*48351Scael.Fn funopen 140*48351Scaelfunction 141*48351Scaelmay not be portable to systems other than 142*48351Scael.Bx . 143