original/man3/fmemopen.3

   1 .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
   2 .\" and Copyright 2005, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" Distributed under the GPL.
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
   9 .\"
  10 .TH FMEMOPEN 3 2015-01-22 "GNU" "Linux Programmer's Manual"
  11 .SH NAME
  12 fmemopen, open_memstream, open_wmemstream \-  open memory as stream
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <stdio.h>
  16
  17 .BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"
  18
  19 .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
  20
  21 .B #include <wchar.h>
  22
  23 .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
  24 .fi
  25 .sp
  26 .in -4n
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .in
  30 .sp
  31 .BR fmemopen (),
  32 .BR open_memstream (),
  33 .BR open_wmemstream ():
  34 .PD 0
  35 .ad l
  36 .RS 4
  37 .TP 4
  38 Since glibc 2.10:
  39 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  40 .TP
  41 Before glibc 2.10:
  42 _GNU_SOURCE
  43 .RE
  44 .ad
  45 .PD
  46 .SH DESCRIPTION
  47 The
  48 .BR fmemopen ()
  49 function opens a stream that permits the access specified by
  50 .IR mode .
  51 The stream allows I/O to be performed on the string or memory buffer
  52 pointed to by
  53 .IR buf .
  54 This buffer must be at least
  55 .I size
  56 bytes long.
  57 .PP
  58 The argument
  59 .I mode
  60 is the same as for
  61 .BR fopen (3).
  62 If
  63 .I mode
  64 specifies an append mode, then the initial file position is set to
  65 the location of the first null byte (\(aq\\0\(aq) in the buffer;
  66 otherwise the initial file position is set to the start of the buffer.
  67 Since glibc 2.9,
  68 the letter \(aqb\(aq may be specified as the second character in
  69 .IR mode .
  70 This provides "binary" mode:
  71 writes don't implicitly add a terminating null byte, and
  72 .BR fseek (3)
  73 .B SEEK_END
  74 is relative to the end of the buffer (i.e., the value specified by the
  75 .I size
  76 argument), rather than the current string length.
  77 .PP
  78 When a stream that has been opened for writing is flushed
  79 .RB ( fflush (3))
  80 or closed
  81 .RB ( fclose (3)),
  82 a null byte is written at the end of the buffer if there is space.
  83 The caller should ensure that an extra byte is available in the
  84 buffer
  85 (and that
  86 .I size
  87 counts that byte)
  88 to allow for this.
  89
  90 Attempts to write more than
  91 .I size
  92 bytes to the buffer result in an error.
  93 (By default, such errors will be visible only when the
  94 .I stdio
  95 buffer is flushed.
  96 Disabling buffering with the following call
  97 may be useful to detect errors at the time of an output operation:
  98
  99     setbuf(stdream, NULL);
 100
 101 Alternatively, the caller can explicitly set
 102 .I buf
 103 as the stdio stream buffer, at the same time informing stdio
 104 of the buffer's size, using:
 105
 106     setbuffer(stream, buf, size);
 107
 108 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
 109 .\" and
 110 .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
 111 .PP
 112 In a stream opened for reading,
 113 null bytes (\(aq\\0\(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 file pointer advances
 117 .I size
 118 bytes past the start of the buffer.
 119 .PP
 120 If
 121 .I buf
 122 is specified as NULL, then
 123 .BR fmemopen ()
 124 dynamically allocates a buffer
 125 .I size
 126 bytes long.
 127 This is useful for an application that wants to write data to
 128 a temporary buffer and then read it back again.
 129 The buffer is automatically freed when the stream is closed.
 130 Note that the caller has no way to obtain a pointer to the
 131 temporary buffer allocated by this call (but see
 132 .BR open_memstream ()
 133 below).
 134
 135 The
 136 .BR open_memstream ()
 137 function opens a stream for writing to a buffer.
 138 The buffer
 139 is dynamically allocated (as with
 140 .BR malloc (3)),
 141 and automatically grows as required.
 142 After closing the stream, the caller should
 143 .BR free (3)
 144 this buffer.
 145
 146 When the stream is closed
 147 .RB ( fclose (3))
 148 or flushed
 149 .RB ( fflush (3)),
 150 the locations pointed to by
 151 .I ptr
 152 and
 153 .I sizeloc
 154 are updated to contain, respectively, a pointer to the buffer and the
 155 current size of the buffer.
 156 These values remain valid only as long as the caller
 157 performs no further output on the stream.
 158 If further output is performed, then the stream
 159 must again be flushed before trying to access these variables.
 160
 161 A null byte is maintained at the end of the buffer.
 162 This byte is
 163 .I not
 164 included in the size value stored at
 165 .IR sizeloc .
 166
 167 The stream's file position can be changed with
 168 .BR fseek (3)
 169 or
 170 .BR fseeko (3).
 171 Moving the file position past the end
 172 of the data already written fills the intervening space with
 173 zeros.
 174
 175 The
 176 .BR open_wmemstream ()
 177 is similar to
 178 .BR open_memstream (),
 179 but operates on wide characters instead of bytes.
 180 .SH RETURN VALUE
 181 Upon successful completion
 182 .BR fmemopen (),
 183 .BR open_memstream ()
 184 and
 185 .BR open_wmemstream ()
 186 return a
 187 .I FILE
 188 pointer.
 189 Otherwise, NULL is returned and
 190 .I errno
 191 is set to indicate the error.
 192 .SH VERSIONS
 193 .BR fmemopen ()
 194 and
 195 .BR open_memstream ()
 196 were already available in glibc 1.0.x.
 197 .BR open_wmemstream ()
 198 is available since glibc 2.4.
 199 .SH CONFORMING TO
 200 POSIX.1-2008.
 201 These functions are not specified in POSIX.1-2001,
 202 and are not widely available on other systems.
 203
 204 POSIX.1-2008 specifies that \(aqb\(aq in
 205 .IR mode
 206 shall be ignored.
 207 However, Technical Corrigendum 1
 208 .\" http://austingroupbugs.net/view.php?id=396
 209 adjusts the standard to allow implementation-specific treatment for this case,
 210 thus permitting the glibc treatment of \(aqb\(aq.
 211 .SH NOTES
 212 There is no file descriptor associated with the file stream
 213 returned by these functions
 214 (i.e.,
 215 .BR fileno (3)
 216 will return an error if called on the returned stream).
 217 .SH BUGS
 218 In glibc before version 2.7, seeking past the end of a stream created by
 219 .BR open_memstream ()
 220 does not enlarge the buffer; instead the
 221 .BR fseek (3)
 222 call fails, returning \-1.
 223 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
 224
 225 If
 226 .I size
 227 is specified as zero,
 228 .BR fmemopen ()
 229 fails with the error
 230 .BR EINVAL .
 231 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=11216
 232 It would be more consistent if this case successfully created
 233 a stream that then returned end of file on the first attempt at reading.
 234 Furthermore, POSIX.1-2008 does not specify a failure for this case.
 235
 236 Specifying append mode ("a" or "a+") for
 237 .BR fmemopen ()
 238 sets the initial file position to the first null byte, but
 239 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13152
 240 (if the file offset is reset to a location other than
 241 the end of the stream)
 242 does not force subsequent writes to append at the end of the stream.
 243
 244 If the
 245 .I mode
 246 argument to
 247 .BR fmemopen ()
 248 specifies append ("a" or "a+"), and the
 249 .I size
 250 argument does not cover a null byte in
 251 .IR buf ,
 252 then, according to POSIX.1-2008,
 253 the initial file position should be set to
 254 the next byte after the end of the buffer.
 255 However, in this case the glibc
 256 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=13151
 257 .BR fmemopen ()
 258 sets the file position to \-1.
 259
 260 To specify binary mode for
 261 .BR fmemopen ()
 262 the \(aqb\(aq must be the
 263 .I second
 264 character in
 265 .IR mode .
 266 Thus, for example, "wb+" has the desired effect, but "w+b" does not.
 267 This is inconsistent with the treatment of
 268 .\" FIXME . http://sourceware.org/bugzilla/show_bug.cgi?id=12836
 269 .IR mode
 270 by
 271 .BR fopen (3).
 272
 273 The glibc 2.9 addition of "binary" mode for
 274 .BR fmemopen ()
 275 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
 276 silently changed the ABI: previously,
 277 .BR fmemopen ()
 278 ignored \(aqb\(aq in
 279 .IR mode .
 280 .SH EXAMPLE
 281 The program below uses
 282 .BR fmemopen ()
 283 to open an input buffer, and
 284 .BR open_memstream ()
 285 to open a dynamically sized output buffer.
 286 The program scans its input string (taken from the program's
 287 first command-line argument) reading integers,
 288 and writes the squares of these integers to the output buffer.
 289 An example of the output produced by this program is the following:
 290 .in +4n
 291 .nf
 292
 293 .RB "$" " ./a.out \(aq1 23 43\(aq"
 294 size=11; ptr=1 529 1849
 295 .fi
 296 .in
 297 .SS Program source
 298 \&
 299 .nf
 300 #define _GNU_SOURCE
 301 #include <string.h>
 302 #include <stdio.h>
 303 #include <stdlib.h>
 304
 305 #define handle_error(msg) \\
 306     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 307
 308 int
 309 main(int argc, char *argv[])
 310 {
 311     FILE *out, *in;
 312     int v, s;
 313     size_t size;
 314     char *ptr;
 315
 316     if (argc != 2) {
 317         fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
 318         exit(EXIT_FAILURE);
 319     }
 320
 321     in = fmemopen(argv[1], strlen(argv[1]), "r");
 322     if (in == NULL)
 323         handle_error("fmemopen");
 324
 325     out = open_memstream(&ptr, &size);
 326     if (out == NULL)
 327         handle_error("open_memstream");
 328
 329     for (;;) {
 330         s = fscanf(in, "%d", &v);
 331         if (s <= 0)
 332             break;
 333
 334         s = fprintf(out, "%d ", v * v);
 335         if (s == \-1)
 336             handle_error("fprintf");
 337     }
 338     fclose(in);
 339     fclose(out);
 340     printf("size=%zu; ptr=%s\\n", size, ptr);
 341     free(ptr);
 342     exit(EXIT_SUCCESS);
 343 }
 344 .fi
 345 .SH SEE ALSO
 346 .BR fopen (3),
 347 .BR fopencookie (3)
 348 .SH COLOPHON
 349 This page is part of release 3.79 of the Linux
 350 .I man-pages
 351 project.
 352 A description of the project,
 353 information about reporting bugs,
 354 and the latest version of this page,
 355 can be found at
 356 \%http://www.kernel.org/doc/man\-pages/.