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