lib/libc/stdio/fmemopen.3

   1 .\"     $NetBSD: fmemopen.3,v 1.5 2010/10/07 00:14:14 enami Exp $
   2 .\"
   3 .\" Copyright (c) 2010 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"        This product includes software developed by the NetBSD
  20 .\"        Foundation, Inc. and its contributors.
  21 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  22 .\"    contributors may be used to endorse or promote products derived
  23 .\"    from this software without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  26 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  27 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  28 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  29 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  30 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  31 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  32 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  33 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  34 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  35 .\" POSSIBILITY OF SUCH DAMAGE.
  36 .\"
  37 .Dd May 13, 2011
  38 .Dt FMEMOPEN 3
  39 .Os
  40 .Sh NAME
  41 .Nm fmemopen
  42 .Nd open a stream that points to the given buffer
  43 .Sh LIBRARY
  44 .Lb libc
  45 .Sh SYNOPSIS
  46 .In stdio.h
  47 .Ft FILE *
  48 .Fn fmemopen "void *restrict buffer" "size_t size" "const char *restrict mode"
  49 .Sh DESCRIPTION
  50 The
  51 .Fn fmemopen
  52 function
  53 associates a stream with the given
  54 .Fa buffer
  55 and
  56 .Fa size .
  57 The
  58 .Fa buffer
  59 can be either
  60 .Dv NULL ,
  61 or must be of the given
  62 .Fa size .
  63 If the
  64 .Fa buffer
  65 is
  66 .Dv NULL ,
  67 a
  68 .Fa buffer
  69 of the given
  70 .Fa size
  71 will be dynamically allocated using
  72 .Xr malloc 3
  73 and freed when
  74 .Xr fclose 3
  75 is called.
  76 .Pp
  77 The
  78 .Fa mode
  79 argument has the same meaning as in
  80 .Xr fopen 3 .
  81 .Pp
  82 The stream treats the buffer as it would treat a file tracking the current
  83 position to perform I/O operations.
  84 For example, in the beginning the stream points to the beginning of the buffer,
  85 unless
  86 .Dv a
  87 was specified in the
  88 .Fa mode
  89 argument, and then it points to the first
  90 .Dv NUL
  91 byte.
  92 If a
  93 .Dv NULL
  94 .Fa buffer
  95 was specified, then the stream will always point at the first byte of the
  96 .Fa buffer .
  97 .Pp
  98 The stream also keeps track of the
  99 .Fa size
 100 of the
 101 .Fa buffer .
 102 The
 103 .Fa size
 104 is initialized depending on the mode:
 105 .Bl -tag -width r/w+
 106 .It Dv r/r+
 107 Set to the
 108 .Fa size
 109 argument.
 110 .It Dv w/w+
 111 Set to
 112 .Dv 0 .
 113 .It Dv a/a+
 114 Set to the first
 115 .Dv NUL
 116 byte, or the
 117 .Fa size
 118 argument if one is not found.
 119 .El
 120 .Pp
 121 Read or write operations advance the buffer, but not to exceed the given
 122 .Fa size
 123 of the
 124 .Fa buffer .
 125 Trying to read beyond the
 126 .Fa size
 127 of the
 128 .Fa buffer
 129 results in
 130 .Dv EOF
 131 returned.
 132 .Dv NUL
 133 bytes are read normally.
 134 Trying to write beyond the
 135 .Fa size
 136 of the
 137 .Fa buffer
 138 has no effect.
 139 .Pp
 140 When a stream open for writing is either flushed or closed, a
 141 .Dv NUL
 142 byte is written at the current position or at the end of the current
 143 .Fa size
 144 as kept internally, if there is room.
 145 .Sh RETURN VALUES
 146 Upon successful completion,
 147 .Fn fmemopen
 148 returns a
 149 .Dv FILE
 150 pointer.
 151 Otherwise,
 152 .Dv NULL
 153 is returned and the global variable
 154 .Va errno
 155 is set to indicate the error.
 156 .Sh ERRORS
 157 .Bl -tag -width Er
 158 .It Bq Er EINVAL
 159 The
 160 .Fa size
 161 was
 162 .Dv 0 ;
 163 or the
 164 .Fa mode
 165 argument is invalid;
 166 or the
 167 .Fa buffer
 168 argument is
 169 .Dv NULL
 170 and the
 171 .Fa mode
 172 argument does not specify a
 173 .Dv + .
 174 .El
 175 .Pp
 176 The
 177 .Fn fmemopen
 178 function
 179 may also fail and set
 180 .Va errno
 181 for any of the errors
 182 specified for the routine
 183 .Xr malloc 3 .
 184 .Sh SEE ALSO
 185 .Xr fclose 3 ,
 186 .Xr fflush 3 ,
 187 .Xr fopen 3 ,
 188 .Xr malloc 3
 189 .Sh HISTORY
 190 The
 191 .Fn fmemopen
 192 functions first appeared in
 193 .Dx 2.11 .
 194 .Pp
 195 This manual page was imported from
 196 .Nx 6.0 .