lib/libc/stdio/funopen.3

   1 .\"     $NetBSD: funopen.3,v 1.23 2015/09/06 01:36:21 dholland Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" Chris Torek.
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)funopen.3   8.1 (Berkeley) 6/9/93
  33 .\"
  34 .Dd March 16, 2012
  35 .Dt FUNOPEN 3
  36 .Os
  37 .Sh NAME
  38 .Nm funopen ,
  39 .Nm funopen2 ,
  40 .Nm fropen ,
  41 .Nm fropen2 ,
  42 .Nm fwopen ,
  43 .Nm fwopen2
  44 .Nd open a stream
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In stdio.h
  49 .Ft FILE *
  50 .Fn funopen "void *cookie" "int (*readfn)(void *, char *, int)" "int (*writefn)(void *, const char *, int)" "off_t (*seekfn)(void *, off_t, int)" "int (*closefn)(void *)"
  51 .Fn funopen2 "void *cookie" "ssize_t (*readfn)(void *, void *, size_t)" "ssize_t (*writefn)(void *, const void *, size_t)" "off_t (*seekfn)(void *, off_t, int)" "int (*flushfn)(void *)" "int (*closefn)(void *)"
  52 .Ft FILE *
  53 .Fn fropen "void *cookie" "int (*readfn)(void *, char *, int)"
  54 .Ft FILE *
  55 .Fn fropen2 "void *cookie" "ssize_t (*readfn)(void *, void *, size_t)"
  56 .Ft FILE *
  57 .Fn fwopen "void *cookie" "int (*writefn)(void *, const char *, int)"
  58 .Ft FILE *
  59 .Fn fwopen2 "void *cookie" "ssize_t (*writefn)(void *, const void *, size_t)"
  60 .Sh DESCRIPTION
  61 The
  62 .Fn funopen
  63 function
  64 associates a stream with up to four
  65 .Dq Tn I/O No functions .
  66 Either
  67 .Fa readfn
  68 or
  69 .Fa writefn
  70 must be specified;
  71 the others can be given as an appropriately-typed
  72 .Dv NULL
  73 pointer.
  74 These
  75 .Tn I/O
  76 functions will be used to read, write, seek and
  77 close the new stream.
  78 .Pp
  79 The
  80 .Fn funopen2
  81 function provides sightly different read and write signatures, which match
  82 better the corresponding system calls, plus the ability to augment the
  83 streams default flushing function.
  84 If a flushing function is provided, then it is called after all data has
  85 been written to the stream.
  86 .Pp
  87 In general, omitting a function means that any attempt to perform the
  88 associated operation on the resulting stream will fail.
  89 If the close function is omitted, closing the stream will flush
  90 any buffered output and then succeed.
  91 .Pp
  92 The calling conventions of
  93 .Fa readfn ,
  94 .Fa writefn ,
  95 .Fa seekfn
  96 and
  97 .Fa closefn
  98 must match those, respectively, of
  99 .Xr read 2 ,
 100 .Xr write 2 ,
 101 .Xr lseek 2 ,
 102 and
 103 .Xr close 2 ;
 104 except that they are passed the
 105 .Fa cookie
 106 argument specified to
 107 .Fn funopen
 108 in place of the traditional file descriptor argument.
 109 .Pp
 110 Read and write
 111 .Tn I/O
 112 functions are allowed to change the underlying buffer
 113 on fully buffered or line buffered streams by calling
 114 .Xr setvbuf 3 .
 115 They are also not required to completely fill or empty the buffer.
 116 They are not, however, allowed to change streams from unbuffered to buffered
 117 or to change the state of the line buffering flag.
 118 They must also be prepared to have read or write calls occur on buffers other
 119 than the one most recently specified.
 120 .Pp
 121 All user
 122 .Tn I/O
 123 functions can report an error by returning \-1.
 124 Additionally, all of the functions should set the external variable
 125 .Va errno
 126 appropriately if an error occurs.
 127 .Pp
 128 An error on
 129 .Fn closefn
 130 does not keep the stream open.
 131 .Pp
 132 As a convenience, the include file
 133 .In stdio.h
 134 defines the macros
 135 .Fn fropen
 136 and
 137 .Fn fwopen
 138 as calls to
 139 .Fn funopen
 140 with only a read or write function specified.
 141 .Sh RETURN VALUES
 142 Upon successful completion,
 143 .Fn funopen
 144 returns a
 145 .Dv FILE
 146 pointer.
 147 Otherwise,
 148 .Dv NULL
 149 is returned and the global variable
 150 .Va errno
 151 is set to indicate the error.
 152 .Sh ERRORS
 153 .Bl -tag -width Er
 154 .It Bq Er EINVAL
 155 The
 156 .Fn funopen
 157 function
 158 was called without either a read or write function.
 159 The
 160 .Fn funopen
 161 function
 162 may also fail and set
 163 .Va errno
 164 for any of the errors
 165 specified for the routine
 166 .Xr malloc 3 .
 167 .El
 168 .Sh SEE ALSO
 169 .Xr fcntl 2 ,
 170 .Xr open 2 ,
 171 .Xr fclose 3 ,
 172 .Xr fmemopen 3 ,
 173 .Xr fopen 3 ,
 174 .Xr fseek 3 ,
 175 .Xr setbuf 3
 176 .Sh HISTORY
 177 The
 178 .Fn funopen
 179 functions first appeared in
 180 .Bx 4.4 .
 181 The
 182 .Fn funopen2
 183 functions first appeared in
 184 .Nx 7.0 .
 185 .Sh CAVEATS
 186 All three functions are specific to
 187 .Nx
 188 and thus unportable.