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

fdopen.3p (5255B)

    

  1. '\" et
  2. .TH FDOPEN "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. fdopen
  12. \(em associate a stream with a file descriptor
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. FILE *fdopen(int \fIfildes\fP, const char *\fImode\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIfdopen\fR()
  23. function shall associate a stream with a file descriptor.
  24. .P
  25. The
  26. .IR mode
  27. argument is a character string having one of the following values:
  28. .IP "\fIr\fP\ or\ \fIrb\fP" 14
  29. Open a file for reading.
  30. .IP "\fIw\fP\ or\ \fIwb\fP" 14
  31. Open a file for writing.
  32. .IP "\fIa\fP\ or\ \fIab\fP" 14
  33. Open a file for writing at end-of-file.
  34. .IP "\fIr\fP+\ or\ \fIrb\fP+\ or\ \fIr\fP+\fIb\fP" 14
  35. Open a file for update (reading and writing).
  36. .IP "\fIw\fP+\ or\ \fIwb\fP+\ or\ \fIw\fP+\fIb\fP" 14
  37. Open a file for update (reading and writing).
  38. .IP "\fIa\fP+\ or\ \fIab\fP+\ or\ \fIa\fP+\fIb\fP" 14
  39. Open a file for update (reading and writing) at end-of-file.
  40. .P
  41. The meaning of these flags is exactly as specified in
  42. \fIfopen\fR(),
  43. except that modes beginning with
  44. .IR w
  45. shall not cause truncation of the file.
  46. .P
  47. Additional values for the
  48. .IR mode
  49. argument may be supported by an implementation.
  50. .P
  51. The application shall ensure that the mode of the stream as expressed
  52. by the
  53. .IR mode
  54. argument is allowed by the file access mode of the open file
  55. description to which
  56. .IR fildes
  57. refers. The file position indicator associated with the new stream is
  58. set to the position indicated by the file offset associated with the
  59. file descriptor.
  60. .P
  61. The error and end-of-file indicators for the stream shall be cleared.
  62. The
  63. \fIfdopen\fR()
  64. function may cause the last data access timestamp of the underlying
  65. file to be marked for update.
  66. .P
  67. If
  68. .IR fildes
  69. refers to a shared memory object, the result of the
  70. \fIfdopen\fR()
  71. function is unspecified.
  72. .P
  73. If
  74. .IR fildes
  75. refers to a typed memory object, the result of the
  76. \fIfdopen\fR()
  77. function is unspecified.
  78. .P
  79. The
  80. \fIfdopen\fR()
  81. function shall preserve the offset maximum previously set for the
  82. open file description corresponding to
  83. .IR fildes .
  84. .SH "RETURN VALUE"
  85. Upon successful completion,
  86. \fIfdopen\fR()
  87. shall return a pointer to a stream; otherwise, a null pointer shall be
  88. returned and
  89. .IR errno
  90. set to indicate the error.
  91. .SH ERRORS
  92. The
  93. \fIfdopen\fR()
  94. function shall fail if:
  95. .TP
  96. .BR EMFILE
  97. {STREAM_MAX}
  98. streams are currently open in the calling process.
  99. .P
  100. The
  101. \fIfdopen\fR()
  102. function may fail if:
  103. .TP
  104. .BR EBADF
  105. The
  106. .IR fildes
  107. argument is not a valid file descriptor.
  108. .TP
  109. .BR EINVAL
  110. The
  111. .IR mode
  112. argument is not a valid mode.
  113. .TP
  114. .BR EMFILE
  115. {FOPEN_MAX}
  116. streams are currently open in the calling process.
  117. .TP
  118. .BR ENOMEM
  119. Insufficient space to allocate a buffer.
  120. .LP
  121. .IR "The following sections are informative."
  122. .SH EXAMPLES
  123. None.
  124. .SH "APPLICATION USAGE"
  125. File descriptors are obtained from calls like
  126. \fIopen\fR(),
  127. \fIdup\fR(),
  128. \fIcreat\fR(),
  129. or
  130. \fIpipe\fR(),
  131. which open files but do not return streams.
  132. .SH RATIONALE
  133. The file descriptor may have been obtained from
  134. \fIopen\fR(),
  135. \fIcreat\fR(),
  136. \fIpipe\fR(),
  137. \fIdup\fR(),
  138. \fIfcntl\fR(),
  139. or
  140. \fIsocket\fR();
  141. inherited through
  142. \fIfork\fR(),
  143. \fIposix_spawn\fR(),
  144. or
  145. .IR exec ;
  146. or perhaps obtained by other means.
  147. .P
  148. The meanings of the
  149. .IR mode
  150. arguments of
  151. \fIfdopen\fR()
  152. and
  153. \fIfopen\fR()
  154. differ. With
  155. \fIfdopen\fR(),
  156. open for write (\fIw\fP or \fIw+\fP) does not truncate, and append
  157. (\fIa\fP or \fIa+\fP) cannot create for writing. The
  158. .IR mode
  159. argument formats that include a \fIb\fP are allowed for consistency
  160. with the ISO\ C standard function
  161. \fIfopen\fR().
  162. The \fIb\fP has no effect on the resulting stream. Although not
  163. explicitly required by this volume of POSIX.1\(hy2017, a good implementation of append (\fIa\fP)
  164. mode would cause the O_APPEND flag to be set.
  165. .SH "FUTURE DIRECTIONS"
  166. None.
  167. .SH "SEE ALSO"
  168. .IR "Section 2.5.1" ", " "Interaction of File Descriptors and Standard I/O Streams",
  169. .IR "\fIfclose\fR\^(\|)",
  170. .IR "\fIfmemopen\fR\^(\|)",
  171. .IR "\fIfopen\fR\^(\|)",
  172. .IR "\fIopen\fR\^(\|)",
  173. .IR "\fIopen_memstream\fR\^(\|)",
  174. .IR "\fIposix_spawn\fR\^(\|)",
  175. .IR "\fIsocket\fR\^(\|)"
  176. .P
  177. The Base Definitions volume of POSIX.1\(hy2017,
  178. .IR "\fB<stdio.h>\fP"
  179. .\"
  180. .SH COPYRIGHT
  181. Portions of this text are reprinted and reproduced in electronic form
  182. from IEEE Std 1003.1-2017, Standard for Information Technology
  183. -- Portable Operating System Interface (POSIX), The Open Group Base
  184. Specifications Issue 7, 2018 Edition,
  185. Copyright (C) 2018 by the Institute of
  186. Electrical and Electronics Engineers, Inc and The Open Group.
  187. In the event of any discrepancy between this version and the original IEEE and
  188. The Open Group Standard, the original IEEE and The Open Group Standard
  189. is the referee document. The original Standard can be obtained online at
  190. http://www.opengroup.org/unix/online.html .
  191. .PP
  192. Any typographical or formatting errors that appear
  193. in this page are most likely
  194. to have been introduced during the conversion of the source files to
  195. man page format. To report such errors, see
  196. https://www.kernel.org/doc/man-pages/reporting_bugs.html .