From nobody Sun Dec 17 14:52:30 2023 X-Original-To: dev-commits-src-branches@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4StQsq2R0Gz53l09; Sun, 17 Dec 2023 14:52:31 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4StQsq15zDz3G0g; Sun, 17 Dec 2023 14:52:31 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1702824751; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=K9HVPCYzx+CZ3kPIY1xSc5KgClSZbqA9Co1m/KpjU08=; b=djZHoL2Zhn+ELg1Br50v5yd1TNlCGBkzmGGxhdTeW1PYl1XYm4oa5nhYzzEz9LtAkCfFRW rWOQcAsW8zZsxV/5BDDuvYAGtJnax42mTLdfkWUejOGtVvU8nX9rzXs8EZ5rtwd51t5gam kZAPyIn1rNw/z19yQju5puwEk+K3bEDQXNT+PjRtI5sa1WMB55990MRkkzv1UyhlYj++u4 BIQdpWrUFsVkfsDCmgHYL63f2X7A4kep0icyNS63AFI/gK0U5ql4fOed5yH8OqN7WpfAoV P1j6/Hxa7gMcGCqcWHksc3hJgdgniCfyuglMpl8FOIwFVqvJMzAnUibVRa/c4g== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1702824751; a=rsa-sha256; cv=none; b=V6LX+1YuNBdwt+2JLy3meC/Qza5rnWwZXa00bdhti/YI4Whrt0bDRVvjR+LaGSQDP95RvX 7mgLq1datRhMYrO6uQBRCoBS1GI+xflg6uM/8Rll+K47evYNy3Ek+WHBG1UVaaDvJRBDzL Qc63uZ+v8N+kMq+lskWCB28Dkv56rKc3h6rklyN4NPZ7AD8uUK9CLWjF5XDf8e4bQoqz6A D0PpVKVbGbqn/eWLunQg69aeavnF+MR+wJHbJGKGOEdMLDlMhHCyX9eoc/lvW2eausZqb3 v3satmfMA7WxXTi6oTo0SqbKtNnd1aZkRbW4gXTEckYSUflle/GUJ5L8M1IG2w== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1702824751; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=K9HVPCYzx+CZ3kPIY1xSc5KgClSZbqA9Co1m/KpjU08=; b=R7VEymgVob4tAASWpEz3LxDNQ06bRgP7KCDBkhoIrJg0mZSAfipi3YXZ1fiR01waMkrkyF xK4Y1WqEB/Z2aNouCY16jE99eqXgD0Ua6VpMLFxSn/ktGVIk5Ff6X3EaJJHZGOvVFSsJEn 9TgqqHfPw6IIEHwwr+SGAT0+xP+UNRI4M8W2pbNF2EKBFvTM51qqWJk0/ceXh8QBEX0O/9 mPkJ1k+PJFuyP12nI+o8+JajA6IL7gekBjjBvOSN76SI2RNyWheP6Y+//gr87ie86H8tcP L3KpVpw4QrOWGZG9jPgGccYKpXi55C58PDOiFXeXC/3IcpEChwY25i1aJUoUHQ== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4StQsq08KDzj1g; Sun, 17 Dec 2023 14:52:31 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.17.1/8.17.1) with ESMTP id 3BHEqUSN038621; Sun, 17 Dec 2023 14:52:30 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.17.1/8.17.1/Submit) id 3BHEqUkL038618; Sun, 17 Dec 2023 14:52:30 GMT (envelope-from git) Date: Sun, 17 Dec 2023 14:52:30 GMT Message-Id: <202312171452.3BHEqUkL038618@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Gordon Bergling Subject: git: f5f993f6c913 - stable/13 - iostat.8: Better wording for some use cases List-Id: Commits to the stable branches of the FreeBSD src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-branches List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-branches@freebsd.org X-BeenThere: dev-commits-src-branches@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: gbe X-Git-Repository: src X-Git-Refname: refs/heads/stable/13 X-Git-Reftype: branch X-Git-Commit: f5f993f6c9134530fbeac712589b3a6363a37286 Auto-Submitted: auto-generated The branch stable/13 has been updated by gbe: URL: https://cgit.FreeBSD.org/src/commit/?id=f5f993f6c9134530fbeac712589b3a6363a37286 commit f5f993f6c9134530fbeac712589b3a6363a37286 Author: Gordon Bergling AuthorDate: 2023-11-26 18:30:58 +0000 Commit: Gordon Bergling CommitDate: 2023-12-17 14:52:21 +0000 iostat.8: Better wording for some use cases The iostat(8) manual page should be more specific when using options. Also extented the BUGS section. PR: 153012 Reviewed by: bcr Differential Revision: https://reviews.freebsd.org/D42633 (cherry picked from commit 502e8f44fcc18bfc6dadca56801d66cbce4c07ec) --- usr.sbin/iostat/iostat.8 | 64 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 46 insertions(+), 18 deletions(-) diff --git a/usr.sbin/iostat/iostat.8 b/usr.sbin/iostat/iostat.8 index 863f8ab8466c..ebeea17fa037 100644 --- a/usr.sbin/iostat/iostat.8 +++ b/usr.sbin/iostat/iostat.8 @@ -54,7 +54,7 @@ .\" .\" @(#)iostat.8 8.1 (Berkeley) 6/6/93 .\" -.Dd August 29, 2023 +.Dd November 26, 2023 .Dt IOSTAT 8 .Os .Sh NAME @@ -83,7 +83,12 @@ The utility displays kernel .Tn I/O statistics on terminal, device and cpu operations. -The first statistics that are printed are averaged over the system uptime. +The first statistics that are printed are averaged over the system uptime +(unless +.Fl I +is specified). +Any references to repetitions in this man page implicitly include the first +statistics output. To get information about the current activity, a suitable wait time should be specified, so that the subsequent sets of printed statistics will be averaged over that time. @@ -101,14 +106,11 @@ is specified. Repeat the display .Ar count times. -If no repeat -.Ar count -is specified, the default depends on whether -.Fl w -is specified. -With -.Fl w -the default repeat count is infinity, otherwise it is 1. +If +.Fl c +is not specified and a wait interval is specified, +the default repeat count is infinity. +If no wait interval is specified, the default repeat count is 1. .It Fl d Display only device statistics. If this flag is turned on, only device statistics will be displayed, unless @@ -130,8 +132,11 @@ per measurement cycle. Display total statistics for a given time period, rather than average statistics for each second during that time period. .It Fl K -In the blocks transferred display (-o), display block count in kilobytes rather -then the device native block size. +In the old-style blocks transferred display +.Po Fl I +and +.Fl o Pc , +display block count in kilobytes rather than the device native block size. .It Fl M Extract values associated with the name list from the specified core instead of the default @@ -145,7 +150,7 @@ Display up to number of devices. The .Nm -utility will display fewer devices if there are not +utility will display fewer devices if there are less than .Ar devs devices present. .It Fl o @@ -220,7 +225,7 @@ Passthrough devices The user must specify at least one device type, and may specify at most one device type from each category. Multiple device types in a single device type statement must be separated by -commas. +commas and are ANDed together. .Pp Any number of .Fl t @@ -234,14 +239,16 @@ Any device that fully matches any argument will be included in the .Nm output, up to the number of devices that can be displayed in -80 columns, or the maximum number of devices specified by the user. +80 columns, or the maximum number of devices +.Pq Fl n +specified by the user. .It Fl w Pause .Ar wait seconds between each display. -If no -.Ar wait -interval is specified, the default is 1 second. +If +.Fl w +is not specified, the default interval is 1 second. .Pp The .Nm @@ -516,3 +523,24 @@ The use of as a debugging tool for crash dumps is probably limited because there is currently no way to get statistics that only cover the time immediately before the crash. +.Pp +Each +.Ar drives +argument is passed to +.Fn isdigit . +If +.Fn isdigit +returns true, +.Nm +switches into an undocumented traditional syntax and subsequent arguments, +if any, will not be interpreted as drive names. +This behavior collides with the one documented in this man page and prevents +specifying drive names starting with a number. +E.g., the following +.Bd -literal -offset indent +iostat ada0 ada1 2 3 cd0 +.Ed +.Pp +This document's use of +.Dq device type +is misleading.