summaryrefslogtreecommitdiffstats
path: root/man2/close.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/close.2')
-rw-r--r--man2/close.2274
1 files changed, 0 insertions, 274 deletions
diff --git a/man2/close.2 b/man2/close.2
deleted file mode 100644
index c653acb..0000000
--- a/man2/close.2
+++ /dev/null
@@ -1,274 +0,0 @@
-.\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)