close.2: Place discussion of error handling under a subheading in NOTES

No content changes.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/close.2 b/man2/close.2
index a568534d31231301ef286c7f91cef40f28e907c0..121ca8de87a81f67dd77eb993541c86be091903e 100644 (file)
--- a/man2/close.2
+++ b/man2/close.2
@@ -90,6 +90,37 @@ should not be retried after an error.
 POSIX.1-2001, POSIX.1-2008, 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.)
+.PP
+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.
+.PP
+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.
+.\"
+.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
@@ -200,35 +231,6 @@ the next major release of the POSIX.1 standard.
 .\" Review the following glibc bug later
 .\" https://sourceware.org/bugzilla/show_bug.cgi?id=14627
 
-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.)
-.PP
-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.
-.PP
-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.
 .SH SEE ALSO
 .BR fcntl (2),
 .BR fsync (2),