man3/fmemopen.3

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