1.\" Copyright (c) 2013 Advanced Computing Technologies 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$ 27.\" 28.Dd February 27, 2013 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 45The 46.Fn open_memstream 47and 48.Fn open_wmemstream 49functions create a write-only, seekable stream backed by a dynamically 50allocated memory buffer. 51The 52.Fn open_memstream 53function creates a byte-oriented stream, 54while the 55.Fn open_wmemstream 56function creates a wide-oriented stream. 57.Pp 58Each stream maintains a current position and size. 59Initially, 60the position and size are set to zero. 61Each write begins at the current position and advances it the number of 62successfully written bytes for 63.Fn open_memstream 64or wide characters for 65.Fn open_wmemstream . 66If a write moves the current position beyond the length of the buffer, 67the length of the buffer is extended and a null character is appended to the 68buffer. 69.Pp 70A stream's buffer always contains a null character at the end of the buffer 71that is not included in the current length. 72.Pp 73If a stream's current position is moved beyond the current length via a 74seek operation and a write is performed, 75the characters between the current length and the current position are filled 76with null characters before the write is performed. 77.Pp 78After a successful call to 79.Xr fclose 3 80or 81.Xr fflush 3 , 82the pointer referenced by 83.Fa bufp 84will contain the start of the memory buffer and the variable referenced by 85.Fa sizep 86will contain the smaller of the current position and the current buffer length. 87.Pp 88After a successful call to 89.Xr fflush 3, 90the pointer referenced by 91.Fa bufp 92and the variable referenced by 93.Fa sizep 94are only valid until the next write operation or a call to 95.Xr fclose 3. 96.Pp 97Once a stream is closed, 98the allocated buffer referenced by 99.Fa bufp 100should be released via a call to 101.Xr free 3 102when it is no longer needed. 103.Sh IMPLEMENTATION NOTES 104Internally all I/O streams are effectively byte-oriented, 105so using wide-oriented operations to write to a stream opened via 106.Fn open_wmemstream 107results in wide characters being expanded to a stream of multibyte characters 108in stdio's internal buffers. 109These multibyte characters are then converted back to wide characters when 110written into the stream. 111As a result, 112the wide-oriented streams maintain an internal multibyte character conversion 113state that is cleared on any seek opertion that changes the current position. 114This should have no effect as long as wide-oriented output operations are used 115on a wide-oriented stream. 116.Sh RETURN VALUES 117Upon successful completion, 118.Fn open_memstream 119and 120.Fn open_wmemstream 121return a 122.Tn FILE 123pointer. 124Otherwise, 125.Dv NULL 126is returned and the global variable 127.Va errno 128is set to indicate the error. 129.Sh ERRORS 130.Bl -tag -width Er 131.It Bq Er EINVAL 132The 133.Fa bufp 134or 135.Fa sizep 136argument was 137.Dv NULL . 138.It Bq Er ENOMEM 139Memory 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 fopen 3 , 145.Xr free 3 , 146.Xr fseek 3 , 147.Xr sbuf 3 , 148.Xr stdio 3 149.Sh STANDARDS 150The 151.Fn open_memstream 152and 153.Fn open_wmemstream 154functions conform to 155.St -p1003.1-2008 . 156