diff options
Diffstat (limited to 'doc/coreutils.texi')
| -rw-r--r-- | doc/coreutils.texi | 755 |
1 files changed, 533 insertions, 222 deletions
diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 2c16dc48..19a523d8 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -2,6 +2,8 @@ @c %**start of header @setfilename coreutils.info @settitle GNU Coreutils +@documentencoding UTF-8 +@allowcodebreaks false @c %**end of header @@ -45,6 +47,7 @@ * chroot: (coreutils)chroot invocation. Specify the root directory. * cksum: (coreutils)cksum invocation. Print POSIX CRC checksum. * comm: (coreutils)comm invocation. Compare sorted files by line. +* coreutils: (coreutils)coreutils invocation. Multi-call program. * cp: (coreutils)cp invocation. Copy files. * csplit: (coreutils)csplit invocation. Split by context. * cut: (coreutils)cut invocation. Print selected parts of lines. @@ -68,7 +71,7 @@ * hostid: (coreutils)hostid invocation. Print numeric host identifier. * hostname: (coreutils)hostname invocation. Print or set system name. * id: (coreutils)id invocation. Print user identity. -* install: (coreutils)install invocation. Copy and change attributes. +* install: (coreutils)install invocation. Copy files and set attributes. * join: (coreutils)join invocation. Join lines on a common field. * kill: (coreutils)kill invocation. Send a signal to processes. * link: (coreutils)link invocation. Make hard links between files. @@ -95,7 +98,7 @@ * ptx: (coreutils)ptx invocation. Produce permuted indexes. * pwd: (coreutils)pwd invocation. Print working directory. * readlink: (coreutils)readlink invocation. Print referent of a symlink. -* realpath: (coreutils)readpath invocation. Print resolved file names. +* realpath: (coreutils)realpath invocation. Print resolved file names. * rm: (coreutils)rm invocation. Remove files. * rmdir: (coreutils)rmdir invocation. Remove empty directories. * runcon: (coreutils)runcon invocation. Run in specified SELinux CTX. @@ -140,7 +143,7 @@ This manual documents version @value{VERSION} of the GNU core utilities, including the standard programs for text and file manipulation. -Copyright @copyright{} 1994-2013 Free Software Foundation, Inc. +Copyright @copyright{} 1994-2014 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -220,13 +223,14 @@ Common 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 +* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax * Random sources:: Sources of random data * Target directory:: Target directory * Trailing slashes:: Trailing slashes * Traversing symlinks:: Traversing symlinks to directories * Treating / specially:: Treating / specially * Standards conformance:: Standards conformance +* coreutils invocation:: Multi-call binary invocation Output of entire files @@ -243,8 +247,6 @@ Formatting file contents * pr invocation:: Paginate or columnate files for printing * fold invocation:: Wrap input lines to fit in specified width -@command{numfmt}: General Options, Units - Output of parts of files * head invocation:: Output the first part of files @@ -543,7 +545,7 @@ insights to the overall process. @macro optBackup @item -b -@itemx @w{@kbd{--backup}[=@var{method}]} +@itemx --backup[=@var{method}] @opindex -b @opindex --backup @vindex VERSION_CONTROL @@ -563,7 +565,7 @@ Append @var{suffix} to each backup file made with @option{-b}. @macro optTargetDirectory @item -t @var{directory} -@itemx @w{@kbd{--target-directory}=@var{directory}} +@itemx --target-directory=@var{directory} @opindex -t @opindex --target-directory @cindex target directory @@ -583,16 +585,42 @@ Do not treat the last operand specially when it is a directory or a symbolic link to a directory. @xref{Target directory}. @end macro -@macro optNull{cmd} -@item -0 -@opindex -0 -@itemx --null -@opindex --null +@macro outputNUL @cindex output NUL-byte-terminated lines Output a zero byte (ASCII NUL) at the end of each line, rather than a newline. This option enables other programs to parse the -output of @command{\cmd\} even when that output would contain data -with embedded newlines. +output even when that output would contain data with embedded newlines. +@end macro + +@macro optNull +@item -0 +@itemx --null +@opindex -0 +@opindex --null +@outputNUL +@end macro + +@macro optZero +@item -z +@itemx --zero +@opindex -z +@opindex --zero +@outputNUL +@end macro + +@macro optZeroTerminated +@item -z +@itemx --zero-terminated +@opindex -z +@opindex --zero-terminated +@cindex process zero-terminated items +Delimit items with a zero byte rather than a newline (ASCII LF). +I.e., treat input as items separated by ASCII NUL +and terminate output items with ASCII NUL. +This option can be useful in conjunction with @samp{perl -0} or +@samp{find -print0} and @samp{xargs -0} which do the same in order to +reliably handle arbitrary file names (even those containing blanks +or other special characters). @end macro @macro optSi @@ -620,7 +648,7 @@ Use the @option{--si} option if you prefer powers of 1000. @end macro @macro optStripTrailingSlashes -@item @w{@kbd{--strip-trailing-slashes}} +@item --strip-trailing-slashes @opindex --strip-trailing-slashes @cindex stripping trailing slashes Remove any trailing slashes from each @var{source} argument. @@ -737,7 +765,7 @@ name. * 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 +* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax * Random sources:: --random-source, in some programs. * Target directory:: Specifying a target directory, in some programs. * Trailing slashes:: --strip-trailing-slashes, in some programs. @@ -745,6 +773,7 @@ name. * Treating / specially:: --preserve-root and --no-preserve-root. * Special built-in utilities:: @command{break}, @command{:}, @dots{} * Standards conformance:: Conformance to the POSIX standard. +* coreutils invocation:: Multi-call binary invocation. @end menu @@ -786,7 +815,7 @@ briefly mentioned in the descriptions of the particular programs. @table @samp @item -b -@itemx @w{@kbd{--backup}[=@var{method}]} +@itemx --backup[=@var{method}] @opindex -b @opindex --backup @vindex VERSION_CONTROL @@ -1014,7 +1043,9 @@ option is equivalent to @option{--block-size=1K}, which is the default unless the @env{POSIXLY_CORRECT} environment variable is set. The @option{-h} or @option{--human-readable} option is equivalent to @option{--block-size=human-readable}. The @option{--si} option is -equivalent to @option{--block-size=si}. +equivalent to @option{--block-size=si}. Note for @command{ls} +the @option{-k} option does not control the display of the +apparent file sizes, whereas the @option{--block-size} option does. @node Floating point @section Floating point numbers @@ -1134,20 +1165,20 @@ also support at least eight real-time signals called @samp{RTMIN}, @samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}. @node Disambiguating names and IDs -@section chown and chgrp: Disambiguating user names and IDs +@section chown, chgrp, chroot, id: Disambiguating user names and IDs @cindex user names, disambiguating @cindex user IDs, disambiguating @cindex group names, disambiguating @cindex group IDs, disambiguating @cindex disambiguating group names and IDs -Since the @var{owner} and @var{group} arguments to @command{chown} and -@command{chgrp} may be specified as names or numeric IDs, there is an +Since the @var{user} and @var{group} arguments to these commands +may be specified as names or numeric IDs, there is an apparent ambiguity. What if a user or group @emph{name} is a string of digits? @footnote{Using a number as a user name is common in some environments.} Should the command interpret it as a user name or as an ID@? -POSIX requires that @command{chown} and @command{chgrp} +POSIX requires that these commands 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, @@ -1156,9 +1187,9 @@ and it must work even in a pathological situation where Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to 1000---not what you intended. -GNU @command{chown} and @command{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. +GNU @command{chown}, @command{chgrp}, @command{chroot}, and @command{id} +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 @samp{+}, in order to force its interpretation as an integer: @@ -1168,8 +1199,7 @@ chgrp +$numeric_group_id another-file chown +0:+0 / @end example -GNU @command{chown} and @command{chgrp} -skip the name look-up process for each @samp{+}-prefixed string, +The name look-up process is skipped for each @samp{+}-prefixed string, because a string containing @samp{+} is never a valid user or group name. This syntax is accepted on most common Unix systems, but not on Solaris 10. @@ -1242,7 +1272,7 @@ treated as a directory and want a diagnostic otherwise, you can use the @option{--target-directory} (@option{-t}) option. @item -t @var{directory} -@itemx @w{@kbd{--target-directory}=@var{directory}} +@itemx --target-directory=@var{directory} @opindex --target-directory @cindex target directory @cindex destination directory @@ -1265,7 +1295,7 @@ 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 @w{@kbd{--target-directory}} (@option{-t}) option allows the @command{cp}, +The @option{--target-directory} (@option{-t}) option allows the @command{cp}, @command{install}, @command{ln}, and @command{mv} programs to be used conveniently with @command{xargs}. For example, you can move the files from the current directory to a sibling directory, @code{d} like this: @@ -1309,7 +1339,7 @@ options cannot be combined. Some GNU programs (at least @command{cp} and @command{mv}) allow you to remove any trailing slashes from each @var{source} argument before -operating on it. The @w{@kbd{--strip-trailing-slashes}} option enables +operating on it. The @option{--strip-trailing-slashes} option enables this behavior. This is useful when a @var{source} argument may have a trailing slash and @@ -1467,6 +1497,22 @@ that assumes an older version of 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. +@node coreutils invocation +@section @command{coreutils}: Multi-call binary + +@pindex multicall +@cindex combined +@cindex calling combined multi-call binary + +@command{coreutils} invokes an individual utility, either +implicitly selected by the last component of @samp{argv[0]}, +or by explicitly calling @command{coreutils} with the +@option{--coreutils-prog} option. Synopsis: + +@example +coreutils @option{--coreutils-prog=PROGRAM} @dots{} +@end example + @node Output of entire files @chapter Output of entire files @@ -1868,6 +1914,16 @@ none (do not print offsets). The default is octal. +@item --endian=@var{order} +@opindex --endian +@cindex byte-swapping +@cindex endianness +Reorder input bytes, to handle inputs with differing byte orders, +or to provide consistent output independent of the endian convention +of the current system. Swapping is performed according to the +specified @option{--type} size and endian @var{order}, which can be +@samp{little} or @samp{big}. + @item -j @var{bytes} @itemx --skip-bytes=@var{bytes} @opindex -j @@ -1910,14 +1966,15 @@ of each output line using each of the data types that you specified, in the order that you specified. Adding a trailing ``z'' to any type specification appends a display -of the ASCII character representation of the printable characters +of the single byte character representation of the printable characters to the output line generated by the type specification. @table @samp @item a named character, ignoring high-order bit @item c -ASCII character or backslash escape, +printable single byte character, C backslash escape +or a 3 digit octal sequence @item d signed decimal @item f @@ -2005,8 +2062,8 @@ Output as octal bytes. Equivalent to @samp{-t o1}. @item -c @opindex -c -Output as ASCII characters or backslash escapes. Equivalent to -@samp{-t c}. +Output as printable single byte characters, C backslash escapes +or 3 digit octal sequences. Equivalent to @samp{-t c}. @item -d @opindex -d @@ -2282,10 +2339,12 @@ Convert the number in input field @var{n} (default: 1). @item --format=@var{format} @opindex --format Use printf-style floating FORMAT string. The @var{format} string must contain -one @samp{%f} directive, optionally with @samp{'}, @samp{-}, or width +one @samp{%f} directive, optionally with @samp{'}, @samp{-}, @samp{0}, or width modifiers. The @samp{'} modifier will enable @option{--grouping}, the @samp{-} modifier will enable left-aligned @option{--padding} and the width modifier will -enable right-aligned @option{--padding}. +enable right-aligned @option{--padding}. The @samp{0} width modifier +(without the @samp{-} modifier) will generate leading zeros on the number, +up to the specified width. @item --from=@var{unit} @opindex --from @@ -2443,7 +2502,7 @@ are interpreted as @emph{IEC} values. Converting a single number from/to @emph{human} representation: @example -$ nunfmt --to=si 500000 +$ numfmt --to=si 500000 500K $ numfmt --to=iec 500000 @@ -2867,8 +2926,10 @@ Print nonprinting characters in octal backslash notation. @opindex -w @opindex --width Set page width to @var{page_width} characters for multiple text-column -output only (default for @var{page_width} is 72). @option{-s[CHAR]} turns -off the default page width and any line truncation and column alignment. +output only (default for @var{page_width} is 72). The specified +@var{page_width} is rounded down so that columns have equal width. +@option{-s[CHAR]} turns off the default page width and any line truncation +and column alignment. Lines of full length are merged, regardless of the column options set. No @var{page_width} setting is possible with single column output. A POSIX-compliant formulation. @@ -2877,12 +2938,13 @@ A POSIX-compliant formulation. @itemx --page_width=@var{page_width} @opindex -W @opindex --page_width -Set the page width to @var{page_width} characters. That's valid with and -without a column option. Text lines are truncated, unless @option{-J} -is used. Together with one of the three column options +Set the page width to @var{page_width} characters, honored with and +without a column option. With a column option, the specified @var{page_width} +is rounded down so that columns have equal width. Text lines are truncated, +unless @option{-J} is used. Together with one of the three column options (@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column alignment is always used. The separator options @option{-S} or @option{-s} -don't affect the @option{-W} option. Default is 72 characters. Without +don't disable the @option{-W} option. Default is 72 characters. Without @option{-W @var{page_width}} and without any of the column options NO line truncation is used (defined to keep downward compatibility and to meet most frequent tasks). That's equivalent to @option{-W 72 -J}@. The header @@ -3156,9 +3218,17 @@ will keep trying until it becomes accessible again. @item --retry @opindex --retry -This option is useful mainly when following by name (i.e., with -@option{--follow=name}). -Without this option, when tail encounters a file that doesn't +Indefinitely try to open the specified file. +This option is useful mainly when following (and otherwise issues a warning). + +When following by file descriptor (i.e., with @option{--follow=descriptor}), +this option only affects the initial open of the file, as after a successful +open, @command{tail} will start following the file descriptor. + +When following by name (i.e., with @option{--follow=name}), @command{tail} +infinitely retries to re-open the given files until killed. + +Without this option, when @command{tail} encounters a file that doesn't exist or is otherwise inaccessible, it reports that fact and never checks it again. @@ -3608,6 +3678,12 @@ long instead of the default 2. @opindex --keep-files Do not remove output files when errors are encountered. +@item --suppress-matched +@opindex --suppress-matched +Do not output lines matching the specified @var{pattern}. +I.E. suppress the boundary line from the start of the second +and subsequent splits. + @item -z @itemx --elide-empty-files @opindex -z @@ -3684,6 +3760,25 @@ $ head xx* 14 @end example +Example of splitting input by empty lines: + +@example +$ csplit --suppress-matched @var{input.txt} '/^$/' '@{*@}' +@end example + +@c +@c TODO: "uniq" already supports "--group". +@c when it gets the "--key" option, uncomment this example. +@c +@c Example of splitting input file, based on the value of column 2: +@c +@c @example +@c $ cat @var{input.txt} | +@c sort -k2,2 | +@c uniq --group -k2,2 | +@c csplit -m '/^$/' '@{*@}' +@c @end example + @node Summarizing files @chapter Summarizing files @@ -4334,6 +4429,9 @@ the @command{df}, @command{du}, or @command{ls} commands that are invoked with their @option{--human-readable} or @option{--si} options. The syntax for numbers is the same as for the @option{--numeric-sort} option; the SI suffix must immediately follow the number. +Note also the @command{numfmt} command, which can be used to reformat +numbers to human format @emph{after} the sort, thus often allowing +sort to operate on more accurate numbers. @item -i @itemx --ignore-nonprinting @@ -4621,21 +4719,7 @@ For example, @code{sort -n -u} inspects only the value of the initial numeric string when checking for uniqueness, whereas @code{sort -n | uniq} inspects the entire line. @xref{uniq invocation}. -@macro zeroTerminatedOption -@item -z -@itemx --zero-terminated -@opindex -z -@opindex --zero-terminated -@cindex process zero-terminated items -Delimit items with a zero byte rather than a newline (ASCII LF). -I.e., treat input as items separated by ASCII NUL -and terminate output items with ASCII NUL. -This option can be useful in conjunction with @samp{perl -0} or -@samp{find -print0} and @samp{xargs -0} which do the same in order to -reliably handle arbitrary file names (even those containing blanks -or other special characters). -@end macro -@zeroTerminatedOption +@optZeroTerminated @end table @@ -4910,7 +4994,19 @@ commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}. Use @var{file} as a source of random data used to determine which permutation to generate. @xref{Random sources}. -@zeroTerminatedOption +@item -r +@itemx --repeat +@opindex -r +@opindex --repeat +@cindex repeat output values +Repeat output values, that is, select with replacement. With this +option the output is not a permutation of the input; instead, each +output line is randomly chosen from all the inputs. This option is +typically combined with @option{--head-count}; if +@option{--head-count} is not given, @command{shuf} repeats +indefinitely. + +@optZeroTerminated @end table @@ -4963,12 +5059,26 @@ and the command @samp{shuf -i 1-4} might output: @end example @noindent -These examples all have four input lines, so @command{shuf} might +The above examples all have four input lines, so @command{shuf} might produce any of the twenty-four possible permutations of the input. In general, if there are @var{n} input lines, there are @var{n}! (i.e., @var{n} factorial, or @var{n} * (@var{n} - 1) * @dots{} * 1) possible output permutations. +@noindent +To output 50 random numbers each in the range 0 through 9, use: + +@example +shuf -r -n 50 -i 0-9 +@end example + +@noindent +To simulate 100 coin flips, use: + +@example +shuf -r -n 100 -e Head Tail +@end example + @exitstatus @@ -5067,7 +5177,7 @@ Do not discard the second and subsequent repeated input lines, but discard lines that are not repeated. This option is useful mainly in conjunction with other options e.g., to ignore case or to compare only selected fields. -The optional @var{delimit-method} tells how to delimit +The optional @var{delimit-method} specifies how to delimit groups of repeated lines, and must be one of the following: @table @samp @@ -5078,33 +5188,68 @@ This is equivalent to @option{--all-repeated} (@option{-D}). @item prepend Output a newline before each group of repeated lines. +@macro nulOutputNote With @option{--zero-terminated} (@option{-z}), use a zero -byte (ASCII NUL) instead of a newline. +byte (ASCII NUL) instead of a newline as the delimiter. +@end macro +@nulOutputNote @item separate Separate groups of repeated lines with a single newline. -With @option{--zero-terminated} (@option{-z}), use a zero -byte (ASCII NUL) instead of a newline. This is the same as using @samp{prepend}, except that no delimiter is inserted before the first group, and hence may be better suited for output direct to users. +@nulOutputNote @end table +@macro ambiguousGroupNote Note that when groups are delimited and the input stream contains two or more consecutive blank lines, then the output is ambiguous. -To avoid that, filter the input through @samp{tr -s '\n'} to replace +To avoid that, filter the input through @samp{tr -s '\\n'} to replace each sequence of consecutive newlines with a single newline. +@end macro +@ambiguousGroupNote This is a GNU extension. @c FIXME: give an example showing *how* it's useful +@item --group[=@var{delimit-method}] +@opindex --group +@cindex all lines, grouping +Output all lines, and delimit each unique group. +@nulOutputNote +The optional @var{delimit-method} specifies how to delimit +groups, and must be one of the following: + +@table @samp + +@item separate +Separate unique groups with a single delimiter. +This is the default delimiting method if none is specified, +and better suited for output direct to users. + +@item prepend +Output a delimiter before each group of unique items. + +@item append +Output a delimiter after each group of unique items. + +@item both +Output a delimiter around each group of unique items. +@end table + +@ambiguousGroupNote + +This is a GNU extension. + @item -u @itemx --unique @opindex -u @opindex --unique @cindex unique lines, outputting -Discard the first repeated line. When used by itself, this option -causes @command{uniq} to print unique lines, and nothing else. +Discard the last line that would be output for a repeated input group. +When used by itself, this option causes @command{uniq} to print unique +lines, and nothing else. @item -w @var{n} @itemx --check-chars=@var{n} @@ -5114,7 +5259,7 @@ Compare at most @var{n} characters on each line (after skipping any specified fields and characters). By default the entire rest of the lines are compared. -@zeroTerminatedOption +@optZeroTerminated @end table @@ -5249,7 +5394,7 @@ compatibility; GNU Standards normally discourage output parameters not introduced by an option. Note that for @emph{any} file named as the value of an option or as an -input text file, a single dash @kbd{-} may be used, in which case +input text file, a single dash @samp{-} may be used, in which case standard input is assumed. However, it would not make sense to use this convention more than once per program invocation. @@ -5547,7 +5692,7 @@ extensions are disabled. Option @option{-M} can be used to change In this output format, each non-graphical character, like newline and tab, is merely changed to exactly one space, with no special attempt to -compress consecutive spaces. Each quote character: @kbd{"} is doubled +compress consecutive spaces. Each quote character @samp{"} is doubled so it will be correctly processed by @command{nroff} or @command{troff}. @item -T @@ -5569,9 +5714,9 @@ selected, the last parameter of each @code{\xx} call is inhibited. Option @option{-M} can be used to change @samp{xx} to another macro name. -In this output format, some special characters, like @kbd{$}, @kbd{%}, -@kbd{&}, @kbd{#} and @kbd{_} are automatically protected with a -backslash. Curly brackets @kbd{@{}, @kbd{@}} are protected with a +In this output format, some special characters, like @samp{$}, @samp{%}, +@samp{&}, @samp{#} and @samp{_} are automatically protected with a +backslash. Curly brackets @samp{@{}, @samp{@}} are protected with a backslash and a pair of dollar signs (to force mathematical mode). The backslash itself produces the sequence @code{\backslash@{@}}. Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and @@ -5636,7 +5781,7 @@ All 256 bytes, even ASCII NUL bytes, are always read and processed from input file with no adverse effect, even if GNU extensions are disabled. However, System V @command{ptx} does not accept 8-bit characters, a few control characters are rejected, and the tilde -@kbd{~} is also rejected. +@samp{~} is also rejected. @item Input line length is only limited by available memory, even if GNU @@ -5961,9 +6106,14 @@ corresponding lines of each given file, separated by a TAB character. Standard input is used for a file name of @samp{-} or if no input files are given. -For example: +Synopsis: @example +paste [@var{option}]@dots{} [@var{file}]@dots{} +@end example + +For example, with: +@example $ cat num2 1 2 @@ -5971,16 +6121,37 @@ $ cat let3 a b c +@end example + +Take lines sequentially from each file: +@example $ paste num2 let3 1 a 2 b @ c @end example -Synopsis: +Duplicate lines from a file: +@example +$ paste num2 let3 num2 +1 a 1 +2 b 2 + @ c +@end example +Intermix lines from stdin: @example -paste [@var{option}]@dots{} [@var{file}]@dots{} +$ paste - let3 - < num2 +1 a 2 + @ b + @ c +@end example + +Join consecutive lines with a space: +@example +$ seq 4 | paste -d ' ' - - +1 2 +3 4 @end example The program accepts the following options. Also see @ref{Common options}. @@ -6181,6 +6352,8 @@ character is used to delimit the fields. Print a line for each unpairable line in file @var{file-number} (either @samp{1} or @samp{2}), instead of the normal output. +@optZeroTerminated + @end table @exitstatus @@ -6191,7 +6364,7 @@ Print a line for each unpairable line in file @var{file-number} @cindex operating on characters -This commands operate on individual characters. +These commands operate on individual characters. @menu * tr invocation:: Translate, squeeze, and/or delete characters. @@ -7143,7 +7316,7 @@ space, there is no alternate access method. When it is a printing character, then there is such a method. GNU @command{ls} uses a @samp{.} character to indicate a file -with an SELinux security context, but no other alternate access method. +with a security context, but no other alternate access method. A file with any other combination of alternate access methods is marked with a @samp{+} character. @@ -7512,11 +7685,9 @@ Assume that each tab stop is @var{cols} columns wide. The default is 8. @command{ls} uses tabs where possible in the output, for efficiency. If @var{cols} is zero, do not use tabs at all. -@c FIXME: remove in 2009, if Apple Terminal has been fixed for long enough. -Some terminal emulators (at least Apple Terminal 1.5 (133) from Mac OS X 10.4.8) -do not properly align columns to the right of a TAB following a -non-ASCII byte. If you use such a terminal emulator, use the -@option{-T0} option or put @code{TABSIZE=0} in your environment to tell +Some terminal emulators might not properly align columns to the right of a +TAB following a non-ASCII byte. You can avoid that issue by using the +@option{-T0} option or put @code{TABSIZE=0} in your environment, to tell @command{ls} to align using spaces, not tabs. @item -w @@ -7918,8 +8089,8 @@ copy recursively by descending into source directories and copying files to corresponding destination directories. When copying from a symbolic link, @command{cp} normally follows the -link only when not copying -recursively. This default can be overridden with the +link only when not copying recursively or when @option{--link} +(@option{-l}) is used. This default can be overridden with the @option{--archive} (@option{-a}), @option{-d}, @option{--dereference} (@option{-L}), @option{--no-dereference} (@option{-P}), and @option{-H} options. If more than one of these options is specified, @@ -7973,7 +8144,7 @@ If the destination already exists, do not alter its contents. See the @option{--preserve} option for controlling which attributes to copy. @item -b -@itemx @w{@kbd{--backup}[=@var{method}]} +@itemx --backup[=@var{method}] @opindex -b @opindex --backup @vindex VERSION_CONTROL @@ -8087,7 +8258,7 @@ they point to. This option affects only symbolic links in the source; symbolic links in the destination are always followed if possible. @item -p -@itemx @w{@kbd{--preserve}[=@var{attribute_list}]} +@itemx --preserve[=@var{attribute_list}] @opindex -p @opindex --preserve @cindex file information, preserving, extended attributes, xattr @@ -8123,9 +8294,11 @@ $ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c @noindent Note the inputs: @file{b} is a symlink to regular file @file{a}, yet the files in destination directory, @file{c/}, are hard-linked. -Since @option{-a} implies @option{--preserve=links}, and since @option{-H} -tells @command{cp} to dereference command line arguments, it sees two files -with the same inode number, and preserves the perceived hard link. +Since @option{-a} implies @option{--no-dereference} it would copy the symlink, +but the later @option{-H} tells @command{cp} to dereference the command line +arguments where it then sees two files with the same inode number. +Then the @option{--preserve=links} option also implied by @option{-a} +will preserve the perceived hard link. Here is a similar example that exercises @command{cp}'s @option{-L} option: @smallexample @@ -8153,12 +8326,13 @@ all but @samp{Operation not supported} warnings are output. Using @option{--preserve} with no @var{attribute_list} is equivalent to @option{--preserve=mode,ownership,timestamps}. -In the absence of this option, each destination file is created with the +In the absence of this option, the permissions of existing destination +files are unchanged, while each new file is created with the mode bits of the corresponding source file, minus the bits set in the umask and minus the set-user-ID and set-group-ID bits. @xref{File permissions}. -@item @w{@kbd{--no-preserve}=@var{attribute_list}} +@item --no-preserve=@var{attribute_list} @cindex file information, preserving Do not preserve the specified attributes. The @var{attribute_list} has the same form as for @option{--preserve}. @@ -8190,7 +8364,8 @@ any missing intermediate directories. @cindex recursively copying directories @cindex non-directories, copying as special files Copy directories recursively. By default, do not follow symbolic -links in the source; see the @option{--archive} (@option{-a}), @option{-d}, +links in the source unless used together with the @option{--link} +(@option{-l}) option; see the @option{--archive} (@option{-a}), @option{-d}, @option{--dereference} (@option{-L}), @option{--no-dereference} (@option{-P}), and @option{-H} options. Special files are copied by creating a destination file of the same type as the source; see the @@ -8327,6 +8502,25 @@ Skip subdirectories that are on different file systems from the one that the copy started on. However, mount point directories @emph{are} copied. +@macro optContext +@item -Z +@itemx --context[=@var{context}] +@opindex -Z +@opindex --context +@cindex SELinux, setting/restoring security context +@cindex security context +Without a specified @var{context}, adjust the SELinux security context according +to the system default type for destination files, similarly to the +@command{restorecon} command. +The long form of this option with a specific context specified, +will set the context for newly created files only. +With a specified context, if both SELinux and SMACK are disabled, a warning is +issued. +@end macro +@optContext +This option is mutually exclusive with the @option{--preserve=context} +option, and overrides the @option{--preserve=all} and @option{-a} options. + @end table @exitstatus @@ -8440,7 +8634,7 @@ that normally make up the last status line. @item none @opindex none @r{dd status=} -Do not print any informational messages to stderr. +Do not print any informational or warning messages to stderr. Error messages are output as normal. @end table @@ -8459,21 +8653,26 @@ Conversions: Convert EBCDIC to ASCII, using the conversion table specified by POSIX@. This provides a 1:1 translation for all 256 bytes. +This option implies @samp{conv=unblock}; input is converted to +ASCII before trailing spaces are deleted. @item ebcdic @opindex ebcdic@r{, converting to} Convert ASCII to EBCDIC@. This is the inverse of the @samp{ascii} conversion. +This option implies @samp{conv=block}; trailing spaces are added +before being converted to EBCDIC@. @item ibm @opindex alternate ebcdic@r{, converting to} -Convert ASCII to alternate EBCDIC, -using the alternate conversion table specified by POSIX@. +This acts like @samp{conv=ebcdic}, except it +uses the alternate conversion table specified by POSIX@. This is not a 1:1 translation, but reflects common historical practice for @samp{~}, @samp{[}, and @samp{]}. The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are -mutually exclusive. +mutually exclusive. If you use any of these options, you should also +use the @samp{cbs=} option. @item block @opindex block @r{(space-padding)} @@ -8771,6 +8970,25 @@ tape=/dev/rmt/0 (dd bs=4k seek=1 count=0 && dd bs=512k) <$tape >$disk @end example +@cindex ddrescue +@cindex disks, failing +For failing disks, other tools come with a great variety of extra +functionality to ease the saving of as much data as possible before the +disk finally dies, e.g. +@uref{http://www.gnu.org/software/ddrescue/, GNU @command{ddrescue}}. +However, in some cases such a tool is not available or the administrator +feels more comfortable with the handling of @command{dd}. +As a simple rescue method, call @command{dd} as shown in the following +example: the options @samp{conv=noerror,sync} are used to continue +after read errors and to pad out bad reads with NULs, while +@samp{iflag=fullblock} caters for short reads (which traditionally never +occur on disk based devices): + +@example +# Rescue data from an (unmounted!) partition of a failing disk. +dd conv=noerror,sync iflag=fullblock </dev/sda1 > /mnt/rescue.img +@end example + Sending an @samp{INFO} signal to a running @command{dd} process makes it print I/O statistics to standard error and then resume copying. In the example below, @@ -8857,6 +9075,12 @@ The program accepts the following options. Also see @ref{Common options}. Compare each pair of source and destination files, and if the destination has identical content and any specified owner, group, permissions, and possibly SELinux context, then do not modify the destination at all. +Note this option is best used in conjunction with @option{--user}, +@option{--group} and @option{--mode} options, lest @command{install} +incorrectly determines the default attributes that installed files would have +(as it doesn't consider setgid directories and POSIX default ACLs for example). +This could result in redundant copies or attributes that are not reset to the +correct defaults. @item -c @opindex -c @@ -8866,8 +9090,8 @@ Ignored; for compatibility with old Unix versions of @command{install}. @opindex -D Create any missing parent directories of @var{dest}, then copy @var{source} to @var{dest}. -This option is ignored if a destination directory is specified -via @option{--target-directory=DIR}. +Explicitly specifying the @option{--target-directory=@var{dir}} will similarly +ensure the presence of that hierarchy before copying @var{source} arguments. @item -d @itemx --directory @@ -8964,15 +9188,9 @@ Program used to strip binaries. @opindex --verbose Print the name of each file before copying it. -@item -Z @var{context} -@itemx --context=@var{context} -@opindex -Z -@opindex --context -@cindex SELinux -@cindex security context -Set the default SELinux security context to be used for any -created files and directories. If SELinux is disabled then -print a warning and ignore the option. +@optContext +This option is mutually exclusive with the @option{--preserve-context} option. + @end table @@ -9105,6 +9323,16 @@ Print the name of each file before moving it. @optNoTargetDirectory +@item -Z +@itemx --context +@opindex -Z +@opindex --context +@cindex SELinux, restoring security context +@cindex security context +This option functions similarly to the @command{restorecon} command, +by adjusting the SELinux security context according +to the system default type for destination files. + @end table @exitstatus @@ -9137,7 +9365,8 @@ the @option{-f} or @option{--force} option is not given, or the If the response is not affirmative, the file is skipped. Any attempt to remove a file whose last file name component is -@file{.} or @file{..} is rejected without any prompting. +@file{.} or @file{..} is rejected without any prompting, as mandated +by POSIX. @emph{Warning}: If you use @command{rm} to remove a file, it is usually possible to recover the contents of that file. If you want more assurance @@ -9416,12 +9645,25 @@ the whole file. @var{bytes} can be followed by a size specification like @samp{K}, @samp{M}, or @samp{G} to specify a multiple. @xref{Block size}. @item -u -@itemx --remove +@itemx --remove[=@var{how}] @opindex -u @opindex --remove +@opindex --remove=unlink +@opindex --remove=wipe +@opindex --remove=wipesync @cindex removing files after shredding After shredding a file, truncate it (if possible) and then remove it. If a file has multiple links, only the named links will be removed. +Often the file name is less sensitive than the file data, in which case +the optional @var{how} parameter gives control of how to more efficiently +remove each directory entry. +The @samp{unlink} parameter will just use a standard unlink call, +@samp{wipe} will also first obfuscate bytes in the name, and +@samp{wipesync} will also sync each obfuscated byte in the name to disk. +Note @samp{wipesync} is the default method, but can be expensive, +requiring a sync for every character in every file. This can become +significant with many files, or is redundant if your file system provides +synchronous metadata updates. @item -v @itemx --verbose @@ -9434,8 +9676,9 @@ Display to standard error all status updates as sterilization proceeds. @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 slack space in +the last block of the file. This space may contain portions of the current +system memory on some systems for example. 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, @@ -9760,8 +10003,24 @@ ln -srv /a/file /tmp '/tmp/file' -> '../a/file' @end smallexample +Relative symbolic links are generated based on their canonicalized +containing directory, and canonicalized targets. I.E. all symbolic +links in these file names will be resolved. @xref{realpath invocation}, which gives greater control -over relative file name generation. +over relative file name generation, as demonstrated in the following example: + +@example +@verbatim +ln--relative() { + test "$1" = --no-symlinks && { nosym=$1; shift; } + target="$1"; + test -d "$2" && link="$2/." || link="$2" + rtarget="$(realpath $nosym -m "$target" \ + --relative-to "$(dirname "$link")")" + ln -s -v "$rtarget" "$link" +} +@end verbatim +@end example @item -s @itemx --symbolic @@ -9890,13 +10149,7 @@ newly-created parent directories are inherited. Print a message for each created directory. This is most useful with @option{--parents}. -@item -Z @var{context} -@itemx --context=@var{context} -@opindex -Z -@opindex --context -@cindex SELinux -@cindex security context -Set the default SELinux security context to be used for created directories. +@optContext @end table @@ -9937,13 +10190,7 @@ Set the mode of created FIFOs to @var{mode}, which is symbolic as in for the point of departure. @var{mode} should specify only file permission bits. @xref{File permissions}. -@item -Z @var{context} -@itemx --context=@var{context} -@opindex -Z -@opindex --context -@cindex SELinux -@cindex security context -Set the default SELinux security context to be used for created FIFOs. +@optContext @end table @@ -10020,13 +10267,7 @@ Set the mode of created files to @var{mode}, which is symbolic as in @var{mode} should specify only file permission bits. @xref{File permissions}. -@item -Z @var{context} -@itemx --context=@var{context} -@opindex -Z -@opindex --context -@cindex SELinux -@cindex security context -Set the default SELinux security context to be used for created files. +@optContext @end table @@ -10119,11 +10360,7 @@ Suppress most error messages. @opindex --verbose Report error messages. -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. +@optZero @end table @@ -10307,6 +10544,13 @@ portable, and because it has undesirable results if the entire @var{owner@samp{.}group} happens to identify a user whose name contains @samp{.}. +@macro chownGroupRestrictions +It is system dependent whether a user can change the group to an arbitrary one, +or the more portable behavior of being restricted to setting a group of +which the user is a member. +@end macro +@chownGroupRestrictions + The @command{chown} command sometimes clears the set-user-ID or set-group-ID permission bits. This behavior depends on the policy and functionality of the underlying @code{chown} system call, which may @@ -10340,7 +10584,7 @@ actually changes. Do not print error messages about files whose ownership cannot be changed. -@item @w{@kbd{--from}=@var{old-owner}} +@item --from=@var{old-owner} @opindex --from @cindex symbolic links, changing owner Change a @var{file}'s ownership only if it has current attributes specified @@ -10467,7 +10711,8 @@ chown -hR root /u @command{chgrp} changes the group ownership of each given @var{file} to @var{group} (which can be either a group name or a numeric group ID) -or to the group of an existing reference file. Synopsis: +or to the group of an existing reference file. @xref{chown invocation}. +Synopsis: @example chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@}@c @@ -10478,6 +10723,8 @@ If @var{group} is intended to represent a numeric group ID, then you may specify it with a leading @samp{+}. @xref{Disambiguating names and IDs}. +@chownGroupRestrictions + The program accepts the following options. Also see @ref{Common options}. @table @samp @@ -10923,21 +11170,19 @@ for that device with the shortest mount point name in the list of file systems (@var{mtab}), i.e., it hides duplicate entries, unless the @option{-a} option is specified. -With the same logic, @command{df} elides a mount entry of a dummy pseude device +With the same logic, @command{df} elides a mount entry of a dummy pseudo device if there is another mount entry of a real block device for that mount point with the same device number, e.g. the early-boot pseudo file system @samp{rootfs} is not shown per default when already the real root device has been mounted. @cindex disk device file @cindex device file, disk -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). GNU @command{df} does not attempt to determine the -disk usage +If an argument @var{file} resolves to a special 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. +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. +requires extremely nonportable intimate knowledge of file system structures. The program accepts the following options. Also see @ref{Common options}. @@ -11013,7 +11258,7 @@ disks, but on some systems (notably SunOS) the results may be slightly out of date. This is the default. @item --output -@itemx @w{@kbd{--output}[=@var{field_list}]} +@itemx --output[=@var{field_list}] @opindex --output Use the output format defined by @var{field_list}, or print all fields if @var{field_list} is omitted. In the latter case, the order of the columns @@ -11052,6 +11297,8 @@ Number of available blocks. @item pcent Percentage of @var{used} divided by @var{size}. +@item file +The file name if specified on the command line. @item target The mount point. @end table @@ -11139,30 +11386,34 @@ An NFS file system, i.e., one mounted over a network from another machine. This is the one type name which seems to be used uniformly by all systems. -@item 4.2@r{, }ufs@r{, }efs@dots{} +@item ext2@r{, }ext3@r{, }ext4@r{, }xfs@r{, }btrfs@dots{} @cindex Linux file system types @cindex local file system types -@opindex 4.2 @r{file system type} -@opindex ufs @r{file system type} -@opindex efs @r{file system type} +@opindex ext2 @r{file system type} +@opindex ext3 @r{file system type} +@opindex ext4 @r{file system type} +@opindex xfs @r{file system type} +@opindex btrfs @r{file system type} A file system on a locally-mounted hard disk. (The system might even support more than one type here; Linux does.) -@item hsfs@r{, }cdfs +@item iso9660@r{, }cdfs @cindex CD-ROM file system type -@cindex High Sierra file system -@opindex hsfs @r{file system type} +@cindex DVD file system type +@cindex ISO9660 file system type +@opindex iso9660 @r{file system type} @opindex cdfs @r{file system type} -A file system on a CD-ROM drive. HP-UX uses @samp{cdfs}, most other -systems use @samp{hsfs} (@samp{hs} for ``High Sierra''). +A file system on a CD or DVD drive. HP-UX uses @samp{cdfs}, most other +systems use @samp{iso9660}. -@item pcfs -@cindex PC file system +@item ntfs@r{,}fat +@cindex NTFS file system @cindex DOS file system @cindex MS-DOS file system -@cindex diskette file system -@opindex pcfs -An MS-DOS file system, usually on a diskette. +@cindex MS-Windows file system +@opindex ntfs @r{file system file} +@opindex fat @r{file system file} +File systems used by MS-Windows / MS-DOS. @end table @@ -11219,7 +11470,7 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@optNull{du} +@optNull @item -a @itemx --all @@ -11296,6 +11547,18 @@ Equivalent to @option{--dereference-args} (@option{-D}). @optHumanReadable +@item --inodes +@opindex --inodes +@cindex inode usage, dereferencing in @command{du} +List inode usage information instead of block usage. +This option is useful for finding directories which contain many files, and +therefore eat up most of the inodes space of a file system (see @command{df}, +option @option{--inodes}). +It can well be combined with the options @option{-a}, @option{-c}, +@option{-h}, @option{-l}, @option{-s}, @option{-S}, @option{-t} and +@option{-x}; however, passing other options regarding the block size, for +example @option{-b}, @option{-m} and @option{--apparent-size}, is ignored. + @item -k @opindex -k @cindex kibibytes for file sizes @@ -11343,8 +11606,7 @@ Normally, in the output of @command{du} (when not using @option{--summarize}), the size listed next to a directory name, @var{d}, represents the sum of sizes of all entries beneath @var{d} as well as the size of @var{d} itself. With @option{--separate-dirs}, the size reported for a directory name, -@var{d}, is merely the @code{stat.st_size}-derived size of the directory -entry, @var{d}. +@var{d}, will exclude the size of any subdirectories. @optSi @@ -11358,7 +11620,9 @@ Display only a total for each argument. @itemx --threshold=@var{size} @opindex -t @opindex --threshold -Exclude entries based on a given @var{size} (@pxref{Block size}). +Exclude entries based on a given @var{size}. The @var{size} refers to used +blocks in normal mode (@pxref{Block size}), or inodes count in conjunction +with the @option{--inodes} option. If @var{size} is positive, then @command{du} will only print entries with a size greater than or equal to that. @@ -11374,6 +11638,10 @@ Please note that the @option{--threshold} option can be combined with the @option{--apparent-size} option, and in this case would elide entries based on its apparent size. +Please note that the @option{--threshold} option can be combined with the +@option{--inodes} option, and in this case would elide entries based on +its inodes count. + Here's how you would use @option{--threshold} to find directories with a size greater than or equal to 200 megabytes: @@ -11388,6 +11656,13 @@ note the @option{-a} - with an apparent size smaller than or equal to 500 bytes: du -a -t -500 --apparent-size @end example +Here's how you would use @option{--threshold} to find directories on the root +file system with more than 20000 inodes used in the directory tree below: + +@example +du --inodes -x --threshold=20000 / +@end example + @item --time @opindex --time @@ -11594,20 +11869,25 @@ The valid @var{format} directives for files with @option{--format} and @item %N - Quoted file name with dereference if symbolic link @item %o - Optimal I/O transfer size hint @item %s - Total size, in bytes -@item %t - Major device type in hex -@item %T - Minor device type in hex +@item %t - Major device type in hex (see below) +@item %T - Minor device type in hex (see below) @item %u - User ID of owner @item %U - User name of owner @item %w - Time of file birth, or @samp{-} if unknown @item %W - Time of file birth as seconds since Epoch, or @samp{0} @item %x - Time of last access @item %X - Time of last access as seconds since Epoch -@item %y - Time of last modification -@item %Y - Time of last modification as seconds since Epoch -@item %z - Time of last change -@item %Z - Time of last change as seconds since Epoch +@item %y - Time of last data modification +@item %Y - Time of last data modification as seconds since Epoch +@item %z - Time of last status change +@item %Z - Time of last status change as seconds since Epoch @end itemize +The @samp{%t} and @samp{%T} formats operate on the st_rdev member of +the stat(2) structure, and are only defined for character and block +special files. On some systems or file types, st_rdev may be used to +represent other quantities. + 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{%.3X} outputs the @@ -11752,6 +12032,7 @@ Base the size of each @var{file} on the size of @var{rfile}. @opindex -s @opindex --size Set or adjust the size of each @var{file} according to @var{size}. +@var{size} is in bytes unless @option{--io-blocks} is specified. @multiplierSuffixesNoBlocks{size} @var{size} may also be prefixed by one of the following to adjust @@ -12979,11 +13260,7 @@ With this, an optional @var{suffix} must be specified using the Remove a trailing @var{suffix}. This option implies the @option{-a} option. -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. +@optZero @end table @@ -13038,11 +13315,7 @@ The program accepts the following option. Also see @ref{Common options}. @table @samp -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. +@optZero @end table @@ -13375,23 +13648,6 @@ This is the default mode of operation. @opindex --quiet Suppress diagnostic messages for specified file names. -@item -s -@itemx --strip -@itemx --no-symlinks -@opindex -s -@opindex --strip -@opindex --no-symlinks -Do not resolve symbolic links. Only resolve references to -@samp{/./}, @samp{/../} and remove extra @samp{/} characters. -When combined with the @option{-m} option, realpath operates -only on the file name, and does not touch any actual file. - -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. - @item --relative-to=@var{file} @opindex --relative-to @cindex relpath @@ -13420,6 +13676,19 @@ realpath --relative-base=/usr /tmp /usr/bin @result{} bin @end example +@item -s +@itemx --strip +@itemx --no-symlinks +@opindex -s +@opindex --strip +@opindex --no-symlinks +Do not resolve symbolic links. Only resolve references to +@samp{/./}, @samp{/../} and remove extra @samp{/} characters. +When combined with the @option{-m} option, realpath operates +only on the file name, and does not touch any actual file. + +@optZero + @end table @cindex exit status of @command{realpath} @@ -13600,6 +13869,16 @@ May be negated. @cindex even parity Set odd parity (even if negated). May be negated. +@item cmspar +@opindex cmspar +@cindex constant parity +@cindex stick parity +@cindex mark parity +@cindex space parity +Use "stick" (mark/space) parity. If parodd is set, the parity bit is +always 1; if parodd is not set, the parity bit is always zero. +Non-POSIX@. May be negated. + @item cs5 @itemx cs6 @itemx cs7 @@ -13705,7 +13984,7 @@ Assume input characters are UTF-8 encoded. May be negated. @opindex ixon @kindex C-s/C-q flow control @cindex XON/XOFF flow control -Enable XON/XOFF flow control (that is, @kbd{CTRL-S}/@kbd{CTRL-Q}). May +Enable XON/XOFF flow control (that is, @kbd{Ctrl-S}/@kbd{Ctrl-Q}). May be negated. @item ixoff @@ -14208,7 +14487,7 @@ The program accepts the following option. Also see @ref{Common options}. @table @samp -@optNull{printenv} +@optNull @end table @@ -14293,9 +14572,13 @@ logins, groups, and so forth. running it if no user is specified. Synopsis: @example -id [@var{option}]@dots{} [@var{username}] +id [@var{option}]@dots{} [@var{user}] @end example +@var{user} can be either a user ID or a name, with name look-up +taking precedence unless the ID is specified with a leading @samp{+}. +@xref{Disambiguating names and IDs}. + @vindex POSIXLY_CORRECT By default, it prints the real user ID, real group ID, effective user ID if different from the real user ID, effective group ID if different from @@ -14349,13 +14632,25 @@ Print only the user ID. @opindex --context @cindex SELinux @cindex security context -Print only the security context of the current user. -If SELinux is disabled then print a warning and +Print only the security context of the process, which is generally +the user's security context inherited from the parent process. +If neither SELinux or SMACK is enabled then print a warning and set the exit status to 1. -@end table +@item -z +@itemx --zero +@opindex -z +@opindex --zero +Delimit output items with NUL characters. +This option is not permitted when using the default format. -@exitstatus +Example: +@example +$ id -Gn --zero +users <NUL> devs <NUL> +@end example + +@end table @macro primaryAndSupplementaryGroups{cmd,arg} Primary and supplementary groups for a process are normally inherited @@ -14367,6 +14662,8 @@ database to be consulted afresh, and so will give a different result. @end macro @primaryAndSupplementaryGroups{id,user argument} +@exitstatus + @node logname invocation @section @command{logname}: Print current login name @@ -14424,13 +14721,12 @@ groups [@var{username}]@dots{} The group lists are equivalent to the output of the command @samp{id -Gn}. -@primaryAndSupplementaryGroups{groups,list of users} - The only options are @option{--help} and @option{--version}. @xref{Common options}. -@exitstatus +@primaryAndSupplementaryGroups{groups,list of users} +@exitstatus @node users invocation @section @command{users}: Print login names of users currently logged in @@ -15842,15 +16138,27 @@ By default, @var{command} is run with the same credentials as the invoking process. Use this option to run it as a different @var{user} and/or with a different primary @var{group}. +If a @var{user} is specified then the supplementary groups +are set according to the system defined list for that user, +unless overridden with the @option{--groups} option. @item --groups=@var{groups} @opindex --groups -Use this option to specify the supplementary @var{groups} to be +Use this option to override the supplementary @var{groups} to be used by the new process. The items in the list (names or numeric IDs) must be separated by commas. +Use @samp{--groups=''} to disable the supplementary group look-up +implicit in the @option{--userspec} option. @end table +The user and group name look-up performed by the @option{--userspec} +and @option{--groups} options, is done both outside and inside +the chroot, with successful look-ups inside the chroot taking precedence. +If the specified user or group items are intended to represent a numeric ID, +then a name to ID resolving step is avoided by specifying a leading @samp{+}. +@xref{Disambiguating names and IDs}. + Here are a few tips to help avoid common problems in using chroot. To start with a simple example, make @var{command} refer to a statically linked binary. If you were to use a dynamically linked executable, then @@ -16009,7 +16317,7 @@ Options must precede operands. @table @samp -@optNull{env} +@optNull @item -u @var{name} @itemx --unset=@var{name} @@ -16647,6 +16955,9 @@ When @var{increment} is not specified, it defaults to @samp{1}, 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. +The sequence of numbers ends when the sum of the current number and +@var{increment} would become greater than @var{last}, +so @code{seq 1 10 10} only produces @samp{1}. Floating-point numbers may be specified. @xref{Floating point}. The program accepts the following options. Also see @ref{Common options}. @@ -17295,10 +17606,10 @@ Know your toolbox! Use each program appropriately. If you don't have an appropriate tool, build one. @end enumerate -As of this writing, all the programs we've discussed are available via -anonymous @command{ftp} from: @* -@uref{ftp://gnudist.gnu.org/textutils/textutils-1.22.tar.gz}. (There may -be more recent versions available now.) +As of this writing, all the programs discussed are available from +@uref{http://ftp.gnu.org/old-gnu/textutils/textutils-1.22.tar.gz}, +with more recent versions available from +@uref{http://ftp.gnu.org/gnu/coreutils}. None of what I have presented in this column is new. The Software Tools philosophy was first introduced in the book @cite{Software Tools}, by |