man3/open_memstream.3

   1 '\" t
   2 .\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-1.0-or-later
   5 .\"
   6 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
   7 .\"
   8 .TH open_memstream 3 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 open_memstream, open_wmemstream \-  open a dynamic memory buffer stream
  11 .SH LIBRARY
  12 Standard C library
  13 .RI ( libc ", " \-lc )
  14 .SH SYNOPSIS
  15 .nf
  16 .B #include <stdio.h>
  17 .PP
  18 .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
  19 .PP
  20 .B #include <wchar.h>
  21 .PP
  22 .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
  23 .fi
  24 .PP
  25 .RS -4
  26 Feature Test Macro Requirements for glibc (see
  27 .BR feature_test_macros (7)):
  28 .RE
  29 .PP
  30 .BR open_memstream (),
  31 .BR open_wmemstream ():
  32 .nf
  33     Since glibc 2.10:
  34         _POSIX_C_SOURCE >= 200809L
  35     Before glibc 2.10:
  36         _GNU_SOURCE
  37 .fi
  38 .SH DESCRIPTION
  39 The
  40 .BR open_memstream ()
  41 function opens a stream for writing to a memory buffer.
  42 The function dynamically allocates the buffer,
  43 and the buffer automatically grows as needed.
  44 Initially, the buffer has a size of zero.
  45 After closing the stream, the caller should
  46 .BR free (3)
  47 this buffer.
  48 .PP
  49 The locations pointed to by
  50 .I ptr
  51 and
  52 .I sizeloc
  53 are used to report, respectively,
  54 the current location and the size of the buffer.
  55 The locations referred to by these pointers are updated
  56 each time the stream is flushed
  57 .RB ( fflush (3))
  58 and when the stream is closed
  59 .RB ( fclose (3)).
  60 These values remain valid only as long as the caller
  61 performs no further output on the stream.
  62 If further output is performed, then the stream
  63 must again be flushed before trying to access these values.
  64 .PP
  65 A null byte is maintained at the end of the buffer.
  66 This byte is
  67 .I not
  68 included in the size value stored at
  69 .IR sizeloc .
  70 .PP
  71 The stream maintains the notion of a current position,
  72 which is initially zero (the start of the buffer).
  73 Each write operation implicitly adjusts the buffer position.
  74 The stream's buffer position can be explicitly changed with
  75 .BR fseek (3)
  76 or
  77 .BR fseeko (3).
  78 Moving the buffer position past the end
  79 of the data already written fills the intervening space with
  80 null characters.
  81 .PP
  82 The
  83 .BR open_wmemstream ()
  84 is similar to
  85 .BR open_memstream (),
  86 but operates on wide characters instead of bytes.
  87 .SH RETURN VALUE
  88 Upon successful completion,
  89 .BR open_memstream ()
  90 and
  91 .BR open_wmemstream ()
  92 return a
  93 .I FILE
  94 pointer.
  95 Otherwise, NULL is returned and
  96 .I errno
  97 is set to indicate the error.
  98 .SH ATTRIBUTES
  99 For an explanation of the terms used in this section, see
 100 .BR attributes (7).
 101 .ad l
 102 .nh
 103 .TS
 104 allbox;
 105 lbx lb lb
 106 l l l.
 107 Interface       Attribute       Value
 108 T{
 109 .BR open_memstream (),
 110 .BR open_wmemstream ()
 111 T}      Thread safety   MT-Safe
 112 .TE
 113 .hy
 114 .ad
 115 .sp 1
 116 .SH STANDARDS
 117 POSIX.1-2008.
 118 .SH HISTORY
 119 .TP
 120 .BR open_memstream ()
 121 glibc 1.0.x.
 122 .TP
 123 .BR open_wmemstream ()
 124 glibc 2.4.
 125 .SH NOTES
 126 There is no file descriptor associated with the file stream
 127 returned by these functions
 128 (i.e.,
 129 .BR fileno (3)
 130 will return an error if called on the returned stream).
 131 .SH BUGS
 132 Before glibc 2.7, seeking past the end of a stream created by
 133 .BR open_memstream ()
 134 does not enlarge the buffer; instead the
 135 .BR fseek (3)
 136 call fails, returning \-1.
 137 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
 138 .SH EXAMPLES
 139 See
 140 .BR fmemopen (3).
 141 .SH SEE ALSO
 142 .BR fmemopen (3),
 143 .BR fopen (3),
 144 .BR setbuf (3)