man3/fmemopen.3

   1 .\" Copyright 2005, 2012, 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   4 .\" Distributed under the GPL.
   5 .\" %%%LICENSE_END
   6 .\"
   7 .TH FMEMOPEN 3 2021-03-22 "GNU" "Linux Programmer's Manual"
   8 .SH NAME
   9 fmemopen \-  open memory as stream
  10 .SH SYNOPSIS
  11 .nf
  12 .B #include <stdio.h>
  13 .PP
  14 .BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"
  15 .fi
  16 .PP
  17 .RS -4
  18 Feature Test Macro Requirements for glibc (see
  19 .BR feature_test_macros (7)):
  20 .RE
  21 .PP
  22 .BR fmemopen ():
  23 .nf
  24     Since glibc 2.10:
  25         _POSIX_C_SOURCE >= 200809L
  26     Before glibc 2.10:
  27         _GNU_SOURCE
  28 .fi
  29 .SH DESCRIPTION
  30 The
  31 .BR fmemopen ()
  32 function opens a stream that permits the access specified by
  33 .IR mode .
  34 The stream allows I/O to be performed on the string or memory buffer
  35 pointed to by
  36 .IR buf .
  37 .PP
  38 The
  39 .I mode
  40 argument specifies the semantics of I/O on the stream,
  41 and is one of the following:
  42 .TP
  43 .I r
  44 The stream is opened for reading.
  45 .TP
  46 .I w
  47 The stream is opened for writing.
  48 .TP
  49 .I a
  50 Append; open the stream for writing,
  51 with the initial buffer position set to the first null byte.
  52 .TP
  53 .I r+
  54 Open the stream for reading and writing.
  55 .TP
  56 .I w+
  57 Open the stream for reading and writing.
  58 The buffer contents are truncated
  59 (i.e., \(aq\e0\(aq is placed in the first byte of the buffer).
  60 .TP
  61 .I a+
  62 Append; open the stream for reading and writing,
  63 with the initial buffer position set to the first null byte.
  64 .PP
  65 The stream maintains the notion of a current position,
  66 the location where the next I/O operation will be performed.
  67 The current position is implicitly updated by I/O operations.
  68 It can be explicitly updated using
  69 .BR fseek (3),
  70 and determined using
  71 .BR ftell (3).
  72 In all modes other than append,
  73 the initial position is set to the start of the buffer.
  74 In append mode, if no null byte is found within the buffer,
  75 then the initial position is
  76 .IR size+1 .
  77 .PP
  78 If
  79 .I buf
  80 is specified as NULL, then
  81 .BR fmemopen ()
  82 allocates a buffer of
  83 .I size
  84 bytes.
  85 This is useful for an application that wants to write data to
  86 a temporary buffer and then read it back again.
  87 The initial position is set to the start of the buffer.
  88 The buffer is automatically freed when the stream is closed.
  89 Note that the caller has no way to obtain a pointer to the
  90 temporary buffer allocated by this call (but see
  91 .BR open_memstream (3)).
  92 .PP
  93 If
  94 .I buf
  95 is not NULL, then it should point to a buffer of at least
  96 .I len
  97 bytes allocated by the caller.
  98 .PP
  99 When a stream that has been opened for writing is flushed
 100 .RB ( fflush (3))
 101 or closed
 102 .RB ( fclose (3)),
 103 a null byte is written at the end of the buffer if there is space.
 104 The caller should ensure that an extra byte is available in the
 105 buffer
 106 (and that
 107 .I size
 108 counts that byte)
 109 to allow for this.
 110 .PP
 111 In a stream opened for reading,
 112 null bytes (\(aq\e0\(aq) in the buffer do not cause read
 113 operations to return an end-of-file indication.
 114 A read from the buffer will indicate end-of-file
 115 only when the current buffer position advances
 116 .I size
 117 bytes past the start of the buffer.
 118 .PP
 119 Write operations take place either at the current position
 120 (for modes other than append), or at the current size of the stream
 121 (for append modes).
 122 .PP
 123 Attempts to write more than
 124 .I size
 125 bytes to the buffer result in an error.
 126 By default, such errors will be visible
 127 (by the absence of data) only when the
 128 .I stdio
 129 buffer is flushed.
 130 Disabling buffering with the following call
 131 may be useful to detect errors at the time of an output operation:
 132 .PP
 133     setbuf(stream, NULL);
 134 .SH RETURN VALUE
 135 Upon successful completion,
 136 .BR fmemopen ()
 137 returns a
 138 .I FILE
 139 pointer.
 140 Otherwise, NULL is returned and
 141 .I errno
 142 is set to indicate the error.
 143 .SH VERSIONS
 144 .BR fmemopen ()
 145 was already available in glibc 1.0.x.
 146 .SH ATTRIBUTES
 147 For an explanation of the terms used in this section, see
 148 .BR attributes (7).
 149 .ad l
 150 .nh
 151 .TS
 152 allbox;
 153 lbx lb lb
 154 l l l.
 155 Interface       Attribute       Value
 156 T{
 157 .BR fmemopen (),
 158 T}      Thread safety   MT-Safe
 159 .TE
 160 .hy
 161 .ad
 162 .sp 1
 163 .SH CONFORMING TO
 164 POSIX.1-2008.
 165 This function is not specified in POSIX.1-2001,
 166 and is not widely available on other systems.
 167 .PP
 168 POSIX.1-2008 specifies that \(aqb\(aq in
 169 .IR mode
 170 shall be ignored.
 171 However, Technical Corrigendum 1
 172 .\" http://austingroupbugs.net/view.php?id=396
 173 adjusts the standard to allow implementation-specific treatment for this case,
 174 thus permitting the glibc treatment of \(aqb\(aq.
 175 .SH NOTES
 176 There is no file descriptor associated with the file stream
 177 returned by this function
 178 (i.e.,
 179 .BR fileno (3)
 180 will return an error if called on the returned stream).
 181 .PP
 182 With version 2.22, binary mode (see below) was removed,
 183 many longstanding bugs in the implementation of
 184 .BR fmemopen ()
 185 were fixed, and a new versioned symbol was created for this interface.
 186 .\"
 187 .SS Binary mode
 188 From version 2.9 to 2.21, the glibc implementation of
 189 .BR fmemopen ()
 190 supported a "binary" mode,
 191 enabled by specifying the letter \(aqb\(aq as the second character in
 192 .IR mode .
 193 In this mode,
 194 writes don't implicitly add a terminating null byte, and
 195 .BR fseek (3)
 196 .B SEEK_END
 197 is relative to the end of the buffer (i.e., the value specified by the
 198 .I size
 199 argument), rather than the current string length.
 200 .PP
 201 An API bug afflicted the implementation of binary mode:
 202 to specify binary mode, the \(aqb\(aq must be the
 203 .I second
 204 character in
 205 .IR mode .
 206 Thus, for example, "wb+" has the desired effect, but "w+b" does not.
 207 This is inconsistent with the treatment of
 208 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=12836
 209 .IR mode
 210 by
 211 .BR fopen (3).
 212 .PP
 213 Binary mode was removed in glibc 2.22; a \(aqb\(aq specified in
 214 .I mode
 215 has no effect.
 216 .SH BUGS
 217 In versions of glibc before 2.22, if
 218 .I size
 219 is specified as zero,
 220 .BR fmemopen ()
 221 fails with the error
 222 .BR EINVAL .
 223 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=11216
 224 It would be more consistent if this case successfully created
 225 a stream that then returned end-of-file on the first attempt at reading;
 226 since version 2.22, the glibc implementation provides that behavior.
 227 .PP
 228 In versions of glibc before 2.22,
 229 specifying append mode ("a" or "a+") for
 230 .BR fmemopen ()
 231 sets the initial buffer position to the first null byte, but
 232 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=13152
 233 (if the current position is reset to a location other than
 234 the end of the stream)
 235 does not force subsequent writes to append at the end of the stream.
 236 This bug is fixed in glibc 2.22.
 237 .PP
 238 In versions of glibc before 2.22, if the
 239 .I mode
 240 argument to
 241 .BR fmemopen ()
 242 specifies append ("a" or "a+"), and the
 243 .I size
 244 argument does not cover a null byte in
 245 .IR buf ,
 246 then, according to POSIX.1-2008,
 247 the initial buffer position should be set to
 248 the next byte after the end of the buffer.
 249 However, in this case the glibc
 250 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=13151
 251 .BR fmemopen ()
 252 sets the buffer position to \-1.
 253 This bug is fixed in glibc 2.22.
 254 .PP
 255 In versions of glibc before 2.22,
 256 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=14292
 257 when a call to
 258 .BR fseek (3)
 259 with a
 260 .I whence
 261 value of
 262 .B SEEK_END
 263 was performed on a stream created by
 264 .BR fmemopen (),
 265 the
 266 .I offset
 267 was
 268 .IR subtracted
 269 from the end-of-stream position, instead of being added.
 270 This bug is fixed in glibc 2.22.
 271 .PP
 272 The glibc 2.9 addition of "binary" mode for
 273 .BR fmemopen ()
 274 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
 275 silently changed the ABI: previously,
 276 .BR fmemopen ()
 277 ignored \(aqb\(aq in
 278 .IR mode .
 279 .SH EXAMPLES
 280 The program below uses
 281 .BR fmemopen ()
 282 to open an input buffer, and
 283 .BR open_memstream (3)
 284 to open a dynamically sized output buffer.
 285 The program scans its input string (taken from the program's
 286 first command-line argument) reading integers,
 287 and writes the squares of these integers to the output buffer.
 288 An example of the output produced by this program is the following:
 289 .PP
 290 .in +4n
 291 .EX
 292 .RB "$" " ./a.out \(aq1 23 43\(aq"
 293 size=11; ptr=1 529 1849
 294 .EE
 295 .in
 296 .SS Program source
 297 \&
 298 .EX
 299 #define _GNU_SOURCE
 300 #include <string.h>
 301 #include <stdio.h>
 302 #include <stdlib.h>
 303
 304 #define handle_error(msg) \e
 305     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 306
 307 int
 308 main(int argc, char *argv[])
 309 {
 310     FILE *out, *in;
 311     int v, s;
 312     size_t size;
 313     char *ptr;
 314
 315     if (argc != 2) {
 316         fprintf(stderr, "Usage: %s \(aq<num>...\(aq\en", argv[0]);
 317         exit(EXIT_FAILURE);
 318     }
 319
 320     in = fmemopen(argv[1], strlen(argv[1]), "r");
 321     if (in == NULL)
 322         handle_error("fmemopen");
 323
 324     out = open_memstream(&ptr, &size);
 325     if (out == NULL)
 326         handle_error("open_memstream");
 327
 328     for (;;) {
 329         s = fscanf(in, "%d", &v);
 330         if (s <= 0)
 331             break;
 332
 333         s = fprintf(out, "%d ", v * v);
 334         if (s == \-1)
 335             handle_error("fprintf");
 336     }
 337
 338     fclose(in);
 339     fclose(out);
 340
 341     printf("size=%zu; ptr=%s\en", size, ptr);
 342
 343     free(ptr);
 344     exit(EXIT_SUCCESS);
 345 }
 346 .EE
 347 .SH SEE ALSO
 348 .BR fopen (3),
 349 .BR fopencookie (3),
 350 .BR open_memstream (3)