lib/libc/stdio/open_memstream.3

   1 .\" Copyright (c) 2013 Hudson River Trading LLC
   2 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: head/lib/libc/stdio/open_memstream.3 286177 2015-08-02 02:00:20Z jhb $
  27 .\"
  28 .Dd September 9, 2015
  29 .Dt OPEN_MEMSTREAM 3
  30 .Os
  31 .Sh NAME
  32 .Nm open_memstream ,
  33 .Nm open_wmemstream
  34 .Nd dynamic memory buffer stream open functions
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In stdio.h
  39 .Ft FILE *
  40 .Fn open_memstream "char **bufp" "size_t *sizep"
  41 .In wchar.h
  42 .Ft FILE *
  43 .Fn open_wmemstream "wchar_t **bufp" "size_t *sizep"
  44 .Sh DESCRIPTION
  45 The
  46 .Fn open_memstream
  47 and
  48 .Fn open_wmemstream
  49 functions create a write-only, seekable stream backed by a dynamically
  50 allocated memory buffer.
  51 The
  52 .Fn open_memstream
  53 function creates a byte-oriented stream,
  54 while the
  55 .Fn open_wmemstream
  56 function creates a wide-oriented stream.
  57 .Pp
  58 Each stream maintains a current position and size.
  59 Initially,
  60 the position and size are set to zero.
  61 Each write begins at the current position and advances it the number of
  62 successfully written bytes for
  63 .Fn open_memstream
  64 or wide characters for
  65 .Fn open_wmemstream .
  66 If a write moves the current position beyond the length of the buffer,
  67 the length of the buffer is extended and a null character is appended to the
  68 buffer.
  69 .Pp
  70 A stream's buffer always contains a null character at the end of the buffer
  71 that is not included in the current length.
  72 .Pp
  73 If a stream's current position is moved beyond the current length via a
  74 seek operation and a write is performed,
  75 the characters between the current length and the current position are filled
  76 with null characters before the write is performed.
  77 .Pp
  78 After a successful call to
  79 .Xr fclose 3
  80 or
  81 .Xr fflush 3 ,
  82 the pointer referenced by
  83 .Fa bufp
  84 will contain the start of the memory buffer and the variable referenced by
  85 .Fa sizep
  86 will contain the smaller of the current position and the current buffer length.
  87 .Pp
  88 After a successful call to
  89 .Xr fflush 3 ,
  90 the pointer referenced by
  91 .Fa bufp
  92 and the variable referenced by
  93 .Fa sizep
  94 are only valid until the next write operation or a call to
  95 .Xr fclose 3 .
  96 .Pp
  97 Once a stream is closed,
  98 the allocated buffer referenced by
  99 .Fa bufp
 100 should be released via a call to
 101 .Xr free 3
 102 when it is no longer needed.
 103 .Sh IMPLEMENTATION NOTES
 104 Internally all I/O streams are effectively byte-oriented,
 105 so using wide-oriented operations to write to a stream opened via
 106 .Fn open_wmemstream
 107 results in wide characters being expanded to a stream of multibyte characters
 108 in stdio's internal buffers.
 109 These multibyte characters are then converted back to wide characters when
 110 written into the stream.
 111 As a result,
 112 the wide-oriented streams maintain an internal multibyte character conversion
 113 state that is cleared on any seek opertion that changes the current position.
 114 This should have no effect as long as wide-oriented output operations are used
 115 on a wide-oriented stream.
 116 .Sh RETURN VALUES
 117 Upon successful completion,
 118 .Fn open_memstream
 119 and
 120 .Fn open_wmemstream
 121 return a
 122 .Tn FILE
 123 pointer.
 124 Otherwise,
 125 .Dv NULL
 126 is returned and the global variable
 127 .Va errno
 128 is set to indicate the error.
 129 .Sh ERRORS
 130 .Bl -tag -width Er
 131 .It Bq Er EINVAL
 132 The
 133 .Fa bufp
 134 or
 135 .Fa sizep
 136 argument was
 137 .Dv NULL .
 138 .It Bq Er ENOMEM
 139 Memory for the stream or buffer could not be allocated.
 140 .El
 141 .Sh SEE ALSO
 142 .Xr fclose 3 ,
 143 .Xr fflush 3 ,
 144 .Xr fmemopen 3 ,
 145 .Xr fopen 3 ,
 146 .Xr free 3 ,
 147 .Xr fseek 3 ,
 148 .Xr sbuf 3 ,
 149 .Xr stdio 3
 150 .Sh STANDARDS
 151 The
 152 .Fn open_memstream
 153 and
 154 .Fn open_wmemstream
 155 functions conform to
 156 .St -p1003.1-2008 .
 157 .Sh HISTORY
 158 The
 159 .Fn open_memstream
 160 function first appeared in
 161 .Dx 2.11 .
 162 The
 163 .Fn open_wmemstream
 164 function first appeared in
 165 .Dx 4.3 .