Adding upstream version 6.8.upstream/6.8upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)