| <html lang="en"> |
| <head> |
| <title>funopen - Untitled</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Untitled"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Stdio.html#Stdio" title="Stdio"> |
| <link rel="prev" href="ftell.html#ftell" title="ftell"> |
| <link rel="next" href="fwide.html#fwide" title="fwide"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="funopen"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="fwide.html#fwide">fwide</a>, |
| Previous: <a rel="previous" accesskey="p" href="ftell.html#ftell">ftell</a>, |
| Up: <a rel="up" accesskey="u" href="Stdio.html#Stdio">Stdio</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">4.29 <code>funopen</code>, <code>fropen</code>, <code>fwopen</code>—open a stream with custom callbacks</h3> |
| |
| <p><a name="index-funopen-208"></a><a name="index-fropen-209"></a><a name="index-fwopen-210"></a><strong>Synopsis</strong> |
| <pre class="example"> #include <stdio.h> |
| FILE *funopen(const void *<var>cookie</var>, |
| int (*<var>readfn</var>) (void *cookie, char *buf, int n), |
| int (*<var>writefn</var>) (void *cookie, const char *buf, int n), |
| fpos_t (*<var>seekfn</var>) (void *cookie, fpos_t off, int whence), |
| int (*<var>closefn</var>) (void *cookie)); |
| FILE *fropen(const void *<var>cookie</var>, |
| int (*<var>readfn</var>) (void *cookie, char *buf, int n)); |
| FILE *fwopen(const void *<var>cookie</var>, |
| int (*<var>writefn</var>) (void *cookie, const char *buf, int n)); |
| |
| </pre> |
| <p><strong>Description</strong><br> |
| <code>funopen</code> creates a <code>FILE</code> stream where I/O is performed using |
| custom callbacks. At least one of <var>readfn</var> and <var>writefn</var> must be |
| provided, which determines whether the stream behaves with mode <"r">, |
| <"w">, or <"r+">. |
| |
| <p><var>readfn</var> should return -1 on failure, or else the number of bytes |
| read (0 on EOF). It is similar to <code>read</code>, except that <int> rather |
| than <size_t> bounds a transaction size, and <var>cookie</var> will be passed |
| as the first argument. A NULL <var>readfn</var> makes attempts to read the |
| stream fail. |
| |
| <p><var>writefn</var> should return -1 on failure, or else the number of bytes |
| written. It is similar to <code>write</code>, except that <int> rather than |
| <size_t> bounds a transaction size, and <var>cookie</var> will be passed as |
| the first argument. A NULL <var>writefn</var> makes attempts to write the |
| stream fail. |
| |
| <p><var>seekfn</var> should return (fpos_t)-1 on failure, or else the current |
| file position. It is similar to <code>lseek</code>, except that <var>cookie</var> |
| will be passed as the first argument. A NULL <var>seekfn</var> makes the |
| stream behave similarly to a pipe in relation to stdio functions that |
| require positioning. This implementation assumes fpos_t and off_t are |
| the same type. |
| |
| <p><var>closefn</var> should return -1 on failure, or 0 on success. It is |
| similar to <code>close</code>, except that <var>cookie</var> will be passed as the |
| first argument. A NULL <var>closefn</var> merely flushes all data then lets |
| <code>fclose</code> succeed. A failed close will still invalidate the stream. |
| |
| <p>Read and write I/O functions are allowed to change the underlying |
| buffer on fully buffered or line buffered streams by calling |
| <code>setvbuf</code>. They are also not required to completely fill or empty |
| the buffer. They are not, however, allowed to change streams from |
| unbuffered to buffered or to change the state of the line buffering |
| flag. They must also be prepared to have read or write calls occur on |
| buffers other than the one most recently specified. |
| |
| <p>The functions <code>fropen</code> and <code>fwopen</code> are convenience macros around |
| <code>funopen</code> that only use the specified callback. |
| |
| <p><br> |
| <strong>Returns</strong><br> |
| The return value is an open FILE pointer on success. On error, |
| <code>NULL</code> is returned, and <code>errno</code> will be set to EINVAL if a |
| function pointer is missing, ENOMEM if the stream cannot be created, |
| or EMFILE if too many streams are already open. |
| |
| <p><br> |
| <strong>Portability</strong><br> |
| This function is a newlib extension, copying the prototype from BSD. |
| It is not portable. See also the <code>fopencookie</code> interface from Linux. |
| |
| <p>Supporting OS subroutines required: <code>sbrk</code>. |
| |
| <p><br> |
| |
| </body></html> |
| |
