mirror of https://github.com/mkerrisk/man-pages
146 lines
3.4 KiB
Groff
146 lines
3.4 KiB
Groff
.\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
|
|
.\" Distributed under the GPL.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
|
|
.\"
|
|
.TH OPEN_MEMSTREAM 3 2020-06-09 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
open_memstream, open_wmemstream \- open a dynamic memory buffer stream
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <stdio.h>
|
|
.PP
|
|
.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
|
|
|
|
.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 ():
|
|
.PD 0
|
|
.ad l
|
|
.RS 4
|
|
.TP 4
|
|
Since glibc 2.10:
|
|
_POSIX_C_SOURCE\ >=\ 200809L
|
|
.TP
|
|
Before glibc 2.10:
|
|
_GNU_SOURCE
|
|
.RE
|
|
.ad
|
|
.PD
|
|
.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
|
|
.IR 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 VERSIONS
|
|
.BR open_memstream ()
|
|
was already available in glibc 1.0.x.
|
|
.BR open_wmemstream ()
|
|
is available since glibc 2.4.
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.TS
|
|
allbox;
|
|
lb lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR open_memstream (),
|
|
.br
|
|
.BR open_wmemstream
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
.sp 1
|
|
.SH CONFORMING TO
|
|
POSIX.1-2008.
|
|
These functions are not specified in POSIX.1-2001,
|
|
and are not widely available on other systems.
|
|
.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
|
|
In glibc before version 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)
|