bin/184755: The vmstat manualpage synopsis doesn't show all optional parameters

[ShelLuser]

>Number:         184755
>Category:       bin
>Synopsis:       The vmstat manualpage synopsis doesn't show all optional parameters
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-bugs
>State:          open
>Quarter:        
>Keywords:       
>Date-Required:
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Dec 13 18:00:00 UTC 2013
>Closed-Date:
>Last-Modified:
>Originator:     ShelLuser
>Release:        9.2-p2
>Organization:
>Environment:
FreeBSD smtp2.losoco.com 9.2-RELEASE-p2 FreeBSD 9.2-RELEASE-p2 #2 r258858: Wed Dec  4 23:53:05 CET 2013     peter at smtp2.losoco.com:/usr/obj/usr/src92/sys/SECKERNEL  amd64

>Description:
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.

>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.
>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]


>Release-Note:
>Audit-Trail:
>Unformatted: