git: d1801babad49 - main - tarfs.5: Document the importance of zstd framing

From: Mark Johnston <markj_at_FreeBSD.org>
Date: Thu, 04 Apr 2024 14:58:54 UTC
The branch main has been updated by markj:

URL: https://cgit.FreeBSD.org/src/commit/?id=d1801babad495be2a3eb1d974e1daf9714c5b0fd

commit d1801babad495be2a3eb1d974e1daf9714c5b0fd
Author:     Mark Johnston <markj@FreeBSD.org>
AuthorDate: 2024-04-04 14:54:25 +0000
Commit:     Mark Johnston <markj@FreeBSD.org>
CommitDate: 2024-04-04 14:54:25 +0000

    tarfs.5: Document the importance of zstd framing
    
    Reviewed by:    des, kib
    MFC after:      1 week
    Sponsored by:   Klara, Inc.
    Differential Revision:  https://reviews.freebsd.org/D44628
---
 share/man/man5/tarfs.5 | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/share/man/man5/tarfs.5 b/share/man/man5/tarfs.5
index 29999b8066f7..5378491b9c9f 100644
--- a/share/man/man5/tarfs.5
+++ b/share/man/man5/tarfs.5
@@ -61,6 +61,19 @@ sysctl setting and tunable.
 Setting it to 0 will reset it to its default value.
 Note that changes to this setting only apply to filesystems mounted
 after the change.
+.Pp
+When the backing tar file is compressed with
+.Xr zstd 1 ,
+I/O performance can be improved by ensuring that compressed data is
+broken up into multiple frames.
+This helps minimize unnecessary decompression work.
+When using
+.Xr bsdtar 1
+to create the tar file, this can be achieved using the
+.Cm zstd:max-frame-size
+and
+.Cm ztsd:frame-per-file
+options.
 .Sh DIAGNOSTICS
 If enabled by the
 .Dv TARFS_DEBUG