stdio/FreeBSD/funopen.3

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