GNU file utilities - 2. Common options

Go to the first, previous, next, last section, table of contents.

# 2. Common options

Certain options are available in all of these programs (in fact, every GNU program should accept them). Rather than writing identical descriptions for each of the programs, they are described here.

``--help'`
  Print a usage message listing all available options, then exit successfully.
``--version'`
  Print the version number, then exit successfully.

## 2.1 Backup options

Some GNU programs (at least `cp`, `install`, `ln`, and `mv`) optionally make backups of files before writing new versions. These options control the details of these backups. The options are also briefly mentioned in the descriptions of the particular programs.

``-b'`
``--backup'`
  Make a backup of each file that would otherwise be overwritten or removed. Without this option, the original versions are destroyed.
``-S suffix'`
``--suffix=suffix'`
  Append suffix to each backup file made with ``-b'`. If this option is not specified, the value of the `SIMPLE_BACKUP_SUFFIX` environment variable is used. And if `SIMPLE_BACKUP_SUFFIX` is not set, the default is ``~'`, just as in Emacs.
``-V method'`
``--version-control=method'`
  Use method to determine the type of backups made with ``-b'`. If this option is not specified, the value of the `VERSION_CONTROL` environment variable is used. And if `VERSION_CONTROL` is not set, the default backup type is ``existing'`. This option corresponds to the Emacs variable ``version-control'`; the same values for method are accepted as in Emacs. This options also more descriptive name. The valid methods (unique abbreviations are accepted):
  ``t'`
  ``numbered'`
    Always make numbered backups.
  ``nil'`
  ``existing'`
    Make numbered backups of files that already have them, simple backups of the others.
  ``never'`
  ``simple'`
    Always make simple backups.

## 2.2 Block size

Some GNU programs (at least `df`, `du`, and `ls`) display file sizes in "blocks". You can adjust the block size to make file sizes easier to read. The block size used for display is independent of any filesystem block size. Displayed sizes are rounded to the nearest block, with ties rounding to an even number.

The default block size is chosen by examining the following environment variables in turn; the first one that is set determines the block size.

`DF_BLOCK_SIZE`
  This specifies the default block size for the `df` command. Similarly, `DU_BLOCK_SIZE` specifies the default for `du` and `LS_BLOCK_SIZE` for `ls`.
`BLOCK_SIZE`
  This specifies the default block size for all three commands, if the above command-specific environment variables are not set.
`POSIXLY_CORRECT`
  If neither the `command_BLOCK_SIZE` nor the `BLOCK_SIZE` variables are set, but this variable is set, the block size defaults to 512.

If none of the above environment variables are set, the block size currently defaults to 1024 bytes, but this number may change in the future.

A block size specification can be a positive integer specifying the number of bytes per block, or it can be `human-readable` or `si` to select a human-readable format.

With human-readable formats, output sizes are followed by a size letter such as ``M'` for megabytes. `BLOCK_SIZE=human-readable` uses powers of 1024; ``M'` stands for 1,048,576 bytes. `BLOCK_SIZE=si` is similar, but uses powers of 1000; ``M'` stands for 1,000,000 bytes. (SI, the International System of Units, defines these power-of-1000 prefixes.)

An integer block size can be followed by a size letter to specify a multiple of that size. When this notation is used, the size letters normally stand for powers of 1024, and can be followed by an optional ``B'` for "byte"; but if followed by ``D'` (for "decimal byte"), they stand for powers of 1000. For example, `BLOCK_SIZE=4MB` is equivalent to `BLOCK_SIZE=4194304`, and `BLOCK_SIZE=4MD` is equivalent to `BLOCK_SIZE=4000000`.

The following size letters are defined. Large sizes like `1Y` may be rejected by your computer due to limitations of its arithmetic.

``k'`
  kilo: 2^10 = 1024 for `human-readable`, or 10^3 = 1000 for `si`.
``M'`
  Mega: 2^20 = 1,048,576 or 10^6 = 1,000,000.
``G'`
  Giga: 2^30 = 1,073,741,824 or 10^9 = 1,000,000,000.
``T'`
  Tera: 2^40 = 1,099,511,627,776 or 10^12 = 1,000,000,000,000.
``P'`
  Peta: 2^50 = 1,125,899,906,842,624 or 10^15 = 1,000,000,000,000,000.
``E'`
  Exa: 2^60 = 1,152,921,504,606,846,976 or 10^18 = 1,000,000,000,000,000,000.
``Z'`
  Zetta: 2^70 = 1,180,591,620,717,411,303,424 or 10^21 = 1,000,000,000,000,000,000,000.
``Y'`
  Yotta: 2^80 = 1,208,925,819,614,629,174,706,176 or 10^24 = 1,000,000,000,000,000,000,000,000.

Block size defaults can be overridden by an explicit ``--block-size=size'` option. The ``-k'` or ``--kilobytes'` option is equivalent to ``--block-size=1k'`, which is the default unless the `POSIXLY_CORRECT` environment variable is set. The ``-h'` or ``--human-readable'` option is equivalent to ``--block-size=human-readable'`. The ``-H'` or ``--si'` option is equivalent to ``--block-size=si'`.

Go to the first, previous, next, last section, table of contents.