lib/libc/stdio/open_memstream.3

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