Bug 221795 - zpool list property documentation doesn't match actual behaviour
Summary: zpool list property documentation doesn't match actual behaviour
Status: New
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2017-08-25 11:12 UTC by Norman Gray
Modified: 2018-07-13 19:53 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Norman Gray 2017-08-25 11:12:00 UTC
The `zpool list` section of the zpool(8) manpage says that the default list of displayed properties is as below:

> The default list is name, size, used, available, fragmentation,
> expandsize, capacity, health, altroot.

This does not seem to be the case.  In fact:

    # zpool list
    NAME   SIZE  ALLOC   FREE  EXPANDSZ   FRAG    CAP  DEDUP  HEALTH  ALTROOT
    tank  10.9T  6.05T  4.83T         -    29%    55%  1.00x  ONLINE  -

The Properties section of the same manpage includes the `used` property, but this seems not to be recognised:

    # zpool list -o used
    bad property list: invalid property 'used'
    usage:
    [...]
    #

The usage message produced here indeed doesn't include `used`.

This is:

    # uname -r
    11.1-RELEASE-p1
Comment 1 Yuri Pankov 2017-12-06 06:53:51 UTC
Reported upstream: https://www.illumos.org/issues/8899
Comment 2 Andrew Daugherity 2018-07-13 19:51:14 UTC
That upstream bug is now fixed and should be merged into all supported FreeBSD versions (the property name change was apparently imported back in 10.0):
https://github.com/illumos/illumos-gate/commit/b0e142e57dfda6f02bf1fa66973c610f5fefe8cb

There is an additional recent upstream commit [f41179bd376293096297cdc1f32e610d44f65c8b] which adds the "checkpoint" property to the default property list, which applies to FreeBSD 11.2+.  This change (but not the "used, avail" => "alloc, free" change) *has* been fixed in FreeBSD current r333081, but has not been MFC into stable/11 yet, let along releng/11.2.
Comment 3 Andrew Daugherity 2018-07-13 19:53:10 UTC
Also, the "[-T d|u]" option to "zpool list" is described twice for some reason, both at the beginning and the end of the option descriptions.  svn blame shows that r228019 added it to the end of the option descriptions, and then r263459 added it to the beginning (while keeping the copy at the end).

I don't know the preferred FreeBSD style for option ordering, but the upstream man page <https://illumos.org/man/1m/zpool> puts the -T option description in alphabetical order, between -p and -v.