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

close.3p (10509B)


  1. '\" et
  2. .TH CLOSE "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. close
  12. \(em close a file descriptor
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int close(int \fIfildes\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIclose\fR()
  23. function shall deallocate the file descriptor indicated by
  24. .IR fildes .
  25. To deallocate means to make the file descriptor available for return by
  26. subsequent calls to
  27. \fIopen\fR()
  28. or other functions that allocate file descriptors. All outstanding
  29. record locks owned by the process on the file associated with the file
  30. descriptor shall be removed (that is, unlocked).
  31. .P
  32. If
  33. \fIclose\fR()
  34. is interrupted by a signal that is to be caught, it shall return
  35. \-1 with
  36. .IR errno
  37. set to
  38. .BR [EINTR]
  39. and the state of
  40. .IR fildes
  41. is unspecified. If an I/O error occurred while reading from or writing
  42. to the file system during
  43. \fIclose\fR(),
  44. it may return \-1 with
  45. .IR errno
  46. set to
  47. .BR [EIO] ;
  48. if this error is returned, the state of
  49. .IR fildes
  50. is unspecified.
  51. .P
  52. When all file descriptors associated with a pipe or FIFO special file
  53. are closed, any data remaining in the pipe or FIFO shall be discarded.
  54. .P
  55. When all file descriptors associated with an open file description have
  56. been closed, the open file description shall be freed.
  57. .P
  58. If the link count of the file is 0, when all file descriptors
  59. associated with the file are closed, the space occupied by the file
  60. shall be freed and the file shall no longer be accessible.
  61. .P
  62. If a STREAMS-based
  63. .IR fildes
  64. is closed and the calling process was previously registered to receive
  65. a SIGPOLL signal
  66. for events associated with that STREAM, the calling process shall be
  67. unregistered for events associated with the STREAM. The last
  68. \fIclose\fR()
  69. for a STREAM shall cause the STREAM associated with
  70. .IR fildes
  71. to be dismantled. If O_NONBLOCK is not set and there have been no
  72. signals posted for the STREAM,
  73. and if there is data on the module's write queue,
  74. \fIclose\fR()
  75. shall wait for an unspecified time (for each module and driver) for
  76. any output to drain before dismantling the STREAM. The time delay
  77. can be changed via an I_SETCLTIME
  78. \fIioctl\fR()
  79. request. If the O_NONBLOCK flag is set, or if there are any pending
  80. signals,
  81. \fIclose\fR()
  82. shall not wait for output to drain, and shall dismantle the STREAM
  83. immediately.
  84. .P
  85. If the implementation supports STREAMS-based pipes, and
  86. .IR fildes
  87. is associated with one end of a pipe, the last
  88. \fIclose\fR()
  89. shall cause a hangup to occur on the other end of the pipe. In
  90. addition, if the other end of the pipe has been named by
  91. \fIfattach\fR(),
  92. then the last
  93. \fIclose\fR()
  94. shall force the named end to be detached by
  95. \fIfdetach\fR().
  96. If the named end has no open file descriptors associated with it and
  97. gets detached, the STREAM associated with that end shall also be
  98. dismantled.
  99. .P
  100. If
  101. .IR fildes
  102. refers to the master side of a pseudo-terminal, and this is the last
  103. close, a SIGHUP signal shall be sent to the
  104. controlling process, if any, for which the slave side of the
  105. pseudo-terminal is the controlling terminal. It is unspecified whether
  106. closing the master side of the pseudo-terminal flushes all queued input
  107. and output.
  108. .P
  109. If
  110. .IR fildes
  111. refers to the slave side of a STREAMS-based pseudo-terminal, a
  112. zero-length message may be sent to the master.
  113. .P
  114. When there is an outstanding cancelable asynchronous I/O operation
  115. against
  116. .IR fildes
  117. when
  118. \fIclose\fR()
  119. is called, that I/O operation may be canceled. An I/O operation that
  120. is not canceled completes as if the
  121. \fIclose\fR()
  122. operation had not yet occurred. All operations that are not canceled
  123. shall complete as if the
  124. \fIclose\fR()
  125. blocked until the operations completed. The
  126. \fIclose\fR()
  127. operation itself need not block awaiting such I/O completion. Whether
  128. any I/O operation is canceled, and which I/O operation may be
  129. canceled upon
  130. \fIclose\fR(),
  131. is implementation-defined.
  132. .P
  133. If a memory mapped file
  134. or a shared memory object
  135. remains referenced at the last close (that is, a process has
  136. it mapped), then the entire contents of the memory object shall
  137. persist until the memory object becomes unreferenced.
  138. If this is the last close of a memory mapped file
  139. or a shared memory object
  140. and the close results in the memory object becoming unreferenced,
  141. and the memory object has been unlinked, then the memory object
  142. shall be removed.
  143. .P
  144. If
  145. .IR fildes
  146. refers to a socket,
  147. \fIclose\fR()
  148. shall cause the socket to be destroyed. If the socket is in
  149. connection-mode, and the SO_LINGER option is set for the socket with
  150. non-zero linger time, and the socket has untransmitted data, then
  151. \fIclose\fR()
  152. shall block for up to the current linger interval until all data is
  153. transmitted.
  154. .SH "RETURN VALUE"
  155. Upon successful completion, 0 shall be returned; otherwise, \-1
  156. shall be returned and
  157. .IR errno
  158. set to indicate the error.
  159. .SH ERRORS
  160. The
  161. \fIclose\fR()
  162. function shall fail if:
  163. .TP
  164. .BR EBADF
  165. The
  166. .IR fildes
  167. argument is not a open file descriptor.
  168. .TP
  169. .BR EINTR
  170. The
  171. \fIclose\fR()
  172. function was interrupted by a signal.
  173. .P
  174. The
  175. \fIclose\fR()
  176. function may fail if:
  177. .TP
  178. .BR EIO
  179. An I/O error occurred while reading from or writing to the file system.
  180. .LP
  181. .IR "The following sections are informative."
  182. .SH EXAMPLES
  183. .SS "Reassigning a File Descriptor"
  184. .P
  185. The following example closes the file descriptor associated with
  186. standard output for the current process, re-assigns standard output to
  187. a new file descriptor, and closes the original file descriptor to clean
  188. up. This example assumes that the file descriptor 0 (which is the
  189. descriptor for standard input) is not closed.
  190. .sp
  191. .RS 4
  192. .nf
  193. #include <unistd.h>
  194. \&...
  195. int pfd;
  196. \&...
  197. close(1);
  198. dup(pfd);
  199. close(pfd);
  200. \&...
  201. .fi
  202. .P
  203. .RE
  204. .P
  205. Incidentally, this is exactly what could be achieved using:
  206. .sp
  207. .RS 4
  208. .nf
  209. dup2(pfd, 1);
  210. close(pfd);
  211. .fi
  212. .P
  213. .RE
  214. .SS "Closing a File Descriptor"
  215. .P
  216. In the following example,
  217. \fIclose\fR()
  218. is used to close
  219. a file descriptor after an unsuccessful attempt is made to associate that
  220. file descriptor with a stream.
  221. .sp
  222. .RS 4
  223. .nf
  224. #include <stdio.h>
  225. #include <unistd.h>
  226. #include <stdlib.h>
  227. .P
  228. #define LOCKFILE "/etc/ptmp"
  229. \&...
  230. int pfd;
  231. FILE *fpfd;
  232. \&...
  233. if ((fpfd = fdopen (pfd, "w")) == NULL) {
  234. close(pfd);
  235. unlink(LOCKFILE);
  236. exit(1);
  237. }
  238. \&...
  239. .fi
  240. .P
  241. .RE
  242. .SH "APPLICATION USAGE"
  243. An application that had used the
  244. .IR stdio
  245. routine
  246. \fIfopen\fR()
  247. to open a file should use the corresponding
  248. \fIfclose\fR()
  249. routine rather than
  250. \fIclose\fR().
  251. Once a file is closed, the file descriptor no longer exists, since the
  252. integer corresponding to it no longer refers to a file.
  253. .P
  254. Implementations may use file descriptors that must be inherited into
  255. child processes for the child process to remain conforming, such as for
  256. message catalog or tracing purposes. Therefore, an application that calls
  257. \fIclose\fR()
  258. on an arbitrary integer risks non-conforming behavior, and
  259. \fIclose\fR()
  260. can only portably be used on file descriptor values that the application
  261. has obtained through explicit actions, as well as the three file
  262. descriptors corresponding to the standard file streams. In multi-threaded
  263. parent applications, the practice of calling
  264. \fIclose\fR()
  265. in a loop after
  266. \fIfork\fR()
  267. and before an
  268. .IR exec
  269. call in order to avoid a race condition of leaking an unintended file
  270. descriptor into a child process, is therefore unsafe, and the race should
  271. instead be combatted by opening all file descriptors with the FD_CLOEXEC
  272. bit set unless the file descriptor is intended to be inherited across
  273. .IR exec .
  274. .P
  275. Usage of
  276. \fIclose\fR()
  277. on file descriptors STDIN_FILENO, STDOUT_FILENO, or STDERR_FILENO
  278. should immediately be followed by an operation to reopen these file
  279. descriptors. Unexpected behavior will result if any of these file
  280. descriptors is left in a closed state (for example, an
  281. .BR [EBADF]
  282. error from
  283. \fIperror\fR())
  284. or if an unrelated
  285. \fIopen\fR()
  286. or similar call later in the application accidentally allocates
  287. a file to one of these well-known file descriptors. Furthermore, a
  288. \fIclose\fR()
  289. followed by a reopen operation (e.g.,
  290. \fIopen\fR(),
  291. \fIdup\fR(),
  292. etc.) is not atomic;
  293. \fIdup2\fR()
  294. should be used to change standard file descriptors.
  295. .SH RATIONALE
  296. The use of interruptible device close routines should be discouraged to
  297. avoid problems with the implicit closes of file descriptors by
  298. .IR exec
  299. and
  300. \fIexit\fR().
  301. This volume of POSIX.1\(hy2017 only intends to permit such behavior by specifying the
  302. .BR [EINTR]
  303. error condition.
  304. .P
  305. Note that the requirement for
  306. \fIclose\fR()
  307. on a socket to block for up to the current linger interval is not
  308. conditional on the O_NONBLOCK setting.
  309. .P
  310. The standard developers rejected a proposal to add
  311. \fIclosefrom\fR()
  312. to the standard. Because the standard permits implementations to
  313. use inherited file descriptors as a means of providing a conforming
  314. environment for the child process, it is not possible to standardize an
  315. interface that closes arbitrary file descriptors above a certain value
  316. while still guaranteeing a conforming environment.
  317. .SH "FUTURE DIRECTIONS"
  318. None.
  319. .SH "SEE ALSO"
  320. .IR "Section 2.6" ", " "STREAMS",
  321. .IR "\fIdup\fR\^(\|)",
  322. .IR "\fIexec\fR\^",
  323. .IR "\fIexit\fR\^(\|)",
  324. .IR "\fIfattach\fR\^(\|)",
  325. .IR "\fIfclose\fR\^(\|)",
  326. .IR "\fIfdetach\fR\^(\|)",
  327. .IR "\fIfopen\fR\^(\|)",
  328. .IR "\fIfork\fR\^(\|)",
  329. .IR "\fIioctl\fR\^(\|)",
  330. .IR "\fIopen\fR\^(\|)",
  331. .IR "\fIperror\fR\^(\|)",
  332. .IR "\fIunlink\fR\^(\|)"
  333. .P
  334. The Base Definitions volume of POSIX.1\(hy2017,
  335. .IR "\fB<unistd.h>\fP"
  336. .\"
  337. .SH COPYRIGHT
  338. Portions of this text are reprinted and reproduced in electronic form
  339. from IEEE Std 1003.1-2017, Standard for Information Technology
  340. -- Portable Operating System Interface (POSIX), The Open Group Base
  341. Specifications Issue 7, 2018 Edition,
  342. Copyright (C) 2018 by the Institute of
  343. Electrical and Electronics Engineers, Inc and The Open Group.
  344. In the event of any discrepancy between this version and the original IEEE and
  345. The Open Group Standard, the original IEEE and The Open Group Standard
  346. is the referee document. The original Standard can be obtained online at
  347. http://www.opengroup.org/unix/online.html .
  348. .PP
  349. Any typographical or formatting errors that appear
  350. in this page are most likely
  351. to have been introduced during the conversion of the source files to
  352. man page format. To report such errors, see
  353. https://www.kernel.org/doc/man-pages/reporting_bugs.html .