diff options
Diffstat (limited to 'man2/close.2')
| -rw-r--r-- | man2/close.2 | 274 |
1 files changed, 0 insertions, 274 deletions
diff --git a/man2/close.2 b/man2/close.2 deleted file mode 100644 index cc6d2f43e..000000000 --- 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 (date) "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) |