teach manpages about largefile's demise
[unleashed.git] / share / man / man1 / sort.1
blob4dac5848ea5beea56f698bdfebe16da114b13ce9
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document.  The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
45 .\" Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved
46 .\"
47 .TH SORT 1 "Oct 25, 2017"
48 .SH NAME
49 sort \- sort, merge, or sequence check text files
50 .SH SYNOPSIS
51 .LP
52 .nf
53 \fB/usr/bin/sort\fR [\fB-bcdfimMnru\fR] [\fB-k\fR \fIkeydef\fR] [\fB-o\fR \fIoutput\fR]
54      [\fB-S\fR \fIkmem\fR] [\fB-t\fR \fIchar\fR] [\fB-T\fR \fIdirectory\fR] [\fB-y\fR [\fIkmem\fR]]
55      [\fB-z\fR \fIrecsz\fR] [+\fIpos1\fR [-\fIpos2\fR]] [\fIfile\fR]...
56 .fi
58 .SH DESCRIPTION
59 .sp
60 .LP
61 The \fBsort\fR command sorts lines of all the named files together and writes
62 the result on the standard output.
63 .sp
64 .LP
65 Comparisons are based on one or more sort keys extracted from each line of
66 input. By default, there is one sort key, the entire input line. Lines are
67 ordered according to the collating sequence of the current locale.
68 .SH OPTIONS
69 .sp
70 .LP
71 The following options alter the default behavior:
72 .SS "/usr/bin/sort"
73 .sp
74 .ne 2
75 .na
76 \fB\fB-c\fR\fR
77 .ad
78 .RS 6n
79 Checks that the single input file is ordered as specified by the arguments and
80 the collating sequence of the current locale. The exit code is set and no
81 output is produced under any circumstances.
82 .RE
84 .sp
85 .ne 2
86 .na
87 \fB\fB-m\fR\fR
88 .ad
89 .RS 16n
90 Merges only. The input files are assumed to be already sorted.
91 .RE
93 .sp
94 .ne 2
95 .na
96 \fB\fB-o\fR \fIoutput\fR\fR
97 .ad
98 .RS 16n
99 Specifies the name of an output file to be used instead of the standard output.
100 This file can be the same as one of the input files.
104 .ne 2
106 \fB\fB-S\fR \fIkmem\fR\fR
108 .RS 16n
109 Specifies the maximum amount of swap-based memory used for sorting, in
110 kilobytes (the default unit). \fIkmem\fR can also be specified directly as a
111 number of bytes (b), kilobytes (k), megabytes (m), gigabytes (g), or terabytes
112 (t); or as a percentage (%) of the installed physical memory.
116 .ne 2
118 \fB\fB-T\fR \fIdirectory\fR\fR
120 .RS 16n
121 Specifies the \fIdirectory\fR in which to place temporary files.
125 .ne 2
127 \fB\fB-u\fR\fR
129 .RS 16n
130 Unique: suppresses all but one in each set of lines having equal keys. If used
131 with the \fB-c\fR option, checks that there are no lines with duplicate keys in
132 addition to checking that the input file is sorted.
136 .ne 2
138 \fB\fB-y\fR \fIkmem\fR\fR
140 .RS 16n
141 (obsolete). This option was used to specify the amount of main memory initially
142 used by \fBsort\fR. Its functionality is not appropriate for a virtual memory
143 system; memory usage for \fBsort\fR is now specified using the \fB-S\fR option.
147 .ne 2
149 \fB\fB-z\fR \fIrecsz\fR\fR
151 .RS 16n
152 (obsolete). This option was used to prevent abnormal termination when lines
153 longer than the system-dependent default buffer size are encountered. Because
154 \fBsort\fR automatically allocates buffers large enough to hold the longest
155 line, this option has no effect.
158 .SS "Ordering Options"
161 The default sort order depends on the value of \fBLC_COLLATE\fR. If
162 \fBLC_COLLATE\fR is set to \fBC\fR, sorting is in \fBASCII\fR order. If
163 \fBLC_COLLATE\fR is set to \fBen_US\fR, sorting is case insensitive except when
164 the two strings are otherwise equal and one has an uppercase letter earlier
165 than the other. Other locales have other sort orders.
168 The following options override the default ordering rules. When ordering
169 options appear independent of any key field specifications, the requested field
170 ordering rules are applied globally to all sort keys. When attached to a
171 specific key (see \fBSort Key Options\fR), the specified ordering options
172 override all global ordering options for that key. In the obsolescent forms, if
173 one or more of these options follows a \fI+pos1\fR option, it affects only the
174 key field specified by that preceding option.
176 .ne 2
178 \fB\fB-d\fR\fR
180 .RS 6n
181 Dictionary order: only letters, digits, and blanks (spaces and tabs) are
182 significant in comparisons.
186 .ne 2
188 \fB\fB-f\fR\fR
190 .RS 6n
191 Folds lower-case letters into upper case.
195 .ne 2
197 \fB\fB-i\fR\fR
199 .RS 6n
200 Ignores non-printable characters.
204 .ne 2
206 \fB\fB-M\fR\fR
208 .RS 6n
209 Compares as months. The first three non-blank characters of the field are
210 folded to upper case and compared. For example, in English the sorting order is
211 \fB"JAN" < "FEB" < .\|.\|. < "DEC"\fR. Invalid fields compare low to
212 \fB"JAN"\fR. The \fB-M\fR option implies the \fB-b\fR option (see below).
216 .ne 2
218 \fB\fB-n\fR\fR
220 .RS 6n
221 Restricts the sort key to an initial numeric string, consisting of optional
222 blank characters, optional minus sign, and zero or more digits with an optional
223 radix character and thousands separators (as defined in the current locale),
224 which is sorted by arithmetic value.  An empty digit string is treated as zero.
225 Leading zeros and signs on zeros do not affect ordering.
229 .ne 2
231 \fB\fB-r\fR\fR
233 .RS 6n
234 Reverses the sense of comparisons.
237 .SS "Field Separator Options"
240 The treatment of field separators can be altered using the following options:
242 .ne 2
244 \fB\fB-b\fR\fR
246 .RS 11n
247 Ignores leading blank characters when determining the starting and ending
248 positions of a restricted sort key. If the \fB-b\fR option is specified before
249 the first sort key option, it is applied to all sort key options. Otherwise,
250 the \fB-b\fR option can be attached independently to each \fB-k\fR
251 \fIfield_start\fR, \fIfield_end\fR, or +\fIpos1\fR or \(mi\fIpos2\fR
252 option-argument (see below).
256 .ne 2
258 \fB\fB-t\fR \fIchar\fR\fR
260 .RS 11n
261 Use \fIchar\fR as the field separator character. \fIchar\fR is not considered
262 to be part of a field (although it can be included in a sort key).  Each
263 occurrence of \fIchar\fR is significant (for example, \fI<char><char>\fR
264 delimits an empty field). If \fB-t\fR is not specified, blank characters are
265 used as default field separators; each maximal non-empty sequence of blank
266 characters that follows a non-blank character is a field separator.
269 .SS "Sort Key Options"
272 Sort keys can be specified using the options:
274 .ne 2
276 \fB\fB-k\fR \fIkeydef\fR\fR
278 .RS 19n
279 The \fIkeydef\fR argument is a restricted sort key field definition. The format
280 of this definition is:
282 .in +2
284 \fB-k\fR \fIfield_start\fR [\fItype\fR] [\fB,\fR\fIfield_end\fR [\fItype\fR] ]
286 .in -2
289 where:
291 .ne 2
293 \fB\fIfield_start\fR and \fIfield_end\fR\fR
295 .sp .6
296 .RS 4n
297 define a key field restricted to a portion of the line.
301 .ne 2
303 \fB\fItype\fR\fR
305 .sp .6
306 .RS 4n
307 is a modifier from the list of characters \fBbdfiMnr\fR. The \fBb\fR modifier
308 behaves like the \fB-b\fR option, but applies only to the \fIfield_start\fR or
309 \fIfield_end\fR to which it is attached and characters within a field are
310 counted from the first non-blank character in the field. (This applies
311 separately to \fIfirst_character\fR and \fIlast_character\fR.) The other
312 modifiers behave like the corresponding options, but apply only to the key
313 field to which they are attached. They have this effect if specified with
314 \fIfield_start\fR, \fIfield_end\fR or both.  If any modifier is attached to a
315 \fIfield_start\fR or to a \fIfield_end\fR, no option applies to either.
318 When there are multiple key fields, later keys are compared only after all
319 earlier keys compare equal. Except when the \fB-u\fR option is specified, lines
320 that otherwise compare equal are ordered as if none of the options \fB-d\fR,
321 \fB-f\fR, \fB-i\fR, \fB-n\fR or \fB-k\fR were present (but with \fB-r\fR still
322 in effect, if it was specified) and with all bytes in the lines significant to
323 the comparison.
325 The notation:
327 .in +2
329 \fB-k\fR \fIfield_start\fR[\fItype\fR][\fB,\fR\fIfield_end\fR[\fItype\fR]]
331 .in -2
334 defines a key field that begins at \fIfield_start\fR and ends at
335 \fIfield_end\fR inclusive, unless \fIfield_start\fR falls beyond the end of the
336 line or after \fIfield_end\fR, in which case the key field is empty. A missing
337 \fIfield_end\fR means the last character of the line.
339 A field comprises a maximal sequence of non-separating characters and, in the
340 absence of option \fB-t\fR, any preceding field separator.
342 The \fIfield_start\fR portion of the \fIkeydef\fR option-argument has the form:
344 .in +2
346 \fIfield_number\fR[\fB\&.\fR\fIfirst_character\fR]
348 .in -2
351 Fields and characters within fields are numbered starting with 1.
352 \fIfield_number\fR and \fIfirst_character\fR, interpreted as positive decimal
353 integers, specify the first character to be used as part of a sort key. If
354 \fB\&.\fR\fIfirst_character\fR is omitted, it refers to the first character of
355 the field.
357 The \fIfield_end\fR portion of the \fIkeydef\fR option-argument has the form:
359 .in +2
361 \fIfield_number\fR[\fB\&.\fR\fIlast_character\fR]
363 .in -2
366 The \fIfield_number\fR is as described above for \fIfield_start\fR.
367 \fIlast_character\fR, interpreted as a non-negative decimal integer, specifies
368 the last character to be used as part of the sort key. If \fIlast_character\fR
369 evaluates to zero or \fB\&.\fR\fIlast_character\fR is omitted, it refers to the
370 last character of the field specified by \fIfield_number\fR.
372 If the \fB-b\fR option or \fBb\fR type modifier is in effect, characters within
373 a field are counted from the first non-blank character in the field. (This
374 applies separately to \fIfirst_character\fR and \fIlast_character\fR.)
378 .ne 2
380 \fB[\fB+\fR\fIpos1\fR [\fB-\fR\fIpos2\fR]]\fR
382 .RS 19n
383 (obsolete). Provide functionality equivalent to the \fB-k\fR\fIkeydef\fR
384 option.
386 \fIpos1\fR and \fIpos2\fR each have the form \fIm\fR\fB\&.\fR\fIn\fR optionally
387 followed by one or more of the flags \fBbdfiMnr\fR. A starting position
388 specified by \fB+\fR\fIm\fR\fB\&.\fR\fIn\fR is interpreted to mean the
389 \fIn\fR+1st character in the \fIm\fR+1st field. A missing \fB\&.\fR\fIn\fR
390 means \fB\&.0\fR, indicating the first character of the \fIm\fR+1st field. If
391 the \fBb\fR flag is in effect \fIn\fR is counted from the first non-blank in
392 the \fIm\fR+1st field; \fB+\fR\fIm\fR\fB\&.0b\fR refers to the first non-blank
393 character in the \fIm\fR+1st field.
395 A last position specified by \fB\(mi\fR\fIm\fR\fB\&.\fR\fIn\fR is interpreted
396 to mean the \fIn\fRth character (including separators) after the last character
397 of the \fIm\fRth field. A missing \fB\&.\fR\fIn\fR means \fB\&.\fR0, indicating
398 the last character of the \fIm\fRth field. If the \fBb\fR flag is in effect
399 \fIn\fR is counted from the last leading blank in the \fIm\fR+1st field;
400 \fB\(mi\fR\fIm\fR\fB\&.\fR1\fBb\fR refers to the first non-blank in the
401 \fIm\fR+1st field.
403 The fully specified \fI+pos1\fR \fI\(mipos2\fR form with type modifiers \fBT\fR
404 and \fBU\fR:
406 .in +2
408 +\fBw\fR.\fBxT\fR -\fBy\fR.\fBzU\fR
410 .in -2
413 is equivalent to:
415 .in +2
417 undefined (z==0 & U contains \fIb\fR & \fI-t\fR is present)
418 -k w+1.x+1T,y.0U     (z==0 otherwise)
419 -k w+1.x+1T,y+1.zU   (z > 0)
421 .in -2
424 Implementations support at least nine occurrences of the sort keys (the
425 \fB-k\fR option and obsolescent \fB+\fR\fIpos1\fR and
426 \fB\(mi\fR\fIpos2\fR\fB)\fR which are significant in command line order. If no
427 sort key is specified, a default sort key of the entire line is used.
430 .SH OPERANDS
433 The following operand is supported:
435 .ne 2
437 \fB\fIfile\fR\fR
439 .RS 8n
440 A path name of a file to be sorted, merged or checked. If no \fIfile\fR
441 operands are specified, or if a \fIfile\fR operand is \fB\(mi\fR, the standard
442 input is used.
445 .SH EXAMPLES
448 In the following examples, first the preferred and then the obsolete way of
449 specifying \fBsort\fR keys are given as an aid to understanding the
450 relationship between the two forms.
452 \fBExample 1 \fRSorting with the Second Field as a sort Key
455 Either of the following commands sorts the contents of \fBinfile\fR with the
456 second field as the sort key:
459 .in +2
461 example% \fBsort -k 2,2 infile\fR
462 example% \fBsort +1 \(mi2 infile\fR
464 .in -2
468 \fBExample 2 \fRSorting in Reverse Order
471 Either of the following commands sorts, in reverse order, the contents of
472 \fBinfile1\fR and \fBinfile2\fR, placing the output in \fBoutfile\fR and using
473 the second character of the second field as the sort key (assuming that the
474 first character of the second field is the field separator):
477 .in +2
479 example% \fBsort -r -o outfile -k 2.2,2.2 infile1 infile2\fR
480 example% \fBsort -r -o outfile +1.1 \(mi1.2 infile1 infile2\fR
482 .in -2
486 \fBExample 3 \fRSorting Using a Specified Character in One of the Files
489 Either of the following commands sorts the contents of \fBinfile1\fR and
490 \fBinfile2\fR using the second non-blank character of the second field as the
491 sort key:
494 .in +2
496 example% \fBsort -k 2.2b,2.2b infile1 infile2\fR
497 example% \fBsort +1.1b \(mi1.2b infile1 infile2\fR
499 .in -2
503 \fBExample 4 \fRSorting by Numeric User ID
506 Either of the following commands prints the \fBpasswd\fR(4) file (user
507 database) sorted by the numeric user ID (the third colon-separated field):
510 .in +2
512 example% \fBsort -t : -k 3,3n /etc/passwd\fR
513 example% \fBsort -t : +2 \(mi3n /etc/passwd\fR
515 .in -2
519 \fBExample 5 \fRPrinting Sorted Lines Excluding Lines that Duplicate a Field
522 Either of the following commands prints the lines of the already sorted file
523 \fBinfile\fR, suppressing all but one occurrence of lines having the same third
524 field:
527 .in +2
529 example% \fBsort -um -k 3.1,3.0 infile\fR
530 example% \fBsort -um +2.0 \(mi3.0 infile\fR
532 .in -2
536 \fBExample 6 \fRSorting by Host IP Address
539 Either of the following commands prints the \fBhosts\fR(4) file (IPv4 hosts
540 database), sorted by the numeric \fBIP\fR address (the first four numeric
541 fields):
544 .in +2
546 example$ \fBsort -t . -k 1,1n -k 2,2n -k 3,3n -k 4,4n /etc/hosts\fR
547 example$ \fBsort -t . +0 -1n +1 -2n +2 -3n +3 -4n /etc/hosts\fR
549 .in -2
554 Since '\fB\&.\fR' is both the field delimiter and, in many locales, the decimal
555 separator, failure to specify both ends of the field leads to results where the
556 second field is interpreted as a fractional portion of the first, and so forth.
558 .SH ENVIRONMENT VARIABLES
561 See \fBenviron\fR(5) for descriptions of the following environment variables
562 that affect the execution of \fBsort\fR: \fBLANG\fR, \fBLC_ALL\fR,
563 \fBLC_COLLATE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
565 .ne 2
567 \fB\fBLC_CTYPE\fR\fR
569 .RS 14n
570 Determine the locale for the interpretation of sequences of bytes of text data
571 as characters (for example, single- versus multi-byte characters in arguments
572 and input files) and the behavior of character classification for the \fB-b\fR,
573 \fB-d\fR, \fB-f\fR, \fB-i\fR and \fB-n\fR options.
577 .ne 2
579 \fB\fBLC_NUMERIC\fR\fR
581 .RS 14n
582 Determine the locale for the definition of the radix character and thousands
583 separator for the \fB-n\fR option.
586 .SH EXIT STATUS
589 The following exit values are returned:
591 .ne 2
593 \fB\fB0\fR\fR
595 .RS 6n
596 All input files were output successfully, or \fB-c\fR was specified and the
597 input file was correctly sorted.
601 .ne 2
603 \fB\fB1\fR\fR
605 .RS 6n
606 Under the \fB-c\fR option, the file was not ordered as specified, or if the
607 \fB-c\fR and \fB-u\fR options were both specified, two input lines were found
608 with equal keys.
612 .ne 2
614 \fB\fB>1\fR\fR
616 .RS 6n
617 An error occurred.
620 .SH FILES
622 .ne 2
624 \fB\fB/var/tmp/stm???\fR\fR
626 .RS 19n
627 Temporary files
630 .SH ATTRIBUTES
633 See \fBattributes\fR(5) for descriptions of the following attributes:
634 .SS "/usr/bin/sort"
639 box;
640 c | c
641 l | l .
642 ATTRIBUTE TYPE  ATTRIBUTE VALUE
644 CSI     Enabled
646 Interface Stability     Standard
649 .SH SEE ALSO
652 \fBcomm\fR(1), \fBjoin\fR(1), \fBuniq\fR(1), \fBnl_langinfo\fR(3C),
653 \fBstrftime\fR(3C), \fBhosts\fR(4), \fBpasswd\fR(4), \fBattributes\fR(5),
654 \fBenviron\fR(5), \fBstandards\fR(5)
655 .SH DIAGNOSTICS
658 Comments and exits with non-zero status for various trouble conditions (for
659 example, when input lines are too long), and for disorders discovered under the
660 \fB-c\fR option.
661 .SH NOTES
664 When the last line of an input file is missing a \fBnew-line\fR character,
665 \fBsort\fR appends one, prints a warning message, and continues.
668 \fBsort\fR does not guarantee preservation of relative line ordering on equal
669 keys.
672 One can tune \fBsort\fR performance for a specific scenario using the \fB-S\fR
673 option. However, one should note in particular that \fBsort\fR has greater
674 knowledge of how to use a finite amount of memory for sorting than the virtual
675 memory system. Thus, a sort invoked to request an extremely large amount of
676 memory via the \fB-S\fR option could perform extremely poorly.
679 As noted, certain of the field modifiers (such as \fB-M\fR and \fB-d\fR) cause
680 the interpretation of input data to be done with reference to locale-specific
681 settings. The results of this interpretation can be unexpected if one's
682 expectations are not aligned with the conventions established by the locale. In
683 the case of the month keys, \fBsort\fR does not attempt to compensate for
684 approximate month abbreviations. The precise month abbreviations from
685 \fBnl_langinfo\fR(3C) or \fBstrftime\fR(3C) are the only ones recognized. For
686 printable or dictionary order, if these concepts are not well-defined by the
687 locale, an empty sort key might be the result, leading to the next key being
688 the significant one for determining the appropriate ordering.