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

fclose.3p (6094B)


  1. '\" et
  2. .TH FCLOSE "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. fclose
  12. \(em close a stream
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <stdio.h>
  17. .P
  18. int fclose(FILE *\fIstream\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The functionality described on this reference page is aligned with the
  22. ISO\ C standard. Any conflict between the requirements described here and the
  23. ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
  24. .P
  25. The
  26. \fIfclose\fR()
  27. function shall cause the stream pointed to by
  28. .IR stream
  29. to be flushed and the associated file to be closed. Any unwritten
  30. buffered data for the stream shall be written to the file; any unread
  31. buffered data shall be discarded. Whether or not the call succeeds,
  32. the stream shall be disassociated from the file and any buffer set by
  33. the
  34. \fIsetbuf\fR()
  35. or
  36. \fIsetvbuf\fR()
  37. function shall be disassociated from the stream. If the associated
  38. buffer was automatically allocated, it shall be deallocated.
  39. .P
  40. If the file is not already at EOF, and the file is one capable of seeking,
  41. the file offset of the underlying open file description shall be set to
  42. the file position of the stream if the stream is the active handle to
  43. the underlying file description.
  44. .P
  45. The
  46. \fIfclose\fR()
  47. function shall mark for update the last data modification and last
  48. file status change timestamps of the underlying file, if the stream was
  49. writable, and if buffered data remains that has not yet been written to
  50. the file. The
  51. \fIfclose\fR()
  52. function shall perform the equivalent of a
  53. \fIclose\fR()
  54. on the file descriptor that is associated with the stream pointed to by
  55. .IR stream .
  56. .P
  57. After the call to
  58. \fIfclose\fR(),
  59. any use of
  60. .IR stream
  61. results in undefined behavior.
  62. .SH "RETURN VALUE"
  63. Upon successful completion,
  64. \fIfclose\fR()
  65. shall return 0; otherwise, it shall return EOF
  66. and set
  67. .IR errno
  68. to indicate the error.
  69. .SH ERRORS
  70. The
  71. \fIfclose\fR()
  72. function shall fail if:
  73. .TP
  74. .BR EAGAIN
  75. The O_NONBLOCK flag is set for the file descriptor underlying
  76. .IR stream
  77. and the thread would be delayed in the write operation.
  78. .TP
  79. .BR EBADF
  80. The file descriptor underlying stream is not valid.
  81. .TP
  82. .BR EFBIG
  83. An attempt was made to write a file that exceeds the maximum file size.
  84. .TP
  85. .BR EFBIG
  86. An attempt was made to write a file that exceeds the file size
  87. limit of the process.
  88. .TP
  89. .BR EFBIG
  90. The file is a regular file and an attempt was made to write at or beyond
  91. the offset maximum associated with the corresponding stream.
  92. .TP
  93. .BR EINTR
  94. The
  95. \fIfclose\fR()
  96. function was interrupted by a signal.
  97. .TP
  98. .BR EIO
  99. The process is a member of a background process group attempting to
  100. write to its controlling terminal, TOSTOP is set, the calling thread
  101. is not blocking SIGTTOU, the process is not ignoring SIGTTOU, and the
  102. process group of the process is orphaned.
  103. This error may also be returned under implementation-defined conditions.
  104. .TP
  105. .BR ENOMEM
  106. The underlying stream was created by
  107. \fIopen_memstream\fR()
  108. or
  109. \fIopen_wmemstream\fR()
  110. and insufficient memory is available.
  111. .TP
  112. .BR ENOSPC
  113. There was no free space remaining on the device containing the file or
  114. in the buffer used by the
  115. \fIfmemopen\fR()
  116. function.
  117. .TP
  118. .BR EPIPE
  119. An attempt is made to write to a pipe or FIFO that is not open for
  120. reading by any process. A SIGPIPE signal shall also be sent to the
  121. thread.
  122. .P
  123. The
  124. \fIfclose\fR()
  125. function may fail if:
  126. .TP
  127. .BR ENXIO
  128. A request was made of a nonexistent device, or the request was outside
  129. the capabilities of the device.
  130. .LP
  131. .IR "The following sections are informative."
  132. .SH EXAMPLES
  133. None.
  134. .SH "APPLICATION USAGE"
  135. Since after the call to
  136. \fIfclose\fR()
  137. any use of
  138. .IR stream
  139. results in undefined behavior,
  140. \fIfclose\fR()
  141. should not be used on
  142. .IR stdin ,
  143. .IR stdout ,
  144. or
  145. .IR stderr
  146. except immediately before process termination (see the Base Definitions volume of POSIX.1\(hy2017,
  147. .IR "Section 3.303" ", " "Process Termination"),
  148. so as to avoid triggering undefined behavior in other standard
  149. interfaces that rely on these streams. If there are any
  150. \fIatexit\fR()
  151. handlers registered by the application, such a call to
  152. \fIfclose\fR()
  153. should not occur until the last handler is finishing. Once
  154. \fIfclose\fR()
  155. has been used to close
  156. .IR stdin ,
  157. .IR stdout ,
  158. or
  159. .IR stderr ,
  160. there is no standard way to reopen any of these streams.
  161. .P
  162. Use of
  163. \fIfreopen\fR()
  164. to change
  165. .IR stdin ,
  166. .IR stdout ,
  167. or
  168. .IR stderr
  169. instead of closing them avoids the danger of a file unexpectedly
  170. being opened as one of the special file descriptors STDIN_FILENO,
  171. STDOUT_FILENO, or STDERR_FILENO at a later time in the application.
  172. .SH RATIONALE
  173. None.
  174. .SH "FUTURE DIRECTIONS"
  175. None.
  176. .SH "SEE ALSO"
  177. .IR "Section 2.5" ", " "Standard I/O Streams",
  178. .IR "\fIatexit\fR\^(\|)",
  179. .IR "\fIclose\fR\^(\|)",
  180. .IR "\fIfmemopen\fR\^(\|)",
  181. .IR "\fIfopen\fR\^(\|)",
  182. .IR "\fIfreopen\fR\^(\|)",
  183. .IR "\fIgetrlimit\fR\^(\|)",
  184. .IR "\fIopen_memstream\fR\^(\|)",
  185. .IR "\fIulimit\fR\^(\|)"
  186. .P
  187. The Base Definitions volume of POSIX.1\(hy2017,
  188. .IR "\fB<stdio.h>\fP"
  189. .\"
  190. .SH COPYRIGHT
  191. Portions of this text are reprinted and reproduced in electronic form
  192. from IEEE Std 1003.1-2017, Standard for Information Technology
  193. -- Portable Operating System Interface (POSIX), The Open Group Base
  194. Specifications Issue 7, 2018 Edition,
  195. Copyright (C) 2018 by the Institute of
  196. Electrical and Electronics Engineers, Inc and The Open Group.
  197. In the event of any discrepancy between this version and the original IEEE and
  198. The Open Group Standard, the original IEEE and The Open Group Standard
  199. is the referee document. The original Standard can be obtained online at
  200. http://www.opengroup.org/unix/online.html .
  201. .PP
  202. Any typographical or formatting errors that appear
  203. in this page are most likely
  204. to have been introduced during the conversion of the source files to
  205. man page format. To report such errors, see
  206. https://www.kernel.org/doc/man-pages/reporting_bugs.html .