1<html lang="en"> 2<head> 3<title>fopencookie - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Stdio.html#Stdio" title="Stdio"> 9<link rel="prev" href="fopen.html#fopen" title="fopen"> 10<link rel="next" href="fpurge.html#fpurge" title="fpurge"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<meta http-equiv="Content-Style-Type" content="text/css"> 13<style type="text/css"><!-- 14 pre.display { font-family:inherit } 15 pre.format { font-family:inherit } 16 pre.smalldisplay { font-family:inherit; font-size:smaller } 17 pre.smallformat { font-family:inherit; font-size:smaller } 18 pre.smallexample { font-size:smaller } 19 pre.smalllisp { font-size:smaller } 20 span.sc { font-variant:small-caps } 21 span.roman { font-family:serif; font-weight:normal; } 22 span.sansserif { font-family:sans-serif; font-weight:normal; } 23--></style> 24<link rel="stylesheet" type="text/css" href="../cs.css"> 25</head> 26<body> 27<div class="node"> 28<a name="fopencookie"></a> 29<p> 30Next: <a rel="next" accesskey="n" href="fpurge.html#fpurge">fpurge</a>, 31Previous: <a rel="previous" accesskey="p" href="fopen.html#fopen">fopen</a>, 32Up: <a rel="up" accesskey="u" href="Stdio.html#Stdio">Stdio</a> 33<hr> 34</div> 35 36<h3 class="section">4.18 <code>fopencookie</code>—open a stream with custom callbacks</h3> 37 38<p><a name="index-fopencookie-180"></a><strong>Synopsis</strong> 39<pre class="example"> #include <stdio.h> 40 FILE *fopencookie(const void *<var>cookie</var>, const char *<var>mode</var>, 41 cookie_io_functions_t <var>functions</var>); 42 43</pre> 44 <p><strong>Description</strong><br> 45<code>fopencookie</code> creates a <code>FILE</code> stream where I/O is performed using 46custom callbacks. The callbacks are registered via the structure: 47 48 <p>typedef ssize_t (*cookie_read_function_t)(void *_cookie, char *_buf, 49size_t _n); 50typedef ssize_t (*cookie_write_function_t)(void *_cookie, 51const char *_buf, size_t _n); 52typedef int (*cookie_seek_function_t)(void *_cookie, off_t *_off, 53int _whence); 54typedef int (*cookie_close_function_t)(void *_cookie); 55 56<pre class="smallexample"> typedef struct 57 { 58 cookie_read_function_t *read; 59 cookie_write_function_t *write; 60 cookie_seek_function_t *seek; 61 cookie_close_function_t *close; 62 } cookie_io_functions_t; 63</pre> 64 <p>The stream is opened with <var>mode</var> treated as in <code>fopen</code>. The 65callbacks <var>functions.read</var> and <var>functions.write</var> may only be NULL 66when <var>mode</var> does not require them. 67 68 <p><var>functions.read</var> should return -1 on failure, or else the number of 69bytes read (0 on EOF). It is similar to <code>read</code>, except that 70<var>cookie</var> will be passed as the first argument. 71 72 <p><var>functions.write</var> should return -1 on failure, or else the number of 73bytes written. It is similar to <code>write</code>, except that <var>cookie</var> 74will be passed as the first argument. 75 76 <p><var>functions.seek</var> should return -1 on failure, and 0 on success, with 77<var>_off</var> set to the current file position. It is a cross between 78<code>lseek</code> and <code>fseek</code>, with the <var>_whence</var> argument interpreted in 79the same manner. A NULL <var>functions.seek</var> makes the stream behave 80similarly to a pipe in relation to stdio functions that require 81positioning. 82 83 <p><var>functions.close</var> should return -1 on failure, or 0 on success. It 84is similar to <code>close</code>, except that <var>cookie</var> will be passed as the 85first argument. A NULL <var>functions.close</var> merely flushes all data 86then lets <code>fclose</code> succeed. A failed close will still invalidate 87the stream. 88 89 <p>Read and write I/O functions are allowed to change the underlying 90buffer on fully buffered or line buffered streams by calling 91<code>setvbuf</code>. They are also not required to completely fill or empty 92the buffer. They are not, however, allowed to change streams from 93unbuffered to buffered or to change the state of the line buffering 94flag. They must also be prepared to have read or write calls occur on 95buffers other than the one most recently specified. 96 97 <p><br> 98<strong>Returns</strong><br> 99The return value is an open FILE pointer on success. On error, 100<code>NULL</code> is returned, and <code>errno</code> will be set to EINVAL if a 101function pointer is missing or <var>mode</var> is invalid, ENOMEM if the 102stream cannot be created, or EMFILE if too many streams are already 103open. 104 105 <p><br> 106<strong>Portability</strong><br> 107This function is a newlib extension, copying the prototype from Linux. 108It is not portable. See also the <code>funopen</code> interface from BSD. 109 110 <p>Supporting OS subroutines required: <code>sbrk</code>. 111 112 <p><br> 113 114 </body></html> 115 116