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