man2/close.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\" and Copyright (C) 1993 Michael Haardt, Ian Jackson.
   3 .\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   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.
  14 .\"
  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.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  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>
  33 .\" Modified 2000-07-22 by Nicolás Lichtmaier <nick@debian.org>
  34 .\"   added note about close(2) not guaranteeing that data is safe on close.
  35 .\"
  36 .TH CLOSE 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  37 .SH NAME
  38 close \- close a file descriptor
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <unistd.h>
  42 .PP
  43 .BI "int close(int " fd );
  44 .fi
  45 .SH DESCRIPTION
  46 .BR close ()
  47 closes a file descriptor, so that it no longer refers to any file and
  48 may be reused.
  49 Any record locks (see
  50 .BR fcntl (2))
  51 held on the file it was associated with,
  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
  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;
  61 if the file descriptor was the last reference to a file which has been
  62 removed using
  63 .BR unlink (2),
  64 the file is deleted.
  65 .SH RETURN VALUE
  66 .BR close ()
  67 returns zero on success.
  68 On error, \-1 is returned, and
  69 .I errno
  70 is set to indicate the error.
  71 .SH ERRORS
  72 .TP
  73 .B EBADF
  74 .I fd
  75 isn't a valid open file descriptor.
  76 .TP
  77 .B EINTR
  78 .\" Though, it's in doubt whether this error can ever occur; see
  79 .\" https://lwn.net/Articles/576478/ "Returning EINTR from close()"
  80 The
  81 .BR close ()
  82 call was interrupted by a signal; see
  83 .BR signal (7).
  84 .TP
  85 .B EIO
  86 An I/O error occurred.
  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 ().
  96 .PP
  97 See NOTES for a discussion of why
  98 .BR close ()
  99 should not be retried after an error.
 100 .SH CONFORMING TO
 101 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 102 .\" SVr4 documents an additional ENOLINK error condition.
 103 .SH NOTES
 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 .\"
 119 .SS Multithreaded processes and close()
 120 It is probably unwise to close file descriptors while
 121 they may be in use by system calls in
 122 other threads in the same process.
 123 Since a file descriptor may be reused,
 124 there are some obscure race conditions
 125 that may cause unintended side effects.
 126 .\" Date: Tue, 4 Sep 2007 13:57:35 +0200
 127 .\" From: Fredrik Noring <noring@nocrew.org>
 128 .\" One such race involves signals and ERESTARTSYS. If a file descriptor
 129 .\" in use by a system call is closed and then reused by e.g. an
 130 .\" independent open() in some unrelated thread, before the original system
 131 .\" call has restarted after ERESTARTSYS, the original system call will
 132 .\" later restart with the reused file descriptor. This is most likely a
 133 .\" serious programming error.
 134 .PP
 135 Furthermore, consider the following scenario where two threads are
 136 performing operations on the same file descriptor:
 137 .IP 1. 3
 138 One thread is blocked in an I/O system call on the file descriptor.
 139 For example, it is trying to
 140 .BR write (2)
 141 to a pipe that is already full, or trying to
 142 .BR read (2)
 143 from a stream socket which currently has no available data.
 144 .IP 2.
 145 Another thread closes the file descriptor.
 146 .PP
 147 The behavior in this situation varies across systems.
 148 On some systems, when the file descriptor is closed,
 149 the blocking system call returns immediately with an error.
 150 .PP
 151 On Linux (and possibly some other systems), the behavior is different:
 152 the blocking I/O system call holds a reference to the underlying
 153 open file description, and this reference keeps the description open
 154 until the I/O system call completes.
 155 .\" 'struct file' in kernel-speak
 156 (See
 157 .BR open (2)
 158 for a discussion of open file descriptions.)
 159 Thus, the blocking system call in the first thread may successfully
 160 complete after the
 161 .BR close ()
 162 in the second thread.
 163 .\"
 164 .SS Dealing with error returns from close()
 165 A careful programmer will check the return value of
 166 .BR close (),
 167 since it is quite possible that errors on a previous
 168 .BR write (2)
 169 operation are reported only on the final
 170 .BR close ()
 171 that releases the open file description.
 172 Failing to check the return value when closing a file may lead to
 173 .I silent
 174 loss of data.
 175 This can especially be observed with NFS and with disk quota.
 176 .PP
 177 Note, however, that a failure return should be used only for
 178 diagnostic purposes (i.e., a warning to the application that there
 179 may still be I/O pending or there may have been failed I/O)
 180 or remedial purposes
 181 (e.g., writing the file once more or creating a backup).
 182 .PP
 183 Retrying the
 184 .BR close ()
 185 after a failure return is the wrong thing to do,
 186 .\" The file descriptor is released early in close();
 187 .\" close() ==> __close_fd():
 188 .\"                     __put_unused_fd() ==> __clear_open_fd()
 189 .\"                     return filp_close(file, files);
 190 .\"
 191 .\" The errors are returned by filp_close() after the FD has been
 192 .\" cleared for re-use.
 193 since this may cause a reused file descriptor
 194 from another thread to be closed.
 195 This can occur because the Linux kernel
 196 .I always
 197 releases the file descriptor early in the close
 198 operation, freeing it for reuse;
 199 the steps that may return an error,
 200 .\" filp_close()
 201 such as flushing data to the filesystem or device,
 202 occur only later in the close operation.
 203 .PP
 204 Many other implementations similarly always close the file descriptor
 205 .\" FreeBSD documents this explicitly. From the look of the source code
 206 .\" SVR4, ancient SunOS, later Solaris, and AIX all do this.
 207 (except in the case of
 208 .BR EBADF ,
 209 meaning that the file descriptor was invalid)
 210 even if they subsequently report an error on return from
 211 .BR close ().
 212 POSIX.1 is currently silent on this point,
 213 but there are plans to mandate this behavior in the next major release
 214 .\" Issue 8
 215 of the standard.
 216 .PP
 217 A careful programmer who wants to know about I/O errors may precede
 218 .BR close ()
 219 with a call to
 220 .BR fsync (2).
 221 .PP
 222 The
 223 .B EINTR
 224 error is a somewhat special case.
 225 Regarding the
 226 .B EINTR
 227 error, POSIX.1-2008 says:
 228 .PP
 229 .RS
 230 If
 231 .BR close ()
 232 is interrupted by a signal that is to be caught, it shall return \-1 with
 233 .I errno
 234 set to
 235 .B EINTR
 236 and the state of
 237 .I fildes
 238 is unspecified.
 239 .RE
 240 .PP
 241 This permits the behavior that occurs on Linux and
 242 many other implementations, where,
 243 as with other errors that may be reported by
 244 .BR close (),
 245 the file descriptor is guaranteed to be closed.
 246 However, it also permits another possibility:
 247 that the implementation returns an
 248 .B EINTR
 249 error and keeps the file descriptor open.
 250 (According to its documentation, HP-UX's
 251 .BR close ()
 252 does this.)
 253 The caller must then once more use
 254 .BR close ()
 255 to close the file descriptor, to avoid file descriptor leaks.
 256 This divergence in implementation behaviors provides
 257 a difficult hurdle for portable applications, since on many implementations,
 258 .BR close ()
 259 must not be called again after an
 260 .B EINTR
 261 error, and on at least one,
 262 .BR close ()
 263 must be called again.
 264 There are plans to address this conundrum for
 265 the next major release of the POSIX.1 standard.
 266 .\" FIXME . for later review when Issue 8 is one day released...
 267 .\" POSIX proposes further changes for EINTR
 268 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
 269 .\" http://austingroupbugs.net/view.php?id=529
 270 .\"
 271 .\" FIXME .
 272 .\" Review the following glibc bug later
 273 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=14627
 274 .SH SEE ALSO
 275 .BR close_range (2),
 276 .BR fcntl (2),
 277 .BR fsync (2),
 278 .BR open (2),
 279 .BR shutdown (2),
 280 .BR unlink (2),
 281 .BR fclose (3)