summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJim Meyering <jim@meyering.net>2002-02-11 15:11:05 +0000
committerJim Meyering <jim@meyering.net>2002-02-11 15:11:05 +0000
commit1b7ac91429412fb3044e6c92655602cb5b191edb (patch)
treedadefdc11cc5dc515d4cb574f7af918b00930659
parentbbc05d986e3d55963a44d07a4f16436db3263e72 (diff)
downloadcoreutils-1b7ac91429412fb3044e6c92655602cb5b191edb.tar.xz
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.
-rw-r--r--doc/coreutils.texi179
1 files changed, 98 insertions, 81 deletions
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.