FreeBSD Manual Pages

FOPENCOOKIE(3) BSD Library Functions Manual FOPENCOOKIE(3)
NAMEfopencookie -- open a stream
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS#include <stdio.h>
typedefssize_t(*cookie_read_function_t)(void*cookie, char*buf, size_tsize);
typedefssize_t(*cookie_write_function_t)(void*cookie, constchar*buf, size_tsize);
typedefint(*cookie_seek_function_t)(void*cookie, off64_t*offset, intwhence);
typedefint(*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, constchar*mode,
cookie_io_functions_tio_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 as-
sociated operation on the resulting stream will fail. If the write func-
tion 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 succeed.
The calling conventions of read, write, and close must match those, re-
spectively, 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 up-
dates 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) inter-
face. Limitations, possibilities, and requirements of that interface ap-
ply to fopencookie.
RETURN VALUES
Upon successful completion, fopencookie returns a FILE pointer. Other-
wise, NULL is returned and the global variable errno is set to indicate
the error.
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 ALSOfcntl(2), open(2), fclose(3), fopen(3), fseek(3), funopen(3)HISTORY
The funopen() functions first appeared in 4.4BSD. The fopencookie func-
tion 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.
BSD May 9, 2016 BSD