FreeBSD Manual Pages
OPEN_MEMSTREAM(3) FreeBSD Library Functions Manual OPEN_MEMSTREAM(3) NAME open_memstream, open_wmemstream -- dynamic memory buffer stream open functions LIBRARY Standard C Library (libc, -lc) SYNOPSIS #include <stdio.h> FILE * open_memstream(char **bufp, size_t *sizep); #include <wchar.h> FILE * open_wmemstream(wchar_t **bufp, size_t *sizep); DESCRIPTION The open_memstream() and open_wmemstream() functions create a write-only, seekable stream backed by a dynamically allocated memory buffer. The open_memstream() function creates a byte-oriented stream, while the open_wmemstream() function creates a wide-oriented stream. Each stream maintains a current position and size. Initially, the posi- tion and size are set to zero. Each write begins at the current position and advances it the number of successfully written bytes for open_memstream() or wide characters for open_wmemstream(). If a write moves the current position beyond the length of the buffer, the length of the buffer is extended and a null character is appended to the buffer. A stream's buffer always contains a null character at the end of the buf- fer that is not included in the current length. If a stream's current position is moved beyond the current length via a seek operation and a write is performed, the characters between the cur- rent length and the current position are filled with null characters be- fore the write is performed. After a successful call to fclose(3) or fflush(3), the pointer referenced by bufp will contain the start of the memory buffer and the variable ref- erenced by sizep will contain the smaller of the current position and the current buffer length. After a successful call to fflush(3), the pointer referenced by bufp and the variable referenced by sizep are only valid until the next write op- eration or a call to fclose(3). Once a stream is closed, the allocated buffer referenced by bufp should be released via a call to free(3) when it is no longer needed. IMPLEMENTATION NOTES Internally all I/O streams are effectively byte-oriented, so using wide- oriented operations to write to a stream opened via open_wmemstream() re- sults in wide characters being expanded to a stream of multibyte charac- ters in stdio's internal buffers. These multibyte characters are then converted back to wide characters when written into the stream. As a re- sult, the wide-oriented streams maintain an internal multibyte character conversion state that is cleared on any seek opertion that changes the current position. This should have no effect as long as wide-oriented output operations are used on a wide-oriented stream. RETURN VALUES Upon successful completion, open_memstream() and open_wmemstream() return a FILE pointer. Otherwise, NULL is returned and the global variable errno is set to indicate the error. ERRORS [EINVAL] The bufp or sizep argument was NULL. [ENOMEM] Memory for the stream or buffer could not be allo- cated. SEE ALSO fclose(3), fflush(3), fopen(3), free(3), fseek(3), stdio(3), sbuf(9) STANDARDS The open_memstream() and open_wmemstream() functions conform to IEEE Std 1003.1-2008 ("POSIX.1"). FreeBSD 13.0 August 1, 2015 FreeBSD 13.0
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | RETURN VALUES | ERRORS | SEE ALSO | STANDARDS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=open_memstream&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>