arcstat.1: modernise

Also slim down the description a tad

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Ahelenia Ziemiańska <[email protected]>
Closes #12125

1 files changed, 111 insertions, 539 deletions

diff --git a/man/man1/arcstat.1 b/man/man1/arcstat.1
index de63206e2..a0240e40e 100644
--- a/man/man1/arcstat.1
+++ b/man/man1/arcstat.1
@@ -8,603 +8,175 @@
 .\" source.  A copy of the CDDL is also available via the Internet at
 .\" http://www.illumos.org/license/CDDL.
 .\"
-.\"
 .\" Copyright 2014 Adam Stevko.  All rights reserved.
 .\" Copyright (c) 2015 by Delphix. All rights reserved.
 .\" Copyright (c) 2020 by AJ Jordan. All rights reserved.
 .\"
-.TH ARCSTAT 1 "Oct 20, 2020" OpenZFS
-.SH NAME
-arcstat \- report ZFS ARC and L2ARC statistics
-.SH SYNOPSIS
-.LP
-.nf
-\fBarcstat\fR [\fB-havxp\fR] [\fB-f field[,field]...\fR] [\fB-o file\fR] [\fB-s string\fR] [\fBinterval\fR [\fBcount\fR]]
-.fi
-
-.SH DESCRIPTION
-.LP
-The \fBarcstat\fR utility print various ZFS ARC and L2ARC statistics in
-vmstat-like fashion.
-.sp
-
-.sp
-.LP
-The \fBarcstat\fR command reports the following information:
-.sp
-.ne 2
-
-.\"
-.sp
-.ne 1
-.na
-\fBc \fR
-.ad
-.RS 14n
+.Dd May 26, 2021
+.Dt ARCSTAT 1
+.Os
+.
+.Sh NAME
+.Nm arcstat
+.Nd report ZFS ARC and L2ARC statistics
+.Sh SYNOPSIS
+.Nm
+.Op Fl havxp
+.Op Fl f Ar field Ns Op , Ns Ar field Ns ...
+.Op Fl o Ar file
+.Op Fl s Ar string
+.Op Ar interval
+.Op Ar count
+.
+.Sh DESCRIPTION
+.Nm
+prints various ZFS ARC and L2ARC statistics in vmstat-like fashion:
+.Bl -tag -width "l2asize"
+.It Sy c
 ARC target size
-.RE
-
-.sp
-.ne 2
-.na
-\fBdh% \fR
-.ad
-.RS 14n
+.It Sy dh%
 Demand data hit percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBdm% \fR
-.ad
-.RS 14n
+.It Sy dm%
 Demand data miss percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBmfu \fR
-.ad
-.RS 14n
+.It Sy mfu
 MFU list hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBmh% \fR
-.ad
-.RS 14n
+.It Sy mh%
 Metadata hit percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBmm% \fR
-.ad
-.RS 14n
+.It Sy mm%
 Metadata miss percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBmru \fR
-.ad
-.RS 14n
+.It Sy mru
 MRU list hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBph% \fR
-.ad
-.RS 14n
+.It Sy ph%
 Prefetch hits percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBpm% \fR
-.ad
-.RS 14n
+.It Sy pm%
 Prefetch miss percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBdhit \fR
-.ad
-.RS 14n
+.It Sy dhit
 Demand data hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBdmis \fR
-.ad
-.RS 14n
+.It Sy dmis
 Demand data misses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBhit% \fR
-.ad
-.RS 14n
+.It Sy hit%
 ARC hit percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBhits \fR
-.ad
-.RS 14n
+.It Sy hits
 ARC reads per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBmfug \fR
-.ad
-.RS 14n
+.It Sy mfug
 MFU ghost list hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBmhit \fR
-.ad
-.RS 14n
+.It Sy mhit
 Metadata hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBmiss \fR
-.ad
-.RS 14n
+.It Sy miss
 ARC misses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBmmis \fR
-.ad
-.RS 14n
+.It Sy mmis
 Metadata misses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBmrug \fR
-.ad
-.RS 14n
+.It Sy mrug
 MRU ghost list hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBphit \fR
-.ad
-.RS 14n
+.It Sy phit
 Prefetch hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBpmis \fR
-.ad
-.RS 14n
+.It Sy pmis
 Prefetch misses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBread \fR
-.ad
-.RS 14n
+.It Sy read
 Total ARC accesses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBtime \fR
-.ad
-.RS 14n
-Time
-.RE
-
-.sp
-.ne 2
-.na
-\fBsize \fR
-.ad
-.RS 14n
+.It Sy time
+Current time
+.It Sy size
 ARC size
-.RE
-
-.sp
-.ne 2
-.na
-\fBarcsz \fR
-.ad
-.RS 14n
-Alias for \fBsize\fR
-.RE
-
-.sp
-.ne 2
-.na
-\fBdread \fR
-.ad
-.RS 14n
+.It Sy arcsz
+Alias for
+.Sy size
+.It Sy dread
 Demand data accesses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBeskip \fR
-.ad
-.RS 14n
+.It Sy eskip
 evict_skip per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBmiss% \fR
-.ad
-.RS 14n
+.It Sy miss%
 ARC miss percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBmread \fR
-.ad
-.RS 14n
+.It Sy mread
 Metadata accesses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBpread \fR
-.ad
-.RS 14n
+.It Sy pread
 Prefetch accesses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2hit% \fR
-.ad
-.RS 14n
+.It Sy l2hit%
 L2ARC access hit percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2hits \fR
-.ad
-.RS 14n
+.It Sy l2hits
 L2ARC hits per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2miss \fR
-.ad
-.RS 14n
+.It Sy l2miss
 L2ARC misses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2read \fR
-.ad
-.RS 14n
+.It Sy l2read
 Total L2ARC accesses per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2pref \fR
-.ad
-.RS 14n
+.It Sy l2pref
 L2ARC prefetch allocated size per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2pref% \fR
-.ad
-.RS 14n
+.It Sy l2pref%
 L2ARC prefetch allocated size percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2mfu \fR
-.ad
-.RS 14n
+.It Sy l2mfu
 L2ARC MFU allocated size per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2mfu% \fR
-.ad
-.RS 14n
+.It Sy l2mfu%
 L2ARC MFU allocated size percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2mru \fR
-.ad
-.RS 14n
+.It Sy l2mru
 L2ARC MRU allocated size per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2mru% \fR
-.ad
-.RS 14n
+.It Sy l2mru%
 L2ARC MRU allocated size percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2data \fR
-.ad
-.RS 14n
+.It Sy l2data
 L2ARC data (buf content) allocated size per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2data% \fR
-.ad
-.RS 14n
+.It Sy l2data%
 L2ARC data (buf content) allocated size percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2meta \fR
-.ad
-.RS 14n
+.It Sy l2meta
 L2ARC metadata (buf content) allocated size per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2meta% \fR
-.ad
-.RS 14n
+.It Sy l2meta%
 L2ARC metadata (buf content) allocated size percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2size \fR
-.ad
-.RS 14n
+.It Sy l2size
 Size of the L2ARC
-.RE
-
-.sp
-.ne 2
-.na
-\fBmtxmis \fR
-.ad
-.RS 14n
+.It Sy mtxmis
 mutex_miss per second
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2bytes \fR
-.ad
-.RS 14n
+.It Sy l2bytes
 Bytes read per second from the L2ARC
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2miss% \fR
-.ad
-.RS 14n
+.It Sy l2miss%
 L2ARC access miss percentage
-.RE
-
-.sp
-.ne 2
-.na
-\fBl2asize \fR
-.ad
-.RS 14n
+.It Sy l2asize
 Actual (compressed) size of the L2ARC
-.RE
-
-.sp
-.ne 2
-.na
-\fBgrow \fR
-.ad
-.RS 14n
+.It Sy grow
 ARC grow disabled
-.RE
-
-.sp
-.ne 2
-.na
-\fBneed \fR
-.ad
-.RS 14n
+.It Sy need
 ARC reclaim needed
-.RE
-
-.sp
-.ne 2
-.na
-\fBfree \fR
-.ad
-.RS 14n
+.It Sy free
 The ARC's idea of how much free memory there is, which includes evictable memory in the page cache.
-Since the ARC tries to keep \fBavail\fR above zero, \fBavail\fR is usually more instructive to observe than \fBfree\fR.
-.RE
-
-.sp
-.ne 2
-.na
-\fBavail \fR
-.ad
-.RS 14n
-The ARC's idea of how much free memory is available to it, which is a bit less than \fBfree\fR.
-May temporarily be negative, in which case the ARC will reduce the target size \fBc\fR.
-.RE
-.\"
-
-.SH OPTIONS
-.LP
-The following options are supported:
-
-.sp
-.ne 2
-.na
-\fB\fB-a\fR\fR
-.ad
-.RS 12n
+Since the ARC tries to keep
+.Sy avail
+above zero,
+.Sy avail
+is usually more instructive to observe than
+.Sy free .
+.It Sy avail
+The ARC's idea of how much free memory is available to it, which is a bit less than
+.Sy free .
+May temporarily be negative, in which case the ARC will reduce the target size
+.Sy c .
+.El
+.
+.Sh OPTIONS
+.Bl -tag -width "-v"
+.It Fl a
 Print all possible stats.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB-f\fR\fR
-.ad
-.RS 12n
-Display only specific fields. See \fBDESCRIPTION\fR for supported statistics.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB-h\fR\fR
-.ad
-.RS 12n
+.It Fl f
+Display only specific fields.
+See
+.Sy DESCRIPTION
+for supported statistics.
+.It Fl h
 Display help message.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB-o\fR\fR
-.ad
-.RS 12n
+.It Fl o
 Report statistics to a file instead of the standard output.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB-p\fR\fR
-.ad
-.RS 12n
+.It Fl p
 Disable auto-scaling of numerical fields (for raw, machine-parsable values).
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB-s\fR\fR
-.ad
-.RS 12n
+.It Fl s
 Display data with a specified separator (default: 2 spaces).
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB-x\fR\fR
-.ad
-.RS 12n
-Print extended stats (same as -f time,mfu,mru,mfug,mrug,eskip,mtxmis,dread,pread,read).
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fB-v\fR\fR
-.ad
-.RS 12n
+.It Fl x
+Print extended stats (same as
+.Fl f Ar time,mfu,mru,mfug,mrug,eskip,mtxmis,dread,pread,read Ns No ).
+.It Fl v
 Show field headers and definitions
-.RE
-
-.SH OPERANDS
-.LP
+.El
+.
+.Sh OPERANDS
 The following operands are supported:
-.sp
-.ne 2
-.na
-\fB\fIcount\fR\fR
-.ad
-.RS 12n
-Display only \fIcount\fR reports.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fIinterval\fR\fR
-.ad
-.RS 12n
+.Bl -tag -width "interval"
+.It Ar interval
 Specify the sampling interval in seconds.
-.RE
-
-.SH AUTHORS
-.LP
-arcstat was originally written in Perl by Neelakanth Nadgir and supported only ZFS ARC statistics.
-Mike Harsch updated it to support L2ARC statistics.
-John Hixson ported it to Python for FreeNAS over some beer, after which many individuals from the OpenZFS community continued to maintain and improve it.
+.It Ar count
+Display only \fIcount\fR reports.
+.El