Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
FOPENCOOKIE(3)		     Library Functions Manual		  FOPENCOOKIE(3)

NAME
     fopencookie -- open a stream

LIBRARY
     Standard C Library (libc, -lc)

SYNOPSIS
     #include <stdio.h>

     typedef ssize_t
     (*cookie_read_function_t)(void *cookie, char *buf, size_t size);

     typedef ssize_t
     (*cookie_write_function_t)(void *cookie, const char *buf, size_t size);

     typedef int
     (*cookie_seek_function_t)(void *cookie, off64_t *offset, int whence);

     typedef int
     (*cookie_close_function_t)(void *cookie);

     typedef struct {
	     cookie_read_function_t  *read;
	     cookie_write_function_t *write;
	     cookie_seek_function_t  *seek;
	     cookie_close_function_t *close;
     } cookie_io_functions_t;

     FILE *
     fopencookie(void *cookie, const char *mode,
	 cookie_io_functions_t io_funcs);

DESCRIPTION
     The  fopencookie  function  associates  a	stream	with  up  to  four  "I/O
     functions".  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 asso-
     ciated  operation on the resulting stream will fail.  If the write function
     is omitted, data written to the stream is discarded.  If the close function
     is omitted, closing the stream will flush any buffered output and then suc-
     ceed.

     The calling conventions of read, write, and close must match those, respec-
     tively, of read(2), write(2), and close(2) with the single  exception  that
     they  are	passed	the cookie argument specified to fopencookie in place of
     the traditional file descriptor argument.	The seek  function  updates  the
     current stream offset using *offset and whence.  If *offset is non-NULL, it
     updates *offset with the current stream offset.

     fopencookie  is implemented as a thin shim around the funopen(3) interface.
     Limitations, possibilities, and requirements of  that  interface  apply  to
     fopencookie.

RETURN VALUES
     Upon successful completion, fopencookie returns a FILE pointer.  Otherwise,
     NULL  is  returned and the global variable errno is set to indicate the er-
     ror.

ERRORS
     [EINVAL]		A bogus mode was provided to fopencookie.

     [ENOMEM]		The fopencookie function may fail and set errno for  any
			of the errors specified for the malloc(3) routine.

SEE ALSO
     fcntl(2), open(2), fclose(3), fopen(3), fseek(3), funopen(3)

HISTORY
     The funopen() functions first appeared in 4.4BSD.	The fopencookie function
     first appeared in FreeBSD 11.

BUGS
     The  fopencookie  function  is a nonstandard glibc extension and may not be
     portable to systems other than FreeBSD and Linux.

FreeBSD ports 15.quarterly	   May 9, 2016			  FOPENCOOKIE(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=fopencookie&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>

home | help