usr.bin/sort/sort.1.in

   1 .\"     $OpenBSD: sort.1,v 1.45 2015/03/19 13:51:10 jmc 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 September 4, 2019
  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
  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
  56 .Fl Fl help
  57 .Nm
  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 an 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 attached 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.
 164 It has a more
 165 permissive format than that allowed by
 166 .Fl n
 167 but it has a significant performance drawback.
 168 .It Fl h , Fl Fl human-numeric-sort , Fl Fl sort=human-numeric
 169 Sort by numerical value, but take into account the SI suffix,
 170 if present.
 171 Sort first by numeric sign (negative, zero, or
 172 positive); then by SI suffix (either empty, or `k' or `K', or one
 173 of `MGTPEZY', in that order); and finally by numeric value.
 174 The SI suffix must immediately follow the number.
 175 For example, '12345K' sorts before '1M', because M is "larger" than K.
 176 This sort option is useful for sorting the output of a single invocation
 177 of 'df' command with
 178 .Fl h
 179 or
 180 .Fl H
 181 options (human-readable).
 182 .It Fl i , Fl Fl ignore-nonprinting
 183 Ignore all non-printable characters.
 184 .It Fl M , Fl Fl month-sort , Fl Fl sort=month
 185 Sort by month abbreviations.
 186 Unknown strings are considered smaller than the month names.
 187 .It Fl n , Fl Fl numeric-sort , Fl Fl sort=numeric
 188 Sort fields numerically by arithmetic value.
 189 Fields are supposed to have optional blanks in the beginning, an
 190 optional minus sign, zero or more digits (including decimal point and
 191 possible thousand separators).
 192 .It Fl R , Fl Fl random-sort , Fl Fl sort=random
 193 Sort by a random order.
 194 This is a random permutation of the inputs except that
 195 the equal keys sort together.
 196 It is implemented by hashing the input keys and sorting
 197 the hash values.
 198 The hash function is chosen randomly.
 199 The hash function is randomized by
 200 .Cm /dev/random
 201 content, or by file content if it is specified by
 202 .Fl Fl random-source .
 203 Even if multiple sort fields are specified,
 204 the same random hash function is used for all of them.
 205 .It Fl r , Fl Fl reverse
 206 Sort in reverse order.
 207 .It Fl V , Fl Fl version-sort
 208 Sort version numbers.
 209 The input lines are treated as file names in form
 210 PREFIX VERSION SUFFIX, where SUFFIX matches the regular expression
 211 "(\.([A-Za-z~][A-Za-z0-9~]*)?)*".
 212 The files are compared by their prefixes and versions (leading
 213 zeros are ignored in version numbers, see example below).
 214 If an input string does not match the pattern, then it is compared
 215 using the byte compare function.
 216 All string comparisons are performed in C locale, the locale
 217 environment setting is ignored.
 218 .Bl -tag -width indent
 219 .It Example:
 220 .It $ ls sort* | sort -V
 221 .It sort-1.022.tgz
 222 .It sort-1.23.tgz
 223 .It sort-1.23.1.tgz
 224 .It sort-1.024.tgz
 225 .It sort-1.024.003.
 226 .It sort-1.024.003.tgz
 227 .It sort-1.024.07.tgz
 228 .It sort-1.024.009.tgz
 229 .El
 230 .El
 231 .Pp
 232 The treatment of field separators can be altered using these options:
 233 .Bl -tag -width indent
 234 .It Fl b , Fl Fl ignore-leading-blanks
 235 Ignore leading blank space when determining the start
 236 and end of a restricted sort key (see
 237 .Fl k ) .
 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 .Fl k Ar field1 Ns Op , Ns Ar field2 ,
 251 .Fl Fl key Ns = Ns Ar field1 Ns Op , Ns Ar field2
 252 .Xc
 253 Define a restricted sort key that has the starting position
 254 .Ar field1 ,
 255 and optional ending position
 256 .Ar field2
 257 of a key field.
 258 The
 259 .Fl k
 260 option may be specified multiple times,
 261 in which case subsequent keys are compared when earlier keys compare equal.
 262 The
 263 .Fl k
 264 option replaces the obsolete options
 265 .Cm \(pl Ns Ar pos1
 266 and
 267 .Fl Ns Ar pos2 ,
 268 but the old notation is also supported.
 269 .It Fl t Ar char , Fl Fl field-separator Ns = Ns Ar char
 270 Use
 271 .Ar char
 272 as a field separator character.
 273 The initial
 274 .Ar char
 275 is not considered to be part of a field when determining key offsets.
 276 Each occurrence of
 277 .Ar char
 278 is significant (for example,
 279 .Dq Ar charchar
 280 delimits an empty field).
 281 If
 282 .Fl t
 283 is not specified, the default field separator is a sequence of
 284 blank space characters, and consecutive blank spaces do
 285 .Em not
 286 delimit an empty field, however, the initial blank space
 287 .Em is
 288 considered part of a field when determining key offsets.
 289 To use NUL as field separator, use
 290 .Fl t
 291 \'\\0\'.
 292 .It Fl z , Fl Fl zero-terminated
 293 Use NUL as record separator.
 294 By default, records in the files are supposed to be separated by
 295 the newline characters.
 296 With this option, NUL (\'\\0\') is used as a record separator character.
 297 .El
 298 .Pp
 299 Other options:
 300 .Bl -tag -width indent
 301 .It Fl Fl batch-size Ns = Ns Ar num
 302 Specify maximum number of files that can be opened by
 303 .Nm
 304 at once.
 305 This option affects behavior when having many input files or using
 306 temporary files.
 307 The default value is 16.
 308 .It Fl Fl compress-program Ns = Ns Ar PROGRAM
 309 Use PROGRAM to compress temporary files.
 310 PROGRAM must compress standard input to standard output, when called
 311 without arguments.
 312 When called with argument
 313 .Fl d
 314 it must decompress standard input to standard output.
 315 If PROGRAM fails,
 316 .Nm
 317 must exit with error.
 318 An example of PROGRAM that can be used here is bzip2.
 319 .It Fl Fl random-source Ns = Ns Ar filename
 320 In random sort, the file content is used as the source of the 'seed' data
 321 for the hash function choice.
 322 Two invocations of random sort with the same seed data will use
 323 the same hash function and will produce the same result if the input is
 324 also identical.
 325 By default, file
 326 .Cm /dev/random
 327 is used.
 328 .It Fl Fl debug
 329 Print some extra information about the sorting process to the
 330 standard output.
 331 %%THREADS%%.It Fl Fl parallel
 332 %%THREADS%%Set the maximum number of execution threads.
 333 %%THREADS%%Default number equals to the number of CPUs.
 334 .It Fl Fl files0-from Ns = Ns Ar filename
 335 Take the input file list from the file
 336 .Ar filename .
 337 The file names must be separated by NUL
 338 (like the output produced by the command "find ... -print0").
 339 .It Fl Fl radixsort
 340 Try to use radix sort, if the sort specifications allow.
 341 The radix sort can only be used for trivial locales (C and POSIX),
 342 and it cannot be used for numeric or month sort.
 343 Radix sort is very fast and stable.
 344 .It Fl Fl mergesort
 345 Use mergesort.
 346 This is a universal algorithm that can always be used,
 347 but it is not always the fastest.
 348 .It Fl Fl qsort
 349 Try to use quick sort, if the sort specifications allow.
 350 This sort algorithm cannot be used with
 351 .Fl u
 352 and
 353 .Fl s .
 354 .It Fl Fl heapsort
 355 Try to use heap sort, if the sort specifications allow.
 356 This sort algorithm cannot be used with
 357 .Fl u
 358 and
 359 .Fl s .
 360 .It Fl Fl mmap
 361 Try to use file memory mapping system call.
 362 It may increase speed in some cases.
 363 .El
 364 .Pp
 365 The following operands are available:
 366 .Bl -tag -width indent
 367 .It Ar file
 368 The pathname of a file to be sorted, merged, or checked.
 369 If no
 370 .Ar file
 371 operands are specified, or if a
 372 .Ar file
 373 operand is
 374 .Fl ,
 375 the standard input is used.
 376 .El
 377 .Pp
 378 A field is defined as a maximal sequence of characters other than the
 379 field separator and record separator (newline by default).
 380 Initial blank spaces are included in the field unless
 381 .Fl b
 382 has been specified;
 383 the first blank space of a sequence of blank spaces acts as the field
 384 separator and is included in the field (unless
 385 .Fl t
 386 is specified).
 387 For example, all blank spaces at the beginning of a line are
 388 considered to be part of the first field.
 389 .Pp
 390 Fields are specified by the
 391 .Sm off
 392 .Fl k\ \& Ar field1 Op , Ar field2
 393 .Sm on
 394 command-line option.
 395 If
 396 .Ar field2
 397 is missing, the end of the key defaults to the end of the line.
 398 .Pp
 399 The arguments
 400 .Ar field1
 401 and
 402 .Ar field2
 403 have the form
 404 .Em m.n
 405 .Em (m,n > 0)
 406 and can be followed by one or more of the modifiers
 407 .Cm b , d , f , i ,
 408 .Cm n , g , M
 409 and
 410 .Cm r ,
 411 which correspond to the options discussed above.
 412 When
 413 .Cm b
 414 is specified it applies only to
 415 .Ar field1
 416 or
 417 .Ar field2
 418 where it is specified while the rest of the modifiers
 419 apply to the whole key field regardless if they are
 420 specified only with
 421 .Ar field1
 422 or
 423 .Ar field2
 424 or both.
 425 A
 426 .Ar field1
 427 position specified by
 428 .Em m.n
 429 is interpreted as the
 430 .Em n Ns th
 431 character from the beginning of the
 432 .Em m Ns th
 433 field.
 434 A missing
 435 .Em \&.n
 436 in
 437 .Ar field1
 438 means
 439 .Ql \&.1 ,
 440 indicating the first character of the
 441 .Em m Ns th
 442 field; if the
 443 .Fl b
 444 option is in effect,
 445 .Em n
 446 is counted from the first non-blank character in the
 447 .Em m Ns th
 448 field;
 449 .Em m Ns \&.1b
 450 refers to the first non-blank character in the
 451 .Em m Ns th
 452 field.
 453 .No 1\&. Ns Em n
 454 refers to the
 455 .Em n Ns th
 456 character from the beginning of the line;
 457 if
 458 .Em n
 459 is greater than the length of the line, the field is taken to be empty.
 460 .Pp
 461 .Em n Ns th
 462 positions are always counted from the field beginning, even if the field
 463 is shorter than the number of specified positions.
 464 Thus, the key can really start from a position in a subsequent field.
 465 .Pp
 466 A
 467 .Ar field2
 468 position specified by
 469 .Em m.n
 470 is interpreted as the
 471 .Em n Ns th
 472 character (including separators) from the beginning of the
 473 .Em m Ns th
 474 field.
 475 A missing
 476 .Em \&.n
 477 indicates the last character of the
 478 .Em m Ns th
 479 field;
 480 .Em m
 481 = \&0
 482 designates the end of a line.
 483 Thus the option
 484 .Fl k Ar v.x,w.y
 485 is synonymous with the obsolete option
 486 .Cm \(pl Ns Ar v-\&1.x-\&1
 487 .Fl Ns Ar w-\&1.y ;
 488 when
 489 .Em y
 490 is omitted,
 491 .Fl k Ar v.x,w
 492 is synonymous with
 493 .Cm \(pl Ns Ar v-\&1.x-\&1
 494 .Fl Ns Ar w\&.0 .
 495 The obsolete
 496 .Cm \(pl Ns Ar pos1
 497 .Fl Ns Ar pos2
 498 option is still supported, except for
 499 .Fl Ns Ar w\&.0b ,
 500 which has no
 501 .Fl k
 502 equivalent.
 503 .Sh ENVIRONMENT
 504 .Bl -tag -width Fl
 505 .It Ev LC_COLLATE
 506 Locale settings to be used to determine the collation for
 507 sorting records.
 508 .It Ev LC_CTYPE
 509 Locale settings to be used to case conversion and classification
 510 of characters, that is, which characters are considered
 511 whitespaces, etc.
 512 .It Ev LC_MESSAGES
 513 Locale settings that determine the language of output messages
 514 that
 515 .Nm
 516 prints out.
 517 .It Ev LC_NUMERIC
 518 Locale settings that determine the number format used in numeric sort.
 519 .It Ev LC_TIME
 520 Locale settings that determine the month format used in month sort.
 521 .It Ev LC_ALL
 522 Locale settings that override all of the above locale settings.
 523 This environment variable can be used to set all these settings
 524 to the same value at once.
 525 .It Ev LANG
 526 Used as a last resort to determine different kinds of locale-specific
 527 behavior if neither the respective environment variable, nor
 528 .Ev LC_ALL
 529 are set.
 530 %%NLS%%.It Ev NLSPATH
 531 %%NLS%%Path to NLS catalogs.
 532 .It Ev TMPDIR
 533 Path to the directory in which temporary files will be stored.
 534 Note that
 535 .Ev TMPDIR
 536 may be overridden by the
 537 .Fl T
 538 option.
 539 .It Ev GNUSORT_NUMERIC_COMPATIBILITY
 540 If defined
 541 .Fl t
 542 will not override the locale numeric symbols, that is, thousand
 543 separators and decimal separators.
 544 By default, if we specify
 545 .Fl t
 546 with the same symbol as the thousand separator or decimal point,
 547 the symbol will be treated as the field separator.
 548 Older behavior was less definite; the symbol was treated as both field
 549 separator and numeric separator, simultaneously.
 550 This environment variable enables the old behavior.
 551 .El
 552 .Sh FILES
 553 .Bl -tag -width Pa -compact
 554 .It Pa /var/tmp/.bsdsort.PID.*
 555 Temporary files.
 556 .It Pa /dev/random
 557 Default seed file for the random sort.
 558 .El
 559 .Sh EXIT STATUS
 560 The
 561 .Nm
 562 utility shall exit with one of the following values:
 563 .Pp
 564 .Bl -tag -width flag -compact
 565 .It 0
 566 Successfully sorted the input files or if used with
 567 .Fl c
 568 or
 569 .Fl C ,
 570 the input file already met the sorting criteria.
 571 .It 1
 572 On disorder (or non-uniqueness) with the
 573 .Fl c
 574 or
 575 .Fl C
 576 options.
 577 .It 2
 578 An error occurred.
 579 .El
 580 .Sh SEE ALSO
 581 .Xr comm 1 ,
 582 .Xr join 1 ,
 583 .Xr uniq 1
 584 .Sh STANDARDS
 585 The
 586 .Nm
 587 utility is compliant with the
 588 .St -p1003.1-2008
 589 specification.
 590 .Pp
 591 The flags
 592 .Op Fl ghRMSsTVz
 593 are extensions to the POSIX specification.
 594 .Pp
 595 All long options are extensions to the specification, some of them are
 596 provided for compatibility with GNU versions and some of them are
 597 own extensions.
 598 .Pp
 599 The old key notations
 600 .Cm \(pl Ns Ar pos1
 601 and
 602 .Fl Ns Ar pos2
 603 come from older versions of
 604 .Nm
 605 and are still supported but their use is highly discouraged.
 606 .Sh HISTORY
 607 A
 608 .Nm
 609 command first appeared in
 610 .At v1 .
 611 .Sh AUTHORS
 612 .An Gabor Kovesdan Aq Mt gabor@FreeBSD.org ,
 613 .Pp
 614 .An Oleg Moskalenko Aq Mt mom040267@gmail.com
 615 .Sh NOTES
 616 This implementation of
 617 .Nm
 618 has no limits on input line length (other than imposed by available
 619 memory) or any restrictions on bytes allowed within lines.
 620 .Pp
 621 The performance depends highly on locale settings,
 622 efficient choice of sort keys and key complexity.
 623 The fastest sort is with locale C, on whole lines,
 624 with option
 625 .Fl s .
 626 In general, locale C is the fastest, then single-byte
 627 locales follow and multi-byte locales as the slowest but
 628 the correct collation order is always respected.
 629 As for the key specification, the simpler to process the
 630 lines the faster the search will be.
 631 .Pp
 632 When sorting by arithmetic value, using
 633 .Fl n
 634 results in much better performance than
 635 .Fl g
 636 so its use is encouraged
 637 whenever possible.