lib/libc/stdio/open_memstream.3

   1 .\"
   2 .\" Copyright (c) 2011 Venkatesh Srinivas,
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS
  15 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  16 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  17 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  18 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  19 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  20 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  21 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  22 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  23 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  24 .\" POSSIBILITY OF SUCH DAMAGE.
  25 .\"
  26 .Dd Sept 12, 2011
  27 .Dt OPEN_MEMSTREAM 3
  28 .Os
  29 .Sh NAME
  30 .Nm open_memstream
  31 .Nd open a stream that points to a dynamic buffer
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In stdio.h
  36 .Ft FILE *
  37 .Fn open_memstream "char **bufp" "size_t *sizep"
  38 .Sh DESCRIPTION
  39 The
  40 .Fn open_memstream
  41 function
  42 creates a FILE stream with a dynamically expanding buffer. A pointer to the
  43 buffer is stored at the
  44 .Fa bufp
  45 argument and the length of the data in the buffer is stored at the
  46 .Fa sizep
  47 argument. The pointer and length values may be updated by writes to the buffer.
  48 .Pp
  49 Writes append to the buffer and may reallocate it, invalidating the
  50 .Fa bufp
  51 argument. Writes may fail if the buffer cannot be resized.
  52 .Pp
  53 The stream is seekable and opened for writing.
  54 .Sh RETURN VALUES
  55 Upon successful completion,
  56 .Fn open_memstream
  57 returns a
  58 .Dv FILE
  59 pointer.
  60 Otherwise,
  61 .Dv NULL
  62 is returned and the global variable
  63 .Va errno
  64 is set to indicate the error.
  65 .Sh ERRORS
  66 .Bl -tag -width Er
  67 .It Bq Er EINVAL
  68 The
  69 .Fa bufp
  70 argument or the
  71 .Fa sizep
  72 argument were
  73 .Dv NULL .
  74 .It Bq Er ENOMEM
  75 Memory for the stream buffer or cookie could not be allocated.
  76 .El
  77 .Sh SEE ALSO
  78 .Xr fmemopen 3 ,
  79 .Xr fclose 3 ,
  80 .Xr fflush 3 ,
  81 .Xr fopen 3
  82 .Sh HISTORY
  83 The
  84 .Fn open_memstream
  85 function first appeared in
  86 .Dx 2.11 .