[linuxjm/jm.git] / manual / gnumaniak / original / man1 / sort.1

.\" You may copy, distribute and modify under the terms of the LDP General
.\" Public License as specified in the LICENSE file that comes with the
.\" gnumaniak distribution
.\"
.\" The author kindly requests that no comments regarding the "better"
.\" suitability or up-to-date notices of any info documentation alternative
.\" is added without contacting him first.
.\"
.\" (C) 2002 Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
.\"
.\"     GNU sort man page
.\"     man pages are NOT obsolete!
.\"     <ragnar@ragnar-hojland.com>
.TH SORT 1 "7 October 2002" "GNU textutils 2.1"
.SH NAME
\fBsort\fR \- sort text files
.SH SYNOPSIS
.B sort
.RB [ \-cm ]
.RB [ \-bdfginruzM ]
.RB [ "\+\fIPOS1\fR[\fB\-\fIPOS2" ]
.RB [ "\-o \fIOUTFILE" ]
.RB [ "\-t \fISEPARATOR" ]
.RB [ "\-k \fIPOS1\fR[\fB,\fIPOS2" ]
.RB [ "\-K \fIPOS1\fR[\fB,\fIPOS2" ]
.RB [ "\-S \fISIZE\fR" ]
.RB [ "\-T \fITEMPDIR" ]
.RB [ \-\-reverse ]
.RI [ FILE... ]

.BR sort " [" \-\-help "] [" \-\-version ]
.SH DESCRIPTION
.B sort
sorts, merges, or compares all the lines from any given
.IR FILE s.
concatenating the result and writing it to standard output
If
.I FILE
is omitted or if it is a
.RB ` \- ',
standard input is used for reading.

GNU \fBsort\fR (as specified for all GNU utilities) 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,
\fBsort\fR silently supplies one.
   
Upon any error, \fBsort\fR exits with a status of 2'.
      
If the environment variable \fBTMPDIR\fR is set, \fBsort\fR uses its value
as the directory for temporary files instead of `/tmp'.  The `\fB\-T
\fiTEMPDIR\fR' option in turn overrides the environment variable.

A position in a sort field specified with the \fB\-k\fR or \fB+\fR option
has the form \fIF\fB.\fIC\fR, where \fIF\fR is the number of the field to
use and \fIC\fR is the number of the first character from the beginning of
the field (for \fB+\fIPOS\fR) or from the end of the previous field (for
\fB\-\fIPOS\fR).  If the \fB.\fIC\fR is omitted, it is taken to be the first
character in the field.  If the \fB\-b\fR option was specified, the
\fB.\fIC\fR part of a field specification is counted from the first nonblank
character of the field (for \fB+\fIPOS\fR) or from the first nonblank
character following the previous field (for \fB\-\fIPOS\fR).

A sort key option may also have any of the output ordering options
appended to it, in which case the global ordering options are not used
for that particular field.  The \fB\-b\fR option may be independently
attached to either or both of the \fB+\fIPOS\fR and \fB\-\fIPOS\fR parts of
a field specification, and if it is inherited from the global options it
will be attached to both.  Keys may span multiple fields.
.SH OPTIONS
.SS Behaviour
The default behaviour for \fBsort\fR is to sort.  You may change this
behaviour with:
.TP
.B \-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.
Otherwise, exit successfully.         
.TP
.B \-m
Merge the given files by sorting them as a group.  Each input file
must always 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
A pair of lines is compared as follows: if any key fields have been
specified, \fBsort\fR 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.

If any of the global options `\fB\-bdfinrM\fR' are given but no key fields
are specified, \fBsort\fR compares the entire lines according to the global
options.

Finally, as a last resort when all keys compare equal (or if no
ordering options were specified at all), \fNsort\fR compares the lines byte
by byte in machine collating sequence instead of \fBLC_COLLATE\fR.  The last
resort comparison honors the \fB\-r\fR global option.  The \fB\-s\fR
(stable) option disables this last-resort comparison so that lines in which
all fields compare equal are left in their original relative order.
\fB\-s\fR has no effect if no fields or global options are specified.
.SS Output Ordering Options
The following options affect how \fBsort\fR orders 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
.B \-b
Ignore leading blanks when finding sort keys in each line.
.TP    
.B \-d
Sort in "phone directory" order: ignore all characters except
letters, digits and blanks when sorting.
.TP
.B \-f
Fold lowercase characters into the equivalent uppercase characters
when sorting so that, for example, `b' and `B' sort as equal.
.TP
.B \-g
Sort numerically using \fBstrtod\fR(3) to arrive at the numeric
values.  This allows floating point numbers to be specified in
scientific notation, like `1.0e-34' and `10e100'.  Use this option
only if there is no alternative;  it is much slower than \fB\-n\fR and
numbers with too many significant digits will be compared as if
they had been truncated.  In addition, numbers outside the range
of representable double precision floating point numbers are
treated as if they were zeroes; overflows, underflows and conversion
errors are not reported.
.TP
.B \-i
Ignore unprintable characters.
.TP
.B \-n
Sort numerically: the number begins each line; specifically, it
consists of optional whitespace, an optional `-' sign, and zero or
more digits, optionally followed by a decimal point and zero or
more digits.
.sp
\fBsort \-n\fR uses what might be considered an unconventional method
to compare strings representing floating point numbers.  Rather than first
converting each string to the C \fBdouble\fR type and then comparing those
values, sort aligns the radix points in the two strings and compares the
strings a character at a time.  One benefit of using this approach is its
speed.  In practice this is much more efficient than performing the two
corresponding string-to-double (or even string-to-integer) conversions and
then comparing doubles.  In addition, there is no corresponding loss of
precision.  Converting each string to \fBdouble\fR before comparison
would limit precision to about 16 digits on most systems.
          
Neither a leading `+' nor exponential notation is recognized.  To
compare such strings numerically, use \fB\-g\fR.
.TP
.B \-r, \-\-reverse
Reverse the result of comparison, so that lines with greater key
values appear earlier in the output instead of later.
.TP
.B \-M
An initial string, consisting of any amount of whitespace, followed
by three letters abbreviating a month name, is folded to upper
case and compared in the order `JAN' < `FEB' < ... < `DEC'.
Invalid names compare low to valid names.
.SS Other Options
.TP
.B +\fIPOS1\fR[\fB-\fIPOS2\fR]
The obsolete, traditional option for specifying a sort field.  The
field consists of the line between \fIPOS1\fR and up to but \fBnot
including\fR \fIPOS2\fR (or the end of the line if \fIPOS2\fR is omitted).
Fields and character positions are numbered starting with 0.
.TP
.B \-k \fIPOS1\fR[\fB,\fIPOS2\fR]
.B \-K \fIPOS1\fR[\fB,\fIPOS2\fR]
The recommended, POSIX, option for specifying a sort field.  The
field consists of the line between \fIPOS1\fR and \fIPOS2\fR (or the end of
the line, if \fIPOS2\fR is omitted), \fBinclusive\fR.  Fields and character
positions are numbered starting with 1.
.TP
.B \-o \fIOUTFILE
Write output to OUTFILE instead of standard output.  If \fIOUTFILE\fR is one
of the input files, \fBsort\fR copies it to a temporary file before sorting
and writing the output to \fIOUTFILE\fR
.TP
.B \-t \fISEPARATOR
Use character \fISEPARATOR\fR 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, given the input line `foo bar', \fBsort\fR
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.
.TP
.B \-u
For the default case or the \fB\-m\fR option, only output the first of
a sequence of lines that compare equal.  For the \fB\-c\fR option,
check that no pair of consecutive lines compares equal.
.TP
.B \-z
Treat the input as a set of lines, each terminated by a <NUL>
(zero byte character) instead of a <LF> (Line Feed)
This option can be useful in conjunction with `perl \-0' or find \-print0'
and `xargs \-0' which do the same in order to reliably 
handle arbitrary pathnames (even those which contain Line Feed characters)
.TP
.B -S \fISIZE\fB
Use a buffer of \fISIZE\fB KB.  Different units may be specified by
specifying multiplier suffix (see below).
.TP
.B \-T \fITEMPDIR
Use \fITEMPDIR\fR as the directory for temporary files. This option
overrides the \fBTMPDIR\fR environment variable.  If multiple \fB\-T\fR
options are specified, each directory is used and may improve performance on
huge sorts/merges.
.TP
.B \-\-help
Print a usage message on standard output and exit successfully.
.TP
.B \-\-version
Print version information on standard output then exit successfully.
.SH EXAMPLES
\fB\(bu\fR Sort in descending (reverse) numeric order.
.sp
.RS
.nf
sort \-nr
.fi
.RE          
.sp
\fB\(bu\fR Sort alphabetically, omitting the first and second fields.  This
uses a single key composed of the characters beginning at the start of field
three and extending to the end of each line.
.sp
.RS
.nf
sort \-k3
.fi
.RE
.sp
\fB\(bu\fR Sort numerically on the second field and resolve ties by sorting
alphabetically on the third and fourth characters of
field five.  Use `:' as the field delimiter.
.sp
.RS
.nf
sort \-t : -k 2,2n \-k 5.3,5.4
.fi
.RE
.sp
Note that if you had written `\-k 2' instead of `-k 2,2' \fBsort\fR
would have used all characters beginning in the second field and extending
to the end of the line as the primary \fBnumeric\fR key.  For the large
majority of applications, treating keys spanning more than one field as
numeric will not do what you expect.

Also note that the `n' modifier was applied to the field-end
specifier for the first key.  It would have been equivalent to
specify `\-k 2n,2' or `\-k 2n,2n'.  All modifiers except `b' apply
to the associated \fBfield\fR, regardless of whether the modifier
character is attached to the field-start and/or the field-end part
of the key specifier.

\fB\(bu\fR Sort the password file on the fifth field and ignore any leading
white space.  Sort lines with equal values in field five on the
numeric user ID in field three.
.sp
.RS
.nf
sort \-t : \-k 5b,5 \-k 3,3n /etc/passwd
.fi
.RE
.sp
An alternative is to use the global numeric modifier \fB\-n\fR.
.sp
.RS
.nf
sort \-t : \-n \-k 5b,5 \-k 3,3 /etc/passwd
.fi
.RE
.sp
\fB\(bu\fR Generate a tags file in case insensitive sorted order.
.sp
.RS
.nf
find src \-type f \-print0 | sort \-t / \-z \-f |
xargs \-0 etags \-\-append
.fi
.RE
.sp
The use of `\-print0', `\-z', and `\-0' in this case mean that
pathnames that contain Line Feed characters will not get broken up
by the sort operation.

Finally, to ignore both leading and trailing white space, you
could have applied the `b' modifier to the field-end specifier for
the first key,
.sp
.RS
.nf
sort \-t : \-n \-k 5b,5b \-k 3,3 /etc/passwd
.fi
.RE
.sp
or by using the global \fB\-b\fR modifier instead of \fB\-n\fR and an
explicit `n' with the second key specifier.
.sp
.RS
.nf
sort \-t : -b \-k 5,5 \-k 3,3n /etc/passwd
.fi
.RE
.SH MULTIPLIERS
Numbers may be followed by a size letter to specify a multiple of that
size, and a \fBB\fR to select normal bytes or a \fBD\fR to select
decimal "commercial" bytes.  For example `1KB' is equal to `1024' and
`1KD' is equal to `1000'.  Exceptions are \fBb\fR (512 bytes), \fBc\fR (1
byte), and \fBw\fR (which should never be used - it means 2 in System V and
4 in 4.2BSD), which can't be followed by a \fBB\fR or \fBD\fR.
.TP
.B k
kilo: 2^10 = 1024 for normal bytes, or 10^3 = 1000 for decimal bytes
.TP
.B M
Mega: 2^20 = 1,048,576 or 10^6 = 1,000,000
.TP
.B G
Giga: 2^30 = 1,073,741,824 or 10^9 = 1,000,000,000
.TP
.B T
Tera: 2^40 = 1,099,511,627,776 or 10^12 = 1,000,000,000,000
.TP
.B P
Peta: 2^50 = 1,125,899,906,842,624 or 10^15 = 1,000,000,000,000,000
.TP
.B E
Exa: 2^60 = 1,152,921,504,606,846,976 or 10^18 = 1,000,000,000,000,000,000
.TP
.B Z
Zetta: 2^70 = 1,180,591,620,717,411,303,424 or 10^21 =
1,000,000,000,000,000,000,000
.TP
.B Y
Yotta: 2^80 = 1,208,925,819,614,629,174,706,176 or 10^24 =
1,000,000,000,000,000,000,000,000
.SH COMPATIBILITY
Historical (BSD and System V) implementations of \fBsort\fR have
differed in their interpretation of some options, particularly 
.BR \-b ", " \-f ", and " \-n .
GNU sort follows the POSIX behavior, which is usually (but not always!) like
the System V behavior.  According to POSIX, \fB\-n\fR no longer implies
\fB-b\fR.  For consistency, \fB\-M\fR has been changed in the same way.
This may affect the meaning of character positions in field specifications
in obscure cases.  The only fix is to add an explicit \fB\-b\fR.
.SH LOCALES
.TP
.B LC_COLLATE
Specifies the character collating sequence used to realize all
comparisions, unless specified otherwise.
.TP
.B LC_CTYPE
Modifies the behaviour of the
.BR \-b ", " \-d ", " \-f " and "\-i
output ordering options.
.TP
.B LC_NUMERIC
Specifies the radix character as well as the thousands separator.
.TP
.B LC_TIME
Determines the month spellings, affecting \fB\-M\fR.
.SH NOTES
Report bugs to bug-textutils@gnu.org.
.br
Man page by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>