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