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