Update man pages and clarify a number of options.

Rework block count calculations to work correctly with small "block" sizes.

MFC after:	14 days

1 files changed, 58 insertions, 29 deletions

diff --git a/bin/df/df.1 b/bin/df/df.1
index 02a4f421..f107ad3 100644
--- a/bin/df/df.1
+++ b/bin/df/df.1
@@ -29,7 +29,7 @@
 .\"     @(#)df.1	8.3 (Berkeley) 5/8/95
 .\" $FreeBSD$
 .\"
-.Dd March 3, 2012
+.Dd November 16, 2012
 .Dt DF 1
 .Os
 .Sh NAME
@@ -50,7 +50,8 @@ displays statistics about the amount of free disk space on the specified
 or on the file system of which
 .Ar file
 is a part.
-Values are displayed in 512-byte per block counts.
+By default block counts are displayed with an assumed block size of
+512 bytes.
 If neither a file or a file system operand is specified,
 statistics for all mounted file systems are displayed
 (subject to the
@@ -65,46 +66,54 @@ Show all mount points, including those that were mounted with the
 flag.
 This is implied for file systems specified on the command line.
 .It Fl b
-Use 512-byte blocks rather than the default.
-This overrides the
+Explicitly use 512 byte blocks, overriding any
 .Ev BLOCKSIZE
 specification from the environment.
+This is the same as the
+.Fl P
+option.
+The
+.Fl k
+option overrides this option.
 .It Fl c
 Display a grand total.
 .It Fl g
-Use 1073741824-byte (1-Gbyte) blocks rather than the default.
-This overrides the
+Use 1073741824 byte (1 Gibibyte) blocks rather than the default.
+This overrides any
 .Ev BLOCKSIZE
 specification from the environment.
 .It Fl H
 .Dq Human-readable
 output.
-Use unit suffixes: Byte, Kilobyte, Megabyte,
-Gigabyte, Terabyte and Petabyte in order to reduce the number of
-digits to four or fewer using base 10 for sizes.
+Use unit suffixes: Byte, Kibibyte, Mebibyte, Gibibyte, Tebibyte and
+Pebibyte (based on powers of 1024) in order to reduce the number of
+digits to four or fewer.
 .It Fl h
 .Dq Human-readable
 output.
 Use unit suffixes: Byte, Kilobyte, Megabyte,
-Gigabyte, Terabyte and Petabyte in order to reduce the number of
-digits to four or fewer using base 2 for sizes.
-Inodes statistics, if enabled with
-.Fl i ,
-are always printed in base 10.
+Gigabyte, Terabyte and Petabyte (based on powers of 1000) in order to
+reduce the number of
+digits to four or fewer.
 .It Fl i
-Include statistics on the number of free inodes.
+Include statistics on the number of free and used inodes.
+In conjunction with the
+.Fl h
+or
+.Fl H
+options, the number of inodes is scaled by powers of 1000.
 .It Fl k
-Use 1024-byte (1-Kbyte) blocks rather than the default.
+Use 1024 byte (1 Kibibyte) blocks rather than the default.
 This overrides the
-.Ev BLOCKSIZE
-specification from the environment and the
 .Fl P
-option.
+option and any
+.Ev BLOCKSIZE
+specification from the environment.
 .It Fl l
 Only display information about locally-mounted file systems.
 .It Fl m
-Use 1048576-byte (1-Mbyte) blocks rather than the default.
-This overrides the
+Use 1048576 byte (1 Mebibyte) blocks rather than the default.
+This overrides any
 .Ev BLOCKSIZE
 specification from the environment.
 .It Fl n
@@ -117,10 +126,12 @@ When this option is specified,
 will not request new statistics from the file systems, but will respond
 with the possibly stale statistics that were previously obtained.
 .It Fl P
-Use POSIX compliant output of 512-byte blocks rather than the default.
-This overrides the
+Explicitly use 512 byte blocks, overriding any
 .Ev BLOCKSIZE
 specification from the environment.
+This is the same as the
+.Fl b
+option.
 The
 .Fl k
 option overrides this option.
@@ -160,9 +171,18 @@ option has no effect.
 .Sh ENVIRONMENT
 .Bl -tag -width BLOCKSIZE
 .It Ev BLOCKSIZE
-If the environment variable
-.Ev BLOCKSIZE
-is set, the block counts will be displayed in units of that size block.
+Specifies the units in which to report block counts.
+This uses
+.Xr getbsize 3 ,
+which allows units of bytes or numbers scaled with the letters
+.Em k
+(for multiples of 1024 bytes),
+.Em m
+(for multiples of 1048576 bytes) or
+.Em g
+(for gibibytes).
+The allowed range is 512 bytes to 1 GB.
+If the value is outside, it will be set to the appropriate limit.
 .El
 .Sh SEE ALSO
 .Xr lsvfs 1 ,
@@ -170,13 +190,12 @@ is set, the block counts will be displayed in units of that size block.
 .Xr fstatfs 2 ,
 .Xr getfsstat 2 ,
 .Xr statfs 2 ,
+.Xr getbsize 3 ,
 .Xr getmntinfo 3 ,
 .Xr localeconv 3 ,
 .Xr fstab 5 ,
 .Xr mount 8 ,
-.Xr pstat 8 ,
-.Xr quot 8 ,
-.Xr swapinfo 8
+.Xr quot 8 .
 .Sh STANDARDS
 With the exception of most options,
 the
@@ -200,3 +219,13 @@ flag is ignored if a file or file system is specified.
 Also, if a mount
 point is not accessible by the user, it is possible that the file system
 information could be stale.
+.Pp
+The
+.Fl b
+and
+.Fl P
+options are identical.
+The former comes from the BSD tradition, and the latter is required
+for
+.St -p1003.1-2004
+conformity.