usr.bin/sort/sort.1

   1 .\"     $NetBSD: sort.1,v 1.28 2009/08/22 21:55:08 dsl 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 August 22, 2009
  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 bcdfHimnrSsu
  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 n
 159 An initial numeric string, consisting of optional blank space, optional
 160 minus sign, and zero or more digits (including decimal point)
 161 .\" with
 162 .\" optional radix character and thousands
 163 .\" separator
 164 .\" (as defined in the current locale),
 165 is sorted by arithmetic value.
 166 (The
 167 .Fl n
 168 option no longer implies the
 169 .Fl b
 170 option.)
 171 .It Fl r
 172 Reverse the sense of comparisons.
 173 .El
 174 .Pp
 175 The treatment of field separators can be altered using these options:
 176 .Bl -tag -width Fl
 177 .It Fl b
 178 Ignores leading blank space when determining the start
 179 and end of a restricted sort key.
 180 A
 181 .Fl b
 182 option specified before the first
 183 .Fl k
 184 option applies globally to all
 185 .Fl k
 186 options.
 187 Otherwise, the
 188 .Fl b
 189 option can be attached independently to each
 190 .Ar field
 191 argument of the
 192 .Fl k
 193 option (see below).
 194 Note that the
 195 .Fl b
 196 option has no effect unless key fields are specified.
 197 .It Fl t Ar char
 198 .Ar char
 199 is used as the field separator character.
 200 The initial
 201 .Ar char
 202 is not considered to be part of a field when determining
 203 key offsets (see below).
 204 Each occurrence of
 205 .Ar char
 206 is significant (for example,
 207 .Dq Ar charchar
 208 delimits an empty field).
 209 If
 210 .Fl t
 211 is not specified, the default field separator is a sequence of
 212 blank-space characters, and consecutive blank spaces do
 213 .Em not
 214 delimit an empty field; further, the initial blank space
 215 .Em is
 216 considered part of a field when determining key offsets.
 217 .It Fl R Ar char
 218 .Ar char
 219 is used as the record separator character.
 220 This should be used with discretion;
 221 .Fl R Ar \*[Lt]alphanumeric\*[Gt]
 222 usually produces undesirable results.
 223 The default record separator is newline.
 224 .It Fl k Ar field1 Ns Op Li \&, Ns Ar field2
 225 Designates the starting position,
 226 .Ar field1 ,
 227 and optional ending position,
 228 .Ar field2 ,
 229 of a key field.
 230 The
 231 .Fl k
 232 option replaces the obsolescent options
 233 .Cm \(pl Ns Ar pos1
 234 and
 235 .Fl Ns Ar pos2 .
 236 .El
 237 .Pp
 238 The following operands are available:
 239 .Bl -tag -width Ar
 240 .It Ar file
 241 The pathname of a file to be sorted, merged, or checked.
 242 If no
 243 .Ar file
 244 operands are specified, or if
 245 a
 246 .Ar file
 247 operand is
 248 .Fl ,
 249 the standard input is used.
 250 .El
 251 .Pp
 252 A field is defined as a minimal sequence of characters followed by a
 253 field separator or a newline character.
 254 By default, the first
 255 blank space of a sequence of blank spaces acts as the field separator.
 256 All blank spaces in a sequence of blank spaces are considered
 257 as part of the next field; for example, all blank spaces at
 258 the beginning of a line are considered to be part of the
 259 first field.
 260 .Pp
 261 Fields are specified
 262 by the
 263 .Fl k
 264 .Ar field1 Ns Op \&, Ns Ar field2
 265 argument.
 266 A missing
 267 .Ar field2
 268 argument defaults to the end of a line.
 269 .Pp
 270 The arguments
 271 .Ar field1
 272 and
 273 .Ar field2
 274 have the form
 275 .Ar m Ns Li \&. Ns Ar n
 276 and can be followed by one or more of the letters
 277 .Cm b , d , f , i ,
 278 .Cm n ,
 279 and
 280 .Cm r ,
 281 which correspond to the options discussed above.
 282 A
 283 .Ar field1
 284 position specified by
 285 .Ar m Ns Li \&. Ns Ar n
 286 .Pq Ar m , n No \*[Gt] 0
 287 is interpreted as the
 288 .Ar n Ns th
 289 character in the
 290 .Ar m Ns th
 291 field.
 292 A missing
 293 .Li \&. Ns Ar n
 294 in
 295 .Ar field1
 296 means
 297 .Ql \&.1 ,
 298 indicating the first character of the
 299 .Ar m Ns th
 300 field; if the
 301 .Fl b
 302 option is in effect,
 303 .Ar n
 304 is counted from the first non-blank character in the
 305 .Ar m Ns th
 306 field;
 307 .Ar m Ns Li \&.1b
 308 refers to the first non-blank character in the
 309 .Ar m Ns th
 310 field.
 311 .Pp
 312 A
 313 .Ar field2
 314 position specified by
 315 .Ar m Ns Li \&. Ns Ar n
 316 is interpreted as
 317 the
 318 .Ar n Ns th
 319 character (including separators) of the
 320 .Ar m Ns th
 321 field.
 322 A missing
 323 .Li \&. Ns Ar n
 324 indicates the last character of the
 325 .Ar m Ns th
 326 field;
 327 .Ar m
 328 = \&0
 329 designates the end of a line.
 330 Thus the option
 331 .Fl k
 332 .Sm off
 333 .Xo
 334 .Ar v Li \&. Ar x Li \&,
 335 .Ar w Li \&. Ar y
 336 .Xc
 337 .Sm on
 338 is synonymous with the obsolescent option
 339 .Sm off
 340 .Cm \(pl Ar v-\&1 Li \&. Ar x-\&1
 341 .Fl Ar w-\&1 Li \&. Ar y ;
 342 .Sm on
 343 when
 344 .Ar y
 345 is omitted,
 346 .Fl k
 347 .Sm off
 348 .Ar v Li \&. Ar x Li \&, Ar w
 349 .Sm on
 350 is synonymous with
 351 .Sm off
 352 .Cm \(pl Ar v-\&1 Li \&. Ar x-\&1
 353 .Fl Ar w+1 Li \&.0 .
 354 .Sm on
 355 The obsolescent
 356 .Cm \(pl Ns Ar pos1
 357 .Fl Ns Ar pos2
 358 option is still supported, except for
 359 .Fl Ns Ar w Ns Li \&.0b ,
 360 which has no
 361 .Fl k
 362 equivalent.
 363 .Sh RETURN VALUES
 364 Sort exits with one of the following values:
 365 .Bl -tag -width flag -compact
 366 .It 0
 367 Normal behavior.
 368 .It 1
 369 On disorder (or non-uniqueness) with the
 370 .Fl c
 371 option
 372 .It 2
 373 An error occurred.
 374 .El
 375 .Sh ENVIRONMENT
 376 If the following environment variable exists, it is used by
 377 .Nm .
 378 .Bl -tag -width Ev
 379 .It Ev TMPDIR
 380 .Nm
 381 uses the contents of the
 382 .Ev TMPDIR
 383 environment variable as the path in which to store
 384 temporary files.
 385 .El
 386 .Sh FILES
 387 .Bl -tag -width outputNUMBER+some -compact
 388 .It Pa /tmp/sort.*
 389 Default temporary files.
 390 .It Ar output Ns NUMBER
 391 Temporary file which is used for output if
 392 .Ar output
 393 already exists.
 394 Once sorting is finished, this file replaces
 395 .Ar output
 396 (via
 397 .Xr link 2
 398 and
 399 .Xr unlink 2 ) .
 400 .El
 401 .Sh SEE ALSO
 402 .Xr comm 1 ,
 403 .Xr join 1 ,
 404 .Xr uniq 1 ,
 405 .Xr qsort 3 ,
 406 .Xr radixsort 3
 407 .Sh HISTORY
 408 A
 409 .Nm
 410 command appeared in
 411 .At v5 .
 412 This
 413 .Nm
 414 implementation appeared in
 415 .Bx 4.4
 416 and is used since
 417 .Nx 1.6 .
 418 .Sh BUGS
 419 Posix requires the locale's thousands separator be ignored in numbers.
 420 It may be faster to sort very large files in pieces and then explicitly
 421 merge them.
 422 .Sh NOTES
 423 This
 424 .Nm
 425 has no limits on input line length (other than imposed by available
 426 memory) or any restrictions on bytes allowed within lines.
 427 .Pp
 428 To protect data
 429 .Nm
 430 .Fl o
 431 calls
 432 .Xr link 2
 433 and
 434 .Xr unlink 2 ,
 435 and thus fails on protected directories.
 436 .Pp
 437 Input files should be text files.
 438 If file doesn't end with record separator (which is typically newline), the
 439 .Nm
 440 utility silently supplies one.
 441 .Pp
 442 The current
 443 .Nm
 444 uses lexicographic radix sorting, which requires
 445 that sort keys be kept in memory (as opposed to previous versions which used quick
 446 and merge sorts and did not.)
 447 Thus performance depends highly on efficient choice of sort keys, and the
 448 .Fl b
 449 option and the
 450 .Ar field2
 451 argument of the
 452 .Fl k
 453 option should be used whenever possible.
 454 Similarly,
 455 .Nm
 456 .Fl k1f
 457 is equivalent to
 458 .Nm
 459 .Fl f
 460 and may take twice as long.