usr.bin/sort/sort.1.in

   1 .\"     $OpenBSD: sort.1,v 1.31 2007/08/21 21:22:37 millert Exp $
   2 .\"     $FreeBSD$
   3 .\"
   4 .\" Copyright (c) 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" This code is derived from software contributed to Berkeley by
   8 .\" the Institute of Electrical and Electronics Engineers, Inc.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)sort.1      8.1 (Berkeley) 6/6/93
  35 .\"
  36 .Dd July 3, 2012
  37 .Dt SORT 1
  38 .Os
  39 .Sh NAME
  40 .Nm sort
  41 .Nd sort or merge records (lines) of text and binary files
  42 .Sh SYNOPSIS
  43 .Nm sort
  44 .Bk -words
  45 .Op Fl bcCdfghiRMmnrsuVz
  46 .Sm off
  47 .Op Fl k\ \& Ar field1 Op , Ar field2
  48 .Sm on
  49 .Op Fl S Ar memsize
  50 .Ek
  51 .Op Fl T Ar dir
  52 .Op Fl t Ar char
  53 .Op Fl o Ar output
  54 .Op Ar file ...
  55 .Nm sort
  56 .Fl Fl help
  57 .Nm sort
  58 .Fl Fl version
  59 .Sh DESCRIPTION
  60 The
  61 .Nm
  62 utility sorts text and binary files by lines.
  63 A line is a record separated from the subsequent record by a
  64 newline (default) or NUL \'\\0\' character (-z option).
  65 A record can contain any printable or unprintable characters.
  66 Comparisons are based on one or more sort keys extracted from
  67 each line of input, and are performed lexicographically,
  68 according to the current locale's collating rules and the
  69 specified command-line options that can tune the actual
  70 sorting behavior.
  71 By default, if keys are not given,
  72 .Nm
  73 uses entire lines for comparison.
  74 .Pp
  75 The command line options are as follows:
  76 .Bl -tag -width Ds
  77 .It Fl c, Fl Fl check, Fl C, Fl Fl check=silent|quiet
  78 Check that the single input file is sorted.
  79 If the file is not sorted,
  80 .Nm
  81 produces the appropriate error messages and exits with code 1,
  82 otherwise returns 0.
  83 If
  84 .Fl C
  85 or
  86 .Fl Fl check=silent
  87 is specified,
  88 .Nm
  89 produces no output.
  90 This is a "silent" version of
  91 .Fl c.
  92 .It Fl m , Fl Fl merge
  93 Merge only.
  94 The input files are assumed to be pre-sorted.
  95 If they are not sorted the output order is undefined.
  96 .It Fl o Ar output , Fl Fl output Ns = Ns Ar output
  97 Print the output to the
  98 .Ar output
  99 file instead of the standard output.
 100 .It Fl S Ar size, Fl Fl buffer-size Ns = Ns Ar size
 101 Use
 102 .Ar size
 103 for the maximum size of the memory buffer.
 104 Size modifiers %,b,K,M,G,T,P,E,Z,Y can be used.
 105 If a memory limit is not explicitly specified,
 106 .Nm
 107 takes up to about 90% of available memory.
 108 If the file size is too big to fit into the memory buffer,
 109 the temporary disk files are used to perform the sorting.
 110 .It Fl T Ar dir , Fl Fl temporary-directory Ns = Ns Ar dir
 111 Store temporary files in the directory
 112 .Ar dir .
 113 The default path is the value of the environment variable
 114 .Ev TMPDIR
 115 or
 116 .Pa /var/tmp
 117 if
 118 .Ev TMPDIR
 119 is not defined.
 120 .It Fl u , Fl Fl unique
 121 Unique keys.
 122 Suppress all lines that have a key that is equal to an already
 123 processed one.
 124 This option, similarly to
 125 .Fl s ,
 126 implies a stable sort.
 127 If used with
 128 .Fl c
 129 or
 130 .Fl C ,
 131 .Nm
 132 also checks that there are no lines with duplicate keys.
 133 .It Fl s
 134 Stable sort.
 135 This option maintains the original record order of records that have
 136 and equal key.
 137 This is a non-standard feature, but it is widely accepted and used.
 138 .It Fl Fl version
 139 Print the version and silently exits.
 140 .It Fl Fl help
 141 Print the help text and silently exits.
 142 .El
 143 .Pp
 144 The following options override the default ordering rules.
 145 When ordering options appear independently of key field
 146 specifications, they apply globally to all sort keys.
 147 When attached to a specific key (see
 148 .Fl k ) ,
 149 the ordering options override all global ordering options for
 150 the key they are attahced to.
 151 .Bl -tag -width indent
 152 .It Fl b, Fl Fl ignore-leading-blanks
 153 Ignore leading blank characters when comparing lines.
 154 .It Fl d , Fl Fl dictionary-order
 155 Consider only blank spaces and alphanumeric characters in comparisons.
 156 .It Fl f , Fl Fl ignore-case
 157 Convert all lowercase characters to their uppercase equivalent
 158 before comparison, that is, perform case-independent sorting.
 159 .It Fl g, Fl Fl general-numeric-sort, Fl Fl sort=general-numeric
 160 Sort by general numerical value.
 161 As opposed to
 162 .Fl n ,
 163 this option handles general floating points, which have a much
 164 permissive format than those allowed by
 165 . Fl n ,
 166 but it has a significant performance drawback.
 167 .It Fl h, Fl Fl human-numeric-sort, Fl Fl sort=human-numeric
 168 Sort by numerical value, but take into account the SI suffix,
 169 if present.
 170 Sort first by numeric sign (negative, zero, or
 171 positive); then by SI suffix (either empty, or `k' or `K', or one
 172 of `MGTPEZY', in that order); and finally by numeric value.
 173 The SI suffix must immediately follow the number.
 174 For example, '12345K' sorts before '1M', because M is "larger" than K.
 175 This sort option is useful for sorting the output of a single invocation
 176 of 'df' command with
 177 .Fl h
 178 or
 179 .Fl H
 180 options (human-readable).
 181 .It Fl i , Fl Fl ignore-nonprinting
 182 Ignore all non-printable characters.
 183 .It Fl M, Fl Fl month-sort, Fl Fl sort=month
 184 Sort by month abbreviations.
 185 Unknown strings are considered smaller than the month names.
 186 .It Fl n , Fl Fl numeric-sort, Fl Fl sort=numeric
 187 Sort fields numerically by arithmetic value.
 188 Fields are supposed to have optional blanks in the beginning, an
 189 optional minus sign, zero or more digits (including decimal point and
 190 possible thousand separators).
 191 .It Fl R, Fl Fl random-sort, Fl Fl sort=random
 192 Sort by a random order.
 193 This is a random permutation of the inputs except that
 194 the equal keys sort together.
 195 It is implemented by hashing the input keys and sorting
 196 the hash values.
 197 The hash function is choosen randomly.
 198 The hash function is randomized by
 199 .Cm /dev/random
 200 content, or by file content if it is specified by
 201 .Fl Fl random-source .
 202 Even if multiple sort fields are specified,
 203 the same random hash function is used for all of them.
 204 .It Fl r , Fl Fl reverse
 205 Sort in reverse order.
 206 .It Fl V, Fl Fl version-sort
 207 Sort version numbers.
 208 The input lines are treated as file names in form
 209 PREFIX VERSION SUFFIX, where SUFFIX matches the regular expression
 210 "(\.([A-Za-z~][A-Za-z0-9~]*)?)*".
 211 The files are compared by their prefixes and versions (leading
 212 zeros are ignored in version numbers, see example below).
 213 If an input string does not match the pattern, then it is compared
 214 using the byte compare function.
 215 All string comparisions are performed in C locale, the locale
 216 environment setting is ignored.
 217 .Bl -tag -width indent
 218 .It Example:
 219 .It $ ls sort* | sort -V
 220 .It sort-1.022.tgz
 221 .It sort-1.23.tgz
 222 .It sort-1.23.1.tgz
 223 .It sort-1.024.tgz
 224 .It sort-1.024.003.
 225 .It sort-1.024.003.tgz
 226 .It sort-1.024.07.tgz
 227 .It sort-1.024.009.tgz
 228 .El
 229 .El
 230 .Pp
 231 The treatment of field separators can be altered using these options:
 232 .Bl -tag -width indent
 233 .It Fl b , Fl Fl ignore-leading-blanks
 234 Ignore leading blank space when determining the start
 235 and end of a restricted sort key (see
 236 .Fl k
 237 ).
 238 If
 239 .Fl b
 240 is specified before the first
 241 .Fl k
 242 option, it applies globally to all key specifications.
 243 Otherwise,
 244 .Fl b
 245 can be attached independently to each
 246 .Ar field
 247 argument of the key specifications.
 248 .Fl b .
 249 .It Xo
 250 .Sm off
 251 .Fl k\ \& Ar field1 Op , Ar field2 , Fl Fl key Ns = Ns Ar field1 Op , Ar field2
 252 .Sm on
 253 .Xc
 254 Define a restricted sort key that has the starting position
 255 .Ar field1 ,
 256 and optional ending position
 257 .Ar field2
 258 of a key field.
 259 The
 260 .Fl k
 261 option may be specified multiple times,
 262 in which case subsequent keys are compared when earlier keys compare equal.
 263 The
 264 .Fl k
 265 option replaces the obsolete options
 266 .Cm \(pl Ns Ar pos1
 267 and
 268 .Fl Ns Ar pos2 ,
 269 but the old notation is also supported.
 270 .It Fl t Ar char , Fl Fl field-separator Ns = Ns Ar char
 271 Use
 272 .Ar char
 273 as a field separator character.
 274 The initial
 275 .Ar char
 276 is not considered to be part of a field when determining key offsets.
 277 Each occurrence of
 278 .Ar char
 279 is significant (for example,
 280 .Dq Ar charchar
 281 delimits an empty field).
 282 If
 283 .Fl t
 284 is not specified, the default field separator is a sequence of
 285 blank space characters, and consecutive blank spaces do
 286 .Em not
 287 delimit an empty field, however, the initial blank space
 288 .Em is
 289 considered part of a field when determining key offsets.
 290 To use NUL as field separator, use
 291 .Fl t
 292 \'\\0\'.
 293 .It Fl z , Fl Fl zero-terminated
 294 Use NUL as record separator.
 295 By default, records in the files are supposed to be separated by
 296 the newline characters.
 297 With this option, NUL (\'\\0\') is used as a record separator character.
 298 .El
 299 .Pp
 300 Other options:
 301 .Bl -tag -width indent
 302 .It Fl Fl batch-size Ns = Ns Ar num
 303 Specify maximum number of files that can be opened by
 304 .Nm
 305 at once.
 306 This option affects behavior when having many input files or using
 307 temporary files.
 308 The default value is 16.
 309 .It Fl Fl compress-program Ns = Ns Ar PROGRAM
 310 Use PROGRAM to compress temporary files.
 311 PROGRAM must compress standard input to standard output, when called
 312 without arguments.
 313 When called with argument
 314 .Fl d
 315 it must decompress standard input to standard output.
 316 If PROGRAM fails,
 317 .Nm
 318 must exit with error.
 319 An example of PROGRAM that can be used here is bzip2.
 320 .It Fl Fl random-source Ns = Ns Ar filename
 321 In random sort, the file content is used as the source of the 'seed' data
 322 for the hash function choice.
 323 Two invocations of random sort with the same seed data will use
 324 the same hash function and will produce the same result if the input is
 325 also identical.
 326 By default, file
 327 .Cm /dev/random
 328 is used.
 329 .It Fl Fl debug
 330 Print some extra information about the sorting process to the
 331 standard output.
 332 %%THREADS%%.It Fl Fl parallel
 333 %%THREADS%%Set the maximum number of execution threads.
 334 %%THREADS%%Default number equals to the number of CPUs.
 335 .It Fl Fl files0-from Ns = Ns Ar filename
 336 Take the input file list from the file
 337 .Ar filename.
 338 The file names must be separated by NUL
 339 (like the output produced by the command "find ... -print0").
 340 .It Fl Fl radixsort
 341 Try to use radix sort, if the sort specifications allow.
 342 The radix sort can only be used for trivial locales (C and POSIX),
 343 and it cannot be used for numeric or month sort.
 344 Radix sort is very fast and stable.
 345 .It Fl Fl mergesort
 346 Use mergesort.
 347 This is a universal algorithm that can always be used,
 348 but it is not always the fastest.
 349 .It Fl Fl qsort
 350 Try to use quick sort, if the sort specifications allow.
 351 This sort algorithm cannot be used with
 352 .Fl u
 353 and
 354 .Fl s .
 355 .It Fl Fl heapsort
 356 Try to use heap sort, if the sort specifications allow.
 357 This sort algorithm cannot be used with
 358 .Fl u
 359 and
 360 .Fl s .
 361 .It Fl Fl mmap
 362 Try to use file memory mapping system call.
 363 It may increase speed in some cases.
 364 .El
 365 .Pp
 366 The following operands are available:
 367 .Bl -tag -width indent
 368 .It Ar file
 369 The pathname of a file to be sorted, merged, or checked.
 370 If no
 371 .Ar file
 372 operands are specified, or if a
 373 .Ar file
 374 operand is
 375 .Fl ,
 376 the standard input is used.
 377 .El
 378 .Pp
 379 A field is defined as a maximal sequence of characters other than the
 380 field separator and record separator (newline by default).
 381 Initial blank spaces are included in the field unless
 382 .Fl b
 383 has been specified;
 384 the first blank space of a sequence of blank spaces acts as the field
 385 separator and is included in the field (unless
 386 .Fl t
 387 is specified).
 388 For example, all blank spaces at the beginning of a line are
 389 considered to be part of the first field.
 390 .Pp
 391 Fields are specified by the
 392 .Sm off
 393 .Fl k\ \& Ar field1 Op , Ar field2
 394 .Sm on
 395 command-line option.
 396 If
 397 .Ar field2
 398 is missing, the end of the key defaults to the end of the line.
 399 .Pp
 400 The arguments
 401 .Ar field1
 402 and
 403 .Ar field2
 404 have the form
 405 .Em m.n
 406 .Em (m,n > 0)
 407 and can be followed by one or more of the modifiers
 408 .Cm b , d , f , i ,
 409 .Cm n , g , M
 410 and
 411 .Cm r ,
 412 which correspond to the options discussed above.
 413 When
 414 .Cm b
 415 is specified it applies only to
 416 .Ar field1
 417 or
 418 .Ar field2
 419 where it is specified while the rest of the modifiers
 420 apply to the whole key field regardless if they are
 421 specified only with
 422 .Ar field1
 423 or
 424 .Ar field2
 425 or both.
 426 A
 427 .Ar field1
 428 position specified by
 429 .Em m.n
 430 is interpreted as the
 431 .Em n Ns th
 432 character from the beginning of the
 433 .Em m Ns th
 434 field.
 435 A missing
 436 .Em \&.n
 437 in
 438 .Ar field1
 439 means
 440 .Ql \&.1 ,
 441 indicating the first character of the
 442 .Em m Ns th
 443 field; if the
 444 .Fl b
 445 option is in effect,
 446 .Em n
 447 is counted from the first non-blank character in the
 448 .Em m Ns th
 449 field;
 450 .Em m Ns \&.1b
 451 refers to the first non-blank character in the
 452 .Em m Ns th
 453 field.
 454 .No 1\&. Ns Em n
 455 refers to the
 456 .Em n Ns th
 457 character from the beginning of the line;
 458 if
 459 .Em n
 460 is greater than the length of the line, the field is taken to be empty.
 461 .Pp
 462 .Em n Ns th
 463 positions are always counted from the field beginning, even if the field
 464 is shorter than the number of specified positions.
 465 Thus, the key can really start from a position in a subsequent field.
 466 .Pp
 467 A
 468 .Ar field2
 469 position specified by
 470 .Em m.n
 471 is interpreted as the
 472 .Em n Ns th
 473 character (including separators) from the beginning of the
 474 .Em m Ns th
 475 field.
 476 A missing
 477 .Em \&.n
 478 indicates the last character of the
 479 .Em m Ns th
 480 field;
 481 .Em m
 482 = \&0
 483 designates the end of a line.
 484 Thus the option
 485 .Fl k Ar v.x,w.y
 486 is synonymous with the obsolete option
 487 .Cm \(pl Ns Ar v-\&1.x-\&1
 488 .Fl Ns Ar w-\&1.y ;
 489 when
 490 .Em y
 491 is omitted,
 492 .Fl k Ar v.x,w
 493 is synonymous with
 494 .Cm \(pl Ns Ar v-\&1.x-\&1
 495 .Fl Ns Ar w\&.0 .
 496 The obsolete
 497 .Cm \(pl Ns Ar pos1
 498 .Fl Ns Ar pos2
 499 option is still supported, except for
 500 .Fl Ns Ar w\&.0b ,
 501 which has no
 502 .Fl k
 503 equivalent.
 504 .Sh ENVIRONMENT
 505 .Bl -tag -width Fl
 506 .It Ev LC_COLLATE
 507 Locale settings to be used to determine the collation for
 508 sorting records.
 509 .It Ev LC_CTYPE
 510 Locale settings to be used to case conversion and classification
 511 of characters, that is, which characters are considered
 512 whitespaces, etc.
 513 .It Ev LC_MESSAGES
 514 Locale settings that determine the language of output messages
 515 that
 516 .Nm
 517 prints out.
 518 .It Ev LC_NUMERIC
 519 Locale settings that determine the number format used in numeric sort.
 520 .It Ev LC_TIME
 521 Locale settings that determine the month format used in month sort.
 522 .It Ev LC_ALL
 523 Locale settings that override all of the above locale settings.
 524 This environment variable can be used to set all these settings
 525 to the same value at once.
 526 .It Ev LANG
 527 Used as a last resort to determine different kinds of locale-specific
 528 behavior if neither the respective environment variable, nor
 529 .Ev LC_ALL
 530 are set.
 531 %%NLS%%.It Ev NLSPATH
 532 %%NLS%%Path to NLS catalogs.
 533 .It Ev TMPDIR
 534 Path to the directory in which temporary files will be stored.
 535 Note that
 536 .Ev TMPDIR
 537 may be overridden by the
 538 .Fl T
 539 option.
 540 .It Ev GNUSORT_NUMERIC_COMPATIBILITY
 541 If defined
 542 .Fl t
 543 will not override the locale numeric symbols, that is, thousand
 544 separators and decimal separators.
 545 By default, if we specify
 546 .Fl t
 547 with the same symbol as the thousand separator or decimal point,
 548 the symbol will be treated as the field separator.
 549 Older behavior was less definite; the symbol was treated as both field
 550 separator and numeric separator, simultaneously.
 551 This environment variable enables the old behavior.
 552 .El
 553 .Sh FILES
 554 .Bl -tag -width Pa -compact
 555 .It Pa /var/tmp/.bsdsort.PID.*
 556 Temporary files.
 557 .It Pa /dev/random
 558 Default seed file for the random sort.
 559 .El
 560 .Sh EXIT STATUS
 561 The
 562 .Nm
 563 utility shall exit with one of the following values:
 564 .Pp
 565 .Bl -tag -width flag -compact
 566 .It 0
 567 Successfully sorted the input files or if used with
 568 .Fl c
 569 or
 570 .Fl C ,
 571 the input file already met the sorting criteria.
 572 .It 1
 573 On disorder (or non-uniqueness) with the
 574 .Fl c
 575 or
 576 .Fl C
 577 options.
 578 .It 2
 579 An error occurred.
 580 .El
 581 .Sh SEE ALSO
 582 .Xr comm 1 ,
 583 .Xr join 1 ,
 584 .Xr uniq 1 .
 585 .Sh STANDARDS
 586 The
 587 .Nm
 588 utility is compliant with the
 589 .St -p1003.1-2008
 590 specification.
 591 .Pp
 592 The flags
 593 .Op Fl ghRMSsTVz
 594 are extensions to the POSIX specification.
 595 .Pp
 596 All long options are extensions to the specification, some of them are
 597 provided for compatibility with GNU versions and some of them are
 598 own extensions.
 599 .Pp
 600 The old key notations
 601 .Cm \(pl Ns Ar pos1
 602 and
 603 .Fl Ns Ar pos2
 604 come from older versions of
 605 .Nm
 606 and are still supported but their use is highly discouraged.
 607 .Sh HISTORY
 608 A
 609 .Nm
 610 command first appeared in
 611 .At v3 .
 612 .Sh AUTHORS
 613 Gabor Kovesdan <gabor@FreeBSD.org>,
 614 .Pp
 615 Oleg Moskalenko <mom040267@gmail.com>
 616 .Sh NOTES
 617 This implementation of
 618 .Nm
 619 has no limits on input line length (other than imposed by available
 620 memory) or any restrictions on bytes allowed within lines.
 621 .Pp
 622 The performance depends highly on locale settings,
 623 efficient choice of sort keys and key complexity.
 624 The fastest sort is with locale C, on whole lines,
 625 with option
 626 .Fl s.
 627 In general, locale C is the fastest, then single-byte
 628 locales follow and multi-byte locales as the slowest but
 629 the correct collation order is always respected.
 630 As for the key specification, the simpler to process the
 631 lines the faster the search will be.
 632 .Pp
 633 When sorting by arithmetic value, using
 634 .Fl n
 635 results in much better performance than
 636 .Fl g
 637 so its use is encouraged
 638 whenever possible.