mirror of https://github.com/mkerrisk/man-pages
fmemopen.3, open_memstream.3: Split open_memstream() and open_wmemstream() out to separate page
The current fmemopen(3) page documents too many functions. Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk
parent
551c427e75
commit
09ffd9ca50
100
man3/fmemopen.3
100
man3/fmemopen.3
|
|
@ -9,18 +9,12 @@
|
|||
.\"
|
||||
.TH FMEMOPEN 3 2015-03-29 "GNU" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
fmemopen, open_memstream, open_wmemstream \- open memory as stream
|
||||
fmemopen \- open memory as stream
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.B #include <stdio.h>
|
||||
|
||||
.BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"
|
||||
|
||||
.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
|
||||
|
||||
.B #include <wchar.h>
|
||||
|
||||
.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
|
||||
.fi
|
||||
.sp
|
||||
.in -4n
|
||||
|
|
@ -28,9 +22,7 @@ Feature Test Macro Requirements for glibc (see
|
|||
.BR feature_test_macros (7)):
|
||||
.in
|
||||
.sp
|
||||
.BR fmemopen (),
|
||||
.BR open_memstream (),
|
||||
.BR open_wmemstream ():
|
||||
.BR fmemopen ():
|
||||
.PD 0
|
||||
.ad l
|
||||
.RS 4
|
||||
|
|
@ -105,8 +97,7 @@ The initial position is set to the start of the buffer.
|
|||
The buffer is automatically freed when the stream is closed.
|
||||
Note that the caller has no way to obtain a pointer to the
|
||||
temporary buffer allocated by this call (but see
|
||||
.BR open_memstream ()
|
||||
below).
|
||||
.BR open_memstream (3)).
|
||||
.PP
|
||||
If
|
||||
.I buf
|
||||
|
|
@ -161,63 +152,10 @@ of the buffer's size, using:
|
|||
.\" and
|
||||
.\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
|
||||
.\"
|
||||
.SS open_memstream() and open_wmemstream()
|
||||
The
|
||||
.BR open_memstream ()
|
||||
function opens a stream for writing to a buffer.
|
||||
The function dynamically allocates the buffer (in the manner of
|
||||
.BR malloc (3)),
|
||||
and the buffer automatically grows as required.
|
||||
After closing the stream, the caller should
|
||||
.BR free (3)
|
||||
this buffer.
|
||||
|
||||
The locations pointed to by
|
||||
.IR ptr
|
||||
and
|
||||
.I sizeloc
|
||||
are used to report the current location and size of the buffer.
|
||||
When the stream is closed
|
||||
.RB ( fclose (3))
|
||||
or flushed
|
||||
.RB ( fflush (3)),
|
||||
the locations pointed to by
|
||||
.I ptr
|
||||
and
|
||||
.I sizeloc
|
||||
are updated to contain, respectively, a pointer to the buffer and the
|
||||
current size of the buffer.
|
||||
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 variables.
|
||||
|
||||
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 .
|
||||
|
||||
The stream's buffer position can be 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
|
||||
zeros.
|
||||
|
||||
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 fmemopen (),
|
||||
.BR open_memstream ()
|
||||
and
|
||||
.BR open_wmemstream ()
|
||||
return a
|
||||
Upon successful completion,
|
||||
.BR fmemopen ()
|
||||
returns a
|
||||
.I FILE
|
||||
pointer.
|
||||
Otherwise, NULL is returned and
|
||||
|
|
@ -225,11 +163,7 @@ Otherwise, NULL is returned and
|
|||
is set to indicate the error.
|
||||
.SH VERSIONS
|
||||
.BR fmemopen ()
|
||||
and
|
||||
.BR open_memstream ()
|
||||
were already available in glibc 1.0.x.
|
||||
.BR open_wmemstream ()
|
||||
is available since glibc 2.4.
|
||||
was already available in glibc 1.0.x.
|
||||
.SH ATTRIBUTES
|
||||
For an explanation of the terms used in this section, see
|
||||
.BR attributes (7).
|
||||
|
|
@ -240,17 +174,13 @@ l l l.
|
|||
Interface Attribute Value
|
||||
T{
|
||||
.BR fmemopen (),
|
||||
.br
|
||||
.BR open_memstream (),
|
||||
.br
|
||||
.BR open_wmemstream
|
||||
T} Thread safety MT-Safe
|
||||
.TE
|
||||
|
||||
.SH CONFORMING TO
|
||||
POSIX.1-2008.
|
||||
These functions are not specified in POSIX.1-2001,
|
||||
and are not widely available on other systems.
|
||||
This function is not specified in POSIX.1-2001,
|
||||
and is not widely available on other systems.
|
||||
|
||||
POSIX.1-2008 specifies that \(aqb\(aq in
|
||||
.IR mode
|
||||
|
|
@ -261,7 +191,7 @@ adjusts the standard to allow implementation-specific treatment for this case,
|
|||
thus permitting the glibc treatment of \(aqb\(aq.
|
||||
.SH NOTES
|
||||
There is no file descriptor associated with the file stream
|
||||
returned by these functions
|
||||
returned by this function
|
||||
(i.e.,
|
||||
.BR fileno (3)
|
||||
will return an error if called on the returned stream).
|
||||
|
|
@ -301,13 +231,6 @@ Binary mode was removed in glibc 2.22; a \(aqb\(aq specified in
|
|||
.I mode
|
||||
has no effect.
|
||||
.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
|
||||
|
||||
In versions of glibc before 2.22, if
|
||||
.I size
|
||||
is specified as zero,
|
||||
|
|
@ -374,7 +297,7 @@ ignored \(aqb\(aq in
|
|||
The program below uses
|
||||
.BR fmemopen ()
|
||||
to open an input buffer, and
|
||||
.BR open_memstream ()
|
||||
.BR open_memstream (3)
|
||||
to open a dynamically sized output buffer.
|
||||
The program scans its input string (taken from the program's
|
||||
first command-line argument) reading integers,
|
||||
|
|
@ -441,3 +364,4 @@ main(int argc, char *argv[])
|
|||
.SH SEE ALSO
|
||||
.BR fopen (3),
|
||||
.BR fopencookie (3)
|
||||
.BR open_memstream (3)
|
||||
|
|
|
|||
|
|
@ -1 +1,147 @@
|
|||
.so man3/fmemopen.3
|
||||
.\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
|
||||
.\" and 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 FMEMOPEN 3 2015-03-29 "GNU" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
open_memstream, open_wmemstream \- open a dynamic memory buffer stream
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.B #include <stdio.h>
|
||||
|
||||
.BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
|
||||
|
||||
.B #include <wchar.h>
|
||||
|
||||
.BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
|
||||
.fi
|
||||
.sp
|
||||
.in -4n
|
||||
Feature Test Macro Requirements for glibc (see
|
||||
.BR feature_test_macros (7)):
|
||||
.in
|
||||
.sp
|
||||
.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 buffer.
|
||||
The function dynamically allocates the buffer (in the manner of
|
||||
.BR malloc (3)),
|
||||
and the buffer automatically grows as required.
|
||||
After closing the stream, the caller should
|
||||
.BR free (3)
|
||||
this buffer.
|
||||
|
||||
The locations pointed to by
|
||||
.IR ptr
|
||||
and
|
||||
.I sizeloc
|
||||
are used to report the current location and size of the buffer.
|
||||
When the stream is closed
|
||||
.RB ( fclose (3))
|
||||
or flushed
|
||||
.RB ( fflush (3)),
|
||||
the locations pointed to by
|
||||
.I ptr
|
||||
and
|
||||
.I sizeloc
|
||||
are updated to contain, respectively, a pointer to the buffer and the
|
||||
current size of the buffer.
|
||||
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 variables.
|
||||
|
||||
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 .
|
||||
|
||||
The stream's buffer position can be 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
|
||||
zeros.
|
||||
|
||||
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
|
||||
|
||||
.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 EXAMPLE
|
||||
See
|
||||
.BR fmemopen (3).
|
||||
.SH SEE ALSO
|
||||
.BR fmemopen (3),
|
||||
.BR fopen (3),
|
||||
.BR fopencookie (3)
|
||||
|
|
|
|||
Loading…
Reference in New Issue