]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
b36a3b92 MK |
2 | .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. |
3 | .\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> | |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" Modified Wed Jul 21 22:40:25 1993 by Rik Faith <faith@cs.unc.edu> | |
8 | .\" Modified Sat Feb 18 15:27:48 1995 by Michael Haardt | |
9 | .\" Modified Sun Apr 14 11:40:50 1996 by Andries Brouwer <aeb@cwi.nl>: | |
10 | .\" corrected description of effect on locks (thanks to | |
11 | .\" Tigran Aivazian <tigran@sco.com>). | |
12 | .\" Modified Fri Jan 31 16:21:46 1997 by Eric S. Raymond <esr@thyrsus.com> | |
e00c3a07 | 13 | .\" Modified 2000-07-22 by Nicolás Lichtmaier <nick@debian.org> |
fea681da MK |
14 | .\" added note about close(2) not guaranteeing that data is safe on close. |
15 | .\" | |
45186a5d | 16 | .TH CLOSE 2 2021-03-22 "Linux man-pages (unreleased)" |
fea681da MK |
17 | .SH NAME |
18 | close \- close a file descriptor | |
e9f4d62c AC |
19 | .SH LIBRARY |
20 | Standard C library | |
8fc3b2cf | 21 | .RI ( libc ", " \-lc ) |
fea681da MK |
22 | .SH SYNOPSIS |
23 | .nf | |
24 | .B #include <unistd.h> | |
68e4db0a | 25 | .PP |
fea681da MK |
26 | .BI "int close(int " fd ); |
27 | .fi | |
28 | .SH DESCRIPTION | |
082aa784 | 29 | .BR close () |
fea681da | 30 | closes a file descriptor, so that it no longer refers to any file and |
082aa784 MK |
31 | may be reused. |
32 | Any record locks (see | |
33 | .BR fcntl (2)) | |
34 | held on the file it was associated with, | |
fea681da MK |
35 | and owned by the process, are removed (regardless of the file |
36 | descriptor that was used to obtain the lock). | |
37 | .PP | |
38 | If | |
39 | .I fd | |
12d8baeb MK |
40 | is the last file descriptor referring to the underlying |
41 | open file description (see | |
42 | .BR open (2)), | |
43 | the resources associated with the open file description are freed; | |
d9cb0d7d | 44 | if the file descriptor was the last reference to a file which has been |
fea681da | 45 | removed using |
bfc0e342 | 46 | .BR unlink (2), |
fea681da | 47 | the file is deleted. |
47297adb | 48 | .SH RETURN VALUE |
082aa784 | 49 | .BR close () |
cca657e2 MK |
50 | returns zero on success. |
51 | On error, \-1 is returned, and | |
52 | .I errno | |
f6a4078b | 53 | is set to indicate the error. |
fea681da MK |
54 | .SH ERRORS |
55 | .TP | |
56 | .B EBADF | |
57 | .I fd | |
58 | isn't a valid open file descriptor. | |
59 | .TP | |
60 | .B EINTR | |
c7dc46d0 MK |
61 | .\" Though, it's in doubt whether this error can ever occur; see |
62 | .\" https://lwn.net/Articles/576478/ "Returning EINTR from close()" | |
fea681da MK |
63 | The |
64 | .BR close () | |
6602d44b MK |
65 | call was interrupted by a signal; see |
66 | .BR signal (7). | |
fea681da MK |
67 | .TP |
68 | .B EIO | |
69 | An I/O error occurred. | |
9c93cce7 N |
70 | .TP |
71 | .BR ENOSPC ", " EDQUOT | |
72 | On NFS, these errors are not normally reported against the first write | |
73 | which exceeds the available storage space, but instead against a | |
74 | subsequent | |
75 | .BR write (2), | |
76 | .BR fsync (2), | |
77 | or | |
549597a8 | 78 | .BR close (). |
2904e19a MK |
79 | .PP |
80 | See NOTES for a discussion of why | |
81 | .BR close () | |
82 | should not be retried after an error. | |
3113c7f3 | 83 | .SH STANDARDS |
11aac258 | 84 | POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. |
97c1eac8 | 85 | .\" SVr4 documents an additional ENOLINK error condition. |
fea681da | 86 | .SH NOTES |
049c89bd MK |
87 | A successful close does not guarantee that the data has been successfully |
88 | saved to disk, as the kernel uses the buffer cache to defer writes. | |
89 | Typically, filesystems do not flush buffers when a file is closed. | |
90 | If you need to be sure that | |
91 | the data is physically stored on the underlying disk, use | |
92 | .BR fsync (2). | |
93 | (It will depend on the disk hardware at this point.) | |
94 | .PP | |
95 | The close-on-exec file descriptor flag can be used to ensure | |
96 | that a file descriptor is automatically closed upon a successful | |
97 | .BR execve (2); | |
98 | see | |
99 | .BR fcntl (2) | |
100 | for details. | |
c2f15a13 MK |
101 | .\" |
102 | .SS Multithreaded processes and close() | |
049c89bd MK |
103 | It is probably unwise to close file descriptors while |
104 | they may be in use by system calls in | |
105 | other threads in the same process. | |
106 | Since a file descriptor may be reused, | |
107 | there are some obscure race conditions | |
108 | that may cause unintended side effects. | |
109 | .\" Date: Tue, 4 Sep 2007 13:57:35 +0200 | |
110 | .\" From: Fredrik Noring <noring@nocrew.org> | |
111 | .\" One such race involves signals and ERESTARTSYS. If a file descriptor | |
112 | .\" in use by a system call is closed and then reused by e.g. an | |
113 | .\" independent open() in some unrelated thread, before the original system | |
114 | .\" call has restarted after ERESTARTSYS, the original system call will | |
115 | .\" later restart with the reused file descriptor. This is most likely a | |
116 | .\" serious programming error. | |
c2f15a13 MK |
117 | .PP |
118 | Furthermore, consider the following scenario where two threads are | |
119 | performing operations on the same file descriptor: | |
120 | .IP 1. 3 | |
121 | One thread is blocked in an I/O system call on the file descriptor. | |
122 | For example, it is trying to | |
123 | .BR write (2) | |
124 | to a pipe that is already full, or trying to | |
125 | .BR read (2) | |
126 | from a stream socket which currently has no available data. | |
127 | .IP 2. | |
128 | Another thread closes the file descriptor. | |
129 | .PP | |
130 | The behavior in this situation varies across systems. | |
131 | On some systems, when the file descriptor is closed, | |
132 | the blocking system call returns immediately with an error. | |
133 | .PP | |
03659d7d | 134 | On Linux (and possibly some other systems), the behavior is different: |
c2f15a13 MK |
135 | the blocking I/O system call holds a reference to the underlying |
136 | open file description, and this reference keeps the description open | |
137 | until the I/O system call completes. | |
138 | .\" 'struct file' in kernel-speak | |
139 | (See | |
140 | .BR open (2) | |
141 | for a discussion of open file descriptions.) | |
142 | Thus, the blocking system call in the first thread may successfully | |
143 | complete after the | |
a36d5a35 | 144 | .BR close () |
c2f15a13 | 145 | in the second thread. |
049c89bd MK |
146 | .\" |
147 | .SS Dealing with error returns from close() | |
b61a87d5 MK |
148 | A careful programmer will check the return value of |
149 | .BR close (), | |
150 | since it is quite possible that errors on a previous | |
fea681da | 151 | .BR write (2) |
b61a87d5 MK |
152 | operation are reported only on the final |
153 | .BR close () | |
154 | that releases the open file description. | |
155 | Failing to check the return value when closing a file may lead to | |
156 | .I silent | |
157 | loss of data. | |
158 | This can especially be observed with NFS and with disk quota. | |
efeece04 | 159 | .PP |
e8730f0e MK |
160 | Note, however, that a failure return should be used only for |
161 | diagnostic purposes (i.e., a warning to the application that there | |
1cab7c16 MK |
162 | may still be I/O pending or there may have been failed I/O) |
163 | or remedial purposes | |
164 | (e.g., writing the file once more or creating a backup). | |
efeece04 | 165 | .PP |
2904e19a MK |
166 | Retrying the |
167 | .BR close () | |
e8730f0e | 168 | after a failure return is the wrong thing to do, |
2904e19a MK |
169 | .\" The file descriptor is released early in close(); |
170 | .\" close() ==> __close_fd(): | |
171 | .\" __put_unused_fd() ==> __clear_open_fd() | |
172 | .\" return filp_close(file, files); | |
173 | .\" | |
e8730f0e | 174 | .\" The errors are returned by filp_close() after the FD has been |
2904e19a MK |
175 | .\" cleared for re-use. |
176 | since this may cause a reused file descriptor | |
177 | from another thread to be closed. | |
7155aa77 MK |
178 | This can occur because the Linux kernel |
179 | .I always | |
180 | releases the file descriptor early in the close | |
2904e19a MK |
181 | operation, freeing it for reuse; |
182 | the steps that may return an error, | |
183 | .\" filp_close() | |
f65f00b0 | 184 | such as flushing data to the filesystem or device, |
7155aa77 | 185 | occur only later in the close operation. |
efeece04 | 186 | .PP |
d24623ee MK |
187 | Many other implementations similarly always close the file descriptor |
188 | .\" FreeBSD documents this explicitly. From the look of the source code | |
7fe8ca51 | 189 | .\" SVR4, ancient SunOS, later Solaris, and AIX all do this. |
d24623ee MK |
190 | (except in the case of |
191 | .BR EBADF , | |
192 | meaning that the file descriptor was invalid) | |
7fe8ca51 | 193 | even if they subsequently report an error on return from |
d24623ee MK |
194 | .BR close (). |
195 | POSIX.1 is currently silent on this point, | |
196 | but there are plans to mandate this behavior in the next major release | |
197 | .\" Issue 8 | |
a25c6036 | 198 | of the standard. |
efeece04 | 199 | .PP |
35e0ce1c MK |
200 | A careful programmer who wants to know about I/O errors may precede |
201 | .BR close () | |
202 | with a call to | |
203 | .BR fsync (2). | |
efeece04 | 204 | .PP |
e8730f0e MK |
205 | The |
206 | .B EINTR | |
207 | error is a somewhat special case. | |
b36a3b92 MK |
208 | Regarding the |
209 | .B EINTR | |
b710e161 | 210 | error, POSIX.1-2008 says: |
efeece04 | 211 | .PP |
b36a3b92 MK |
212 | .RS |
213 | If | |
2904e19a MK |
214 | .BR close () |
215 | is interrupted by a signal that is to be caught, it shall return \-1 with | |
216 | .I errno | |
217 | set to | |
218 | .B EINTR | |
73c922ea MK |
219 | and the state of |
220 | .I fildes | |
221 | is unspecified. | |
b36a3b92 | 222 | .RE |
efeece04 | 223 | .PP |
b36a3b92 | 224 | This permits the behavior that occurs on Linux and |
e8730f0e MK |
225 | many other implementations, where, |
226 | as with other errors that may be reported by | |
227 | .BR close (), | |
b36a3b92 MK |
228 | the file descriptor is guaranteed to be closed. |
229 | However, it also permits another possibility: | |
230 | that the implementation returns an | |
231 | .B EINTR | |
232 | error and keeps the file descriptor open. | |
233 | (According to its documentation, HP-UX's | |
234 | .BR close () | |
235 | does this.) | |
236 | The caller must then once more use | |
237 | .BR close () | |
238 | to close the file descriptor, to avoid file descriptor leaks. | |
239 | This divergence in implementation behaviors provides | |
240 | a difficult hurdle for portable applications, since on many implementations, | |
241 | .BR close () | |
242 | must not be called again after an | |
243 | .B EINTR | |
244 | error, and on at least one, | |
245 | .BR close () | |
246 | must be called again. | |
247 | There are plans to address this conundrum for | |
248 | the next major release of the POSIX.1 standard. | |
2904e19a MK |
249 | .\" FIXME . for later review when Issue 8 is one day released... |
250 | .\" POSIX proposes further changes for EINTR | |
251 | .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 | |
252 | .\" http://austingroupbugs.net/view.php?id=529 | |
ca734d5b MK |
253 | .\" |
254 | .\" FIXME . | |
255 | .\" Review the following glibc bug later | |
256 | .\" https://sourceware.org/bugzilla/show_bug.cgi?id=14627 | |
47297adb | 257 | .SH SEE ALSO |
3bb4fe47 | 258 | .BR close_range (2), |
fea681da MK |
259 | .BR fcntl (2), |
260 | .BR fsync (2), | |
261 | .BR open (2), | |
262 | .BR shutdown (2), | |
263 | .BR unlink (2), | |
264 | .BR fclose (3) |