1<html lang="en"> 2<head> 3<title>funopen - 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="ftell.html#ftell" title="ftell"> 10<link rel="next" href="fwide.html#fwide" title="fwide"> 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="funopen"></a> 29<p> 30Next: <a rel="next" accesskey="n" href="fwide.html#fwide">fwide</a>, 31Previous: <a rel="previous" accesskey="p" href="ftell.html#ftell">ftell</a>, 32Up: <a rel="up" accesskey="u" href="Stdio.html#Stdio">Stdio</a> 33<hr> 34</div> 35 36<h3 class="section">4.29 <code>funopen</code>, <code>fropen</code>, <code>fwopen</code>—open a stream with custom callbacks</h3> 37 38<p><a name="index-funopen-208"></a><a name="index-fropen-209"></a><a name="index-fwopen-210"></a><strong>Synopsis</strong> 39<pre class="example"> #include <stdio.h> 40 FILE *funopen(const void *<var>cookie</var>, 41 int (*<var>readfn</var>) (void *cookie, char *buf, int n), 42 int (*<var>writefn</var>) (void *cookie, const char *buf, int n), 43 fpos_t (*<var>seekfn</var>) (void *cookie, fpos_t off, int whence), 44 int (*<var>closefn</var>) (void *cookie)); 45 FILE *fropen(const void *<var>cookie</var>, 46 int (*<var>readfn</var>) (void *cookie, char *buf, int n)); 47 FILE *fwopen(const void *<var>cookie</var>, 48 int (*<var>writefn</var>) (void *cookie, const char *buf, int n)); 49 50</pre> 51 <p><strong>Description</strong><br> 52<code>funopen</code> creates a <code>FILE</code> stream where I/O is performed using 53custom callbacks. At least one of <var>readfn</var> and <var>writefn</var> must be 54provided, which determines whether the stream behaves with mode <"r">, 55<"w">, or <"r+">. 56 57 <p><var>readfn</var> should return -1 on failure, or else the number of bytes 58read (0 on EOF). It is similar to <code>read</code>, except that <int> rather 59than <size_t> bounds a transaction size, and <var>cookie</var> will be passed 60as the first argument. A NULL <var>readfn</var> makes attempts to read the 61stream fail. 62 63 <p><var>writefn</var> should return -1 on failure, or else the number of bytes 64written. It is similar to <code>write</code>, except that <int> rather than 65<size_t> bounds a transaction size, and <var>cookie</var> will be passed as 66the first argument. A NULL <var>writefn</var> makes attempts to write the 67stream fail. 68 69 <p><var>seekfn</var> should return (fpos_t)-1 on failure, or else the current 70file position. It is similar to <code>lseek</code>, except that <var>cookie</var> 71will be passed as the first argument. A NULL <var>seekfn</var> makes the 72stream behave similarly to a pipe in relation to stdio functions that 73require positioning. This implementation assumes fpos_t and off_t are 74the same type. 75 76 <p><var>closefn</var> should return -1 on failure, or 0 on success. It is 77similar to <code>close</code>, except that <var>cookie</var> will be passed as the 78first argument. A NULL <var>closefn</var> merely flushes all data then lets 79<code>fclose</code> succeed. A failed close will still invalidate the stream. 80 81 <p>Read and write I/O functions are allowed to change the underlying 82buffer on fully buffered or line buffered streams by calling 83<code>setvbuf</code>. They are also not required to completely fill or empty 84the buffer. They are not, however, allowed to change streams from 85unbuffered to buffered or to change the state of the line buffering 86flag. They must also be prepared to have read or write calls occur on 87buffers other than the one most recently specified. 88 89 <p>The functions <code>fropen</code> and <code>fwopen</code> are convenience macros around 90<code>funopen</code> that only use the specified callback. 91 92 <p><br> 93<strong>Returns</strong><br> 94The return value is an open FILE pointer on success. On error, 95<code>NULL</code> is returned, and <code>errno</code> will be set to EINVAL if a 96function pointer is missing, ENOMEM if the stream cannot be created, 97or EMFILE if too many streams are already open. 98 99 <p><br> 100<strong>Portability</strong><br> 101This function is a newlib extension, copying the prototype from BSD. 102It is not portable. See also the <code>fopencookie</code> interface from Linux. 103 104 <p>Supporting OS subroutines required: <code>sbrk</code>. 105 106 <p><br> 107 108 </body></html> 109 110