open_memstream.3p (5461B)
- '\" et
- .TH OPEN_MEMSTREAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- open_memstream, open_wmemstream
- \(em open a dynamic memory buffer stream
- .SH SYNOPSIS
- .LP
- .nf
- #include <stdio.h>
- .P
- FILE *open_memstream(char **\fIbufp\fP, size_t *\fIsizep\fP);
- .P
- #include <wchar.h>
- .P
- FILE *open_wmemstream(wchar_t **\fIbufp\fP, size_t *\fIsizep\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIopen_memstream\fR()
- and
- \fIopen_wmemstream\fR()
- functions shall create an I/O stream associated with a dynamically
- allocated memory buffer. The stream shall be opened for writing and
- shall be seekable.
- .P
- The stream associated with a call to
- \fIopen_memstream\fR()
- shall be byte-oriented.
- .P
- The stream associated with a call to
- \fIopen_wmemstream\fR()
- shall be wide-oriented.
- .P
- The stream shall maintain a current position in the allocated buffer
- and a current buffer length. The position shall be initially set to
- zero (the start of the buffer). Each write to the stream shall start at
- the current position and move this position by the number of
- successfully written bytes for
- \fIopen_memstream\fR()
- or the number of successfully written wide characters for
- \fIopen_wmemstream\fR().
- The length shall be initially set to zero. If a write moves the
- position to a value larger than the current length, the current length
- shall be set to this position. In this case a null character for
- \fIopen_memstream\fR()
- or a null wide character for
- \fIopen_wmemstream\fR()
- shall be appended to the current buffer. For both functions the
- terminating null is not included in the calculation of the buffer
- length.
- .P
- After a successful
- \fIfflush\fR()
- or
- \fIfclose\fR(),
- the pointer referenced by
- .IR bufp
- shall contain the address of the buffer, and the variable pointed to by
- .IR sizep
- shall contain the smaller of the current buffer length and the
- number of bytes for
- \fIopen_memstream\fR(),
- or the number of wide characters for
- \fIopen_wmemstream\fR(),
- between the beginning of the buffer and the current file position indicator.
- .P
- After a successful
- \fIfflush\fR()
- the pointer referenced by
- .IR bufp
- and the variable referenced by
- .IR sizep
- remain valid only until the next write operation on the stream or a
- call to
- \fIfclose\fR().
- .P
- After a successful
- \fIfclose\fR(),
- the pointer referenced by
- .IR bufp
- can be passed to
- \fIfree\fR().
- .SH "RETURN VALUE"
- Upon successful completion, these functions shall return a pointer to
- the object controlling the stream. Otherwise, a null pointer shall be
- returned, and
- .IR errno
- shall be set to indicate the error.
- .SH ERRORS
- These functions shall fail if:
- .TP
- .BR EMFILE
- {STREAM_MAX}
- streams are currently open in the calling process.
- .P
- These functions may fail if:
- .TP
- .BR EINVAL
- .IR bufp
- or
- .IR sizep
- are NULL.
- .TP
- .BR EMFILE
- {FOPEN_MAX}
- streams are currently open in the calling process.
- .TP
- .BR ENOMEM
- Memory for the stream or the buffer could not be allocated.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .sp
- .RS 4
- .nf
- #include <stdio.h>
- #include <stdlib.h>
- .P
- int
- main (void)
- {
- FILE *stream;
- char *buf;
- size_t len;
- off_t eob;
- .P
- stream = open_memstream (&buf, &len);
- if (stream == NULL)
- /* handle error */ ;
- fprintf (stream, "hello my world");
- fflush (stream);
- printf ("buf=%s, len=%zu\en", buf, len);
- eob = ftello(stream);
- fseeko (stream, 0, SEEK_SET);
- fprintf (stream, "good-bye");
- fseeko (stream, eob, SEEK_SET);
- fclose (stream);
- printf ("buf=%s, len=%zu\en", buf, len);
- free (buf);
- return 0;
- }
- .fi
- .P
- .RE
- .P
- This program produces the following output:
- .sp
- .RS 4
- .nf
- buf=hello my world, len=14
- buf=good-bye world, len=14
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- The buffer created by these functions should be freed by the
- application after closing the stream, by means of a call to
- \fIfree\fR().
- .SH RATIONALE
- These functions are similar to
- \fIfmemopen\fR()
- except that the memory is always allocated dynamically by the function,
- and the stream is opened only for output.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIfclose\fR\^(\|)",
- .IR "\fIfdopen\fR\^(\|)",
- .IR "\fIfflush\fR\^(\|)",
- .IR "\fIfmemopen\fR\^(\|)",
- .IR "\fIfopen\fR\^(\|)",
- .IR "\fIfree\fR\^(\|)",
- .IR "\fIfreopen\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<stdio.h>\fP",
- .IR "\fB<wchar.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .