1.\" Copyright (c) 2016, EMC / Isilon Storage Division 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS 14.\" IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 15.\" THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 16.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR 17.\" CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 18.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 19.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 20.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 21.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 22.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 23.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd May 9, 2016 28.Dt FOPENCOOKIE 3 29.Os 30.Sh NAME 31.Nm fopencookie 32.Nd open a stream 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In stdio.h 37.Ft typedef ssize_t 38.Fn (*cookie_read_function_t) "void *cookie" "char *buf" "size_t size" 39.Ft typedef ssize_t 40.Fn (*cookie_write_function_t) "void *cookie" "const char *buf" "size_t size" 41.Ft typedef int 42.Fn (*cookie_seek_function_t) "void *cookie" "off64_t *offset" "int whence" 43.Ft typedef int 44.Fn (*cookie_close_function_t) "void *cookie" 45.Bd -literal 46typedef struct { 47 cookie_read_function_t *read; 48 cookie_write_function_t *write; 49 cookie_seek_function_t *seek; 50 cookie_close_function_t *close; 51} cookie_io_functions_t; 52.Ed 53.Ft FILE * 54.Fn fopencookie "void *cookie" "const char *mode" "cookie_io_functions_t io_funcs" 55.Sh DESCRIPTION 56The 57.Nm 58function 59associates a stream with up to four 60.Dq Tn I/O No functions . 61These 62.Tn I/O 63functions will be used to read, write, seek and 64close the new stream. 65.Pp 66In general, omitting a function means that any attempt to perform the 67associated operation on the resulting stream will fail. 68If the write function is omitted, data written to the stream is discarded. 69If the close function is omitted, closing the stream will flush 70any buffered output and then succeed. 71.Pp 72The calling conventions of 73.Fa read , 74.Fa write , 75and 76.Fa close 77must match those, respectively, of 78.Xr read 2 , 79.Xr write 2 , 80and 81.Xr close 2 82with the single exception that they are passed the 83.Fa cookie 84argument specified to 85.Nm 86in place of the traditional file descriptor argument. 87The 88.Fa seek 89function updates the current stream offset using 90.Fa *offset 91and 92.Fa whence . 93If 94.Fa *offset 95is non-NULL, it updates 96.Fa *offset 97with the current stream offset. 98.Pp 99.Nm 100is implemented as a thin shim around the 101.Xr funopen 3 102interface. 103Limitations, possibilities, and requirements of that interface apply to 104.Nm . 105.Sh RETURN VALUES 106Upon successful completion, 107.Nm 108returns a 109.Dv FILE 110pointer. 111Otherwise, 112.Dv NULL 113is returned and the global variable 114.Va errno 115is set to indicate the error. 116.Sh ERRORS 117.Bl -tag -width Er 118.It Bq Er EINVAL 119A bogus 120.Fa mode 121was provided to 122.Nm . 123.It Bq Er ENOMEM 124The 125.Nm 126function 127may fail and set 128.Va errno 129for any of the errors 130specified for the 131.Xr malloc 3 132routine. 133.El 134.Sh SEE ALSO 135.Xr fcntl 2 , 136.Xr open 2 , 137.Xr fclose 3 , 138.Xr fopen 3 , 139.Xr fseek 3 , 140.Xr funopen 3 141.Sh HISTORY 142The 143.Fn funopen 144functions first appeared in 145.Bx 4.4 . 146The 147.Nm 148function first appeared in 149.Fx 11 . 150.Sh BUGS 151The 152.Nm 153function is a nonstandard glibc extension and may not be portable to systems 154other than 155.Fx 156and Linux. 157