lib/libc/stdio/fmemopen.3

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