diff options
Diffstat (limited to '')
| -rw-r--r-- | man2/close.2 | 44 |
1 files changed, 26 insertions, 18 deletions
diff --git a/man2/close.2 b/man2/close.2 index 239979b..c653acb 100644 --- a/man2/close.2 +++ b/man2/close.2 @@ -13,7 +13,7 @@ .\" 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-03-30 "Linux man-pages 6.05.01" +.TH close 2 2023-10-31 "Linux man-pages 6.7" .SH NAME close \- close a file descriptor .SH LIBRARY @@ -22,7 +22,7 @@ Standard C library .SH SYNOPSIS .nf .B #include <unistd.h> -.PP +.P .BI "int close(int " fd ); .fi .SH DESCRIPTION @@ -32,9 +32,15 @@ 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). -.PP +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 @@ -68,7 +74,9 @@ call was interrupted by a signal; see .B EIO An I/O error occurred. .TP -.BR ENOSPC ", " EDQUOT +.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 @@ -76,7 +84,7 @@ subsequent .BR fsync (2), or .BR close (). -.PP +.P See NOTES for a discussion of why .BR close () should not be retried after an error. @@ -93,7 +101,7 @@ 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.) -.PP +.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); @@ -116,7 +124,7 @@ that may cause unintended side effects. .\" 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. -.PP +.P Furthermore, consider the following scenario where two threads are performing operations on the same file descriptor: .IP (1) 5 @@ -128,11 +136,11 @@ to a pipe that is already full, or trying to from a stream socket which currently has no available data. .IP (2) Another thread closes the file descriptor. -.PP +.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. -.PP +.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 @@ -158,13 +166,13 @@ 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. -.PP +.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). -.PP +.P Retrying the .BR close () after a failure return is the wrong thing to do, @@ -185,7 +193,7 @@ 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. -.PP +.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. @@ -198,19 +206,19 @@ 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. -.PP +.P A careful programmer who wants to know about I/O errors may precede .BR close () with a call to .BR fsync (2). -.PP +.P The .B EINTR error is a somewhat special case. Regarding the .B EINTR error, POSIX.1-2008 says: -.PP +.P .RS If .BR close () @@ -222,7 +230,7 @@ and the state of .I fildes is unspecified. .RE -.PP +.P This permits the behavior that occurs on Linux and many other implementations, where, as with other errors that may be reported by |