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 September 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 creates a
  42 .Vt FILE
  43 stream with a dynamically expanding buffer.
  44 A pointer to the buffer is stored at the
  45 .Fa bufp
  46 argument and the length of the data in the buffer is stored at the
  47 .Fa sizep
  48 argument.
  49 The pointer and length values may be updated by writes to the buffer.
  50 .Pp
  51 Writes append to the buffer and may reallocate it, invalidating the
  52 .Fa bufp
  53 argument.
  54 Writes may fail if the buffer cannot be resized.
  55 .Pp
  56 The stream is seekable and opened for writing.
  57 .Sh RETURN VALUES
  58 Upon successful completion,
  59 .Fn open_memstream
  60 returns a
  61 .Vt FILE
  62 pointer.
  63 Otherwise,
  64 .Dv NULL
  65 is returned and the global variable
  66 .Va errno
  67 is set to indicate the error.
  68 .Sh ERRORS
  69 .Bl -tag -width Er
  70 .It Bq Er EINVAL
  71 The
  72 .Fa bufp
  73 argument or the
  74 .Fa sizep
  75 argument were
  76 .Dv NULL .
  77 .It Bq Er ENOMEM
  78 Memory for the stream buffer or cookie could not be allocated.
  79 .El
  80 .Sh SEE ALSO
  81 .Xr fclose 3 ,
  82 .Xr fflush 3 ,
  83 .Xr fmemopen 3 ,
  84 .Xr fopen 3
  85 .Sh HISTORY
  86 The
  87 .Fn open_memstream
  88 function first appeared in
  89 .Dx 2.11 .