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