gnu Coreutils Core GNU utilities for version 5.93, 2 November 2005 David MacKenzie et al. This manual documents version 5.93 of the gnu core utilities, including the standard pro- grams for text and file manipulation. Copyright c 1994, 1995, 1996, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License”. Chapter 1: Introduction 1 1 Introduction This manual is a work in progress: many sections make no attempt to explain basic concepts in a way suitable for novices. Thus, if you are interested, please get involved in improving this manual. The entire gnu community will benefit. The gnu utilities documented here are mostly compatible with the POSIX standard. Please report bugs to [email protected]. Remember to include the version number, machine architecture, input files, and any other information needed to reproduce the bug: your input, what you expected, what you got, and why it is wrong. Diffs are welcome, but please include a description of the problem as well, since this is sometimes difficult to infer. See section “Bugs” in Using and Porting GNU CC. This manual was originally derived from the Unix man pages in the distributions, which were written by David MacKenzie and updated by Jim Meyering. What you are reading now is the authoritative documentation for these utilities; the man pages are no longer being maintained. The original fmt man page was written by Ross Paterson. Fran¸cois Pinard did the initial conversion to Texinfo format. Karl Berry did the indexing, some reorganization, and editing of the results. Brian Youmans of the Free Software Foundation office staff combined the manuals for textutils, fileutils, and sh-utils to produce the present omnibus manual. Richard Stallman contributed his usual invaluable insights to the overall process. Chapter 2: Common options 2 2 Common options Certain options are available in all of these programs. Rather than writing identical de- scriptions 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. A few programs can usefully have trailing operands with leading ‘-’. With such a program, options must precede operands even if POSIXLY_CORRECT is not set, and this fact is noted in the program description. For example, the env command’s options must appear before its operands, since in some cases the operands specify a command that itself contains options. 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 ‘-’ operand 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. For example, ‘sort -’ reads from standard input, and is equivalent to plain ‘sort’, and ‘tee -’ writes an extra copy of its input to standard output. Unless otherwise specified, ‘-’ can appear as any operand that requires a file name. 2.1 Exit status Nearly every command invocation yields an integral exit status that can be used to change how other commands work. For the vast majority of commands, an exit status of zero indicates success. Failure is indicated by a nonzero value—typically ‘1’, though it may differ on unusual platforms as POSIX requires only that it be nonzero. However, some of the programs documented here do produce other exit status values and a few associate different meanings with the values ‘0’ and ‘1’. Here are some of the exceptions: chroot, env, expr, nice, nohup, printenv, sort, su, test, tty. 2.2 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. Chapter 2: Common options 3 ‘-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 deter- mine 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. 2.3 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 file system 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. Chapter 2: Common options 4 BLOCKSIZE This specifies the default block size for all values that are normally printed as blocks, if neither BLOCK_SIZE nor the above command-specific environment variables are set. Unlike the other environment variables, BLOCKSIZE does not affect values that are normally printed as byte counts, e.g., the file sizes con- tained in ls -l output. POSIXLY_CORRECT If neither command_BLOCK_SIZE, nor BLOCK_SIZE, nor BLOCKSIZE is 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 (http://www.bipm.fr/enus/3_SI/si-prefixes.html) for decimal multiples and with the IEC 60027-2 prefixes for binary multiples (http://physics.nist.gov/cuu/Units/binary.html). 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 thou- sands 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: 103 = 1000. ‘k’ ‘K’ ‘KiB’ kibibyte: 210 = 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: 106 = 1, 000, 000. Chapter 2: Common options 5 ‘M’ ‘MiB’ mebibyte: 220 = 1, 048, 576.