1.\" $OpenBSD: open_memstream.3,v 1.4 2013/06/05 03:39:23 tedu Exp $ 2.\" 3.\" Copyright (c) 2011 Martin Pieuchot <mpi@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: June 5 2013 $ 18.Dt OPEN_MEMSTREAM 3 19.Os 20.Sh NAME 21.Nm open_memstream , 22.Nm open_wmemstream 23.Nd open a memory buffer stream 24.Sh SYNOPSIS 25.In stdio.h 26.Ft FILE * 27.Fn open_memstream "char **pbuf" "size_t *psize" 28.In wchar.h 29.Ft FILE * 30.Fn open_wmemstream "wchar_t **pbuf" "size_t *psize" 31.Sh DESCRIPTION 32The 33.Fn open_memstream 34and 35.Fn open_wmemstream 36functions create, respectively, a seekable byte-oriented or wide-oriented 37stream for writing. 38A dynamically allocated buffer, using 39.Xr malloc 3 , 40is then wrapped to the pointer referenced by 41.Fa pbuf 42and grows automatically as required. 43.Pp 44When the stream is either closed or flushed, the address of the buffer is 45stored in the pointer referenced by 46.Fa pbuf . 47At the same time the smaller of the current position and the buffer length is 48written in the variable pointed to by 49.Fa psize . 50This value represents, respectively, 51the number of bytes or wide characters contained in the buffer, 52not including the terminating null character. 53.Pp 54The buffer memory should be released after the stream is closed. 55.Sh RETURN VALUES 56Upon successful completion, 57.Fn open_memstream 58and 59.Fn open_wmemstream 60return a 61.Dv FILE 62pointer. 63Otherwise, 64.Dv NULL 65is returned and the global variable 66.Va errno 67is set to indicate the error. 68.Sh ERRORS 69.Bl -tag -width Er 70.It Bq Er EINVAL 71The 72.Fa pbuf 73or the 74.Fa psize 75argument is 76.Dv NULL . 77.El 78.Pp 79The 80.Fn open_memstream 81and 82.Fn open_wmemstream 83functions 84may also fail and set 85.Va errno 86for any of the errors 87specified for the routine 88.Xr malloc 3 . 89.Sh SEE ALSO 90.Xr fmemopen 3 , 91.Xr fopen 3 , 92.Xr funopen 3 , 93.Xr malloc 3 94.Sh STANDARDS 95The functions 96.Fn open_memstream 97and 98.Fn open_wmemstream , 99conform to 100.St -p1003.1-2008 . 101.Sh HISTORY 102The 103.Fn open_memstream 104and 105.Fn open_wmemstream 106functions first appeared in 107.Ox 5.4 . 108