logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

open_memstream.3p (5461B)


  1. '\" et
  2. .TH OPEN_MEMSTREAM "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. open_memstream, open_wmemstream
  12. \(em open a dynamic memory buffer stream
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. FILE *open_memstream(char **\fIbufp\fP, size_t *\fIsizep\fP);
  19. .P
  20. #include <wchar.h>
  21. .P
  22. FILE *open_wmemstream(wchar_t **\fIbufp\fP, size_t *\fIsizep\fP);
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. \fIopen_memstream\fR()
  27. and
  28. \fIopen_wmemstream\fR()
  29. functions shall create an I/O stream associated with a dynamically
  30. allocated memory buffer. The stream shall be opened for writing and
  31. shall be seekable.
  32. .P
  33. The stream associated with a call to
  34. \fIopen_memstream\fR()
  35. shall be byte-oriented.
  36. .P
  37. The stream associated with a call to
  38. \fIopen_wmemstream\fR()
  39. shall be wide-oriented.
  40. .P
  41. The stream shall maintain a current position in the allocated buffer
  42. and a current buffer length. The position shall be initially set to
  43. zero (the start of the buffer). Each write to the stream shall start at
  44. the current position and move this position by the number of
  45. successfully written bytes for
  46. \fIopen_memstream\fR()
  47. or the number of successfully written wide characters for
  48. \fIopen_wmemstream\fR().
  49. The length shall be initially set to zero. If a write moves the
  50. position to a value larger than the current length, the current length
  51. shall be set to this position. In this case a null character for
  52. \fIopen_memstream\fR()
  53. or a null wide character for
  54. \fIopen_wmemstream\fR()
  55. shall be appended to the current buffer. For both functions the
  56. terminating null is not included in the calculation of the buffer
  57. length.
  58. .P
  59. After a successful
  60. \fIfflush\fR()
  61. or
  62. \fIfclose\fR(),
  63. the pointer referenced by
  64. .IR bufp
  65. shall contain the address of the buffer, and the variable pointed to by
  66. .IR sizep
  67. shall contain the smaller of the current buffer length and the
  68. number of bytes for
  69. \fIopen_memstream\fR(),
  70. or the number of wide characters for
  71. \fIopen_wmemstream\fR(),
  72. between the beginning of the buffer and the current file position indicator.
  73. .P
  74. After a successful
  75. \fIfflush\fR()
  76. the pointer referenced by
  77. .IR bufp
  78. and the variable referenced by
  79. .IR sizep
  80. remain valid only until the next write operation on the stream or a
  81. call to
  82. \fIfclose\fR().
  83. .P
  84. After a successful
  85. \fIfclose\fR(),
  86. the pointer referenced by
  87. .IR bufp
  88. can be passed to
  89. \fIfree\fR().
  90. .SH "RETURN VALUE"
  91. Upon successful completion, these functions shall return a pointer to
  92. the object controlling the stream. Otherwise, a null pointer shall be
  93. returned, and
  94. .IR errno
  95. shall be set to indicate the error.
  96. .SH ERRORS
  97. These functions shall fail if:
  98. .TP
  99. .BR EMFILE
  100. {STREAM_MAX}
  101. streams are currently open in the calling process.
  102. .P
  103. These functions may fail if:
  104. .TP
  105. .BR EINVAL
  106. .IR bufp
  107. or
  108. .IR sizep
  109. are NULL.
  110. .TP
  111. .BR EMFILE
  112. {FOPEN_MAX}
  113. streams are currently open in the calling process.
  114. .TP
  115. .BR ENOMEM
  116. Memory for the stream or the buffer could not be allocated.
  117. .LP
  118. .IR "The following sections are informative."
  119. .SH EXAMPLES
  120. .sp
  121. .RS 4
  122. .nf
  123. #include <stdio.h>
  124. #include <stdlib.h>
  125. .P
  126. int
  127. main (void)
  128. {
  129. FILE *stream;
  130. char *buf;
  131. size_t len;
  132. off_t eob;
  133. .P
  134. stream = open_memstream (&buf, &len);
  135. if (stream == NULL)
  136. /* handle error */ ;
  137. fprintf (stream, "hello my world");
  138. fflush (stream);
  139. printf ("buf=%s, len=%zu\en", buf, len);
  140. eob = ftello(stream);
  141. fseeko (stream, 0, SEEK_SET);
  142. fprintf (stream, "good-bye");
  143. fseeko (stream, eob, SEEK_SET);
  144. fclose (stream);
  145. printf ("buf=%s, len=%zu\en", buf, len);
  146. free (buf);
  147. return 0;
  148. }
  149. .fi
  150. .P
  151. .RE
  152. .P
  153. This program produces the following output:
  154. .sp
  155. .RS 4
  156. .nf
  157. buf=hello my world, len=14
  158. buf=good-bye world, len=14
  159. .fi
  160. .P
  161. .RE
  162. .SH "APPLICATION USAGE"
  163. The buffer created by these functions should be freed by the
  164. application after closing the stream, by means of a call to
  165. \fIfree\fR().
  166. .SH RATIONALE
  167. These functions are similar to
  168. \fIfmemopen\fR()
  169. except that the memory is always allocated dynamically by the function,
  170. and the stream is opened only for output.
  171. .SH "FUTURE DIRECTIONS"
  172. None.
  173. .SH "SEE ALSO"
  174. .IR "\fIfclose\fR\^(\|)",
  175. .IR "\fIfdopen\fR\^(\|)",
  176. .IR "\fIfflush\fR\^(\|)",
  177. .IR "\fIfmemopen\fR\^(\|)",
  178. .IR "\fIfopen\fR\^(\|)",
  179. .IR "\fIfree\fR\^(\|)",
  180. .IR "\fIfreopen\fR\^(\|)"
  181. .P
  182. The Base Definitions volume of POSIX.1\(hy2017,
  183. .IR "\fB<stdio.h>\fP",
  184. .IR "\fB<wchar.h>\fP"
  185. .\"
  186. .SH COPYRIGHT
  187. Portions of this text are reprinted and reproduced in electronic form
  188. from IEEE Std 1003.1-2017, Standard for Information Technology
  189. -- Portable Operating System Interface (POSIX), The Open Group Base
  190. Specifications Issue 7, 2018 Edition,
  191. Copyright (C) 2018 by the Institute of
  192. Electrical and Electronics Engineers, Inc and The Open Group.
  193. In the event of any discrepancy between this version and the original IEEE and
  194. The Open Group Standard, the original IEEE and The Open Group Standard
  195. is the referee document. The original Standard can be obtained online at
  196. http://www.opengroup.org/unix/online.html .
  197. .PP
  198. Any typographical or formatting errors that appear
  199. in this page are most likely
  200. to have been introduced during the conversion of the source files to
  201. man page format. To report such errors, see
  202. https://www.kernel.org/doc/man-pages/reporting_bugs.html .