original/man3/fmemopen.3

   1 .\" Copyright 2005 walter harms (walter.harms@informatik.uni-oldenburg.de),
   2 .\" and Copyright 2005 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\" Distributed under the GPL.
   4 .\" 2008-12-04, Petr Baudis <pasky@suse.cz>: Document open_wmemstream()
   5 .\"
   6 .TH FMEMOPEN 3 2010-09-15 "GNU" "Linux Programmer's Manual"
   7 .SH NAME
   8 fmemopen, open_memstream, open_wmemstream \-  open memory as stream
   9 .SH SYNOPSIS
  10 .nf
  11 .B #include <stdio.h>
  12
  13 .BI "FILE *fmemopen(void *"buf ", size_t "size ", const char *" mode ");"
  14
  15 .BI "FILE *open_memstream(char **" ptr ", size_t *" sizeloc );
  16
  17 .B #include <wchar.h>
  18
  19 .BI "FILE *open_wmemstream(wchar_t **" ptr ", size_t *" sizeloc );
  20 .fi
  21 .sp
  22 .in -4n
  23 Feature Test Macro Requirements for glibc (see
  24 .BR feature_test_macros (7)):
  25 .in
  26 .sp
  27 .BR fmemopen (),
  28 .BR open_memstream (),
  29 .BR open_wmemstream ():
  30 .PD 0
  31 .ad l
  32 .RS 4
  33 .TP 4
  34 Since glibc 2.10:
  35 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
  36 .TP
  37 Before glibc 2.10:
  38 _GNU_SOURCE
  39 .RE
  40 .ad
  41 .PD
  42 .SH DESCRIPTION
  43 The
  44 .BR fmemopen ()
  45 function opens a stream that permits the access specified by
  46 .IR mode .
  47 The stream allows I/O to be performed on the string or memory buffer
  48 pointed to by
  49 .IR buf .
  50 This buffer must be at least
  51 .I size
  52 bytes long.
  53 .PP
  54 The argument
  55 .I mode
  56 is the same as for
  57 .BR fopen (3).
  58 If
  59 .I mode
  60 specifies an append mode, then the initial file position is set to
  61 the location of the first null byte (\(aq\\0\(aq) in the buffer;
  62 otherwise the initial file position is set to the start of the buffer.
  63 Since glibc 2.9,
  64 the letter 'b' may be specified as the second character in
  65 .IR mode .
  66 This provides "binary" mode:
  67 writes don't implicitly add a terminating null byte, and
  68 .BR fseek (3)
  69 .B SEEK_END
  70 is relative to the end of the buffer (i.e., the value specified by the
  71 .I size
  72 argument), rather than the current string length.
  73 .PP
  74 When a stream that has been opened for writing is flushed
  75 .RB ( fflush (3))
  76 or closed
  77 .RB ( fclose (3)),
  78 a null byte is written at the end of the buffer if there is space.
  79 The caller should ensure that an extra byte is available in the
  80 buffer
  81 (and that
  82 .I size
  83 counts that byte)
  84 to allow for this.
  85
  86 Attempts to write more than
  87 .I size
  88 bytes to the buffer result in an error.
  89 (By default, such errors will only be visible when the
  90 .I stdio
  91 buffer is flushed.
  92 Disabling buffering with
  93 .I setbuf(fp,\ NULL)
  94 may be useful to detect errors at the time of an output operation.
  95 Alternatively, the caller can explicitly set
  96 .I buf
  97 as the stdio stream buffer, at the same time informing stdio
  98 of the buffer's size, using
  99 .IR "setbuffer(fp, buf, size)" .)
 100 .\" See http://sourceware.org/bugzilla/show_bug.cgi?id=1995
 101 .\" and
 102 .\" http://sources.redhat.com/ml/libc-alpha/2006-04/msg00064.html
 103 .PP
 104 In a stream opened for reading,
 105 null bytes (\(aq\\0\(aq) in the buffer do not cause read
 106 operations to return an end-of-file indication.
 107 A read from the buffer will only indicate end-of-file
 108 when the file pointer advances
 109 .I size
 110 bytes past the start of the buffer.
 111 .PP
 112 If
 113 .I buf
 114 is specified as NULL, then
 115 .BR fmemopen ()
 116 dynamically allocates a buffer
 117 .I size
 118 bytes long.
 119 This is useful for an application that wants to write data to
 120 a temporary buffer and then read it back again.
 121 The buffer is automatically freed when the stream is closed.
 122 Note that the caller has no way to obtain a pointer to the
 123 temporary buffer allocated by this call (but see
 124 .BR open_memstream ()
 125 below).
 126
 127 The
 128 .BR open_memstream ()
 129 function opens a stream for writing to a buffer.
 130 The buffer
 131 is dynamically allocated (as with
 132 .BR malloc (3)),
 133 and automatically grows as required.
 134 After closing the stream, the caller should
 135 .BR free (3)
 136 this buffer.
 137
 138 When the stream is closed
 139 .RB ( fclose (3))
 140 or flushed
 141 .RB ( fflush (3)),
 142 the locations pointed to by
 143 .I ptr
 144 and
 145 .I sizeloc
 146 are updated to contain, respectively, a pointer to the buffer and the
 147 current size of the buffer.
 148 These values remain valid only as long as the caller
 149 performs no further output on the stream.
 150 If further output is performed, then the stream
 151 must again be flushed before trying to access these variables.
 152
 153 A null byte is maintained at the end of the buffer.
 154 This byte is
 155 .I not
 156 included in the size value stored at
 157 .IR sizeloc .
 158
 159 The stream's file position can be changed with
 160 .BR fseek (3)
 161 or
 162 .BR fseeko (3).
 163 Moving the file position past the end
 164 of the data already written fills the intervening space with
 165 zeros.
 166
 167 The
 168 .BR open_wmemstream ()
 169 is similar to
 170 .BR open_memstream (),
 171 but operates on wide characters instead of bytes.
 172 .SH "RETURN VALUE"
 173 Upon successful completion
 174 .BR fmemopen (),
 175 .BR open_memstream ()
 176 and
 177 .BR open_wmemstream ()
 178 return a
 179 .I FILE
 180 pointer.
 181 Otherwise, NULL is returned and
 182 .I errno
 183 is set to indicate the error.
 184 .SH VERSIONS
 185 .BR fmemopen ()
 186 and
 187 .BR open_memstream ()
 188 were already available in glibc 1.0.x.
 189 .BR open_wmemstream ()
 190 is available since glibc 2.4.
 191 .SH "CONFORMING TO"
 192 POSIX.1-2008.
 193 These functions are not specified in POSIX.1-2001,
 194 and are not widely available on other systems.
 195 .SH NOTES
 196 There is no file descriptor associated with the file stream
 197 returned by these functions
 198 (i.e.,
 199 .BR fileno (3)
 200 will return an error if called on the returned stream).
 201 .SH BUGS
 202 In glibc before version 2.7, seeking past the end of a stream created by
 203 .BR open_memstream ()
 204 does not enlarge the buffer; instead the
 205 .BR fseek ()
 206 call fails, returning \-1.
 207 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=1996
 208 .SH "EXAMPLE"
 209 The program below uses
 210 .BR fmemopen ()
 211 to open an input buffer, and
 212 .BR open_memstream ()
 213 to open a dynamically sized output buffer.
 214 The program scans its input string (taken from the program's
 215 first command-line argument) reading integers,
 216 and writes the squares of these integers to the output buffer.
 217 An example of the output produced by this program is the following:
 218 .in +4n
 219 .nf
 220
 221 .RB "$" " ./a.out \(aq1 23 43\(aq"
 222 size=11; ptr=1 529 1849
 223 .fi
 224 .in
 225 .SS Program source
 226 \&
 227 .nf
 228 #define _GNU_SOURCE
 229 #include <string.h>
 230 #include <stdio.h>
 231 #include <stdlib.h>
 232
 233 #define handle_error(msg) \\
 234     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 235
 236 int
 237 main(int argc, char *argv[])
 238 {
 239     FILE *out, *in;
 240     int v, s;
 241     size_t size;
 242     char *ptr;
 243
 244     if (argc != 2) {
 245         fprintf(stderr, "Usage: %s <file>\\n", argv[0]);
 246         exit(EXIT_FAILURE);
 247     }
 248
 249     in = fmemopen(argv[1], strlen(argv[1]), "r");
 250     if (in == NULL)
 251         handle_error("fmemopen");
 252
 253     out = open_memstream(&ptr, &size);
 254     if (out == NULL)
 255         handle_error("open_memstream");
 256
 257     for (;;) {
 258         s = fscanf(in, "%d", &v);
 259         if (s <= 0)
 260             break;
 261
 262         s = fprintf(out, "%d ", v * v);
 263         if (s == \-1)
 264             handle_error("fprintf");
 265     }
 266     fclose(in);
 267     fclose(out);
 268     printf("size=%ld; ptr=%s\\n", (long) size, ptr);
 269     free(ptr);
 270     exit(EXIT_SUCCESS);
 271 }
 272 .fi
 273 .SH "SEE ALSO"
 274 .BR fopen (3),
 275 .BR fopencookie (3),
 276 .BR feature_test_macros (7)