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 2014-04-06 "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
  97 .I setbuf(fp,\ NULL)
  98 may be useful to detect errors at the time of an output operation.
  99 Alternatively, the caller can explicitly set
 100 .I buf
 101 as the stdio stream buffer, at the same time informing stdio
 102 of the buffer's size, using
 103 .IR "setbuffer(fp, buf, size)" .)
 104 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
 105 .\" and
 106 .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
 107 .PP
 108 In a stream opened for reading,
 109 null bytes (\(aq\\0\(aq) in the buffer do not cause read
 110 operations to return an end-of-file indication.
 111 A read from the buffer will only indicate end-of-file
 112 when the file pointer advances
 113 .I size
 114 bytes past the start of the buffer.
 115 .PP
 116 If
 117 .I buf
 118 is specified as NULL, then
 119 .BR fmemopen ()
 120 dynamically allocates a buffer
 121 .I size
 122 bytes long.
 123 This is useful for an application that wants to write data to
 124 a temporary buffer and then read it back again.
 125 The buffer is automatically freed when the stream is closed.
 126 Note that the caller has no way to obtain a pointer to the
 127 temporary buffer allocated by this call (but see
 128 .BR open_memstream ()
 129 below).
 130
 131 The
 132 .BR open_memstream ()
 133 function opens a stream for writing to a buffer.
 134 The buffer
 135 is dynamically allocated (as with
 136 .BR malloc (3)),
 137 and automatically grows as required.
 138 After closing the stream, the caller should
 139 .BR free (3)
 140 this buffer.
 141
 142 When the stream is closed
 143 .RB ( fclose (3))
 144 or flushed
 145 .RB ( fflush (3)),
 146 the locations pointed to by
 147 .I ptr
 148 and
 149 .I sizeloc
 150 are updated to contain, respectively, a pointer to the buffer and the
 151 current size of the buffer.
 152 These values remain valid only as long as the caller
 153 performs no further output on the stream.
 154 If further output is performed, then the stream
 155 must again be flushed before trying to access these variables.
 156
 157 A null byte is maintained at the end of the buffer.
 158 This byte is
 159 .I not
 160 included in the size value stored at
 161 .IR sizeloc .
 162
 163 The stream's file position can be changed with
 164 .BR fseek (3)
 165 or
 166 .BR fseeko (3).
 167 Moving the file position past the end
 168 of the data already written fills the intervening space with
 169 zeros.
 170
 171 The
 172 .BR open_wmemstream ()
 173 is similar to
 174 .BR open_memstream (),
 175 but operates on wide characters instead of bytes.
 176 .SH RETURN VALUE
 177 Upon successful completion
 178 .BR fmemopen (),
 179 .BR open_memstream ()
 180 and
 181 .BR open_wmemstream ()
 182 return a
 183 .I FILE
 184 pointer.
 185 Otherwise, NULL is returned and
 186 .I errno
 187 is set to indicate the error.
 188 .SH VERSIONS
 189 .BR fmemopen ()
 190 and
 191 .BR open_memstream ()
 192 were already available in glibc 1.0.x.
 193 .BR open_wmemstream ()
 194 is available since glibc 2.4.
 195 .SH CONFORMING TO
 196 POSIX.1-2008.
 197 These functions are not specified in POSIX.1-2001,
 198 and are not widely available on other systems.
 199
 200 POSIX.1-2008 specifies that \(aqb\(aq in
 201 .IR mode
 202 shall be ignored.
 203 However, Technical Corrigendum 1
 204 .\" http://austingroupbugs.net/view.php?id=396
 205 adjusts the standard to allow implementation-specific treatment for this case,
 206 thus permitting the glibc treatment of \(aqb\(aq.
 207 .SH NOTES
 208 There is no file descriptor associated with the file stream
 209 returned by these functions
 210 (i.e.,
 211 .BR fileno (3)
 212 will return an error if called on the returned stream).
 213 .SH BUGS
 214 In glibc before version 2.7, seeking past the end of a stream created by
 215 .BR open_memstream ()
 216 does not enlarge the buffer; instead the
 217 .BR fseek (3)
 218 call fails, returning \-1.
 219 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
 220
 221 If
 222 .I size
 223 is specified as zero,
 224 .BR fmemopen ()
 225 fails with the error
 226 .BR EINVAL .
 227 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=11216
 228 It would be more consistent if this case successfully created
 229 a stream that then returned end of file on the first attempt at reading.
 230 Furthermore, POSIX.1-2008 does not specify a failure for this case.
 231
 232 Specifying append mode ("a" or "a+") for
 233 .BR fmemopen ()
 234 sets the initial file position to the first null byte, but
 235 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=13152
 236 (if the file offset is reset to a location other than
 237 the end of the stream)
 238 does not force subsequent writes to append at the end of the stream.
 239
 240 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 file position should be set to
 250 the next byte after the end of the buffer.
 251 However, in this case the glibc
 252 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=13151
 253 .BR fmemopen ()
 254 sets the file position to \-1.
 255
 256 To specify binary mode for
 257 .BR fmemopen ()
 258 the \(aqb\(aq must be the
 259 .I second
 260 character in
 261 .IR mode .
 262 Thus, for example, "wb+" has the desired effect, but "w+b" does not.
 263 This is inconsistent with the treatment of
 264 .\" FIXME http://sourceware.org/bugzilla/show_bug.cgi?id=12836
 265 .IR mode
 266 by
 267 .BR fopen (3).
 268
 269 The glibc 2.9 addition of "binary" mode for
 270 .BR fmemopen ()
 271 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=6544
 272 silently changed the ABI: previously,
 273 .BR fmemopen ()
 274 ignored \(aqb\(aq in
 275 .IR mode .
 276 .SH EXAMPLE
 277 The program below uses
 278 .BR fmemopen ()
 279 to open an input buffer, and
 280 .BR open_memstream ()
 281 to open a dynamically sized output buffer.
 282 The program scans its input string (taken from the program's
 283 first command-line argument) reading integers,
 284 and writes the squares of these integers to the output buffer.
 285 An example of the output produced by this program is the following:
 286 .in +4n
 287 .nf
 288
 289 .RB "$" " ./a.out \(aq1 23 43\(aq"
 290 size=11; ptr=1 529 1849
 291 .fi
 292 .in
 293 .SS Program source
 294 \&
 295 .nf
 296 #define _GNU_SOURCE
 297 #include <string.h>
 298 #include <stdio.h>
 299 #include <stdlib.h>
 300
 301 #define handle_error(msg) \\
 302     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 303
 304 int
 305 main(int argc, char *argv[])
 306 {
 307     FILE *out, *in;
 308     int v, s;
 309     size_t size;
 310     char *ptr;
 311
 312     if (argc != 2) {
 313         fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
 314         exit(EXIT_FAILURE);
 315     }
 316
 317     in = fmemopen(argv[1], strlen(argv[1]), "r");
 318     if (in == NULL)
 319         handle_error("fmemopen");
 320
 321     out = open_memstream(&ptr, &size);
 322     if (out == NULL)
 323         handle_error("open_memstream");
 324
 325     for (;;) {
 326         s = fscanf(in, "%d", &v);
 327         if (s <= 0)
 328             break;
 329
 330         s = fprintf(out, "%d ", v * v);
 331         if (s == \-1)
 332             handle_error("fprintf");
 333     }
 334     fclose(in);
 335     fclose(out);
 336     printf("size=%zu; ptr=%s\\n", size, ptr);
 337     free(ptr);
 338     exit(EXIT_SUCCESS);
 339 }
 340 .fi
 341 .SH SEE ALSO
 342 .BR fopen (3),
 343 .BR fopencookie (3)
 344 .SH COLOPHON
 345 This page is part of release 3.67 of the Linux
 346 .I man-pages
 347 project.
 348 A description of the project,
 349 information about reporting bugs,
 350 and the latest version of this page,
 351 can be found at
 352 \%http://www.kernel.org/doc/man\-pages/.