1cd62a92dSRobert Mustacchi.\" 2cd62a92dSRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3cd62a92dSRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4cd62a92dSRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5cd62a92dSRobert Mustacchi.\" 1.0 of the CDDL. 6cd62a92dSRobert Mustacchi.\" 7cd62a92dSRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8cd62a92dSRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9cd62a92dSRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 10cd62a92dSRobert Mustacchi.\" 11cd62a92dSRobert Mustacchi.\" 12cd62a92dSRobert Mustacchi.\" Copyright 2020 Robert Mustacchi 13cd62a92dSRobert Mustacchi.\" 14*4a8d6d7cSPeter Tribble.Dd February 17, 2023 15cd62a92dSRobert Mustacchi.Dt FMEMOPEN 3C 16cd62a92dSRobert Mustacchi.Os 17cd62a92dSRobert Mustacchi.Sh NAME 18cd62a92dSRobert Mustacchi.Nm fmemopen 19cd62a92dSRobert Mustacchi.Nd open a memory stream 20cd62a92dSRobert Mustacchi.Sh SYNOPSIS 21cd62a92dSRobert Mustacchi.In stdio.h 22cd62a92dSRobert Mustacchi.Ft "FILE *" 23cd62a92dSRobert Mustacchi.Fo fmemopen 24cd62a92dSRobert Mustacchi.Fa "void *restrict buf" 25cd62a92dSRobert Mustacchi.Fa "size_t size" 26cd62a92dSRobert Mustacchi.Fa "const char *restrict mode" 27cd62a92dSRobert Mustacchi.Fc 28cd62a92dSRobert Mustacchi.Sh DESCRIPTION 29cd62a92dSRobert MustacchiThe 30cd62a92dSRobert Mustacchi.Fn fmemopen 31cd62a92dSRobert Mustacchifunction provides a means of associating a file stream with a 32cd62a92dSRobert Mustacchicorresponding memory buffer of a fixed size. 33cd62a92dSRobert MustacchiThe resulting stream can then be used just like any other stream, and 34cd62a92dSRobert Mustacchiwhen done should be released by calling the 35cd62a92dSRobert Mustacchi.Xr fclose 3C 36cd62a92dSRobert Mustacchifunction. 37cd62a92dSRobert Mustacchi.Pp 38cd62a92dSRobert MustacchiThe stream can either dynamically allocate memory or it can use an 39cd62a92dSRobert Mustacchiexisting memory buffer. 40cd62a92dSRobert MustacchiIf 41cd62a92dSRobert Mustacchi.Fa buf 42cd62a92dSRobert Mustacchiis 43cd62a92dSRobert Mustacchi.Dv NULL , 44cd62a92dSRobert Mustacchithen a buffer 45cd62a92dSRobert Mustacchi.Fa size 46cd62a92dSRobert Mustacchibytes long will be allocated for the stream and initialized to zero. 47cd62a92dSRobert MustacchiThis buffer will be allocated as though a call to 48cd62a92dSRobert Mustacchi.Xr malloc 3C 49cd62a92dSRobert Mustacchiand will be freed when 50cd62a92dSRobert Mustacchi.Xr fclose 3C 51cd62a92dSRobert Mustacchiis called. 52cd62a92dSRobert MustacchiWhen using this mode, the stream must be created for update 53cd62a92dSRobert Mustacchi.Po 54cd62a92dSRobert Mustacchiindicated by a 55cd62a92dSRobert Mustacchi.Sq + 56cd62a92dSRobert Mustacchicharacter in the 57cd62a92dSRobert Mustacchi.Fa mode 58cd62a92dSRobert Mustacchiargument 59cd62a92dSRobert Mustacchi.Pc . 60cd62a92dSRobert MustacchiOtherwise, it is assumed that 61cd62a92dSRobert Mustacchi.Fa buf 62cd62a92dSRobert Mustacchiis at least 63cd62a92dSRobert Mustacchi.Fa size 64cd62a92dSRobert Mustacchibytes long. 65cd62a92dSRobert Mustacchi.Pp 66cd62a92dSRobert MustacchiThe 67cd62a92dSRobert Mustacchi.Fa mode 68cd62a92dSRobert Mustacchiargument determines whether the stream is opened for read, write, or 69cd62a92dSRobert Mustacchiappend. 70cd62a92dSRobert MustacchiThe 71cd62a92dSRobert Mustacchi.Fa mode 72cd62a92dSRobert Mustacchiargument accepts all the same values as 73cd62a92dSRobert Mustacchi.Xr fopen 3C . 74cd62a92dSRobert Mustacchi.Pp 75cd62a92dSRobert MustacchiThe resulting stream behaves in a similar way to a stream backed by a 76cd62a92dSRobert Mustacchifile. 77cd62a92dSRobert MustacchiThe stream can be read and written to. 78*4a8d6d7cSPeter TribbleThe stream is seekable and can either be byte or wide-character 79cd62a92dSRobert Mustacchioriented. 80cd62a92dSRobert MustacchiA NUL byte has no special meaning when reading. 81cd62a92dSRobert Mustacchi.Pp 82cd62a92dSRobert MustacchiThe stream logically tracks three different values: 83cd62a92dSRobert Mustacchi.Bl -enum -offset indent 84cd62a92dSRobert Mustacchi.It 85cd62a92dSRobert MustacchiThe current position in the stream. 86cd62a92dSRobert Mustacchi.It 87cd62a92dSRobert MustacchiThe current size of the stream. 88cd62a92dSRobert Mustacchi.It 89cd62a92dSRobert MustacchiThe maximum size of the stream. 90cd62a92dSRobert Mustacchi.El 91cd62a92dSRobert Mustacchi.Pp 92cd62a92dSRobert MustacchiThe current position is where reads or writes take place. 93cd62a92dSRobert MustacchiWhen the stream is opened for read or write 94cd62a92dSRobert Mustacchi.Pq r, r+, w, w+ 95cd62a92dSRobert Mustacchithen the initial position is set to zero. 96cd62a92dSRobert MustacchiIf the stream is opened for update 97cd62a92dSRobert Mustacchi.Pq a, a+ 98cd62a92dSRobert Mustacchithen the initial position is set to the first NUL byte in the buffer. 99cd62a92dSRobert Mustacchi.Pp 100cd62a92dSRobert MustacchiThe current size of the stream represents the length of the stream. 101cd62a92dSRobert MustacchiLike a file, this starts at a specific size and then can grow over time. 102cd62a92dSRobert MustacchiUnlike a file, where the maximum size is determined by the file system, 103cd62a92dSRobert Mustacchithe maximum size here is determined at the creation of the stream. 104cd62a92dSRobert Mustacchi.Pp 105cd62a92dSRobert MustacchiThis size is used when using 106cd62a92dSRobert Mustacchi.Dv SEEK_END 107cd62a92dSRobert Mustacchias an argument to functions like 108cd62a92dSRobert Mustacchi.Xr fseek 3C . 109cd62a92dSRobert MustacchiReads cannot advance beyond the current size of the stream and 110cd62a92dSRobert Mustacchiattempting to read beyond it is considered hitting the end-of-file. 111cd62a92dSRobert MustacchiWrites beyond the end of the current size will cause the current size to 112cd62a92dSRobert Mustacchiincrease, though it cannot increase beyond the maximum size. 113cd62a92dSRobert Mustacchi.Pp 114cd62a92dSRobert MustacchiThe initial size of the stream varies. 115cd62a92dSRobert MustacchiIt is set depending on the mode and works as follows: 116cd62a92dSRobert Mustacchi.Bl -tag -width Sy -offset indent 117cd62a92dSRobert Mustacchi.It Sy r, r+ 118cd62a92dSRobert MustacchiThe size is set to the 119cd62a92dSRobert Mustacchi.Fa size 120cd62a92dSRobert Mustacchiargument. 121cd62a92dSRobert Mustacchi.It Sy w, w+ 122cd62a92dSRobert MustacchiThe initial size is set to zero. 123cd62a92dSRobert Mustacchi.It Sy a, a+ 124cd62a92dSRobert MustacchiThe initial size is set according to the following rules: 125cd62a92dSRobert Mustacchi.Bl -enum 126cd62a92dSRobert Mustacchi.It 127cd62a92dSRobert MustacchiIf 128cd62a92dSRobert Mustacchi.Fa buf 129cd62a92dSRobert Mustacchiis a 130cd62a92dSRobert Mustacchi.Dv NULL 131cd62a92dSRobert Mustacchipointer, the current size is set to zero. 132cd62a92dSRobert Mustacchi.It 133cd62a92dSRobert MustacchiIf a NUL byte is found in the first 134cd62a92dSRobert Mustacchi.Fa size 135cd62a92dSRobert Mustacchibytes of 136cd62a92dSRobert Mustacchi.Fa buf , 137cd62a92dSRobert Mustacchithen the current size is set to the first NUL byte. 138cd62a92dSRobert Mustacchi.It 139cd62a92dSRobert MustacchiThe position is set to the 140cd62a92dSRobert Mustacchi.Fa size 141cd62a92dSRobert Mustacchiargument 142cd62a92dSRobert Mustacchi.Pq the maximum size 143cd62a92dSRobert Mustacchiif no NUL byte was found in 144cd62a92dSRobert Mustacchi.Fa buf . 145cd62a92dSRobert Mustacchi.El 146cd62a92dSRobert Mustacchi.El 147cd62a92dSRobert Mustacchi.Pp 148cd62a92dSRobert MustacchiThe maximum size of the stream is determined by the 149cd62a92dSRobert Mustacchi.Fa size 150cd62a92dSRobert Mustacchiargument. 151cd62a92dSRobert MustacchiWrites beyond this size are dropped. 152cd62a92dSRobert MustacchiAttempts to seek beyond the maximum size will result in an error. 153cd62a92dSRobert Mustacchi.Pp 154cd62a92dSRobert MustacchiIf the stream was open for writing or update, when the stream is flushed 155cd62a92dSRobert Mustacchior closed, a NUL byte will be written to terminate the stream based on 156cd62a92dSRobert Mustacchithe current position and size of the stream. 157cd62a92dSRobert MustacchiIf the stream was open for update, if the stream is flushed or closed 158cd62a92dSRobert Mustacchiand the last write changed the current buffer size, a NUL byte will be 159cd62a92dSRobert Mustacchiwritten if there is still space for it within the buffer. 160cd62a92dSRobert Mustacchi.Pp 161cd62a92dSRobert MustacchiBy default, all streams are buffered. 162cd62a92dSRobert MustacchiThis means that writes beyond the size of the memory buffer could fail, 163cd62a92dSRobert Mustacchibut not be seen until the stream is flushed or closed. 164cd62a92dSRobert MustacchiTo detect errors right away, one can explicitly disable buffering with 165cd62a92dSRobert Mustacchithe 166cd62a92dSRobert Mustacchi.Xr setvbuf 3C 167cd62a92dSRobert Mustacchifunction or perform explicit buffer flushes with the 168cd62a92dSRobert Mustacchi.Xr fflush 3C 169cd62a92dSRobert Mustacchifunction. 170cd62a92dSRobert Mustacchi.Sh RETURN VALUES 171cd62a92dSRobert MustacchiUpon successful completion, the 172cd62a92dSRobert Mustacchi.Fn fmemopen 173cd62a92dSRobert Mustacchifunction returns a pointer to a stream. 174cd62a92dSRobert MustacchiOtherwise, 175cd62a92dSRobert Mustacchi.Dv NULL 176cd62a92dSRobert Mustacchiis returned and 177cd62a92dSRobert Mustacchi.Dv errno 178cd62a92dSRobert Mustacchiis set to indicate the error. 179cd62a92dSRobert Mustacchi.Sh ERRORS 180cd62a92dSRobert MustacchiThe 181cd62a92dSRobert Mustacchi.Fn fmemopen 182cd62a92dSRobert Mustacchifunction will fail if: 183cd62a92dSRobert Mustacchi.Bl -tag -width Er 184cd62a92dSRobert Mustacchi.It Er EINVAL 185cd62a92dSRobert MustacchiThe value of 186cd62a92dSRobert Mustacchi.Fa mode 187cd62a92dSRobert Mustacchiis invalid. 188cd62a92dSRobert Mustacchi.Pp 189cd62a92dSRobert MustacchiThe 190cd62a92dSRobert Mustacchi.Fa size 191cd62a92dSRobert Mustacchiargument was zero. 192cd62a92dSRobert Mustacchi.Pp 193cd62a92dSRobert MustacchiThe 194cd62a92dSRobert Mustacchi.Fa buf 195cd62a92dSRobert Mustacchiargument is 196cd62a92dSRobert Mustacchi.Dv NULL 197cd62a92dSRobert Mustacchiand the 198cd62a92dSRobert Mustacchi.Fa mode 199cd62a92dSRobert Mustacchiargument does not contain a 200cd62a92dSRobert Mustacchi.Sq + 201cd62a92dSRobert Mustacchicharacter. 202cd62a92dSRobert Mustacchi.It Er EMFILE 203cd62a92dSRobert Mustacchi.Brq FOPEN_MAX 204cd62a92dSRobert Mustacchistreams are currently open in the calling process. 205cd62a92dSRobert Mustacchi.Pp 206cd62a92dSRobert Mustacchi.Brq STREAM_MAX 207cd62a92dSRobert Mustacchistreams are currently open in the calling process. 208cd62a92dSRobert Mustacchi.It Er ENOMEM 209cd62a92dSRobert MustacchiThe system was unable to allocate memory for the stream or its backing 210cd62a92dSRobert Mustacchibuffer. 211cd62a92dSRobert Mustacchi.El 212cd62a92dSRobert Mustacchi.Sh MT-LEVEL 213cd62a92dSRobert Mustacchi.Sy MT-Safe 214cd62a92dSRobert Mustacchi.Sh INTERFACE STABILITY 215cd62a92dSRobert Mustacchi.Sy Committed 216cd62a92dSRobert Mustacchi.Sh SEE ALSO 217cd62a92dSRobert Mustacchi.Xr fclose 3C , 218cd62a92dSRobert Mustacchi.Xr fflush 3C , 219cd62a92dSRobert Mustacchi.Xr fopen 3C , 220cd62a92dSRobert Mustacchi.Xr fseek 3C , 221cd62a92dSRobert Mustacchi.Xr malloc 3C , 222cd62a92dSRobert Mustacchi.Xr open_memstream 3C 223