gnu/usr.bin/sort/sort.1

   1 .\" $FreeBSD: src/gnu/usr.bin/sort/sort.1,v 1.5.8.1 2001/07/22 11:01:34 dd Exp $
   2 .TH SORT 1 "GNU Text Utilities" "FSF" \" -*- nroff -*-
   3 .SH NAME
   4 sort \- sort lines of text files
   5 .SH SYNOPSIS
   6 .B sort
   7 [\-cmus] [\-t separator] [\-o output-file] [\-T tempdir] [\-bdfiMnr]
   8 [+POS1 [\-POS2]] [\-k POS1[,POS2]] [file...]
   9 .br
  10 .B sort
  11 {\-\-help,\-\-version}
  12 .SH DESCRIPTION
  13 This manual page
  14 documents the GNU version of
  15 .BR sort .
  16 .B sort
  17 sorts, merges, or compares all the lines from the given files, or the standard
  18 input if no files are given.  A file name of `-' means standard input.
  19 By default,
  20 .B sort
  21 writes the results to the standard output.
  22 .PP
  23 .B sort
  24 has three modes of operation: sort (the default), merge, and check for
  25 sortedness.  The following options change the operation mode:
  26 .TP
  27 .I \-c
  28 Check whether the given files are already sorted: if they are not all
  29 sorted, print an error message and exit with a status of 1.
  30 .TP
  31 .I \-m
  32 Merge the given files by sorting them as a group.  Each input file
  33 should already be individually sorted.  It always works to sort
  34 instead of merge; merging is provided because it is faster, in the
  35 case where it works.
  36 .PP
  37 A pair of lines is compared as follows:
  38 if any key fields have been specified,
  39 .B sort
  40 compares each pair of fields, in the order specified on the command
  41 line, according to the associated ordering options, until a difference
  42 is found or no fields are left.
  43 .PP
  44 If any of the global options
  45 .I Mbdfinr
  46 are given but no key fields are
  47 specified,
  48 .B sort
  49 compares the entire lines according to the global options.
  50 .PP
  51 Finally, as a last resort when all keys compare equal
  52 (or if no ordering options were specified at all),
  53 .B sort
  54 compares the lines byte by byte in machine collating sequence.
  55 The last resort comparison honors the
  56 .I -r
  57 global option.
  58 The
  59 .I \-s
  60 (stable) option disables this last-resort comparison so that
  61 lines in which all fields compare equal are left in their original
  62 relative order.  If no fields or global options are specified,
  63 .I \-s
  64 has no effect.
  65 .PP
  66 GNU
  67 .B sort
  68 has no limits on input line length or restrictions on bytes allowed
  69 within lines.  In addition, if the final byte of an input file is not
  70 a newline, GNU
  71 .B sort
  72 silently supplies one.
  73 .PP
  74 If the environment variable
  75 .B TMPDIR
  76 is set,
  77 .B sort
  78 uses it as the directory in which to put temporary files instead of
  79 the default, /tmp.  The
  80 .I "\-T tempdir"
  81 option is another way to select the directory for temporary files; it
  82 overrides the environment variable.
  83 .PP
  84 The following options affect the ordering of output lines.  They may
  85 be specified globally or as part of a specific key field.  If no key
  86 fields are specified, global options apply to comparison of entire
  87 lines; otherwise the global options are inherited by key fields that
  88 do not specify any special options of their own.
  89 .TP
  90 .I \-b
  91 Ignore leading blanks when finding sort keys in each line.
  92 .TP
  93 .I \-d
  94 Sort in `phone directory' order: ignore all characters except letters,
  95 digits and blanks when sorting.
  96 .TP
  97 .I \-f
  98 Fold lower case characters into the equivalent upper case characters
  99 when sorting so that, for example, `b' is sorted the same way `B' is.
 100 .TP
 101 .I \-i
 102 Ignore characters outside the ASCII range 040-0176 octal (inclusive)
 103 when sorting.
 104 .TP
 105 .I \-M
 106 An initial string, consisting of any amount of white space, followed
 107 by three letters abbreviating a month name, is folded to UPPER case
 108 and compared in the order `JAN' < `FEB' < ... < `DEC.'  Invalid names
 109 compare low to valid names.
 110 .TP
 111 .I \-n
 112 Compare according to arithmetic value an initial numeric string
 113 consisting of optional white space, an optional \- sign, and zero or
 114 more digits, optionally followed by a decimal point and zero or more
 115 digits.
 116 .TP
 117 .I \-r
 118 Reverse the result of comparison, so that lines with greater key
 119 values appear earlier in the output instead of later.
 120 .PP
 121 Other options are:
 122 .TP
 123 .I "\-o output-file"
 124 Write output to
 125 .I output-file
 126 instead of to the standard output.  If
 127 .I output-file
 128 is one of the input files,
 129 .B sort
 130 copies it to a temporary file before sorting and writing the output to
 131 .IR output-file .
 132 .TP
 133 .I "\-t separator"
 134 Use character
 135 .I separator
 136 as the field separator when finding the sort keys in each line.  By
 137 default, fields are separated by the empty string between a
 138 non-whitespace character and a whitespace character.  That is to say,
 139 given the input line ` foo bar',
 140 .B sort
 141 breaks it into fields ` foo' and ` bar'.  The field separator is not
 142 considered to be part of either the field preceding or the field
 143 following it.
 144 .TP
 145 .I \-u
 146 For the default case or the
 147 .I \-m
 148 option, only output the first of a sequence of lines that compare
 149 equal.  For the
 150 .I \-c
 151 option, check that no pair of consecutive lines compares equal.
 152 .TP
 153 .I "+POS1 [\-POS2]"
 154 Specify a field within each line to use as a sorting key.  The field
 155 consists of the portion of the line starting at POS1 and up to (but
 156 not including) POS2 (or to the end of the line if POS2 is not given).
 157 The fields and character positions are numbered starting with 0.
 158 .TP
 159 .I "\-k POS1[,POS2]"
 160 An alternate syntax for specifying sorting keys.
 161 The fields and character positions are numbered starting with 1.
 162 .PP
 163 A position has the form \fIf\fP.\fIc\fP, where \fIf\fP is the number
 164 of the field to use and \fIc\fP is the number of the first character
 165 from the beginning of the field (for \fI+pos\fP) or from the end of
 166 the previous field (for \fI\-pos\fP).  The .\fIc\fP part of a position
 167 may be omitted in which case it is taken to be the first character in
 168 the field.  If the
 169 .I \-b
 170 option has been given, the .\fIc\fP part of a field specification is
 171 counted from the first nonblank character of the field (for
 172 \fI+pos\fP) or from the first nonblank character following the
 173 previous field (for \fI\-pos\fP).
 174 .PP
 175 A \fI+pos\fP or \fI-pos\fP argument may also have any of the option
 176 letters
 177 .I Mbdfinr
 178 appended to it, in which case the global ordering options are not used
 179 for that particular field.  The
 180 .I \-b
 181 option may be independently attached to either or both of the
 182 \fI+pos\fP and \fI\-pos\fP parts of a field specification, and if it
 183 is inherited from the global options it will be attached to both.
 184 If a
 185 .I \-n
 186 or
 187 .I \-M
 188 option is used, thus implying a
 189 .I \-b
 190 option, the
 191 .I \-b
 192 option is taken to apply to both the \fI+pos\fP and the \fI\-pos\fP
 193 parts of a key specification.  Keys may span multiple fields.
 194 .PP
 195 In addition, when GNU
 196 .B sort
 197 is invoked with exactly one argument, the following options are recognized:
 198 .TP
 199 .I "\-\-help"
 200 Print a usage message on standard output and exit successfully.
 201 .TP
 202 .I "\-\-version"
 203 Print version information on standard output then exit successfully.
 204 .SH COMPATIBILITY
 205 Historical (BSD and System V) implementations of
 206 .B sort
 207 have differed in their interpretation of some options,
 208 particularly
 209 .IR \-b ,
 210 .IR \-f ,
 211 and
 212 .IR \-n .
 213 GNU sort follows the POSIX behavior, which is
 214 usually (but not always!) like the System V behavior.
 215 According to POSIX
 216 .I \-n
 217 no longer implies
 218 .IR \-b .
 219 For consistency,
 220 .I \-M
 221 has been changed in the same way.
 222 This may affect the meaning of character positions in field
 223 specifications in obscure cases.
 224 If this bites you the fix is to add an explicit
 225 .IR \-b .
 226 .SH BUGS
 227 The different meaning of field numbers depending
 228 on whether
 229 .I -k
 230 is used is confusing.
 231 It's all POSIX's fault!