df: document the new --output option

* src/df.c (usage): Add a short description of --output and its
available field names for use in the optional argument.
* doc/coreutils.texi (df invocation): Add the new option with more
details and a few examples.
* NEWS (New features): Mention the new option.
(Changes in behvaior): Mention the new placeholder for fields
in the "total" line.

diff --git a/NEWS b/NEWS
index c824e41a1aa2dac14076b3645d3e717fe27f3256..db6a207bd4b79af170abd04136d9cae16984d363 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -2,12 +2,25 @@ GNU coreutils NEWS                                    -*- outline -*-
 
 * Noteworthy changes in release ?.? (????-??-??) [?]
 
+** New features
+
+  df now accepts the --output[=FIELD_LIST] option to define the list of columns
+  to include in the output, or all available columns if the FIELD_LIST is
+  omitted.  Note this enables df to output both block and inode fields together.
+
 ** Bug fixes
 
   pr -n no longer crashes when passed values >= 32.  Also line numbers are
   consistently padded with spaces, rather than with zeros for certain widths.
   [bug introduced in TEXTUTILS-1_22i]
 
+** Changes in behavior
+
+  df --total now prints '-' into the target column (mount point) of the
+  summary line, accommodating to the --output option where the target
+  field can be in any column.  If there is no source column, then df
+  prints 'total' into the target column.
+
 ** Build-related
 
   Perl is now more of a prerequisite.  It has long been required in order

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 767a31e9c6057132c6e9c1b9ea37f394cbfe3f92..b251b3d91c2ab89e116a58e078335aa1bd9244e7 100644 (file)
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -10637,6 +10637,12 @@ Print a grand total of all arguments after all arguments have
 been processed.  This can be used to find out the total disk size, usage
 and available space of all listed devices.
 
+For the grand total line, @command{df} prints @samp{"total"} into the
+@var{source} column, and @samp{"-"} into the @var{target} column.
+If there is no @var{source} column (see @option{--output}), then
+@command{df} prints @samp{"total"} into the @var{target} column,
+if present.
+
 @optHumanReadable
 
 @item -H
@@ -10675,6 +10681,66 @@ This may make @command{df} run significantly faster on systems with many
 disks, but on some systems (notably SunOS) the results may be slightly
 out of date.  This is the default.
 
+@item --output
+@itemx @w{@kbd{--output}[=@var{field_list}]}
+@opindex --output
+Use the output format defined by @var{field_list}, or print all fields if
+@var{field_list} is omitted.
+
+The use of the @option{--output} together with each of the options @option{-i},
+@option{-P}, and @option{-T} is mutually exclusive.
+
+FIELD_LIST is a comma-separated list of columns to be included in @command{df}'s
+output and therefore effectively controls the order of output columns.
+Each field can thus be used at the place of choice, but yet must only be
+used once.
+
+Valid field names in the @var{field_list} are:
+@table @samp
+@item source
+The source of the mount point, usually a device.
+@item fstype
+File system type.
+
+@item size
+Total number of blocks.
+@item used
+Number of used blocks.
+@item avail
+Number of available blocks.
+@item pcent
+Percentage of @var{used} divided by @var{size}.
+
+@item itotal
+Total number of inodes.
+@item iused
+Number of used inodes.
+@item iavail
+Number of available inodes.
+@item ipcent
+Percentage of @var{iused} divided by @var{itotal}.
+
+@item target
+The mount point.
+@end table
+
+The fields for block and inodes statistics are affected by the scaling
+options like @option{-h} as usual.
+
+The definition of the @var{field_list} can even be splitted among several
+@option{--output} uses.
+
+@example
+#!/bin/sh
+# Print the TARGET (i.e., the mount point) along with their percentage
+# statistic regarding the blocks and the inodes.
+df --out=target --output=pcent,ipcent
+
+# Print all available fields.
+df --o
+@end example
+
+
 @item -P
 @itemx --portability
 @opindex -P

diff --git a/src/df.c b/src/df.c
index 2f4208d57a9d8eb58fe14ebe69491475f03cecb8..c62d16b50ede88b572d404415a312e7a555c0066 100644 (file)
--- a/src/df.c
+++ b/src/df.c
@@ -1149,6 +1149,8 @@ Mandatory arguments to long options are mandatory for short options too.\n\
 \n\
 "), stdout);
       fputs (_("\
+      --output[=FIELD_LIST]  use the output format defined by FIELD_LIST,\n\
+                               or print all fields if FIELD_LIST is omitted.\n\
   -P, --portability     use the POSIX output format\n\
       --sync            invoke sync before getting usage info\n\
   -t, --type=TYPE       limit listing to file systems of type TYPE\n\
@@ -1160,6 +1162,11 @@ Mandatory arguments to long options are mandatory for short options too.\n\
       fputs (VERSION_OPTION_DESCRIPTION, stdout);
       emit_blocksize_note ("DF");
       emit_size_note ();
+      fputs (_("\n\
+FIELD_LIST is a comma-separated list of columns to be included.  Valid\n\
+field names are: 'source', 'fstype', 'size', 'used', 'avail', 'pcent',\n\
+'itotal', 'iused', 'iavail', 'ipcent' and 'target' (see info page).\n\
+"), stdout);
       emit_ancillary_info ();
     }
   exit (status);