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