1*62887Sbostic.\" Copyright (c) 1990, 1991, 1993 2*62887Sbostic.\" The Regents of the University of California. 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*62887Sbostic.\" @(#)funopen.3 8.1 (Berkeley) 06/09/93 947014Sbostic.\" 1048351Scael.Dd 1148351Scael.Dt FUNOPEN 3 1248351Scael.Os 1348351Scael.Sh NAME 1448351Scael.Nm funopen , 1548351Scael.Nm fropen , 1648351Scael.Nm fwopen 1748351Scael.Nd open a stream 1848351Scael.Sh SYNOPSIS 1948351Scael.Fd #include <stdio.h> 2048351Scael.Ft FILE * 2148351Scael.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 *)" 2248351Scael.Ft FILE * 2348351Scael.Fn fropen "void *cookie" "int (*readfn)(void *, char *, int)" 2448351Scael.Ft FILE * 2548351Scael.Fn fwopen "void *cookie" "int (*writefn)(void *, char *, int)" 2648351Scael.Sh DESCRIPTION 2748351ScaelThe 2848351Scael.Fn funopen 2948351Scaelfunction 3048351Scaelassociates a stream with up to four 3148351Scael.Dq Tn I/O No functions . 3247014SbosticEither 3348351Scael.Fa readfn 3447014Sbosticor 3548351Scael.Fa writefn 3647014Sbosticmust be specified; 3748351Scaelthe others can be given as an appropriately-typed 3848351Scael.Dv NULL 3948351Scaelpointer. 4048351ScaelThese 4148351Scael.Tn I/O 4248351Scaelfunctions will be used to read, write, seek and 4347014Sbosticclose the new stream. 4448351Scael.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. 4948351Scael.Pp 5047014SbosticThe calling conventions of 5148351Scael.Fa readfn , 5248351Scael.Fa writefn , 5348351Scael.Fa seekfn 5447014Sbosticand 5548351Scael.Fa closefn 5647014Sbosticmust match those, respectively, of 5748351Scael.Xr read 2 , 5848351Scael.Xr write 2 , 5948351Scael.Xr seek 2 , 6047014Sbosticand 6148351Scael.Xr close 2 6247014Sbosticwith the single exception that they are passed the 6348351Scael.Fa cookie 6447014Sbosticargument specified to 6548351Scael.Fn funopen 6647014Sbosticin place of the traditional file descriptor argument. 6748351Scael.Pp 6848351ScaelRead and write 6948351Scael.Tn I/O 7048351Scaelfunctions are allowed to change the underlying buffer 7147014Sbosticon fully buffered or line buffered streams by calling 7248351Scael.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. 7848351Scael.Pp 7948351ScaelAll user 8048351Scael.Tn I/O 8148351Scaelfunctions can report an error by returning \-1. 8247014SbosticAdditionally, all of the functions should set the external variable 8348351Scael.Va errno 8447014Sbosticappropriately if an error occurs. 8548351Scael.Pp 8647014SbosticAn error on 8748351Scael.Fn closefn 8847014Sbosticdoes not keep the stream open. 8948351Scael.Pp 9048351ScaelAs a convenience, the include file 9148351Scael.Aq Pa stdio.h 9248351Scaeldefines the macros 9348351Scael.Fn fropen 9447014Sbosticand 9548351Scael.Fn fwopen 9647014Sbosticas calls to 9748351Scael.Fn funopen 9847014Sbosticwith only a read or write function specified. 9948351Scael.Sh RETURN VALUES 10047014SbosticUpon successful completion, 10148351Scael.Fn funopen 10248351Scaelreturns a 10348351Scael.Dv FILE 10448351Scaelpointer. 10548351ScaelOtherwise, 10648351Scael.Dv NULL 10748351Scaelis returned and the global variable 10848351Scael.Va errno 10947014Sbosticis set to indicate the error. 11048351Scael.Sh ERRORS 11148351Scael.Bl -tag -width [EINVAL] 11248351Scael.It Bq Er EINVAL 11348351ScaelThe 11448351Scael.Fn funopen 11548351Scaelfunction 11647014Sbosticwas called without either a read or write function. 11748351ScaelThe 11848351Scael.Fn funopen 11948351Scaelfunction 12048351Scaelmay also fail and set 12148351Scael.Va errno 12248351Scaelfor any of the errors 12347014Sbosticspecified for the routine 12448351Scael.Xr malloc 3 . 12548351Scael.El 12648351Scael.Sh SEE ALSO 12748351Scael.Xr fcntl 2 , 12848351Scael.Xr open 2 , 12948351Scael.Xr fclose 3 , 13048351Scael.Xr fopen 3 , 13148351Scael.Xr fseek 3 , 13248351Scael.Xr setbuf 3 13348351Scael.Sh HISTORY 13462886SbosticThe 13562886Sbostic.Fn funopen 13662886Sbosticfunctions first appeared in 4.4BSD. 13748351Scael.Sh BUGS 13848351ScaelThe 13948351Scael.Fn funopen 14048351Scaelfunction 14148351Scaelmay not be portable to systems other than 14248351Scael.Bx . 143