Package: manpages-dev Version: 3.05-1 Followup-For: Bug #182706 Hi,
Well i wrote the manpage for fopencookie from one i found, but that was formatted badly and incomplete (the URL is the manpage header). No problem for licensing, the original author licensed it as GPL. All the sources used for making the manpage are commented in the it. Usually i don't write manpages for sections 2/3, so tell me if something is wrong about formatting, it can be useful for future use. I attach it. Regards, ---- François Wendling <[EMAIL PROTECTED]> IRC : [EMAIL PROTECTED]/OFTC
.\" Copyright 2002 walter harms ([EMAIL PROTECTED]) .\" Distributed under GPL. Original Verson : .\" http://www.freiburg.linux.de/projekte/manpages/man/fopencookie/fopencookie.3 .\" .\" François Wendling <[EMAIL PROTECTED]> - 09/05/2008 .\" * changed the layout .\" * added compatibility mode .\" * added Authors section and Debian notice (It's _NOT_ an upstream .\" manpage) .\" * changed description and cookie info with docs from GNU .\" doc (http://www.delorie.com/gnu/docs/glibc/libc_231.html) .TH fopencookie 3 2008-09-04 "" "CUSTOM STREAMS" .SH NAME fopencookie \- open a custom stream .SH SYNOPSIS .sp .B #define _GNU_SOURCE .br .B #include <stdio.h> .sp .BI "FILE * fopencookie (void *" cookie ", const char *" mode "," .br .BI " cookie_io_functions_t " io-functions " );" .SH DESCRIPTION Inside every custom stream is a special object called the cookie. This is an object supplied by you which records where to fetch or store the data read or written. It is up to you to define a data type to use for the cookie. The stream functions in the library never refer directly to its contents, and they don't even know what the type is; they record its address with type void *. .PP To implement a custom stream, you must specify how to fetch or store the data in the specified place. You do this by defining hook functions to read, write, change "file position", and close the stream. All four of these functions will be passed the stream's cookie so they can tell where to fetch or store the data. The library functions don't know what's inside the cookie, but your functions will know. .PP When you create a custom stream, you must specify the cookie pointer, and also the four hook functions stored in a structure of type \fBcookie_io_functions_t\fR. .SS "Cookie Structure" \x'-1' .nf /* The structure with the cookie function pointers. */ typedef struct { cookie_read_function_t *read; /* Read cookie */ cookie_write_function_t *write; /* Write cookie */ cookie_seek_function_t *seek; /* Seek/tell file position */ cookie_close_function_t *close; /* Close file */ } cookie_io_functions_t ; .fi .SS "Cookie io-functions" \x'-1' .TP .BI cookie_read_function_t \ \fR*\fIread This is the function that reads data from the cookie. If the value is a null pointer instead of a function, then read operations on ths stream always return EOF. .TP .BI cookie_write_function_t \ \fR*\fIwrite This is the function that writes data to the cookie. If the value is a null pointer instead of a function, then data written to the stream is discarded. .TP .BI cookie_seek_function_t \ \fR*\fIseek This is the function that performs the equivalent of file positioning on the cookie. If the value is a null pointer instead of a function, calls to fseek on this stream can only seek to locations within the buffer; any attempt to seek outside the buffer will return an ESPIPE error. .TP .BI cookie_close_function_t \ \fR*\fIclose This function performs any appropriate cleanup on the cookie when closing the stream. If the value is a null pointer instead of a function, nothing special is done to close the cookie when the stream is closed. .SH "RETURN VALUE" The .BR fopencookie () function returns NULL on error. .SH EXAMPLE The example will install dummy functions that print only there name. The main() function will trigger all of them. .sp .nf #define _GNU_SOURCE #include <stdio.h> #include <stdlib.h> struct my_FILE { int foo; }; ssize_t my_write(void *FILE, const char *buf, size_t size) { puts(__func__); return 0; } ssize_t my_read(void *FILE, char *buf, size_t size) { puts(__func__); return 0; } int my_seek (void *FILE ,off64_t *position ,int whence ) { puts(__func__); return 0; } int my_close(void *FILE) { puts(__func__); return 0; } int main() { cookie_io_functions_t my_func = { .read=my_read, .write=my_write, .seek=my_seek, .close=my_close }; FILE *fp; char *buf; struct my_FILE *cookie=calloc(1,sizeof(struct my_FILE)); fp=fopencookie(cookie,"r+",my_func); setbuf(fp,NULL); /* disable buffering */ fprintf(fp,"foo"); /* my_write */ rewind(fp); /* my_seek */ fread(buf,1,1,fp); /* my_read */ fclose(fp); /* my_close */ return 0; } .fi .PP Please beware that this example has no error checking. .SH "SEE ALSO" .BR fmemopen (3), .BR fwrite (3), .BR fseek (3), .BR fread (3), .BR fopen (3) .SH "COMPATIBILITY" .\" src : http://www.update.uu.se/~ams/home/gnulib/doc/glibc-functions/ .PP This function is missing on all non-glibc platforms: MacOS X 10.3, FreeBSD 6.0, NetBSD 3.0, OpenBSD 3.8, AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 10, Cygwin, mingw, Interix 3.5, BeOS. .SH AUTHORS This manual page was written by Walter Harms <[EMAIL PROTECTED]> in 2002, and updated by Francois Wendling <[EMAIL PROTECTED]> for the Debian GNU/Linux system (but may be used by others).
