diff options
Diffstat (limited to 'man/man2/close.2')
| -rw-r--r-- | man/man2/close.2 | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/man/man2/close.2 b/man/man2/close.2 new file mode 100644 index 0000000..1ee6c44 --- /dev/null +++ b/man/man2/close.2 @@ -0,0 +1,274 @@ +.\" This manpage is Copyright (C) 1992 Drew Eckhardt; +.\" and Copyright (C) 1993 Michael Haardt, Ian Jackson. +.\" and Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Wed Jul 21 22:40:25 1993 by Rik Faith <faith@cs.unc.edu> +.\" Modified Sat Feb 18 15:27:48 1995 by Michael Haardt +.\" Modified Sun Apr 14 11:40:50 1996 by Andries Brouwer <aeb@cwi.nl>: +.\" corrected description of effect on locks (thanks to +.\" Tigran Aivazian <tigran@sco.com>). +.\" Modified Fri Jan 31 16:21:46 1997 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 2000-07-22 by Nicolás Lichtmaier <nick@debian.org> +.\" added note about close(2) not guaranteeing that data is safe on close. +.\" +.TH close 2 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +close \- close a file descriptor +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int close(int " fd ); +.fi +.SH DESCRIPTION +.BR close () +closes a file descriptor, so that it no longer refers to any file and +may be reused. +Any record locks (see +.BR fcntl (2)) +held on the file it was associated with, +and owned by the process, +are removed regardless of the file descriptor that was used to obtain the lock. +This has some unfortunate consequences +and one should be extra careful when using advisory record locking. +See +.BR fcntl (2) +for discussion of the risks and consequences +as well as for the (probably preferred) open file description locks. +.P +If +.I fd +is the last file descriptor referring to the underlying +open file description (see +.BR open (2)), +the resources associated with the open file description are freed; +if the file descriptor was the last reference to a file which has been +removed using +.BR unlink (2), +the file is deleted. +.SH RETURN VALUE +.BR close () +returns zero on success. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EBADF +.I fd +isn't a valid open file descriptor. +.TP +.B EINTR +.\" Though, it's in doubt whether this error can ever occur; see +.\" https://lwn.net/Articles/576478/ "Returning EINTR from close()" +The +.BR close () +call was interrupted by a signal; see +.BR signal (7). +.TP +.B EIO +An I/O error occurred. +.TP +.B ENOSPC +.TQ +.B EDQUOT +On NFS, these errors are not normally reported against the first write +which exceeds the available storage space, but instead against a +subsequent +.BR write (2), +.BR fsync (2), +or +.BR close (). +.P +See NOTES for a discussion of why +.BR close () +should not be retried after an error. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.\" SVr4 documents an additional ENOLINK error condition. +.SH NOTES +A successful close does not guarantee that the data has been successfully +saved to disk, as the kernel uses the buffer cache to defer writes. +Typically, filesystems do not flush buffers when a file is closed. +If you need to be sure that +the data is physically stored on the underlying disk, use +.BR fsync (2). +(It will depend on the disk hardware at this point.) +.P +The close-on-exec file descriptor flag can be used to ensure +that a file descriptor is automatically closed upon a successful +.BR execve (2); +see +.BR fcntl (2) +for details. +.\" +.SS Multithreaded processes and close() +It is probably unwise to close file descriptors while +they may be in use by system calls in +other threads in the same process. +Since a file descriptor may be reused, +there are some obscure race conditions +that may cause unintended side effects. +.\" Date: Tue, 4 Sep 2007 13:57:35 +0200 +.\" From: Fredrik Noring <noring@nocrew.org> +.\" One such race involves signals and ERESTARTSYS. If a file descriptor +.\" in use by a system call is closed and then reused by e.g. an +.\" independent open() in some unrelated thread, before the original system +.\" call has restarted after ERESTARTSYS, the original system call will +.\" later restart with the reused file descriptor. This is most likely a +.\" serious programming error. +.P +Furthermore, consider the following scenario where two threads are +performing operations on the same file descriptor: +.IP (1) 5 +One thread is blocked in an I/O system call on the file descriptor. +For example, it is trying to +.BR write (2) +to a pipe that is already full, or trying to +.BR read (2) +from a stream socket which currently has no available data. +.IP (2) +Another thread closes the file descriptor. +.P +The behavior in this situation varies across systems. +On some systems, when the file descriptor is closed, +the blocking system call returns immediately with an error. +.P +On Linux (and possibly some other systems), the behavior is different: +the blocking I/O system call holds a reference to the underlying +open file description, and this reference keeps the description open +until the I/O system call completes. +.\" 'struct file' in kernel-speak +(See +.BR open (2) +for a discussion of open file descriptions.) +Thus, the blocking system call in the first thread may successfully +complete after the +.BR close () +in the second thread. +.\" +.SS Dealing with error returns from close() +A careful programmer will check the return value of +.BR close (), +since it is quite possible that errors on a previous +.BR write (2) +operation are reported only on the final +.BR close () +that releases the open file description. +Failing to check the return value when closing a file may lead to +.I silent +loss of data. +This can especially be observed with NFS and with disk quota. +.P +Note, however, that a failure return should be used only for +diagnostic purposes (i.e., a warning to the application that there +may still be I/O pending or there may have been failed I/O) +or remedial purposes +(e.g., writing the file once more or creating a backup). +.P +Retrying the +.BR close () +after a failure return is the wrong thing to do, +.\" The file descriptor is released early in close(); +.\" close() ==> __close_fd(): +.\" __put_unused_fd() ==> __clear_open_fd() +.\" return filp_close(file, files); +.\" +.\" The errors are returned by filp_close() after the FD has been +.\" cleared for re-use. +since this may cause a reused file descriptor +from another thread to be closed. +This can occur because the Linux kernel +.I always +releases the file descriptor early in the close +operation, freeing it for reuse; +the steps that may return an error, +.\" filp_close() +such as flushing data to the filesystem or device, +occur only later in the close operation. +.P +Many other implementations similarly always close the file descriptor +.\" FreeBSD documents this explicitly. From the look of the source code +.\" SVR4, ancient SunOS, later Solaris, and AIX all do this. +(except in the case of +.BR EBADF , +meaning that the file descriptor was invalid) +even if they subsequently report an error on return from +.BR close (). +POSIX.1 is currently silent on this point, +but there are plans to mandate this behavior in the next major release +.\" Issue 8 +of the standard. +.P +A careful programmer who wants to know about I/O errors may precede +.BR close () +with a call to +.BR fsync (2). +.P +The +.B EINTR +error is a somewhat special case. +Regarding the +.B EINTR +error, POSIX.1-2008 says: +.P +.RS +If +.BR close () +is interrupted by a signal that is to be caught, it shall return \-1 with +.I errno +set to +.B EINTR +and the state of +.I fildes +is unspecified. +.RE +.P +This permits the behavior that occurs on Linux and +many other implementations, where, +as with other errors that may be reported by +.BR close (), +the file descriptor is guaranteed to be closed. +However, it also permits another possibility: +that the implementation returns an +.B EINTR +error and keeps the file descriptor open. +(According to its documentation, HP-UX's +.BR close () +does this.) +The caller must then once more use +.BR close () +to close the file descriptor, to avoid file descriptor leaks. +This divergence in implementation behaviors provides +a difficult hurdle for portable applications, since on many implementations, +.BR close () +must not be called again after an +.B EINTR +error, and on at least one, +.BR close () +must be called again. +There are plans to address this conundrum for +the next major release of the POSIX.1 standard. +.\" FIXME . for later review when Issue 8 is one day released... +.\" POSIX proposes further changes for EINTR +.\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 +.\" http://austingroupbugs.net/view.php?id=529 +.\" +.\" FIXME . +.\" Review the following glibc bug later +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=14627 +.SH SEE ALSO +.BR close_range (2), +.BR fcntl (2), +.BR fsync (2), +.BR open (2), +.BR shutdown (2), +.BR unlink (2), +.BR fclose (3) |