1.\" $NetBSD: fmemopen.3,v 1.9 2015/09/06 03:10:50 pgoyette Exp $ 2.\" 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of The NetBSD Foundation nor the names of its 18.\" contributors may be used to endorse or promote products derived 19.\" from this software without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 22.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 23.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 24.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 25.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 26.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 27.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 28.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 29.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 30.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 31.\" POSSIBILITY OF SUCH DAMAGE. 32.\" 33.Dd September 5, 2015 34.Dt FMEMOPEN 3 35.Os 36.Sh NAME 37.Nm fmemopen 38.Nd open a stream that points to a memory buffer 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In stdio.h 43.Ft FILE * 44.Fn fmemopen "void *restrict buffer" "size_t size" "const char *restrict mode" 45.Sh DESCRIPTION 46The 47.Fn fmemopen 48function 49associates a stream with the given 50.Fa buffer 51and 52.Fa size . 53The 54.Fa buffer 55can be either 56.Dv NULL , 57or must be of the given 58.Fa size . 59If the 60.Fa buffer 61is 62.Dv NULL , 63a 64.Fa buffer 65of the given 66.Fa size 67will be dynamically allocated using 68.Xr malloc 3 69and freed when 70.Xr fclose 3 71is called. 72.Pp 73The 74.Fa mode 75argument has the same meaning as in 76.Xr fopen 3 . 77.Pp 78The stream treats the buffer as it would treat a file tracking the current 79position to perform I/O operations. 80For example, in the beginning the stream points to the beginning of the buffer, 81unless 82.Dv a 83was specified in the 84.Fa mode 85argument, and then it points to the first 86.Dv NUL 87byte. 88If a 89.Dv NULL 90.Fa buffer 91was specified, then the stream will always point at the first byte of the 92.Fa buffer . 93.Pp 94The stream also keeps track of the 95.Fa size 96of the 97.Fa buffer . 98The 99.Fa size 100is initialized depending on the mode: 101.Bl -tag -width r/w+ 102.It Dv r/r+ 103Set to the 104.Fa size 105argument. 106.It Dv w/w+ 107Set to 108.Dv 0 . 109.It Dv a/a+ 110Set to the first 111.Dv NUL 112byte, or the 113.Fa size 114argument if one is not found. 115.El 116.Pp 117Read or write operations advance the buffer, but not to exceed the given 118.Fa size 119of the 120.Fa buffer . 121Trying to read beyond the 122.Fa size 123of the 124.Fa buffer 125results in 126.Dv EOF 127returned. 128.Dv NUL 129bytes are read normally. 130Trying to write beyond the 131.Fa size 132of the 133.Fa buffer 134has no effect. 135.Pp 136When a stream open for writing is either flushed or closed, a 137.Dv NUL 138byte is written at the current position or at the end of the current 139.Fa size 140as kept internally, if there is room. 141.Sh RETURN VALUES 142Upon successful completion, 143.Fn fmemopen 144returns a 145.Dv FILE 146pointer. 147Otherwise, 148.Dv NULL 149is returned and the global variable 150.Va errno 151is set to indicate the error. 152.Sh ERRORS 153.Bl -tag -width Er 154.It Bq Er EINVAL 155The 156.Fa size 157was 158.Dv 0 ; 159or the 160.Fa mode 161argument is invalid; 162or the 163.Fa buffer 164argument is 165.Dv NULL 166and the 167.Fa mode 168argument does not specify a 169.Dv + . 170.El 171.Pp 172The 173.Fn fmemopen 174function 175may also fail and set 176.Va errno 177for any of the errors 178specified for the routine 179.Xr malloc 3 . 180.Sh SEE ALSO 181.Xr fclose 3 , 182.Xr fflush 3 , 183.Xr fopen 3 , 184.Xr malloc 3 185.Sh STANDARDS 186The 187.Fn fmemopen 188function conforms to 189.St -p1003.1-2008 . 190.Sh HISTORY 191The 192.Fn fmemopen 193function first appeared in 194.Nx 6.0 . 195