diff options
Diffstat (limited to 'man-pages-posix-2013/man3p/open_memstream.3p')
| -rw-r--r-- | man-pages-posix-2013/man3p/open_memstream.3p | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man3p/open_memstream.3p b/man-pages-posix-2013/man3p/open_memstream.3p new file mode 100644 index 0000000..7e1a648 --- /dev/null +++ b/man-pages-posix-2013/man3p/open_memstream.3p @@ -0,0 +1,189 @@ +'\" et +.TH OPEN_MEMSTREAM "3P" 2013 "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(). +.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 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 +\fB +#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 \fR +.P +.RE +.P +This program produces the following output: +.sp +.RS 4 +.nf +\fB +buf=hello my world, len=14 +buf=good-bye world, len=14 +.fi \fR +.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\(hy2008, +.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, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html . + +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 . |