open_memstream(3)

1open_memstream(3)          Library Functions Manual          open_memstream(3)
2
3
4

NAME

6       open_memstream, open_wmemstream -  open a dynamic memory buffer stream
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <stdio.h>
13
14       FILE *open_memstream(char **ptr, size_t *sizeloc);
15
16       #include <wchar.h>
17
18       FILE *open_wmemstream(wchar_t **ptr, size_t *sizeloc);
19
20   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
21
22       open_memstream(), open_wmemstream():
23           Since glibc 2.10:
24               _POSIX_C_SOURCE >= 200809L
25           Before glibc 2.10:
26               _GNU_SOURCE
27

DESCRIPTION

29       The  open_memstream()  function  opens a stream for writing to a memory
30       buffer.  The function dynamically allocates the buffer, and the  buffer
31       automatically  grows  as  needed.   Initially, the buffer has a size of
32       zero.  After closing the stream, the caller should free(3) this buffer.
33
34       The locations pointed to by ptr and sizeloc are used to report, respec‐
35       tively, the current location and the size of the buffer.  The locations
36       referred to by these pointers are  updated  each  time  the  stream  is
37       flushed  (fflush(3))  and when the stream is closed (fclose(3)).  These
38       values remain valid only as long as the caller performs no further out‐
39       put  on  the  stream.   If further output is performed, then the stream
40       must again be flushed before trying to access these values.
41
42       A null byte is maintained at the end of the buffer.  This byte  is  not
43       included in the size value stored at sizeloc.
44
45       The  stream  maintains  the notion of a current position, which is ini‐
46       tially zero (the start of the buffer).  Each write operation implicitly
47       adjusts  the  buffer position.  The stream's buffer position can be ex‐
48       plicitly changed with fseek(3) or fseeko(3).  Moving the  buffer  posi‐
49       tion  past  the  end  of the data already written fills the intervening
50       space with null characters.
51
52       The open_wmemstream() is similar to open_memstream(), but  operates  on
53       wide characters instead of bytes.
54

RETURN VALUE

56       Upon  successful completion, open_memstream() and open_wmemstream() re‐
57       turn a FILE pointer.  Otherwise, NULL is returned and errno is  set  to
58       indicate the error.
59

ATTRIBUTES

61       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
62       tributes(7).
63
64       ┌────────────────────────────────────────────┬───────────────┬─────────┐
65       │Interface                                   │ Attribute     │ Value   │
66       ├────────────────────────────────────────────┼───────────────┼─────────┤
67       │open_memstream(), open_wmemstream()         │ Thread safety │ MT-Safe │
68       └────────────────────────────────────────────┴───────────────┴─────────┘
69

STANDARDS

71       POSIX.1-2008.
72

HISTORY

74       open_memstream()
75              glibc 1.0.x.
76
77       open_wmemstream()
78              glibc 2.4.
79

NOTES

81       There is no file descriptor associated with the file stream returned by
82       these  functions (i.e., fileno(3) will return an error if called on the
83       returned stream).
84

BUGS

86       Before glibc  2.7,  seeking  past  the  end  of  a  stream  created  by
87       open_memstream() does not enlarge the buffer; instead the fseek(3) call
88       fails, returning -1.
89

EXAMPLES

91       See fmemopen(3).
92