This manual documents version 6.9 of the gnu core utilities, including the standard programs for text and file manipulation.
Copyright © 1994, 1995, 1996, 2000, 2001, 2002, 2003, 2004, 2005, 2006 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.2 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”.
--- The Detailed Node Listing ---
Common Options
Output of entire files
Formatting file contents
Output of parts of files
Summarizing files
Operating on sorted files
ptx: Produce permuted indexes
Operating on fields within a line
Operating on characters
tr: Translate, squeeze, and/or delete characters
Directory listing
ls: List directory contents
Basic operations
Special file types
Changing file attributes
Disk usage
Printing text
Conditions
test: Check file types and compare values
expr: Evaluate expression
Redirection
File name manipulation
Working context
stty: Print or change terminal characteristics
User information
System context
date: Print or set system date and time
Modified command invocation
Process control
Delaying
Numeric operations
File permissions
Date input formats
Opening the software toolbox
Copying This Manual
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 bug-coreutils@gnu.org. 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 Bugs.
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çois 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.
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.
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.
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.
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.
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.
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):
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_SIZEBLOCK_SIZEBLOCKSIZEls -l output.
POSIXLY_CORRECTIf 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.
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.
Since the owner and group arguments to chown and
chgrp may be specified as names or numeric IDs, there is an
apparent ambiguity.
What if a user or group name is a string of digits?
1
Should the command interpret it as a user name or as an ID?
POSIX requires that chown and chgrp
first attempt to resolve the specified string as a name, and
only once that fails, then try to interpret it as an ID.
This is troublesome when you want to specify a numeric ID, say 42,
and it must work even in a pathological situation where
‘42’ is a user name that maps to some other user ID, say 1000.
Simply invoking chown 42 F, will set Fs owner ID to
1000—not what you intended.
GNU chown and chgrp provide a way to work around this, that at the same time may result in a significant performance improvement by eliminating a database look-up. Simply precede each numeric user ID and/or group ID with a ‘+’, in order to force its interpretation as an integer:
chown +42 F
chgrp +$numeric_group_id another-file
chown +0:+0 /
GNU chown and chgrp skip the name look-up process for each ‘+’-prefixed string, because a string containing ‘+’ is never a valid user or group name. This syntax is accepted on most common Unix systems, but not on Solaris 10.
The shuf, shred, and sort commands sometimes need random data to do their work. For example, ‘sort -R’ must choose a hash function at random, and it needs random data to make this selection.
Normally these commands use the device file /dev/urandom as the source of random data. Typically, this device gathers environmental noise from device drivers and other sources into an entropy pool, and uses the pool to generate random bits. If the pool is short of data, the device reuses the internal pool to produce more bits, using a cryptographically secure pseudorandom number generator.
/dev/urandom suffices for most practical uses, but applications requiring high-value or long-term protection of private data may require an alternate data source like /dev/random or /dev/arandom. The set of available sources depends on your operating system.
To use such a source, specify the --random-source=file option, e.g., ‘shuf --random-source=/dev/random’. The contents of file should be as random as possible. An error is reported if file does not contain enough bytes to randomize the input adequately.
To reproduce the results of an earlier invocation of a command, you can save some random data into a file and then use that file as the random source in earlier and later invocations of the command.
Some old-fashioned or stripped-down operating systems lack support for /dev/urandom. On these systems commands like shuf by default fall back on an internal pseudorandom generator initialized by a small amount of entropy.
The cp, install, ln, and mv commands normally treat the last operand specially when it is a directory or a symbolic link to a directory. For example, ‘cp source dest’ is equivalent to ‘cp source dest/source’ if dest is a directory. Sometimes this behavior is not exactly what is wanted, so these commands support the following options to allow more fine-grained control:
In the opposite situation, where you want the last operand to be
treated as a directory and want a diagnostic otherwise, you can use
the --target-directory (-t) option.
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 (-t) 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:
ls | xargs mv -t ../d --
However, this doesn't move files whose names begin with ‘.’. If you use the gnu find program, you can move those files too, with this command:
find . -mindepth 1 -maxdepth 1 \
| xargs mv -t ../d
But both of the above approaches fail if there are no files in the current directory, or if any file has a name containing a blank or some other special characters. 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 -t ../d
The --target-directory (-t) and --no-target-directory (-T) options cannot be combined.
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.
The following options modify how chown and chgrp traverse a hierarchy when the --recursive (-R) option is also specified. If more than one of the following options is specified, only the final one takes effect. These options specify whether processing a symbolic link to a directory entails operating on just the symbolic link or on all files in the hierarchy rooted at that directory.
These options are independent of --dereference and --no-dereference (-h), which control whether to modify a symlink or its referent.
Certain commands can operate destructively on entire hierarchies. For example, if a user with appropriate privileges mistakenly runs ‘rm -rf / tmp/junk’, that may remove all files on the entire system. Since there are so few legitimate uses for such a command, gnu rm normally declines to operate on any directory that resolves to /. If you really want to try to remove all the files on your system, you can use the --no-preserve-root option, but the default behavior, specified by the --preserve-option, is safer for most purposes.
The commands chgrp, chmod and chown can also operate destructively on entire hierarchies, so they too support these options. Although, unlike rm, they don't actually unlink files, these commands are arguably more dangerous when operating recursively on /, since they often work much more quickly, and hence damage more files before an alert user can interrupt them. Tradition and POSIX require these commands to operate recursively on /, so they default to --no-preserve-root, but using the --preserve-root option makes them safer for most purposes. For convenience you can specify --preserve-root in an alias or in a shell function.
Note that the --preserve-root option also ensures that chgrp and chown do not modify / even when dereferencing a symlink pointing to /.
Some programs like nice can invoke other programs; for example, the command ‘nice cat file’ invokes the program cat by executing the command ‘cat file’. However, special built-in utilities like exit cannot be invoked this way. For example, the command ‘nice exit’ does not have a well-defined behavior: it may generate an error message instead of exiting.
Here is a list of the special built-in utilities that are standardized by POSIX 1003.1-2004.
. : break continue eval exec exit export readonly return set shift times trap unset
For example, because ‘.’, ‘:’, and ‘exec’ are special, the commands ‘nice . foo.sh’, ‘nice :’, and ‘nice exec pwd’ do not work as you might expect.
Many shells extend this list. For example, Bash has several extra special built-in utilities like history, and suspend, and with Bash the command ‘nice suspend’ generates an error message instead of suspending.
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 have a newer system but are running software that assumes an older version of POSIX and uses ‘sort +1’ or ‘tail +10’, you can work around any compatibility problems by setting ‘_POSIX2_VERSION=199209’ in your environment.
These commands read and write entire files, possibly transforming them in some way.
cat copies each file (‘-’ means standard input), or standard input if none are given, to standard output. Synopsis:
cat [option] [file]...
The program accepts the following options. Also see Common options.
On systems like MS-DOS that distinguish between text and binary files, cat normally reads and writes in binary mode. However, cat reads in text mode if one of the options -bensAE is used or if cat is reading from standard input and standard input is a terminal. Similarly, cat writes in text mode if one of the options -bensAE is used or if standard output is a terminal.
An exit status of zero indicates success, and a nonzero value indicates failure.
Examples:
# Output f's contents, then standard input, then g's contents.
cat f - g
# Copy standard input to standard output.
cat
tac copies each file (‘-’ means standard input), or standard input if none are given, to standard output, reversing the records (lines by default) in each separately. Synopsis:
tac [option]... [file]...
Records are separated by instances of a string (newline by default). By default, this separator string is attached to the end of the record that it follows in the file.
The program accepts the following options. Also see Common options.
An exit status of zero indicates success, and a nonzero value indicates failure.
nl writes each file (‘-’ means standard input), or standard input if none are given, to standard output, with line numbers added to some or all of the lines. Synopsis:
nl [option]... [file]...
nl decomposes its input into (logical) pages; by default, the line number is reset to 1 at the top of each logical page. nl treats all of the input files as a single document; it does not reset line numbers or logical pages between files.
A logical page consists of three sections: header, body, and footer. Any of the sections can be empty. Each can be numbered in a different style from the others.
The beginnings of the sections of logical pages are indicated in the input file by a line containing exactly one of these delimiter strings:
The two characters from which these strings are made can be changed from ‘\’ and ‘:’ via options (see below), but the pattern and length of each string cannot be changed.
A section delimiter is replaced by an empty line on output. Any text that comes before the first section delimiter string in the input file is considered to be part of a body section, so nl treats a file that contains no section delimiters as a single body section.
The program accepts the following options. Also see Common options.
rn):
An exit status of zero indicates success, and a nonzero value indicates failure.
od writes an unambiguous representation of each file (‘-’ means standard input), or standard input if none are given. Synopses:
od [option]... [file]...
od [-abcdfilosx]... [file] [[+]offset[.][b]]
od [option]... --traditional [file] [[+]offset[.][b] [[+]label[.][b]]]
Each line of output consists of the offset in the input, followed by
groups of data from the file. By default, od prints the offset in
octal, and each group of file data is a C short int's worth of input
printed as a single octal number.
If offset is given, it specifies how many input bytes to skip before formatting and writing. By default, it is interpreted as an octal number, but the optional trailing decimal point causes it to be interpreted as decimal. If no decimal is specified and the offset begins with ‘0x’ or ‘0X’ it is interpreted as a hexadecimal number. If there is a trailing ‘b’, the number of bytes skipped will be offset multiplied by 512.
If a command is of both the first and second forms, the second form is assumed if the last operand begins with ‘+’ or (if there are two operands) a digit. For example, in ‘od foo 10’ and ‘od +10’ the ‘10’ is an offset, whereas in ‘od 10’ the ‘10’ is a file name.
The program accepts the following options. Also see Common options.
The default is octal.
bytes are interpreted as for the -j option.
If n is omitted with --strings, the default is 3.
Adding a trailing “z” to any type specification appends a display of the ASCII character representation of the printable characters to the output line generated by the type specification.
The type a outputs things like ‘sp’ for space, ‘nl’ for
newline, and ‘nul’ for a null (zero) byte. Only the least significant
seven bits of each byte is used; the high-order bit is ignored.
Type c outputs
‘ ’, ‘\n’, and \0, respectively.
Except for types ‘a’ and ‘c’, you can specify the number of bytes to use in interpreting each number in the given data type by following the type indicator character with a decimal integer. Alternately, you can specify the size of one of the C compiler's built-in data types by following the type indicator character with one of the following characters. For integers (‘d’, ‘o’, ‘u’, ‘x’):
For floating point (f):
n input bytes per output line. This must be a multiple of
the least common multiple of the sizes associated with the specified
output types.
If this option is not given at all, the default is 16. If n is omitted, the default is 32.
The next several options are shorthands for format specifications. gnu od accepts any combination of shorthands and format specification options. These options accumulate.
od --traditional [file] [[+]offset[.][b] [[+]label[.][b]]]
can be used to specify at most one file and optional arguments specifying an offset and a pseudo-start address, label. The label argument is interpreted just like offset, but it specifies an initial pseudo-address. The pseudo-addresses are displayed in parentheses following any normal address.
An exit status of zero indicates success, and a nonzero value indicates failure.
base64 transforms data read from a file, or standard input, into (or from) base64 encoded form. The base64 encoded form uses printable ASCII characters to represent binary data, see RFC 3548. Synopses:
base64 [option]... [file]
base64 --decode [option]... [file]
The base64 encoding expands data to roughly 133% of the original.
The program accepts the following options. Also see Common options.
The default is to wrap after 76 characters. Use the value 0 to
disable line wrapping altogether.
An exit status of zero indicates success, and a nonzero value indicates failure.
These commands reformat the contents of files.
fmt fills and joins lines to produce output lines of (at most) a given number of characters (75 by default). Synopsis:
fmt [option]... [file]...
fmt reads from the specified file arguments (or standard input if none are given), and writes to standard output.
By default, blank lines, spaces between words, and indentation are preserved in the output; successive input lines with different indentation are not joined; tabs are expanded on input and introduced on output.
fmt prefers breaking lines at the end of a sentence, and tries to avoid line breaks after the first word of a sentence or before the last word of a sentence. A sentence break is defined as either the end of a paragraph or a word ending in any of ‘.?!’, followed by two spaces or end of line, ignoring any intervening parentheses or quotes. Like TeX, fmt reads entire “paragraphs” before choosing line breaks; the algorithm is a variant of that given by Donald E. Knuth and Michael F. Plass in “Breaking Paragraphs Into Lines”, Software—Practice & Experience 11, 11 (November 1981), 1119–1184.
The program accepts the following options. Also see Common options.
An exit status of zero indicates success, and a nonzero value indicates failure.
pr writes each file (‘-’ means standard input), or standard input if none are given, to standard output, paginating and optionally outputting in multicolumn format; optionally merges all files, printing all in parallel, one per column. Synopsis:
pr [option]... [file]...
By default, a 5-line header is printed at each page: two blank lines; a line with the date, the file name, and the page count; and two more blank lines. A footer of five blank lines is also printed. With the -F option, a 3-line header is printed: the leading two blank lines are omitted; no footer is used. The default page_length in both cases is 66 lines. The default number of text lines changes from 56 (without -F) to 63 (with -F). The text line of the header takes the form ‘date string page’, with spaces inserted around string so that the line takes up the full page_width. Here, date is the date (see the -D or --date-format option for details), string is the centered header string, and page identifies the page number. The LC_MESSAGES locale category affects the spelling of page; in the default C locale, it is ‘Page number’ where number is the decimal page number.
Form feeds in the input cause page breaks in the output. Multiple form feeds produce empty pages.
Columns are of equal width, separated by an optional string (default is ‘space’). For multicolumn output, lines will always be truncated to page_width (default 72), unless you use the -J option. For single column output no line truncation occurs by default. Use -W option to truncate lines in that case.
The following changes were made in version 1.22i and apply to later versions of pr: - Brian
The program accepts the following options. Also see Common options.
Normally the date format defaults to ‘%Y-%m-%d %H:%M’ (for example, ‘2001-12-04 23:59’); but if the POSIXLY_CORRECT environment variable is set and the LC_TIME locale category specifies the POSIX locale, the default is ‘%b %e %H:%M %Y’ (for example, ‘Dec 4 23:59 2001’.
Time stamps are listed according to the time zone rules specified by
the TZ environment variable, or by the system default rules if
TZ is not set. See Specifying the Time Zone with TZ.