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