libc: Prototype and manual page for open_memstream.
authorVenkatesh Srinivas <me@endeavour.zapto.org>
Mon, 12 Sep 2011 20:35:15 +0000 (13:35 -0700)
committerVenkatesh Srinivas <me@endeavour.zapto.org>
Mon, 12 Sep 2011 20:35:15 +0000 (13:35 -0700)
include/stdio.h
lib/libc/stdio/Makefile.inc
lib/libc/stdio/open_memstream.3 [new file with mode: 0644]

index fd29bb9..36f7be2 100644 (file)
@@ -300,6 +300,7 @@ ssize_t      getdelim(char ** __restrict, size_t * __restrict, int,
 int     renameat(int, const char *, int, const char *);
 int     vdprintf(int, const char * __restrict, __va_list);
 FILE   *fmemopen(void *__restrict, size_t, const char *__restrict);
+FILE   *open_memstream(char **, size_t *);
 
 /*
  * Every programmer and his dog wrote functions called getline() and dprintf()
index 43d9256..fc3d554 100644 (file)
@@ -34,7 +34,7 @@ SRCS+=        __fpending.c _flock_stub.c \
 MAN+=  fclose.3 ferror.3 fflush.3 fgetln.3 fgets.3 fgetwln.3 fgetws.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 \
+       getwc.3 mktemp.3 open_memstream.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
 
 MLINKS+=fclose.3 fcloseall.3
diff --git a/lib/libc/stdio/open_memstream.3 b/lib/libc/stdio/open_memstream.3
new file mode 100644 (file)
index 0000000..c019abf
--- /dev/null
@@ -0,0 +1,86 @@
+.\"
+.\" Copyright (c) 2011 Venkatesh Srinivas,
+.\" All rights reserved.
+.\"
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 Sept 12, 2011
+.Dt OPEN_MEMSTREAM 3
+.Os
+.Sh NAME
+.Nm open_memstream
+.Nd open a stream that points to a dynamic buffer
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In stdio.h
+.Ft FILE *
+.Fn open_memstream "char **bufp" "size_t *sizep" 
+.Sh DESCRIPTION
+The
+.Fn open_memstream
+function
+creates a FILE stream with a dynamically expanding buffer. A pointer to the
+buffer is stored at the
+.Fa bufp
+argument and the length of the data in the buffer is stored at the
+.Fa sizep
+argument. The pointer and length values may be updated by writes to the buffer.
+.Pp
+Writes append to the buffer and may reallocate it, invalidating the 
+.Fa bufp 
+argument. Writes may fail if the buffer cannot be resized.
+.Pp
+The stream is seekable and opened for writing.
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn open_memstream
+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 bufp
+argument or the
+.Fa sizep
+argument were
+.Dv NULL .
+.It Bq Er ENOMEM
+Memory for the stream buffer or cookie could not be allocated.
+.El
+.Sh SEE ALSO
+.Xr fmemopen 3 ,
+.Xr fclose 3 ,
+.Xr fflush 3 ,
+.Xr fopen 3 
+.Sh HISTORY
+The
+.Fn open_memstream
+function first appeared in
+.Dx 2.11 .