* shuf: (coreutils)shuf invocation. Shuffling text files.
* sleep: (coreutils)sleep invocation. Delay for a specified time.
* sort: (coreutils)sort invocation. Sort text files.
-* split: (coreutils)split invocation. Split into fixed-size pieces.
+* split: (coreutils)split invocation. Split into pieces.
* stat: (coreutils)stat invocation. Report file(system) status.
* stdbuf: (coreutils)stdbuf invocation. Modify stdio buffering.
* stty: (coreutils)stty invocation. Print/change terminal settings.
This manual documents version @value{VERSION} of the @sc{gnu} core
utilities, including the standard programs for text and file manipulation.
-Copyright @copyright{} 1994-1996, 2000-2010 Free Software Foundation, Inc.
+Copyright @copyright{} 1994-1996, 2000-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* Exit status:: Indicating program success or failure
* Backup options:: Backup options
* Block size:: Block size
+* Floating point:: Floating point number representation
* Signal specifications:: Specifying signals
* Disambiguating names and IDs:: chgrp and chown owner and group syntax
* Random sources:: Sources of random data
@macro mayConflictWithShellBuiltIn{cmd}
@cindex conflicts with shell built-ins
@cindex built-in shell commands, conflicts with
-Due to shell aliases and built-in @command{\cmd\} command, using an
+Due to shell aliases and built-in @command{\cmd\} functions, using an
unadorned @command{\cmd\} interactively or in a script may get you
different functionality than that described here. Invoke it via
@command{env} (i.e., @code{env \cmd\ @dots{}}) to avoid interference
* Exit status:: Indicating program success or failure.
* Backup options:: -b -S, in some programs.
* Block size:: BLOCK_SIZE and --block-size, in some programs.
+* Floating point:: Floating point number representation.
* Signal specifications:: Specifying signals using the --signal option.
* Disambiguating names and IDs:: chgrp and chown owner and group syntax
* Random sources:: --random-source, in some programs.
* Trailing slashes:: --strip-trailing-slashes, in some programs.
* Traversing symlinks:: -H, -L, or -P, in some programs.
* Treating / specially:: --preserve-root and --no-preserve-root.
-* Special built-in utilities:: @command{break}, @command{:}, @command{eval}, @dots{}
+* Special built-in utilities:: @command{break}, @command{:}, @dots{}
* Standards conformance:: Conformance to the @acronym{POSIX} standard.
@end menu
@option{--block-size=human-readable}. The @option{--si} option is
equivalent to @option{--block-size=si}.
+@node Floating point
+@section Floating point numbers
+@cindex floating point
+@cindex IEEE floating point
+
+Commands that accept or produce floating point numbers employ the
+floating point representation of the underlying system, and suffer
+from rounding error, overflow, and similar floating-point issues.
+Almost all modern systems use IEEE-754 floating point, and it is
+typically portable to assume IEEE-754 behavior these days. IEEE-754
+has positive and negative infinity, distinguishes positive from
+negative zero, and uses special values called NaNs to represent
+invalid computations such as dividing zero by itself. For more
+information, please see David Goldberg's paper
+@uref{http://@/www.validlab.com/@/goldberg/@/paper.pdf, What Every
+Computer Scientist Should Know About Floating-Point Arithmetic}.
+
+@vindex LC_NUMERIC
+Commands that accept floating point numbers as options, operands or
+input use the standard C functions @code{strtod} and @code{strtold} to
+convert from text to floating point numbers. These floating point
+numbers therefore can use scientific notation like @code{1.0e-34} and
+@code{-10e100}. Modern C implementations also accept hexadecimal
+floating point numbers such as @code{-0x.ep-3}, which stands for
+@minus{}14/16 times @math{2^-3}, which equals @minus{}0.109375. The
+@env{LC_NUMERIC} locale determines the decimal-point character.
+@xref{Parsing of Floats,,, libc, The GNU C Library Reference Manual}.
+
@node Signal specifications
@section Signal specifications
@cindex signals, specifying
@macro choptH
@item -H
@opindex -H
-@cindex symbolic link to directory, traverse each that is specified on the command line
+@cindex symbolic link to directory, traverse if on the command line
If @option{--recursive} (@option{-R}) is specified and
a command line argument is a symbolic link to a directory, traverse it.
@end macro
that is standard for your system. To cause them to conform to a
different version of @acronym{POSIX}, define the @env{_POSIX2_VERSION}
environment variable to a value of the form @var{yyyymm} specifying
-the year and month the standard was adopted. Two values are currently
+the year and month the standard was adopted. Three values are currently
supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
-@acronym{POSIX} 1003.2-1992, and @samp{200112} stands for @acronym{POSIX}
-1003.1-2001. For example, if you have a newer system but are running software
+@acronym{POSIX} 1003.2-1992, @samp{200112} stands for @acronym{POSIX}
+1003.1-2001, and @samp{200809} stands for @acronym{POSIX} 1003.1-2008.
+For example, if you have a newer system but are running software
that assumes an older version of @acronym{POSIX} and uses @samp{sort +1}
or @samp{tail +10}, you can work around any compatibility problems by setting
@samp{_POSIX2_VERSION=199209} in your environment.
@smallexample
od [@var{option}]@dots{} [@var{file}]@dots{}
od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]]
-od [@var{option}]@dots{} --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
+od [@var{option}]@dots{} --traditional [@var{file}]@c
+ [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
@end smallexample
Each line of output consists of the offset in the input, followed by
Instead of the normal output, output only @dfn{string constants}: at
least @var{bytes} consecutive @acronym{ASCII} graphic characters,
followed by a zero byte (@acronym{ASCII} @sc{nul}).
-Prefixes and suffixes on @code{bytes} are interpreted as for the
+Prefixes and suffixes on @var{bytes} are interpreted as for the
@option{-j} option.
If @var{n} is omitted with @option{--strings}, the default is 3.
@item d
signed decimal
@item f
-floating point
+floating point (@pxref{Floating point})
@item o
octal
@item u
@menu
* head invocation:: Output the first part of files.
* tail invocation:: Output the last part of files.
-* split invocation:: Split a file into fixed-size pieces.
+* split invocation:: Split a file into pieces.
* csplit invocation:: Split a file into context-determined pieces.
@end menu
Likewise, the @option{-f} option has no effect for any
operand specified as @samp{-}, when standard input is a FIFO or a pipe.
+With kernel inotify support, output is asynchronous and generally very prompt.
+Otherwise, @command{tail} sleeps for one second between checks---
+use @option{--sleep-interval=@var{N}} to change that default---which can
+make the output appear slightly less responsive or bursty.
+
@item -F
@opindex -F
This option is the same as @option{--follow=name --retry}. That is, tail
changed size.
Historical implementations of @command{tail} have required that
@var{number} be an integer. However, GNU @command{tail} accepts
-an arbitrary floating point number (using a period before any
-fractional digits).
+an arbitrary floating point number. @xref{Floating point}.
+When @command{tail} uses inotify, this polling-related option
+is usually ignored. However, if you also specify @option{--pid=@var{p}},
+@command{tail} checks whether process @var{p} is alive at least
+every @var{number} seconds.
@itemx --pid=@var{pid}
@opindex --pid
When following a log file that is rotated, this is approximately the
number of seconds between when tail prints the last pre-rotation lines
and when it prints the lines that have accumulated in the new log file.
-This option is meaningful only when following by name.
+This option is meaningful only when polling (i.e., without inotify)
+and when following by name.
@itemx -n @var{k}
@itemx --lines=@var{k}
@node split invocation
-@section @command{split}: Split a file into fixed-size pieces
+@section @command{split}: Split a file into pieces.
@pindex split
@cindex splitting a file into pieces
@cindex pieces, splitting a file into
-@command{split} creates output files containing consecutive sections of
-@var{input} (standard input if none is given or @var{input} is
-@samp{-}). Synopsis:
+@command{split} creates output files containing consecutive or interleaved
+sections of @var{input} (standard input if none is given or @var{input}
+is @samp{-}). Synopsis:
@example
split [@var{option}] [@var{input} [@var{prefix}]]
The output files' names consist of @var{prefix} (@samp{x} by default)
followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by
default), such that concatenating the output files in traditional
-sorted order by file name produces
-the original input file. If the output file names are exhausted,
-@command{split} reports an error without deleting the output files
-that it did create.
+sorted order by file name produces the original input file (except
+@option{-r}). If the output file names are exhausted, @command{split}
+reports an error without deleting the output files that it did create.
The program accepts the following options. Also see @ref{Common options}.
Put @var{lines} lines of @var{input} into each output file.
For compatibility @command{split} also supports an obsolete
-option syntax @option{-@var{lines}}. New scripts should use @option{-l
-@var{lines}} instead.
+option syntax @option{-@var{lines}}. New scripts should use
+@option{-l @var{lines}} instead.
@item -b @var{size}
@itemx --bytes=@var{size}
@var{size} bytes are broken into multiple files.
@var{size} has the same format as for the @option{--bytes} option.
+@itemx --filter=@var{command}
+@opindex --filter
+With this option, rather than simply writing to each output file,
+write through a pipe to the specified shell @var{command} for each output file.
+@var{command} should use the $FILE environment variable, which is set
+to a different output file name for each invocation of the command.
+For example, imagine that you have a 1TiB compressed file
+that, if uncompressed, would be too large to reside on disk,
+yet you must split it into individually-compressed pieces
+of a more manageable size.
+To do that, you might run this command:
+
+@example
+xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big-
+@end example
+
+Assuming a 10:1 compression ratio, that would create about fifty 20GiB files
+with names @file{big-xaa.xz}, @file{big-xab.xz}, @file{big-xac.xz}, etc.
+
+@item -n @var{chunks}
+@itemx --number=@var{chunks}
+@opindex -n
+@opindex --number
+
+Split @var{input} to @var{chunks} output files where @var{chunks} may be:
+
+@example
+@var{n} generate @var{n} files based on current size of @var{input}
+@var{k}/@var{n} only output @var{k}th of @var{n} to stdout
+l/@var{n} generate @var{n} files without splitting lines
+l/@var{k}/@var{n} likewise but only output @var{k}th of @var{n} to stdout
+r/@var{n} like @samp{l} but use round robin distribution
+r/@var{k}/@var{n} likewise but only output @var{k}th of @var{n} to stdout
+@end example
+
+Any excess bytes remaining after dividing the @var{input}
+into @var{n} chunks, are assigned to the last chunk.
+Any excess bytes appearing after the initial calculation are discarded
+(except when using @samp{r} mode).
+
+All @var{n} files are created even if there are fewer than @var{n} lines,
+or the @var{input} is truncated.
+
+For @samp{l} mode, chunks are approximately @var{input} size / @var{n}.
+The @var{input} is partitioned into @var{n} equal sized portions, with
+the last assigned any excess. If a line @emph{starts} within a partition
+it is written completely to the corresponding file. Since lines
+are not split even if they overlap a partition, the files written
+can be larger or smaller than the partition size, and even empty
+if a line is so long as to completely overlap the partition.
+
+For @samp{r} mode, the size of @var{input} is irrelevant,
+and so can be a pipe for example.
+
@item -a @var{length}
@itemx --suffix-length=@var{length}
@opindex -a
@opindex --numeric-suffixes
Use digits in suffixes rather than lower-case letters.
+@item -e
+@itemx --elide-empty-files
+@opindex -e
+@opindex --elide-empty-files
+Suppress the generation of zero-length output files. This can happen
+with the @option{--number} option if a file is (truncated to be) shorter
+than the number requested, or if a line is so long as to completely
+span a chunk. The output file sequence numbers, always run consecutively
+even when this option is specified.
+
+@item -u
+@itemx --unbuffered
+@opindex -u
+@opindex --unbuffered
+Immediately copy input to output in @option{--number r/...} mode,
+which is a much slower mode of operation.
+
@itemx --verbose
@opindex --verbose
Write a diagnostic just before each output file is opened.
@exitstatus
+Here are a few examples to illustrate how the
+@option{--number} (@option{-n}) option works:
+
+Notice how, by default, one line may be split onto two or more:
+
+@example
+$ seq -w 6 10 > k; split -n3 k; head xa?
+==> xaa <==
+06
+07
+==> xab <==
+
+08
+0
+==> xac <==
+9
+10
+@end example
+
+Use the "l/" modifier to suppress that:
+
+@example
+$ seq -w 6 10 > k; split -nl/3 k; head xa?
+==> xaa <==
+06
+07
+
+==> xab <==
+08
+09
+
+==> xac <==
+10
+@end example
+
+Use the "r/" modifier to distribute lines in a round-robin fashion:
+
+@example
+$ seq -w 6 10 > k; split -nr/3 k; head xa?
+==> xaa <==
+06
+09
+
+==> xab <==
+07
+10
+
+==> xac <==
+08
+@end example
+
+You can also extract just the Kth chunk.
+This extracts and prints just the 7th "chunk" of 33:
+
+@example
+$ seq 100 > k; split -nl/7/33 k
+20
+21
+22
+@end example
+
@node csplit invocation
@section @command{csplit}: Split a file into context-determined pieces
In such cases, running @command{\cmd\} via @command{xargs} is undesirable
because it splits the list into pieces and makes @command{\cmd\} print
\subListOutput\ for each sublist rather than for the entire list.
-One way to produce a list of @acronym{ASCII} @sc{nul} terminated file names is with @sc{gnu}
+One way to produce a list of @acronym{ASCII} @sc{nul} terminated file
+names is with @sc{gnu}
@command{find}, using its @option{-print0} predicate.
-If @var{file} is @samp{-} then the @acronym{ASCII} @sc{nul} terminated file names
-are read from standard input.
+If @var{file} is @samp{-} then the @acronym{ASCII} @sc{nul} terminated
+file names are read from standard input.
@end macro
@filesZeroFromOption{wc,,a total}
@opindex --sort
@cindex general numeric sort
@vindex LC_NUMERIC
-Sort numerically, using the standard C function @code{strtold} to convert
-a prefix of each line to a long double-precision floating point number.
-This allows floating point numbers to be specified in scientific notation,
-like @code{1.0e-34} and @code{10e100}.
-The @env{LC_NUMERIC} locale determines the decimal-point character.
+Sort numerically, converting a prefix of each line to a long
+double-precision floating point number. @xref{Floating point}.
Do not report overflow, underflow, or conversion errors.
Use the following collating sequence:
@item --parallel=@var{n}
@opindex --parallel
@cindex multithreaded sort
-Limit the number of sorts run in parallel to @var{n}. By default,
-@var{n} is set to the number of available processors, and values
-greater than that are reduced to that limit. Also see
-@ref{nproc invocation}.
+Set the number of sorts run in parallel to @var{n}. By default,
+@var{n} is set to the number of available processors, but limited
+to 8, as there are diminishing performance gains after that.
+Note also that using @var{n} threads increases the memory usage by
+a factor of log @var{n}. Also see @ref{nproc invocation}.
@item -u
@itemx --unique
Historical (BSD and System V) implementations of @command{sort} have
differed in their interpretation of some options, particularly
-@option{-b}, @option{-f}, and @option{-n}. @sc{gnu} sort follows the @acronym{POSIX}
+@option{-b}, @option{-f}, and @option{-n}.
+@sc{gnu} sort follows the @acronym{POSIX}
behavior, which is usually (but not always!) like the System V behavior.
According to @acronym{POSIX}, @option{-n} no longer implies @option{-b}. For
consistency, @option{-M} has been changed in the same way. This may
@c and converting each @samp{\0} back to the original record delimiter.
@c
@c @example
-@c printf 'c\n\nb\n\na\n'|perl -0pe 's/\n\n/\n\0/g'|sort -z|perl -0pe 's/\0/\n/g'
+@c printf 'c\n\nb\n\na\n' |
+@c perl -0pe 's/\n\n/\n\0/g' |
+@c sort -z |
+@c perl -0pe 's/\0/\n/g'
@c @end example
@item
@macro checkOrderOption{cmd}
If the @option{--check-order} option is given, unsorted inputs will
cause a fatal error message. If the option @option{--nocheck-order}
-is given, unsorted inputs will never cause an error message. If
-neither of these options is given, wrongly sorted inputs are diagnosed
-only if an input file is found to contain unpairable lines. If an
-input file is diagnosed as being unsorted, the @command{\cmd\} command
-will exit with a nonzero status (and the output should not be used).
+is given, unsorted inputs will never cause an error message. If neither
+of these options is given, wrongly sorted inputs are diagnosed
+only if an input file is found to contain unpairable
+@ifset JOIN_COMMAND
+lines, and when both input files are non empty.
+@end ifset
+@ifclear JOIN_COMMAND
+lines.
+@end ifclear
+If an input file is diagnosed as being unsorted, the @command{\cmd\}
+command will exit with a nonzero status (and the output should not be used).
Forcing @command{\cmd\} to process wrongly sorted input files
containing unpairable lines by specifying @option{--nocheck-order} is
processing. Each output line will look like:
@smallexample
-.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}" "@var{head}" "@var{ref}"
+.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}"@c
+ "@var{head}" "@var{ref}"
@end smallexample
so it will be possible to write a @samp{.xx} roff macro to take care of
line will look like:
@smallexample
-\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@{@var{after}@}@{@var{head}@}@{@var{ref}@}
+\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@c
+@{@var{after}@}@{@var{head}@}@{@var{ref}@}
@end smallexample
@noindent
Fields are separated by a TAB character by default. Also print any
line that contains no delimiter character, unless the
@option{--only-delimited} (@option{-s}) option is specified.
-Note @command{cut} does not support specifying runs of whitespace as a
-delimiter, so to achieve that common functionality one can pre-process
-with @command{tr} like:
+
+Note @command{awk} supports more sophisticated field processing,
+and by default will use (and discard) runs of blank characters to
+separate fields, and ignore leading and trailing blanks.
@example
-tr -s '[:blank:]' '\t' | cut -f@dots{}
+@verbatim
+awk '{print $2}' # print the second field
+awk '{print $NF-1}' # print the penultimate field
+awk '{print $2,$1}' # reorder the first two fields
+@end verbatim
+@end example
+
+In the unlikely event that @command{awk} is unavailable,
+one can use the @command{join} command, to process blank
+characters as @command{awk} does above.
+@example
+@verbatim
+join -a1 -o 1.2 - /dev/null # print the second field
+join -a1 -o 1.2,1.1 - /dev/null # reorder the first two fields
+@end verbatim
@end example
@item -d @var{input_delim_byte}
b b1 b2
@end example
+@set JOIN_COMMAND
@checkOrderOption{join}
+@clear JOIN_COMMAND
The defaults are:
@itemize
@item -e @var{string}
@opindex -e
-Replace those output fields that are missing in the input with
-@var{string}.
+Replace those output fields that are missing in the input with @var{string}.
+I.E. missing fields specified with the @option{-12jo} options.
@item --header
@opindex --header
Equivalent to @option{-1 @var{field} -2 @var{field}}.
@item -o @var{field-list}
-Construct each output line according to the format in @var{field-list}.
-Each element in @var{field-list} is either the single character @samp{0} or
-has the form @var{m.n} where the file number, @var{m}, is @samp{1} or
-@samp{2} and @var{n} is a positive field number.
+@itemx -o auto
+If the keyword @samp{auto} is specified, infer the output format from
+the first line in each file. This is the same as the default output format
+but also ensures the same number of fields are output for each line.
+Missing fields are replaced with the @option{-e} option and extra fields
+are discarded.
+
+Otherwise, construct each output line according to the format in
+@var{field-list}. Each element in @var{field-list} is either the single
+character @samp{0} or has the form @var{m.n} where the file number, @var{m},
+is @samp{1} or @samp{2} and @var{n} is a positive field number.
A field specification of @samp{0} denotes the join field.
In most cases, the functionality of the @samp{0} field spec
@item \v
Control-K.
@item \@var{ooo}
-The character with the value given by @var{ooo}, which is 1 to 3
-octal digits,
+The 8-bit character with the value given by @var{ooo}, which is 1 to 3
+octal digits. Note that @samp{\400} is interpreted as the two-byte
+sequence, @samp{\040} @samp{0}.
@item \\
A backslash.
@end table
@noindent
By the way, the above idiom is not portable because it uses ranges, and
it assumes that the octal code for newline is 012.
-Assuming a @acronym{POSIX} compliant @command{tr}, here is a better way to write it:
+Assuming a @acronym{POSIX} compliant @command{tr}, here is a better
+way to write it:
@example
tr -cs '[:alnum:]' '[\n*]'
@command{less} usually produces unreadable results. However, using
@code{more -f} does seem to work.
+@vindex LS_COLORS
+@vindex SHELL @r{environment variable, and color}
+Note that using the @option{--color} option may incur a noticeable
+performance penalty when run in a directory with very many entries,
+because the default settings require that @command{ls} @code{stat} every
+single file it lists.
+However, if you would like most of the file-type coloring
+but can live without the other coloring options (e.g.,
+executable, orphan, sticky, other-writable, capability), use
+@command{dircolors} to set the @env{LS_COLORS} environment variable like this,
+@example
+eval $(dircolors -p | perl -pe \
+ 's/^((CAP|S[ET]|O[TR]|M|E)\w+).*/$1 00/' | dircolors -)
+@end example
+and on a @code{dirent.d_type}-capable file system, @command{ls}
+will perform only one @code{stat} call per command line argument.
+
@item -F
@itemx --classify
@itemx --indicator-style=classify
This makes @command{dd} read and write @var{bytes} per block,
overriding any @samp{ibs} and @samp{obs} settings.
In addition, if no data-transforming @option{conv} option is specified,
-each input block is copied to the output as a single block,
-without aggregating short reads.
+input is copied to the output as soon as it's read,
+even if it is smaller than the block size.
@item cbs=@var{bytes}
@opindex cbs
when an odd number of bytes are read---the last byte is simply copied
(since there is nothing to swap it with).
-@item noerror
-@opindex noerror
-@cindex read errors, ignoring
-Continue after read errors.
+@item sync
+@opindex sync @r{(padding with @acronym{ASCII} @sc{nul}s)}
+Pad every input block to size of @samp{ibs} with trailing zero bytes.
+When used with @samp{block} or @samp{unblock}, pad with spaces instead of
+zero bytes.
-@item nocreat
-@opindex nocreat
-@cindex creating output file, avoiding
-Do not create the output file; the output file must already exist.
+@end table
+The following ``conversions'' are really file flags
+and don't affect internal processing:
+
+@table @samp
@item excl
@opindex excl
@cindex creating output file, requiring
Fail if the output file already exists; @command{dd} must create the
output file itself.
+@item nocreat
+@opindex nocreat
+@cindex creating output file, avoiding
+Do not create the output file; the output file must already exist.
+
The @samp{excl} and @samp{nocreat} conversions are mutually exclusive.
@item notrunc
@cindex truncating output file, avoiding
Do not truncate the output file.
-@item sync
-@opindex sync @r{(padding with @acronym{ASCII} @sc{nul}s)}
-Pad every input block to size of @samp{ibs} with trailing zero bytes.
-When used with @samp{block} or @samp{unblock}, pad with spaces instead of
-zero bytes.
+@item noerror
+@opindex noerror
+@cindex read errors, ignoring
+Continue after read errors.
@item fdatasync
@opindex fdatasync
@cindex synchronized data and metadata I/O
Use synchronized I/O for both data and metadata.
+@item nocache
+@opindex nocache
+@cindex discarding file cache
+Discard the data cache for a file.
+When count=0 all cache is discarded,
+otherwise the cache is dropped for the processed
+portion of the file. Also when count=0
+failure to discard the cache is diagnosed
+and reflected in the exit status.
+Here as some usage examples:
+
+@example
+# Advise to drop cache for whole file
+dd if=ifile iflag=nocache count=0
+
+# Ensure drop cache for the whole file
+dd of=ofile oflag=nocache conv=notrunc,fdatasync count=0
+
+# Drop cache for part of file
+dd if=ifile iflag=nocache skip=10 count=10 of=/dev/null
+
+# Stream data using just the read-ahead cache
+dd if=ifile of=ofile iflag=nocache oflag=nocache
+@end example
+
@item nonblock
@opindex nonblock
@cindex nonblocking I/O
when it might be a symlink to a directory.
Otherwise, @command{mv} may do something very surprising, since
its behavior depends on the underlying rename system call.
-On a system with a modern Linux-based kernel, it fails with @code{errno=ENOTDIR}.
+On a system with a modern Linux-based kernel, it fails with
+@code{errno=ENOTDIR}.
However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently
renames not the symlink but rather the directory referenced by the symlink.
@xref{Trailing slashes}.
@opindex -x
@opindex --exact
By default, @command{shred} rounds the size of a regular file up to the next
-multiple of the file system block size to fully erase the last block of the file.
+multiple of the file system block size to fully erase the last block
+of the file.
Use @option{--exact} to suppress that behavior.
Thus, by default if you shred a 10-byte regular file on a system with 512-byte
blocks, the resulting file will be 512 bytes long. With this option,
shred --verbose /dev/sda5
@end example
+On modern disks, a single pass should be adequate,
+and it will take one third the time of the default three-pass approach.
+
+@example
+# 1 pass, write pseudo-random data; 3x faster than the default
+shred --verbose -n1 /dev/sda5
+@end example
+
+To be on the safe side, use at least one pass that overwrites using
+pseudo-random data. I.e., don't be tempted to use @samp{-n0 --zero},
+in case some disk controller optimizes the process of writing blocks
+of all zeros, and thereby does not clear all bytes in a block.
+Some SSDs may do just that.
+
A @var{file} of @samp{-} denotes standard output.
The intended use of this is to shred a removed temporary file.
For example:
Synopsis:
@example
-chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@} @var{file}@dots{}
+chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
@end example
If used, @var{new-owner} specifies the new owner and/or group as follows
or to the group of an existing reference file. Synopsis:
@example
-chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@} @var{file}@dots{}
+chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
@end example
If @var{group} is intended to represent a
@command{chmod} changes the access permissions of the named files. Synopsis:
@example
-chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@} @var{file}@dots{}
+chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
@end example
@cindex symbolic links, permissions of
If an argument @var{file} is a disk device file containing a mounted
file system, @command{df} shows the space available on that file system
rather than on the file system containing the device node (i.e., the root
-file system). @sc{gnu} @command{df} does not attempt to determine the disk usage
+file system). @sc{gnu} @command{df} does not attempt to determine the
+disk usage
on unmounted file systems, because on most kinds of systems doing so
requires extremely nonportable intimate knowledge of file system
structures.
The @samp{%W}, @samp{%X}, @samp{%Y}, and @samp{%Z} formats accept a
precision preceded by a period to specify the number of digits to
-print after the decimal point. For example, @samp{%.9X} outputs the
-last access time to nanosecond precision. If a period is given but no
-precision, @command{stat} uses the estimated precision of the file
-system. When discarding excess precision, time stamps are truncated
+print after the decimal point. For example, @samp{%.3X} outputs the
+last access time to millisecond precision. If a period is given but no
+precision, @command{stat} uses 9 digits, so @samp{%.X} is equivalent to
+@samp{%.9X}. When discarding excess precision, time stamps are truncated
toward minus infinity.
@example
$ stat -c '[%.3Y]' /usr
[1288929712.114]
$ stat -c '[%.Y]' /usr
- [1288929712.114951]
+ [1288929712.114951834]
@end example
The mount point printed by @samp{%m} is similar to that output
backslash
@item \0@var{nnn}
the eight-bit value that is the octal number @var{nnn}
-(zero to three octal digits)
+(zero to three octal digits), if @var{nnn} is
+a nine-bit value, the ninth bit is ignored
@item \@var{nnn}
the eight-bit value that is the octal number @var{nnn}
-(one to three octal digits)
+(one to three octal digits), if @var{nnn} is
+a nine-bit value, the ninth bit is ignored
@item \x@var{hh}
the eight-bit value that is the hexadecimal number @var{hh}
(one or two hexadecimal digits)
@command{printf} has an additional directive, @samp{%b}, which prints its
argument string with @samp{\} escapes interpreted in the same way as in
the @var{format} string, except that octal escapes are of the form
-@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits.
+@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits. If
+@samp{\@var{ooo}} is nine-bit value, ignore the ninth bit.
If a precision is also given, it limits the number of bytes printed
from the converted string.
current locale. For example, in a locale whose radix character is a
comma, the command @samp{printf %g 3.14} outputs @samp{3,14} whereas
the command @samp{printf %g 3,14} is an error.
+@xref{Floating point}.
@kindex \@var{ooo}
@kindex \x@var{hh}
@command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number
-(if @var{ooo} is 1 to 3 octal digits) specifying a character to print,
+(if @var{ooo} is 1 to 3 octal digits) specifying a byte to print,
and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex
digits) specifying a character to print.
+Note however that when @samp{\@var{ooo}} specifies a number larger than 255,
+@command{printf} ignores the ninth bit.
+For example, @samp{printf '\400'} is equivalent to @samp{printf '\0'}.
@kindex \uhhhh
@kindex \Uhhhhhhhh
If @var{expression} is omitted, @command{test} returns false.
If @var{expression} is a single argument,
-@command{test} returns false if the argument is null and true otherwise. The argument
+@command{test} returns false if the argument is null and true
+otherwise. The argument
can be any string, including strings like @samp{-d}, @samp{-1},
@samp{--}, @samp{--help}, and @samp{--version} that most other
programs would treat as options. To get help and version information,
* File type tests:: -[bcdfhLpSt]
* Access permission tests:: -[gkruwxOG]
* File characteristic tests:: -e -s -nt -ot -ef
-* String tests:: -z -n = !=
+* String tests:: -z -n = == !=
* Numeric tests:: -eq -ne -lt -le -gt -ge
* Connectives for test:: ! -a -o
@end menu
@cindex equal string check
True if the strings are equal.
+@item @var{string1} == @var{string2}
+@opindex ==
+@cindex equal string check
+True if the strings are equal (synonym for =).
+
@item @var{string1} != @var{string2}
@opindex !=
@cindex not-equal string check
@opindex --file
Set the line opened by the file name specified in @var{device} instead of
the tty line connected to standard input. This option is necessary
-because opening a @acronym{POSIX} tty requires use of the @code{O_NONDELAY} flag to
-prevent a @acronym{POSIX} tty from blocking until the carrier detect line is high if
+because opening a @acronym{POSIX} tty requires use of the
+@code{O_NONDELAY} flag to prevent a @acronym{POSIX} tty from blocking
+until the carrier detect line is high if
the @code{clocal} flag is not set. Hence, it is not always possible
to allow the shell to open the device in the traditional manner.
of course).
Some settings are not available on all @acronym{POSIX} systems, since they use
-extensions. Such arguments are marked below with ``Non-@acronym{POSIX}'' in their
-description. On non-@acronym{POSIX} systems, those or other settings also may not
+extensions. Such arguments are marked below with
+``Non-@acronym{POSIX}'' in their description. On non-@acronym{POSIX}
+systems, those or other settings also may not
be available, but it's not feasible to document all the variations: just
try it and see.
@item ofill
@opindex ofill
@cindex pad instead of timing for delaying
-Use fill (padding) characters instead of timing for delays. Non-@acronym{POSIX}.
+Use fill (padding) characters instead of timing for delays.
+Non-@acronym{POSIX}.
May be negated.
@item ofdel
@opindex crtkill
Echo the @code{kill} special character by erasing each character on
the line as indicated by the @code{echoprt} and @code{echoe} settings,
-instead of by the @code{echoctl} and @code{echok} settings. Non-@acronym{POSIX}.
+instead of by the @code{echoctl} and @code{echok} settings.
+Non-@acronym{POSIX}.
May be negated.
@end table
@item rows @var{n}
@opindex rows
-Tell the tty kernel driver that the terminal has @var{n} rows. Non-@acronym{POSIX}.
+Tell the tty kernel driver that the terminal has @var{n} rows.
+Non-@acronym{POSIX}.
@item cols @var{n}
@itemx columns @var{n}
@smallexample
uname -a
-@result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686 unknown unknown GNU/Linux
+@result{} Linux dum 2.2.18 #4 SMP Tue Jun 5 11:24:08 PDT 2001 i686@c
+ unknown unknown GNU/Linux
@end smallexample
@smallexample
chcon [@var{option}]@dots{} @var{context} @var{file}@dots{}
-chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}] [-t @var{type}] @var{file}@dots{}
+chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}]@c
+ [-t @var{type}] @var{file}@dots{}
chcon [@var{option}]@dots{} --reference=@var{rfile} @var{file}@dots{}
@end smallexample
Synopses:
@smallexample
runcon @var{context} @var{command} [@var{args}]
-runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}] [-l @var{range}] @var{command} [@var{args}]
+runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}]@c
+ [-l @var{range}] @var{command} [@var{args}]
@end smallexample
Run @var{command} with completely-specified @var{context}, or with
Any additional arguments after @var{command}
are interpreted as arguments to the command.
-With neither @var{context} nor @var{command}, print the current security context.
+With neither @var{context} nor @var{command}, print the current
+security context.
The program accepts the following options. Also see @ref{Common options}.
Historical implementations of @command{sleep} have required that
@var{number} be an integer, and only accepted a single argument
without a suffix. However, GNU @command{sleep} accepts
-arbitrary floating point numbers (using a period before any fractional
-digits).
+arbitrary floating point numbers. @xref{Floating point}.
The only options are @option{--help} and @option{--version}. @xref{Common
options}.
even when @var{first} is larger than @var{last}.
@var{first} also defaults to @samp{1}. So @code{seq 1} prints
@samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
-Floating-point numbers
-may be specified (using a period before any fractional digits).
+Floating-point numbers may be specified. @xref{Floating point}.
The program accepts the following options. Also see @ref{Common options}.
Options must precede operands.
On most systems, seq can produce whole-number output for values up to
at least @math{2^{53}}. Larger integers are approximated. The details
-differ depending on your floating-point implementation, but a common
+differ depending on your floating-point implementation.
+@xref{Floating point}. A common
case is that @command{seq} works with integers through @math{2^{64}},
and larger integers may not be numerically correct:
@unnumberedsec Toolbox Introduction
This month's column is only peripherally related to the GNU Project, in
-that it describes a number of the GNU tools on your GNU/Linux system and how they
+that it describes a number of the GNU tools on your GNU/Linux system
+and how they
might be used. What it's really about is the ``Software Tools'' philosophy
of program development and usage.
@unnumberedsec Putting the Tools Together
Now, let's suppose this is a large ISP server system with dozens of users
-logged in. The management wants the system administrator to write a program that will
+logged in. The management wants the system administrator to write a
+program that will
generate a sorted list of logged in users. Furthermore, even if a user
is logged in multiple times, his or her name should only show up in the
output once.
@command{uniq} does. However, @command{uniq} has other uses for which one
cannot substitute @samp{sort -u}.
-The administrator puts this pipeline into a shell script, and makes it available for
+The administrator puts this pipeline into a shell script, and makes it
+available for
all the users on the system (@samp{#} is the system administrator,
or @code{root}, prompt):
projects / platform / upstream / coreutils.git / blobdiff