usr.bin/sort/sort.1

   1 .\"     $NetBSD: sort.1,v 1.31 2010/12/18 23:09:48 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2000-2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Ben Harris and Jaromir Dolecek.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" Copyright (c) 1991, 1993
  31 .\"     The Regents of the University of California.  All rights reserved.
  32 .\"
  33 .\" This code is derived from software contributed to Berkeley by
  34 .\" the Institute of Electrical and Electronics Engineers, Inc.
  35 .\"
  36 .\" Redistribution and use in source and binary forms, with or without
  37 .\" modification, are permitted provided that the following conditions
  38 .\" are met:
  39 .\" 1. Redistributions of source code must retain the above copyright
  40 .\"    notice, this list of conditions and the following disclaimer.
  41 .\" 2. Redistributions in binary form must reproduce the above copyright
  42 .\"    notice, this list of conditions and the following disclaimer in the
  43 .\"    documentation and/or other materials provided with the distribution.
  44 .\" 3. Neither the name of the University nor the names of its contributors
  45 .\"    may be used to endorse or promote products derived from this software
  46 .\"    without specific prior written permission.
  47 .\"
  48 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  49 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  50 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  51 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  52 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  53 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  54 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  55 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  56 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  57 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  58 .\" SUCH DAMAGE.
  59 .\"
  60 .\"     @(#)sort.1      8.1 (Berkeley) 6/6/93
  61 .\"
  62 .Dd December 18, 2010
  63 .Dt SORT 1
  64 .Os
  65 .Sh NAME
  66 .Nm sort
  67 .Nd sort or merge text files
  68 .Sh SYNOPSIS
  69 .Nm sort
  70 .Op Fl bcdfHilmnrSsu
  71 .Oo
  72 .Fl k
  73 .Ar field1 Ns Op Li \&, Ns Ar field2
  74 .Oc
  75 .Op Fl o Ar output
  76 .Op Fl R Ar char
  77 .Op Fl T Ar dir
  78 .Op Fl t Ar char
  79 .Op Ar
  80 .Sh DESCRIPTION
  81 The
  82 .Nm
  83 utility sorts text files by lines.
  84 Comparisons are based on one or more sort keys extracted
  85 from each line of input, and are performed lexicographically.
  86 By default, if keys are not given,
  87 .Nm
  88 regards each input line as a single field.
  89 .Pp
  90 The following options are available:
  91 .Bl -tag -width Fl
  92 .It Fl c
  93 Check that the single input file is sorted.
  94 If the file is not sorted,
  95 .Nm
  96 produces the appropriate error messages and exits with code 1; otherwise,
  97 .Nm
  98 returns 0.
  99 .Nm
 100 .Fl c
 101 produces no output.
 102 .It Fl H
 103 Ignored for compatibility with earlier versions of
 104 .Nm .
 105 .It Fl m
 106 Merge only; the input files are assumed to be pre-sorted.
 107 .It Fl o Ar output
 108 The argument given is the name of an
 109 .Ar output
 110 file to be used instead of the standard output.
 111 This file can be the same as one of the input files.
 112 .It Fl S
 113 Don't use stable sort.
 114 Default is to use stable sort.
 115 .It Fl s
 116 Use stable sort, keeps records with equal keys in their original order.
 117 This is the default.
 118 Provided for compatibility with other
 119 .Nm
 120 implementations only.
 121 .It Fl T Ar dir
 122 Use
 123 .Ar dir
 124 as the directory for temporary files.
 125 The default is the value specified in the environment variable
 126 .Ev TMPDIR or
 127 .Pa /tmp
 128 if
 129 .Ev TMPDIR
 130 is not defined.
 131 .It Fl u
 132 Unique: suppress all but one in each set of lines having equal keys.
 133 If used with the
 134 .Fl c
 135 option, check that there are no lines with duplicate keys.
 136 .El
 137 .Pp
 138 The following options override the default ordering rules.
 139 When ordering options appear independent of key field
 140 specifications, the requested field ordering rules are
 141 applied globally to all sort keys.
 142 When attached to a specific key (see
 143 .Fl k ) ,
 144 the ordering options override
 145 all global ordering options for that key.
 146 .Bl -tag -width Fl
 147 .It Fl d
 148 Only blank space and alphanumeric characters
 149 .\" according
 150 .\" to the current setting of LC_CTYPE
 151 are used
 152 in making comparisons.
 153 .It Fl f
 154 Considers all lowercase characters that have uppercase
 155 equivalents to be the same for purposes of comparison.
 156 .It Fl i
 157 Ignore all non-printable characters.
 158 .It Fl l
 159 Sort by the string length of the field, not by the field itself.
 160 .It Fl n
 161 An initial numeric string, consisting of optional blank space, optional
 162 minus sign, and zero or more digits (including decimal point)
 163 .\" with
 164 .\" optional radix character and thousands
 165 .\" separator
 166 .\" (as defined in the current locale),
 167 is sorted by arithmetic value.
 168 (The
 169 .Fl n
 170 option no longer implies the
 171 .Fl b
 172 option.)
 173 .It Fl r
 174 Reverse the sense of comparisons.
 175 .El
 176 .Pp
 177 The treatment of field separators can be altered using these options:
 178 .Bl -tag -width Fl
 179 .It Fl b
 180 Ignores leading blank space when determining the start
 181 and end of a restricted sort key.
 182 A
 183 .Fl b
 184 option specified before the first
 185 .Fl k
 186 option applies globally to all
 187 .Fl k
 188 options.
 189 Otherwise, the
 190 .Fl b
 191 option can be attached independently to each
 192 .Ar field
 193 argument of the
 194 .Fl k
 195 option (see below).
 196 Note that the
 197 .Fl b
 198 option has no effect unless key fields are specified.
 199 .It Fl t Ar char
 200 .Ar char
 201 is used as the field separator character.
 202 The initial
 203 .Ar char
 204 is not considered to be part of a field when determining
 205 key offsets (see below).
 206 Each occurrence of
 207 .Ar char
 208 is significant (for example,
 209 .Dq Ar charchar
 210 delimits an empty field).
 211 If
 212 .Fl t
 213 is not specified, the default field separator is a sequence of
 214 blank-space characters, and consecutive blank spaces do
 215 .Em not
 216 delimit an empty field; further, the initial blank space
 217 .Em is
 218 considered part of a field when determining key offsets.
 219 .It Fl R Ar char
 220 .Ar char
 221 is used as the record separator character.
 222 This should be used with discretion;
 223 .Fl R Ar \*[Lt]alphanumeric\*[Gt]
 224 usually produces undesirable results.
 225 The default record separator is newline.
 226 .It Fl k Ar field1 Ns Op Li \&, Ns Ar field2
 227 Designates the starting position,
 228 .Ar field1 ,
 229 and optional ending position,
 230 .Ar field2 ,
 231 of a key field.
 232 The
 233 .Fl k
 234 option replaces the obsolescent options
 235 .Cm \(pl Ns Ar pos1
 236 and
 237 .Fl Ns Ar pos2 .
 238 .El
 239 .Pp
 240 The following operands are available:
 241 .Bl -tag -width Ar
 242 .It Ar file
 243 The pathname of a file to be sorted, merged, or checked.
 244 If no
 245 .Ar file
 246 operands are specified, or if
 247 a
 248 .Ar file
 249 operand is
 250 .Fl ,
 251 the standard input is used.
 252 .El
 253 .Pp
 254 A field is defined as a minimal sequence of characters followed by a
 255 field separator or a newline character.
 256 By default, the first
 257 blank space of a sequence of blank spaces acts as the field separator.
 258 All blank spaces in a sequence of blank spaces are considered
 259 as part of the next field; for example, all blank spaces at
 260 the beginning of a line are considered to be part of the
 261 first field.
 262 .Pp
 263 Fields are specified
 264 by the
 265 .Fl k
 266 .Ar field1 Ns Op \&, Ns Ar field2
 267 argument.
 268 A missing
 269 .Ar field2
 270 argument defaults to the end of a line.
 271 .Pp
 272 The arguments
 273 .Ar field1
 274 and
 275 .Ar field2
 276 have the form
 277 .Ar m Ns Li \&. Ns Ar n
 278 and can be followed by one or more of the letters
 279 .Cm b , d , f , i ,
 280 .Cm l , n ,
 281 and
 282 .Cm r ,
 283 which correspond to the options discussed above.
 284 A
 285 .Ar field1
 286 position specified by
 287 .Ar m Ns Li \&. Ns Ar n
 288 .Pq Ar m , n No \*[Gt] 0
 289 is interpreted as the
 290 .Ar n Ns th
 291 character in the
 292 .Ar m Ns th
 293 field.
 294 A missing
 295 .Li \&. Ns Ar n
 296 in
 297 .Ar field1
 298 means
 299 .Ql \&.1 ,
 300 indicating the first character of the
 301 .Ar m Ns th
 302 field; if the
 303 .Fl b
 304 option is in effect,
 305 .Ar n
 306 is counted from the first non-blank character in the
 307 .Ar m Ns th
 308 field;
 309 .Ar m Ns Li \&.1b
 310 refers to the first non-blank character in the
 311 .Ar m Ns th
 312 field.
 313 .Pp
 314 A
 315 .Ar field2
 316 position specified by
 317 .Ar m Ns Li \&. Ns Ar n
 318 is interpreted as
 319 the
 320 .Ar n Ns th
 321 character (including separators) of the
 322 .Ar m Ns th
 323 field.
 324 A missing
 325 .Li \&. Ns Ar n
 326 indicates the last character of the
 327 .Ar m Ns th
 328 field;
 329 .Ar m
 330 = \&0
 331 designates the end of a line.
 332 Thus the option
 333 .Fl k
 334 .Sm off
 335 .Xo
 336 .Ar v Li \&. Ar x Li \&,
 337 .Ar w Li \&. Ar y
 338 .Xc
 339 .Sm on
 340 is synonymous with the obsolescent option
 341 .Sm off
 342 .Cm \(pl Ar v-\&1 Li \&. Ar x-\&1
 343 .Fl Ar w-\&1 Li \&. Ar y ;
 344 .Sm on
 345 when
 346 .Ar y
 347 is omitted,
 348 .Fl k
 349 .Sm off
 350 .Ar v Li \&. Ar x Li \&, Ar w
 351 .Sm on
 352 is synonymous with
 353 .Sm off
 354 .Cm \(pl Ar v-\&1 Li \&. Ar x-\&1
 355 .Fl Ar w+1 Li \&.0 .
 356 .Sm on
 357 The obsolescent
 358 .Cm \(pl Ns Ar pos1
 359 .Fl Ns Ar pos2
 360 option is still supported, except for
 361 .Fl Ns Ar w Ns Li \&.0b ,
 362 which has no
 363 .Fl k
 364 equivalent.
 365 .Sh ENVIRONMENT
 366 If the following environment variable exists, it is used by
 367 .Nm .
 368 .Bl -tag -width Ev
 369 .It Ev TMPDIR
 370 .Nm
 371 uses the contents of the
 372 .Ev TMPDIR
 373 environment variable as the path in which to store
 374 temporary files.
 375 .El
 376 .Sh FILES
 377 .Bl -tag -width outputNUMBER+some -compact
 378 .It Pa /tmp/sort.*
 379 Default temporary files.
 380 .It Ar output Ns NUMBER
 381 Temporary file which is used for output if
 382 .Ar output
 383 already exists.
 384 Once sorting is finished, this file replaces
 385 .Ar output
 386 (via
 387 .Xr link 2
 388 and
 389 .Xr unlink 2 ) .
 390 .El
 391 .Sh EXIT STATUS
 392 Sort exits with one of the following values:
 393 .Bl -tag -width flag -compact
 394 .It 0
 395 Normal behavior.
 396 .It 1
 397 On disorder (or non-uniqueness) with the
 398 .Fl c
 399 option
 400 .It 2
 401 An error occurred.
 402 .El
 403 .Sh SEE ALSO
 404 .Xr comm 1 ,
 405 .Xr join 1 ,
 406 .Xr uniq 1 ,
 407 .Xr qsort 3 ,
 408 .Xr radixsort 3
 409 .Sh HISTORY
 410 A
 411 .Nm
 412 command appeared in
 413 .At v5 .
 414 This
 415 .Nm
 416 implementation appeared in
 417 .Bx 4.4
 418 and is used since
 419 .Nx 1.6 .
 420 .Sh BUGS
 421 Posix requires the locale's thousands separator be ignored in numbers.
 422 It may be faster to sort very large files in pieces and then explicitly
 423 merge them.
 424 .Sh NOTES
 425 This
 426 .Nm
 427 has no limits on input line length (other than imposed by available
 428 memory) or any restrictions on bytes allowed within lines.
 429 .Pp
 430 To protect data
 431 .Nm
 432 .Fl o
 433 calls
 434 .Xr link 2
 435 and
 436 .Xr unlink 2 ,
 437 and thus fails on protected directories.
 438 .Pp
 439 Input files should be text files.
 440 If file doesn't end with record separator (which is typically newline), the
 441 .Nm
 442 utility silently supplies one.
 443 .Pp
 444 The current
 445 .Nm
 446 uses lexicographic radix sorting, which requires
 447 that sort keys be kept in memory (as opposed to previous versions which used quick
 448 and merge sorts and did not.)
 449 Thus performance depends highly on efficient choice of sort keys, and the
 450 .Fl b
 451 option and the
 452 .Ar field2
 453 argument of the
 454 .Fl k
 455 option should be used whenever possible.
 456 Similarly,
 457 .Nm
 458 .Fl k1f
 459 is equivalent to
 460 .Nm
 461 .Fl f
 462 and may take twice as long.