summaryrefslogtreecommitdiffstats
path: root/man3/open_memstream.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/open_memstream.3')
-rw-r--r--man3/open_memstream.3142
1 files changed, 142 insertions, 0 deletions
diff --git a/man3/open_memstream.3 b/man3/open_memstream.3
new file mode 100644
index 0000000..ce9da19
--- /dev/null
+++ b/man3/open_memstream.3
@@ -0,0 +1,142 @@
+'\" t
+.\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
+.\"
+.TH open_memstream 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+open_memstream, open_wmemstream \- open a dynamic memory buffer stream
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.PP
+.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
+.PP
+.B #include <wchar.h>
+.PP
+.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
+.fi
+.PP
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR open_memstream (),
+.BR open_wmemstream ():
+.nf
+ Since glibc 2.10:
+ _POSIX_C_SOURCE >= 200809L
+ Before glibc 2.10:
+ _GNU_SOURCE
+.fi
+.SH DESCRIPTION
+The
+.BR open_memstream ()
+function opens a stream for writing to a memory buffer.
+The function dynamically allocates the buffer,
+and the buffer automatically grows as needed.
+Initially, the buffer has a size of zero.
+After closing the stream, the caller should
+.BR free (3)
+this buffer.
+.PP
+The locations pointed to by
+.I ptr
+and
+.I sizeloc
+are used to report, respectively,
+the current location and the size of the buffer.
+The locations referred to by these pointers are updated
+each time the stream is flushed
+.RB ( fflush (3))
+and when the stream is closed
+.RB ( fclose (3)).
+These values remain valid only as long as the caller
+performs no further output on the stream.
+If further output is performed, then the stream
+must again be flushed before trying to access these values.
+.PP
+A null byte is maintained at the end of the buffer.
+This byte is
+.I not
+included in the size value stored at
+.IR sizeloc .
+.PP
+The stream maintains the notion of a current position,
+which is initially zero (the start of the buffer).
+Each write operation implicitly adjusts the buffer position.
+The stream's buffer position can be explicitly changed with
+.BR fseek (3)
+or
+.BR fseeko (3).
+Moving the buffer position past the end
+of the data already written fills the intervening space with
+null characters.
+.PP
+The
+.BR open_wmemstream ()
+is similar to
+.BR open_memstream (),
+but operates on wide characters instead of bytes.
+.SH RETURN VALUE
+Upon successful completion,
+.BR open_memstream ()
+and
+.BR open_wmemstream ()
+return a
+.I FILE
+pointer.
+Otherwise, NULL is returned and
+.I errno
+is set to indicate the error.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR open_memstream (),
+.BR open_wmemstream ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR open_memstream ()
+glibc 1.0.x.
+.TP
+.BR open_wmemstream ()
+glibc 2.4.
+.SH NOTES
+There is no file descriptor associated with the file stream
+returned by these functions
+(i.e.,
+.BR fileno (3)
+will return an error if called on the returned stream).
+.SH BUGS
+Before glibc 2.7, seeking past the end of a stream created by
+.BR open_memstream ()
+does not enlarge the buffer; instead the
+.BR fseek (3)
+call fails, returning \-1.
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
+.SH EXAMPLES
+See
+.BR fmemopen (3).
+.SH SEE ALSO
+.BR fmemopen (3),
+.BR fopen (3),
+.BR setbuf (3)