2008-09-09 05:48:00 +00:00
|
|
|
.\" Copyright (c) 2008, Linux Foundation, written by Michael Kerrisk
|
|
|
|
.\" <mtk.manpages@gmail.com>
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
2010-05-24 13:18:03 +00:00
|
|
|
.TH FOPENCOOKIE 3 2008-12-05 "Linux" "Linux Programmer's Manual"
|
2008-09-09 05:48:00 +00:00
|
|
|
.SH NAME
|
|
|
|
fopencookie \- opening a custom stream
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
2008-12-05 16:34:02 +00:00
|
|
|
.B #define _GNU_SOURCE
|
2008-09-09 05:48:00 +00:00
|
|
|
.B #include <stdio.h>
|
|
|
|
|
|
|
|
.BI "FILE *fopencookie(void *" cookie ", const char *" mode ,
|
|
|
|
.BI " cookie_io_functions_t " io_funcs );
|
|
|
|
.fi
|
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
|
|
|
.BR fopencookie ()
|
|
|
|
function allows the programmer to create a custom implementation
|
|
|
|
for a standard I/O stream.
|
|
|
|
This implementation can store the stream's data at a location of
|
|
|
|
its own choosing; for example,
|
|
|
|
.BR fopencookie ()
|
|
|
|
is used to implement
|
|
|
|
.BR fmemopen (3),
|
2009-12-05 05:11:59 +00:00
|
|
|
which provides a stream interface to data that is stored in a
|
2008-09-09 05:48:00 +00:00
|
|
|
buffer in memory.
|
|
|
|
|
|
|
|
In order to create a custom stream the programmer must:
|
|
|
|
.IP * 3
|
|
|
|
Implement four "hook" functions that are used internally by the
|
|
|
|
standard I/O library when performing I/O on the stream.
|
|
|
|
.IP *
|
|
|
|
Define a "cookie" data type,
|
|
|
|
a structure that provides bookkeeping information
|
|
|
|
(e.g., where to store data) used by the aforementioned hook functions.
|
|
|
|
The standard I/O package knows nothing about the contents of this cookie
|
|
|
|
(thus it is typed as
|
|
|
|
.IR "void\ *"
|
|
|
|
when passed to
|
|
|
|
.BR fopencookie ()),
|
|
|
|
but automatically supplies the cookie
|
|
|
|
as the first argument when calling the hook functions.
|
|
|
|
.IP *
|
|
|
|
Call
|
|
|
|
.BR fopencookie ()
|
|
|
|
to open a new stream and associate the cookie and hook functions
|
|
|
|
with that stream.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.BR fopencookie ()
|
|
|
|
function serves a purpose similar to
|
|
|
|
.BR fopen (3):
|
2008-09-10 12:39:34 +00:00
|
|
|
it opens a new stream and returns a pointer to a
|
2008-09-09 05:48:00 +00:00
|
|
|
.I FILE
|
|
|
|
object that is used to operate on that stream.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I cookie
|
|
|
|
argument is a pointer to the caller's cookie structure
|
|
|
|
that is to be associated with the new stream.
|
|
|
|
This pointer is supplied as the first argument when the standard I/O
|
|
|
|
library invokes any of the hook functions described below.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I mode
|
|
|
|
argument serves the same purpose as for
|
|
|
|
.BR fopen (3).
|
|
|
|
The following modes are supported:
|
|
|
|
.IR r ,
|
|
|
|
.IR w ,
|
|
|
|
.IR a ,
|
|
|
|
.IR r+ ,
|
|
|
|
.IR w+ ,
|
|
|
|
and
|
|
|
|
.IR a+ .
|
|
|
|
See
|
|
|
|
.BR fopen (3)
|
|
|
|
for details.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I io_funcs
|
|
|
|
argument is a structure that contains four fields pointing to the
|
|
|
|
programmer-defined hook functions that are used to implement this stream.
|
|
|
|
The structure is defined as follows
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
|
|
|
|
struct cookie_io_functions_t {
|
|
|
|
cookie_read_function_t *read;
|
|
|
|
cookie_write_function_t *write;
|
|
|
|
cookie_seek_function_t *seek;
|
|
|
|
cookie_close_function_t *close;
|
|
|
|
};
|
|
|
|
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
The four fields are as follows:
|
|
|
|
.TP
|
|
|
|
.I cookie_read_function_t *read
|
|
|
|
This function implements read operations for the stream.
|
|
|
|
When called, it receives three arguments:
|
|
|
|
|
|
|
|
ssize_t read(void *cookie, char *buf, size_t size);
|
|
|
|
|
|
|
|
The
|
|
|
|
.I buf
|
|
|
|
and
|
|
|
|
.I size
|
|
|
|
arguments are, respectively,
|
|
|
|
a buffer into which input data can be placed and the size of that buffer.
|
|
|
|
As its function result, the
|
|
|
|
.I read
|
|
|
|
function should return the number of bytes copied into
|
|
|
|
.IR buf ,
|
|
|
|
0 on end of file, or \-1 on error.
|
|
|
|
The
|
|
|
|
.I read
|
|
|
|
function should update the stream offset appropriately.
|
|
|
|
|
|
|
|
If
|
|
|
|
.I *read
|
|
|
|
is a NULL pointer,
|
|
|
|
then reads from the custom stream always return end of file.
|
|
|
|
.TP
|
|
|
|
.I cookie_write_function_t *write
|
|
|
|
This function implements write operations for the stream.
|
|
|
|
When called, it receives three arguments:
|
|
|
|
|
|
|
|
ssize_t write(void *cookie, const char *buf, size_t size);
|
|
|
|
|
|
|
|
The
|
|
|
|
.I buf
|
|
|
|
and
|
|
|
|
.I size
|
|
|
|
arguments are, respectively,
|
|
|
|
a buffer of data to be output to the stream and the size of that buffer.
|
|
|
|
As its function result, the
|
|
|
|
.I write
|
|
|
|
function should return the number of bytes copied from
|
|
|
|
.IR buf ,
|
|
|
|
or \-1 on error.
|
|
|
|
The
|
|
|
|
.I write
|
|
|
|
function should update the stream offset appropriately.
|
|
|
|
|
|
|
|
If
|
|
|
|
.I *write
|
|
|
|
is a NULL pointer,
|
|
|
|
then output to the stream is discarded.
|
|
|
|
.TP
|
|
|
|
.I cookie_seek_function_t *seek
|
|
|
|
This function implements seek operations on the stream.
|
|
|
|
When called, it receives three arguments:
|
|
|
|
|
|
|
|
int seek(void *cookie, off64_t *offset, int whence);
|
|
|
|
|
|
|
|
The
|
|
|
|
.I *offset
|
|
|
|
argument specifies the new file offset depending on which
|
|
|
|
of the following three values is supplied in
|
|
|
|
.IR whence :
|
|
|
|
.RS
|
|
|
|
.TP 10
|
|
|
|
.B SEEK_SET
|
|
|
|
The stream offset should be set
|
|
|
|
.I *offset
|
|
|
|
bytes from the start of the stream.
|
|
|
|
.TP
|
|
|
|
.B SEEK_CUR
|
|
|
|
.I *offset
|
|
|
|
should be added to the current stream offset.
|
|
|
|
.TP
|
|
|
|
.B SEEK_END
|
|
|
|
The stream offset should be set to the size of the stream plus
|
|
|
|
.IR *offset .
|
|
|
|
.RE
|
|
|
|
.IP
|
|
|
|
Before returning, the
|
|
|
|
.I seek
|
|
|
|
function should update
|
|
|
|
.I *offset
|
|
|
|
to indicate the new stream offset.
|
|
|
|
|
|
|
|
As its function result, the
|
|
|
|
.I seek
|
|
|
|
function should return 0 on success, and \-1 on error.
|
|
|
|
|
|
|
|
If
|
|
|
|
.I *seek
|
|
|
|
is a NULL pointer,
|
|
|
|
then it is not possible to perform seek operations on the stream.
|
|
|
|
.TP
|
|
|
|
.I cookie_close_function_t *close
|
|
|
|
This function closes the stream.
|
|
|
|
The hook function can do things such as freeing buffers allocated
|
|
|
|
for the stream.
|
|
|
|
When called, it receives one argument:
|
|
|
|
|
|
|
|
int close(void *cookie);
|
|
|
|
|
|
|
|
The
|
|
|
|
.I cookie
|
|
|
|
argument is the cookie that the programmer supplied when calling
|
|
|
|
.BR fopencookie ().
|
|
|
|
|
|
|
|
As its function result, the
|
|
|
|
.I close
|
|
|
|
function should return 0 on success, and
|
|
|
|
.B EOF
|
|
|
|
on error.
|
|
|
|
|
|
|
|
If
|
|
|
|
.I *close
|
|
|
|
is NULL, then no special action is performed when the stream is closed.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success
|
|
|
|
.BR fopencookie ()
|
|
|
|
returns a pointer to the new stream.
|
|
|
|
On error, NULL is returned.
|
|
|
|
.\" .SH ERRORS
|
|
|
|
.\" It's not clear if errno ever gets set...
|
|
|
|
.SH CONFORMING TO
|
accept.2, execve.2, futimesat.2, getresuid.2, getrlimit.2, madvise.2, mq_getsetattr.2, msgctl.2, nice.2, open.2, poll.2, setresuid.2, shmctl.2, sigaction.2, times.2, utimensat.2, __setfpucw.3, atoi.3, endian.3, err.3, euidaccess.3, fenv.3, fopencookie.3, fpurge.3, getgrouplist.3, getutmp.3, j0.3, lgamma.3, netlink.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_cleanup_push_defer_np.3, pthread_getattr_np.3, pthread_kill_other_threads_np.3, pthread_setaffinity_np.3, pthread_tryjoin_np.3, pthread_yield.3, random_r.3, readdir.3, rtnetlink.3, scanf.3, setenv.3, significand.3, sigsetops.3, strerror.3, strstr.3, sysv_signal.3, termios.3, timegm.3, unlocked_stdio.3, y0.3, locale.5, bootparam.7, feature_test_macros.7, ip.7, locale.7, pthreads.7, rtld-audit.7, nscd.8: Global fix: s/non-standard/nonstandard/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:37:52 +00:00
|
|
|
This function is a nonstandard GNU extension.
|
2008-09-09 05:48:00 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
The program below implements a custom stream whose functionality
|
|
|
|
is similar (but not identical) to that available via
|
|
|
|
.BR fmemopen (3).
|
|
|
|
It implements a stream whose data is stored in a memory buffer.
|
|
|
|
The program writes its command-line arguments to the stream,
|
|
|
|
and then seeks through the stream reading two out of every
|
|
|
|
five characters and writing them to standard output.
|
|
|
|
The following shell session demonstrates the use of the program:
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
|
eventfd.2, execve.2, getdents.2, ioprio_set.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, malloc.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5, proc.5, cpuset.7, mq_overview.7: Global fix: Format user input in shell sessions in boldface
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-10-28 15:37:22 +00:00
|
|
|
.RB "$" " ./a.out \(aqhello world\(aq"
|
2008-09-09 05:48:00 +00:00
|
|
|
/he/
|
|
|
|
/ w/
|
|
|
|
/d/
|
|
|
|
Reached end of file
|
|
|
|
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
Note that a more general version of the program below
|
|
|
|
could be improved to more robustly handle various error situations
|
|
|
|
(e.g., opening a stream with a cookie that already has an open stream;
|
|
|
|
closing a stream that has already been closed).
|
eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strtol.3, core.5: global fix: Add ".SS Program source" to EXAMPLE
Add ".SS Program source" to clearly distinguish shell session and
descriptive text from actual program code.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-10-28 15:51:05 +00:00
|
|
|
.SS Program source
|
eventfd.2, getdents.2, mprotect.2, signalfd.2, timerfd_create.2, wait.2, backtrace.3, clock_getcpuclockid.3, end.3, fmemopen.3, fopencookie.3, frexp.3, getaddrinfo.3, getdate.3, getgrouplist.3, getprotoent_r.3, getservent_r.3, gnu_get_libc_version.3, inet.3, inet_pton.3, makecontext.3, matherr.3, offsetof.3, pthread_attr_init.3, pthread_create.3, pthread_getattr_np.3, sem_wait.3, strftime.3, strtok.3, strtol.3, core.5: srcfix
s/\.R " "/\\\&/ as a way of getting a blank line after a .SS heading.
(Suggested by Sam Varshavchik <mrsam@courier-mta.com>)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2008-11-05 01:42:45 +00:00
|
|
|
\&
|
2008-09-09 05:48:00 +00:00
|
|
|
.nf
|
|
|
|
#define _GNU_SOURCE
|
|
|
|
#include <sys/types.h>
|
|
|
|
#include <stdio.h>
|
|
|
|
#include <stdlib.h>
|
|
|
|
#include <unistd.h>
|
|
|
|
#include <string.h>
|
|
|
|
|
|
|
|
#define INIT_BUF_SIZE 4
|
|
|
|
|
|
|
|
struct memfile_cookie {
|
|
|
|
char *buf; /* Dynamically sized buffer for data */
|
|
|
|
size_t allocated; /* Size of buf */
|
|
|
|
size_t endpos; /* Number of characters in buf */
|
|
|
|
off_t offset; /* Current file offset in buf */
|
|
|
|
};
|
|
|
|
|
|
|
|
ssize_t
|
|
|
|
memfile_write(void *c, const char *buf, size_t size)
|
|
|
|
{
|
|
|
|
char *new_buff;
|
|
|
|
struct memfile_cookie *cookie = c;
|
|
|
|
|
|
|
|
/* Buffer too small? Keep doubling size until big enough */
|
|
|
|
|
|
|
|
while (size + cookie\->offset > cookie->allocated) {
|
|
|
|
new_buff = realloc(cookie\->buf, cookie->allocated * 2);
|
|
|
|
if (new_buff == NULL) {
|
|
|
|
return \-1;
|
|
|
|
} else {
|
|
|
|
cookie\->allocated *= 2;
|
|
|
|
cookie\->buf = new_buff;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
memcpy(cookie\->buf + cookie->offset, buf, size);
|
|
|
|
|
|
|
|
cookie\->offset += size;
|
|
|
|
if (cookie\->offset > cookie->endpos)
|
|
|
|
cookie\->endpos = cookie->offset;
|
|
|
|
|
|
|
|
return size;
|
|
|
|
}
|
|
|
|
|
|
|
|
ssize_t
|
|
|
|
memfile_read(void *c, char *buf, size_t size)
|
|
|
|
{
|
|
|
|
ssize_t xbytes;
|
|
|
|
struct memfile_cookie *cookie = c;
|
|
|
|
|
|
|
|
/* Fetch minimum of bytes requested and bytes available */
|
|
|
|
|
|
|
|
xbytes = size;
|
|
|
|
if (cookie\->offset + size > cookie->endpos)
|
|
|
|
xbytes = cookie\->endpos - cookie->offset;
|
|
|
|
if (xbytes < 0) /* offset may be past endpos */
|
|
|
|
xbytes = 0;
|
|
|
|
|
2008-09-10 12:39:34 +00:00
|
|
|
memcpy(buf, cookie\->buf + cookie->offset, xbytes);
|
2008-09-09 05:48:00 +00:00
|
|
|
|
|
|
|
cookie\->offset += xbytes;
|
|
|
|
return xbytes;
|
|
|
|
}
|
|
|
|
|
|
|
|
int
|
|
|
|
memfile_seek(void *c, off64_t *offset, int whence)
|
|
|
|
{
|
|
|
|
off64_t new_offset;
|
|
|
|
struct memfile_cookie *cookie = c;
|
|
|
|
|
|
|
|
if (whence == SEEK_SET)
|
|
|
|
new_offset = *offset;
|
|
|
|
else if (whence == SEEK_END)
|
|
|
|
new_offset = cookie\->endpos + *offset;
|
|
|
|
else if (whence == SEEK_CUR)
|
|
|
|
new_offset = cookie\->offset + *offset;
|
|
|
|
else
|
|
|
|
return \-1;
|
|
|
|
|
|
|
|
if (new_offset < 0)
|
|
|
|
return \-1;
|
|
|
|
|
|
|
|
cookie\->offset = new_offset;
|
|
|
|
*offset = new_offset;
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
|
|
|
|
int
|
|
|
|
memfile_close(void *c)
|
|
|
|
{
|
|
|
|
struct memfile_cookie *cookie = c;
|
|
|
|
|
|
|
|
free(cookie\->buf);
|
|
|
|
cookie\->allocated = 0;
|
|
|
|
cookie\->buf = NULL;
|
|
|
|
|
|
|
|
return 0;
|
|
|
|
}
|
|
|
|
|
|
|
|
int
|
|
|
|
main(int argc, char *argv[])
|
|
|
|
{
|
|
|
|
cookie_io_functions_t memfile_func = {
|
|
|
|
.read = memfile_read,
|
|
|
|
.write = memfile_write,
|
|
|
|
.seek = memfile_seek,
|
|
|
|
.close = memfile_close
|
|
|
|
};
|
|
|
|
FILE *fp;
|
|
|
|
struct memfile_cookie mycookie;
|
|
|
|
ssize_t nread;
|
|
|
|
long p;
|
|
|
|
int j;
|
|
|
|
char buf[1000];
|
|
|
|
|
|
|
|
/* Set up the cookie before calling fopencookie() */
|
|
|
|
|
|
|
|
mycookie.buf = malloc(INIT_BUF_SIZE);
|
|
|
|
if (mycookie.buf == NULL) {
|
|
|
|
perror("malloc");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
|
|
|
|
mycookie.allocated = INIT_BUF_SIZE;
|
|
|
|
mycookie.offset = 0;
|
|
|
|
mycookie.endpos = 0;
|
|
|
|
|
|
|
|
fp = fopencookie(&mycookie,"w+", memfile_func);
|
|
|
|
if (fp == NULL) {
|
|
|
|
perror("fopencookie");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
|
2008-09-10 12:39:34 +00:00
|
|
|
/* Write command\-line arguments to our file */
|
2008-09-09 05:48:00 +00:00
|
|
|
|
|
|
|
for (j = 1; j < argc; j++)
|
|
|
|
if (fputs(argv[j], fp) == EOF) {
|
|
|
|
perror("fputs");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
|
|
|
|
/* Read two bytes out of every five, until EOF */
|
|
|
|
|
|
|
|
for (p = 0; ; p += 5) {
|
|
|
|
if (fseek(fp, p, SEEK_SET) == \-1) {
|
|
|
|
perror("fseek");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
nread = fread(buf, 1, 2, fp);
|
|
|
|
if (nread == \-1) {
|
|
|
|
perror("fread");
|
|
|
|
exit(EXIT_FAILURE);
|
|
|
|
}
|
|
|
|
if (nread == 0) {
|
|
|
|
printf("Reached end of file\\n");
|
|
|
|
break;
|
|
|
|
}
|
|
|
|
|
|
|
|
printf("/%.*s/\\n", nread, buf);
|
|
|
|
}
|
|
|
|
|
|
|
|
exit(EXIT_SUCCESS);
|
|
|
|
}
|
|
|
|
.fi
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR fclose (3),
|
|
|
|
.BR fmemopen (3),
|
|
|
|
.BR fopen (3),
|
2008-12-05 16:34:02 +00:00
|
|
|
.BR fseek (3),
|
|
|
|
.BR feature_test_macros (7)
|