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