From 92157c840c37532358aeda4667a1e07bd1f97cef Mon Sep 17 00:00:00 2001 From: Cameron Harr Date: Tue, 20 May 2025 14:54:58 -0700 Subject: [PATCH] Refactor man page and CLI help output per mandoc The man page and the usage statement from the CLI have been refactored to abide by the ManDoc standard. Style changes include: * Upper-case letters before lower-case * List short options w/o arguments first * Then list short options w/ arguments * Then list long arguments Reviewed-by: Brian Behlendorf Signed-off-by: Cameron Harr Closes #17357 --- cmd/zpool/zpool_main.c | 20 +++++++++--------- man/man8/zpool-status.8 | 46 ++++++++++++++++++++--------------------- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/cmd/zpool/zpool_main.c b/cmd/zpool/zpool_main.c index aaf4a352b..d45900246 100644 --- a/cmd/zpool/zpool_main.c +++ b/cmd/zpool/zpool_main.c @@ -521,11 +521,11 @@ get_usage(zpool_help_t idx) return (gettext("\ttrim [-dw] [-r ] [-c | -s] " "[ ...]\n")); case HELP_STATUS: - return (gettext("\tstatus [-c script1[,script2,...]] " - "[-dDegiLpPstvx] ...\n" - "\t [-j [--json-int] [--json-flat-vdevs] " + return (gettext("\tstatus [-DdegiLPpstvx] " + "[-c script1[,script2,...]] ...\n" + "\t [-j|--json [--json-flat-vdevs] [--json-int] " "[--json-pool-key-guid]] ...\n" - "\t [--power] [-T d|u] [pool] [interval [count]]\n")); + "\t [-T d|u] [--power] [pool] [interval [count]]\n")); case HELP_UPGRADE: return (gettext("\tupgrade\n" "\tupgrade -v\n" @@ -10980,28 +10980,28 @@ status_callback(zpool_handle_t *zhp, void *data) } /* - * zpool status [-c [script1,script2,...]] [-dDegiLpPstvx] ... - * [-j [--json-int] [--json-flat-vdevs] ... + * zpool status [-dDegiLpPstvx] [-c [script1,script2,...]] ... + * [-j|--json [--json-flat-vdevs] [--json-int] ... * [--json-pool-key-guid]] [--power] [-T d|u] ... * [pool] [interval [count]] * * -c CMD For each vdev, run command CMD - * -d Display Direct I/O write verify errors * -D Display dedup status (undocumented) + * -d Display Direct I/O write verify errors * -e Display only unhealthy vdevs * -g Display guid for individual vdev name. * -i Display vdev initialization status. * -j [...] Display output in JSON format - * --json-int Display numbers in inteeger format instead of string * --json-flat-vdevs Display vdevs in flat hierarchy + * --json-int Display numbers in integer format instead of string * --json-pool-key-guid Use pool GUID as key for pool objects * -L Follow links when resolving vdev path name. - * -p Display values in parsable (exact) format. * -P Display full path for vdev name. + * -p Display values in parsable (exact) format. * --power Display vdev enclosure slot power status * -s Display slow IOs column. - * -t Display vdev TRIM status. * -T Display a timestamp in date(1) or Unix format + * -t Display vdev TRIM status. * -v Display complete error logs * -x Display only pools with potential problems * diff --git a/man/man8/zpool-status.8 b/man/man8/zpool-status.8 index ca489e7be..a7f3e0880 100644 --- a/man/man8/zpool-status.8 +++ b/man/man8/zpool-status.8 @@ -37,15 +37,15 @@ .Sh SYNOPSIS .Nm zpool .Cm status +.Op Fl DdegiLPpstvx .Op Fl c Ar script1 Ns Oo , Ns Ar script2 Ns ,… Oc -.Op Fl dDegiLpPstvx -.Oo Fl j -.Oo Ns Fl Fl json-int Oc -.Oo Ns Fl Fl json-flat-vdevs Oc -.Oo Ns Fl Fl json-pool-key-guid Oc +.Oo Fl j|--json +.Oo Ns Fl -json-flat-vdevs Oc +.Oo Ns Fl -json-int Oc +.Oo Ns Fl -json-pool-key-guid Oc .Oc -.Op Fl Fl power .Op Fl T Ar d|u +.Op Fl -power .Op Ar pool .Op Ar interval Op Ar count . @@ -74,6 +74,14 @@ See the option of .Nm zpool Cm iostat for complete details. +.It Fl D +Display a histogram of deduplication statistics, showing the allocated +.Pq physically present on disk +and referenced +.Pq logically referenced in the pool +block counts and sizes by reference count. +If repeated, (-DD), also shows statistics on how much of the DDT is resident +in the ARC. .It Fl d Display the number of Direct I/O read/write checksum verify errors that have occurred on a top-level VDEV. @@ -87,14 +95,6 @@ Direct I/O reads checksum verify errors can also occur if the contents of the buffer are being manipulated after the I/O has been issued and is in flight. In the case of Direct I/O read checksum verify errors, the I/O will be reissued through the ARC. -.It Fl D -Display a histogram of deduplication statistics, showing the allocated -.Pq physically present on disk -and referenced -.Pq logically referenced in the pool -block counts and sizes by reference count. -If repeated, (-DD), also shows statistics on how much of the DDT is resident -in the ARC. .It Fl e Only show unhealthy vdevs (not-ONLINE or with errors). .It Fl g @@ -103,16 +103,16 @@ These GUIDs can be used in place of device names for the zpool detach/offline/remove/replace commands. .It Fl i Display vdev initialization status. -.It Fl j , -json Oo Ns Fl Fl json-int Oc Oo Ns Fl Fl json-flat-vdevs Oc \ -Oo Ns Fl Fl json-pool-key-guid Oc +.It Fl j , -json Oo Ns Fl -json-flat-vdevs Oc Oo Ns Fl -json-int Oc \ +Oo Ns Fl -json-pool-key-guid Oc Display the status for ZFS pools in JSON format. Specify -.Sy --json-int -to display numbers in integer format instead of strings. -Specify .Sy --json-flat-vdevs to display vdevs in flat hierarchy instead of nested vdev objects. Specify +.Sy --json-int +to display numbers in integer format instead of strings. +Specify .Sy --json-pool-key-guid to set pool GUID as key for pool objects instead of pool names. .It Fl L @@ -120,14 +120,14 @@ Display real paths for vdevs resolving all symbolic links. This can be used to look up the current block device name regardless of the .Pa /dev/disk/ path used to open it. -.It Fl p -Display numbers in parsable (exact) values. .It Fl P Display full paths for vdevs instead of only the last component of the path. This can be used in conjunction with the .Fl L flag. +.It Fl p +Display numbers in parsable (exact) values. .It Fl -power Display vdev enclosure slot power status (on or off). .It Fl s @@ -140,8 +140,6 @@ This does not necessarily mean the I/O operations failed to complete, just took an unreasonably long amount of time. This may indicate a problem with the underlying storage. -.It Fl t -Display vdev TRIM status. .It Fl T Sy d Ns | Ns Sy u Display a time stamp. Specify @@ -154,6 +152,8 @@ Specify for a printed representation of the internal representation of time. See .Xr time 1 . +.It Fl t +Display vdev TRIM status. .It Fl v Displays verbose data error information, printing out a complete list of all data errors since the last complete pool scrub.