swapon: improve man page notes about holes

Signed-off-by: Karel Zak <kzak@redhat.com>

diff --git a/sys-utils/swapon.8 b/sys-utils/swapon.8
index 2aa6fe20e2f9e2203438227e43fe3ebf7b7977cb..cf66b01ca51b3c8ba9ca15e20de401885de1ba90 100644 (file)
--- a/sys-utils/swapon.8
+++ b/sys-utils/swapon.8
@@ -192,31 +192,47 @@ Be verbose.
 .BR \-V , " \-\-version"
 Display version information and exit.
 .SH NOTES
-You should not use
+You should not use swapon on a file with holes. This can be seen in the system
+log as
+.RS
+.sp
+.B "swapon: swapfile has holes."
+.sp
+.RE
+The swap file implementation in the kernel expecting to be able to write to the
+file directly, without the assistance of the file system. This is problem on
+preallocated files (e.g.
+.BR fallocate (1)
+) on filesystems like \fBXFS\fR or \fBext4\fR, and on copy-on-write file
+systems like \fBbtrfs\fR.
+.PP
+It is recommended to use
+. BR dd (1)
+and
+.I /dev/zero
+to avoid holes on XFS and ext4.
+.PP
 .B swapon
-on a file with holes.
-Swap over NFS may not work.
+may not work correctly when using a swap file with some versions of
+\fBbtrfs\fR.  This is due to Since btrfs is a copy-on-write file system, the
+file location may not be static and corruption can result.  Btrfs actively
+disallows the use of files on its file systems by refusing to map the file.
+.PP
+One possible workaround is to map the
+file to a loopback device.  This will allow the file system to determine the
+mapping properly but may come with a performance impact.
+.PP
+Swap over \fBNFS\fR may not work.
 .PP
 .B swapon
 automatically detects and rewrites swap space signature with old software
 suspend data (e.g S1SUSPEND, S2SUSPEND, ...). The problem is that if we don't
 do it, then we get data corruption the next time an attempt at unsuspending is
 made.
-.PP
-.B swapon
-may not work correctly when using a swap file with some versions of btrfs.
-This is due to the swap file implementation in the kernel expecting to be able
-to write to the file directly, without the assistance of the file system.
-Since btrfs is a copy-on-write file system, the file location may not be
-static and corruption can result.  Btrfs actively disallows the use of files
-on its file systems by refusing to map the file.  This can be seen in the system
-log as "swapon: swapfile has holes."  One possible workaround is to map the
-file to a loopback device.  This will allow the file system to determine the
-mapping properly but may come with a performance impact.
 
 .SH ENVIRONMENT
-.IP LIBMOUNT_DEBUG=0xffff
-enables debug output.
+.IP LIBMOUNT_DEBUG=all
+enables libmount debug output.
 
 .SH SEE ALSO
 .BR swapon (2),