Bug 184755 - The vmstat(8) manualpage synopsis doesn't show all optional parameters
Summary: The vmstat(8) manualpage synopsis doesn't show all optional parameters
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: Normal Affects Only Me
Assignee: Benjamin Kaduk
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-12-13 18:00 UTC by pl
Modified: 2019-01-21 09:35 UTC (History)
3 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description pl 2013-12-13 18:00:00 UTC
The vmstat(8) manualpage shows the following synopsis:

     vmstat [-afHhimPsz] [-c count] [-M core [-N system]] [-w wait] [-n devs]
            [-p type,if,pass] [disks]

So it basically says that if you supply an optional parameter without specifying a specific option (-c, -M, etc.) then you're specifying the disk to display. We can see that this works as expected:

smtp2:/home/peter $ sysctl kern.disks
kern.disks: vtbd0
smtp2:/home/peter $ vmstat vtbd0
 procs      memory      page                   disk   faults         cpu
 r b w     avm    fre   flt  re  pi  po    fr  sr vt0   in   sy   cs us sy id
 0 0 0   4271M   399M   996   0   0   0  1096  24   0   22 1353  470  2  1 97

However, if you provide a numerical parameter which isn't a disk (GEOM?) then it will be used to provide a value for the -w option (-w: "Pause 'wait' seconds between each display"). As can be seen here:

smtp2:/home/peter $ time vmstat 2
 procs      memory      page                   disk   faults         cpu
 r b w     avm    fre   flt  re  pi  po    fr  sr vt0   in   sy   cs us sy id
 0 0 0   4351M   384M   996   0   0   0  1095  24   0   22 1352  470  2  1 97
 0 0 0   4351M   384M    16   0   0   0     0   0   0    4  263  253  0  0 100
 0 0 0   4351M   384M    16   0   0   0   148   0  40   26  224  453  0  1 99
^C    4.51s real     0.00s user     0.03s system

Better yet: even if you do specify a disk then you can also provide an extra numerical parameter which will then be used as the wait interval.

Fix: 

My suggestion would be to change the synopsis section of the vmstat(8) manualpage as follows:

SYNOPSIS
     vmstat [-afHhimPsz] [-c count] [-M core [-N system]] [-w wait] [-n devs]
            [-p type,if,pass] [disks] [interval]
How-To-Repeat: Start vmstat with a numerical parameter, either on its own or in addition to providing the disk to work on. It will continue to display values at an interval equal to the value of the numerical parameter.
Comment 1 Mark Linimon freebsd_committer freebsd_triage 2014-01-01 00:55:37 UTC
Responsible Changed
From-To: freebsd-bugs->freebsd-doc

reclassify.
Comment 2 commit-hook freebsd_committer freebsd_triage 2015-09-30 00:11:40 UTC
A commit references this bug:

Author: jhb
Date: Wed Sep 30 00:11:07 UTC 2015
New revision: 288407
URL: https://svnweb.freebsd.org/changeset/base/288407

Log:
  MFC 269727:
  Update vmstat usage for last-argument count/wait parameters

  Correct the usage in both the manpage and in usage() to indicate
  that the wait interval and repetition count may be given either
  with the respective -w/-c arguments, or as the final positional
  arguments. [0]

  The corresponding code to implement the positional arguments has
  been conditional on the (always-enabled) BACKWARD_COMPATIBILITY
  macro since the original 4.4-lite import.  It's no longer reasonable
  to remove the functionality, so remove the macro and conditional
  instead.

  Note that multiple disks may be given on the command line.

  While here, sort arguments and apply minor mdoc fixes.

  PR:		184755 [0]

Changes:
_U  stable/10/
  stable/10/usr.bin/vmstat/vmstat.8
  stable/10/usr.bin/vmstat/vmstat.c
Comment 3 Oleksandr Tymoshenko freebsd_committer freebsd_triage 2019-01-21 09:35:02 UTC
There is a commit referencing this PR, but it's still not closed and has been inactive for some time. Closing the PR as fixed but feel free to re-open it if the issue hasn't been completely resolved.

Thanks