FUNOPEN(3)                     Library Routines                     FUNOPEN(3)




NAME

       funopen, fropen, fwopen - open a stream


SYNOPSIS

       #include <stdio.h>

       FILE  *funopen (void  *cookie, int  (*readfn)(void *, char *, int), int
       (*writefn)(void *, const char *, int), fpos_t (*seekfn)(void *, fpos_t,
       int), int (*closefn)(void *));

       FILE *fropen (void  *cookie, int  (*readfn)(void *, char *, int));

       FILE *fwopen (void  *cookie, int  (*writefn)(void *, char *, int));


DESCRIPTION

       The funopen function associates a stream with up to four I/O functions.
       Either readfn or writefn must be specified; the others can be given  as
       an  appropriately-typed NULL pointer.  These I/O functions will be used
       to read, write, seek and close the new stream.

       In general, omitting a function means that any attempt to  perform  the
       associated  operation  on the resulting stream will fail.  If the close
       function is omitted, closing the stream will flush any buffered  output
       and then succeed.

       The  calling  conventions  of  readfn, writefn, seekfn and closefn must
       match those, respectively, of read(2), write(2), seek(2), and  close(2)
       with  the  single  exception  that  they are passed the cookie argument
       specified to funopen in place of the traditional file descriptor  argu-
       ment.

       Read  and  write  I/O  functions  are  allowed to change the underlying
       buffer  on  fully  buffered  or  line  buffered  streams   by   calling
       setvbuf(3).  They are also not required to completely fill or empty the
       buffer.   They  are  not,  however,  allowed  to  change  streams  from
       unbuffered  to  buffered  or  to change the state of the line buffering
       flag.  They must also be prepared to have read or write calls occur  on
       buffers other than the one most recently specified.

       All  user I/O functions can report an error by returning -1.  Addition-
       ally, all of the functions  should  set  the  external  variable  errno
       appropriately if an error occurs.

       An error on closefn does not keep the stream open.

       As  a convenience, the include file <stdio.h> defines the macros fropen
       and fwopen as calls to funopen with only a read or write function spec-
       ified.


GNO IMPLEMENTATION NOTE

       Since  the  underlying (BSD) implementation makes assumptions about the
       newline character, the returned  stream  is  always  in  text  (newline
       translation)  mode.   If you need to have a stream open in binary mode,
       you must call fsetbinary(3) on the returned file  pointer;  this  state
       information is not carried over from the previous file pointer.


RETURN VALUES

       Upon successful completion, funopen returns a FILE pointer.  Otherwise,
       NULL is returned and the global variable errno is set to  indicate  the
       error.


ERRORS

              EINVAL The  funopen function was called without either a read or
                     write function.  The funopen function may also  fail  and
                     set errno for any of the errors specified for the routine
                     malloc(3).


SEE ALSO

       fcntl(2), open(2), fclose(3), fopen(3), fseek(3),  fsetbinary(3),  set-
       buf(3)


HISTORY

       The funopen functions first appeared in 4.4BSD.


BUGS

       The funopen function may not be portable to systems other than BSD.



GNO                              28 April 1998                      FUNOPEN(3)

Man(1) output converted with man2html