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