docs/162438: du(1) man page improvements

Fri Nov 11 11:00:24 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: Fri, 11 Nov 2011 11:00:10 +0000

 --XsQoSWH+UP9D9v3l
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline

 here's another revised version of my patch. this now also includes changes
 to du.c:usage() to reflect the man page changes.

 cheers.
 alex

 --XsQoSWH+UP9D9v3l
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: attachment; filename="du.1.diff3"

 diff --git a/usr.bin/du/du.1 b/usr.bin/du/du.1
 index ef8b5ac..66bdefe 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 11, 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
 @@ -65,7 +62,9 @@ Calculate block counts in
  .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,48 +78,31 @@ 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 h
 -"Human-readable" output.
 -Use unit suffixes: Byte, Kilobyte, Megabyte,
 -Gigabyte, Terabyte and Petabyte.
 -.It Fl r
 -Generate messages about directories that cannot be read, files
 -that cannot be opened, and so on.
 -This is the default case.
 -This option exists solely for conformance with
 -.St -xpg4 .
 -.It Fl s
 -Display an entry for each specified file.
 -(Equivalent to
 -.Fl d Li 0 )
 -.It Fl t Ar threshold
 -Display only entries for which size exceeds
 -.Ar threshold .
 -If
 -.Ar threshold
 -is negative, display only entries for which size is less than the absolute
 -value of
 -.Ar threshold .
 +.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 c
 -Display a grand total.
 +.It Fl h
 +.Dq Human-readable
 +output.
 +Use unit suffixes: Byte, Kilobyte, Megabyte,
 +Gigabyte, Terabyte and Petabyte.
  .It Fl k
  Display block counts in 1024-byte (1-Kbyte) blocks.
  .It Fl l
 -If a file has multiple hard links, count its size many times.
 +If a file has multiple hard links, count its size multiple times.
  The default behavior of
  .Nm
  is to count files with multiple hard links only once.
 @@ -136,6 +118,24 @@ Ignore files and directories with user
  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.
 +This is the default case.
 +This option exists solely for conformance with
 +.St -xpg4 .
 +.It Fl s
 +Display an entry for each specified file.
 +(Equivalent to
 +.Fl d Li 0 )
 +.It Fl t Ar threshold
 +Display only entries for which size exceeds
 +.Ar threshold .
 +If
 +.Ar threshold
 +is negative, display only entries for which size is less than the absolute
 +value of
 +.Ar threshold .
  .It Fl x
  File system mount points are not traversed.
  .El
 @@ -152,25 +152,32 @@ 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 counts 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
 +.Fl m
  options are not specified, the block counts will be displayed in units of
  that block size.
  If
  .Ev BLOCKSIZE
  is not set, and the
 -.Fl k, m
 +.Fl h, k
  or
 -.Fl h
 +.Fl m
  options are not specified, the block counts will be displayed in 512-byte
  blocks.
  .El
 diff --git a/usr.bin/du/du.c b/usr.bin/du/du.c
 index 5c670d4..2dfd05b 100644
 --- a/usr.bin/du/du.c
 +++ b/usr.bin/du/du.c
 @@ -499,9 +499,8 @@ static void
  usage(void)
  {
  	(void)fprintf(stderr,
 -		"usage: du [-A] [-H | -L | -P] [-a | -s | -d depth] [-c] "
 -		"[-l] [-h | -k | -m | -B bsize] [-n] [-x] [-I mask] "
 -		"[file ...]\n");
 +		"usage: du [-Achklmnx] [-H | -L | -P] [-a | -s | -d depth] "
 +		"[-B blocksize] [-I mask] [-t threshold] [file ...]\n");
  	exit(EX_USAGE);
  }

 --XsQoSWH+UP9D9v3l--