From f97864e99208386fb3d2a7fffbe99445ce4abbe7 Mon Sep 17 00:00:00 2001 From: Venkatesh Srinivas Date: Fri, 13 May 2011 19:04:31 -0700 Subject: [PATCH] Import fmemopen(3) manual page from NetBSD. --- lib/libc/stdio/Makefile.inc | 4 +- lib/libc/stdio/fmemopen.3 | 196 ++++++++++++++++++++++++++++++++++++ 2 files changed, 198 insertions(+), 2 deletions(-) create mode 100644 lib/libc/stdio/fmemopen.3 diff --git a/lib/libc/stdio/Makefile.inc b/lib/libc/stdio/Makefile.inc index 44e14213b4..41a130f9ff 100644 --- a/lib/libc/stdio/Makefile.inc +++ b/lib/libc/stdio/Makefile.inc @@ -32,8 +32,8 @@ SRCS+= __fpending.c _flock_stub.c \ .if ${LIB} == "c" MAN+= fclose.3 ferror.3 fflush.3 fgetln.3 fgets.3 fgetwln.3 fgetws.3 \ - flockfile.3 fopen.3 fputs.3 fputws.3 fread.3 fseek.3 funopen.3 \ - fwide.3 getc.3 getline.3 \ + flockfile.3 fmemopen.3 fopen.3 fputs.3 fputws.3 fread.3 fseek.3 \ + funopen.3 fwide.3 getc.3 getline.3 \ getwc.3 mktemp.3 printf.3 putc.3 putwc.3 remove.3 \ scanf.3 setbuf.3 stdio.3 tmpnam.3 ungetc.3 ungetwc.3 wprintf.3 wscanf.3 diff --git a/lib/libc/stdio/fmemopen.3 b/lib/libc/stdio/fmemopen.3 new file mode 100644 index 0000000000..b61c12dbf6 --- /dev/null +++ b/lib/libc/stdio/fmemopen.3 @@ -0,0 +1,196 @@ +.\" $NetBSD: fmemopen.3,v 1.5 2010/10/07 00:14:14 enami Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christos Zoulas. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the NetBSD +.\" Foundation, Inc. and its contributors. +.\" 4. Neither the name of The NetBSD Foundation nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd May 13, 2011 +.Dt FMEMOPEN 3 +.Os +.Sh NAME +.Nm fmemopen +.Nd open a stream that points to the given buffer +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In stdio.h +.Ft FILE * +.Fn fmemopen "void *restrict buffer" "size_t size" "const char *restrict mode" +.Sh DESCRIPTION +The +.Fn fmemopen +function +associates a stream with the given +.Fa buffer +and +.Fa size . +The +.Fa buffer +can be either +.Dv NULL , +or must be of the given +.Fa size . +If the +.Fa buffer +is +.Dv NULL , +a +.Fa buffer +of the given +.Fa size +will be dynamically allocated using +.Xr malloc 3 +and freed when +.Xr fclose 3 +is called. +.Pp +The +.Fa mode +argument has the same meaning as in +.Xr fopen 3 . +.Pp +The stream treats the buffer as it would treat a file tracking the current +position to perform I/O operations. +For example, in the beginning the stream points to the beginning of the buffer, +unless +.Dv a +was specified in the +.Fa mode +argument, and then it points to the first +.Dv NUL +byte. +If a +.Dv NULL +.Fa buffer +was specified, then the stream will always point at the first byte of the +.Fa buffer . +.Pp +The stream also keeps track of the +.Fa size +of the +.Fa buffer . +The +.Fa size +is initialized depending on the mode: +.Bl -tag -width r/w+ +.It Dv r/r+ +Set to the +.Fa size +argument. +.It Dv w/w+ +Set to +.Dv 0 . +.It Dv a/a+ +Set to the first +.Dv NUL +byte, or the +.Fa size +argument if one is not found. +.El +.Pp +Read or write operations advance the buffer, but not to exceed the given +.Fa size +of the +.Fa buffer . +Trying to read beyond the +.Fa size +of the +.Fa buffer +results in +.Dv EOF +returned. +.Dv NUL +bytes are read normally. +Trying to write beyond the +.Fa size +of the +.Fa buffer +has no effect. +.Pp +When a stream open for writing is either flushed or closed, a +.Dv NUL +byte is written at the current position or at the end of the current +.Fa size +as kept internally, if there is room. +.Sh RETURN VALUES +Upon successful completion, +.Fn fmemopen +returns a +.Dv FILE +pointer. +Otherwise, +.Dv NULL +is returned and the global variable +.Va errno +is set to indicate the error. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa size +was +.Dv 0 ; +or the +.Fa mode +argument is invalid; +or the +.Fa buffer +argument is +.Dv NULL +and the +.Fa mode +argument does not specify a +.Dv + . +.El +.Pp +The +.Fn fmemopen +function +may also fail and set +.Va errno +for any of the errors +specified for the routine +.Xr malloc 3 . +.Sh SEE ALSO +.Xr fclose 3 , +.Xr fflush 3 , +.Xr fopen 3 , +.Xr malloc 3 +.Sh HISTORY +The +.Fn fmemopen +functions first appeared in +.Dx 2.11 . +.Pp +This manual page was imported from +.Nx 6.0 . -- 2.41.0