diff options
Diffstat (limited to 'man/man3/open_memstream.3')
| -rw-r--r-- | man/man3/open_memstream.3 | 141 |
1 files changed, 141 insertions, 0 deletions
diff --git a/man/man3/open_memstream.3 b/man/man3/open_memstream.3 new file mode 100644 index 000000000..63a1ea9be --- /dev/null +++ b/man/man3/open_memstream.3 @@ -0,0 +1,141 @@ +'\" 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 (date) "Linux man-pages (unreleased)" +.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> +.P +.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc ); +.P +.B #include <wchar.h> +.P +.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.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. +.P +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. +.P +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 . +.P +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. +.P +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 +.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) |