xref: /minix3/lib/libc/stdio/fmemopen.3 (revision 0a6a1f1d05b60e214de2f05a7310ddd1f0e590e7)
1*0a6a1f1dSLionel Sambuc.\"	$NetBSD: fmemopen.3,v 1.9 2015/09/06 03:10:50 pgoyette Exp $
22fe8fb19SBen Gras.\"
32fe8fb19SBen Gras.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
42fe8fb19SBen Gras.\" All rights reserved.
52fe8fb19SBen Gras.\"
62fe8fb19SBen Gras.\" This code is derived from software contributed to The NetBSD Foundation
72fe8fb19SBen Gras.\" by Christos Zoulas.
82fe8fb19SBen Gras.\"
92fe8fb19SBen Gras.\" Redistribution and use in source and binary forms, with or without
102fe8fb19SBen Gras.\" modification, are permitted provided that the following conditions
112fe8fb19SBen Gras.\" are met:
122fe8fb19SBen Gras.\" 1. Redistributions of source code must retain the above copyright
132fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer.
142fe8fb19SBen Gras.\" 2. Redistributions in binary form must reproduce the above copyright
152fe8fb19SBen Gras.\"    notice, this list of conditions and the following disclaimer in the
162fe8fb19SBen Gras.\"    documentation and/or other materials provided with the distribution.
17f14fb602SLionel Sambuc.\" 3. Neither the name of The NetBSD Foundation nor the names of its
182fe8fb19SBen Gras.\"    contributors may be used to endorse or promote products derived
192fe8fb19SBen Gras.\"    from this software without specific prior written permission.
202fe8fb19SBen Gras.\"
212fe8fb19SBen Gras.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
222fe8fb19SBen Gras.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
232fe8fb19SBen Gras.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
242fe8fb19SBen Gras.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
252fe8fb19SBen Gras.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
262fe8fb19SBen Gras.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
272fe8fb19SBen Gras.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
282fe8fb19SBen Gras.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
292fe8fb19SBen Gras.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
302fe8fb19SBen Gras.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
312fe8fb19SBen Gras.\" POSSIBILITY OF SUCH DAMAGE.
322fe8fb19SBen Gras.\"
33*0a6a1f1dSLionel Sambuc.Dd September 5, 2015
342fe8fb19SBen Gras.Dt FMEMOPEN 3
352fe8fb19SBen Gras.Os
362fe8fb19SBen Gras.Sh NAME
372fe8fb19SBen Gras.Nm fmemopen
38*0a6a1f1dSLionel Sambuc.Nd open a stream that points to a memory buffer
392fe8fb19SBen Gras.Sh LIBRARY
402fe8fb19SBen Gras.Lb libc
412fe8fb19SBen Gras.Sh SYNOPSIS
422fe8fb19SBen Gras.In stdio.h
432fe8fb19SBen Gras.Ft FILE *
442fe8fb19SBen Gras.Fn fmemopen "void *restrict buffer" "size_t size" "const char *restrict mode"
452fe8fb19SBen Gras.Sh DESCRIPTION
462fe8fb19SBen GrasThe
472fe8fb19SBen Gras.Fn fmemopen
482fe8fb19SBen Grasfunction
492fe8fb19SBen Grasassociates a stream with the given
502fe8fb19SBen Gras.Fa buffer
512fe8fb19SBen Grasand
522fe8fb19SBen Gras.Fa size .
532fe8fb19SBen GrasThe
542fe8fb19SBen Gras.Fa buffer
552fe8fb19SBen Grascan be either
562fe8fb19SBen Gras.Dv NULL ,
572fe8fb19SBen Grasor must be of the given
582fe8fb19SBen Gras.Fa size .
592fe8fb19SBen GrasIf the
602fe8fb19SBen Gras.Fa buffer
612fe8fb19SBen Grasis
622fe8fb19SBen Gras.Dv NULL ,
632fe8fb19SBen Grasa
642fe8fb19SBen Gras.Fa buffer
652fe8fb19SBen Grasof the given
662fe8fb19SBen Gras.Fa size
672fe8fb19SBen Graswill be dynamically allocated using
682fe8fb19SBen Gras.Xr malloc 3
692fe8fb19SBen Grasand freed when
702fe8fb19SBen Gras.Xr fclose 3
712fe8fb19SBen Grasis called.
722fe8fb19SBen Gras.Pp
732fe8fb19SBen GrasThe
742fe8fb19SBen Gras.Fa mode
752fe8fb19SBen Grasargument has the same meaning as in
762fe8fb19SBen Gras.Xr fopen 3 .
772fe8fb19SBen Gras.Pp
782fe8fb19SBen GrasThe stream treats the buffer as it would treat a file tracking the current
792fe8fb19SBen Grasposition to perform I/O operations.
802fe8fb19SBen GrasFor example, in the beginning the stream points to the beginning of the buffer,
812fe8fb19SBen Grasunless
822fe8fb19SBen Gras.Dv a
832fe8fb19SBen Graswas specified in the
842fe8fb19SBen Gras.Fa mode
852fe8fb19SBen Grasargument, and then it points to the first
862fe8fb19SBen Gras.Dv NUL
872fe8fb19SBen Grasbyte.
882fe8fb19SBen GrasIf a
892fe8fb19SBen Gras.Dv NULL
902fe8fb19SBen Gras.Fa buffer
912fe8fb19SBen Graswas specified, then the stream will always point at the first byte of the
922fe8fb19SBen Gras.Fa buffer .
932fe8fb19SBen Gras.Pp
942fe8fb19SBen GrasThe stream also keeps track of the
952fe8fb19SBen Gras.Fa size
962fe8fb19SBen Grasof the
972fe8fb19SBen Gras.Fa buffer .
982fe8fb19SBen GrasThe
992fe8fb19SBen Gras.Fa size
1002fe8fb19SBen Grasis initialized depending on the mode:
1012fe8fb19SBen Gras.Bl -tag -width r/w+
1022fe8fb19SBen Gras.It Dv r/r+
1032fe8fb19SBen GrasSet to the
1042fe8fb19SBen Gras.Fa size
1052fe8fb19SBen Grasargument.
1062fe8fb19SBen Gras.It Dv w/w+
1072fe8fb19SBen GrasSet to
1082fe8fb19SBen Gras.Dv 0 .
1092fe8fb19SBen Gras.It Dv a/a+
1102fe8fb19SBen GrasSet to the first
1112fe8fb19SBen Gras.Dv NUL
1122fe8fb19SBen Grasbyte, or the
1132fe8fb19SBen Gras.Fa size
1142fe8fb19SBen Grasargument if one is not found.
1152fe8fb19SBen Gras.El
1162fe8fb19SBen Gras.Pp
1172fe8fb19SBen GrasRead or write operations advance the buffer, but not to exceed the given
1182fe8fb19SBen Gras.Fa size
1192fe8fb19SBen Grasof the
1202fe8fb19SBen Gras.Fa buffer .
1212fe8fb19SBen GrasTrying to read beyond the
1222fe8fb19SBen Gras.Fa size
1232fe8fb19SBen Grasof the
1242fe8fb19SBen Gras.Fa buffer
1252fe8fb19SBen Grasresults in
1262fe8fb19SBen Gras.Dv EOF
1272fe8fb19SBen Grasreturned.
1282fe8fb19SBen Gras.Dv NUL
1292fe8fb19SBen Grasbytes are read normally.
1302fe8fb19SBen GrasTrying to write beyond the
1312fe8fb19SBen Gras.Fa size
1322fe8fb19SBen Grasof the
1332fe8fb19SBen Gras.Fa buffer
1342fe8fb19SBen Grashas no effect.
1352fe8fb19SBen Gras.Pp
1362fe8fb19SBen GrasWhen a stream open for writing is either flushed or closed, a
1372fe8fb19SBen Gras.Dv NUL
1382fe8fb19SBen Grasbyte is written at the current position or at the end of the current
1392fe8fb19SBen Gras.Fa size
1402fe8fb19SBen Grasas kept internally, if there is room.
1412fe8fb19SBen Gras.Sh RETURN VALUES
1422fe8fb19SBen GrasUpon successful completion,
1432fe8fb19SBen Gras.Fn fmemopen
1442fe8fb19SBen Grasreturns a
1452fe8fb19SBen Gras.Dv FILE
1462fe8fb19SBen Graspointer.
1472fe8fb19SBen GrasOtherwise,
1482fe8fb19SBen Gras.Dv NULL
1492fe8fb19SBen Grasis returned and the global variable
1502fe8fb19SBen Gras.Va errno
1512fe8fb19SBen Grasis set to indicate the error.
1522fe8fb19SBen Gras.Sh ERRORS
1532fe8fb19SBen Gras.Bl -tag -width Er
1542fe8fb19SBen Gras.It Bq Er EINVAL
1552fe8fb19SBen GrasThe
1562fe8fb19SBen Gras.Fa size
1572fe8fb19SBen Graswas
1582fe8fb19SBen Gras.Dv 0 ;
1592fe8fb19SBen Grasor the
1602fe8fb19SBen Gras.Fa mode
1612fe8fb19SBen Grasargument is invalid;
1622fe8fb19SBen Grasor the
1632fe8fb19SBen Gras.Fa buffer
1642fe8fb19SBen Grasargument is
1652fe8fb19SBen Gras.Dv NULL
1662fe8fb19SBen Grasand the
1672fe8fb19SBen Gras.Fa mode
1682fe8fb19SBen Grasargument does not specify a
1692fe8fb19SBen Gras.Dv + .
1702fe8fb19SBen Gras.El
1712fe8fb19SBen Gras.Pp
1722fe8fb19SBen GrasThe
1732fe8fb19SBen Gras.Fn fmemopen
1742fe8fb19SBen Grasfunction
1752fe8fb19SBen Grasmay also fail and set
1762fe8fb19SBen Gras.Va errno
1772fe8fb19SBen Grasfor any of the errors
1782fe8fb19SBen Grasspecified for the routine
1792fe8fb19SBen Gras.Xr malloc 3 .
1802fe8fb19SBen Gras.Sh SEE ALSO
1812fe8fb19SBen Gras.Xr fclose 3 ,
1822fe8fb19SBen Gras.Xr fflush 3 ,
1832fe8fb19SBen Gras.Xr fopen 3 ,
1842fe8fb19SBen Gras.Xr malloc 3
185f14fb602SLionel Sambuc.Sh STANDARDS
186f14fb602SLionel SambucThe
187f14fb602SLionel Sambuc.Fn fmemopen
188f14fb602SLionel Sambucfunction conforms to
189f14fb602SLionel Sambuc.St -p1003.1-2008 .
1902fe8fb19SBen Gras.Sh HISTORY
1912fe8fb19SBen GrasThe
1922fe8fb19SBen Gras.Fn fmemopen
193*0a6a1f1dSLionel Sambucfunction first appeared in
1942fe8fb19SBen Gras.Nx 6.0 .
195