zfs(8): improve document of compression behaviours

Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Reviewed-by: George Melikov <mail@gmelikov.ru>
Reviewed by: Allan Jude <allanjude@freebsd.org>
Reviewed-by: bunder2015 <omfgbunder@gmail.com>
Signed-off-by: DHE <git@dehacked.net>
Closes #4660
Closes #8423

diff --git a/man/man8/zfs.8 b/man/man8/zfs.8
index c4c172155ae2c36fe47052c8daab8699210c9115..4cabf23ba88dfa1c06ff53aedcedfca56af88351 100644 (file)
--- a/man/man8/zfs.8
+++ b/man/man8/zfs.8
@@ -1275,6 +1275,19 @@ compression algorithm compresses runs of zeros.
 This property can also be referred to by its shortened column name
 .Sy compress .
 Changing this property affects only newly-written data.
+.Pp
+When any setting except
+.Sy off
+is selected, compression will explicitly check for blocks consisting of only
+zeroes (the NUL byte).  When a zero-filled block is detected, it is stored as
+a hole and not compressed using the indicated compression algorithm.
+.Pp
+Any block being compressed must be no larger than 7/8 of its original size
+after compression, otherwise the compression will not be considered worthwhile
+and the block saved uncompressed. Note that when the logical block is less than
+8 times the disk sector size this effectively reduces the necessary compression
+ratio; for example 8k blocks on disks with 4k disk sectors must compress to 1/2
+or less of their original size.
 .It Xo
 .Sy context Ns = Ns Sy none Ns | Ns
 .Em SELinux_User:SElinux_Role:Selinux_Type:Sensitivity_Level