+++ /dev/null
-.\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
-.\" and Copyright 2005, 2012 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-01-22 "GNU" "Linux Programmer's Manual"
-.SH NAME
-fmemopen, open_memstream, open_wmemstream \- 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
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.in
-.sp
-.BR fmemopen (),
-.BR open_memstream (),
-.BR open_wmemstream ():
-.PD 0
-.ad l
-.RS 4
-.TP 4
-Since glibc 2.10:
-_XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
-.TP
-Before glibc 2.10:
-_GNU_SOURCE
-.RE
-.ad
-.PD
-.SH DESCRIPTION
-The
-.BR fmemopen ()
-function opens a stream that permits the access specified by
-.IR mode .
-The stream allows I/O to be performed on the string or memory buffer
-pointed to by
-.IR buf .
-This buffer must be at least
-.I size
-bytes long.
-.PP
-The argument
-.I mode
-is the same as for
-.BR fopen (3).
-If
-.I mode
-specifies an append mode, then the initial file position is set to
-the location of the first null byte (\(aq\\0\(aq) in the buffer;
-otherwise the initial file position is set to the start of the buffer.
-Since glibc 2.9,
-the letter \(aqb\(aq may be specified as the second character in
-.IR mode .
-This provides "binary" mode:
-writes don't implicitly add a terminating null byte, and
-.BR fseek (3)
-.B SEEK_END
-is relative to the end of the buffer (i.e., the value specified by the
-.I size
-argument), rather than the current string length.
-.PP
-When a stream that has been opened for writing is flushed
-.RB ( fflush (3))
-or closed
-.RB ( fclose (3)),
-a null byte is written at the end of the buffer if there is space.
-The caller should ensure that an extra byte is available in the
-buffer
-(and that
-.I size
-counts that byte)
-to allow for this.
-
-Attempts to write more than
-.I size
-bytes to the buffer result in an error.
-(By default, such errors will be visible only when the
-.I stdio
-buffer is flushed.
-Disabling buffering with the following call
-may be useful to detect errors at the time of an output operation:
-
- setbuf(stdream, NULL);
-
-Alternatively, the caller can explicitly set
-.I buf
-as the stdio stream buffer, at the same time informing stdio
-of the buffer's size, using:
-
- setbuffer(stream, buf, size);
-
-.\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
-.\" and
-.\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
-.PP
-In a stream opened for reading,
-null bytes (\(aq\\0\(aq) in the buffer do not cause read
-operations to return an end-of-file indication.
-A read from the buffer will indicate end-of-file
-only when the file pointer advances
-.I size
-bytes past the start of the buffer.
-.PP
-If
-.I buf
-is specified as NULL, then
-.BR fmemopen ()
-dynamically allocates a buffer
-.I size
-bytes long.
-This is useful for an application that wants to write data to
-a temporary buffer and then read it back again.
-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).
-
-The
-.BR open_memstream ()
-function opens a stream for writing to a buffer.
-The buffer
-is dynamically allocated (as with
-.BR malloc (3)),
-and automatically grows as required.
-After closing the stream, the caller should
-.BR free (3)
-this 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 file position can be changed with
-.BR fseek (3)
-or
-.BR fseeko (3).
-Moving the file 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
-.I FILE
-pointer.
-Otherwise, NULL is returned and
-.I errno
-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.
-.SH CONFORMING TO
-POSIX.1-2008.
-These functions are not specified in POSIX.1-2001,
-and are not widely available on other systems.
-
-POSIX.1-2008 specifies that \(aqb\(aq in
-.IR mode
-shall be ignored.
-However, Technical Corrigendum 1
-.\" http://austingroupbugs.net/view.php?id=396
-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
-(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
-
-If
-.I size
-is specified as zero,
-.BR fmemopen ()
-fails with the error
-.BR EINVAL .
-.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=11216
-It would be more consistent if this case successfully created
-a stream that then returned end of file on the first attempt at reading.
-Furthermore, POSIX.1-2008 does not specify a failure for this case.
-
-Specifying append mode ("a" or "a+") for
-.BR fmemopen ()
-sets the initial file position to the first null byte, but
-.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13152
-(if the file offset is reset to a location other than
-the end of the stream)
-does not force subsequent writes to append at the end of the stream.
-
-If the
-.I mode
-argument to
-.BR fmemopen ()
-specifies append ("a" or "a+"), and the
-.I size
-argument does not cover a null byte in
-.IR buf ,
-then, according to POSIX.1-2008,
-the initial file position should be set to
-the next byte after the end of the buffer.
-However, in this case the glibc
-.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13151
-.BR fmemopen ()
-sets the file position to \-1.
-
-To specify binary mode for
-.BR fmemopen ()
-the \(aqb\(aq must be the
-.I second
-character in
-.IR mode .
-Thus, for example, "wb+" has the desired effect, but "w+b" does not.
-This is inconsistent with the treatment of
-.\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12836
-.IR mode
-by
-.BR fopen (3).
-
-The glibc 2.9 addition of "binary" mode for
-.BR fmemopen ()
-.\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
-silently changed the ABI: previously,
-.BR fmemopen ()
-ignored \(aqb\(aq in
-.IR mode .
-.SH EXAMPLE
-The program below uses
-.BR fmemopen ()
-to open an input buffer, and
-.BR open_memstream ()
-to open a dynamically sized output buffer.
-The program scans its input string (taken from the program's
-first command-line argument) reading integers,
-and writes the squares of these integers to the output buffer.
-An example of the output produced by this program is the following:
-.in +4n
-.nf
-
-.RB "$" " ./a.out \(aq1 23 43\(aq"
-size=11; ptr=1 529 1849
-.fi
-.in
-.SS Program source
-\&
-.nf
-#define _GNU_SOURCE
-#include <string.h>
-#include <stdio.h>
-#include <stdlib.h>
-
-#define handle_error(msg) \\
- do { perror(msg); exit(EXIT_FAILURE); } while (0)
-
-int
-main(int argc, char *argv[])
-{
- FILE *out, *in;
- int v, s;
- size_t size;
- char *ptr;
-
- if (argc != 2) {
- fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
- exit(EXIT_FAILURE);
- }
-
- in = fmemopen(argv[1], strlen(argv[1]), "r");
- if (in == NULL)
- handle_error("fmemopen");
-
- out = open_memstream(&ptr, &size);
- if (out == NULL)
- handle_error("open_memstream");
-
- for (;;) {
- s = fscanf(in, "%d", &v);
- if (s <= 0)
- break;
-
- s = fprintf(out, "%d ", v * v);
- if (s == \-1)
- handle_error("fprintf");
- }
- fclose(in);
- fclose(out);
- printf("size=%zu; ptr=%s\\n", size, ptr);
- free(ptr);
- exit(EXIT_SUCCESS);
-}
-.fi
-.SH SEE ALSO
-.BR fopen (3),
-.BR fopencookie (3)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
