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 buf‐
       fer 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  ap‐
       propriately 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)