386BSD 0.1 development

[unix-history] / usr / src / usr.bin / sort / sort.1

diff --git a/usr/src/usr.bin/sort/sort.1 b/usr/src/usr.bin/sort/sort.1
index ae5c3b5..d7e68b3 100644 (file)
--- a/usr/src/usr.bin/sort/sort.1
+++ b/usr/src/usr.bin/sort/sort.1
@@ -1,179 +1,185 @@
-.\"    @(#)sort.1      4.1 (Berkeley) %G%
-.\"
-.TH SORT 1 
-.AT 3
+.TH SORT 1L \" -*- nroff -*-

 .SH NAME
 .SH NAME

-sort \- sort or merge files
+sort \- sort lines of text files

 .SH SYNOPSIS
 .B sort
 .SH SYNOPSIS
 .B sort

-[
-.if t \fB\-mubdf\&inrt\fIx\fR
-.if n -mubdfinrt\b\b\b\b\b\b\b\b\b_________x
-]
-[ \fB+\fIpos1 \fR [ \fB\-\fIpos2 \fR]
-] ...
-[ 
-.B \-o 
-name ] [
-.B \-T
-directory ] [ name ] ...
+[\-cmus] [\-t separator] [\-o output-file] [\-bdfiMnr] [+POS1 [\-POS2]]
+[\-k POS1[,POS2]] [file...]

 .SH DESCRIPTION
 .SH DESCRIPTION

-.I Sort
-sorts
-lines of all the named files together
-and writes the result on
-the standard output.
-The name `\-' means
-the standard input.
-If no input files are named, the standard input is sorted.
-.PP
-The default sort key is an entire line.
-Default ordering is
-lexicographic by bytes in machine
-collating sequence.
-The ordering is affected globally by the following options,
-one or more of which may appear.
-.TP 5
-.B  b
-Ignore leading blanks (spaces and tabs) in field comparisons.
-.TP 5
-.B  d
-`Dictionary' order: only letters, digits and blanks
-are significant in comparisons.
-.TP 5
-.B  f
-Fold upper case
-letters onto lower case.
-.TP 5
-.B  i
-Ignore characters outside the ASCII range 040-0176
-in nonnumeric comparisons.
-.TP 5
-.B  n
-An initial numeric string,
-consisting of optional blanks, optional minus sign,
-and zero or more digits with optional decimal point,
-is sorted by arithmetic value.
-Option
-.B n
-implies option
-.B b.
-.TP 5
-.B  r
-Reverse the sense of comparisons.
-.TP 5
-.BI t x
-`Tab character' separating fields is
-.IR x .
-.PP
-The notation
-.BI + "pos1 " "\-\fIpos2"
-restricts a sort key to a field beginning at
-.I pos1
-and ending just before
-.IR pos2 .
-.I Pos1
-and
-.I pos2
-each have the form
-.IB m . n\fR,
-optionally followed by one or more of the flags
-.B bdf\&inr,
-where
-.I m
-tells a number of fields to skip from the beginning of the line and
-.I n
-tells a number of characters to skip further.
-If any flags are present they override all the global
-ordering options for this key.
-If the
-.B b
-option is in effect
-.I n
-is counted from the first nonblank in the field;
-.B b
-is attached independently to 
-.IR pos2 .
-A missing
-\&\fB.\fIn\fR
-means .0;
-a missing
-.BI \- pos2
-means the end of the line.
-Under the
-.BI \-t x
-option, fields are strings separated by
-.IR x ;
-otherwise fields are
-nonempty nonblank strings separated by blanks.
+This manual page
+documents the GNU version of
+.BR sort .
+.B sort
+sorts, merges, or compares all the lines from the given files, or the standard
+input if no files are given.  A file name of `-' means standard input.
+By default,
+.B sort
+writes the results to the standard output.

 .PP
 .PP

-When there are multiple sort keys, later keys
-are compared only after all earlier keys
-compare equal.
-Lines that otherwise compare equal are ordered
-with all bytes significant.
+.B sort
+has three modes of operation: sort (the default), merge, and check for
+sortedness.  The following options change the operation mode:
+.TP
+.I \-c
+Check whether the given files are already sorted: if they are not all
+sorted, print an error message and exit with a status of 1.
+.TP
+.I \-m
+Merge the given files by sorting them as a group.  Each input file
+should already be individually sorted.  It always works to sort
+instead of merge; merging is provided because it is faster, in the
+case where it works.

 .PP
 .PP

-These option arguments are also understood:
-.TP 5
-.B c
-Check that the input file is sorted according to the ordering rules;
-give no output unless the file is out of sort.
-.TP 5
-.B  m
-Merge only, the input files are already sorted.
-.TP 5
-.B  o
-The next argument is the name of an output file
-to use instead of the standard output.
-This file may be the same as one of the inputs.
-.TP 5
-.B T
-The next argument is the name of a directory in which temporary files
-should be made.
-.TP 5
-.B  u
-Suppress all but one in each
-set of equal lines.
-Ignored bytes
-and bytes outside keys
-do not participate in
-this comparison.
+A pair of lines is compared as follows: 
+if any key fields have been specified,
+.B sort
+compares each pair of fields, in the order specified on the command
+line, according to the associated ordering options, until a difference
+is found or no fields are left.
+.PP 
+If any of the global options
+.I Mbdfinr
+are given but no key fields are 
+specified,
+.B sort
+compares the entire lines according to the global options.
+.PP 
+Finally, as a last resort when all keys compare equal
+(or if no ordering options were specified at all),
+.B sort
+compares the lines byte by byte in machine collating sequence.  The
+.I \-s
+option disables this last resort comparison, producing a stable sort.

 .PP
 .PP

-.B Examples.
-Print in alphabetical order all the unique spellings
-in a list of words.
-Capitalized words differ from uncapitalized.
+GNU
+.B sort
+has no limits on input line length or restrictions on bytes allowed
+within lines.  In addition, if the final byte of an input file is not
+a newline, GNU
+.B sort
+silently supplies one.  In some cases, such as exactly what the
+.I \-b
+and
+.I \-f
+options do, BSD and System V
+.B sort
+programs produce different output; GNU
+.B sort
+follows the POSIX behavior, which is usually like the System V behavior.

 .PP
 .PP

-.ti +8
-sort \-u +0f +0 list
+If the environment variable TMPDIR is set,
+.B sort
+uses it as the directory in which to put temporary files instead of
+the default, /tmp.

 .PP
 .PP

-Print the password file
-.RI ( passwd (5))
-sorted by user id number (the 3rd colon-separated field).
+The following options affect the ordering of output lines.  They may
+be specified globally or as part of a specific key field.  If no key
+fields are specified, global options apply to comparison of entire
+lines; otherwise the global options are inherited by key fields that
+do not specify any special options of their own.
+.TP
+.I \-b
+Ignore leading blanks when finding sort keys in each line.
+.TP
+.I \-d
+Sort in `dictionary order': ignore all characters except letters,
+digits and blanks when sorting.
+.TP
+.I \-f
+Fold lower case characters into the equivalent upper case characters
+when sorting so that, for example, `b' is sorted the same way `B' is.
+.TP
+.I \-i
+Ignore characters outside the ASCII range 040-0176 (inclusive) when sorting.
+.TP
+.I \-M
+An initial string, consisting of any amount of white space, followed 
+by three letters abbreviating a month name, is folded to lower case 
+and compared in the order `jan' < `feb' < ... < `dec.'  Invalid names 
+compare low to valid names.  This option implies
+.IR \-b .
+.TP
+.I \-n
+Compare according to arithmetic value an initial numeric string
+consisting of optional white space, an optional \- sign, and zero or
+more digits, optionally followed by a decimal point and zero or more
+digits.  This option implies
+.IR \-b .
+.TP
+.I \-r
+Reverse the result of comparison, so that lines with greater key
+values appear earlier in the output instead of later.

 .PP
 .PP

-.ti +8
-sort \-t: +2n /etc/passwd
+Other options are:
+.TP
+.I "\-o output-file"
+Write output to
+.I output-file
+instead of to the standard output.  If
+.I output-file
+is one of the input files,
+.B sort
+copies it to a temporary file before sorting and writing the output to
+.IR output-file .
+.TP
+.I "\-t separator"
+Use character
+.I separator
+as the field separator when finding the sort keys in each line.  By
+default, fields are separated by the empty string between a
+non-whitespace character and a whitespace character.  That is to say,
+given the input line ` foo bar',
+.B sort
+breaks it into fields ` foo' and ` bar'.  The field separator is not
+considered to be part of either the field preceding or the field
+following it.
+.TP
+.I \-u
+For the default case or the
+.I \-m
+option, only output the first of a sequence of lines that compare
+equal.  For the
+.I \-c
+option, check that no pair of consecutive lines compares equal.
+.TP
+.I "+POS1 [\-POS2]"
+Specify a field within each line to use as a sorting key.  The field
+consists of the portion of the line starting at POS1 and up to (but
+not including) POS2 (or to the end of the line if POS2 is not given).
+The fields and character positions are numbered starting with 0.
+.TP
+.I "\-k POS1[,POS2]"
+An alternate syntax for specifying sorting keys.
+The fields and character positions are numbered starting with 1.

 .PP
 .PP

-Print the first instance of each month in an already sorted file
-of (month day) entries.
-The options
-.B \-um
-with just one input file make the choice of a
-unique representative from a set of equal lines predictable.
+A position has the form \fIf\fP.\fIc\fP, where \fIf\fP is the number
+of the field to use and \fIc\fP is the number of the first character
+from the beginning of the field (for \fI+pos\fP) or from the end of
+the previous field (for \fI\-pos\fP).  The .\fIc\fP part of a position
+may be omitted in which case it is taken to be the first character in
+the field.  If the
+.I \-b
+option has been given, the .\fIc\fP part of a field specification is
+counted from the first nonblank character of the field (for
+\fI+pos\fP) or from the first nonblank character following the
+previous field (for \fI\-pos\fP).

 .PP
 .PP

-.ti +8
-sort \-um +0 \-1 dates
-.SH FILES
-/usr/tmp/stm*, /tmp/*  first and second tries for
-temporary files
-.SH "SEE ALSO"
-uniq(1),
-comm(1),
-rev(1),
-join(1)
-.SH DIAGNOSTICS
-Comments and exits with nonzero status for various trouble
-conditions and for disorder discovered under option
-.BR \-c .
-.SH BUGS
-Very long lines are silently truncated.
+A \fI+pos\fP or \fI-pos\fP argument may also have any of the option
+letters
+.I Mbdfinr
+appended to it, in which case the global ordering options are not used
+for that particular field.  The
+.I \-b
+option may be independently attached to either or both of the
+\fI+pos\fP and \fI\-pos\fP parts of a field specification, and if it
+is inherited from the global options it will be attached to both.
+If a
+.I \-n
+or
+.I \-M
+option is used, thus implying a
+.I \-b
+option, the
+.I \-b
+option is taken to apply to both the \fI+pos\fP and the \fI\-pos\fP
+parts of a key specification.  Keys may span multiple fields.