From 1b7ac91429412fb3044e6c92655602cb5b191edb Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Mon, 11 Feb 2002 15:11:05 +0000 Subject: Add more support for POSIX 1003.1-2001, which requires removal for support of obsolete "-N" option syntax in expand, head, fold, split, tail, unexpand, uniq, and which prohibits options with optional arguments in od and pr. --- doc/coreutils.texi | 179 +++++++++++++++++++++++++++++------------------------ 1 file changed, 98 insertions(+), 81 deletions(-) (limited to 'doc/coreutils.texi') diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 8ea4d589d..82770fe15 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -1193,11 +1193,11 @@ Use @var{number} characters for line numbers (default 6). @code{od} writes an unambiguous representation of each @var{file} (@samp{-} means standard input), or standard input if none are given. -Synopsis: +Synopses: @example od [@var{option}]@dots{} [@var{file}]@dots{} -od -C [@var{file}] [[+]@var{offset} [[+]@var{label}]] +od --traditional [@var{file}] [[+]@var{offset} [[+]@var{label}]] @end example Each line of output consists of the offset in the input, followed by @@ -1248,15 +1248,21 @@ by 1024, and @samp{m} by 1048576. Output at most @var{bytes} bytes of the input. Prefixes and suffixes on @code{bytes} are interpreted as for the @option{-j} option. -@item -s [@var{n}] +@item -s @var{n} @itemx --strings[=@var{n}] @opindex -s @opindex --strings @cindex string constants, outputting Instead of the normal output, output only @dfn{string constants}: at -least @var{n} (3 by default) consecutive @sc{ascii} graphic characters, +least @var{n} consecutive @sc{ascii} graphic characters, followed by a null (zero) byte. +If @var{n} is omitted with @option{--strings}, the default is 3. On +older systems, @sc{gnu} @command{od} instead supports an obsolete +option @option{-s[@var{n}]}, where @var{n} also defaults to 3. Newer +systems do not support @option{-s} without an argument; use +@option{--strings} instead. + @item -t @var{type} @itemx --format=@var{type} @opindex -t @@ -1333,22 +1339,26 @@ more consecutive output lines would be identical, @code{od} outputs only the first line, and puts just an asterisk on the following line to indicate the elision. -@item -w[@var{n}] +@item -w @var{n} @itemx --width[=@var{n}] @opindex -w @opindex --width Dump @code{n} input bytes per output line. This must be a multiple of the least common multiple of the sizes associated with the specified -output types. If @var{n} is omitted, the default is 32. If this option -is not given at all, the default is 16. +output types. + +If this option is not given at all, the default is 16. If @var{n} is +omitted with @option{--width}, the default is 32. On older systems, +@sc{gnu} @command{od} instead supports an obsolete option +@option{-w[@var{n}]}, where @var{n} also defaults to 32. Newer +systems do not support @option{-w} without an argument; use +@option{--width} instead. @end table -The next several options map the old, pre-@sc{posix} format specification -options to the corresponding @sc{posix} format specs. -@sc{gnu} @code{od} accepts -any combination of old- and new-style options. Format specification -options accumulate. +The next several options are shorthands for format specifications. +@sc{gnu} @code{od} accepts any combination of shorthands and format +specification options. These options accumulate. @table @samp @@ -1393,10 +1403,9 @@ Output as octal shorts. Equivalent to @option{-to2}. @opindex -x Output as hexadecimal shorts. Equivalent to @option{-tx2}. -@item -C -@itemx --traditional +@item --traditional @opindex --traditional -Recognize the pre-@sc{posix} non-option arguments that traditional @code{od} +Recognize the non-option arguments that traditional @code{od} accepted. The following syntax: @smallexample @@ -1600,7 +1609,7 @@ form feeds set in the input files requires the @option{-T} option. Capital letter options override small letter ones. @item -Some of the option-arguments (compare @option{-s}, @option{-S}, @option{-e}, +Some of the option-arguments (compare @option{-s}, @option{-e}, @option{-i}, @option{-n}) cannot be specified as separate arguments from the preceding option letter (already stated in the @sc{posix} specification). @end itemize @@ -1726,8 +1735,9 @@ is 8). Merge lines of full length. Used together with the column options @option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off @option{-W/-w} line truncation; -no column alignment used; may be used with @option{-S[@var{string}]}. -@option{-J} has been introduced (together with @option{-W} and @option{-S}) +no column alignment used; may be used with +@option{--sep-string[=@var{string}]}. @option{-J} has been introduced +(together with @option{-W} and @option{--sep-string}) to disentangle the old (@sc{posix}-compliant) options @option{-w} and @option{-s} along with the three column options. @@ -1748,7 +1758,8 @@ the @option{-T} option had been given. @opindex --merge Merge and print all @var{file}s in parallel, one in each column. If a line is too long to fit in a column, it is truncated, unless the @option{-J} -option is used. @option{-S[@var{string}]} may be used. Empty pages in +option is used. @option{--sep-string[=@var{string}]} may be used. +Empty pages in some @var{file}s (form feeds set) produce empty columns, still marked by @var{string}. The result is a continuous line numbering and column marking throughout the whole merged file. Completely empty merged pages @@ -1818,7 +1829,7 @@ three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless @option{-w} is set. This is a @sc{posix}-compliant formulation. -@item -S[@var{string}] +@item -S @var{string} @itemx --sep-string[=@var{string}] @opindex -S @opindex --sep-string @@ -1828,13 +1839,15 @@ does not affect line truncation or column alignment. Without @option{-S}, and with @option{-J}, @code{pr} uses the default output separator, TAB. Without @option{-S} or @option{-J}, @code{pr} uses a @samp{space} -(same as @option{-S" "}). -Using @option{-S} with no @var{string} is equivalent to @option{-S""}. -Note that for some of @code{pr}'s options the single-letter option -character must be followed immediately by any corresponding argument; -there may not be any intervening white space. -@option{-S/-s} is one of them. Don't use @option{-S "STRING"}. -@sc{posix} requires this. +(same as @option{-S"@w{ }"}). With @option{-S@var{string}}, +@var{string} must be nonempty; @option{--sep-string} with no +@var{string} is equivalent to @option{--sep-string=""}. + +On older systems, @command{pr} instead supports an obsolete option +@option{-S[@var{string}]}, where @var{string} is optional. This usage +conflicts with newer systems, where @option{-S} always has an +argument. To specify an empty @var{string} portably, use +@option{--sep-string}. @item -t @itemx --omit-header @@ -1939,6 +1952,10 @@ is broken at the maximum line length as usual. @opindex --width Use a maximum line length of @var{width} columns instead of 80. +On older systems, @command{fold} supports an obsolete option +@option{-@var{width}}. Newer systems do not support this; use +@option{-w @var{width}} instead. + @end table @@ -1966,11 +1983,10 @@ These commands output pieces of the input. @code{head} prints the first part (10 lines by default) of each @var{file}; it reads from standard input if no files are given or -when given a @var{file} of @option{-}. Synopses: +when given a @var{file} of @option{-}. Synopsis: @example head [@var{option}]@dots{} [@var{file}]@dots{} -head -@var{number} [@var{option}]@dots{} [@var{file}]@dots{} @end example If more than one @var{file} is specified, @code{head} prints a @@ -1981,21 +1997,10 @@ one-line header consisting of @noindent before the output for each @var{file}. -@code{head} accepts two option formats: the new one, in which numbers -are arguments to the options (@option{-q -n 1}), and the old one, in which -the number precedes any option letters (@option{-1q}). - The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -@var{count}@var{options} -@opindex -@var{count} -This option is only recognized if it is specified first. @var{count} is -a decimal number optionally followed by a size letter (@samp{b}, -@samp{k}, @samp{m}) as in @code{-c}, or @samp{l} to mean count by lines, -or other option letters (@samp{cqv}). - @item -c @var{bytes} @itemx --bytes=@var{bytes} @opindex -c @@ -2026,6 +2031,13 @@ Always print file name headers. @end table +On older systems, @command{head} supports an obsolete option +@option{-@var{count}@var{options}}, which is recognized only if it is +specified first. @var{count} is a decimal number optionally followed +by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @code{-c}, or +@samp{l} to mean count by lines, or other option letters (@samp{cqv}). +Newer systems do not support this; use @option{-c @var{count}} or +@option{-n @var{count}} instead. @node tail invocation @section @code{tail}: Output the last part of files @@ -2035,11 +2047,10 @@ Always print file name headers. @code{tail} prints the last part (10 lines by default) of each @var{file}; it reads from standard input if no files are given or -when given a @var{file} of @samp{-}. Synopses: +when given a @var{file} of @samp{-}. Synopsis: @example tail [@var{option}]@dots{} [@var{file}]@dots{} -tail -@var{number} [@var{option}]@dots{} [@var{file}]@dots{} @end example If more than one @var{file} is specified, @code{tail} prints a @@ -2059,14 +2070,6 @@ only reverse files that are at most as large as its buffer, which is typically 32k. A more reliable and versatile way to reverse files is the @sc{gnu} @code{tac} command. -@code{tail} accepts two option formats: the standard one, in which -numbers are arguments to the options (@option{-n 1}), and the -obsolescent one, in which the number precedes any option letters -(@option{-1}). On older systems @command{tail} also supports an -obsolete option format @option{+@var{count}} with the same meaning as -@option{-+@var{count}}, but @sc{posix} no longer allows this; use -@option{-n +@var{count}} instead. - If any option-argument is a number @var{n} starting with a @samp{+}, @code{tail} begins printing with the @var{n}th item from the start of each file, instead of from the end. @@ -2075,13 +2078,6 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -@var{count} -@opindex -@var{count} -This option is only recognized if it is specified first. @var{count} is -a decimal number optionally followed by a size letter (@samp{b}, -@samp{k}, @samp{m}) as in @code{-c}, or @samp{l} to mean count by lines, -or other option letters (@samp{cfqv}). - @item -c @var{bytes} @itemx --bytes=@var{bytes} @opindex -c @@ -2205,6 +2201,15 @@ Always print file name headers. @end table +On older systems, @command{tail} supports an obsolete option +@option{-@var{count}@var{options}}, which is recognized only if it is +specified first. @var{count} is a decimal number optionally followed +by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @code{-c}, or +@samp{l} to mean count by lines, or other option letters +(@samp{cfqv}). Some older @command{tail} implementations also support +an obsolete option @option{+@var{count}} with the same meaning as +@option{-+@var{count}}. Newer systems do not support these options; +use @option{-c @var{count}} or @option{-n @var{count}} instead. @node split invocation @section @code{split}: Split a file into fixed-size pieces @@ -2235,13 +2240,16 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -@var{lines} -@itemx -l @var{lines} +@item -l @var{lines} @itemx --lines=@var{lines} @opindex -l @opindex --lines Put @var{lines} lines of @var{input} into each output file. +On older systems, @command{split} supports an obsolete option +@option{-@var{lines}}. Newer systems do not support this; use +@option{-l @var{lines}} instead. + @item -b @var{bytes} @itemx --bytes=@var{bytes} @opindex -b @@ -3040,9 +3048,9 @@ end positions of a field specification, and if it is inherited from the global options it will be attached to both. Keys may span multiple fields. -On older systems @command{sort} supports an obsolete origin-zero -syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys, but -@sc{posix} no longer allows this. Use @option{-k} instead. +On older systems, @command{sort} supports an obsolete origin-zero +syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys. +Newer systems do not support this; use @option{-k} instead. Here are some examples to illustrate various combinations of options. @@ -3170,25 +3178,28 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -@var{n} -@itemx -f @var{n} +@item -f @var{n} @itemx --skip-fields=@var{n} -@opindex -@var{n} @opindex -f @opindex --skip-fields Skip @var{n} fields on each line before checking for uniqueness. Fields are sequences of non-space non-tab characters that are separated from each other by at least one space or tab. +On older systems, @command{uniq} supports an obsolete option +@option{-@var{n}}. Newer systems do not support this; use @option{-f +@var{n}} instead. + @item -s @var{n} @itemx --skip-chars=@var{n} @opindex -s @opindex --skip-chars Skip @var{n} characters before checking for uniqueness. If you use both the field and character skipping options, fields are skipped over first. -On older systems, @command{uniq} also supports an obsolete option -format @option{+@var{n}}, but @sc{posix} no longer allows this format; -use @option{-s @var{n}} instead. + +On older systems, @command{uniq} supports an obsolete option +@option{+@var{n}}. Newer systems do not support this; use @option{-s +@var{n}} instead. @item -c @itemx --count @@ -4514,27 +4525,29 @@ expand [@var{option}]@dots{} [@var{file}]@dots{} By default, @code{expand} converts all tabs to spaces. It preserves backspace characters in the output; they decrement the column count for -tab calculations. The default action is equivalent to @option{-8} (set +tab calculations. The default action is equivalent to @option{-t 8} (set tabs every 8 columns). The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -@var{tab1}[,@var{tab2}]@dots{} -@itemx -t @var{tab1}[,@var{tab2}]@dots{} +@item -t @var{tab1}[,@var{tab2}]@dots{} @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{} -@opindex -@var{tab} @opindex -t @opindex --tabs @cindex tabstops, setting If only one tab stop is given, set the tabs @var{tab1} spaces apart (default is 8). Otherwise, set the tabs at columns @var{tab1}, @var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the -last tabstop given with single spaces. If the tabstops are specified -with the @option{-t} or @option{--tabs} option, they can be separated by +last tabstop given with single spaces. Tabstops can be separated by blanks as well as by commas. +On older systems, @command{expand} supports an obsolete option +@option{-@var{tab1}[,@var{tab2}]@dots{}}, where tabstops must be +separated by commas. Newer systems do not support this; use +@option{-t @var{tab1}[,@var{tab2}]@dots{}} instead. + @item -i @itemx --initial @opindex -i @@ -4571,19 +4584,22 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -@var{tab1}[,@var{tab2}]@dots{} -@itemx -t @var{tab1}[,@var{tab2}]@dots{} +@item -t @var{tab1}[,@var{tab2}]@dots{} @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{} -@opindex -@var{tab} @opindex -t @opindex --tabs If only one tab stop is given, set the tabs @var{tab1} spaces apart instead of the default 8. Otherwise, set the tabs at columns @var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave spaces and -tabs beyond the tabstops given unchanged. If the tabstops are specified -with the @option{-t} or @option{--tabs} option, they can be separated by +tabs beyond the tabstops given unchanged. Tabstops can be separated by blanks as well as by commas. This option implies the @option{-a} option. +On older systems, @command{unexpand} supports an obsolete option +@option{-@var{tab1}[,@var{tab2}]@dots{}}, where tabstops must be +separated by commas. (Unlike @option{-t}, this obsolete option does +not imply @option{-a}.) Newer systems do not support this; use +@option{--first-only -t @var{tab1}[,@var{tab2}]@dots{}} instead. + @item -a @itemx --all @opindex -a @@ -7212,12 +7228,13 @@ specified files. Synopsis: touch [@var{option}]@dots{} @var{file}@dots{} @end example -Older systems support an obsolete variant syntax, as follows. +On older systems, @command{touch} supports an obsolete syntax, as follows. If the first @var{file} would be a valid argument to the @option{-t} option and no timestamp is given with any of the @option{-d}, @option{-r}, or @option{-t} options and the @samp{--} argument is not given, that argument is interpreted as the time for the other files instead of -as a file name. This usage is obsolete; use @option{-t} instead. +as a file name. Newer systems do not support this; use @option{-t} +instead. @cindex empty files, creating Any @var{file} that does not exist is created empty. -- cgit v1.2.3-54-g00ecf