docs/162438: du(1) man page improvements

Thu Nov 10 21:30:11 UTC 2011

The following reply was made to PR docs/162438; it has been noted by GNATS.

From: Alexander Best <arundel at freebsd.org>
To: Benjamin Kaduk <kaduk at mit.edu>
Cc: freebsd-doc at freebsd.org, freebsd-gnats-submit at freebsd.org
Subject: Re: docs/162438: du(1) man page improvements
Date: Thu, 10 Nov 2011 21:27:24 +0000

 On Thu Nov 10 11, Benjamin Kaduk wrote:
 > On Thu, 10 Nov 2011, Alexander Best wrote:
 > 
 > >Patch attached with submission follows:
 > >
 > >diff --git a/usr.bin/du/du.1 b/usr.bin/du/du.1
 > >index ef8b5ac..960be23 100644
 > >--- a/usr.bin/du/du.1
 > >+++ b/usr.bin/du/du.1
 > >@@ -28,7 +28,7 @@
 > >.\"	@(#)du.1	8.2 (Berkeley) 4/1/94
 > >.\" $FreeBSD$
 > >.\"
 > >-.Dd November 6, 2008
 > >+.Dd November 10, 2011
 > >.Dt DU 1
 > >.Os
 > >.Sh NAME
 > >@@ -36,15 +36,12 @@
 > >.Nd display disk usage statistics
 > >.Sh SYNOPSIS
 > >.Nm
 > >-.Op Fl A
 > >+.Op Fl Achklmnx
 > >.Op Fl H | L | P
 > >-.Op Fl a | s | d Ar depth | Fl t Ar threshold
 > >-.Op Fl c
 > >-.Op Fl l
 > >-.Op Fl h | k | m | B Ar blocksize
 > >-.Op Fl n
 > >-.Op Fl x
 > >+.Op Fl a | s | d Ar depth
 > >+.Op Fl B Ar blocksize
 > >.Op Fl I Ar mask
 > >+.Op Fl t Ar threshold
 > >.Op Ar
 > >.Sh DESCRIPTION
 > >The
 > >@@ -61,11 +58,13 @@ The options are as follows:
 > >Display the apparent size instead of the disk usage.
 > >This can be helpful when operating on compressed volumes or sparse files.
 > >.It Fl B Ar blocksize
 > >-Calculate block counts in
 > >+Calculate block count in
 > 
 > I think this is incorrect.  Block counts are computed for all path 
 > arguments given to du(1).  (Even if it was just "block count", it would 
 > need to be "the block count".)
 > 
 > >.Ar blocksize
 > >byte blocks.
 > >This is different from the
 > >-.Fl k, m
 > >+.Fl h, k
 > >+and
 > >+.Fl  m
 > >options or setting
 > >.Ev BLOCKSIZE
 > >and gives an estimate of how much space the examined file hierarchy would
 > >@@ -79,20 +78,45 @@ is rounded up to the next multiple of 512.
 > >.It Fl H
 > >Symbolic links on the command line are followed, symbolic links in file
 > >hierarchies are not followed.
 > >-.It Fl L
 > >-Symbolic links on the command line and in file hierarchies are followed.
 > >.It Fl I Ar mask
 > >Ignore files and directories matching the specified
 > >.Ar mask .
 > >+.It Fl L
 > >+Symbolic links on the command line and in file hierarchies are followed.
 > >.It Fl P
 > >No symbolic links are followed.
 > >This is the default.
 > >.It Fl a
 > >Display an entry for each file in a file hierarchy.
 > >+.It Fl c
 > >+Display a grand total.
 > >+.It Fl d Ar depth
 > >+Display an entry for all files and directories
 > >+.Ar depth
 > >+directories deep.
 > >.It Fl h
 > >"Human-readable" output.
 > >Use unit suffixes: Byte, Kilobyte, Megabyte,
 > >Gigabyte, Terabyte and Petabyte.
 > >+.It Fl k
 > >+Display block count in 1024-byte (1-Kbyte) blocks.
 > 
 > Likewise here.
 > 
 > >+.It Fl l
 > >+If a file has multiple hard links, count its size many times.
 > 
 > I would probably s/many/multiple/ to make the parallelism clear.
 > 
 > >+The default behavior of
 > >+.Nm
 > >+is to count files with multiple hard links only once.
 > >+When the
 > >+.Fl l
 > >+option is specified, the hard link checks are disabled, and these files
 > >+are counted (and displayed) as many times as they are found.
 > 
 > Could use .Pq, I suppose.
 > 
 > >+.It Fl m
 > >+Display block count in 1048576-byte (1-Mbyte) blocks.
 > 
 > block counts, again.
 > (and .Pq)
 > 
 > (Is moving a block of text around in the same commit as changing it 
 > actually a good idea?)
 > 
 > >+.It Fl n
 > >+Ignore files and directories with user
 > >+.Dq nodump
 > >+flag
 > >+.Pq Dv UF_NODUMP
 > >+set.
 > >.It Fl r
 > >Generate messages about directories that cannot be read, files
 > >that cannot be opened, and so on.
 > [the block that got moved]
 > >@@ -152,26 +151,33 @@ If either the
 > >.Fl H
 > >or
 > >.Fl L
 > >-options are specified, storage used by any symbolic links which are
 > >-followed is not counted or displayed.
 > >+option is specified, storage used by any symbolic links which are
 > >+followed is not counted (or displayed).
 > >+.Pp
 > >+The
 > >+.Fl h, k
 > >+and
 > >+.Fl m
 > >+options all override each other; the last one specified determines
 > >+the block count used.
 > >.Sh ENVIRONMENT
 > >.Bl -tag -width BLOCKSIZE
 > >.It Ev BLOCKSIZE
 > >If the environment variable
 > >.Ev BLOCKSIZE
 > >is set, and the
 > >-.Fl k, m
 > >+.Fl h, k
 > >or
 > >-.Fl h
 > >-options are not specified, the block counts will be displayed in units of
 > >+.Fl m
 > >+options are not specified, the block count will be displayed in units of
 > 
 > counts again
 > 
 > 
 > Thanks for spotting the style issues.

 thanks for looking at my patch. i'll try to fix all those issues you mentioned
 and will submit a followup patch.

 cheers.
 alex

 > 
 > -Ben Kaduk
 > 
 > 
 > >that block size.
 > >If
 > >.Ev BLOCKSIZE
 > >is not set, and the
 > >-.Fl k, m
 > >+.Fl h, k
 > >or
 > >-.Fl h
 > >-options are not specified, the block counts will be displayed in 512-byte
 > >+.Fl m
 > >+options are not specified, the block count will be displayed in 512-byte
 > >blocks.
 > >.El
 > >.Sh SEE ALSO
 > >
 > >
 > >>Release-Note:
 > >>Audit-Trail:
 > >>Unformatted:
 > >_______________________________________________
 > >freebsd-doc at freebsd.org mailing list
 > >http://lists.freebsd.org/mailman/listinfo/freebsd-doc
 > >To unsubscribe, send any mail to "freebsd-doc-unsubscribe at freebsd.org"
 > >