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.
This commit is contained in:
Bernhard Voelker authored and Pádraig Brady committed 2012-11-08 16:12:02 +00:00
1 parent dae8d223b6
commit ae3c2b4620
3 files changed
+86

No files matched your search

+13
View File
@@ -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
+66
View File
@@ -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
+7
View File
@@ -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);