2. Common options

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

Normally options and operands can appear in any order, and programs act as if all the options appear before any operands. For example, `sort -r passwd -t :' acts like `sort -r -t : passwd', since `:' is an option-argument of `-t'. However, if the POSIXLY_CORRECT environment variable is set, options must appear before operands, unless otherwise specified for a particular command.

Some of these programs recognize the `--help' and `--version' options only when one of them is the sole command line argument.

`--help'

Print a usage message listing all available options, then exit successfully.

`--version'

Print the version number, then exit successfully.

`--'

Delimit the option list. Later arguments, if any, are treated as operands even if they begin with `-'. For example, `sort -- -r' reads from the file named `-r'.

A single `-' is not really an option, though it looks like one. It stands for standard input, or for standard output if that is clear from the context, and it can be used either as an operand or as an option-argument. For example, `sort -o - -' outputs to standard output and reads from standard input, and is equivalent to plain `sort'. Unless otherwise specified, `-' can appear in any context that requires a file name.

2.1 Backup options		-b -S -V, in some programs.
2.2 Block size		BLOCK_SIZE and --block-size, in some programs.
2.3 Target directory		--target-directory, in some programs.
2.4 Trailing slashes		--strip-trailing-slashes, in some programs.
2.5 Standards conformance		Conformance to the POSIX standard.

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[=method]'

Make a backup of each file that would otherwise be overwritten or removed. Without this option, the original versions are destroyed. Use method to determine the type of backups to make. When this option is used but method is not specified, then the value of the VERSION_CONTROL environment variable is used. And if VERSION_CONTROL is not set, the default backup type is `existing'.

Note that the short form of this option, `-b' does not accept any argument. Using `-b' is equivalent to using `--backup=existing'.

This option corresponds to the Emacs variable `version-control'; the values for method are the same as those used in Emacs. This option also accepts more descriptive names. The valid methods are (unique abbreviations are accepted):

`none'

`off'

Never make backups.

`numbered'

`t'

Always make numbered backups.

`existing'

`nil'

Make numbered backups of files that already have them, simple backups of the others.

`simple'

`never'

Always make simple backups. Please note `never' is not to be confused with `none'.

`-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.

`--version-control=method'

This option is obsolete and will be removed in a future release. It has been replaced with --backup.

2.2 Block size

Some GNU programs (at least df, du, and ls) display sizes in "blocks". You can adjust the block size and method of display to make sizes easier to read. The block size used for display is independent of any filesystem block size. Fractional block counts are rounded up to the nearest integer.

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 in most contexts, but this number may change in the future. For ls file sizes, the block size defaults to 1 byte.

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. Integers may be followed by suffixes that are upward compatible with the SI prefixes for decimal multiples and with the IEC 60027-2 prefixes for binary multiples.

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 and appends `B'; `MB' stands for 1,000,000 bytes.

A block size specification preceded by `'' causes output sizes to be displayed with thousands separators. The LC_NUMERIC locale specifies the thousands separator and grouping. For example, in an American English locale, `--block-size="'1kB"' would cause a size of 1234000 bytes to be displayed as `1,234'. In the default C locale, there is no thousands separator so a leading `'' has no effect.

An integer block size can be followed by a suffix to specify a multiple of that size. A bare size letter, or one followed by `iB', specifies a multiple using powers of 1024. A size letter followed by `B' specifies powers of 1000 instead. For example, `1M' and `1MiB' are equivalent to `1048576', whereas `1MB' is equivalent to `1000000'.

A plain suffix without a preceding integer acts as if `1' were prepended, except that it causes a size indication to be appended to the output. For example, `--block-size="kB"' displays 3000 as `3kB'.

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

`kB'

kilobyte: 10^3 = 1000.

`k'

`K'

`KiB'

kibibyte: 2^10 = 1024. `K' is special: the SI prefix is `k' and the IEC 60027-2 prefix is `Ki', but tradition and POSIX use `k' to mean `KiB'.

`MB'

megabyte: 10^6 = 1,000,000.

`M'

`MiB'

mebibyte: 2^20 = 1,048,576.

`GB'

gigabyte: 10^9 = 1,000,000,000.

`G'

`GiB'

gibibyte: 2^30 = 1,073,741,824.

`TB'

terabyte: 10^12 = 1,000,000,000,000.

`T'

`TiB'

tebibyte: 2^40 = 1,099,511,627,776.

`PB'

petabyte: 10^15 = 1,000,000,000,000,000.

`P'

`PiB'

pebibyte: 2^50 = 1,125,899,906,842,624.

`EB'

exabyte: 10^18 = 1,000,000,000,000,000,000.

`E'

`EiB'

exbibyte: 2^60 = 1,152,921,504,606,846,976.

`ZB'

zettabyte: 10^21 = 1,000,000,000,000,000,000,000

`Z'

`ZiB'

2^70 = 1,180,591,620,717,411,303,424. (`Zi' is a GNU extension to IEC 60027-2.)

`YB'

yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000.

`Y'

`YiB'

2^80 = 1,208,925,819,614,629,174,706,176. (`Yi' is a GNU extension to IEC 60027-2.)

Block size defaults can be overridden by an explicit `--block-size=size' option. The `-k' 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 `--si' option is equivalent to `--block-size=si'.

2.3 Target directory

Some GNU programs (at least cp, install, ln, and mv) allow you to specify the target directory via this option:

`--target-directory=directory'

Specify the destination directory.

The interface for most programs is that after processing options and a finite (possibly zero) number of fixed-position arguments, the remaining argument list is either expected to be empty, or is a list of items (usually files) that will all be handled identically. The xargs program is designed to work well with this convention.

The commands in the mv-family are unusual in that they take a variable number of arguments with a special case at the end (namely, the target directory). This makes it nontrivial to perform some operations, e.g., "move all files from here to ../d/", because mv * ../d/ might exhaust the argument space, and ls | xargs ... doesn't have a clean way to specify an extra final argument for each invocation of the subject command. (It can be done by going through a shell command, but that requires more human labor and brain power than it should.)

The --target-directory option allows the cp, install, ln, and mv programs to be used conveniently with xargs. For example, you can move the files from the current directory to a sibling directory, d like this: (However, this doesn't move files whose names begin with `.'.)

ls |xargs mv --target-directory=../d

If you use the GNU find program, you can move all files with this command:

find . -mindepth 1 -maxdepth 1 \ | xargs mv --target-directory=../d

But that will fail if there are no files in the current directory or if any file has a name containing a newline character. The following example removes those limitations and requires both GNU find and GNU xargs:

find . -mindepth 1 -maxdepth 1 -print0 \ | xargs --null --no-run-if-empty \ mv --target-directory=../d

2.4 Trailing slashes

Some GNU programs (at least cp and mv) allow you to remove any trailing slashes from each source argument before operating on it. The --strip-trailing-slashes option enables this behavior.

This is useful when a source argument may have a trailing slash and specify a symbolic link to a directory. This scenario is in fact rather common because some shells can automatically append a trailing slash when performing file name completion on such symbolic links. Without this option, mv, for example, (via the system's rename function) must interpret a trailing slash as a request to dereference the symbolic link and so must rename the indirectly referenced directory and not the symbolic link. Although it may seem surprising that such behavior be the default, it is required by POSIX and is consistent with other parts of that standard.

2.5 Standards conformance

In a few cases, the GNU utilities' default behavior is incompatible with the POSIX standard. To suppress these incompatibilities, define the POSIXLY_CORRECT environment variable. Unless you are checking for POSIX conformance, you probably do not need to define POSIXLY_CORRECT.

Newer versions of POSIX are occasionally incompatible with older versions. For example, older versions of POSIX required the command `sort +1' to sort based on the second and succeeding fields in each input line, but starting with POSIX 1003.1-2001 the same command is required to sort the file named `+1', and you must instead use the command `sort -k 2' to get the field-based sort.

The GNU utilities normally conform to the version of POSIX that is standard for your system. To cause them to conform to a different version of POSIX, define the _POSIX2_VERSION environment variable to a value of the form yyyymm specifying the year and month the standard was adopted. Two values are currently supported for _POSIX2_VERSION: `199209' stands for POSIX 1003.2-1992, and `200112' stands for POSIX 1003.1-2001. For example, if you are running older software that assumes an older version of POSIX and uses `sort +1', you can work around the compatibility problems by setting `_POSIX2_VERSION=199209' in your environment.