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