1*cd62a92dSRobert Mustacchi.\" 2*cd62a92dSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*cd62a92dSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*cd62a92dSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*cd62a92dSRobert Mustacchi.\" 1.0 of the CDDL. 6*cd62a92dSRobert Mustacchi.\" 7*cd62a92dSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*cd62a92dSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*cd62a92dSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10*cd62a92dSRobert Mustacchi.\" 11*cd62a92dSRobert Mustacchi.\" 12*cd62a92dSRobert Mustacchi.\" Copyright 2020 Robert Mustacchi 13*cd62a92dSRobert Mustacchi.\" 14*cd62a92dSRobert Mustacchi.Dd March 25, 2020 15*cd62a92dSRobert Mustacchi.Dt OPEN_MEMSTREAM 3C 16*cd62a92dSRobert Mustacchi.Os 17*cd62a92dSRobert Mustacchi.Sh NAME 18*cd62a92dSRobert Mustacchi.Nm open_memstream , 19*cd62a92dSRobert Mustacchi.Nm open_wmemstream 20*cd62a92dSRobert Mustacchi.Nd open a memory stream 21*cd62a92dSRobert Mustacchi.Sh SYNOPSIS 22*cd62a92dSRobert Mustacchi.In stdio.h 23*cd62a92dSRobert Mustacchi.Ft "FILE *" 24*cd62a92dSRobert Mustacchi.Fo open_memstream 25*cd62a92dSRobert Mustacchi.Fa "char **bufp" 26*cd62a92dSRobert Mustacchi.Fa "size_t *sizep" 27*cd62a92dSRobert Mustacchi.Fc 28*cd62a92dSRobert Mustacchi.In wchar.h 29*cd62a92dSRobert Mustacchi.Ft "FILE *" 30*cd62a92dSRobert Mustacchi.Fo open_wmemstream 31*cd62a92dSRobert Mustacchi.Fa "wchar_t **bufp" 32*cd62a92dSRobert Mustacchi.Fa "size_t *sizep" 33*cd62a92dSRobert Mustacchi.Fc 34*cd62a92dSRobert Mustacchi.Sh DESCRIPTION 35*cd62a92dSRobert MustacchiThe 36*cd62a92dSRobert Mustacchi.Fn open_memstream 37*cd62a92dSRobert Mustacchiand 38*cd62a92dSRobert Mustacchi.Fn open_wmemstream 39*cd62a92dSRobert Mustacchifunctions create an I/O stream that is backed by a dynamic memory buffer 40*cd62a92dSRobert Mustacchiwhich will grow as needed. 41*cd62a92dSRobert MustacchiThe stream is seekable and writable. 42*cd62a92dSRobert MustacchiThe stream is not readable. 43*cd62a92dSRobert MustacchiThe stream is byte-oriented in the case of the 44*cd62a92dSRobert Mustacchi.Fn open_memstream 45*cd62a92dSRobert Mustacchifunction or it is wide-oriented in the case of the 46*cd62a92dSRobert Mustacchi.Fn open_wmemstream 47*cd62a92dSRobert Mustacchifunction. 48*cd62a92dSRobert Mustacchi.Pp 49*cd62a92dSRobert MustacchiMemory for the stream is dynamically allocated and reallocated as though 50*cd62a92dSRobert Mustacchia call to 51*cd62a92dSRobert Mustacchi.Xr malloc 3C . 52*cd62a92dSRobert MustacchiAs the stream is written to, flushed, or closed, the underlying buffer 53*cd62a92dSRobert Mustacchiwill be grown automatically as required. 54*cd62a92dSRobert MustacchiAfter the stream is flushed or closed, the 55*cd62a92dSRobert Mustacchi.Fa bufp 56*cd62a92dSRobert Mustacchiargument will be filled in with a pointer to the current buffer. 57*cd62a92dSRobert MustacchiThe 58*cd62a92dSRobert Mustacchi.Fa sizep 59*cd62a92dSRobert Mustacchiargument will be filled in with the smaller of the current buffer length 60*cd62a92dSRobert Mustacchiand the current position in bytes 61*cd62a92dSRobert Mustacchi.Pq Fn open_memstream 62*cd62a92dSRobert Mustacchior wide characters 63*cd62a92dSRobert Mustacchi.Pq Fn open_wmemstream , 64*cd62a92dSRobert Mustacchiexcluding a NUL character. 65*cd62a92dSRobert MustacchiNote, because the current position is taken into account, the actual 66*cd62a92dSRobert Mustacchisize of the buffer may be larger than is found in 67*cd62a92dSRobert Mustacchi.Fa sizep ; 68*cd62a92dSRobert Mustacchihowever data should not be accessed beyond the indicated size. 69*cd62a92dSRobert MustacchiThe values stored in the 70*cd62a92dSRobert Mustacchi.Fa bufp 71*cd62a92dSRobert Mustacchiand 72*cd62a92dSRobert Mustacchi.Fa sizep 73*cd62a92dSRobert Mustacchiarguments are only valid until the next write operation on the stream 74*cd62a92dSRobert Mustacchior a call to 75*cd62a92dSRobert Mustacchi.Xr fclose 3C . 76*cd62a92dSRobert Mustacchi.Pp 77*cd62a92dSRobert MustacchiThe stream maintains both the current position and the current length of 78*cd62a92dSRobert Mustacchithe stream. 79*cd62a92dSRobert MustacchiBoth the initial position and length of the buffer are set to zero. 80*cd62a92dSRobert MustacchiWhenever a write at the current position exceeds the current length of the 81*cd62a92dSRobert Mustacchibuffer, the current length is increased and a NUL character, 82*cd62a92dSRobert Mustacchi.Sq \e0 83*cd62a92dSRobert Mustacchi.Pq Fn open_memstream 84*cd62a92dSRobert Mustacchior NUL wide character, 85*cd62a92dSRobert Mustacchi.Sq L\e0 86*cd62a92dSRobert Mustacchi.Pq Fn open_wmemstream 87*cd62a92dSRobert Mustacchiwill be added to the buffer. 88*cd62a92dSRobert MustacchiIf the stream is seeked beyond the current length and a subsequent write 89*cd62a92dSRobert Mustacchioccurs, intervening characters will be filled with the corresponding NUL 90*cd62a92dSRobert Mustacchicharacter for the stream. 91*cd62a92dSRobert Mustacchi.Pp 92*cd62a92dSRobert MustacchiTo release the stream, the caller must call the 93*cd62a92dSRobert Mustacchi.Xr fclose 3C 94*cd62a92dSRobert Mustacchifunction. 95*cd62a92dSRobert MustacchiThe corresponding dynamically allocated memory will be disassociated 96*cd62a92dSRobert Mustacchifrom the stream and will become owned by the caller. 97*cd62a92dSRobert MustacchiThe caller must eventually release the memory buffer pointed to in the 98*cd62a92dSRobert Mustacchi.Fa bufp 99*cd62a92dSRobert Mustacchiargument with a call to 100*cd62a92dSRobert Mustacchi.Xr free 3C . 101*cd62a92dSRobert Mustacchi.Ss Fn open_wmemstream , Xr fseek 3C , Xr fsetops 3C, and Xr ftell 3C 102*cd62a92dSRobert MustacchiThe specification for the 103*cd62a92dSRobert Mustacchi.Fn open_wmemstream 104*cd62a92dSRobert Mustacchifunction causes the 105*cd62a92dSRobert Mustacchi.Xr fseek 3C 106*cd62a92dSRobert Mustacchiand 107*cd62a92dSRobert Mustacchi.Xr ftell 3C 108*cd62a92dSRobert Mustacchifamilies of functions to operate differently. 109*cd62a92dSRobert MustacchiTraditionally, these functions always return units in bytes, regardless 110*cd62a92dSRobert Mustacchiof whether the underlying stream is byte- or wide-oriented. 111*cd62a92dSRobert MustacchiHowever, when used against a stream created by the 112*cd62a92dSRobert Mustacchi.Fn open_wmemstream 113*cd62a92dSRobert Mustacchifunction these now count in terms of units of wide characters. 114*cd62a92dSRobert MustacchiWhile this is different from the traditional behavior, this does mean 115*cd62a92dSRobert Mustacchithat the units will be the same as tracked in 116*cd62a92dSRobert Mustacchi.Fa sizep . 117*cd62a92dSRobert Mustacchi.Ss Fn open_wmemstream and byte-oriented functions 118*cd62a92dSRobert MustacchiUnlike other streams, streams created by 119*cd62a92dSRobert Mustacchi.Fn open_wmemstream 120*cd62a92dSRobert Mustacchiare not only wide-oriented, but operate in terms of the 121*cd62a92dSRobert Mustacchi.Vt wchar_t 122*cd62a92dSRobert Mustacchidata type. 123*cd62a92dSRobert MustacchiWhen normal bytes are written to the stream, an implicit multi-byte 124*cd62a92dSRobert Mustacchiconversion state is maintained. 125*cd62a92dSRobert MustacchiWriting byte sequences that don't correspond to valid byte sequences in 126*cd62a92dSRobert Mustacchithe locale can cause I/O errors to occur when using write functions such 127*cd62a92dSRobert Mustacchias 128*cd62a92dSRobert Mustacchi.Xr fputc 3C 129*cd62a92dSRobert Mustacchior 130*cd62a92dSRobert Mustacchi.Xr fwrite 3C , 131*cd62a92dSRobert Mustacchior when buffered data is flushed through functions like 132*cd62a92dSRobert Mustacchi.Xr fflush 3C 133*cd62a92dSRobert Mustacchior 134*cd62a92dSRobert Mustacchi.Xr fclose 3C . 135*cd62a92dSRobert Mustacchi.Pp 136*cd62a92dSRobert MustacchiThe same problem can occur when explicitly using wide characters, for 137*cd62a92dSRobert Mustacchiexample, 138*cd62a92dSRobert Mustacchi.Xr fputwc 3C , 139*cd62a92dSRobert Mustacchiif the 140*cd62a92dSRobert Mustacchiwide character represents a code point that is not valid in the current 141*cd62a92dSRobert Mustacchilocale. 142*cd62a92dSRobert MustacchiTo avoid these errors when flushing or closing, one can disable 143*cd62a92dSRobert Mustacchibuffering by passing 144*cd62a92dSRobert Mustacchi.Dv _IONBF 145*cd62a92dSRobert Mustacchias the buffering type with 146*cd62a92dSRobert Mustacchi.Xr setvbuf 3C . 147*cd62a92dSRobert Mustacchi.Pp 148*cd62a92dSRobert MustacchiIt is not recommended to change the locale of such a stream while 149*cd62a92dSRobert Mustacchiwriting a byte sequence that represents valid wide characters. 150*cd62a92dSRobert MustacchiThe behavior of using byte-oriented functions is not standardized and 151*cd62a92dSRobert Mustacchinot all systems will behave the same way. 152*cd62a92dSRobert Mustacchi.Sh RETURN VALUES 153*cd62a92dSRobert MustacchiUpon successful completion, the 154*cd62a92dSRobert Mustacchi.Fn open_memstream 155*cd62a92dSRobert Mustacchiand 156*cd62a92dSRobert Mustacchi.Fn open_wmemstream 157*cd62a92dSRobert Mustacchifunctions returns a pointer to a stream. 158*cd62a92dSRobert MustacchiOtherwise, 159*cd62a92dSRobert Mustacchi.Dv NULL 160*cd62a92dSRobert Mustacchiis returned and 161*cd62a92dSRobert Mustacchi.Dv errno 162*cd62a92dSRobert Mustacchiis set to indicate the error. 163*cd62a92dSRobert Mustacchi.Sh ERRORS 164*cd62a92dSRobert MustacchiThe 165*cd62a92dSRobert Mustacchi.Fn fmemopen 166*cd62a92dSRobert Mustacchifunction will fail if: 167*cd62a92dSRobert Mustacchi.Bl -tag -width Er 168*cd62a92dSRobert Mustacchi.It Er EINVAL 169*cd62a92dSRobert MustacchiEither of the 170*cd62a92dSRobert Mustacchi.Fa bufp 171*cd62a92dSRobert Mustacchior 172*cd62a92dSRobert Mustacchi.Fa sizep 173*cd62a92dSRobert Mustacchiarguments are 174*cd62a92dSRobert Mustacchi.Dv NULL . 175*cd62a92dSRobert Mustacchi.It Er EMFILE 176*cd62a92dSRobert Mustacchi.Brq FOPEN_MAX 177*cd62a92dSRobert Mustacchistreams are currently open in the calling process. 178*cd62a92dSRobert Mustacchi.Pp 179*cd62a92dSRobert Mustacchi.Brq STREAM_MAX 180*cd62a92dSRobert Mustacchistreams are currently open in the calling process. 181*cd62a92dSRobert Mustacchi.It Er ENOMEM 182*cd62a92dSRobert MustacchiThe system was unable to allocate memory for the stream or its backing 183*cd62a92dSRobert Mustacchimemory buffer. 184*cd62a92dSRobert Mustacchi.El 185*cd62a92dSRobert Mustacchi.Sh MT-LEVEL 186*cd62a92dSRobert Mustacchi.Sy MT-Safe 187*cd62a92dSRobert Mustacchi.Sh INTERFACE STABILITY 188*cd62a92dSRobert Mustacchi.Sy Committed 189*cd62a92dSRobert Mustacchi.Sh SEE ALSO 190*cd62a92dSRobert Mustacchi.Xr fclose 3C , 191*cd62a92dSRobert Mustacchi.Xr fflush 3C , 192*cd62a92dSRobert Mustacchi.Xr fmemopen 3C , 193*cd62a92dSRobert Mustacchi.Xr free 3C , 194*cd62a92dSRobert Mustacchi.Xr malloc 3C , 195*cd62a92dSRobert Mustacchi.Xr setvbuf 3C 196