3 @setfilename coreutils.info
5 @settitle GNU Coreutils @value{VERSION}
6 @documentencoding UTF-8
7 @set txicodequoteundirected
8 @set txicodequotebacktick
13 @include constants.texi
15 @c Define new indices.
19 @c Put everything in one index (arbitrarily chosen to be the concept index).
29 * Coreutils: (coreutils). Core GNU (file, text, shell) utilities.
30 * Common options: (coreutils)Common options.
31 * File permissions: (coreutils)File permissions. Access modes.
32 * Date input formats: (coreutils)Date input formats.
35 @c FIXME: the following need documentation
36 @c * [: (coreutils)[ invocation. File/string tests.
37 @c * pinky: (coreutils)pinky invocation. FIXME.
39 @dircategory Individual utilities
41 * arch: (coreutils)arch invocation. Print machine hardware name.
42 * b2sum: (coreutils)b2sum invocation. Print or check BLAKE2 digests.
43 * base32: (coreutils)base32 invocation. Base32 encode/decode data.
44 * base64: (coreutils)base64 invocation. Base64 encode/decode data.
45 * basename: (coreutils)basename invocation. Strip directory and suffix.
46 * basenc: (coreutils)basenc invocation. Encoding/decoding of data.
47 * cat: (coreutils)cat invocation. Concatenate and write files.
48 * chcon: (coreutils)chcon invocation. Change SELinux CTX of files.
49 * chgrp: (coreutils)chgrp invocation. Change file groups.
50 * chmod: (coreutils)chmod invocation. Change access permissions.
51 * chown: (coreutils)chown invocation. Change file owners and groups.
52 * chroot: (coreutils)chroot invocation. Specify the root directory.
53 * cksum: (coreutils)cksum invocation. Print POSIX CRC checksum.
54 * comm: (coreutils)comm invocation. Compare sorted files by line.
55 * cp: (coreutils)cp invocation. Copy files.
56 * csplit: (coreutils)csplit invocation. Split by context.
57 * cut: (coreutils)cut invocation. Print selected parts of lines.
58 * date: (coreutils)date invocation. Print/set system date and time.
59 * dd: (coreutils)dd invocation. Copy and convert a file.
60 * df: (coreutils)df invocation. Report file system usage.
61 * dir: (coreutils)dir invocation. List directories briefly.
62 * dircolors: (coreutils)dircolors invocation. Color setup for ls.
63 * dirname: (coreutils)dirname invocation. Strip last file name component.
64 * du: (coreutils)du invocation. Report file usage.
65 * echo: (coreutils)echo invocation. Print a line of text.
66 * env: (coreutils)env invocation. Modify the environment.
67 * expand: (coreutils)expand invocation. Convert tabs to spaces.
68 * expr: (coreutils)expr invocation. Evaluate expressions.
69 * factor: (coreutils)factor invocation. Print prime factors
70 * false: (coreutils)false invocation. Do nothing, unsuccessfully.
71 * fmt: (coreutils)fmt invocation. Reformat paragraph text.
72 * fold: (coreutils)fold invocation. Wrap long input lines.
73 * groups: (coreutils)groups invocation. Print group names a user is in.
74 * head: (coreutils)head invocation. Output the first part of files.
75 * hostid: (coreutils)hostid invocation. Print numeric host identifier.
76 * hostname: (coreutils)hostname invocation. Print or set system name.
77 * id: (coreutils)id invocation. Print user identity.
78 * install: (coreutils)install invocation. Copy files and set attributes.
79 * join: (coreutils)join invocation. Join lines on a common field.
80 * kill: (coreutils)kill invocation. Send a signal to processes.
81 * link: (coreutils)link invocation. Make hard links between files.
82 * ln: (coreutils)ln invocation. Make links between files.
83 * logname: (coreutils)logname invocation. Print current login name.
84 * ls: (coreutils)ls invocation. List directory contents.
85 * md5sum: (coreutils)md5sum invocation. Print or check MD5 digests.
86 * mkdir: (coreutils)mkdir invocation. Create directories.
87 * mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes).
88 * mknod: (coreutils)mknod invocation. Create special files.
89 * mktemp: (coreutils)mktemp invocation. Create temporary files.
90 * mv: (coreutils)mv invocation. Rename files.
91 * nice: (coreutils)nice invocation. Modify niceness.
92 * nl: (coreutils)nl invocation. Number lines and write files.
93 * nohup: (coreutils)nohup invocation. Immunize to hangups.
94 * nproc: (coreutils)nproc invocation. Print the number of processors.
95 * numfmt: (coreutils)numfmt invocation. Reformat numbers.
96 * od: (coreutils)od invocation. Dump files in octal, etc.
97 * paste: (coreutils)paste invocation. Merge lines of files.
98 * pathchk: (coreutils)pathchk invocation. Check file name portability.
99 * pr: (coreutils)pr invocation. Paginate or columnate files.
100 * printenv: (coreutils)printenv invocation. Print environment variables.
101 * printf: (coreutils)printf invocation. Format and print data.
102 * ptx: (coreutils)ptx invocation. Produce permuted indexes.
103 * pwd: (coreutils)pwd invocation. Print working directory.
104 * readlink: (coreutils)readlink invocation. Print referent of a symlink.
105 * realpath: (coreutils)realpath invocation. Print resolved file names.
106 * rm: (coreutils)rm invocation. Remove files.
107 * rmdir: (coreutils)rmdir invocation. Remove empty directories.
108 * runcon: (coreutils)runcon invocation. Run in specified SELinux CTX.
109 * seq: (coreutils)seq invocation. Print numeric sequences
110 * sha1sum: (coreutils)sha1sum invocation. Print or check SHA-1 digests.
111 * sha2: (coreutils)sha2 utilities. Print or check SHA-2 digests.
112 * shred: (coreutils)shred invocation. Remove files more securely.
113 * shuf: (coreutils)shuf invocation. Shuffling text files.
114 * sleep: (coreutils)sleep invocation. Delay for a specified time.
115 * sort: (coreutils)sort invocation. Sort text files.
116 * split: (coreutils)split invocation. Split into pieces.
117 * stat: (coreutils)stat invocation. Report file(system) status.
118 * stdbuf: (coreutils)stdbuf invocation. Modify stdio buffering.
119 * stty: (coreutils)stty invocation. Print/change terminal settings.
120 * sum: (coreutils)sum invocation. Print traditional checksum.
121 * sync: (coreutils)sync invocation. Sync files to stable storage.
122 * tac: (coreutils)tac invocation. Reverse files.
123 * tail: (coreutils)tail invocation. Output the last part of files.
124 * tee: (coreutils)tee invocation. Redirect to multiple files.
125 * test: (coreutils)test invocation. File/string tests.
126 * timeout: (coreutils)timeout invocation. Run with time limit.
127 * touch: (coreutils)touch invocation. Change file timestamps.
128 * tr: (coreutils)tr invocation. Translate characters.
129 * true: (coreutils)true invocation. Do nothing, successfully.
130 * truncate: (coreutils)truncate invocation. Shrink/extend size of a file.
131 * tsort: (coreutils)tsort invocation. Topological sort.
132 * tty: (coreutils)tty invocation. Print terminal name.
133 * uname: (coreutils)uname invocation. Print system information.
134 * unexpand: (coreutils)unexpand invocation. Convert spaces to tabs.
135 * uniq: (coreutils)uniq invocation. Uniquify files.
136 * unlink: (coreutils)unlink invocation. Removal via unlink(2).
137 * uptime: (coreutils)uptime invocation. Print uptime and load.
138 * users: (coreutils)users invocation. Print current user names.
139 * vdir: (coreutils)vdir invocation. List directories verbosely.
140 * wc: (coreutils)wc invocation. Line, word, and byte counts.
141 * who: (coreutils)who invocation. Print who is logged in.
142 * whoami: (coreutils)whoami invocation. Print effective user ID.
143 * yes: (coreutils)yes invocation. Print a string indefinitely.
147 This manual documents version @value{VERSION} of the GNU core
148 utilities, including the standard programs for text and file manipulation.
150 Copyright @copyright{} 1994--2023 Free Software Foundation, Inc.
153 Permission is granted to copy, distribute and/or modify this document
154 under the terms of the GNU Free Documentation License, Version 1.3 or
155 any later version published by the Free Software Foundation; with no
156 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
157 Texts. A copy of the license is included in the section entitled ``GNU
158 Free Documentation License''.
163 @title GNU @code{Coreutils}
164 @subtitle Core GNU utilities
165 @subtitle for version @value{VERSION}, @value{UPDATED}
166 @author David MacKenzie et al.
169 @vskip 0pt plus 1filll
182 @cindex core utilities
183 @cindex text utilities
184 @cindex shell utilities
185 @cindex file utilities
188 * Introduction:: Caveats, overview, and authors
189 * Common options:: Common options
190 * Output of entire files:: cat tac nl od base32 base64 basenc
191 * Formatting file contents:: fmt pr fold
192 * Output of parts of files:: head tail split csplit
193 * Summarizing files:: wc sum cksum b2sum md5sum sha1sum sha2
194 * Operating on sorted files:: sort shuf uniq comm ptx tsort
195 * Operating on fields:: cut paste join
196 * Operating on characters:: tr expand unexpand
197 * Directory listing:: ls dir vdir dircolors
198 * Basic operations:: cp dd install mv rm shred
199 * Special file types:: mkdir rmdir unlink mkfifo mknod ln link readlink
200 * Changing file attributes:: chgrp chmod chown touch
201 * File space usage:: df du stat sync truncate
202 * Printing text:: echo printf yes
203 * Conditions:: false true test expr
205 * File name manipulation:: dirname basename pathchk mktemp realpath
206 * Working context:: pwd stty printenv tty
207 * User information:: id logname whoami groups users who
208 * System context:: date arch nproc uname hostname hostid uptime
209 * SELinux context:: chcon runcon
210 * Modified command invocation:: chroot env nice nohup stdbuf timeout
211 * Process control:: kill
213 * Numeric operations:: factor numfmt seq
214 * File permissions:: Access modes
215 * File timestamps:: File timestamp issues
216 * Date input formats:: Specifying date strings
217 * Version sort ordering:: Details on version-sort algorithm
218 * Opening the software toolbox:: The software tools philosophy
219 * GNU Free Documentation License:: Copying and sharing this manual
220 * Concept index:: General index
223 --- The Detailed Node Listing ---
227 * Exit status:: Indicating program success or failure
228 * Backup options:: Backup options
229 * Block size:: Block size
230 * Floating point:: Floating point number representation
231 * Signal specifications:: Specifying signals
232 * Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax
233 * Random sources:: Sources of random data
234 * Target directory:: Target directory
235 * Trailing slashes:: Trailing slashes
236 * Traversing symlinks:: Traversing symlinks to directories
237 * Treating / specially:: Treating / specially
238 * Standards conformance:: Standards conformance
239 * Multi-call invocation:: Multi-call program invocation
241 Output of entire files
243 * cat invocation:: Concatenate and write files
244 * tac invocation:: Concatenate and write files in reverse
245 * nl invocation:: Number lines and write files
246 * od invocation:: Write files in octal or other formats
247 * base32 invocation:: Transform data into printable data
248 * base64 invocation:: Transform data into printable data
249 * basenc invocation:: Transform data into printable data
251 Formatting file contents
253 * fmt invocation:: Reformat paragraph text
254 * pr invocation:: Paginate or columnate files for printing
255 * fold invocation:: Wrap input lines to fit in specified width
257 Output of parts of files
259 * head invocation:: Output the first part of files
260 * tail invocation:: Output the last part of files
261 * split invocation:: Split a file into fixed-size pieces
262 * csplit invocation:: Split a file into context-determined pieces
266 * wc invocation:: Print newline, word, and byte counts
267 * sum invocation:: Print checksum and block counts
268 * cksum invocation:: Print CRC checksum and byte counts
269 * b2sum invocation:: Print or check BLAKE2 digests
270 * md5sum invocation:: Print or check MD5 digests
271 * sha1sum invocation:: Print or check SHA-1 digests
272 * sha2 utilities:: Print or check SHA-2 digests
274 Operating on sorted files
276 * sort invocation:: Sort text files
277 * shuf invocation:: Shuffle text files
278 * uniq invocation:: Uniquify files
279 * comm invocation:: Compare two sorted files line by line
280 * ptx invocation:: Produce a permuted index of file contents
281 * tsort invocation:: Topological sort
283 @command{ptx}: Produce permuted indexes
285 * General options in ptx:: Options which affect general program behavior
286 * Charset selection in ptx:: Underlying character set considerations
287 * Input processing in ptx:: Input fields, contexts, and keyword selection
288 * Output formatting in ptx:: Types of output format, and sizing the fields
289 * Compatibility in ptx:: The GNU extensions to @command{ptx}
293 * cut invocation:: Print selected parts of lines
294 * paste invocation:: Merge lines of files
295 * join invocation:: Join lines on a common field
297 Operating on characters
299 * tr invocation:: Translate, squeeze, and/or delete characters
300 * expand invocation:: Convert tabs to spaces
301 * unexpand invocation:: Convert spaces to tabs
303 @command{tr}: Translate, squeeze, and/or delete characters
305 * Character arrays:: Specifying arrays of characters
306 * Translating:: Changing one set of characters to another
307 * Squeezing and deleting:: Removing characters
311 * ls invocation:: List directory contents
312 * dir invocation:: Briefly list directory contents
313 * vdir invocation:: Verbosely list directory contents
314 * dircolors invocation:: Color setup for @command{ls}
316 @command{ls}: List directory contents
318 * Which files are listed:: Which files are listed
319 * What information is listed:: What information is listed
320 * Sorting the output:: Sorting the output
321 * General output formatting:: General output formatting
322 * Formatting the file names:: Formatting the file names
326 * cp invocation:: Copy files and directories
327 * dd invocation:: Convert and copy a file
328 * install invocation:: Copy files and set attributes
329 * mv invocation:: Move (rename) files
330 * rm invocation:: Remove files or directories
331 * shred invocation:: Remove files more securely
335 * link invocation:: Make a hard link via the link syscall
336 * ln invocation:: Make links between files
337 * mkdir invocation:: Make directories
338 * mkfifo invocation:: Make FIFOs (named pipes)
339 * mknod invocation:: Make block or character special files
340 * readlink invocation:: Print value of a symlink or canonical file name
341 * rmdir invocation:: Remove empty directories
342 * unlink invocation:: Remove files via unlink syscall
344 Changing file attributes
346 * chown invocation:: Change file owner and group
347 * chgrp invocation:: Change group ownership
348 * chmod invocation:: Change access permissions
349 * touch invocation:: Change file timestamps
353 * df invocation:: Report file system space usage
354 * du invocation:: Estimate file space usage
355 * stat invocation:: Report file or file system status
356 * sync invocation:: Synchronize cached writes to persistent storage
357 * truncate invocation:: Shrink or extend the size of a file
361 * echo invocation:: Print a line of text
362 * printf invocation:: Format and print data
363 * yes invocation:: Print a string until interrupted
367 * false invocation:: Do nothing, unsuccessfully
368 * true invocation:: Do nothing, successfully
369 * test invocation:: Check file types and compare values
370 * expr invocation:: Evaluate expressions
372 @command{test}: Check file types and compare values
374 * File type tests:: File type tests
375 * Access permission tests:: Access permission tests
376 * File characteristic tests:: File characteristic tests
377 * String tests:: String tests
378 * Numeric tests:: Numeric tests
380 @command{expr}: Evaluate expression
382 * String expressions:: @code{+ : match substr index length}
383 * Numeric expressions:: @code{+ - * / %}
384 * Relations for expr:: @code{| & < <= = == != >= >}
385 * Examples of expr:: Examples of using @command{expr}
389 * tee invocation:: Redirect output to multiple files or processes
391 File name manipulation
393 * basename invocation:: Strip directory and suffix from a file name
394 * dirname invocation:: Strip last file name component
395 * pathchk invocation:: Check file name validity and portability
396 * mktemp invocation:: Create temporary file or directory
397 * realpath invocation:: Print resolved file names
401 * pwd invocation:: Print working directory
402 * stty invocation:: Print or change terminal characteristics
403 * printenv invocation:: Print all or some environment variables
404 * tty invocation:: Print file name of terminal on standard input
406 @command{stty}: Print or change terminal characteristics
408 * Control:: Control settings
409 * Input:: Input settings
410 * Output:: Output settings
411 * Local:: Local settings
412 * Combination:: Combination settings
413 * Characters:: Special characters
414 * Special:: Special settings
418 * id invocation:: Print user identity
419 * logname invocation:: Print current login name
420 * whoami invocation:: Print effective user ID
421 * groups invocation:: Print group names a user is in
422 * users invocation:: Print login names of users currently logged in
423 * who invocation:: Print who is currently logged in
427 * arch invocation:: Print machine hardware name
428 * date invocation:: Print or set system date and time
429 * nproc invocation:: Print the number of processors
430 * uname invocation:: Print system information
431 * hostname invocation:: Print or set system name
432 * hostid invocation:: Print numeric host identifier
433 * uptime invocation:: Print system uptime and load
435 @command{date}: Print or set system date and time
437 * Time conversion specifiers:: %[HIklMNpPrRsSTXzZ]
438 * Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY]
439 * Literal conversion specifiers:: %[%nt]
440 * Padding and other flags:: Pad with zeros, spaces, etc.
441 * Setting the time:: Changing the system clock
442 * Options for date:: Instead of the current time
443 * Date input formats:: Specifying date strings
444 * Examples of date:: Examples
448 * chcon invocation:: Change SELinux context of file
449 * runcon invocation:: Run a command in specified SELinux context
451 Modified command invocation
453 * chroot invocation:: Run a command with a different root directory
454 * env invocation:: Run a command in a modified environment
455 * nice invocation:: Run a command with modified niceness
456 * nohup invocation:: Run a command immune to hangups
457 * stdbuf invocation:: Run a command with modified I/O buffering
458 * timeout invocation:: Run a command with a time limit
462 * kill invocation:: Sending a signal to processes.
466 * sleep invocation:: Delay for a specified time
470 * factor invocation:: Print prime factors
471 * numfmt invocation:: Reformat numbers
472 * seq invocation:: Print numeric sequences
477 * File timestamps:: File timestamp issues
481 * Mode Structure:: Structure of file mode bits
482 * Symbolic Modes:: Mnemonic representation of file mode bits
483 * Numeric Modes:: File mode bits as octal numbers
484 * Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories
488 * General date syntax:: Common rules
489 * Calendar date items:: @samp{14 Nov 2022}
490 * Time of day items:: @samp{9:02pm}
491 * Time zone items:: @samp{UTC}, @samp{-0700}, @samp{+0900}, @dots{}
492 * Combined date and time of day items:: @samp{2022-11-14T21:02:42,000000-0500}
493 * Day of week items:: @samp{Monday} and others
494 * Relative items in date strings:: @samp{next tuesday, 2 years ago}
495 * Pure numbers in date strings:: @samp{20221114}, @samp{2102}
496 * Seconds since the Epoch:: @samp{@@1668477762}
497 * Specifying time zone rules:: @samp{TZ="America/New_York"}, @samp{TZ="UTC0"}
498 * Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al.
500 Version sorting order
502 * Version sort overview::
503 * Version sort implementation::
504 * Differences from Debian version sort::
505 * Advanced version sort topics::
507 Opening the software toolbox
509 * Toolbox introduction:: Toolbox introduction
510 * I/O redirection:: I/O redirection
511 * The who command:: The @command{who} command
512 * The cut command:: The @command{cut} command
513 * The sort command:: The @command{sort} command
514 * The uniq command:: The @command{uniq} command
515 * Putting the tools together:: Putting the tools together
519 * GNU Free Documentation License:: Copying and sharing this manual
526 @chapter Introduction
528 This manual is a work in progress: many sections make no attempt to explain
529 basic concepts in a way suitable for novices. Thus, if you are interested,
530 please get involved in improving this manual. The entire GNU community
534 The GNU utilities documented here are mostly compatible with the
536 @cindex bugs, reporting
538 Please report bugs to @email{bug-coreutils@@gnu.org}.
539 Include the version number, machine architecture, input files, and
540 any other information needed to reproduce the bug: your input, what you
541 expected, what you got, and why it is wrong.
543 If you have a problem with @command{sort} or @command{date}, try using the
544 @option{--debug} option, as it can often help find and fix problems without
545 having to wait for an answer to a bug report. If the debug output
546 does not suffice to fix the problem on your own, please compress and
547 attach it to the rest of your bug report.
549 Although diffs are welcome,
550 please include a description of the problem as well, since this is
551 sometimes difficult to infer. @xref{Bugs, , , gcc, Using and Porting GNU CC}.
557 @cindex MacKenzie, D.
560 This manual was originally derived from the Unix man pages in the
561 distributions, which were written by David MacKenzie and updated by Jim
562 Meyering. What you are reading now is the authoritative documentation
563 for these utilities; the man pages are no longer being maintained. The
564 original @command{fmt} man page was written by Ross Paterson. Fran@,{c}ois
565 Pinard did the initial conversion to Texinfo format. Karl Berry did the
566 indexing, some reorganization, and editing of the results. Brian
567 Youmans of the Free Software Foundation office staff combined the
568 manuals for textutils, fileutils, and sh-utils to produce the present
569 omnibus manual. Richard Stallman contributed his usual invaluable
570 insights to the overall process.
573 @chapter Common options
577 @itemx --backup[=@var{method}]
580 @vindex VERSION_CONTROL
581 @cindex backups, making
582 @xref{Backup options}.
583 Make a backup of each file that would otherwise be overwritten or removed.
586 @macro optBackupSuffix
587 @item -S @var{suffix}
588 @itemx --suffix=@var{suffix}
591 Append @var{suffix} to each backup file made with @option{-b}.
592 @xref{Backup options}.
595 @macro optTargetDirectory
596 @item -t @var{directory}
597 @itemx --target-directory=@var{directory}
599 @opindex --target-directory
600 @cindex target directory
601 @cindex destination directory
602 Specify the destination @var{directory}.
603 @xref{Target directory}.
606 @macro optNoTargetDirectory
608 @itemx --no-target-directory
610 @opindex --no-target-directory
611 @cindex target directory
612 @cindex destination directory
613 Do not treat the last operand specially when it is a directory or a
614 symbolic link to a directory. @xref{Target directory}.
618 @cindex output NUL-byte-terminated lines
619 Output a zero byte (ASCII NUL) at the end of each line,
620 rather than a newline. This option enables other programs to parse the
621 output even when that output would contain data with embedded newlines.
640 @macro optZeroTerminated
642 @itemx --zero-terminated
644 @opindex --zero-terminated
645 @cindex process zero-terminated items
646 Delimit items with a zero byte rather than a newline (ASCII LF).
647 I.e., treat input as items separated by ASCII NUL
648 and terminate output items with ASCII NUL.
649 This option can be useful in conjunction with @samp{perl -0} or
650 @samp{find -print0} and @samp{xargs -0} which do the same in order to
651 reliably handle arbitrary file names (even those containing blanks
652 or other special characters).
659 Append an SI-style abbreviation to each size, such as @samp{M} for
660 megabytes. Powers of 1000 are used, not 1024; @samp{M} stands for
661 1,000,000 bytes. This option is equivalent to
662 @option{--block-size=si}. Use the @option{-h} or
663 @option{--human-readable} option if
664 you prefer powers of 1024.
667 @macro optHumanReadable
669 @itemx --human-readable
671 @opindex --human-readable
672 @cindex human-readable output
673 Append a size letter to each size, such as @samp{M} for mebibytes.
674 Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
675 This option is equivalent to @option{--block-size=human-readable}.
676 Use the @option{--si} option if you prefer powers of 1000.
679 @macro optStripTrailingSlashes
680 @item --strip-trailing-slashes
681 @opindex --strip-trailing-slashes
682 @cindex stripping trailing slashes
683 Remove any trailing slashes from each @var{source} argument.
684 @xref{Trailing slashes}.
687 @macro mayConflictWithShellBuiltIn{cmd}
688 @cindex conflicts with shell built-ins
689 @cindex built-in shell commands, conflicts with
690 Due to shell aliases and built-in @command{\cmd\} functions, using an
691 unadorned @command{\cmd\} interactively or in a script may get you
692 different functionality than that described here. Invoke it via
693 @command{env} (i.e., @code{env \cmd\ @dots{}}) to avoid interference
698 @macro multiplierSuffixes{varName}
699 @var{\varName\} may be, or may be an integer optionally followed by,
700 one of the following multiplicative suffixes:
702 @samp{b} => 512 ("blocks")
703 @samp{KB} => 1000 (KiloBytes)
704 @samp{K} => 1024 (KibiBytes)
705 @samp{MB} => 1000*1000 (MegaBytes)
706 @samp{M} => 1024*1024 (MebiBytes)
707 @samp{GB} => 1000*1000*1000 (GigaBytes)
708 @samp{G} => 1024*1024*1024 (GibiBytes)
710 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y},
711 @samp{R}, and @samp{Q}.
712 Binary prefixes can be used, too: @samp{KiB}=@samp{K}, @samp{MiB}=@samp{M},
716 @c FIXME: same as above, but no ``blocks'' line.
717 @macro multiplierSuffixesNoBlocks{varName}
718 @var{\varName\} may be, or may be an integer optionally followed by,
719 one of the following multiplicative suffixes:
721 @samp{KB} => 1000 (KiloBytes)
722 @samp{K} => 1024 (KibiBytes)
723 @samp{MB} => 1000*1000 (MegaBytes)
724 @samp{M} => 1024*1024 (MebiBytes)
725 @samp{GB} => 1000*1000*1000 (GigaBytes)
726 @samp{G} => 1024*1024*1024 (GibiBytes)
728 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y},
729 @samp{R}, and @samp{Q}.
730 Binary prefixes can be used, too: @samp{KiB}=@samp{K}, @samp{MiB}=@samp{M},
734 @cindex common options
736 Certain options are available in all of these programs. Rather than
737 writing identical descriptions for each of the programs, they are
738 described here. (In fact, every GNU program accepts (or should accept)
741 @vindex POSIXLY_CORRECT
742 Normally options and operands can appear in any order, and programs act
743 as if all the options appear before any operands. For example,
744 @samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since
745 @samp{:} is an option-argument of @option{-t}. However, if the
746 @env{POSIXLY_CORRECT} environment variable is set, options must appear
747 before operands, unless otherwise specified for a particular command.
749 A few programs can usefully have trailing operands with leading
750 @samp{-}. With such a program, options must precede operands even if
751 @env{POSIXLY_CORRECT} is not set, and this fact is noted in the
752 program description. For example, the @command{env} command's options
753 must appear before its operands, since in some cases the operands
754 specify a command that itself contains options.
756 Most programs that accept long options recognize unambiguous
757 abbreviations of those options. For example, @samp{rmdir
758 --ignore-fail-on-non-empty} can be invoked as @samp{rmdir
759 --ignore-fail} or even @samp{rmdir --i}. Ambiguous options, such as
760 @samp{ls --h}, are identified as such.
762 Some of these programs recognize the @option{--help} and @option{--version}
763 options only when one of them is the sole command line argument. For
764 these programs, abbreviations of the long options are not always recognized.
771 Print a usage message listing all available options, then exit successfully.
775 @cindex version number, finding
776 Print the version number, then exit successfully.
780 @cindex option delimiter
781 Delimit the option list. Later arguments, if any, are treated as
782 operands even if they begin with @samp{-}. For example, @samp{sort --
783 -r} reads from the file named @file{-r}.
787 @cindex standard input
788 @cindex standard output
789 A single @samp{-} operand is not really an option, though it looks like one. It
790 stands for a file operand, and some tools treat it as standard input, or as
791 standard output if that is clear from the context. For example, @samp{sort -}
792 reads from standard input, and is equivalent to plain @samp{sort}. Unless
793 otherwise specified, a @samp{-} can appear as any operand that requires a file
797 Items shared between some programs:
799 * Backup options:: @option{-b} @option{-S}.
800 * Block size:: BLOCK_SIZE and @option{--block-size}.
801 * Signal specifications:: Specifying signals with @option{--signal}.
802 * Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax
803 * Random sources:: @option{--random-source}.
804 * Target directory:: Specifying a target directory.
805 * Trailing slashes:: @option{--strip-trailing-slashes}.
806 * Traversing symlinks:: @option{-H}, @option{-L}, or @option{-P}.
807 * Treating / specially:: @option{--preserve-root} and the converse.
808 * Special built-in utilities:: @command{break}, @command{:}, @dots{}
810 Items applicable to all programs:
812 * Exit status:: Indicating program success or failure.
813 * Floating point:: Floating point number representation.
814 * Standards conformance:: Conformance to the POSIX standard.
815 * Multi-call invocation:: Multi-call program invocation.
820 @section Backup options
822 @cindex backup options
824 Some GNU programs (at least @command{cp}, @command{install},
825 @command{ln}, and @command{mv}) optionally make backups of files
826 before writing new versions.
827 These options control the details of these backups. The options are also
828 briefly mentioned in the descriptions of the particular programs.
833 @itemx --backup[=@var{method}]
836 @vindex VERSION_CONTROL
837 @cindex backups, making
838 Make a backup of each file that would otherwise be overwritten or removed.
839 Without this option, the original versions are destroyed.
840 Use @var{method} to determine the type of backups to make.
841 When this option is used but @var{method} is not specified,
842 then the value of the @env{VERSION_CONTROL}
843 environment variable is used. And if @env{VERSION_CONTROL} is not set,
844 the default backup type is @samp{existing}.
846 Note that the short form of this option, @option{-b} does not accept any
847 argument. Using @option{-b} is equivalent to using @option{--backup=existing}.
849 @vindex version-control @r{Emacs variable}
850 This option corresponds to the Emacs variable @samp{version-control};
851 the values for @var{method} are the same as those used in Emacs.
852 This option also accepts more descriptive names.
853 The valid @var{method}s are (unique abbreviations are accepted):
858 @opindex none @r{backup method}
863 @opindex numbered @r{backup method}
864 Always make numbered backups.
868 @opindex existing @r{backup method}
869 Make numbered backups of files that already have them, simple backups
874 @opindex simple @r{backup method}
875 Always make simple backups. Please note @samp{never} is not to be
876 confused with @samp{none}.
880 @item -S @var{suffix}
881 @itemx --suffix=@var{suffix}
884 @cindex backup suffix
885 @vindex SIMPLE_BACKUP_SUFFIX
886 Append @var{suffix} to each backup file made with @option{-b}. If this
887 option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
888 environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not
889 set, the default is @samp{~}, just as in Emacs.
898 Some GNU programs (at least @command{df}, @command{du}, and
899 @command{ls}) display sizes in ``blocks''. You can adjust the block size
900 and method of display to make sizes easier to read. The block size
901 used for display is independent of any file system block size.
902 Fractional block counts are rounded up to the nearest integer.
904 @opindex --block-size=@var{size}
907 @vindex DF_BLOCK_SIZE
908 @vindex DU_BLOCK_SIZE
909 @vindex LS_BLOCK_SIZE
910 @vindex POSIXLY_CORRECT@r{, and block size}
912 The default block size is chosen by examining the following environment
913 variables in turn; the first one that is set determines the block size.
918 This specifies the default block size for the @command{df} command.
919 Similarly, @env{DU_BLOCK_SIZE} specifies the default for @command{du} and
920 @env{LS_BLOCK_SIZE} for @command{ls}.
923 This specifies the default block size for all three commands, if the
924 above command-specific environment variables are not set.
927 This specifies the default block size for all values that are normally
928 printed as blocks, if neither @env{BLOCK_SIZE} nor the above
929 command-specific environment variables are set. Unlike the other
930 environment variables, @env{BLOCKSIZE} does not affect values that are
931 normally printed as byte counts, e.g., the file sizes contained in
934 @item POSIXLY_CORRECT
935 If neither @env{@var{command}_BLOCK_SIZE}, nor @env{BLOCK_SIZE}, nor
936 @env{BLOCKSIZE} is set, but this variable is set, the block size
941 If none of the above environment variables are set, the block size
942 currently defaults to 1024 bytes in most contexts, but this number may
943 change in the future. For @command{ls} file sizes, the block size
946 @cindex human-readable output
949 A block size specification can be a positive integer specifying the number
950 of bytes per block, or it can be @code{human-readable} or @code{si} to
951 select a human-readable format. Integers may be followed by suffixes
952 that are upward compatible with the
953 @uref{http://www.bipm.org/en/publications/si-brochure/chapter3.html,
955 for decimal multiples and with the
956 @uref{https://physics.nist.gov/cuu/Units/binary.html, ISO/IEC 80000-13
957 (formerly IEC 60027-2) prefixes} for binary multiples.
959 With human-readable formats, output sizes are followed by a size letter
960 such as @samp{M} for megabytes. @code{BLOCK_SIZE=human-readable} uses
961 powers of 1024; @samp{M} stands for 1,048,576 bytes.
962 @code{BLOCK_SIZE=si} is similar, but uses powers of 1000 and appends
963 @samp{B}; @samp{MB} stands for 1,000,000 bytes.
966 A block size specification preceded by @samp{'} causes output sizes to
967 be displayed with thousands separators. The @env{LC_NUMERIC} locale
968 specifies the thousands separator and grouping. For example, in an
969 American English locale, @samp{--block-size="'1kB"} would cause a size
970 of 1234000 bytes to be displayed as @samp{1,234}. In the default C
971 locale, there is no thousands separator so a leading @samp{'} has no
974 An integer block size can be followed by a suffix to specify a
975 multiple of that size. A bare size letter,
976 or one followed by @samp{iB}, specifies
977 a multiple using powers of 1024. A size letter followed by @samp{B}
978 specifies powers of 1000 instead. For example, @samp{1M} and
979 @samp{1MiB} are equivalent to @samp{1048576}, whereas @samp{1MB} is
980 equivalent to @samp{1000000}.
982 A plain suffix without a preceding integer acts as if @samp{1} were
983 prepended, except that it causes a size indication to be appended to
984 the output. For example, @samp{--block-size="kB"} displays 3000 as
987 The following suffixes are defined. Large sizes like @code{1Q}
988 may be rejected by your computer due to limitations of its arithmetic.
992 @cindex kilobyte, definition of
993 kilobyte: @math{10^3 = 1000}.
997 @cindex kibibyte, definition of
998 kibibyte: @math{2^{10} = 1024}. @samp{K} is special: the SI prefix is
999 @samp{k} and the ISO/IEC 80000-13 prefix is @samp{Ki}, but tradition and
1000 POSIX use @samp{k} to mean @samp{KiB}.
1002 @cindex megabyte, definition of
1003 megabyte: @math{10^6 = 1,000,000}.
1006 @cindex mebibyte, definition of
1007 mebibyte: @math{2^{20} = 1,048,576}.
1009 @cindex gigabyte, definition of
1010 gigabyte: @math{10^9 = 1,000,000,000}.
1013 @cindex gibibyte, definition of
1014 gibibyte: @math{2^{30} = 1,073,741,824}.
1016 @cindex terabyte, definition of
1017 terabyte: @math{10^{12} = 1,000,000,000,000}.
1020 @cindex tebibyte, definition of
1021 tebibyte: @math{2^{40} = 1,099,511,627,776}.
1023 @cindex petabyte, definition of
1024 petabyte: @math{10^{15} = 1,000,000,000,000,000}.
1027 @cindex pebibyte, definition of
1028 pebibyte: @math{2^{50} = 1,125,899,906,842,624}.
1030 @cindex exabyte, definition of
1031 exabyte: @math{10^{18} = 1,000,000,000,000,000,000}.
1034 @cindex exbibyte, definition of
1035 exbibyte: @math{2^{60} = 1,152,921,504,606,846,976}.
1037 @cindex zettabyte, definition of
1038 zettabyte: @math{10^{21} = 1,000,000,000,000,000,000,000}
1041 zebibyte: @math{2^{70} = 1,180,591,620,717,411,303,424}.
1043 @cindex yottabyte, definition of
1044 yottabyte: @math{10^{24} = 1,000,000,000,000,000,000,000,000}.
1047 yobibyte: @math{2^{80} = 1,208,925,819,614,629,174,706,176}.
1049 @cindex ronnabyte, definition of
1050 ronnabyte: @math{10^{27} = 1,000,000,000,000,000,000,000,000,000}.
1053 robibyte: @math{2^{90} = 1,237,940,039,285,380,274,899,124,224}.
1055 @cindex quettabyte, definition of
1056 quettabyte: @math{10^{30} = 1,000,000,000,000,000,000,000,000,000,000}.
1059 quebibyte: @math{2^{100} = 1,267,650,600,228,229,401,496,703,205,376}.
1064 @opindex --block-size
1065 @opindex --human-readable
1068 Block size defaults can be overridden by an explicit
1069 @option{--block-size=@var{size}} option. The @option{-k}
1070 option is equivalent to @option{--block-size=1K}, which
1071 is the default unless the @env{POSIXLY_CORRECT} environment variable is
1072 set. The @option{-h} or @option{--human-readable} option is equivalent to
1073 @option{--block-size=human-readable}. The @option{--si} option is
1074 equivalent to @option{--block-size=si}. Note for @command{ls}
1075 the @option{-k} option does not control the display of the
1076 apparent file sizes, whereas the @option{--block-size} option does.
1078 @node Signal specifications
1079 @section Signal specifications
1080 @cindex signals, specifying
1082 A @var{signal} may be a signal name like @samp{HUP}, or a signal
1083 number like @samp{1}, or an exit status of a process terminated by the
1084 signal. A signal name can be given in canonical form or prefixed by
1085 @samp{SIG}@. The case of the letters is ignored. The following signal names
1086 and numbers are supported on all POSIX compliant systems:
1092 2. Terminal interrupt.
1098 9. Kill (cannot be caught or ignored).
1106 Other supported signal names have system-dependent corresponding
1107 numbers. All systems conforming to POSIX 1003.1-2001 also
1108 support the following signals:
1112 Access to an undefined portion of a memory object.
1114 Child process terminated, stopped, or continued.
1116 Continue executing, if stopped.
1118 Erroneous arithmetic operation.
1120 Illegal Instruction.
1122 Write on a pipe with no one to read it.
1124 Invalid memory reference.
1126 Stop executing (cannot be caught or ignored).
1130 Background process attempting read.
1132 Background process attempting write.
1134 High bandwidth data is available at a socket.
1136 User-defined signal 1.
1138 User-defined signal 2.
1142 POSIX 1003.1-2001 systems that support the XSI extension
1143 also support the following signals:
1149 Profiling timer expired.
1153 Trace/breakpoint trap.
1155 Virtual timer expired.
1157 CPU time limit exceeded.
1159 File size limit exceeded.
1163 POSIX 1003.1-2001 systems that support the XRT extension
1164 also support at least eight real-time signals called @samp{RTMIN},
1165 @samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}.
1167 @node Disambiguating names and IDs
1168 @section chown, chgrp, chroot, id: Disambiguating user names and IDs
1169 @cindex user names, disambiguating
1170 @cindex user IDs, disambiguating
1171 @cindex group names, disambiguating
1172 @cindex group IDs, disambiguating
1173 @cindex disambiguating group names and IDs
1175 Since the @var{user} and @var{group} arguments to these commands
1176 may be specified as names or numeric IDs, there is an
1178 What if a user or group @emph{name} is a string of digits?
1179 Should the command interpret it as a user name or as an ID@?
1180 (Using a number as a user name is common in some environments.)
1181 POSIX requires that these commands
1182 first attempt to resolve the specified string as a name, and
1183 only once that fails, then try to interpret it as an ID@.
1184 This is troublesome when you want to specify a numeric ID, say 42,
1185 and it must work even in a pathological situation where
1186 @samp{42} is a user name that maps to some other user ID, say 1000.
1187 Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to
1188 1000 -- not what you intended.
1190 GNU @command{chown}, @command{chgrp}, @command{chroot}, and @command{id}
1191 provide a way to work around this, that at the same time may result in a
1192 significant performance improvement by eliminating a database look-up.
1193 Simply precede each numeric user ID and/or group ID with a @samp{+},
1194 in order to force its interpretation as an integer:
1198 chgrp +$numeric_group_id another-file
1202 The name look-up process is skipped for each @samp{+}-prefixed string,
1203 because a string containing @samp{+} is never a valid user or group name.
1204 This syntax is accepted on most common Unix systems, but not on Solaris 10.
1206 @node Random sources
1207 @section Sources of random data
1209 @cindex random sources
1211 The @command{shuf}, @command{shred}, and @command{sort} commands
1212 sometimes need random data to do their work. For example, @samp{sort
1213 -R} must choose a hash function at random, and it needs random data to
1214 make this selection.
1216 By default these commands use an internal pseudo-random generator
1217 initialized by a small amount of entropy, but can be directed to use
1218 an external source with the @option{--random-source=@var{file}} option.
1219 An error is reported if @var{file} does not contain enough bytes.
1221 For example, the device file @file{/dev/urandom} could be used as the
1222 source of random data. Typically, this device gathers environmental
1223 noise from device drivers and other sources into an entropy pool, and
1224 uses the pool to generate random bits. If the pool is short of data,
1225 the device reuses the internal pool to produce more bits, using a
1226 cryptographically secure pseudo-random number generator. But be aware
1227 that this device is not designed for bulk random data generation
1228 and is relatively slow.
1230 @file{/dev/urandom} suffices for most practical uses, but applications
1231 requiring high-value or long-term protection of private data may
1232 require an alternate data source like @file{/dev/random} or
1233 @file{/dev/arandom}. The set of available sources depends on your
1236 To reproduce the results of an earlier invocation of a command, you
1237 can save some random data into a file and then use that file as the
1238 random source in earlier and later invocations of the command.
1240 Rather than depending on a file, one can generate a reproducible
1241 arbitrary amount of pseudo-random data given a seed value, using
1248 openssl enc -aes-256-ctr -pass pass:"$seed" -nosalt \
1249 </dev/zero 2>/dev/null
1252 shuf -i1-100 --random-source=<(get_seeded_random 42)
1255 @node Target directory
1256 @section Target directory
1258 @cindex target directory
1260 The @command{cp}, @command{install}, @command{ln}, and @command{mv}
1261 commands normally treat the last operand specially when it is a
1262 directory or a symbolic link to a directory. For example, @samp{cp
1263 source dest} is equivalent to @samp{cp source dest/source} if
1264 @file{dest} is a directory. Sometimes this behavior is not exactly
1265 what is wanted, so these commands support the following options to
1266 allow more fine-grained control:
1271 @itemx --no-target-directory
1272 @opindex --no-target-directory
1273 @cindex target directory
1274 @cindex destination directory
1275 Do not treat the last operand specially when it is a directory or a
1276 symbolic link to a directory. This can help avoid race conditions in
1277 programs that operate in a shared area. For example, when the command
1278 @samp{mv /tmp/source /tmp/dest} succeeds, there is no guarantee that
1279 @file{/tmp/source} was renamed to @file{/tmp/dest}: it could have been
1280 renamed to @file{/tmp/dest/source} instead, if some other process
1281 created @file{/tmp/dest} as a directory. However, if @file{mv
1282 -T /tmp/source /tmp/dest} succeeds, there is no
1283 question that @file{/tmp/source} was renamed to @file{/tmp/dest}.
1285 In the opposite situation, where you want the last operand to be
1286 treated as a directory and want a diagnostic otherwise, you can use
1287 the @option{--target-directory} (@option{-t}) option.
1289 @item -t @var{directory}
1290 @itemx --target-directory=@var{directory}
1291 @opindex --target-directory
1292 @cindex target directory
1293 @cindex destination directory
1294 Use @var{directory} as the directory component of each destination
1297 The interface for most programs is that after processing options and a
1298 finite (possibly zero) number of fixed-position arguments, the remaining
1299 argument list is either expected to be empty, or is a list of items
1300 (usually files) that will all be handled identically. The @command{xargs}
1301 program is designed to work well with this convention.
1303 The commands in the @command{mv}-family are unusual in that they take
1304 a variable number of arguments with a special case at the @emph{end}
1305 (namely, the target directory). This makes it nontrivial to perform some
1306 operations, e.g., ``move all files from here to ../d/'', because
1307 @code{mv * ../d/} might exhaust the argument space, and @code{ls | xargs ...}
1308 doesn't have a clean way to specify an extra final argument for each
1309 invocation of the subject command. (It can be done by going through a
1310 shell command, but that requires more human labor and brain power than
1313 The @option{--target-directory} (@option{-t}) option allows the @command{cp},
1314 @command{install}, @command{ln}, and @command{mv} programs to be used
1315 conveniently with @command{xargs}. For example, you can move the files
1316 from the current directory to a sibling directory, @code{d} like this:
1319 ls | xargs mv -t ../d --
1322 However, this doesn't move files whose names begin with @samp{.}.
1323 If you use the GNU @command{find} program, you can move those
1324 files too, with this command:
1327 find . -mindepth 1 -maxdepth 1 \
1331 But both of the above approaches fail if there are no files in the
1332 current directory, or if any file has a name containing a blank or
1333 some other special characters.
1334 The following example removes those limitations and requires both
1335 GNU @command{find} and GNU @command{xargs}:
1338 find . -mindepth 1 -maxdepth 1 -print0 \
1339 | xargs --null --no-run-if-empty \
1346 The @option{--target-directory} (@option{-t}) and
1347 @option{--no-target-directory} (@option{-T})
1348 options cannot be combined.
1350 @node Trailing slashes
1351 @section Trailing slashes
1353 @cindex trailing slashes
1355 Some GNU programs (at least @command{cp} and @command{mv}) allow you to
1356 remove any trailing slashes from each @var{source} argument before
1357 operating on it. The @option{--strip-trailing-slashes} option enables
1360 This is useful when a @var{source} argument may have a trailing slash and
1361 @c FIXME: mv's behavior in this case is system-dependent
1362 specify a symbolic link to a directory. This scenario is in fact rather
1363 common because some shells can automatically append a trailing slash when
1364 performing file name completion on such symbolic links. Without this
1365 option, @command{mv}, for example, (via the system's rename function) must
1366 interpret a trailing slash as a request to dereference the symbolic link
1367 and so must rename the indirectly referenced @emph{directory} and not
1368 the symbolic link. Although it may seem surprising that such behavior
1369 be the default, it is required by POSIX and is consistent with
1370 other parts of that standard.
1372 @node Traversing symlinks
1373 @section Traversing symlinks
1375 @cindex symbolic link to directory, controlling traversal of
1377 The following options modify how @command{chown} and @command{chgrp}
1378 @c FIXME: note that 'du' has these options, too, but they have slightly
1379 @c different meaning.
1380 traverse a hierarchy when the @option{--recursive} (@option{-R})
1381 option is also specified.
1382 If more than one of the following options is specified, only the final
1384 These options specify whether processing a symbolic link to a directory
1385 entails operating on just the symbolic link or on all files in the
1386 hierarchy rooted at that directory.
1388 These options are independent of @option{--dereference} and
1389 @option{--no-dereference} (@option{-h}), which control whether to modify
1390 a symlink or its referent.
1397 @cindex symbolic link to directory, traverse if on the command line
1398 If @option{--recursive} (@option{-R}) is specified and
1399 a command line argument is a symbolic link to a directory, traverse it.
1406 @cindex symbolic link to directory, traverse each that is encountered
1407 In a recursive traversal, traverse every symbolic link to a directory
1408 that is encountered.
1411 @c Append the following warning to -L where appropriate (e.g. chown).
1412 @macro warnOptDerefWithRec
1414 Combining this dereferencing option with the @option{--recursive} option
1415 may create a security risk:
1416 During the traversal of the directory tree, an attacker may be able to
1417 introduce a symlink to an arbitrary target; when the tool reaches that,
1418 the operation will be performed on the target of that symlink,
1419 possibly allowing the attacker to escalate privileges.
1428 @cindex symbolic link to directory, never traverse
1429 Do not traverse any symbolic links.
1430 This is the default if none of @option{-H}, @option{-L},
1431 or @option{-P} is specified.
1438 @node Treating / specially
1439 @section Treating @file{/} specially
1441 Certain commands can operate destructively on entire hierarchies.
1442 For example, if a user with appropriate privileges mistakenly runs
1443 @samp{rm -rf / tmp/junk}, that may remove
1444 all files on the entire system. Since there are so few
1445 legitimate uses for such a command,
1446 GNU @command{rm} normally declines to operate on any directory
1447 that resolves to @file{/}. If you really want to try to remove all
1448 the files on your system, you can use the @option{--no-preserve-root}
1449 option, but the default behavior, specified by the
1450 @option{--preserve-root} option, is safer for most purposes.
1452 The commands @command{chgrp}, @command{chmod} and @command{chown}
1453 can also operate destructively on entire hierarchies, so they too
1454 support these options. Although, unlike @command{rm}, they don't
1455 actually unlink files, these commands are arguably more dangerous
1456 when operating recursively on @file{/}, since they often work much
1457 more quickly, and hence damage more files before an alert user can
1458 interrupt them. Tradition and POSIX require these commands
1459 to operate recursively on @file{/}, so they default to
1460 @option{--no-preserve-root}, but using the @option{--preserve-root}
1461 option makes them safer for most purposes. For convenience you can
1462 specify @option{--preserve-root} in an alias or in a shell function.
1464 Note that the @option{--preserve-root} option also ensures
1465 that @command{chgrp} and @command{chown} do not modify @file{/}
1466 even when dereferencing a symlink pointing to @file{/}.
1468 @node Special built-in utilities
1469 @section Special built-in utilities
1471 Some programs like @command{nice} can invoke other programs; for
1472 example, the command @samp{nice cat file} invokes the program
1473 @command{cat} by executing the command @samp{cat file}. However,
1474 @dfn{special built-in utilities} like @command{exit} cannot be invoked
1475 this way. For example, the command @samp{nice exit} does not have a
1476 well-defined behavior: it may generate an error message instead of
1479 Here is a list of the special built-in utilities that are standardized
1480 by POSIX 1003.1-2004.
1483 @t{.@: : break continue eval exec exit export readonly
1484 return set shift times trap unset}
1487 For example, because @samp{.}, @samp{:}, and @samp{exec} are special,
1488 the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec
1489 pwd} do not work as you might expect.
1491 Many shells extend this list. For example, Bash has several extra
1492 special built-in utilities like @command{history}, and
1493 @command{suspend}, and with Bash the command @samp{nice suspend}
1494 generates an error message instead of suspending.
1498 @section Exit status
1501 An exit status of zero indicates success,
1502 and a nonzero value indicates failure.
1505 Nearly every command invocation yields an integral @dfn{exit status}
1506 that can be used to change how other commands work.
1507 For the vast majority of commands, an exit status of zero indicates
1508 success. Failure is indicated by a nonzero value -- typically
1509 @samp{1}, though it may differ on unusual platforms as POSIX
1510 requires only that it be nonzero.
1512 However, some of the programs documented here do produce
1513 other exit status values and a few associate different
1514 meanings with the values @samp{0} and @samp{1}.
1515 Here are the exceptions:
1516 @c You can generate the following list with:
1517 @c grep initialize_exit_failure src/*.c | cut -f1 -d: |
1518 @c sed -n 's|src/\(.*\)\.c|@command{\1},|p' | sort | fmt
1519 @command{chroot}, @command{env}, @command{expr}, @command{ls},
1520 @command{nice}, @command{nohup}, @command{numfmt}, @command{printenv},
1521 @command{runcon}, @command{sort}, @command{stdbuf}, @command{test},
1522 @command{timeout}, @command{tty}.
1524 @node Floating point
1525 @section Floating point numbers
1526 @cindex floating point
1527 @cindex IEEE floating point
1529 Commands that accept or produce floating point numbers employ the
1530 floating point representation of the underlying system, and suffer
1531 from rounding error, overflow, and similar floating-point issues.
1532 Almost all modern systems use IEEE-754 floating point, and it is
1533 typically portable to assume IEEE-754 behavior these days. IEEE-754
1534 has positive and negative infinity, distinguishes positive from
1535 negative zero, and uses special values called NaNs to represent
1536 invalid computations such as dividing zero by itself. For more
1537 information, please see David Goldberg's paper
1538 @uref{https://@/docs.oracle.com/@/cd/@/E19957-01/@/806-3568/@/ncg_goldberg.html,
1539 What Every Computer Scientist Should Know About Floating-Point Arithmetic}.
1541 Commands that accept floating point numbers as options, operands or
1542 input use the standard C functions @code{strtod} and @code{strtold} to
1543 convert from text to floating point numbers. These floating point
1544 numbers therefore can use scientific notation like @code{1.0e-34} and
1545 @code{-10e100}. Commands that parse floating point also understand
1546 case-insensitive @code{inf}, @code{infinity}, and @code{NaN}, although
1547 whether such values are useful depends on the command in question.
1548 Modern C implementations also accept hexadecimal floating point
1549 numbers such as @code{-0x.ep-3}, which stands for @minus{}14/16 times
1550 @math{2^-3}, which equals @minus{}0.109375. @xref{Parsing of
1551 Floats,,, libc, The GNU C Library Reference Manual}.
1554 Normally the @env{LC_NUMERIC} locale determines the decimal-point
1555 character. However, some commands' descriptions specify that they
1556 accept numbers in either the current or the C locale; for example,
1557 they treat @samp{3.14} like @samp{3,14} if the current locale uses
1558 comma as a decimal point.
1561 @node Standards conformance
1562 @section Standards conformance
1564 @vindex POSIXLY_CORRECT
1565 In a few cases, the GNU utilities' default behavior is
1566 incompatible with the POSIX standard. To suppress these
1567 incompatibilities, define the @env{POSIXLY_CORRECT} environment
1568 variable. Unless you are checking for POSIX conformance, you
1569 probably do not need to define @env{POSIXLY_CORRECT}.
1571 Newer versions of POSIX are occasionally incompatible with older
1572 versions. For example, older versions of POSIX required the
1573 command @samp{sort +1} to sort based on the second and succeeding
1574 fields in each input line, but in POSIX 1003.1-2001
1575 the same command is required to sort the file named @file{+1}, and you
1576 must instead use the command @samp{sort -k 2} to get the field-based
1577 sort. To complicate things further, POSIX 1003.1-2008 allows an
1578 implementation to have either the old or the new behavior.
1580 @vindex _POSIX2_VERSION
1581 The GNU utilities normally conform to the version of POSIX
1582 that is standard for your system. To cause them to conform to a
1583 different version of POSIX, define the @env{_POSIX2_VERSION}
1584 environment variable to a value of the form @var{yyyymm} specifying
1585 the year and month the standard was adopted. Three values are currently
1586 supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
1587 POSIX 1003.2-1992, @samp{200112} stands for POSIX
1588 1003.1-2001, and @samp{200809} stands for POSIX 1003.1-2008.
1589 For example, if you have a POSIX 1003.1-2001 system but are running software
1590 containing traditional usage like @samp{sort +1} or @samp{tail +10},
1591 you can work around the compatibility problems by setting
1592 @samp{_POSIX2_VERSION=200809} in your environment.
1594 @c This node is named "Multi-call invocation", not the usual
1595 @c "coreutils invocation", so that shell commands like
1596 @c 'info coreutils "touch invocation"' work as expected.
1597 @node Multi-call invocation
1598 @section @command{coreutils}: Multi-call program
1602 @cindex calling combined multi-call program
1604 The @command{coreutils} command invokes an individual utility, either
1605 implicitly selected by the last component of the name used to invoke
1606 @command{coreutils}, or explicitly with the
1607 @option{--coreutils-prog} option. Synopsis:
1610 coreutils @option{--coreutils-prog=PROGRAM} @dots{}
1613 The @command{coreutils} command is not installed by default, so
1614 portable scripts should not rely on its existence.
1616 @node Output of entire files
1617 @chapter Output of entire files
1619 @cindex output of entire files
1620 @cindex entire files, output of
1622 These commands read and write entire files, possibly transforming them
1626 * cat invocation:: Concatenate and write files.
1627 * tac invocation:: Concatenate and write files in reverse.
1628 * nl invocation:: Number lines and write files.
1629 * od invocation:: Write files in octal or other formats.
1630 * base32 invocation:: Transform data into printable data.
1631 * base64 invocation:: Transform data into printable data.
1632 * basenc invocation:: Transform data into printable data.
1635 @node cat invocation
1636 @section @command{cat}: Concatenate and write files
1639 @cindex concatenate and write files
1640 @cindex copying files
1642 @command{cat} copies each @var{file} (@samp{-} means standard input), or
1643 standard input if none are given, to standard output. Synopsis:
1646 cat [@var{option}] [@var{file}]@dots{}
1649 The program accepts the following options. Also see @ref{Common options}.
1657 Equivalent to @option{-vET}.
1660 @itemx --number-nonblank
1662 @opindex --number-nonblank
1663 Number all nonempty output lines, starting with 1.
1667 Equivalent to @option{-vE}.
1672 @opindex --show-ends
1673 Display a @samp{$} after the end of each line.
1674 The @code{\r\n} combination is shown as @samp{^M$}.
1680 Number all output lines, starting with 1. This option is ignored
1681 if @option{-b} is in effect.
1684 @itemx --squeeze-blank
1686 @opindex --squeeze-blank
1687 @cindex squeezing empty lines
1688 @cindex squeezing blank lines
1689 Suppress repeated adjacent blank lines; output just one empty line
1694 Equivalent to @option{-vT}.
1699 @opindex --show-tabs
1700 Display TAB characters as @samp{^I}.
1704 Ignored; for POSIX compatibility.
1707 @itemx --show-nonprinting
1709 @opindex --show-nonprinting
1710 Display control characters except for LFD and TAB using
1711 @samp{^} notation and precede characters that have the high bit set with
1716 On systems like MS-DOS that distinguish between text and binary files,
1717 @command{cat} normally reads and writes in binary mode. However,
1718 @command{cat} reads in text mode if one of the options
1719 @option{-bensAE} is used or if @command{cat} is reading from standard
1720 input and standard input is a terminal. Similarly, @command{cat}
1721 writes in text mode if one of the options @option{-bensAE} is used or
1722 if standard output is a terminal.
1729 # Output f's contents, then standard input, then g's contents.
1732 # Copy standard input to standard output.
1737 @node tac invocation
1738 @section @command{tac}: Concatenate and write files in reverse
1741 @cindex reversing files
1743 @command{tac} copies each @var{file} (@samp{-} means standard input), or
1744 standard input if none are given, to standard output, reversing the
1745 records (lines by default) in each separately. Synopsis:
1748 tac [@var{option}]@dots{} [@var{file}]@dots{}
1751 @dfn{Records} are separated by instances of a string (newline by
1752 default). By default, this separator string is attached to the end of
1753 the record that it follows in the file.
1755 The program accepts the following options. Also see @ref{Common options}.
1763 The separator is attached to the beginning of the record that it
1764 precedes in the file.
1770 Treat the separator string as a regular expression.
1772 @item -s @var{separator}
1773 @itemx --separator=@var{separator}
1775 @opindex --separator
1776 Use @var{separator} as the record separator, instead of newline.
1777 Note an empty @var{separator} is treated as a zero byte.
1778 I.e., input and output items are delimited with ASCII NUL.
1782 On systems like MS-DOS that distinguish between text and binary files,
1783 @command{tac} reads and writes in binary mode.
1790 # Reverse a file character by character.
1796 @section @command{nl}: Number lines and write files
1799 @cindex numbering lines
1800 @cindex line numbering
1802 @command{nl} writes each @var{file} (@samp{-} means standard input), or
1803 standard input if none are given, to standard output, with line numbers
1804 added to some or all of the lines. Synopsis:
1807 nl [@var{option}]@dots{} [@var{file}]@dots{}
1810 @cindex logical pages, numbering on
1811 @command{nl} decomposes its input into (logical) page sections;
1812 by default, the line number is reset to 1 at each logical page section.
1813 @command{nl} treats all of the input files as a single document;
1814 it does not reset line numbers or logical pages between files.
1816 @cindex headers, numbering
1817 @cindex body, numbering
1818 @cindex footers, numbering
1819 A logical page consists of three sections: header, body, and footer.
1820 Any of the sections can be empty. Each can be numbered in a different
1821 style from the others.
1823 The beginnings of the sections of logical pages are indicated in the
1824 input file by a line containing exactly one of these delimiter strings:
1835 The characters from which these strings are made can be changed from
1836 @samp{\} and @samp{:} via options (see below), but the pattern
1837 of each string cannot be changed.
1839 A section delimiter is replaced by an empty line on output. Any text
1840 that comes before the first section delimiter string in the input file
1841 is considered to be part of a body section, so @command{nl} treats a
1842 file that contains no section delimiters as a single body section.
1844 The program accepts the following options. Also see @ref{Common options}.
1848 @item -b @var{style}
1849 @itemx --body-numbering=@var{style}
1851 @opindex --body-numbering
1852 Select the numbering style for lines in the body section of each
1853 logical page. When a line is not numbered, the current line number
1854 is not incremented, but the line number separator character is still
1855 prepended to the line. The styles are:
1861 number only nonempty lines (default for body),
1863 do not number lines (default for header and footer),
1865 number only lines that contain a match for the basic regular
1866 expression @var{bre}.
1867 @xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}.
1871 @itemx --section-delimiter=@var{cd}
1873 @opindex --section-delimiter
1874 @cindex section delimiters of pages
1875 Set the section delimiter characters to @var{cd}; default is
1876 @samp{\:}. If only @var{c} is given, the second remains @samp{:}.
1877 As a GNU extension more than two characters can be specified,
1878 and also if @var{cd} is empty (@option{-d ''}), then section
1879 matching is disabled.
1880 (Remember to protect @samp{\} or other metacharacters from shell
1881 expansion with quotes or extra backslashes.)
1883 @item -f @var{style}
1884 @itemx --footer-numbering=@var{style}
1886 @opindex --footer-numbering
1887 Analogous to @option{--body-numbering}.
1889 @item -h @var{style}
1890 @itemx --header-numbering=@var{style}
1892 @opindex --header-numbering
1893 Analogous to @option{--body-numbering}.
1895 @item -i @var{number}
1896 @itemx --line-increment=@var{number}
1898 @opindex --line-increment
1899 Increment line numbers by @var{number} (default 1).
1900 @var{number} can be negative to decrement.
1902 @item -l @var{number}
1903 @itemx --join-blank-lines=@var{number}
1905 @opindex --join-blank-lines
1906 @cindex empty lines, numbering
1907 @cindex blank lines, numbering
1908 Consider @var{number} (default 1) consecutive empty lines to be one
1909 logical line for numbering, and only number the last one. Where fewer
1910 than @var{number} consecutive empty lines occur, do not number them.
1911 An empty line is one that contains no characters, not even spaces
1914 @item -n @var{format}
1915 @itemx --number-format=@var{format}
1917 @opindex --number-format
1918 Select the line numbering format (default is @code{rn}):
1922 @opindex ln @r{format for @command{nl}}
1923 left justified, no leading zeros;
1925 @opindex rn @r{format for @command{nl}}
1926 right justified, no leading zeros;
1928 @opindex rz @r{format for @command{nl}}
1929 right justified, leading zeros.
1933 @itemx --no-renumber
1935 @opindex --no-renumber
1936 Do not reset the line number at the start of a logical page.
1938 @item -s @var{string}
1939 @itemx --number-separator=@var{string}
1941 @opindex --number-separator
1942 Separate the line number from the text line in the output with
1943 @var{string} (default is the TAB character).
1945 @item -v @var{number}
1946 @itemx --starting-line-number=@var{number}
1948 @opindex --starting-line-number
1949 Set the initial line number on each logical page to @var{number} (default 1).
1950 The starting @var{number} can be negative.
1952 @item -w @var{number}
1953 @itemx --number-width=@var{number}
1955 @opindex --number-width
1956 Use @var{number} characters for line numbers (default 6).
1964 @section @command{od}: Write files in octal or other formats
1967 @cindex octal dump of files
1968 @cindex hex dump of files
1969 @cindex ASCII dump of files
1970 @cindex file contents, dumping unambiguously
1972 @command{od} writes an unambiguous representation of each @var{file}
1973 (@samp{-} means standard input), or standard input if none are given.
1977 od [@var{option}]@dots{} [@var{file}]@dots{}
1978 od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]]
1979 od [@var{option}]@dots{} --traditional [@var{file}]@c
1980 [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
1983 Each line of output consists of the offset in the input, followed by
1984 groups of data from the file. By default, @command{od} prints the offset in
1985 octal, and each group of file data is a C @code{short int}'s worth of input
1986 printed as a single octal number.
1988 If @var{offset} is given, it specifies how many input bytes to skip
1989 before formatting and writing. By default, it is interpreted as an
1990 octal number, but the optional trailing decimal point causes it to be
1991 interpreted as decimal. If no decimal is specified and the offset
1992 begins with @samp{0x} or @samp{0X} it is interpreted as a hexadecimal
1993 number. If there is a trailing @samp{b}, the number of bytes skipped
1994 will be @var{offset} multiplied by 512.
1996 If a command is of both the first and second forms, the second form is
1997 assumed if the last operand begins with @samp{+} or (if there are two
1998 operands) a digit. For example, in @samp{od foo 10} and @samp{od +10}
1999 the @samp{10} is an offset, whereas in @samp{od 10} the @samp{10} is a
2002 The program accepts the following options. Also see @ref{Common options}.
2006 @item -A @var{radix}
2007 @itemx --address-radix=@var{radix}
2009 @opindex --address-radix
2010 @cindex radix for file offsets
2011 @cindex file offset radix
2012 Select the base in which file offsets are printed. @var{radix} can
2013 be one of the following:
2023 none (do not print offsets).
2026 The default is octal.
2028 @item --endian=@var{order}
2030 @cindex byte-swapping
2032 Reorder input bytes, to handle inputs with differing byte orders,
2033 or to provide consistent output independent of the endian convention
2034 of the current system. Swapping is performed according to the
2035 specified @option{--type} size and endian @var{order}, which can be
2036 @samp{little} or @samp{big}.
2038 @item -j @var{bytes}
2039 @itemx --skip-bytes=@var{bytes}
2041 @opindex --skip-bytes
2042 Skip @var{bytes} input bytes before formatting and writing. If
2043 @var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in
2044 hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise,
2046 @multiplierSuffixes{bytes}
2048 @item -N @var{bytes}
2049 @itemx --read-bytes=@var{bytes}
2051 @opindex --read-bytes
2052 Output at most @var{bytes} bytes of the input. Prefixes and suffixes on
2053 @code{bytes} are interpreted as for the @option{-j} option.
2055 @item -S @var{bytes}
2056 @itemx --strings[=@var{bytes}]
2059 @cindex string constants, outputting
2060 Instead of the normal output, output only @dfn{string constants}: at
2061 least @var{bytes} consecutive ASCII graphic characters,
2062 followed by a zero byte (ASCII NUL).
2063 Prefixes and suffixes on @var{bytes} are interpreted as for the
2066 If @var{bytes} is omitted with @option{--strings}, the default is 3.
2069 @itemx --format=@var{type}
2072 Select the format in which to output the file data. @var{type} is a
2073 string of one or more of the below type indicator characters. If you
2074 include more than one type indicator character in a single @var{type}
2075 string, or use this option more than once, @command{od} writes one copy
2076 of each output line using each of the data types that you specified,
2077 in the order that you specified.
2079 Adding a trailing ``z'' to any type specification appends a display
2080 of the single byte character representation of the printable characters
2081 to the output line generated by the type specification.
2085 named character, ignoring high-order bit
2087 printable single byte character, C backslash escape
2088 or a 3 digit octal sequence
2092 floating point (@pxref{Floating point})
2101 The type @code{a} outputs things like @samp{sp} for space, @samp{nl} for
2102 newline, and @samp{nul} for a zero byte. Only the least significant
2103 seven bits of each byte is used; the high-order bit is ignored.
2104 Type @code{c} outputs
2105 @samp{ }, @samp{\n}, and @code{\0}, respectively.
2108 Except for types @samp{a} and @samp{c}, you can specify the number
2109 of bytes to use in interpreting each number in the given data type
2110 by following the type indicator character with a decimal integer.
2111 Alternately, you can specify the size of one of the C compiler's
2112 built-in data types by following the type indicator character with
2113 one of the following characters. For integers (@samp{d}, @samp{o},
2114 @samp{u}, @samp{x}):
2127 For floating point (@code{f}):
2139 @itemx --output-duplicates
2141 @opindex --output-duplicates
2142 Output consecutive lines that are identical. By default, when two or
2143 more consecutive output lines would be identical, @command{od} outputs only
2144 the first line, and puts just an asterisk on the following line to
2145 indicate the elision.
2148 @itemx --width[=@var{n}]
2151 Dump @code{n} input bytes per output line. This must be a multiple of
2152 the least common multiple of the sizes associated with the specified
2155 If this option is not given at all, the default is 16. If @var{n} is
2156 omitted, the default is 32.
2160 The next several options are shorthands for format specifications.
2161 GNU @command{od} accepts any combination of shorthands and format
2162 specification options. These options accumulate.
2168 Output as named characters. Equivalent to @samp{-t a}.
2172 Output as octal bytes. Equivalent to @samp{-t o1}.
2176 Output as printable single byte characters, C backslash escapes
2177 or 3 digit octal sequences. Equivalent to @samp{-t c}.
2181 Output as unsigned decimal two-byte units. Equivalent to @samp{-t u2}.
2185 Output as floats. Equivalent to @samp{-t fF}.
2189 Output as decimal ints. Equivalent to @samp{-t dI}.
2193 Output as decimal long ints. Equivalent to @samp{-t dL}.
2197 Output as octal two-byte units. Equivalent to @option{-t o2}.
2201 Output as decimal two-byte units. Equivalent to @option{-t d2}.
2205 Output as hexadecimal two-byte units. Equivalent to @samp{-t x2}.
2208 @opindex --traditional
2209 Recognize the non-option label argument that traditional @command{od}
2210 accepted. The following syntax:
2213 od --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
2217 can be used to specify at most one file and optional arguments
2218 specifying an offset and a pseudo-start address, @var{label}.
2219 The @var{label} argument is interpreted
2220 just like @var{offset}, but it specifies an initial pseudo-address. The
2221 pseudo-addresses are displayed in parentheses following any normal
2229 @node base32 invocation
2230 @section @command{base32}: Transform data into printable data
2233 @cindex base32 encoding
2235 @command{base32} transforms data read from a file, or standard input,
2236 into (or from) base32 encoded form. The base32 encoded form uses
2237 printable ASCII characters to represent binary data.
2238 The usage and options of this command are precisely the
2239 same as for @command{base64}. @xref{base64 invocation}.
2240 For more general encoding functionalty see @ref{basenc invocation}.
2243 @node base64 invocation
2244 @section @command{base64}: Transform data into printable data
2247 @cindex base64 encoding
2249 @command{base64} transforms data read from a file, or standard input,
2250 into (or from) base64 encoded form. The base64 encoded form uses
2251 printable ASCII characters to represent binary data.
2255 base64 [@var{option}]@dots{} [@var{file}]
2256 base64 --decode [@var{option}]@dots{} [@var{file}]
2259 The base64 encoding expands data to roughly 133% of the original.
2260 The base32 encoding expands data to roughly 160% of the original.
2261 The format conforms to
2262 @uref{https://tools.ietf.org/search/rfc4648, RFC 4648}.
2264 For more general encoding functionalty see @ref{basenc invocation}.
2266 The program accepts the following options. Also see @ref{Common options}.
2271 @itemx --wrap=@var{cols}
2275 @cindex column to wrap data after
2276 During encoding, wrap lines after @var{cols} characters. This must be
2279 The default is to wrap after 76 characters. Use the value 0 to
2280 disable line wrapping altogether.
2286 @cindex Decode base64 data
2287 @cindex Base64 decoding
2288 Change the mode of operation, from the default of encoding data, to
2289 decoding data. Input is expected to be base64 encoded data, and the
2290 output will be the original data.
2293 @itemx --ignore-garbage
2295 @opindex --ignore-garbage
2296 @cindex Ignore garbage in base64 stream
2297 When decoding, newlines are always accepted.
2298 During decoding, ignore unrecognized bytes,
2299 to permit distorted data to be decoded.
2305 @node basenc invocation
2306 @section @command{basenc}: Transform data into printable data
2309 @cindex base32 encoding
2311 @command{basenc} transforms data read from a file, or standard input,
2312 into (or from) various common encoding forms. The encoded form uses
2313 printable ASCII characters to represent binary data.
2318 basenc @var{encoding} [@var{option}]@dots{} [@var{file}]
2319 basenc @var{encoding} --decode [@var{option}]@dots{} [@var{file}]
2322 The @var{encoding} argument is required. If @var{file} is omitted,
2323 @command{basenc} reads from standard input.
2324 The @option{-w/--wrap},@option{-i/--ignore-garbage},
2325 @option{-d/--decode} options of this command are precisely the same as
2326 for @command{base64}. @xref{base64 invocation}.
2329 Supported @var{encoding}s are:
2335 Encode into (or decode from with @option{-d/--decode}) base64 form.
2336 The format conforms to
2337 @uref{https://tools.ietf.org/search/rfc4648#section-4, RFC 4648#4}.
2338 Equivalent to the @command{base64} command.
2341 @opindex --base64url
2342 Encode into (or decode from with @option{-d/--decode}) file-and-url-safe
2343 base64 form (using @samp{_} and @samp{-} instead of @samp{+} and @samp{/}).
2344 The format conforms to
2345 @uref{https://tools.ietf.org/search/rfc4648#section-5, RFC 4648#5}.
2349 Encode into (or decode from with @option{-d/--decode}) base32 form.
2350 The encoded data uses the @samp{ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=} characters.
2351 The format conforms to
2352 @uref{https://tools.ietf.org/search/rfc4648#section-6, RFC 4648#6}.
2353 Equivalent to the @command{base32} command.
2356 @opindex --base32hex
2357 Encode into (or decode from with @option{-d/--decode}) Extended Hex Alphabet
2358 base32 form. The encoded data uses the
2359 @samp{0123456789ABCDEFGHIJKLMNOPQRSTUV=} characters. The format conforms to
2360 @uref{https://tools.ietf.org/search/rfc4648#section-7, RFC 4648#7}.
2364 Encode into (or decode from with @option{-d/--decode}) base16 (hexadecimal)
2365 form. The encoded data uses the @samp{0123456789ABCDEF} characters. The format
2367 @uref{https://tools.ietf.org/search/rfc4648#section-8, RFC 4648#8}.
2370 @opindex --base2lsbf
2371 Encode into (or decode from with @option{-d/--decode}) binary string form
2372 (@samp{0} and @samp{1}) with the @emph{least} significant bit of every byte
2376 @opindex --base2msbf
2377 Encode into (or decode from with @option{-d/--decode}) binary string form
2378 (@samp{0} and @samp{1}) with the @emph{most} significant bit of every byte
2383 Encode into (or decode from with @option{-d/--decode}) Z85 form
2384 (a modified Ascii85 form). The encoded data uses the
2385 @samp{0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU@
2386 VWXYZ.-:+=^!/*?&<>()[]@{@}@@%$#}.
2387 characters. The format conforms to
2388 @uref{https://rfc.zeromq.org/spec:32/Z85/, ZeroMQ spec:32/Z85}.
2390 When encoding with @option{--z85}, input length must be a multiple of 4;
2391 when decoding with @option{--z85}, input length must be a multiple of 5.
2397 Encoding/decoding examples:
2400 $ printf '\376\117\202' | basenc --base64
2403 $ printf '\376\117\202' | basenc --base64url
2406 $ printf '\376\117\202' | basenc --base32
2409 $ printf '\376\117\202' | basenc --base32hex
2412 $ printf '\376\117\202' | basenc --base16
2415 $ printf '\376\117\202' | basenc --base2lsbf
2416 011111111111001001000001
2418 $ printf '\376\117\202' | basenc --base2msbf
2419 111111100100111110000010
2421 $ printf '\376\117\202\000' | basenc --z85
2424 $ printf 01010100 | basenc --base2msbf --decode
2427 $ printf 01010100 | basenc --base2lsbf --decode
2433 @node Formatting file contents
2434 @chapter Formatting file contents
2436 @cindex formatting file contents
2438 These commands reformat the contents of files.
2441 * fmt invocation:: Reformat paragraph text.
2442 * pr invocation:: Paginate or columnate files for printing.
2443 * fold invocation:: Wrap input lines to fit in specified width.
2447 @node fmt invocation
2448 @section @command{fmt}: Reformat paragraph text
2451 @cindex reformatting paragraph text
2452 @cindex paragraphs, reformatting
2453 @cindex text, reformatting
2455 @command{fmt} fills and joins lines to produce output lines of (at most)
2456 a given number of characters (75 by default). Synopsis:
2459 fmt [@var{option}]@dots{} [@var{file}]@dots{}
2462 @command{fmt} reads from the specified @var{file} arguments (or standard
2463 input if none are given), and writes to standard output.
2465 By default, blank lines, spaces between words, and indentation are
2466 preserved in the output; successive input lines with different
2467 indentation are not joined; tabs are expanded on input and introduced on
2470 @cindex line-breaking
2471 @cindex sentences and line-breaking
2472 @cindex Knuth, Donald E.
2473 @cindex Plass, Michael F.
2474 @command{fmt} prefers breaking lines at the end of a sentence, and tries to
2475 avoid line breaks after the first word of a sentence or before the last
2476 word of a sentence. A @dfn{sentence break} is defined as either the end
2477 of a paragraph or a word ending in any of @samp{.?!}, followed by two
2478 spaces or end of line, ignoring any intervening parentheses or quotes.
2479 Like @TeX{}, @command{fmt} reads entire ``paragraphs'' before choosing line
2480 breaks; the algorithm is a variant of that given by Donald E. Knuth
2481 and Michael F. Plass in ``Breaking Paragraphs Into Lines'',
2482 @cite{Software: Practice & Experience} @b{11}, 11 (November 1981),
2485 The program accepts the following options. Also see @ref{Common options}.
2490 @itemx --crown-margin
2492 @opindex --crown-margin
2493 @cindex crown margin
2494 @dfn{Crown margin} mode: preserve the indentation of the first two
2495 lines within a paragraph, and align the left margin of each subsequent
2496 line with that of the second line.
2499 @itemx --tagged-paragraph
2501 @opindex --tagged-paragraph
2502 @cindex tagged paragraphs
2503 @dfn{Tagged paragraph} mode: like crown margin mode, except that if
2504 indentation of the first line of a paragraph is the same as the
2505 indentation of the second, the first line is treated as a one-line
2511 @opindex --split-only
2512 Split lines only. Do not join short lines to form longer ones. This
2513 prevents sample lines of code, and other such ``formatted'' text from
2514 being unduly combined.
2517 @itemx --uniform-spacing
2519 @opindex --uniform-spacing
2520 Uniform spacing. Reduce spacing between words to one space, and spacing
2521 between sentences to two spaces.
2524 @itemx -w @var{width}
2525 @itemx --width=@var{width}
2526 @opindex -@var{width}
2529 Fill output lines up to @var{width} characters (default 75 or @var{goal}
2530 plus 10, if @var{goal} is provided).
2533 @itemx --goal=@var{goal}
2536 @command{fmt} initially tries to make lines @var{goal} characters wide.
2537 By default, this is 7% shorter than @var{width}.
2539 @item -p @var{prefix}
2540 @itemx --prefix=@var{prefix}
2541 Only lines beginning with @var{prefix} (possibly preceded by whitespace)
2542 are subject to formatting. The prefix and any preceding whitespace are
2543 stripped for the formatting and then re-attached to each formatted output
2544 line. One use is to format certain kinds of program comments, while
2545 leaving the code unchanged.
2552 @section @command{pr}: Paginate or columnate files for printing
2555 @cindex printing, preparing files for
2556 @cindex multicolumn output, generating
2557 @cindex merging files in parallel
2559 @command{pr} writes each @var{file} (@samp{-} means standard input), or
2560 standard input if none are given, to standard output, paginating and
2561 optionally outputting in multicolumn format; optionally merges all
2562 @var{file}s, printing all in parallel, one per column. Synopsis:
2565 pr [@var{option}]@dots{} [@var{file}]@dots{}
2569 By default, a 5-line header is printed at each page: two blank lines;
2570 a line with the date, the file name, and the page count; and two more
2571 blank lines. A footer of five blank lines is also printed.
2572 The default @var{page_length} is 66
2573 lines. The default number of text lines is therefore 56.
2574 The text line of the header takes the form
2575 @samp{@var{date} @var{string} @var{page}}, with spaces inserted around
2576 @var{string} so that the line takes up the full @var{page_width}. Here,
2577 @var{date} is the date (see the @option{-D} or @option{--date-format}
2578 option for details), @var{string} is the centered header string, and
2579 @var{page} identifies the page number. The @env{LC_MESSAGES} locale
2580 category affects the spelling of @var{page}; in the default C locale, it
2581 is @samp{Page @var{number}} where @var{number} is the decimal page
2584 Form feeds in the input cause page breaks in the output. Multiple form
2585 feeds produce empty pages.
2587 Columns are of equal width, separated by an optional string (default
2588 is @samp{space}). For multicolumn output, lines will always be truncated to
2589 @var{page_width} (default 72), unless you use the @option{-J} option.
2591 column output no line truncation occurs by default. Use @option{-W} option to
2592 truncate lines in that case.
2594 The program accepts the following options. Also see @ref{Common options}.
2598 @item +@var{first_page}[:@var{last_page}]
2599 @itemx --pages=@var{first_page}[:@var{last_page}]
2600 @c The two following @opindex lines evoke warnings because they contain ':'
2601 @c The 'info' spec does not permit that. If we use those lines, we end
2602 @c up with truncated index entries that don't work.
2603 @c @opindex +@var{first_page}[:@var{last_page}]
2604 @c @opindex --pages=@var{first_page}[:@var{last_page}]
2605 @opindex +@var{page_range}
2606 @opindex --pages=@var{page_range}
2607 Begin printing with page @var{first_page} and stop with @var{last_page}.
2608 Missing @samp{:@var{last_page}} implies end of file. While estimating
2609 the number of skipped pages each form feed in the input file results
2610 in a new page. Page counting with and without @samp{+@var{first_page}}
2611 is identical. By default, counting starts with the first page of input
2612 file (not first page printed). Line numbering may be altered by @option{-N}
2616 @itemx --columns=@var{column}
2617 @opindex -@var{column}
2619 @cindex down columns
2620 With each single @var{file}, produce @var{column} columns of output
2621 (default is 1) and print columns down, unless @option{-a} is used. The
2622 column width is automatically decreased as @var{column} increases; unless
2623 you use the @option{-W/-w} option to increase @var{page_width} as well.
2624 This option might well cause some lines to be truncated. The number of
2625 lines in the columns on each page are balanced. The options @option{-e}
2626 and @option{-i} are on for multiple text-column output. Together with
2627 @option{-J} option column alignment and line truncation is turned off.
2628 Lines of full length are joined in a free field format and @option{-S}
2629 option may set field separators. @option{-@var{column}} may not be used
2630 with @option{-m} option.
2636 @cindex across columns
2637 With each single @var{file}, print columns across rather than down. The
2638 @option{-@var{column}} option must be given with @var{column} greater than one.
2639 If a line is too long to fit in a column, it is truncated.
2642 @itemx --show-control-chars
2644 @opindex --show-control-chars
2645 Print control characters using hat notation (e.g., @samp{^G}); print
2646 other nonprinting characters in octal backslash notation. By default,
2647 nonprinting characters are not changed.
2650 @itemx --double-space
2652 @opindex --double-space
2653 @cindex double spacing
2654 Double space the output.
2656 @item -D @var{format}
2657 @itemx --date-format=@var{format}
2658 @cindex time formats
2659 @cindex formatting times
2660 Format header dates using @var{format}, using the same conventions as
2661 for the command @samp{date +@var{format}}. @xref{date invocation}.
2662 Except for directives, which start with
2663 @samp{%}, characters in @var{format} are printed unchanged. You can use
2664 this option to specify an arbitrary string in place of the header date,
2665 e.g., @option{--date-format="Monday morning"}.
2667 @vindex POSIXLY_CORRECT
2669 The default date format is @samp{%Y-%m-%d %H:%M} (for example,
2670 @samp{2020-07-09 23:59});
2671 but if the @env{POSIXLY_CORRECT} environment variable is set
2672 and the @env{LC_TIME} locale category specifies the POSIX
2673 locale, the default is @samp{%b %e %H:%M %Y} (for example,
2674 @samp{Jul@ @ 9 23:59 2020}.
2677 Timestamps are listed according to the time zone rules specified by
2678 the @env{TZ} environment variable, or by the system default rules if
2679 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
2680 with @env{TZ}, libc, The GNU C Library Reference Manual}.
2682 @item -e[@var{in-tabchar}[@var{in-tabwidth}]]
2683 @itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]]
2685 @opindex --expand-tabs
2687 Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is
2688 the input tab character (default is the TAB character). Second optional
2689 argument @var{in-tabwidth} is the input tab character's width (default
2697 @opindex --form-feed
2698 Use a form feed instead of newlines to separate output pages. This does
2699 not alter the default page length of 66 lines.
2701 @item -h @var{header}
2702 @itemx --header=@var{header}
2705 Replace the file name in the header with the centered string @var{header}.
2706 When using the shell, @var{header} should be quoted and should be
2707 separated from @option{-h} by a space.
2709 @item -i[@var{out-tabchar}[@var{out-tabwidth}]]
2710 @itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
2712 @opindex --output-tabs
2714 Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar}
2715 is the output tab character (default is the TAB character). Second optional
2716 argument @var{out-tabwidth} is the output tab character's width (default
2722 @opindex --join-lines
2723 Merge lines of full length. Used together with the column options
2724 @option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off
2725 @option{-W/-w} line truncation;
2726 no column alignment used; may be used with
2727 @option{--sep-string[=@var{string}]}. @option{-J} has been introduced
2728 (together with @option{-W} and @option{--sep-string})
2729 to disentangle the old (POSIX-compliant) options @option{-w} and
2730 @option{-s} along with the three column options.
2733 @item -l @var{page_length}
2734 @itemx --length=@var{page_length}
2737 Set the page length to @var{page_length} (default 66) lines, including
2738 the lines of the header [and the footer]. If @var{page_length} is less
2739 than or equal to 10, the header and footer are omitted, as if the
2740 @option{-t} option had been given.
2746 Merge and print all @var{file}s in parallel, one in each column. If a
2747 line is too long to fit in a column, it is truncated, unless the @option{-J}
2748 option is used. @option{--sep-string[=@var{string}]} may be used.
2750 some @var{file}s (form feeds set) produce empty columns, still marked
2751 by @var{string}. The result is a continuous line numbering and column
2752 marking throughout the whole merged file. Completely empty merged pages
2753 show no separators or line numbers. The default header becomes
2754 @samp{@var{date} @var{page}} with spaces inserted in the middle; this
2755 may be used with the @option{-h} or @option{--header} option to fill up
2756 the middle blank part.
2758 @item -n[@var{number-separator}[@var{digits}]]
2759 @itemx --number-lines[=@var{number-separator}[@var{digits}]]
2761 @opindex --number-lines
2762 Provide @var{digits} digit line numbering (default for @var{digits} is
2763 5). With multicolumn output the number occupies the first @var{digits}
2764 column positions of each text column or only each line of @option{-m}
2765 output. With single column output the number precedes each line just as
2766 @option{-m} does. Default counting of the line numbers starts with the
2767 first line of the input file (not the first line printed, compare the
2768 @option{--page} option and @option{-N} option).
2769 Optional argument @var{number-separator} is the character appended to
2770 the line number to separate it from the text followed. The default
2771 separator is the TAB character. In a strict sense a TAB is always
2772 printed with single column output only. The TAB width varies
2773 with the TAB position, e.g., with the left @var{margin} specified
2774 by @option{-o} option. With multicolumn output priority is given to
2775 @samp{equal width of output columns} (a POSIX specification).
2776 The TAB width is fixed to the value of the first column and does
2777 not change with different values of left @var{margin}. That means a
2778 fixed number of spaces is always printed in the place of the
2779 @var{number-separator} TAB@. The tabification depends upon the output
2782 @item -N @var{line_number}
2783 @itemx --first-line-number=@var{line_number}
2785 @opindex --first-line-number
2786 Start line counting with the number @var{line_number} at first line of
2787 first page printed (in most cases not the first line of the input file).
2789 @item -o @var{margin}
2790 @itemx --indent=@var{margin}
2793 @cindex indenting lines
2795 Indent each line with a margin @var{margin} spaces wide (default is zero).
2796 The total page width is the size of the margin plus the @var{page_width}
2797 set with the @option{-W/-w} option. A limited overflow may occur with
2798 numbered single column output (compare @option{-n} option).
2801 @itemx --no-file-warnings
2803 @opindex --no-file-warnings
2804 Do not print a warning message when an argument @var{file} cannot be
2805 opened. (The exit status will still be nonzero, however.)
2807 @item -s[@var{char}]
2808 @itemx --separator[=@var{char}]
2810 @opindex --separator
2811 Separate columns by a single character @var{char}. The default for
2812 @var{char} is the TAB character without @option{-w} and @samp{no
2813 character} with @option{-w}. Without @option{-s} the default separator
2814 @samp{space} is set. @option{-s[char]} turns off line truncation of all
2815 three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless
2816 @option{-w} is set. This is a POSIX-compliant formulation.
2819 @item -S[@var{string}]
2820 @itemx --sep-string[=@var{string}]
2822 @opindex --sep-string
2823 Use @var{string} to separate output columns. The @option{-S} option doesn't
2824 affect the @option{-W/-w} option, unlike the @option{-s} option which does. It
2825 does not affect line truncation or column alignment.
2826 Without @option{-S}, and with @option{-J}, @command{pr} uses the default output
2828 Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space}
2829 (same as @option{-S"@w{ }"}).
2830 If no @samp{@var{string}} argument is specified, @samp{""} is assumed.
2833 @itemx --omit-header
2835 @opindex --omit-header
2836 Do not print the usual header [and footer] on each page, and do not fill
2837 out the bottom of pages (with blank lines or a form feed). No page
2838 structure is produced, but form feeds set in the input files are retained.
2839 The predefined pagination is not changed. @option{-t} or @option{-T} may be
2840 useful together with other options; e.g.: @option{-t -e4}, expand TAB characters
2841 in the input file to 4 spaces but don't make any other changes. Use of
2842 @option{-t} overrides @option{-h}.
2845 @itemx --omit-pagination
2847 @opindex --omit-pagination
2848 Do not print header [and footer]. In addition eliminate all form feeds
2849 set in the input files.
2852 @itemx --show-nonprinting
2854 @opindex --show-nonprinting
2855 Print nonprinting characters in octal backslash notation.
2857 @item -w @var{page_width}
2858 @itemx --width=@var{page_width}
2861 Set page width to @var{page_width} characters for multiple text-column
2862 output only (default for @var{page_width} is 72). The specified
2863 @var{page_width} is rounded down so that columns have equal width.
2864 @option{-s[CHAR]} turns off the default page width and any line truncation
2865 and column alignment.
2866 Lines of full length are merged, regardless of the column options
2867 set. No @var{page_width} setting is possible with single column output.
2868 A POSIX-compliant formulation.
2870 @item -W @var{page_width}
2871 @itemx --page_width=@var{page_width}
2873 @opindex --page_width
2874 Set the page width to @var{page_width} characters, honored with and
2875 without a column option. With a column option, the specified @var{page_width}
2876 is rounded down so that columns have equal width. Text lines are truncated,
2877 unless @option{-J} is used. Together with one of the three column options
2878 (@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column
2879 alignment is always used. The separator options @option{-S} or @option{-s}
2880 don't disable the @option{-W} option. Default is 72 characters. Without
2881 @option{-W @var{page_width}} and without any of the column options NO line
2882 truncation is used (defined to keep downward compatibility and to meet
2883 most frequent tasks). That's equivalent to @option{-W 72 -J}@. The header
2884 line is never truncated.
2891 @node fold invocation
2892 @section @command{fold}: Wrap input lines to fit in specified width
2895 @cindex wrapping long input lines
2896 @cindex folding long input lines
2898 @command{fold} writes each @var{file} (@option{-} means standard input), or
2899 standard input if none are given, to standard output, breaking long
2903 fold [@var{option}]@dots{} [@var{file}]@dots{}
2906 By default, @command{fold} breaks lines wider than 80 columns. The output
2907 is split into as many lines as necessary.
2909 @cindex screen columns
2910 @command{fold} counts screen columns by default; thus, a tab may count more
2911 than one column, backspace decreases the column count, and carriage
2912 return sets the column to zero.
2914 The program accepts the following options. Also see @ref{Common options}.
2922 Count bytes rather than columns, so that tabs, backspaces, and carriage
2923 returns are each counted as taking up one column, just like other
2930 Break at word boundaries: the line is broken after the last blank before
2931 the maximum line length. If the line contains no such blanks, the line
2932 is broken at the maximum line length as usual.
2934 @item -w @var{width}
2935 @itemx --width=@var{width}
2938 Use a maximum line length of @var{width} columns instead of 80.
2940 For compatibility @command{fold} supports an obsolete option syntax
2941 @option{-@var{width}}. New scripts should use @option{-w @var{width}}
2949 @node Output of parts of files
2950 @chapter Output of parts of files
2952 @cindex output of parts of files
2953 @cindex parts of files, output of
2955 These commands output pieces of the input.
2958 * head invocation:: Output the first part of files.
2959 * tail invocation:: Output the last part of files.
2960 * split invocation:: Split a file into pieces.
2961 * csplit invocation:: Split a file into context-determined pieces.
2964 @node head invocation
2965 @section @command{head}: Output the first part of files
2968 @cindex initial part of files, outputting
2969 @cindex first part of files, outputting
2971 @command{head} prints the first part (10 lines by default) of each
2972 @var{file}; it reads from standard input if no files are given or
2973 when given a @var{file} of @option{-}. Synopsis:
2976 head [@var{option}]@dots{} [@var{file}]@dots{}
2979 If more than one @var{file} is specified, @command{head} prints a
2980 one-line header consisting of:
2983 ==> @var{file name} <==
2987 before the output for each @var{file}.
2989 The program accepts the following options. Also see @ref{Common options}.
2993 @item -c [-]@var{num}
2994 @itemx --bytes=[-]@var{num}
2997 Print the first @var{num} bytes, instead of initial lines.
2998 However, if @var{num} is prefixed with a @samp{-},
2999 print all but the last @var{num} bytes of each file.
3000 @multiplierSuffixes{num}
3002 @item -n [-]@var{num}
3003 @itemx --lines=[-]@var{num}
3006 Output the first @var{num} lines.
3007 However, if @var{num} is prefixed with a @samp{-},
3008 print all but the last @var{num} lines of each file.
3009 Size multiplier suffixes are the same as with the @option{-c} option.
3017 Never print file name headers.
3023 Always print file name headers.
3029 For compatibility @command{head} also supports an obsolete option syntax
3030 @option{-[@var{num}][bkm][cqv]}, which is recognized only if it is
3031 specified first. @var{num} is a decimal number optionally followed
3032 by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or
3033 @samp{l} to mean count by lines, or other option letters (@samp{cqv}).
3034 Scripts intended for standard hosts should use @option{-c @var{num}}
3035 or @option{-n @var{num}} instead. If your script must also run on
3036 hosts that support only the obsolete syntax, it is usually simpler to
3037 avoid @command{head}, e.g., by using @samp{sed 5q} instead of
3043 @node tail invocation
3044 @section @command{tail}: Output the last part of files
3047 @cindex last part of files, outputting
3049 @command{tail} prints the last part (10 lines by default) of each
3050 @var{file}; it reads from standard input if no files are given or
3051 when given a @var{file} of @samp{-}. Synopsis:
3054 tail [@var{option}]@dots{} [@var{file}]@dots{}
3057 If more than one @var{file} is specified, @command{tail} prints a
3058 one-line header before the output for each @var{file}, consisting of:
3061 ==> @var{file name} <==
3064 For further processing of tail output, it can be useful to convert the
3065 file headers to line prefixes, which can be done like:
3070 /^==> .* <==$/ @{prefix=substr($0,5,length-8)":"; next@}
3075 @cindex BSD @command{tail}
3076 GNU @command{tail} can output any amount of data (some other versions of
3077 @command{tail} cannot). It also has no @option{-r} option (print in
3078 reverse), since reversing a file is really a different job from printing
3079 the end of a file; BSD @command{tail} (which is the one with @option{-r}) can
3080 only reverse files that are at most as large as its buffer, which is
3081 typically 32 KiB@. A more reliable and versatile way to reverse files is
3082 the GNU @command{tac} command.
3084 The program accepts the following options. Also see @ref{Common options}.
3088 @item -c [+]@var{num}
3089 @itemx --bytes=[+]@var{num}
3092 Output the last @var{num} bytes, instead of final lines.
3093 However, if @var{num} is prefixed with a @samp{+}, start printing with
3094 byte @var{num} from the start of each file, instead of from the end.
3095 @multiplierSuffixes{num}
3098 @itemx --follow[=@var{how}]
3101 @cindex growing files
3102 @vindex name @r{follow option}
3103 @vindex descriptor @r{follow option}
3104 Loop forever trying to read more characters at the end of the file,
3105 presumably because the file is growing.
3106 If more than one file is given, @command{tail} prints a header whenever it
3107 gets output from a different file, to indicate which file that output is
3110 There are two ways to specify how you'd like to track files with this option,
3111 but that difference is noticeable only when a followed file is removed or
3113 If you'd like to continue to track the end of a growing file even after
3114 it has been unlinked, use @option{--follow=descriptor}. This is the default
3115 behavior, but it is not useful if you're tracking a log file that may be
3116 rotated (removed or renamed, then reopened). In that case, use
3117 @option{--follow=name} to track the named file, perhaps by reopening it
3118 periodically to see if it has been removed and recreated by some other program.
3119 Note that the inotify-based implementation handles this case without
3120 the need for any periodic reopening.
3122 No matter which method you use, if the tracked file is determined to have
3123 shrunk, @command{tail} prints a message saying the file has been truncated
3124 and resumes tracking from the start of the file, assuming it has been
3125 truncated to 0, which is the usual truncation operation for log files.
3127 When a file is removed, @command{tail}'s behavior depends on whether it is
3128 following the name or the descriptor. When following by name, tail can
3129 detect that a file has been removed and gives a message to that effect,
3130 and if @option{--retry} has been specified it will continue checking
3131 periodically to see if the file reappears.
3132 When following a descriptor, tail does not detect that the file has
3133 been unlinked or renamed and issues no message; even though the file
3134 may no longer be accessible via its original name, it may still be
3137 The option values @samp{descriptor} and @samp{name} may be specified only
3138 with the long form of the option, not with @option{-f}.
3140 The @option{-f} option is ignored if
3141 no @var{file} operand is specified and standard input is a FIFO or a pipe.
3142 Likewise, the @option{-f} option has no effect for any
3143 operand specified as @samp{-}, when standard input is a FIFO or a pipe.
3145 With kernel inotify support, output is triggered by file changes
3146 and is generally very prompt.
3147 Otherwise, @command{tail} sleeps for one second between checks --
3148 use @option{--sleep-interval=@var{n}} to change that default -- which can
3149 make the output appear slightly less responsive or bursty.
3150 When using tail without inotify support, you can make it more responsive
3151 by using a sub-second sleep interval, e.g., via an alias like this:
3154 alias tail='tail -s.1'
3159 This option is the same as @option{--follow=name --retry}. That is, tail
3160 will attempt to reopen a file when it is removed. Should this fail, tail
3161 will keep trying until it becomes accessible again.
3163 @item --max-unchanged-stats=@var{n}
3164 @opindex --max-unchanged-stats
3165 When tailing a file by name, if there have been @var{n} (default
3166 n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive
3167 iterations for which the file has not changed, then
3168 @code{open}/@code{fstat} the file to determine if that file name is
3169 still associated with the same device/inode-number pair as before.
3170 When following a log file that is rotated, this is approximately the
3171 number of seconds between when tail prints the last pre-rotation lines
3172 and when it prints the lines that have accumulated in the new log file.
3173 This option is meaningful only when polling (i.e., without inotify)
3174 and when following by name.
3176 @item -n [+]@var{num}
3177 @itemx --lines=[+]@var{}
3180 Output the last @var{num} lines.
3181 However, if @var{num} is prefixed with a @samp{+}, start printing with
3182 line @var{num} from the start of each file, instead of from the end.
3183 Size multiplier suffixes are the same as with the @option{-c} option.
3185 @item --pid=@var{pid}
3187 When following by name or by descriptor, you may specify the process ID,
3188 @var{pid}, of the sole writer of all @var{file} arguments. Then, shortly
3189 after that process terminates, tail will also terminate. This will
3190 work properly only if the writer and the tailing process are running on
3191 the same machine. For example, to save the output of a build in a file
3192 and to watch the file grow, if you invoke @command{make} and @command{tail}
3193 like this then the tail process will stop when your build completes.
3194 Without this option, you would have had to kill the @code{tail -f}
3198 $ make >& makerr & tail --pid=$! -f makerr
3201 If you specify a @var{pid} that is not in use or that does not correspond
3202 to the process that is writing to the tailed files, then @command{tail}
3203 may terminate long before any @var{file}s stop growing or it may not
3204 terminate until long after the real writer has terminated.
3205 Note that @option{--pid} cannot be supported on some systems; @command{tail}
3206 will print a warning if this is the case.
3214 Never print file name headers.
3218 Indefinitely try to open the specified file.
3219 This option is useful mainly when following (and otherwise issues a warning).
3221 When following by file descriptor (i.e., with @option{--follow=descriptor}),
3222 this option only affects the initial open of the file, as after a successful
3223 open, @command{tail} will start following the file descriptor.
3225 When following by name (i.e., with @option{--follow=name}), @command{tail}
3226 infinitely retries to re-open the given files until killed.
3228 Without this option, when @command{tail} encounters a file that doesn't
3229 exist or is otherwise inaccessible, it reports that fact and
3230 never checks it again.
3232 @item -s @var{number}
3233 @itemx --sleep-interval=@var{number}
3235 @opindex --sleep-interval
3236 Change the number of seconds to wait between iterations (the default is 1.0).
3237 During one iteration, every specified file is checked to see if it has
3239 When @command{tail} uses inotify, this polling-related option
3240 is usually ignored. However, if you also specify @option{--pid=@var{p}},
3241 @command{tail} checks whether process @var{p} is alive at least
3242 every @var{number} seconds.
3243 The @var{number} must be non-negative and can be a floating-point number
3244 in either the current or the C locale. @xref{Floating point}.
3250 Always print file name headers.
3256 For compatibility @command{tail} also supports an obsolete usage
3257 @samp{tail -[@var{num}][bcl][f] [@var{file}]}, which is recognized
3258 only if it does not conflict with the usage described
3259 above. This obsolete form uses exactly one option and at most one
3260 file. In the option, @var{num} is an optional decimal number optionally
3261 followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count
3262 by 512-byte blocks, bytes, or lines, optionally followed by @samp{f}
3263 which has the same meaning as @option{-f}.
3265 @vindex _POSIX2_VERSION
3266 On systems not conforming to POSIX 1003.1-2001, the leading @samp{-}
3267 can be replaced by @samp{+} in the traditional option syntax with the
3268 same meaning as in counts, and on obsolete systems predating POSIX
3269 1003.1-2001 traditional usage overrides normal usage when the two
3270 conflict. This behavior can be controlled with the
3271 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
3274 Scripts intended for use on standard hosts should avoid traditional
3275 syntax and should use @option{-c @var{num}[b]}, @option{-n
3276 @var{num}}, and/or @option{-f} instead. If your script must also
3277 run on hosts that support only the traditional syntax, you can often
3278 rewrite it to avoid problematic usages, e.g., by using @samp{sed -n
3279 '$p'} rather than @samp{tail -1}. If that's not possible, the script
3280 can use a test like @samp{if tail -c +1 </dev/null >/dev/null 2>&1;
3281 then @dots{}} to decide which syntax to use.
3283 Even if your script assumes the standard behavior, you should still
3284 beware usages whose behaviors differ depending on the POSIX
3285 version. For example, avoid @samp{tail - main.c}, since it might be
3286 interpreted as either @samp{tail main.c} or as @samp{tail -- -
3287 main.c}; avoid @samp{tail -c 4}, since it might mean either @samp{tail
3288 -c4} or @samp{tail -c 10 4}; and avoid @samp{tail +4}, since it might
3289 mean either @samp{tail ./+4} or @samp{tail -n +4}.
3294 @node split invocation
3295 @section @command{split}: Split a file into pieces.
3298 @cindex splitting a file into pieces
3299 @cindex pieces, splitting a file into
3301 @command{split} creates output files containing consecutive or interleaved
3302 sections of @var{input} (standard input if none is given or @var{input}
3303 is @samp{-}). Synopsis:
3306 split [@var{option}] [@var{input} [@var{prefix}]]
3309 By default, @command{split} puts 1000 lines of @var{input} (or whatever is
3310 left over for the last section), into each output file.
3312 @cindex output file name prefix
3313 The output files' names consist of @var{prefix} (@samp{x} by default)
3314 followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by
3315 default), such that concatenating the output files in traditional
3316 sorted order by file name produces the original input file (except
3317 @option{-nr/@var{n}}). By default split will initially create files
3318 with two generated suffix characters, and will increase this width by two
3319 when the next most significant position reaches the last character.
3320 (@samp{yz}, @samp{zaaa}, @samp{zaab}, @dots{}). In this way an arbitrary
3321 number of output files are supported, which sort as described above,
3322 even in the presence of an @option{--additional-suffix} option.
3323 If the @option{-a} option is specified and the output file names are
3324 exhausted, @command{split} reports an error without deleting the
3325 output files that it did create.
3327 The program accepts the following options. Also see @ref{Common options}.
3331 @item -l @var{lines}
3332 @itemx --lines=@var{lines}
3335 Put @var{lines} lines of @var{input} into each output file.
3336 If @option{--separator} is specified, then @var{lines} determines
3337 the number of records.
3339 For compatibility @command{split} also supports an obsolete
3340 option syntax @option{-@var{lines}}. New scripts should use
3341 @option{-l @var{lines}} instead.
3344 @itemx --bytes=@var{size}
3347 Put @var{size} bytes of @var{input} into each output file.
3348 @multiplierSuffixes{size}
3351 @itemx --line-bytes=@var{size}
3353 @opindex --line-bytes
3354 Put into each output file as many complete lines of @var{input} as
3355 possible without exceeding @var{size} bytes. Individual lines or records
3356 longer than @var{size} bytes are broken into multiple files.
3357 @var{size} has the same format as for the @option{--bytes} option.
3358 If @option{--separator} is specified, then @var{lines} determines
3359 the number of records.
3361 @item --filter=@var{command}
3363 With this option, rather than simply writing to each output file,
3364 write through a pipe to the specified shell @var{command} for each output file.
3365 @var{command} should use the $FILE environment variable, which is set
3366 to a different output file name for each invocation of the command.
3367 For example, imagine that you have a 1TiB compressed file
3368 that, if uncompressed, would be too large to reside on secondary storage,
3369 yet you must split it into individually-compressed pieces
3370 of a more manageable size.
3371 To do that, you might run this command:
3374 xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big-
3377 Assuming a 10:1 compression ratio, that would create about fifty 20GiB files
3378 with names @file{big-aa.xz}, @file{big-ab.xz}, @file{big-ac.xz}, etc.
3380 @item -n @var{chunks}
3381 @itemx --number=@var{chunks}
3385 Split @var{input} to @var{chunks} output files where @var{chunks} may be:
3388 @var{n} generate @var{n} files based on current size of @var{input}
3389 @var{k}/@var{n} output only @var{k}th of @var{n} to standard output
3390 l/@var{n} generate @var{n} files without splitting lines or records
3391 l/@var{k}/@var{n} likewise but output only @var{k}th of @var{n} to stdout
3392 r/@var{n} like @samp{l} but use round robin distribution
3393 r/@var{k}/@var{n} likewise but output only @var{k}th of @var{n} to stdout
3396 Any excess bytes remaining after dividing the @var{input}
3397 into @var{n} chunks, are assigned to the last chunk.
3398 Any excess bytes appearing after the initial calculation are discarded
3399 (except when using @samp{r} mode).
3401 All @var{n} files are created even if there are fewer than @var{n} lines,
3402 or the @var{input} is truncated.
3404 For @samp{l} mode, chunks are approximately @var{input} size / @var{n}.
3405 The @var{input} is partitioned into @var{n} equal sized portions, with
3406 the last assigned any excess. If a line @emph{starts} within a partition
3407 it is written completely to the corresponding file. Since lines or records
3408 are not split even if they overlap a partition, the files written
3409 can be larger or smaller than the partition size, and even empty
3410 if a line/record is so long as to completely overlap the partition.
3412 For @samp{r} mode, the size of @var{input} is irrelevant,
3413 and so can be a pipe for example.
3415 @item -a @var{length}
3416 @itemx --suffix-length=@var{length}
3418 @opindex --suffix-length
3419 Use suffixes of length @var{length}. If a @var{length} of 0 is specified,
3420 this is the same as if (any previous) @option{-a} was not specified, and
3421 thus enables the default behavior, which starts the suffix length at 2,
3422 and unless @option{-n} or @option{--numeric-suffixes=@var{from}} is
3423 specified, will auto increase the length by 2 as required.
3426 @itemx --numeric-suffixes[=@var{from}]
3428 @opindex --numeric-suffixes
3429 Use digits in suffixes rather than lower-case letters. The numerical
3430 suffix counts from @var{from} if specified, 0 otherwise.
3432 @var{from} is supported with the long form option, and is used to either set the
3433 initial suffix for a single run, or to set the suffix offset for independently
3434 split inputs, and consequently the auto suffix length expansion described above
3435 is disabled. Therefore you may also want to use option @option{-a} to allow
3436 suffixes beyond @samp{99}. Note if option @option{--number} is specified and
3437 the number of files is less than @var{from}, a single run is assumed and the
3438 minimum suffix length required is automatically determined.
3441 @itemx --hex-suffixes[=@var{from}]
3443 @opindex --hex-suffixes
3444 Like @option{--numeric-suffixes}, but use hexadecimal numbers (in lower case).
3446 @item --additional-suffix=@var{suffix}
3447 @opindex --additional-suffix
3448 Append an additional @var{suffix} to output file names. @var{suffix}
3449 must not contain slash.
3452 @itemx --elide-empty-files
3454 @opindex --elide-empty-files
3455 Suppress the generation of zero-length output files. This can happen
3456 with the @option{--number} option if a file is (truncated to be) shorter
3457 than the number requested, or if a line is so long as to completely
3458 span a chunk. The output file sequence numbers, always run consecutively
3459 even when this option is specified.
3461 @item -t @var{separator}
3462 @itemx --separator=@var{separator}
3464 @opindex --separator
3465 @cindex line separator character
3466 @cindex record separator character
3467 Use character @var{separator} as the record separator instead of the default
3468 newline character (ASCII LF).
3469 To specify ASCII NUL as the separator, use the two-character string @samp{\0},
3470 e.g., @samp{split -t '\0'}.
3475 @opindex --unbuffered
3476 Immediately copy input to output in @option{--number r/@dots{}} mode,
3477 which is a much slower mode of operation.
3481 Write a diagnostic just before each output file is opened.
3487 Here are a few examples to illustrate how the
3488 @option{--number} (@option{-n}) option works:
3490 Notice how, by default, one line may be split onto two or more:
3493 $ seq -w 6 10 > k; split -n3 k; head xa?
3506 Use the "l/" modifier to suppress that:
3509 $ seq -w 6 10 > k; split -nl/3 k; head xa?
3522 Use the "r/" modifier to distribute lines in a round-robin fashion:
3525 $ seq -w 6 10 > k; split -nr/3 k; head xa?
3538 You can also extract just the Kth chunk.
3539 This extracts and prints just the 7th "chunk" of 33:
3542 $ seq 100 > k; split -nl/7/33 k
3549 @node csplit invocation
3550 @section @command{csplit}: Split a file into context-determined pieces
3553 @cindex context splitting
3554 @cindex splitting a file into pieces by context
3556 @command{csplit} creates zero or more output files containing sections of
3557 @var{input} (standard input if @var{input} is @samp{-}). Synopsis:
3560 csplit [@var{option}]@dots{} @var{input} @var{pattern}@dots{}
3563 The contents of the output files are determined by the @var{pattern}
3564 arguments, as detailed below. An error occurs if a @var{pattern}
3565 argument refers to a nonexistent line of the input file (e.g., if no
3566 remaining line matches a given regular expression). After every
3567 @var{pattern} has been matched, any remaining input is copied into one
3570 By default, @command{csplit} prints the number of bytes written to each
3571 output file after it has been created.
3573 The types of pattern arguments are:
3578 Create an output file containing the input up to but not including line
3579 @var{n} (a positive integer). If followed by a repeat count, also
3580 create an output file containing the next @var{n} lines of the input
3581 file once for each repeat.
3583 @item /@var{regexp}/[@var{offset}]
3584 Create an output file containing the current line up to (but not
3585 including) the next line of the input file that contains a match for
3586 @var{regexp}. The optional @var{offset} is an integer, that can
3587 be preceded by @samp{+} or @samp{-}.
3588 If it is given, the input up to (but not including) the
3589 matching line plus or minus @var{offset} is put into the output file,
3590 and the line after that begins the next section of input.
3591 Note lines within a negative offset of a regexp pattern
3592 are not matched in subsequent regexp patterns.
3594 @item %@var{regexp}%[@var{offset}]
3595 Like the previous type, except that it does not create an output
3596 file, so that section of the input file is effectively ignored.
3598 @item @{@var{repeat-count}@}
3599 Repeat the previous pattern @var{repeat-count} additional
3600 times. The @var{repeat-count} can either be a positive integer or an
3601 asterisk, meaning repeat as many times as necessary until the input is
3606 The output files' names consist of a prefix (@samp{xx} by default)
3607 followed by a suffix. By default, the suffix is an ascending sequence
3608 of two-digit decimal numbers from @samp{00} to @samp{99}. In any case,
3609 concatenating the output files in sorted order by file name produces the
3610 original input file, excluding portions skipped with a %@var{regexp}%
3611 pattern or the @option{--suppress-matched} option.
3613 By default, if @command{csplit} encounters an error or receives a hangup,
3614 interrupt, quit, or terminate signal, it removes any output files
3615 that it has created so far before it exits.
3617 The program accepts the following options. Also see @ref{Common options}.
3621 @item -f @var{prefix}
3622 @itemx --prefix=@var{prefix}
3625 @cindex output file name prefix
3626 Use @var{prefix} as the output file name prefix.
3628 @item -b @var{format}
3629 @itemx --suffix-format=@var{format}
3631 @opindex --suffix-format
3632 @cindex output file name suffix
3633 Use @var{format} as the output file name suffix. When this option is
3634 specified, the suffix string must include exactly one
3635 @code{printf(3)}-style conversion specification, possibly including
3636 format specification flags, a field width, a precision specification,
3637 or all of these kinds of modifiers. The format letter must convert a
3638 binary unsigned integer argument to readable form. The format letters
3639 @samp{d} and @samp{i} are aliases for @samp{u}, and the
3640 @samp{u}, @samp{o}, @samp{x}, and @samp{X} conversions are allowed. The
3641 entire @var{format} is given (with the current output file number) to
3642 @code{sprintf(3)} to form the file name suffixes for each of the
3643 individual output files in turn. If this option is used, the
3644 @option{--digits} option is ignored.
3646 @item -n @var{digits}
3647 @itemx --digits=@var{digits}
3650 Use output file names containing numbers that are @var{digits} digits
3651 long instead of the default 2.
3656 @opindex --keep-files
3657 Do not remove output files when errors are encountered.
3659 @item --suppress-matched
3660 @opindex --suppress-matched
3661 Do not output lines matching the specified @var{pattern}.
3662 I.e., suppress the boundary line from the start of the second
3663 and subsequent splits.
3666 @itemx --elide-empty-files
3668 @opindex --elide-empty-files
3669 Suppress the generation of zero-length output files. (In cases where
3670 the section delimiters of the input file are supposed to mark the first
3671 lines of each of the sections, the first output file will generally be a
3672 zero-length file unless you use this option.) The output file sequence
3673 numbers always run consecutively starting from 0, even when this option
3684 Do not print counts of output file sizes.
3690 Here is an example of its usage.
3691 First, create an empty directory for the exercise,
3698 Now, split the sequence of 1..14 on lines that end with 0 or 5:
3701 $ seq 14 | csplit - '/[05]$/' '@{*@}'
3707 Each number printed above is the size of an output
3708 file that csplit has just created.
3709 List the names of those output files:
3716 Use @command{head} to show their contents:
3741 Example of splitting input by empty lines:
3744 $ csplit --suppress-matched @var{input.txt} '/^$/' '@{*@}'
3748 @c TODO: "uniq" already supports "--group".
3749 @c when it gets the "--key" option, uncomment this example.
3751 @c Example of splitting input file, based on the value of column 2:
3754 @c $ cat @var{input.txt} |
3756 @c uniq --group -k2,2 |
3757 @c csplit -m '/^$/' '@{*@}'
3760 @node Summarizing files
3761 @chapter Summarizing files
3763 @cindex summarizing files
3765 These commands generate just a few numbers representing entire
3769 * wc invocation:: Print newline, word, and byte counts.
3770 * sum invocation:: Print checksum and block counts.
3771 * cksum invocation:: Print CRC checksum and byte counts.
3772 * b2sum invocation:: Print or check BLAKE2 digests.
3773 * md5sum invocation:: Print or check MD5 digests.
3774 * sha1sum invocation:: Print or check SHA-1 digests.
3775 * sha2 utilities:: Print or check SHA-2 digests.
3780 @section @command{wc}: Print newline, word, and byte counts
3784 @cindex character count
3788 @command{wc} counts the number of bytes, characters, words, and newlines
3789 in each given @var{file}, or standard input if none are given
3790 or for a @var{file} of @samp{-}. A word is a nonzero length
3791 sequence of printable characters delimited by white space. Synopsis:
3794 wc [@var{option}]@dots{} [@var{file}]@dots{}
3797 @cindex total counts
3798 @command{wc} prints one line of counts for each file, and if the file was
3799 given as an argument, it prints the file name following the counts. By default
3800 if more than one @var{file} is given, @command{wc} prints a final line
3801 containing the cumulative counts, with the file name @file{total}.
3802 This @samp{total} line can be controlled with the @option{--total} option,
3803 which is a GNU extension.
3804 The counts are printed in this order: newlines, words, characters, bytes,
3805 maximum line length.
3806 Each count is printed right-justified in a field with at least one
3807 space between fields so that the numbers and file names normally line
3808 up nicely in columns. The width of the count fields varies depending
3809 on the inputs, so you should not depend on a particular field width.
3810 However, as a GNU extension, if only one count is printed,
3811 it is guaranteed to be printed without leading spaces.
3813 By default, @command{wc} prints three counts: the newline, words, and byte
3814 counts. Options can specify that only certain counts be printed.
3815 Options do not undo others previously given, so
3822 prints both the byte counts and the word counts.
3824 With the @option{--max-line-length} option, @command{wc} prints the length
3825 of the longest line per file, and if there is more than one file it
3826 prints the maximum (not the sum) of those lengths. The line lengths here
3827 are measured in screen columns, according to the current locale and
3828 assuming tab positions in every 8th column.
3830 The program accepts the following options. Also see @ref{Common options}.
3838 Print only the byte counts.
3844 Print only the character counts, as per the current locale.
3845 Invalid characters are not counted.
3851 Print only the word counts. A word is a nonzero length
3852 sequence of printable characters separated by white space.
3858 Print only the newline character counts.
3859 Note a file without a trailing newline character,
3860 will not have that last portion included in the line count.
3863 @itemx --max-line-length
3865 @opindex --max-line-length
3866 Print only the maximum display widths.
3867 Tabs are set at every 8th column.
3868 Display widths of wide characters are considered.
3869 Non-printable characters are given 0 width.
3871 @item --total=@var{when}
3872 @opindex --total=@var{when}
3873 Control when and how the final line with cumulative counts is printed.
3874 @var{when} is one of:
3877 @vindex auto @r{total option}
3878 - This is the default mode of @command{wc} when no @option{--total}
3879 option is specified. Output a total line if more than one @var{file}
3882 @vindex always @r{total option}
3883 - Always output a total line, irrespective of the number of files processed.
3885 @vindex only @r{total option}
3886 - Only output total counts. I.e., don't print individual file counts,
3887 suppress any leading spaces, and don't print the @samp{total} word itself,
3888 to simplify subsequent processing.
3890 @vindex none @r{total option}
3891 - Never output a total line.
3894 @macro filesZeroFromOption{cmd,withTotalOption,subListOutput}
3895 @item --files0-from=@var{file}
3896 @opindex --files0-from=@var{file}
3897 @c This is commented out to avoid a texi2dvi failure.
3898 @c texi2dvi (GNU Texinfo 4.11) 1.104
3899 @c @cindex including files from @command{\cmd\}
3900 Disallow processing files named on the command line, and instead process
3901 those named in file @var{file}; each name being terminated by a zero byte
3903 This is useful \withTotalOption\
3904 when the list of file names is so long that it may exceed a command line
3906 In such cases, running @command{\cmd\} via @command{xargs} is undesirable
3907 because it splits the list into pieces and makes @command{\cmd\} print
3908 \subListOutput\ for each sublist rather than for the entire list.
3909 One way to produce a list of ASCII NUL terminated file
3911 @command{find}, using its @option{-print0} predicate.
3912 If @var{file} is @samp{-} then the ASCII NUL terminated
3913 file names are read from standard input.
3915 @filesZeroFromOption{wc,,a total}
3917 For example, to find the length of the longest line in any @file{.c} or
3918 @file{.h} file in the current hierarchy, do this:
3921 find . -name '*.[ch]' -print0 |
3922 wc -L --files0-from=- | tail -n1
3930 @node sum invocation
3931 @section @command{sum}: Print checksum and block counts
3934 @cindex 16-bit checksum
3935 @cindex checksum, 16-bit
3937 @command{sum} computes a 16-bit checksum for each given @var{file}, or
3938 standard input if none are given or for a @var{file} of @samp{-}. Synopsis:
3941 sum [@var{option}]@dots{} [@var{file}]@dots{}
3944 @command{sum} prints the checksum for each @var{file} followed by the
3945 number of blocks in the file (rounded up). If at least one @var{file}
3946 is given, file names are also printed.
3948 By default, GNU @command{sum} computes checksums using an algorithm
3949 compatible with BSD @command{sum} and prints file sizes in units of
3952 The program accepts the following options. Also see @ref{Common options}.
3958 @cindex BSD @command{sum}
3959 Use the default (BSD compatible) algorithm. This option is included for
3960 compatibility with the System V @command{sum}. Unless @option{-s} was also
3961 given, it has no effect.
3967 @cindex System V @command{sum}
3968 Compute checksums using an algorithm compatible with System V
3969 @command{sum}'s default, and print file sizes in units of 512-byte blocks.
3973 @command{sum} is provided for compatibility; the @command{cksum} program (see
3974 next section) is preferable in new applications.
3979 @node cksum invocation
3980 @section @command{cksum}: Print and verify file checksums
3983 @cindex cyclic redundancy check
3984 @cindex CRC checksum
3987 @command{cksum} by default computes a cyclic redundancy check (CRC) checksum
3988 for each given @var{file}, or standard input if none are given or for a
3989 @var{file} of @samp{-}.
3991 cksum also supports the @option{-a/--algorithm} option to select the
3992 digest algorithm to use. @command{cksum} is the preferred interface
3993 to these digests, subsuming the other standalone checksumming utilities,
3994 which can be emulated using @code{cksum -a md5 --untagged "$@@"} etc.
3998 cksum [@var{option}]@dots{} [@var{file}]@dots{}
4001 @command{cksum} is typically used to ensure that files have not been corrupted,
4002 by comparing the @command{cksum} output for the received files with the
4003 @command{cksum} output for the original files (typically given in the
4006 @command{cksum} by default prints the POSIX standard CRC checksum
4007 for each file along with the number of bytes in the file,
4008 and the file name unless no arguments were given.
4010 The same usage and options as the @command{b2sum}
4011 command are supported. @xref{b2sum invocation}.
4012 In addition @command{cksum} supports the following options.
4019 @opindex --algorithm
4020 @cindex digest algorithm
4021 Compute checksums using the specified digest algorithm.
4023 Supported legacy checksums (which are not supported by @option{--check}):
4025 @samp{sysv} equivalent to @command{sum -s}
4026 @samp{bsd} equivalent to @command{sum -r}
4027 @samp{crc} equivalent to @command{cksum} (the default)
4030 Supported more modern digest algorithms are:
4032 @samp{md5} equivalent to @command{md5sum}
4033 @samp{sha1} equivalent to @command{sha1sum}
4034 @samp{sha224} equivalent to @command{sha224sum}
4035 @samp{sha256} equivalent to @command{sha256sum}
4036 @samp{sha384} equivalent to @command{sha384sum}
4037 @samp{sha512} equivalent to @command{sha512sum}
4038 @samp{blake2b} equivalent to @command{b2sum}
4039 @samp{sm3} only available through @command{cksum}
4046 @cindex base64 checksum encoding
4047 Print base64-encoded digests not hexadecimal.
4048 This option is ignored with @option{--check}.
4049 The format conforms to
4050 @uref{https://tools.ietf.org/search/rfc4648#section-4, RFC 4648#4}.
4052 Note that each base64-encoded digest has zero, one or two trailing padding
4053 (@samp{=}) bytes. The length of that padding is the checksum-bit-length
4054 modulo 3, and the @option{--check} parser requires precisely the same
4055 input digest string as what is output. I.e., removing or adding any
4056 @samp{=} padding renders a digest non-matching.
4060 Output extra information to stderr, like the checksum implementation being used.
4064 @cindex raw binary checksum
4065 Print only the unencoded raw binary digest for a single input.
4066 Do not output the file name or anything else.
4067 Use network byte order (big endian) where applicable:
4068 for @samp{bsd}, @samp{crc}, and @samp{sysv}.
4069 This option works only with a single input.
4070 Unlike other output formats, @command{cksum} provides no way to
4071 @option{--check} a @option{--raw} checksum.
4075 Output using the original Coreutils format used by the other
4076 standalone checksum utilities like @command{md5sum} for example.
4077 This format has the checksum at the start of the line, and may be
4078 more amenable to further processing by other utilities,
4079 especially in combination with the @option{--zero} option.
4080 Note this does not identify the digest algorithm used for the checksum.
4081 @xref{md5sum invocation} for details of this format.
4085 @node b2sum invocation
4086 @section @command{b2sum}: Print or check BLAKE2 digests
4090 @cindex 512-bit checksum
4091 @cindex checksum, 512-bit
4092 @cindex fingerprint, 512-bit
4093 @cindex message-digest, 512-bit
4095 @command{b2sum} computes a 512-bit checksum for each specified
4096 @var{file}. The same usage and options as the @command{md5sum}
4097 command are supported. @xref{md5sum invocation}.
4098 In addition @command{b2sum} supports the following options.
4105 @cindex BLAKE2 hash length
4106 Change (shorten) the default digest length.
4107 This is specified in bits and thus must be a multiple of 8.
4108 This option is ignored when @option{--check} is specified,
4109 as the length is automatically determined when checking.
4112 @node md5sum invocation
4113 @section @command{md5sum}: Print or check MD5 digests
4117 @cindex 128-bit checksum
4118 @cindex checksum, 128-bit
4119 @cindex fingerprint, 128-bit
4120 @cindex message-digest, 128-bit
4122 @command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or
4123 @dfn{message-digest}) for each specified @var{file}.
4125 @macro weakHash{hash}
4126 Note: The \hash\ digest is more reliable than a simple CRC (provided by
4127 the @command{cksum} command) for detecting accidental file corruption,
4128 as the chances of accidentally having two files with identical \hash\
4129 are vanishingly small. However, it should not be considered secure
4130 against malicious tampering: although finding a file with a given \hash\
4131 fingerprint is considered infeasible at the moment, it is known how
4132 to modify certain files, including digital certificates, so that they
4133 appear valid when signed with an \hash\ digest. For more secure hashes,
4134 consider using SHA-2, or the newer @command{b2sum} command.
4135 @xref{sha2 utilities}. @xref{b2sum invocation}.
4139 If a @var{file} is specified as @samp{-} or if no files are given
4140 @command{md5sum} computes the checksum for the standard input.
4141 @command{md5sum} can also determine whether a file and checksum are
4142 consistent. Synopsis:
4145 md5sum [@var{option}]@dots{} [@var{file}]@dots{}
4148 For each @var{file}, @samp{md5sum} outputs by default, the MD5 checksum,
4149 a space, a flag indicating binary or text input mode, and the file name.
4150 Binary mode is indicated with @samp{*}, text mode with @samp{ } (space).
4151 Binary mode is the default on systems where it's significant,
4152 otherwise text mode is the default. The @command{cksum} command always
4153 uses binary mode and a @samp{ } (space) flag.
4155 Without @option{--zero}, if @var{file} contains a backslash, newline,
4156 or carriage return, the line is started with a backslash, and each
4157 problematic character in the file name is escaped with a backslash,
4158 making the output unambiguous even in the presence of arbitrary file names.
4160 If @var{file} is omitted or specified as @samp{-}, standard input is read.
4162 The program accepts the following options. Also see @ref{Common options}.
4170 @cindex binary input files
4171 Note this option is not supported by the @command{cksum} command,
4172 as it operates in binary mode exclusively.
4173 Treat each input file as binary, by reading it in binary mode and
4174 outputting a @samp{*} flag. This is the inverse of @option{--text}.
4175 On systems like GNU that do not distinguish between binary
4176 and text files, this option merely flags each input mode as binary:
4177 the MD5 checksum is unaffected. This option is the default on systems
4178 like MS-DOS that distinguish between binary and text files, except
4179 for reading standard input when standard input is a terminal.
4183 Read file names and checksum information (not data) from each
4184 @var{file} (or from standard input if no @var{file} was specified) and report
4185 whether the checksums match the contents of the named files.
4186 The input to this mode of @command{md5sum} is usually the output of
4187 a prior, checksum-generating run of @samp{md5sum}.
4189 Three input formats are supported. Either the default output
4190 format described above, the @option{--tag} output format,
4191 or the BSD reversed mode format which is similar to the default mode,
4192 but doesn't use a character to distinguish binary and text modes.
4194 For the @command{cksum} command, the @option{--check} option
4195 supports auto-detecting the digest algorithm to use,
4196 when presented with checksum information in the @option{--tag} output format.
4198 Also for the @command{cksum} command, the @option{--check} option
4199 auto-detects the digest encoding, accepting both standard hexidecimal
4200 checksums and those generated via @command{cksum} with its
4201 @option{--base64} option.
4203 Output with @option{--zero} enabled is not supported by @option{--check}.
4205 For each such line, @command{md5sum} reads the named file and computes its
4206 MD5 checksum. Then, if the computed message digest does not match the
4207 one on the line with the file name, the file is noted as having
4208 failed the test. Otherwise, the file passes the test.
4209 By default, for each valid line, one line is written to standard
4210 output indicating whether the named file passed the test.
4211 After all checks have been performed, if there were any failures,
4212 a warning is issued to standard error.
4213 Use the @option{--status} option to inhibit that output.
4214 If any listed file cannot be opened or read, if any valid line has
4215 an MD5 checksum inconsistent with the associated file, or if no valid
4216 line is found, @command{md5sum} exits with nonzero status. Otherwise,
4217 it exits successfully.
4218 Note the @command{cksum} command doesn't support @option{--check}
4219 with the older @samp{sysv}, @samp{bsd}, or @samp{crc} algorithms.
4221 @item --ignore-missing
4222 @opindex --ignore-missing
4223 @cindex verifying MD5 checksums
4224 This option is useful only when verifying checksums.
4225 When verifying checksums, don't fail or report any status
4226 for missing files. This is useful when verifying a subset
4227 of downloaded files given a larger list of checksums.
4231 @cindex verifying MD5 checksums
4232 This option is useful only when verifying checksums.
4233 When verifying checksums, don't generate an 'OK' message per successfully
4234 checked file. Files that fail the verification are reported in the
4235 default one-line-per-file format. If there is any checksum mismatch,
4236 print a warning summarizing the failures to standard error.
4240 @cindex verifying MD5 checksums
4241 This option is useful only when verifying checksums.
4242 When verifying checksums, don't generate the default one-line-per-file
4243 diagnostic and don't output the warning summarizing any failures.
4244 Failures to open or read a file still evoke individual diagnostics to
4246 If all listed files are readable and are consistent with the associated
4247 MD5 checksums, exit successfully. Otherwise exit with a status code
4248 indicating there was a failure.
4253 Output BSD style checksums, which indicate the checksum algorithm used.
4254 As a GNU extension, if @option{--zero} is not used, file names with problematic
4255 characters are escaped as described above, with the same escaping indicator of
4256 @samp{\} at the start of the line, being used.
4257 The @option{--tag} option implies binary mode, and is disallowed with
4258 @option{--text} mode as supporting that would unnecessarily complicate
4259 the output format, while providing little benefit.
4260 The @command{cksum} command, uses @option{--tag} as its default output format.
4266 @cindex text input files
4267 Note this option is not supported by the @command{cksum} command.
4268 Treat each input file as text, by reading it in text mode and
4269 outputting a @samp{ } flag. This is the inverse of @option{--binary}.
4270 This option is the default on systems like GNU that do not
4271 distinguish between binary and text files. On other systems, it is
4272 the default for reading standard input when standard input is a
4273 terminal. This mode is never defaulted to if @option{--tag} is used.
4279 @cindex verifying MD5 checksums
4280 When verifying checksums, warn about improperly formatted MD5 checksum lines.
4281 This option is useful only if all but a few lines in the checked input
4286 @cindex verifying MD5 checksums
4287 When verifying checksums,
4288 if one or more input line is invalid,
4289 exit nonzero after all warnings have been issued.
4292 Also file name escaping is not used.
4298 @node sha1sum invocation
4299 @section @command{sha1sum}: Print or check SHA-1 digests
4303 @cindex 160-bit checksum
4304 @cindex checksum, 160-bit
4305 @cindex fingerprint, 160-bit
4306 @cindex message-digest, 160-bit
4308 @command{sha1sum} computes a 160-bit checksum for each specified
4309 @var{file}. The usage and options of this command are precisely the
4310 same as for @command{md5sum}. @xref{md5sum invocation}.
4315 @node sha2 utilities
4316 @section sha2 utilities: Print or check SHA-2 digests
4323 @cindex 224-bit checksum
4324 @cindex 256-bit checksum
4325 @cindex 384-bit checksum
4326 @cindex 512-bit checksum
4327 @cindex checksum, 224-bit
4328 @cindex checksum, 256-bit
4329 @cindex checksum, 384-bit
4330 @cindex checksum, 512-bit
4331 @cindex fingerprint, 224-bit
4332 @cindex fingerprint, 256-bit
4333 @cindex fingerprint, 384-bit
4334 @cindex fingerprint, 512-bit
4335 @cindex message-digest, 224-bit
4336 @cindex message-digest, 256-bit
4337 @cindex message-digest, 384-bit
4338 @cindex message-digest, 512-bit
4340 The commands @command{sha224sum}, @command{sha256sum},
4341 @command{sha384sum} and @command{sha512sum} compute checksums of
4342 various lengths (respectively 224, 256, 384 and 512 bits),
4343 collectively known as the SHA-2 hashes. The usage and options of
4344 these commands are precisely the same as for @command{md5sum}
4345 and @command{sha1sum}.
4346 @xref{md5sum invocation}.
4349 @node Operating on sorted files
4350 @chapter Operating on sorted files
4352 @cindex operating on sorted files
4353 @cindex sorted files, operations on
4355 These commands work with (or produce) sorted files.
4358 * sort invocation:: Sort text files.
4359 * shuf invocation:: Shuffle text files.
4360 * uniq invocation:: Uniquify files.
4361 * comm invocation:: Compare two sorted files line by line.
4362 * ptx invocation:: Produce a permuted index of file contents.
4363 * tsort invocation:: Topological sort.
4367 @node sort invocation
4368 @section @command{sort}: Sort text files
4371 @cindex sorting files
4373 @command{sort} sorts, merges, or compares all the lines from the given
4374 files, or standard input if none are given or for a @var{file} of
4375 @samp{-}. By default, @command{sort} writes the results to standard
4379 sort [@var{option}]@dots{} [@var{file}]@dots{}
4382 @cindex sort stability
4383 @cindex sort's last-resort comparison
4384 Many options affect how @command{sort} compares lines; if the results
4385 are unexpected, try the @option{--debug} option to see what happened.
4386 A pair of lines is compared as follows:
4387 @command{sort} compares each pair of fields (see @option{--key}), in the
4388 order specified on the command line, according to the associated
4389 ordering options, until a difference is found or no fields are left.
4390 If no key fields are specified, @command{sort} uses a default key of
4391 the entire line. Finally, as a last resort when all keys compare
4392 equal, @command{sort} compares entire lines as if no ordering options
4393 other than @option{--reverse} (@option{-r}) were specified. The
4394 @option{--stable} (@option{-s}) option disables this @dfn{last-resort
4395 comparison} so that lines in which all fields compare equal are left
4396 in their original relative order. The @option{--unique}
4397 (@option{-u}) option also disables the last-resort comparison.
4401 Unless otherwise specified, all comparisons use the character collating
4402 sequence specified by the @env{LC_COLLATE} locale.@footnote{If you
4403 use a non-POSIX locale (e.g., by setting @env{LC_ALL}
4404 to @samp{en_US}), then @command{sort} may produce output that is sorted
4405 differently than you're accustomed to. In that case, set the @env{LC_ALL}
4406 environment variable to @samp{C}@. Note that setting only @env{LC_COLLATE}
4407 has two problems. First, it is ineffective if @env{LC_ALL} is also set.
4408 Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if
4409 @env{LC_CTYPE} is unset) is set to an incompatible value. For example,
4410 you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but
4411 @env{LC_COLLATE} is @code{en_US.UTF-8}.}
4412 A line's trailing newline is not part of the line for comparison
4413 purposes. If the final byte of an input file is not a newline, GNU
4414 @command{sort} silently supplies one. GNU @command{sort} (as
4415 specified for all GNU utilities) has no limit on input line length or
4416 restrictions on bytes allowed within lines.
4418 @command{sort} has three modes of operation: sort (the default), merge,
4419 and check for sortedness. The following options change the operation
4426 @itemx --check=diagnose-first
4429 @cindex checking for sortedness
4430 Check whether the given file is already sorted: if it is not all
4431 sorted, print a diagnostic containing the first out-of-order line and
4432 exit with a status of 1.
4433 Otherwise, exit successfully.
4434 At most one input file can be given.
4437 @itemx --check=quiet
4438 @itemx --check=silent
4441 @cindex checking for sortedness
4442 Exit successfully if the given file is already sorted, and
4443 exit with status 1 otherwise.
4444 At most one input file can be given.
4445 This is like @option{-c}, except it does not print a diagnostic.
4451 @cindex merging sorted files
4452 Merge the given files by sorting them as a group. Each input file must
4453 always be individually sorted. It always works to sort instead of
4454 merge; merging is provided because it is faster, in the case where it
4459 @cindex exit status of @command{sort}
4463 0 if no error occurred
4464 1 if invoked with @option{-c} or @option{-C} and the input is not sorted
4465 2 if an error occurred
4469 If the environment variable @env{TMPDIR} is set, @command{sort} uses its
4470 value as the directory for temporary files instead of @file{/tmp}. The
4471 @option{--temporary-directory} (@option{-T}) option in turn overrides
4472 the environment variable.
4474 The following options affect the ordering of output lines. They may be
4475 specified globally or as part of a specific key field. If no key
4476 fields are specified, global options apply to comparison of entire
4477 lines; otherwise the global options are inherited by key fields that do
4478 not specify any special options of their own. In pre-POSIX
4479 versions of @command{sort}, global options affect only later key fields,
4480 so portable shell scripts should specify global options first.
4485 @itemx --ignore-leading-blanks
4487 @opindex --ignore-leading-blanks
4488 @cindex blanks, ignoring leading
4490 Ignore leading blanks when finding sort keys in each line.
4491 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
4492 can change this. Note blanks may be ignored by your locale's collating
4493 rules, but without this option they will be significant for character
4494 positions specified in keys with the @option{-k} option.
4497 @itemx --dictionary-order
4499 @opindex --dictionary-order
4500 @cindex dictionary order
4501 @cindex phone directory order
4502 @cindex telephone directory order
4504 Sort in @dfn{phone directory} order: ignore all characters except
4505 letters, digits and blanks when sorting.
4506 By default letters and digits are those of ASCII and a blank
4507 is a space or a tab, but the @env{LC_CTYPE} locale can change this.
4510 @itemx --ignore-case
4512 @opindex --ignore-case
4513 @cindex ignoring case
4514 @cindex case folding
4516 Fold lowercase characters into the equivalent uppercase characters when
4517 comparing so that, for example, @samp{b} and @samp{B} sort as equal.
4518 The @env{LC_CTYPE} locale determines character types.
4519 When used with @option{--unique} those lower case equivalent lines are
4520 thrown away. (There is currently no way to throw away the upper case
4521 equivalent instead. (Any @option{--reverse} given would only affect
4522 the final result, after the throwing away.))
4525 @itemx --general-numeric-sort
4526 @itemx --sort=general-numeric
4528 @opindex --general-numeric-sort
4530 @cindex general numeric sort
4532 Sort numerically, converting a prefix of each line to a long
4533 double-precision floating point number. @xref{Floating point}.
4534 Do not report overflow, underflow, or conversion errors.
4535 Use the following collating sequence:
4539 Lines that do not start with numbers (all considered to be equal).
4541 NaNs (``Not a Number'' values, in IEEE floating point arithmetic)
4542 in a consistent but machine-dependent order.
4546 Finite numbers in ascending numeric order (with @math{-0} and @math{+0} equal).
4551 Use this option only if there is no alternative; it is much slower than
4552 @option{--numeric-sort} (@option{-n}) and it can lose information when
4553 converting to floating point.
4555 You can use this option to sort hexadecimal numbers prefixed with
4556 @samp{0x} or @samp{0X}, where those numbers are not fixed width,
4557 or of varying case. However for hex numbers of consistent case,
4558 and left padded with @samp{0} to a consistent width, a standard
4559 lexicographic sort will be faster.
4562 @itemx --human-numeric-sort
4563 @itemx --sort=human-numeric
4565 @opindex --human-numeric-sort
4567 @cindex human numeric sort
4569 Sort numerically, first by numeric sign (negative, zero, or positive);
4570 then by SI suffix (either empty, or @samp{k} or @samp{K}, or
4571 one of @samp{MGTPEZYRQ}, in that order; @pxref{Block size}); and finally
4572 by numeric value. For example, @samp{1023M} sorts before @samp{1G}
4573 because @samp{M} (mega) precedes @samp{G} (giga) as an SI
4574 suffix. This option sorts values that are consistently scaled to the
4575 nearest suffix, regardless of whether suffixes denote powers of 1000
4576 or 1024, and it therefore sorts the output of any single invocation of
4577 the @command{df}, @command{du}, or @command{ls} commands that are
4578 invoked with their @option{--human-readable} or @option{--si} options.
4579 The syntax for numbers is the same as for the @option{--numeric-sort}
4580 option; the SI suffix must immediately follow the number.
4581 Note also the @command{numfmt} command, which can be used to reformat
4582 numbers to human format @emph{after} the sort, thus often allowing
4583 sort to operate on more accurate numbers.
4586 @itemx --ignore-nonprinting
4588 @opindex --ignore-nonprinting
4589 @cindex nonprinting characters, ignoring
4590 @cindex unprintable characters, ignoring
4592 Ignore nonprinting characters.
4593 The @env{LC_CTYPE} locale determines character types.
4594 This option has no effect if the stronger @option{--dictionary-order}
4595 (@option{-d}) option is also given.
4601 @opindex --month-sort
4603 @cindex months, sorting by
4605 An initial string, consisting of any amount of blanks, followed
4606 by a month name abbreviation, is folded to UPPER case and
4607 compared in the order @samp{JAN} < @samp{FEB} < @dots{} < @samp{DEC}@.
4608 Invalid names compare low to valid names. The @env{LC_TIME} locale
4609 category determines the month spellings.
4610 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
4614 @itemx --numeric-sort
4615 @itemx --sort=numeric
4617 @opindex --numeric-sort
4619 @cindex numeric sort
4621 Sort numerically. The number begins each line and consists
4622 of optional blanks, an optional @samp{-} sign, and zero or more
4623 digits possibly separated by thousands separators, optionally followed
4624 by a decimal-point character and zero or more digits. An empty
4625 number is treated as @samp{0}. The @env{LC_NUMERIC}
4626 locale specifies the decimal-point character and thousands separator.
4627 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
4630 Comparison is exact; there is no rounding error.
4632 Neither a leading @samp{+} nor exponential notation is recognized.
4633 To compare such strings numerically, use the
4634 @option{--general-numeric-sort} (@option{-g}) option.
4637 @itemx --version-sort
4639 @opindex --version-sort
4640 @cindex version number sort
4641 Sort by version name and number. It behaves like a standard sort,
4642 except that each sequence of decimal digits is treated numerically
4643 as an index/version number. (@xref{Version sort ordering}.)
4649 @cindex reverse sorting
4650 Reverse the result of comparison, so that lines with greater key values
4651 appear earlier in the output instead of later.
4654 @itemx --random-sort
4655 @itemx --sort=random
4657 @opindex --random-sort
4660 Sort by hashing the input keys and then sorting the hash values.
4661 Choose the hash function at random, ensuring that it is free of
4662 collisions so that differing keys have differing hash values. This is
4663 like a random permutation of the inputs (@pxref{shuf invocation}),
4664 except that keys with the same value sort together.
4666 If multiple random sort fields are specified, the same random hash
4667 function is used for all fields. To use different random hash
4668 functions for different fields, you can invoke @command{sort} more
4671 The choice of hash function is affected by the
4672 @option{--random-source} option.
4680 @item --compress-program=@var{prog}
4681 Compress any temporary files with the program @var{prog}.
4683 With no arguments, @var{prog} must compress standard input to standard
4684 output, and when given the @option{-d} option it must decompress
4685 standard input to standard output.
4687 Terminate with an error if @var{prog} exits with nonzero status.
4689 White space and the backslash character should not appear in
4690 @var{prog}; they are reserved for future use.
4692 @filesZeroFromOption{sort,,sorted output}
4694 @item -k @var{pos1}[,@var{pos2}]
4695 @itemx --key=@var{pos1}[,@var{pos2}]
4699 Specify a sort field that consists of the part of the line between
4700 @var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is
4701 omitted), @emph{inclusive}.
4703 In its simplest form @var{pos} specifies a field number (starting with 1),
4704 with fields being separated by runs of blank characters, and by default
4705 those blanks being included in the comparison at the start of each field.
4706 To adjust the handling of blank characters see the @option{-b} and
4707 @option{-t} options.
4710 each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]},
4711 where @var{f} is the number of the field to use, and @var{c} is the number
4712 of the first character from the beginning of the field. Fields and character
4713 positions are numbered starting with 1; a character position of zero in
4714 @var{pos2} indicates the field's last character. If @samp{.@var{c}} is
4715 omitted from @var{pos1}, it defaults to 1 (the beginning of the field);
4716 if omitted from @var{pos2}, it defaults to 0 (the end of the field).
4717 @var{opts} are ordering options, allowing individual keys to be sorted
4718 according to different rules; see below for details. Keys can span
4721 Example: To sort on the second field, use @option{--key=2,2}
4722 (@option{-k 2,2}). See below for more notes on keys and more examples.
4723 See also the @option{--debug} option to help determine the part
4724 of the line being used in the sort.
4727 Highlight the portion of each line used for sorting.
4728 Also issue warnings about questionable usage to standard error.
4730 @item --batch-size=@var{nmerge}
4731 @opindex --batch-size
4732 @cindex number of inputs to merge, nmerge
4733 Merge at most @var{nmerge} inputs at once.
4735 When @command{sort} has to merge more than @var{nmerge} inputs,
4736 it merges them in groups of @var{nmerge}, saving the result in
4737 a temporary file, which is then used as an input in a subsequent merge.
4739 A large value of @var{nmerge} may improve merge performance and decrease
4740 temporary storage utilization at the expense of increased memory usage
4741 and I/O@. Conversely a small value of @var{nmerge} may reduce memory
4742 requirements and I/O at the expense of temporary storage consumption and
4745 The value of @var{nmerge} must be at least 2. The default value is
4746 currently 16, but this is implementation-dependent and may change in
4749 The value of @var{nmerge} may be bounded by a resource limit for open
4750 file descriptors. The commands @samp{ulimit -n} or @samp{getconf
4751 OPEN_MAX} may display limits for your systems; these limits may be
4752 modified further if your program already has some files open, or if
4753 the operating system has other limits on the number of open files. If
4754 the value of @var{nmerge} exceeds the resource limit, @command{sort}
4755 silently uses a smaller value.
4757 @item -o @var{output-file}
4758 @itemx --output=@var{output-file}
4761 @cindex overwriting of input, allowed
4762 Write output to @var{output-file} instead of standard output.
4763 Normally, @command{sort} reads all input before opening
4764 @var{output-file}, so you can sort a file in place by using
4765 commands like @code{sort -o F F} and @code{cat F | sort -o F}@.
4766 However, it is often safer to output to an otherwise-unused file, as
4767 data may be lost if the system crashes or @command{sort} encounters
4768 an I/O or other serious error while a file is being sorted in place.
4769 Also, @command{sort} with @option{--merge} (@option{-m}) can open
4770 the output file before reading all input, so a command like @code{cat
4771 F | sort -m -o F - G} is not safe as @command{sort} might start
4772 writing @file{F} before @command{cat} is done reading it.
4774 @vindex POSIXLY_CORRECT
4775 On newer systems, @option{-o} cannot appear after an input file if
4776 @env{POSIXLY_CORRECT} is set, e.g., @samp{sort F -o F}@. Portable
4777 scripts should specify @option{-o @var{output-file}} before any input
4780 @item --random-source=@var{file}
4781 @opindex --random-source
4782 @cindex random source for sorting
4783 Use @var{file} as a source of random data used to determine which
4784 random hash function to use with the @option{-R} option. @xref{Random
4791 @cindex sort stability
4792 @cindex sort's last-resort comparison
4794 Make @command{sort} stable by disabling its last-resort comparison.
4795 This option has no effect if no fields or global ordering options
4796 other than @option{--reverse} (@option{-r}) are specified.
4799 @itemx --buffer-size=@var{size}
4801 @opindex --buffer-size
4802 @cindex size for main memory sorting
4803 Use a main-memory sort buffer of the given @var{size}. By default,
4804 @var{size} is in units of 1024 bytes. Appending @samp{%} causes
4805 @var{size} to be interpreted as a percentage of physical memory.
4806 Appending @samp{K} multiplies @var{size} by 1024 (the default),
4807 @samp{M} by 1,048,576, @samp{G} by 1,073,741,824, and so on for
4808 @samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y}, @samp{R}, and @samp{Q}@.
4810 @samp{b} causes @var{size} to be interpreted as a byte count, with no
4813 This option can improve the performance of @command{sort} by causing it
4814 to start with a larger or smaller sort buffer than the default.
4815 However, this option affects only the initial buffer size. The buffer
4816 grows beyond @var{size} if @command{sort} encounters input lines larger
4819 @item -t @var{separator}
4820 @itemx --field-separator=@var{separator}
4822 @opindex --field-separator
4823 @cindex field separator character
4824 Use character @var{separator} as the field separator when finding the
4825 sort keys in each line. By default, fields are separated by the empty
4826 string between a non-blank character and a blank character.
4827 By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
4830 That is, given the input line @w{@samp{ foo bar}}, @command{sort} breaks it
4831 into fields @w{@samp{ foo}} and @w{@samp{ bar}}. The field separator is
4832 not considered to be part of either the field preceding or the field
4833 following, so with @samp{sort @w{-t " "}} the same input line has
4834 three fields: an empty field, @samp{foo}, and @samp{bar}.
4835 However, fields that extend to the end of the line,
4836 as @option{-k 2}, or fields consisting of a range, as @option{-k 2,3},
4837 retain the field separators present between the endpoints of the range.
4839 To specify ASCII NUL as the field separator,
4840 use the two-character string @samp{\0}, e.g., @samp{sort -t '\0'}.
4842 @item -T @var{tempdir}
4843 @itemx --temporary-directory=@var{tempdir}
4845 @opindex --temporary-directory
4846 @cindex temporary directory
4848 Use directory @var{tempdir} to store temporary files, overriding the
4849 @env{TMPDIR} environment variable. If this option is given more than
4850 once, temporary files are stored in all the directories given. If you
4851 have a large sort or merge that is I/O-bound, you can often improve
4852 performance by using this option to specify directories on different
4855 @item --parallel=@var{n}
4857 @cindex multithreaded sort
4858 Set the number of sorts run in parallel to @var{n}. By default,
4859 @var{n} is set to the number of available processors, but limited
4860 to 8, as there are diminishing performance gains after that.
4861 Note also that using @var{n} threads increases the memory usage by
4862 a factor of log @var{n}. Also see @ref{nproc invocation}.
4868 @cindex uniquifying output
4870 Normally, output only the first of a sequence of lines that compare
4871 equal. For the @option{--check} (@option{-c} or @option{-C}) option,
4872 check that no pair of consecutive lines compares equal.
4874 This option also disables the default last-resort comparison.
4876 The commands @code{sort -u} and @code{sort | uniq} are equivalent, but
4877 this equivalence does not extend to arbitrary @command{sort} options.
4878 For example, @code{sort -n -u} inspects only the value of the initial
4879 numeric string when checking for uniqueness, whereas @code{sort -n |
4880 uniq} inspects the entire line. @xref{uniq invocation}.
4883 @macro newlineFieldSeparator
4884 Note with @option{-z} the newline character is treated as a field separator.
4889 Historical (BSD and System V) implementations of @command{sort} have
4890 differed in their interpretation of some options, particularly
4891 @option{-b}, @option{-f}, and @option{-n}.
4892 GNU sort follows the POSIX
4893 behavior, which is usually (but not always!) like the System V behavior.
4894 According to POSIX, @option{-n} no longer implies @option{-b}. For
4895 consistency, @option{-M} has been changed in the same way. This may
4896 affect the meaning of character positions in field specifications in
4897 obscure cases. The only fix is to add an explicit @option{-b}.
4899 A position in a sort field specified with @option{-k} may have any
4900 of the option letters @samp{MbdfghinRrV} appended to it, in which case no
4901 global ordering options are inherited by that particular field. The
4902 @option{-b} option may be independently attached to either or both of
4903 the start and end positions of a field specification, and if it is
4904 inherited from the global options it will be attached to both.
4905 If input lines can contain leading or adjacent blanks and @option{-t}
4906 is not used, then @option{-k} is typically combined with @option{-b} or
4907 an option that implicitly ignores leading blanks (@samp{Mghn}) as otherwise
4908 the varying numbers of leading blanks in fields can cause confusing results.
4910 If the start position in a sort field specifier falls after the end of
4911 the line or after the end field, the field is empty. If the @option{-b}
4912 option was specified, the @samp{.@var{c}} part of a field specification
4913 is counted from the first nonblank character of the field.
4915 @vindex _POSIX2_VERSION
4916 @vindex POSIXLY_CORRECT
4917 On systems not conforming to POSIX 1003.1-2001,
4918 @command{sort} supports a traditional origin-zero
4919 syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys.
4920 The traditional command @samp{sort +@var{a}.@var{x} -@var{b}.@var{y}}
4921 is equivalent to @samp{sort -k @var{a+1}.@var{x+1},@var{b}} if @var{y}
4922 is @samp{0} or absent, otherwise it is equivalent to @samp{sort -k
4923 @var{a+1}.@var{x+1},@var{b+1}.@var{y}}.
4925 This traditional behavior can be controlled with the
4926 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
4927 conformance}); it can also be enabled when @env{POSIXLY_CORRECT} is
4928 not set by using the traditional syntax with @samp{-@var{pos2}} present.
4930 Scripts intended for use on standard hosts should avoid traditional
4931 syntax and should use @option{-k} instead. For example, avoid
4932 @samp{sort +2}, since it might be interpreted as either @samp{sort
4933 ./+2} or @samp{sort -k 3}. If your script must also run on hosts that
4934 support only the traditional syntax, it can use a test like @samp{if sort
4935 -k 1 </dev/null >/dev/null 2>&1; then @dots{}} to decide which syntax
4938 Here are some examples to illustrate various combinations of options.
4943 Sort in descending (reverse) numeric order.
4950 Run no more than 4 sorts concurrently, using a buffer size of 10M.
4953 sort --parallel=4 -S 10M
4957 Sort alphabetically, omitting the first and second fields
4958 and the blanks at the start of the third field.
4959 This uses a single key composed of the characters beginning
4960 at the start of the first nonblank character in field three
4961 and extending to the end of each line.
4968 Sort numerically on the second field and resolve ties by sorting
4969 alphabetically on the third and fourth characters of field five.
4970 Use @samp{:} as the field delimiter.
4973 sort -t : -k 2,2n -k 5.3,5.4
4976 Note that if you had written @option{-k 2n} instead of @option{-k 2,2n}
4977 @command{sort} would have used all characters beginning in the second field
4978 and extending to the end of the line as the primary @emph{numeric}
4979 key. For the large majority of applications, treating keys spanning
4980 more than one field as numeric will not do what you expect.
4982 Also note that the @samp{n} modifier was applied to the field-end
4983 specifier for the first key. It would have been equivalent to
4984 specify @option{-k 2n,2} or @option{-k 2n,2n}. All modifiers except
4985 @samp{b} apply to the associated @emph{field}, regardless of whether
4986 the modifier character is attached to the field-start and/or the
4987 field-end part of the key specifier.
4990 Sort the password file on the fifth field and ignore any
4991 leading blanks. Sort lines with equal values in field five
4992 on the numeric user ID in field three. Fields are separated
4996 sort -t : -k 5b,5 -k 3,3n /etc/passwd
4997 sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
4998 sort -t : -b -k 5,5 -k 3,3n /etc/passwd
5001 These three commands have equivalent effect. The first specifies that
5002 the first key's start position ignores leading blanks and the second
5003 key is sorted numerically. The other two commands rely on global
5004 options being inherited by sort keys that lack modifiers. The inheritance
5005 works in this case because @option{-k 5b,5b} and @option{-k 5b,5} are
5006 equivalent, as the location of a field-end lacking a @samp{.@var{c}}
5007 character position is not affected by whether initial blanks are
5011 Sort a set of log files, primarily by IPv4 address and secondarily by
5012 timestamp. If two lines' primary and secondary keys are identical,
5013 output the lines in the same order that they were input. The log
5014 files contain lines that look like this:
5017 4.150.156.3 - - [01/Apr/2020:06:31:51 +0000] message 1
5018 211.24.3.231 - - [24/Apr/2020:20:17:39 +0000] message 2
5021 Fields are separated by exactly one space. Sort IPv4 addresses
5022 lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201
5023 because 61 is less than 129.
5026 sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log |
5027 sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n
5030 This example cannot be done with a single POSIX @command{sort} invocation,
5031 since IPv4 address components are separated by @samp{.} while dates
5032 come just after a space. So it is broken down into two invocations of
5033 @command{sort}: the first sorts by timestamp and the second by IPv4
5034 address. The timestamp is sorted by year, then month, then day, and
5035 finally by hour-minute-second field, using @option{-k} to isolate each
5036 field. Except for hour-minute-second there's no need to specify the
5037 end of each key field, since the @samp{n} and @samp{M} modifiers sort
5038 based on leading prefixes that cannot cross field boundaries. The
5039 IPv4 addresses are sorted lexicographically. The second sort uses
5040 @samp{-s} so that ties in the primary key are broken by the secondary
5041 key; the first sort uses @samp{-s} so that the combination of the two
5042 sorts is stable. Note as a GNU extension, the above example could
5043 be achieved in a single @command{sort} invocation by sorting the
5044 IPv4 address field using a @samp{V} version type, like @samp{-k1,1V}.
5047 Generate a tags file in case-insensitive sorted order.
5050 find src -type f -print0 | sort -z -f | xargs -0 etags --append
5053 The use of @option{-print0}, @option{-z}, and @option{-0} in this case means
5054 that file names that contain blanks or other special characters are
5056 by the sort operation.
5058 @c This example is a bit contrived and needs more explanation.
5060 @c Sort records separated by an arbitrary string by using a pipe to convert
5061 @c each record delimiter string to @samp{\0},
5062 @c then using sort's @option{-z} option,
5063 @c and converting each @samp{\0} back to the original record delimiter.
5066 @c printf 'c\n\nb\n\na\n' |
5067 @c perl -0pe 's/\n\n/\n\0/g' |
5069 @c perl -0pe 's/\0/\n/g'
5073 Use the common DSU, Decorate Sort Undecorate idiom to
5074 sort lines according to their length.
5077 awk '@{print length, $0@}' /etc/passwd | sort -n | cut -f2- -d' '
5080 In general this technique can be used to sort data that the @command{sort}
5081 command does not support, or is inefficient at, sorting directly.
5084 Shuffle a list of directories, but preserve the order of files within
5085 each directory. For instance, one could use this to generate a music
5086 playlist in which albums are shuffled but the songs of each album are
5090 ls */* | sort -t / -k 1,1R -k 2,2
5096 @node shuf invocation
5097 @section @command{shuf}: Shuffling text
5100 @cindex shuffling files
5102 @command{shuf} shuffles its input by outputting a random permutation
5103 of its input lines. Each output permutation is equally likely.
5107 shuf [@var{option}]@dots{} [@var{file}]
5108 shuf -e [@var{option}]@dots{} [@var{arg}]@dots{}
5109 shuf -i @var{lo}-@var{hi} [@var{option}]@dots{}
5112 @command{shuf} has three modes of operation that affect where it
5113 obtains its input lines. By default, it reads lines from standard
5114 input. The following options change the operation mode:
5122 @cindex command-line operands to shuffle
5123 Treat each command-line operand as an input line.
5125 @item -i @var{lo}-@var{hi}
5126 @itemx --input-range=@var{lo}-@var{hi}
5128 @opindex --input-range
5129 @cindex input range to shuffle
5130 Act as if input came from a file containing the range of unsigned
5131 decimal integers @var{lo}@dots{}@var{hi}, one per line.
5135 @command{shuf}'s other options can affect its behavior in all
5140 @item -n @var{count}
5141 @itemx --head-count=@var{count}
5143 @opindex --head-count
5144 @cindex head of output
5145 Output at most @var{count} lines. By default, all input lines are
5148 @item -o @var{output-file}
5149 @itemx --output=@var{output-file}
5152 @cindex overwriting of input, allowed
5153 Write output to @var{output-file} instead of standard output.
5154 @command{shuf} reads all input before opening
5155 @var{output-file}, so you can safely shuffle a file in place by using
5156 commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}.
5158 @item --random-source=@var{file}
5159 @opindex --random-source
5160 @cindex random source for shuffling
5161 Use @var{file} as a source of random data used to determine which
5162 permutation to generate. @xref{Random sources}.
5168 @cindex repeat output values
5169 Repeat output values, that is, select with replacement. With this
5170 option the output is not a permutation of the input; instead, each
5171 output line is randomly chosen from all the inputs. This option is
5172 typically combined with @option{--head-count}; if
5173 @option{--head-count} is not given, @command{shuf} repeats
5192 might produce the output
5202 Similarly, the command:
5205 shuf -e clubs hearts diamonds spades
5219 and the command @samp{shuf -i 1-4} might output:
5229 The above examples all have four input lines, so @command{shuf} might
5230 produce any of the twenty-four possible permutations of the input. In
5231 general, if there are @var{n} input lines, there are @var{n}! (i.e.,
5232 @var{n} factorial, or @var{n} * (@var{n} - 1) * @dots{} * 1) possible
5233 output permutations.
5236 To output 50 random numbers each in the range 0 through 9, use:
5239 shuf -r -n 50 -i 0-9
5243 To simulate 100 coin flips, use:
5246 shuf -r -n 100 -e Head Tail
5252 @node uniq invocation
5253 @section @command{uniq}: Uniquify files
5256 @cindex uniquify files
5258 @command{uniq} writes the unique lines in the given @file{input}, or
5259 standard input if nothing is given or for an @var{input} name of
5263 uniq [@var{option}]@dots{} [@var{input} [@var{output}]]
5266 By default, @command{uniq} prints its input lines, except that
5267 it discards all but the first of adjacent repeated lines, so that
5268 no output lines are repeated. Optionally, it can instead discard
5269 lines that are not repeated, or all repeated lines.
5271 The input need not be sorted, but repeated input lines are detected
5272 only if they are adjacent. If you want to discard non-adjacent
5273 duplicate lines, perhaps you want to use @code{sort -u}.
5274 @xref{sort invocation}.
5277 Comparisons honor the rules specified by the @env{LC_COLLATE}
5280 If no @var{output} file is specified, @command{uniq} writes to standard
5283 The program accepts the following options. Also see @ref{Common options}.
5288 @itemx --skip-fields=@var{n}
5290 @opindex --skip-fields
5291 Skip @var{n} fields on each line before checking for uniqueness. Use
5292 a null string for comparison if a line has fewer than @var{n} fields.
5293 Fields are a sequence of blank characters followed by non-blank characters.
5294 Field numbers are one based, i.e., @option{-f 1} will skip the first
5295 field (which may optionally have leading blanks).
5297 For compatibility @command{uniq} supports a traditional option syntax
5298 @option{-@var{n}}. New scripts should use @option{-f @var{n}} instead.
5301 @itemx --skip-chars=@var{n}
5303 @opindex --skip-chars
5304 Skip @var{n} characters before checking for uniqueness. Use a null string
5305 for comparison if a line has fewer than @var{n} characters. If you use both
5306 the field and character skipping options, fields are skipped over first.
5308 @vindex _POSIX2_VERSION
5309 On systems not conforming to POSIX 1003.1-2001,
5310 @command{uniq} supports a traditional option syntax
5312 Although this traditional behavior can be controlled with the
5313 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
5314 conformance}), portable scripts should avoid commands whose
5315 behavior depends on this variable.
5316 For example, use @samp{uniq ./+10} or @samp{uniq -s 10} rather than
5317 the ambiguous @samp{uniq +10}.
5323 Print the number of times each line occurred along with the line.
5326 @itemx --ignore-case
5328 @opindex --ignore-case
5329 Ignore differences in case when comparing lines.
5335 @cindex repeated lines, outputting
5336 Discard lines that are not repeated. When used by itself, this option
5337 causes @command{uniq} to print the first copy of each repeated line,
5341 @itemx --all-repeated[=@var{delimit-method}]
5343 @opindex --all-repeated
5344 @cindex all repeated lines, outputting
5345 Do not discard the second and subsequent repeated input lines,
5346 but discard lines that are not repeated.
5347 This option is useful mainly in conjunction with other options e.g.,
5348 to ignore case or to compare only selected fields.
5349 The optional @var{delimit-method}, supported with the long form option,
5350 specifies how to delimit groups of repeated lines, and must be one of the
5356 Do not delimit groups of repeated lines.
5357 This is equivalent to @option{--all-repeated} (@option{-D}).
5360 Output a newline before each group of repeated lines.
5361 @macro nulOutputNote
5362 With @option{--zero-terminated} (@option{-z}), use a zero
5363 byte (ASCII NUL) instead of a newline as the delimiter.
5368 Separate groups of repeated lines with a single newline.
5369 This is the same as using @samp{prepend}, except that
5370 no delimiter is inserted before the first group, and hence
5371 may be better suited for output direct to users.
5375 @macro ambiguousGroupNote
5376 Note that when groups are delimited and the input stream contains
5377 blank lines, then the output is ambiguous.
5378 To avoid that, filter the input through @samp{tr -s '\\n'} to
5383 This is a GNU extension.
5384 @c FIXME: give an example showing *how* it's useful
5386 @item --group[=@var{delimit-method}]
5388 @cindex all lines, grouping
5389 Output all lines, and delimit each unique group.
5391 The optional @var{delimit-method} specifies how to delimit
5392 groups, and must be one of the following:
5397 Separate unique groups with a single delimiter.
5398 This is the default delimiting method if none is specified,
5399 and better suited for output direct to users.
5402 Output a delimiter before each group of unique items.
5405 Output a delimiter after each group of unique items.
5408 Output a delimiter around each group of unique items.
5413 This is a GNU extension.
5419 @cindex unique lines, outputting
5420 Discard the last line that would be output for a repeated input group.
5421 When used by itself, this option causes @command{uniq} to print unique
5422 lines, and nothing else.
5425 @itemx --check-chars=@var{n}
5427 @opindex --check-chars
5428 Compare at most @var{n} characters on each line (after skipping any specified
5429 fields and characters). By default the entire rest of the lines are
5433 @newlineFieldSeparator
5440 @node comm invocation
5441 @section @command{comm}: Compare two sorted files line by line
5444 @cindex line-by-line comparison
5445 @cindex comparing sorted files
5447 @command{comm} writes to standard output lines that are common, and lines
5448 that are unique, to two input files; a file name of @samp{-} means
5449 standard input. Synopsis:
5452 comm [@var{option}]@dots{} @var{file1} @var{file2}
5456 Before @command{comm} can be used, the input files must be sorted using the
5457 collating sequence specified by the @env{LC_COLLATE} locale.
5458 If an input file ends in a non-newline
5459 character, a newline is silently appended. The @command{sort} command with
5460 no options always outputs a file that is suitable input to @command{comm}.
5462 @cindex differing lines
5463 @cindex common lines
5464 With no options, @command{comm} produces three-column output. Column one
5465 contains lines unique to @var{file1}, column two contains lines unique
5466 to @var{file2}, and column three contains lines common to both files.
5467 Columns are separated by a single TAB character.
5468 @c FIXME: when there's an option to supply an alternative separator
5469 @c string, append "by default" to the above sentence.
5474 The options @option{-1}, @option{-2}, and @option{-3} suppress printing of
5475 the corresponding columns (and separators). Also see @ref{Common options}.
5477 Unlike some other comparison utilities, @command{comm} has an exit
5478 status that does not depend on the result of the comparison.
5479 Upon normal completion @command{comm} produces an exit code of zero.
5480 If there is an error it exits with nonzero status.
5482 @macro checkOrderOption{cmd}
5483 If the @option{--check-order} option is given, unsorted inputs will
5484 cause a fatal error message. If the option @option{--nocheck-order}
5485 is given, unsorted inputs will never cause an error message. If neither
5486 of these options is given, wrongly sorted inputs are diagnosed
5487 only if an input file is found to contain unpairable
5489 lines, and when both input files are non empty.
5491 @ifclear JOIN_COMMAND
5494 If an input file is diagnosed as being unsorted, the @command{\cmd\}
5495 command will exit with a nonzero status (and the output should not be used).
5497 Forcing @command{\cmd\} to process wrongly sorted input files
5498 containing unpairable lines by specifying @option{--nocheck-order} is
5499 not guaranteed to produce any particular output. The output will
5500 probably not correspond with whatever you hoped it would be.
5502 @checkOrderOption{comm}
5507 Fail with an error message if either input file is wrongly ordered.
5509 @item --nocheck-order
5510 Do not check that both input files are in sorted order.
5514 @item --output-delimiter=@var{str}
5515 Print @var{str} between adjacent output columns,
5516 rather than the default of a single TAB character.
5518 The delimiter @var{str} may be empty, in which case
5519 the ASCII NUL character is used to delimit output columns.
5522 Output a summary at the end.
5524 Similar to the regular output,
5525 column one contains the total number of lines unique to @var{file1},
5526 column two contains the total number of lines unique to @var{file2}, and
5527 column three contains the total number of lines common to both files,
5528 followed by the word @samp{total} in the additional column four.
5530 In the following example, @command{comm} omits the regular output
5531 (@option{-123}), thus just printing the summary:
5534 $ printf '%s\n' a b c d e > file1
5535 $ printf '%s\n' b c d e f g > file2
5536 $ comm --total -123 file1 file2
5540 This option is a GNU extension. Portable scripts should use @command{wc} to
5541 get the totals, e.g. for the above example files:
5544 $ comm -23 file1 file2 | wc -l # number of lines only in file1
5546 $ comm -13 file1 file2 | wc -l # number of lines only in file2
5548 $ comm -12 file1 file2 | wc -l # number of lines common to both files
5556 @node ptx invocation
5557 @section @command{ptx}: Produce permuted indexes
5561 @command{ptx} reads a text file and essentially produces a permuted index, with
5562 each keyword in its context. The calling sketch is either one of:
5565 ptx [@var{option} @dots{}] [@var{file} @dots{}]
5566 ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]]
5569 The @option{-G} (or its equivalent: @option{--traditional}) option disables
5570 all GNU extensions and reverts to traditional mode, thus introducing some
5571 limitations and changing several of the program's default option values.
5572 When @option{-G} is not specified, GNU extensions are always enabled.
5573 GNU extensions to @command{ptx} are documented wherever appropriate in this
5574 document. @xref{Compatibility in ptx}, for the full list.
5576 Individual options are explained in the following sections.
5578 When GNU extensions are enabled, there may be zero, one or several
5579 @var{file}s after the options. If there is no @var{file}, the program
5580 reads the standard input. If there is one or several @var{file}s, they
5581 give the name of input files which are all read in turn, as if all the
5582 input files were concatenated. However, there is a full contextual
5583 break between each file and, when automatic referencing is requested,
5584 file names and line numbers refer to individual text input files. In
5585 all cases, the program outputs the permuted index to the standard
5588 When GNU extensions are @emph{not} enabled, that is, when the program
5589 operates in traditional mode, there may be zero, one or two parameters
5590 besides the options. If there are no parameters, the program reads the
5591 standard input and outputs the permuted index to the standard output.
5592 If there is only one parameter, it names the text @var{input} to be read
5593 instead of the standard input. If two parameters are given, they give
5594 respectively the name of the @var{input} file to read and the name of
5595 the @var{output} file to produce. @emph{Be very careful} to note that,
5596 in this case, the contents of file given by the second parameter is
5597 destroyed. This behavior is dictated by System V @command{ptx}
5598 compatibility; GNU Standards normally discourage output parameters not
5599 introduced by an option.
5601 Note that for @emph{any} file named as the value of an option or as an
5602 input text file, a single dash @samp{-} may be used, in which case
5603 standard input is assumed. However, it would not make sense to use this
5604 convention more than once per program invocation.
5607 * General options in ptx:: Options which affect general program behavior.
5608 * Charset selection in ptx:: Underlying character set considerations.
5609 * Input processing in ptx:: Input fields, contexts, and keyword selection.
5610 * Output formatting in ptx:: Types of output format, and sizing the fields.
5611 * Compatibility in ptx::
5615 @node General options in ptx
5616 @subsection General options
5621 @itemx --traditional
5622 As already explained, this option disables all GNU extensions to
5623 @command{ptx} and switches to traditional mode.
5626 Print a short help on standard output, then exit without further
5630 Print the program version on standard output, then exit without further
5638 @node Charset selection in ptx
5639 @subsection Charset selection
5641 As it is set up now, @command{ptx} assumes that the input file is coded
5642 using 8-bit characters, and it may not work well in multibyte locales.
5643 In a single-byte locale, the default regular expression
5644 for a keyword allows foreign or diacriticized letters. Keyword sorting,
5645 however, is still crude; it obeys the underlying character set ordering
5648 The output of @command{ptx} assumes the locale's character encoding.
5649 For example, with @command{ptx}'s @option{-T} option, if the locale
5650 uses the Latin-1 encoding you may need a LaTeX directive like
5651 @samp{\usepackage[latin1]@{inputenc@}} to render non-ASCII characters
5657 @itemx --ignore-case
5659 @opindex --ignore-case
5660 Fold lower case letters to upper case for sorting.
5665 @node Input processing in ptx
5666 @subsection Word selection and input processing
5671 @itemx --break-file=@var{file}
5673 @opindex --break-file
5675 This option provides an alternative (to @option{-W}) method of describing
5676 which characters make up words. It introduces the name of a
5677 file which contains a list of characters which can@emph{not} be part of
5678 one word; this file is called the @dfn{Break file}. Any character which
5679 is not part of the Break file is a word constituent. If both options
5680 @option{-b} and @option{-W} are specified, then @option{-W} has precedence and
5681 @option{-b} is ignored.
5683 When GNU extensions are enabled, the only way to avoid newline as a
5684 break character is to write all the break characters in the file with no
5685 newline at all, not even at the end of the file. When GNU extensions
5686 are disabled, spaces, tabs and newlines are always considered as break
5687 characters even if not included in the Break file.
5690 @itemx --ignore-file=@var{file}
5692 @opindex --ignore-file
5694 The file associated with this option contains a list of words which will
5695 never be taken as keywords in concordance output. It is called the
5696 @dfn{Ignore file}. The file contains exactly one word in each line; the
5697 end of line separation of words is not subject to the value of the
5701 @itemx --only-file=@var{file}
5703 @opindex --only-file
5705 The file associated with this option contains a list of words which will
5706 be retained in concordance output; any word not mentioned in this file
5707 is ignored. The file is called the @dfn{Only file}. The file contains
5708 exactly one word in each line; the end of line separation of words is
5709 not subject to the value of the @option{-S} option.
5711 There is no default for the Only file. When both an Only file and an
5712 Ignore file are specified, a word is considered a keyword only
5713 if it is listed in the Only file and not in the Ignore file.
5718 @opindex --references
5720 On each input line, the leading sequence of non-white space characters will be
5721 taken to be a reference that has the purpose of identifying this input
5722 line in the resulting permuted index.
5723 @xref{Output formatting in ptx},
5724 for more information about reference production.
5725 Using this option changes the default value for option @option{-S}.
5727 Using this option, the program does not try very hard to remove
5728 references from contexts in output, but it succeeds in doing so
5729 @emph{when} the context ends exactly at the newline. If option
5730 @option{-r} is used with @option{-S} default value, or when GNU extensions
5731 are disabled, this condition is always met and references are completely
5732 excluded from the output contexts.
5734 @item -S @var{regexp}
5735 @itemx --sentence-regexp=@var{regexp}
5737 @opindex --sentence-regexp
5739 This option selects which regular expression will describe the end of a
5740 line or the end of a sentence. In fact, this regular expression is not
5741 the only distinction between end of lines or end of sentences, and input
5742 line boundaries have no special significance outside this option. By
5743 default, when GNU extensions are enabled and if @option{-r} option is not
5744 used, end of sentences are used. In this case, this @var{regex} is
5745 imported from GNU Emacs:
5748 [.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]*
5751 Whenever GNU extensions are disabled or if @option{-r} option is used, end
5752 of lines are used; in this case, the default @var{regexp} is just:
5758 Using an empty @var{regexp} is equivalent to completely disabling end of
5759 line or end of sentence recognition. In this case, the whole file is
5760 considered to be a single big line or sentence. The user might want to
5761 disallow all truncation flag generation as well, through option @option{-F
5762 ""}. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
5765 When the keywords happen to be near the beginning of the input line or
5766 sentence, this often creates an unused area at the beginning of the
5767 output context line; when the keywords happen to be near the end of the
5768 input line or sentence, this often creates an unused area at the end of
5769 the output context line. The program tries to fill those unused areas
5770 by wrapping around context in them; the tail of the input line or
5771 sentence is used to fill the unused area on the left of the output line;
5772 the head of the input line or sentence is used to fill the unused area
5773 on the right of the output line.
5775 As a matter of convenience to the user, many usual backslashed escape
5776 sequences from the C language are recognized and converted to the
5777 corresponding characters by @command{ptx} itself.
5779 @item -W @var{regexp}
5780 @itemx --word-regexp=@var{regexp}
5782 @opindex --word-regexp
5784 This option selects which regular expression will describe each keyword.
5785 By default, if GNU extensions are enabled, a word is a sequence of
5786 letters; the @var{regexp} used is @samp{\w+}. When GNU extensions are
5787 disabled, a word is by default anything which ends with a space, a tab
5788 or a newline; the @var{regexp} used is @samp{[^ \t\n]+}.
5790 An empty @var{regexp} is equivalent to not using this option.
5791 @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
5794 As a matter of convenience to the user, many usual backslashed escape
5795 sequences, as found in the C language, are recognized and converted to
5796 the corresponding characters by @command{ptx} itself.
5801 @node Output formatting in ptx
5802 @subsection Output formatting
5804 Output format is mainly controlled by the @option{-O} and @option{-T} options
5805 described in the table below. When neither @option{-O} nor @option{-T} are
5806 selected, and if GNU extensions are enabled, the program chooses an
5807 output format suitable for a dumb terminal. Each keyword occurrence is
5808 output to the center of one line, surrounded by its left and right
5809 contexts. Each field is properly justified, so the concordance output
5810 can be readily observed. As a special feature, if automatic
5811 references are selected by option @option{-A} and are output before the
5812 left context, that is, if option @option{-R} is @emph{not} selected, then
5813 a colon is added after the reference; this nicely interfaces with GNU
5814 Emacs @code{next-error} processing. In this default output format, each
5815 white space character, like newline and tab, is merely changed to
5816 exactly one space, with no special attempt to compress consecutive
5817 spaces. This might change in the future. Except for those white space
5818 characters, every other character of the underlying set of 256
5819 characters is transmitted verbatim.
5821 Output format is further controlled by the following options.
5825 @item -g @var{number}
5826 @itemx --gap-size=@var{number}
5830 Select the size of the minimum white space gap between the fields on the
5833 @item -w @var{number}
5834 @itemx --width=@var{number}
5838 Select the maximum output width of each final line. If references are
5839 used, they are included or excluded from the maximum output width
5840 depending on the value of option @option{-R}@. If this option is not
5841 selected, that is, when references are output before the left context,
5842 the maximum output width takes into account the maximum length of all
5843 references. If this option is selected, that is, when references are
5844 output after the right context, the maximum output width does not take
5845 into account the space taken by references, nor the gap that precedes
5849 @itemx --auto-reference
5851 @opindex --auto-reference
5853 Select automatic references. Each input line will have an automatic
5854 reference made up of the file name and the line ordinal, with a single
5855 colon between them. However, the file name will be empty when standard
5856 input is being read. If both @option{-A} and @option{-r} are selected, then
5857 the input reference is still read and skipped, but the automatic
5858 reference is used at output time, overriding the input reference.
5861 @itemx --right-side-refs
5863 @opindex --right-side-refs
5865 In the default output format, when option @option{-R} is not used, any
5866 references produced by the effect of options @option{-r} or @option{-A} are
5867 placed to the far right of output lines, after the right context. With
5868 default output format, when the @option{-R} option is specified, references
5869 are rather placed at the beginning of each output line, before the left
5870 context. For any other output format, option @option{-R} is
5871 ignored, with one exception: with @option{-R} the width of references
5872 is @emph{not} taken into account in total output width given by @option{-w}.
5874 This option is automatically selected whenever GNU extensions are
5877 @item -F @var{string}
5878 @itemx --flag-truncation=@var{string}
5880 @opindex --flag-truncation
5882 This option will request that any truncation in the output be reported
5883 using the string @var{string}. Most output fields theoretically extend
5884 towards the beginning or the end of the current line, or current
5885 sentence, as selected with option @option{-S}@. But there is a maximum
5886 allowed output line width, changeable through option @option{-w}, which is
5887 further divided into space for various output fields. When a field has
5888 to be truncated because it cannot extend beyond the beginning or the end of
5889 the current line to fit in, then a truncation occurs. By default,
5890 the string used is a single slash, as in @option{-F /}.
5892 @var{string} may have more than one character, as in @option{-F @dots{}}.
5893 Also, in the particular case when @var{string} is empty (@option{-F ""}),
5894 truncation flagging is disabled, and no truncation marks are appended in
5897 As a matter of convenience to the user, many usual backslashed escape
5898 sequences, as found in the C language, are recognized and converted to
5899 the corresponding characters by @command{ptx} itself.
5901 @item -M @var{string}
5902 @itemx --macro-name=@var{string}
5904 @opindex --macro-name
5906 Select another @var{string} to be used instead of @samp{xx}, while
5907 generating output suitable for @command{nroff}, @command{troff} or @TeX{}.
5910 @itemx --format=roff
5912 @opindex --format=roff
5914 Choose an output format suitable for @command{nroff} or @command{troff}
5915 processing. Each output line will look like:
5918 .xx "@var{tail}" "@var{before}" "@var{keyword_and_after}"@c
5919 "@var{head}" "@var{ref}"
5922 so it will be possible to write a @samp{.xx} roff macro to take care of
5923 the output typesetting. This is the default output format when GNU
5924 extensions are disabled. Option @option{-M} can be used to change
5925 @samp{xx} to another macro name.
5927 In this output format, each non-graphical character, like newline and
5928 tab, is merely changed to exactly one space, with no special attempt to
5929 compress consecutive spaces. Each quote character @samp{"} is doubled
5930 so it will be correctly processed by @command{nroff} or @command{troff}.
5935 @opindex --format=tex
5937 Choose an output format suitable for @TeX{} processing. Each output
5938 line will look like:
5941 \xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@c
5942 @{@var{after}@}@{@var{head}@}@{@var{ref}@}
5946 so it will be possible to write a @code{\xx} definition to take care of
5947 the output typesetting. Note that when references are not being
5948 produced, that is, neither option @option{-A} nor option @option{-r} is
5949 selected, the last parameter of each @code{\xx} call is inhibited.
5950 Option @option{-M} can be used to change @samp{xx} to another macro
5953 In this output format, some special characters, like @samp{$}, @samp{%},
5954 @samp{&}, @samp{#} and @samp{_} are automatically protected with a
5955 backslash. Curly brackets @samp{@{}, @samp{@}} are protected with a
5956 backslash and a pair of dollar signs (to force mathematical mode). The
5957 backslash itself produces the sequence @code{\backslash@{@}}.
5958 Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and
5959 @code{~\@{ @}} respectively. Other diacriticized characters of the
5960 underlying character set produce an appropriate @TeX{} sequence as far
5961 as possible. The other non-graphical characters, like newline and tab,
5962 and all other characters which are not part of ASCII, are merely
5963 changed to exactly one space, with no special attempt to compress
5964 consecutive spaces. Let me know how to improve this special character
5965 processing for @TeX{}.
5970 @node Compatibility in ptx
5971 @subsection The GNU extensions to @command{ptx}
5973 This version of @command{ptx} contains a few features which do not exist in
5974 System V @command{ptx}. These extra features are suppressed by using the
5975 @option{-G} command line option, unless overridden by other command line
5976 options. Some GNU extensions cannot be recovered by overriding, so the
5977 simple rule is to avoid @option{-G} if you care about GNU extensions.
5978 Here are the differences between this program and System V @command{ptx}.
5983 This program can read many input files at once, it always writes the
5984 resulting concordance on standard output. On the other hand, System V
5985 @command{ptx} reads only one file and sends the result to standard output
5986 or, if a second @var{file} parameter is given on the command, to that
5989 Having output parameters not introduced by options is a dangerous
5990 practice which GNU avoids as far as possible. So, for using @command{ptx}
5991 portably between GNU and System V, you should always use it with a
5992 single input file, and always expect the result on standard output. You
5993 might also want to automatically configure in a @option{-G} option to
5994 @command{ptx} calls in products using @command{ptx}, if the configurator finds
5995 that the installed @command{ptx} accepts @option{-G}.
5998 The only options available in System V @command{ptx} are options @option{-b},
5999 @option{-f}, @option{-g}, @option{-i}, @option{-o}, @option{-r}, @option{-t} and
6000 @option{-w}. All other options are GNU extensions and are not repeated in
6001 this enumeration. Moreover, some options have a slightly different
6002 meaning when GNU extensions are enabled, as explained below.
6005 By default, concordance output is not formatted for @command{troff} or
6006 @command{nroff}. It is rather formatted for a dumb terminal. @command{troff}
6007 or @command{nroff} output may still be selected through option @option{-O}.
6010 Unless @option{-R} option is used, the maximum reference width is
6011 subtracted from the total output line width. With GNU extensions
6012 disabled, width of references is not taken into account in the output
6013 line width computations.
6016 All 256 bytes, even ASCII NUL bytes, are always read and
6017 processed from input file with no adverse effect, even if GNU extensions
6018 are disabled. However, System V @command{ptx} does not accept 8-bit
6019 characters, a few control characters are rejected, and the tilde
6020 @samp{~} is also rejected.
6023 Input line length is only limited by available memory, even if GNU
6024 extensions are disabled. However, System V @command{ptx} processes only
6025 the first 200 characters in each line.
6028 The break (non-word) characters default to be every character except all
6029 letters of the underlying character set, diacriticized or not. When GNU
6030 extensions are disabled, the break characters default to space, tab and
6034 The program makes better use of output line width. If GNU extensions
6035 are disabled, the program rather tries to imitate System V @command{ptx},
6036 but still, there are some slight disposition glitches this program does
6037 not completely reproduce.
6040 The user can specify both an Ignore file and an Only file. This is not
6041 allowed with System V @command{ptx}.
6046 @node tsort invocation
6047 @section @command{tsort}: Topological sort
6050 @cindex topological sort
6052 @command{tsort} performs a topological sort on the given @var{file}, or
6053 standard input if no input file is given or for a @var{file} of
6054 @samp{-}. For more details and some history, see @ref{tsort background}.
6058 tsort [@var{option}] [@var{file}]
6061 @command{tsort} reads its input as pairs of strings, separated by blanks,
6062 indicating a partial ordering. The output is a total ordering that
6063 corresponds to the given partial ordering.
6077 will produce the output
6088 Consider a more realistic example.
6089 You have a large set of functions all in one file, and they may all be
6090 declared static except one. Currently that one (say @code{main}) is the
6091 first function defined in the file, and the ones it calls directly follow
6092 it, followed by those they call, etc. Let's say that you are determined
6093 to take advantage of prototypes, so you have to choose between declaring
6094 all of those functions (which means duplicating a lot of information from
6095 the definitions) and rearranging the functions so that as many as possible
6096 are defined before they are used. One way to automate the latter process
6097 is to get a list for each function of the functions it calls directly.
6098 Many programs can generate such lists. They describe a call graph.
6099 Consider the following list, in which a given line indicates that the
6100 function on the left calls the one on the right directly.
6106 tail_file pretty_name
6107 tail_file write_header
6109 tail_forever recheck
6110 tail_forever pretty_name
6111 tail_forever write_header
6112 tail_forever dump_remainder
6115 tail_lines start_lines
6116 tail_lines dump_remainder
6117 tail_lines file_lines
6118 tail_lines pipe_lines
6120 tail_bytes start_bytes
6121 tail_bytes dump_remainder
6122 tail_bytes pipe_bytes
6123 file_lines dump_remainder
6127 then you can use @command{tsort} to produce an ordering of those
6128 functions that satisfies your requirement.
6131 example$ tsort call-graph | tac
6151 @command{tsort} detects any cycles in the input and writes the first cycle
6152 encountered to standard error.
6154 Note that for a given partial ordering, generally there is no unique
6155 total ordering. In the context of the call graph above, the function
6156 @code{parse_options} may be placed anywhere in the list as long as it
6157 precedes @code{main}.
6159 The only options are @option{--help} and @option{--version}. @xref{Common
6165 * tsort background:: Where tsort came from.
6168 @node tsort background
6169 @subsection @command{tsort}: Background
6171 @command{tsort} exists because very early versions of the Unix linker processed
6172 an archive file exactly once, and in order. As @command{ld} read each object
6173 in the archive, it decided whether it was needed in the program based on
6174 whether it defined any symbols which were undefined at that point in
6177 This meant that dependencies within the archive had to be handled
6178 specially. For example, @code{scanf} probably calls @code{read}. That means
6179 that in a single pass through an archive, it was important for @code{scanf.o}
6180 to appear before read.o, because otherwise a program which calls
6181 @code{scanf} but not @code{read} might end up with an unexpected unresolved
6182 reference to @code{read}.
6184 The way to address this problem was to first generate a set of
6185 dependencies of one object file on another. This was done by a shell
6186 script called @command{lorder}. The GNU tools don't provide a version of
6187 lorder, as far as I know, but you can still find it in BSD
6190 Then you ran @command{tsort} over the @command{lorder} output, and you used the
6191 resulting sort to define the order in which you added objects to the archive.
6193 This whole procedure has been obsolete since about 1980, because
6194 Unix archives now contain a symbol table (traditionally built by
6195 @command{ranlib}, now generally built by @command{ar} itself), and the Unix
6196 linker uses the symbol table to effectively make multiple passes over
6199 Anyhow, that's where tsort came from. To solve an old problem with
6200 the way the linker handled archive files, which has since been solved
6204 @node Operating on fields
6205 @chapter Operating on fields
6208 * cut invocation:: Print selected parts of lines.
6209 * paste invocation:: Merge lines of files.
6210 * join invocation:: Join lines on a common field.
6214 @node cut invocation
6215 @section @command{cut}: Print selected parts of lines
6218 @command{cut} writes to standard output selected parts of each line of each
6219 input file, or standard input if no files are given or for a file name of
6223 cut @var{option}@dots{} [@var{file}]@dots{}
6226 In the table which follows, the @var{byte-list}, @var{character-list},
6227 and @var{field-list} are one or more numbers or ranges (two numbers
6228 separated by a dash) separated by commas. Bytes, characters, and
6229 fields are numbered starting at 1. Incomplete ranges may be
6230 given: @option{-@var{m}} means @samp{1-@var{m}}; @samp{@var{n}-} means
6231 @samp{@var{n}} through end of line or last field. The list elements
6232 can be repeated, can overlap, and can be specified in any order; but
6233 the selected input is written in the same order that it is read, and
6234 is written exactly once.
6236 The program accepts the following options. Also see @ref{Common
6241 @item -b @var{byte-list}
6242 @itemx --bytes=@var{byte-list}
6245 Select for printing only the bytes in positions listed in
6246 @var{byte-list}. Tabs and backspaces are treated like any other
6247 character; they take up 1 byte. If an output delimiter is specified,
6248 (see the description of @option{--output-delimiter}), then output that
6249 string between ranges of selected bytes.
6251 @item -c @var{character-list}
6252 @itemx --characters=@var{character-list}
6254 @opindex --characters
6255 Select for printing only the characters in positions listed in
6256 @var{character-list}. The same as @option{-b} for now, but
6257 internationalization will change that. Tabs and backspaces are
6258 treated like any other character; they take up 1 character. If an
6259 output delimiter is specified, (see the description of
6260 @option{--output-delimiter}), then output that string between ranges
6263 @item -f @var{field-list}
6264 @itemx --fields=@var{field-list}
6267 Select for printing only the fields listed in @var{field-list}.
6268 Fields are separated by a TAB character by default. Also print any
6269 line that contains no delimiter character, unless the
6270 @option{--only-delimited} (@option{-s}) option is specified.
6272 Note @command{awk} supports more sophisticated field processing,
6273 like reordering fields, and handling fields aligned with blank characters.
6274 By default @command{awk} uses (and discards) runs of blank characters
6275 to separate fields, and ignores leading and trailing blanks.
6278 awk '{print $2}' # print the second field
6279 awk '{print $(NF-1)}' # print the penultimate field
6280 awk '{print $2,$1}' # reorder the first two fields
6283 Note while @command{cut} accepts field specifications in
6284 arbitrary order, output is always in the order encountered in the file.
6286 In the unlikely event that @command{awk} is unavailable,
6287 one can use the @command{join} command, to process blank
6288 characters as @command{awk} does above.
6291 join -a1 -o 1.2 - /dev/null # print the second field
6292 join -a1 -o 1.2,1.1 - /dev/null # reorder the first two fields
6296 @item -d @var{input_delim_byte}
6297 @itemx --delimiter=@var{input_delim_byte}
6299 @opindex --delimiter
6300 With @option{-f}, use the first byte of @var{input_delim_byte} as
6301 the input fields separator (default is TAB).
6305 Do not split multi-byte characters (no-op for now).
6308 @itemx --only-delimited
6310 @opindex --only-delimited
6311 For @option{-f}, do not print lines that do not contain the field separator
6312 character. Normally, any line without a field separator is printed verbatim.
6314 @item --output-delimiter=@var{output_delim_string}
6315 @opindex --output-delimiter
6316 With @option{-f}, output fields are separated by @var{output_delim_string}.
6317 The default with @option{-f} is to use the input delimiter.
6318 When using @option{-b} or @option{-c} to select ranges of byte or
6319 character offsets (as opposed to ranges of fields),
6320 output @var{output_delim_string} between non-overlapping
6321 ranges of selected bytes.
6324 @opindex --complement
6325 This option is a GNU extension.
6326 Select for printing the complement of the bytes, characters or fields
6327 selected with the @option{-b}, @option{-c} or @option{-f} options.
6328 In other words, do @emph{not} print the bytes, characters or fields
6329 specified via those options. This option is useful when you have
6330 many fields and want to print all but a few of them.
6339 @node paste invocation
6340 @section @command{paste}: Merge lines of files
6343 @cindex merging files
6345 @command{paste} writes to standard output lines consisting of sequentially
6346 corresponding lines of each given file, separated by a TAB character.
6347 Standard input is used for a file name of @samp{-} or if no input files
6353 paste [@var{option}]@dots{} [@var{file}]@dots{}
6367 Take lines sequentially from each file:
6375 Duplicate lines from a file:
6377 $ paste num2 let3 num2
6383 Intermix lines from standard input:
6385 $ paste - let3 - < num2
6391 Join consecutive lines with a space:
6393 $ seq 4 | paste -d ' ' - -
6398 The program accepts the following options. Also see @ref{Common options}.
6406 Paste the lines of one file at a time rather than one line from each
6407 file. Using the above example data:
6410 $ paste -s num2 let3
6415 @item -d @var{delim-list}
6416 @itemx --delimiters=@var{delim-list}
6418 @opindex --delimiters
6419 Consecutively use the characters in @var{delim-list} instead of
6420 TAB to separate merged lines. When @var{delim-list} is
6421 exhausted, start again at its beginning. Using the above example data:
6424 $ paste -d '%_' num2 let3 num2
6437 @node join invocation
6438 @section @command{join}: Join lines on a common field
6441 @cindex common field, joining on
6443 @command{join} writes to standard output a line for each pair of input
6444 lines that have identical join fields. Synopsis:
6447 join [@var{option}]@dots{} @var{file1} @var{file2}
6450 Either @var{file1} or @var{file2} (but not both) can be @samp{-},
6451 meaning standard input. @var{file1} and @var{file2} should be
6452 sorted on the join fields.
6474 @command{join}'s default behavior (when no options are given):
6476 @item the join field is the first field in each line;
6477 @item fields in the input are separated by one or more blanks, with leading
6478 blanks on the line ignored;
6479 @item fields in the output are separated by a space;
6480 @item each output line consists of the join field, the remaining
6481 fields from @var{file1}, then the remaining fields from @var{file2}.
6486 * General options in join:: Options which affect general program behavior.
6487 * Sorting files for join:: Using @command{sort} before @command{join}.
6488 * Working with fields:: Joining on different fields.
6489 * Paired and unpaired lines:: Controlling @command{join}'s field matching.
6490 * Header lines:: Working with header lines in files.
6491 * Set operations:: Union, Intersection and Difference of files.
6494 @node General options in join
6495 @subsection General options
6496 The program accepts the following options. Also see @ref{Common options}.
6500 @item -a @var{file-number}
6502 Print a line for each unpairable line in file @var{file-number} (either
6503 @samp{1} or @samp{2}), in addition to the normal output.
6506 Fail with an error message if either input file is wrongly ordered.
6508 @item --nocheck-order
6509 Do not check that both input files are in sorted order. This is the default.
6511 @item -e @var{string}
6513 Replace those output fields that are missing in the input with @var{string}.
6514 I.e., missing fields specified with the @option{-12jo} options.
6518 Treat the first line of each input file as a header line. The header lines
6519 will be joined and printed as the first output line. If @option{-o} is used to
6520 specify output format, the header line will be printed according to the
6521 specified format. The header lines will not be checked for ordering even if
6522 @option{--check-order} is specified. Also if the header lines from each file
6523 do not match, the heading fields from the first file will be used.
6526 @itemx --ignore-case
6528 @opindex --ignore-case
6529 Ignore differences in case when comparing keys.
6530 With this option, the lines of the input files must be ordered in the same way.
6531 Use @samp{sort -f} to produce this ordering.
6533 @item -1 @var{field}
6535 Join on field @var{field} (a positive integer) of file 1.
6537 @item -2 @var{field}
6539 Join on field @var{field} (a positive integer) of file 2.
6541 @item -j @var{field}
6542 Equivalent to @option{-1 @var{field} -2 @var{field}}.
6544 @item -o @var{field-list}
6546 If the keyword @samp{auto} is specified, infer the output format from
6547 the first line in each file. This is the same as the default output format
6548 but also ensures the same number of fields are output for each line.
6549 Missing fields are replaced with the @option{-e} option and extra fields
6552 Otherwise, construct each output line according to the format in
6553 @var{field-list}. Each element in @var{field-list} is either the single
6554 character @samp{0} or has the form @var{m.n} where the file number, @var{m},
6555 is @samp{1} or @samp{2} and @var{n} is a positive field number.
6557 A field specification of @samp{0} denotes the join field.
6558 In most cases, the functionality of the @samp{0} field spec
6559 may be reproduced using the explicit @var{m.n} that corresponds
6560 to the join field. However, when printing unpairable lines
6561 (using either of the @option{-a} or @option{-v} options), there is no way
6562 to specify the join field using @var{m.n} in @var{field-list}
6563 if there are unpairable lines in both files.
6564 To give @command{join} that functionality, POSIX invented the @samp{0}
6565 field specification notation.
6567 The elements in @var{field-list}
6568 are separated by commas or blanks.
6569 Blank separators typically need to be quoted for the shell. For
6570 example, the commands @samp{join -o 1.2,2.2} and @samp{join -o '1.2
6571 2.2'} are equivalent.
6573 All output lines -- including those printed because of any @option{-a}
6574 or @option{-v} option -- are subject to the specified @var{field-list}.
6577 Use character @var{char} as the input and output field separator.
6578 Treat as significant each occurrence of @var{char} in the input file.
6579 Use @samp{sort -t @var{char}}, without the @option{-b} option of
6580 @samp{sort}, to produce this ordering. If @samp{join -t ''} is specified,
6581 the whole line is considered, matching the default operation of sort.
6582 If @samp{-t '\0'} is specified then the ASCII NUL
6583 character is used to delimit the fields.
6585 @item -v @var{file-number}
6586 Print a line for each unpairable line in file @var{file-number}
6587 (either @samp{1} or @samp{2}), instead of the normal output.
6590 @newlineFieldSeparator
6597 @checkOrderOption{join}
6602 @node Sorting files for join
6603 @subsection Pre-sorting
6605 @command{join} requires sorted input files. Each input file should be
6606 sorted according to the key (=field/column number) used in
6607 @command{join}. The recommended sorting option is @samp{sort -k 1b,1}
6608 (assuming the desired key is in the first column).
6610 @noindent Typical usage:
6613 $ sort -k 1b,1 file1 > file1.sorted
6614 $ sort -k 1b,1 file2 > file2.sorted
6615 $ join file1.sorted file2.sorted > file3
6620 Normally, the sort order is that of the
6621 collating sequence specified by the @env{LC_COLLATE} locale. Unless
6622 the @option{-t} option is given, the sort comparison ignores blanks at
6623 the start of the join field, as in @code{sort -b}. If the
6624 @option{--ignore-case} option is given, the sort comparison ignores
6625 the case of characters in the join field, as in @code{sort -f}:
6629 $ sort -k 1bf,1 file1 > file1.sorted
6630 $ sort -k 1bf,1 file2 > file2.sorted
6631 $ join --ignore-case file1.sorted file2.sorted > file3
6635 The @command{sort} and @command{join} commands should use consistent
6636 locales and options if the output of @command{sort} is fed to
6637 @command{join}. You can use a command like @samp{sort -k 1b,1} to
6638 sort a file on its default join field, but if you select a non-default
6639 locale, join field, separator, or comparison options, then you should
6640 do so consistently between @command{join} and @command{sort}.
6642 @noindent To avoid any locale-related issues, it is recommended to use the
6643 @samp{C} locale for both commands:
6647 $ LC_ALL=C sort -k 1b,1 file1 > file1.sorted
6648 $ LC_ALL=C sort -k 1b,1 file2 > file2.sorted
6649 $ LC_ALL=C join file1.sorted file2.sorted > file3
6654 @node Working with fields
6655 @subsection Working with fields
6657 Use @option{-1},@option{-2} to set the key fields for each of the input files.
6658 Ensure the preceding @command{sort} commands operated on the same fields.
6661 The following example joins two files, using the values from seventh field
6662 of the first file and the third field of the second file:
6666 $ sort -k 7b,7 file1 > file1.sorted
6667 $ sort -k 3b,3 file2 > file2.sorted
6668 $ join -1 7 -2 3 file1.sorted file2.sorted > file3
6673 If the field number is the same for both files, use @option{-j}:
6677 $ sort -k4b,4 file1 > file1.sorted
6678 $ sort -k4b,4 file2 > file2.sorted
6679 $ join -j4 file1.sorted file2.sorted > file3
6684 Both @command{sort} and @command{join} operate of whitespace-delimited
6685 fields. To specify a different delimiter, use @option{-t} in @emph{both}:
6689 $ sort -t, -k3b,3 file1 > file1.sorted
6690 $ sort -t, -k3b,3 file2 > file2.sorted
6691 $ join -t, -j3 file1.sorted file2.sorted > file3
6696 To specify a tab (@sc{ascii} 0x09) character instead of whitespace,
6697 use:@footnote{the @code{$'\t'} is supported in most modern shells.
6698 For older shells, use a literal tab.}
6702 $ sort -t$'\t' -k3b,3 file1 > file1.sorted
6703 $ sort -t$'\t' -k3b,3 file2 > file2.sorted
6704 $ join -t$'\t' -j3 file1.sorted file2.sorted > file3
6710 If @samp{join -t ''} is specified then the whole line is considered which
6711 matches the default operation of sort:
6715 $ sort file1 > file1.sorted
6716 $ sort file2 > file2.sorted
6717 $ join -t '' file1.sorted file2.sorted > file3
6722 @node Paired and unpaired lines
6723 @subsection Controlling @command{join}'s field matching
6725 In this section the @command{sort} commands are omitted for brevity.
6726 Sorting the files before joining is still required.
6728 @command{join}'s default behavior is to print only lines common to
6729 both input files. Use @option{-a} and @option{-v} to print unpairable lines
6730 from one or both files.
6733 All examples below use the following two (pre-sorted) input files:
6735 @multitable @columnfractions .5 .5
6752 @c TODO: Find better column widths that work for both HTML and PDF
6753 @c and disable indentation of @example.
6754 @multitable @columnfractions 0.5 0.5
6756 @headitem Command @tab Outcome
6766 (@emph{intersection})
6772 $ join -a 1 file1 file2
6777 common lines @emph{and} unpaired
6778 lines from the first file
6783 $ join -a 2 file1 file2
6788 common lines @emph{and} unpaired lines from the second file
6793 $ join -a 1 -a 2 file1 file2
6799 all lines (paired and unpaired) from both files
6802 see note below regarding @code{-o auto}.
6807 $ join -v 1 file1 file2
6811 unpaired lines from the first file
6817 $ join -v 2 file1 file2
6821 unpaired lines from the second file
6827 $ join -v 1 -v 2 file1 file2
6832 unpaired lines from both files, omitting common lines
6833 (@emph{symmetric difference}).
6839 The @option{-o auto -e X} options are useful when dealing with unpaired lines.
6840 The following example prints all lines (common and unpaired) from both files.
6841 Without @option{-o auto} it is not easy to discern which fields originate from
6845 $ join -a 1 -a 2 file1 file2
6850 $ join -o auto -e X -a 1 -a 2 file1 file2
6857 If the input has no unpairable lines, a GNU extension is
6858 available; the sort order can be any order that considers two fields
6859 to be equal if and only if the sort comparison described above
6860 considers them to be equal. For example:
6883 @subsection Header lines
6885 The @option{--header} option can be used when the files to join
6886 have a header line which is not sorted:
6900 $ join --header -o auto -e NA -a1 -a2 file1 file2
6909 To sort a file with a header line, use GNU @command{sed -u}.
6910 The following example sort the files but keeps the first line of each
6915 $ ( sed -u 1q ; sort -k2b,2 ) < file1 > file1.sorted
6916 $ ( sed -u 1q ; sort -k2b,2 ) < file2 > file2.sorted
6917 $ join --header -o auto -e NA -a1 -a2 file1.sorted file2.sorted > file3
6921 @node Set operations
6922 @subsection Union, Intersection and Difference of files
6924 Combine @command{sort}, @command{uniq} and @command{join} to
6925 perform the equivalent of set operations on files:
6927 @c From https://www.pixelbeat.org/cmdline.html#sets
6928 @multitable @columnfractions 0.5 0.5
6929 @headitem Command @tab outcome
6930 @item @code{sort -u file1 file2}
6931 @tab Union of unsorted files
6933 @item @code{sort file1 file2 | uniq -d}
6934 @tab Intersection of unsorted files
6936 @item @code{sort file1 file1 file2 | uniq -u}
6937 @tab Difference of unsorted files
6939 @item @code{sort file1 file2 | uniq -u}
6940 @tab Symmetric Difference of unsorted files
6942 @item @code{join -t '' -a1 -a2 file1 file2}
6943 @tab Union of sorted files
6945 @item @code{join -t '' file1 file2}
6946 @tab Intersection of sorted files
6948 @item @code{join -t '' -v2 file1 file2}
6949 @tab Difference of sorted files
6951 @item @code{join -t '' -v1 -v2 file1 file2}
6952 @tab Symmetric Difference of sorted files
6956 All examples above operate on entire lines and not on specific fields:
6957 @command{sort} without @option{-k} and @command{join -t ''} both consider
6958 entire lines as the key.
6961 @node Operating on characters
6962 @chapter Operating on characters
6964 @cindex operating on characters
6966 These commands operate on individual characters.
6969 * tr invocation:: Translate, squeeze, and/or delete characters.
6970 * expand invocation:: Convert tabs to spaces.
6971 * unexpand invocation:: Convert spaces to tabs.
6976 @section @command{tr}: Translate, squeeze, and/or delete characters
6983 tr [@var{option}]@dots{} @var{string1} [@var{string2}]
6986 @command{tr} copies standard input to standard output, performing
6987 one of the following operations:
6991 translate, and optionally squeeze repeated characters in the result,
6993 squeeze repeated characters,
6997 delete characters, then squeeze repeated characters from the result.
7000 The @var{string1} and @var{string2} operands define arrays of
7001 characters @var{array1} and @var{array2}. By default @var{array1}
7002 lists input characters that @command{tr} operates on, and @var{array2}
7003 lists corresponding translations. In some cases the second operand is
7006 The program accepts the following options. Also see @ref{Common options}.
7007 Options must precede operands.
7016 @opindex --complement
7017 Instead of @var{array1}, use its complement (all characters not
7018 specified by @var{string1}), in ascending order. Use this option with
7019 caution in multibyte locales where its meaning is not always clear
7020 or portable; see @ref{Character arrays}.
7026 Delete characters in @var{array1}; do not translate.
7029 @itemx --squeeze-repeats
7031 @opindex --squeeze-repeats
7032 Replace each sequence of a repeated character that is listed in
7033 the last specified @var{array}, with a single occurrence of that character.
7036 @itemx --truncate-set1
7038 @opindex --truncate-set1
7039 Truncate @var{array1} to the length of @var{array2}.
7047 * Character arrays:: Specifying arrays of characters.
7048 * Translating:: Changing characters to other characters.
7049 * Squeezing and deleting:: Removing characters.
7053 @node Character arrays
7054 @subsection Specifying arrays of characters
7056 @cindex arrays of characters in @command{tr}
7058 The @var{string1} and @var{string2} operands are not regular
7059 expressions, even though they may look similar. Instead, they
7060 merely represent arrays of characters. As a GNU extension to POSIX,
7061 an empty string operand represents an empty array of characters.
7063 The interpretation of @var{string1} and @var{string2} depends on locale.
7064 GNU @command{tr} fully supports only safe single-byte locales,
7065 where each possible input byte represents a single character.
7066 Unfortunately, this means GNU @command{tr} will not handle commands
7067 like @samp{tr @"o @L{}} the way you might expect,
7068 since (assuming a UTF-8 encoding) this is equivalent to
7069 @samp{tr '\303\266' '\305\201'} and GNU @command{tr} will
7070 simply transliterate all @samp{\303} bytes to @samp{\305} bytes, etc.
7071 POSIX does not clearly specify the behavior of @command{tr} in locales
7072 where characters are represented by byte sequences instead of by
7073 individual bytes, or where data might contain invalid bytes that are
7074 encoding errors. To avoid problems in this area, you can run
7075 @command{tr} in a safe single-byte locale by using a shell command
7076 like @samp{LC_ALL=C tr} instead of plain @command{tr}.
7078 Although most characters simply represent themselves in @var{string1}
7079 and @var{string2}, the strings can contain shorthands listed below,
7080 for convenience. Some shorthands can be used only in @var{string1} or
7081 @var{string2}, as noted below.
7085 @item Backslash escapes
7086 @cindex backslash escapes
7088 The following backslash escape sequences are recognized:
7092 Bell (BEL, Control-G).
7094 Backspace (BS, Control-H).
7096 Form feed (FF, Control-L).
7098 Newline (LF, Control-J).
7100 Carriage return (CR, Control-M).
7102 Tab (HT, Control-I).
7104 Vertical tab (VT, Control-K).
7106 The eight-bit byte with the value given by @var{ooo}, which is the longest
7107 sequence of one to three octal digits following the backslash.
7108 For portability, @var{ooo} should represent a value that fits in eight bits.
7109 As a GNU extension to POSIX, if the value would not fit, then only the
7110 first two digits of @var{ooo} are used, e.g., @samp{\400}
7111 is equivalent to @samp{\0400} and represents a two-byte sequence.
7116 It is an error if no character follows an unescaped backslash.
7117 As a GNU extension, a backslash followed by a character not listed
7118 above is interpreted as that character, removing any special
7119 significance; this can be used to escape the characters
7120 @samp{[} and @samp{-} when they would otherwise be special.
7125 The notation @samp{@var{m}-@var{n}} expands to the characters
7126 from @var{m} through @var{n}, in ascending order. @var{m} should
7127 not collate after @var{n}; if it does, an error results. As an example,
7128 @samp{0-9} is the same as @samp{0123456789}.
7130 GNU @command{tr} does not support the System V syntax that uses square
7131 brackets to enclose ranges. Translations specified in that format
7132 sometimes work as expected, since the brackets are often transliterated
7133 to themselves. However, they should be avoided because they sometimes
7134 behave unexpectedly. For example, @samp{tr -d '[0-9]'} deletes brackets
7137 Many historically common and even accepted uses of ranges are not fully
7138 portable. For example, on EBCDIC hosts using the @samp{A-Z}
7139 range will not do what most would expect because @samp{A} through @samp{Z}
7140 are not contiguous as they are in ASCII@.
7141 One way to work around this is to use character classes (see below).
7142 Otherwise, it is most portable (and most ugly) to enumerate the members
7145 @item Repeated characters
7146 @cindex repeated characters
7148 The notation @samp{[@var{c}*@var{n}]} in @var{string2} expands to @var{n}
7149 copies of character @var{c}. Thus, @samp{[y*6]} is the same as
7150 @samp{yyyyyy}. The notation @samp{[@var{c}*]} in @var{string2} expands
7151 to as many copies of @var{c} as are needed to make @var{array2} as long as
7152 @var{array1}. If @var{n} begins with @samp{0}, it is interpreted in
7153 octal, otherwise in decimal. A zero-valued @var{n} is treated as if
7156 @item Character classes
7157 @cindex character classes
7159 The notation @samp{[:@var{class}:]} expands to all characters in
7160 the (predefined) class @var{class}. When the @option{--delete} (@option{-d})
7161 and @option{--squeeze-repeats} (@option{-s}) options are both given, any
7162 character class can be used in @var{string2}. Otherwise, only the
7163 character classes @code{lower} and @code{upper} are accepted in
7164 @var{string2}, and then only if the corresponding character class
7165 (@code{upper} and @code{lower}, respectively) is specified in the same
7166 relative position in @var{string1}. Doing this specifies case conversion.
7167 Except for case conversion, a class's characters appear in no particular order.
7168 The class names are given below; an error results when an invalid class
7180 Horizontal whitespace.
7189 Printable characters, not including space.
7195 Printable characters, including space.
7198 Punctuation characters.
7201 Horizontal or vertical whitespace.
7210 @item Equivalence classes
7211 @cindex equivalence classes
7213 The syntax @samp{[=@var{c}=]} expands to all characters equivalent to
7214 @var{c}, in no particular order. These equivalence classes are
7215 allowed in @var{string2} only when @option{--delete} (@option{-d}) and
7216 @option{--squeeze-repeats} @option{-s} are both given.
7218 Although equivalence classes are intended to support non-English alphabets,
7219 there seems to be no standard way to define them or determine their
7220 contents. Therefore, they are not fully implemented in GNU @command{tr};
7221 each character's equivalence class consists only of that character,
7222 which is of no particular use.
7228 @subsection Translating
7230 @cindex translating characters
7232 @command{tr} performs translation when @var{string1} and @var{string2} are
7233 both given and the @option{--delete} (@option{-d}) option is not given.
7234 @command{tr} translates each character of its input that is in @var{array1}
7235 to the corresponding character in @var{array2}. Characters not in
7236 @var{array1} are passed through unchanged.
7238 As a GNU extension to POSIX, when a character appears more than once
7239 in @var{array1}, only the final instance is used. For example, these
7240 two commands are equivalent:
7247 A common use of @command{tr} is to convert lowercase characters to
7248 uppercase. This can be done in many ways. Here are three of them:
7251 tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
7253 tr '[:lower:]' '[:upper:]'
7257 However, ranges like @code{a-z} are not portable outside the C locale.
7259 When @command{tr} is performing translation, @var{array1} and @var{array2}
7260 typically have the same length. If @var{array1} is shorter than
7261 @var{array2}, the extra characters at the end of @var{array2} are ignored.
7263 On the other hand, making @var{array1} longer than @var{array2} is not
7264 portable; POSIX says that the result is undefined. In this situation,
7265 BSD @command{tr} pads @var{array2} to the length of @var{array1} by repeating
7266 the last character of @var{array2} as many times as necessary. System V
7267 @command{tr} truncates @var{array1} to the length of @var{array2}.
7269 By default, GNU @command{tr} handles this case like BSD @command{tr}.
7270 When the @option{--truncate-set1} (@option{-t}) option is given,
7271 GNU @command{tr} handles this case like the System V @command{tr}
7272 instead. This option is ignored for operations other than translation.
7274 Acting like System V @command{tr} in this case breaks the relatively common
7278 tr -cs A-Za-z0-9 '\012'
7282 because it converts only zero bytes (the first element in the
7283 complement of @var{array1}), rather than all non-alphanumerics, to
7287 By the way, the above idiom is not portable because it uses ranges, and
7288 it assumes that the octal code for newline is 012. Here is a better
7292 tr -cs '[:alnum:]' '[\n*]'
7296 @node Squeezing and deleting
7297 @subsection Squeezing repeats and deleting
7299 @cindex squeezing repeat characters
7300 @cindex deleting characters
7301 @cindex removing characters
7303 When given just the @option{--delete} (@option{-d}) option, @command{tr}
7304 removes any input characters that are in @var{array1}.
7306 When given just the @option{--squeeze-repeats} (@option{-s}) option
7307 and not translating, @command{tr} replaces each input sequence of a
7308 repeated character that is in @var{array1} with a single occurrence of
7311 When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr}
7312 first performs any deletions using @var{array1}, then squeezes repeats
7313 from any remaining characters using @var{array2}.
7315 The @option{--squeeze-repeats} option may also be used when translating,
7316 in which case @command{tr} first performs translation, then squeezes
7317 repeats from any remaining characters using @var{array2}.
7319 Here are some examples to illustrate various combinations of options:
7324 Remove all zero bytes:
7331 Put all words on lines by themselves. This converts all
7332 non-alphanumeric characters to newlines, then squeezes each string
7333 of repeated newlines into a single newline:
7336 tr -cs '[:alnum:]' '[\n*]'
7340 Convert each sequence of repeated newlines to a single newline.
7341 I.e., delete empty lines:
7348 Find doubled occurrences of words in a document.
7349 @c Separate the following two "the"s, so typo checkers don't complain.
7350 For example, people often write ``the @w{}the'' with the repeated words
7351 separated by a newline. The Bourne shell script below works first
7352 by converting each sequence of punctuation and blank characters to a
7353 single newline. That puts each ``word'' on a line by itself.
7354 Next it maps all uppercase characters to lower case, and finally it
7355 runs @command{uniq} with the @option{-d} option to print out only the words
7361 | tr -s '[:punct:][:blank:]' '[\n*]' \
7362 | tr '[:upper:]' '[:lower:]' \
7367 Deleting a small set of characters is usually straightforward. For example,
7368 to remove all @samp{a}s, @samp{x}s, and @samp{M}s you would do this:
7374 However, when @samp{-} is one of those characters, it can be tricky because
7375 @samp{-} has special meanings. Performing the same task as above but also
7376 removing all @samp{-} characters, we might try @code{tr -d -axM}, but
7377 that would fail because @command{tr} would try to interpret @option{-a} as
7378 a command-line option. Alternatively, we could try putting the hyphen
7379 inside the string, @code{tr -d a-xM}, but that wouldn't work either because
7380 it would make @command{tr} interpret @code{a-x} as the range of characters
7381 @samp{a}@dots{}@samp{x} rather than the three.
7382 One way to solve the problem is to put the hyphen at the end of the list
7389 Or you can use @samp{--} to terminate option processing:
7398 @node expand invocation
7399 @section @command{expand}: Convert tabs to spaces
7402 @cindex tabs to spaces, converting
7403 @cindex converting tabs to spaces
7405 @command{expand} writes the contents of each given @var{file}, or standard
7406 input if none are given or for a @var{file} of @samp{-}, to standard
7407 output, with tab characters converted to the appropriate number of
7411 expand [@var{option}]@dots{} [@var{file}]@dots{}
7414 By default, @command{expand} converts all tabs to spaces. It preserves
7415 backspace characters in the output; they decrement the column count for
7416 tab calculations. The default action is equivalent to @option{-t 8} (set
7417 tabs every 8 columns).
7419 The program accepts the following options. Also see @ref{Common options}.
7423 @item -t @var{tab1}[,@var{tab2}]@dots{}
7424 @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
7427 @cindex tab stops, setting
7428 If only one tab stop is given, set the tabs @var{tab1} spaces apart
7429 (default is 8). Otherwise, set the tabs at columns @var{tab1},
7430 @var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the
7431 last tab stop given with single spaces.
7432 @macro gnuExpandTabs
7433 Tab stops can be separated by blanks as well as by commas.
7435 As a GNU extension the last @var{tab} specified can be prefixed
7436 with a @samp{/} to indicate a tab size to use for remaining positions.
7437 For example, @option{--tabs=2,4,/8} will set tab stops at position 2 and 4,
7438 and every multiple of 8 after that.
7440 Also the last @var{tab} specified can be prefixed with a @samp{+} to indicate
7441 a tab size to use for remaining positions, offset from the final explicitly
7443 For example, to ignore the 1 character gutter present in diff output,
7444 one can specify a 1 character offset using @option{--tabs=1,+8},
7445 which will set tab stops at positions 1,9,17,@dots{}
7450 For compatibility, GNU @command{expand} also accepts the obsolete
7451 option syntax, @option{-@var{t1}[,@var{t2}]@dots{}}. New scripts
7452 should use @option{-t @var{t1}[,@var{t2}]@dots{}} instead.
7458 @cindex initial tabs, converting
7459 Only convert initial tabs (those that precede all non-space or non-tab
7460 characters) on each line to spaces.
7467 @node unexpand invocation
7468 @section @command{unexpand}: Convert spaces to tabs
7472 @command{unexpand} writes the contents of each given @var{file}, or
7473 standard input if none are given or for a @var{file} of @samp{-}, to
7474 standard output, converting blanks at the beginning of each line into
7475 as many tab characters as needed. In the default POSIX
7476 locale, a @dfn{blank} is a space or a tab; other locales may specify
7477 additional blank characters. Synopsis:
7480 unexpand [@var{option}]@dots{} [@var{file}]@dots{}
7483 By default, @command{unexpand} converts only initial blanks (those
7484 that precede all non-blank characters) on each line. It
7485 preserves backspace characters in the output; they decrement the column
7486 count for tab calculations. By default, tabs are set at every 8th
7489 The program accepts the following options. Also see @ref{Common options}.
7493 @item -t @var{tab1}[,@var{tab2}]@dots{}
7494 @itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
7497 If only one tab stop is given, set the tabs @var{tab1} columns apart
7498 instead of the default 8. Otherwise, set the tabs at columns
7499 @var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave blanks
7500 beyond the tab stops given unchanged.
7503 This option implies the @option{-a} option.
7505 For compatibility, GNU @command{unexpand} supports the obsolete option syntax,
7506 @option{-@var{tab1}[,@var{tab2}]@dots{}}, where tab stops must be
7507 separated by commas. (Unlike @option{-t}, this obsolete option does
7508 not imply @option{-a}.) New scripts should use @option{--first-only -t
7509 @var{tab1}[,@var{tab2}]@dots{}} instead.
7515 Also convert all sequences of two or more blanks just before a tab stop,
7516 even if they occur after non-blank characters in a line.
7523 @node Directory listing
7524 @chapter Directory listing
7526 This chapter describes the @command{ls} command and its variants @command{dir}
7527 and @command{vdir}, which list information about files.
7530 * ls invocation:: List directory contents.
7531 * dir invocation:: Briefly ls.
7532 * vdir invocation:: Verbosely ls.
7533 * dircolors invocation:: Color setup for ls, etc.
7538 @section @command{ls}: List directory contents
7541 @cindex directory listing
7543 The @command{ls} program lists information about files (of any type,
7544 including directories). Options and file arguments can be intermixed
7545 arbitrarily, as usual. Later options override earlier options that
7548 For non-option command-line arguments that are directories, by default
7549 @command{ls} lists the contents of directories, not recursively, and
7550 omitting files with names beginning with @samp{.}. For other non-option
7551 arguments, by default @command{ls} lists just the file name. If no
7552 non-option argument is specified, @command{ls} operates on the current
7553 directory, acting as if it had been invoked with a single argument of @samp{.}.
7556 By default, the output is sorted alphabetically, according to the locale
7557 settings in effect.@footnote{If you use a non-POSIX
7558 locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may
7559 produce output that is sorted differently than you're accustomed to.
7560 In that case, set the @env{LC_ALL} environment variable to @samp{C}.}
7561 If standard output is
7562 a terminal, the output is in columns (sorted vertically) and control
7563 characters are output as question marks; otherwise, the output is listed
7564 one per line and control characters are output as-is.
7566 Because @command{ls} is such a fundamental program, it has accumulated many
7567 options over the years. They are described in the subsections below;
7568 within each section, options are listed alphabetically (ignoring case).
7569 The division of options into the subsections is not absolute, since some
7570 options affect more than one aspect of @command{ls}'s operation.
7572 @cindex exit status of @command{ls}
7577 1 minor problems (e.g., failure to access a file or directory not
7578 specified as a command line argument. This happens when listing a
7579 directory in which entries are actively being removed or renamed.)
7580 2 serious trouble (e.g., memory exhausted, invalid option, failure
7581 to access a file or directory specified as a command line argument
7582 or a directory loop)
7585 Also see @ref{Common options}.
7588 * Which files are listed::
7589 * What information is listed::
7590 * Sorting the output::
7591 * General output formatting::
7592 * Formatting file timestamps::
7593 * Formatting the file names::
7597 @node Which files are listed
7598 @subsection Which files are listed
7600 These options determine which files @command{ls} lists information for.
7601 By default, @command{ls} lists files and the contents of any
7602 directories on the command line, except that in directories it ignores
7603 files whose names start with @samp{.}.
7611 In directories, do not ignore file names that start with @samp{.}.
7616 @opindex --almost-all
7617 In directories, do not ignore all file names that start with @samp{.};
7618 ignore only @file{.} and @file{..}. The @option{--all} (@option{-a})
7619 option overrides this option.
7622 @itemx --ignore-backups
7624 @opindex --ignore-backups
7625 @cindex backup files, ignoring
7626 In directories, ignore files that end with @samp{~}. This option is
7627 equivalent to @samp{--ignore='*~' --ignore='.*~'}.
7632 @opindex --directory
7633 List just the names of directories, as with other types of files, rather
7634 than listing their contents.
7635 @c The following sentence is the same as the one for -F.
7636 Do not follow symbolic links listed on the
7637 command line unless the @option{--dereference-command-line} (@option{-H}),
7638 @option{--dereference} (@option{-L}), or
7639 @option{--dereference-command-line-symlink-to-dir} options are specified.
7642 @itemx --dereference-command-line
7644 @opindex --dereference-command-line
7645 @cindex symbolic links, dereferencing
7646 If a command line argument specifies a symbolic link, show information
7647 for the file the link references rather than for the link itself.
7649 @item --dereference-command-line-symlink-to-dir
7650 @opindex --dereference-command-line-symlink-to-dir
7651 @cindex symbolic links, dereferencing
7652 Do not dereference symbolic links, with one exception:
7653 if a command line argument specifies a symbolic link that refers to
7654 a directory, show information for that directory rather than for the
7656 This is the default behavior unless long format is being used
7657 or any of the following options is in effect:
7658 @option{--classify} (@option{-F}),
7659 @option{--directory} (@option{-d}),
7660 @option{--dereference} (@option{-L}), or
7661 @option{--dereference-command-line} (@option{-H})).
7663 @item --group-directories-first
7664 @opindex --group-directories-first
7665 Group all the directories before the files and then sort the
7666 directories and the files separately using the selected sort key
7667 (see @option{--sort} option).
7668 That is, this option specifies a primary sort key,
7669 and the @option{--sort} option specifies a secondary key.
7670 However, any use of @option{--sort=none}
7671 (@option{-U}) disables this option altogether.
7673 @item --hide=PATTERN
7674 @opindex --hide=@var{pattern}
7675 In directories, ignore files whose names match the shell pattern
7676 @var{pattern}, unless the @option{--all} (@option{-a}) or
7677 @option{--almost-all} (@option{-A}) is also given. This
7678 option acts like @option{--ignore=@var{pattern}} except that it has no
7679 effect if @option{--all} (@option{-a}) or @option{--almost-all}
7680 (@option{-A}) is also given.
7682 This option can be useful in shell aliases. For example, if
7683 @command{lx} is an alias for @samp{ls --hide='*~'} and @command{ly} is
7684 an alias for @samp{ls --ignore='*~'}, then the command @samp{lx -A}
7685 lists the file @file{README~} even though @samp{ly -A} would not.
7687 @item -I @var{pattern}
7688 @itemx --ignore=@var{pattern}
7690 @opindex --ignore=@var{pattern}
7691 In directories, ignore files whose names match the shell pattern
7692 (not regular expression) @var{pattern}. As
7693 in the shell, an initial @samp{.} in a file name does not match a
7694 wildcard at the start of @var{pattern}. Sometimes it is useful
7695 to give this option several times. For example,
7698 $ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
7701 The first option ignores names of length 3 or more that start with @samp{.},
7702 the second ignores all two-character names that start with @samp{.}
7703 except @samp{..}, and the third ignores names that start with @samp{#}.
7706 @itemx --dereference
7708 @opindex --dereference
7709 @cindex symbolic links, dereferencing
7710 When showing file information for a symbolic link, show information
7711 for the file the link references rather than the link itself.
7712 However, even with this option, @command{ls} still prints the name
7713 of the link itself, not the name of the file that the link points to.
7718 @opindex --recursive
7719 @cindex recursive directory listing
7720 @cindex directory listing, recursive
7721 List the contents of all directories recursively.
7726 @node What information is listed
7727 @subsection What information is listed
7729 These options affect the information that @command{ls} displays. By
7730 default, only file names are shown.
7736 @cindex hurd, author, printing
7737 In long format, list each file's author.
7738 In GNU/Hurd, file authors can differ from their owners, but in other
7739 operating systems the two are the same.
7745 @cindex dired Emacs mode support
7746 Print an additional line after the main output:
7749 //DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{}
7753 The @var{begn} and @var{endn} are unsigned integers that record the
7754 byte position of the beginning and end of each file name in the output.
7755 This makes it easy for Emacs to find the names, even when they contain
7756 unusual characters such as space or newline, without fancy searching.
7758 If directories are being listed recursively via
7759 @option{--recursive} (@option{-R}), output a similar
7760 line with offsets for each subdirectory name:
7763 //SUBDIRED// @var{beg1} @var{end1} @dots{}
7766 Finally, output a line of the form:
7769 //DIRED-OPTIONS// --quoting-style=@var{word}
7773 where @var{word} is the quoting style (@pxref{Formatting the file names}).
7775 Here is an actual example:
7778 $ mkdir -p a/sub/deeper a/sub2
7780 $ touch a/sub/deeper/file
7781 $ ls -gloRF --dired a
7784 -rw-r--r-- 1 0 Jun 10 12:27 f1
7785 -rw-r--r-- 1 0 Jun 10 12:27 f2
7786 drwxr-xr-x 3 4096 Jun 10 12:27 sub/
7787 drwxr-xr-x 2 4096 Jun 10 12:27 sub2/
7791 drwxr-xr-x 2 4096 Jun 10 12:27 deeper/
7795 -rw-r--r-- 1 0 Jun 10 12:27 file
7799 //DIRED// 48 50 84 86 120 123 158 162 217 223 282 286
7800 //SUBDIRED// 2 3 167 172 228 240 290 296
7801 //DIRED-OPTIONS// --quoting-style=literal
7804 The pairs of offsets on the @samp{//DIRED//} line above delimit
7805 these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper},
7807 The offsets on the @samp{//SUBDIRED//} line delimit the following
7808 directory names: @file{a}, @file{a/sub}, @file{a/sub/deeper}, @file{a/sub2}.
7810 Here is an example of how to extract the fifth entry name, @samp{deeper},
7811 corresponding to the pair of offsets, 222 and 228:
7814 $ ls -gloRF --dired a > out
7815 $ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo
7819 Although the listing above includes a trailing slash
7820 for the @samp{deeper} entry, the offsets select the name without
7821 the trailing slash. However, if you invoke @command{ls} with @option{--dired}
7822 (@option{-D}) along with an option like
7823 @option{--escape} (@option{-b}) and operate
7824 on a file whose name contains special characters, the backslash
7829 $ ls -blog --dired 'a b'
7830 -rw-r--r-- 1 0 Jun 10 12:28 a\ b
7832 //DIRED-OPTIONS// --quoting-style=escape
7835 If you use a quoting style like @option{--quoting-style=c} (@option{-Q})
7836 that adds quote marks, then the offsets include the quote marks.
7837 So beware that the user may select the quoting style via the environment
7838 variable @env{QUOTING_STYLE}@. Hence, applications using @option{--dired}
7839 should either specify an explicit @option{--quoting-style=literal}
7840 (@option{-N}) option on the command line, or else be
7841 prepared to parse the escaped names.
7843 The @option{--dired} (@option{-D}) option has well-defined behavior
7844 only when long format is in effect and hyperlinks are disabled (e.g.,
7845 @option{--hyperlink=none}).
7848 @opindex --full-time
7849 Produce long format, and list times in full. It is
7850 equivalent to using @option{--format=long} (@option{-l}) with
7851 @option{--time-style=full-iso} (@pxref{Formatting file timestamps}).
7855 Produce long format, but omit owner information.
7861 Inhibit display of group information in long format.
7862 (This is the default in some non-GNU versions of @command{ls}, so we
7863 provide this option for compatibility.)
7871 @cindex inode number, printing
7872 Print the inode number (also called the file serial number and index
7873 number) of each file to the left of the file name. (This number
7874 uniquely identifies each file within a particular file system.)
7877 @itemx --format=long
7878 @itemx --format=verbose
7881 @opindex long ls @r{format}
7882 @opindex verbose ls @r{format}
7883 Produce long format.
7884 In addition to the name of each file, print the file type, file mode bits,
7885 number of hard links, owner name, group name, size, and
7886 timestamp (@pxref{Formatting file timestamps}), normally
7887 the modification timestamp (the mtime, @pxref{File timestamps}).
7888 If the owner or group name cannot be determined, print
7889 the owner or group ID instead, right-justified as a cue
7890 that it is a number rather than a textual name.
7891 Print question marks for other information that
7892 cannot be determined.
7894 Normally the size is printed as a byte count without punctuation, but
7895 this can be overridden (@pxref{Block size}).
7896 For example, @option{--human-readable} (@option{-h})
7897 prints an abbreviated, human-readable count, and
7898 @samp{--block-size="'1"} prints a byte count with the thousands
7899 separator of the current locale.
7901 For each directory that is listed, preface the files with a line
7902 @samp{total @var{blocks}}, where @var{blocks} is the file system allocation
7903 for all files in that directory. The block size currently defaults to 1024
7904 bytes, but this can be overridden (@pxref{Block size}).
7905 The @var{blocks} computed counts each hard link separately;
7906 this is arguably a deficiency.
7908 The file type is one of the following characters:
7910 @c The commented-out entries are ones we're not sure about.
7918 character special file
7920 high performance (``contiguous data'') file
7926 @c semaphore, if this is a distinct file type
7930 @c multiplexed file (7th edition Unix; obsolete)
7932 off-line (``migrated'') file (Cray DMF)
7934 network special file (HP-UX)
7940 @c message queue, if this is a distinct file type
7944 @c shared memory object, if this is a distinct file type
7946 @c typed memory object, if this is a distinct file type
7948 @c whiteout (4.4BSD; not implemented)
7950 some other file type
7953 @cindex permissions, output by @command{ls}
7954 The file mode bits listed are similar to symbolic mode specifications
7955 (@pxref{Symbolic Modes}). But @command{ls} combines multiple bits into the
7956 third character of each set of permissions as follows:
7960 If the set-user-ID or set-group-ID bit and the corresponding executable bit
7964 If the set-user-ID or set-group-ID bit is set but the corresponding
7965 executable bit is not set.
7968 If the restricted deletion flag or sticky bit, and the
7969 other-executable bit, are both set. The restricted deletion flag is
7970 another name for the sticky bit. @xref{Mode Structure}.
7973 If the restricted deletion flag or sticky bit is set but the
7974 other-executable bit is not set.
7977 If the executable bit is set and none of the above apply.
7983 Following the file mode bits is a single character that specifies
7984 whether an alternate access method such as an access control list
7985 applies to the file. When the character following the file mode bits is a
7986 space, there is no alternate access method. When it is a printing
7987 character, then there is such a method.
7989 GNU @command{ls} uses a @samp{.} character to indicate a file
7990 with a security context, but no other alternate access method.
7992 A file with any other combination of alternate access methods
7993 is marked with a @samp{+} character.
7996 @itemx --numeric-uid-gid
7998 @opindex --numeric-uid-gid
7999 @cindex numeric uid and gid
8000 @cindex numeric user and group IDs
8001 Produce long format, but
8002 display right-justified numeric user and group IDs
8003 instead of left-justified owner and group names.
8007 Produce long format, but omit group information.
8008 It is equivalent to using @option{--format=long} (@option{-l})
8009 with @option{--no-group} (@option{-G}).
8015 @cindex file system allocation
8016 @cindex size of files, reporting
8017 Print the file system allocation of each file to the left of the file name.
8018 This is the amount of file system space used by the file, which is usually a
8019 bit more than the file's size, but it can be less if the file has holes.
8021 Normally the allocation is printed in units of
8022 1024 bytes, but this can be overridden (@pxref{Block size}).
8024 @cindex NFS mounts from BSD to HP-UX
8025 For files that are NFS-mounted from an HP-UX system to a BSD system,
8026 this option reports sizes that are half the correct values. On HP-UX
8027 systems, it reports sizes that are twice the correct values for files
8028 that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX;
8029 it also affects the HP-UX @command{ls} program.
8038 @cindex security context
8039 Display the SELinux security context or @samp{?} if none is found.
8040 In long format, print the security context to the left of the size column.
8045 @node Sorting the output
8046 @subsection Sorting the output
8048 @cindex sorting @command{ls} output
8049 These options change the order in which @command{ls} sorts the information
8050 it outputs. By default, sorting is done by character code
8051 (e.g., ASCII order).
8057 @itemx --time=status
8060 @opindex ctime@r{, printing or sorting by}
8061 @opindex status time@r{, printing or sorting by}
8062 @opindex use time@r{, printing or sorting files by}
8064 print the status change timestamp (the ctime) instead of the mtime.
8065 When sorting by time or when not using long format,
8066 sort according to the ctime. @xref{File timestamps}.
8070 @cindex unsorted directory listing
8071 @cindex directory order, listing by
8072 Produce an unsorted directory listing.
8073 This is equivalent to the combination of @option{--all} (@option{-a}),
8074 @option{--sort=none} (@option{-U}), @option{-1},
8075 @option{--color=none}, and @option{--hyperlink=none},
8076 while also disabling any previous use of @option{--size} (@option{-s}).
8082 @cindex reverse sorting
8083 Reverse whatever the sorting method is -- e.g., list files in reverse
8084 alphabetical order, youngest first, smallest first, or whatever.
8085 This option has no effect when @option{--sort=none} (@option{-U})
8092 @opindex size of files@r{, sorting files by}
8093 Sort by file size, largest first.
8099 @opindex modification timestamp@r{, sorting files by}
8100 Sort by modification timestamp (mtime) by default, newest first.
8101 The timestamp to order by can be changed with the @option{--time} option.
8102 @xref{File timestamps}.
8106 @itemx --time=access
8110 @opindex use time@r{, printing or sorting files by}
8111 @opindex atime@r{, printing or sorting files by}
8112 @opindex access timestamp@r{, printing or sorting files by}
8113 In long format, print the last access timestamp (the atime).
8114 When sorting by time or when not using long format,
8115 sort according to the atime.
8116 @xref{File timestamps}.
8119 @itemx --time=modification
8121 @opindex data modification time@r{, printing or sorting files by}
8122 @opindex mtime@r{, printing or sorting files by}
8123 This is the default timestamp display and sorting mode.
8124 In long format, print the last data modification timestamp (the mtime).
8125 When sorting by time or when not using long format,
8126 sort according to the mtime.
8127 @xref{File timestamps}.
8130 @itemx --time=creation
8132 @opindex birth time@r{, printing or sorting files by}
8133 @opindex creation timestamp@r{, printing or sorting files by}
8134 In long format, print the file creation timestamp if available,
8135 falling back to the file modification timestamp (mtime) if not.
8136 When sorting by time or when not using long format,
8137 sort according to the birth time.
8138 @xref{File timestamps}.
8144 @opindex none@r{, sorting option for @command{ls}}
8145 Do not sort; list the files in whatever order they are
8146 stored in the directory. (Do not do any of the other unrelated things
8147 that @option{-f} does.) This can be useful when listing large
8148 directories, where sorting can take some time.
8151 @itemx --sort=version
8154 @opindex version@r{, sorting option for @command{ls}}
8155 Sort by version name and number, lowest first. It behaves like a default
8156 sort, except that each sequence of decimal digits is treated numerically
8157 as an index/version number. @xref{Version sort ordering}.
8161 @opindex width@r{, sorting option for @command{ls}}
8162 Sort by printed width of file names.
8163 This can be useful with the @option{--format=vertical} (@option{-C})
8164 output format, to most densely display the listed files.
8167 @itemx --sort=extension
8170 @opindex extension@r{, sorting files by}
8171 Sort directory contents alphabetically by file extension (characters
8172 after the last @samp{.}); files with no extension are sorted first.
8177 @node General output formatting
8178 @subsection General output formatting
8180 These options affect the appearance of the overall output.
8184 @item --format=single-column
8186 @opindex single-column @r{output of files}
8187 List one file name per line, with no other information.
8188 This is the default for @command{ls} when standard
8189 output is not a terminal. See also the @option{--escape} (@option{-b}),
8190 @option{--hide-control-chars} (@option{-q}), and @option{--zero} options
8191 to disambiguate output of file names containing newline characters.
8195 List one file per line. This is like @option{--format=single-column}
8196 except that it has no effect if long format is also in effect.
8199 @itemx --format=vertical
8202 @opindex vertical @r{sorted files in columns}
8203 List files in columns, sorted vertically, with no other information.
8204 This is the default for @command{ls} if standard output is a terminal.
8205 It is always the default for the @command{dir} program.
8206 GNU @command{ls} uses variable width columns to display as many files as
8207 possible in the fewest lines.
8209 @item --color [=@var{when}]
8211 @cindex color, distinguishing file types with
8212 Specify whether to use color for distinguishing file types; @var{when}
8213 may be omitted, or one of:
8216 @vindex none @r{color option}
8217 - Do not use color at all. This is the default.
8219 @vindex auto @r{color option}
8220 @cindex terminal, using color iff
8221 - Only use color if standard output is a terminal.
8223 @vindex always @r{color option}
8226 Specifying @option{--color} and no @var{when} is equivalent to
8227 @option{--color=always}.
8228 If piping a colored listing through a pager like @command{less},
8229 use the pager's @option{-R} option to pass the color codes to the terminal.
8232 @vindex SHELL @r{environment variable, and color}
8233 Using the @option{--color} option may incur a noticeable
8234 performance penalty when run in a large directory,
8235 because the default settings require that @command{ls} @code{stat} every
8236 single file it lists.
8237 However, if you would like most of the file-type coloring
8238 but can live without the other coloring options (e.g.,
8239 executable, orphan, sticky, other-writable, capability), use
8240 @command{dircolors} to set the @env{LS_COLORS} environment variable like this,
8242 eval $(dircolors -p | perl -pe \
8243 's/^((CAP|S[ET]|O[TR]|M|E)\w+).*/$1 00/' | dircolors -)
8245 and on a @code{dirent.d_type}-capable file system, @command{ls}
8246 will perform only one @code{stat} call per command line argument.
8249 @itemx --classify [=@var{when}]
8250 @itemx --indicator-style=classify
8253 @opindex --indicator-style
8254 @cindex file type and executables, marking
8255 @cindex executables and file type, marking
8256 Append a character to each file name indicating the file type. Also,
8257 for regular files that are executable, append @samp{*}. The file type
8258 indicators are @samp{/} for directories, @samp{@@} for symbolic links,
8259 @samp{|} for FIFOs, @samp{=} for sockets, @samp{>} for doors,
8260 and nothing for regular files.
8261 @var{when} may be omitted, or one of:
8264 @vindex none @r{classify option}
8265 - Do not classify. This is the default.
8267 @vindex auto @r{classify option}
8268 @cindex terminal, using classify iff
8269 - Only classify if standard output is a terminal.
8271 @vindex always @r{classify option}
8274 Specifying @option{--classify} and no @var{when} is equivalent to
8275 @option{--classify=always}.
8276 @c The following sentence is the same as the one for -d.
8277 Do not follow symbolic links listed on the
8278 command line unless the @option{--dereference-command-line} (@option{-H}),
8279 @option{--dereference} (@option{-L}), or
8280 @option{--dereference-command-line-symlink-to-dir} options are specified.
8283 @itemx --indicator-style=file-type
8284 @opindex --file-type
8285 @opindex --indicator-style
8286 @cindex file type, marking
8287 Append a character to each file name indicating the file type. This is
8288 like @option{--classify} (@option{-F}, except that executables are not marked.
8290 @item --hyperlink [=@var{when}]
8291 @opindex --hyperlink
8292 @cindex hyperlink, linking to files
8293 Output codes recognized by some terminals to link
8294 to files using the @samp{file://} URI format.
8295 @var{when} may be omitted, or one of:
8298 @vindex none @r{hyperlink option}
8299 - Do not use hyperlinks at all. This is the default.
8301 @vindex auto @r{hyperlink option}
8302 @cindex terminal, using hyperlink iff
8303 - Only use hyperlinks if standard output is a terminal.
8305 @vindex always @r{hyperlink option}
8306 - Always use hyperlinks.
8308 Specifying @option{--hyperlink} and no @var{when} is equivalent to
8309 @option{--hyperlink=always}.
8311 @item --indicator-style=@var{word}
8312 @opindex --indicator-style
8313 Append a character indicator with style @var{word} to entry names,
8318 Do not append any character indicator; this is the default.
8320 Append @samp{/} for directories. This is the same as the @option{-p}
8323 Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|}
8324 for FIFOs, @samp{=} for sockets, and nothing for regular files. This is
8325 the same as the @option{--file-type} option.
8327 Append @samp{*} for executable regular files, otherwise behave as for
8328 @samp{file-type}. This is the same as the @option{--classify}
8329 (@option{-F}) option.
8335 @opindex --kibibytes
8336 Set the default block size to its normal value of 1024 bytes,
8337 overriding any contrary specification in environment variables
8338 (@pxref{Block size}). If @option{--block-size},
8339 @option{--human-readable} (@option{-h}), or @option{--si} options are used,
8340 they take precedence even if @option{--kibibytes} (@option{-k}) is placed after
8342 The @option{--kibibytes} (@option{-k}) option affects the
8343 per-directory block count written in long format,
8344 and the file system allocation written by the @option{--size} (@option{-s})
8345 option. It does not affect the file size in bytes that is written in
8349 @itemx --format=commas
8352 @opindex commas@r{, outputting between files}
8353 List files horizontally, with as many as will fit on each line,
8354 separated by @samp{, } (a comma and a space),
8355 and with no other information.
8358 @itemx --indicator-style=slash
8360 @opindex --indicator-style
8361 @cindex file type, marking
8362 Append a @samp{/} to directory names.
8365 @itemx --format=across
8366 @itemx --format=horizontal
8369 @opindex across@r{, listing files}
8370 @opindex horizontal@r{, listing files}
8371 List the files in columns, sorted horizontally.
8374 @itemx --tabsize=@var{cols}
8377 Assume that each tab stop is @var{cols} columns wide. The default is 8.
8378 @command{ls} uses tabs where possible in the output, for efficiency. If
8379 @var{cols} is zero, do not use tabs at all.
8381 Some terminal emulators might not properly align columns to the right of a
8382 TAB following a non-ASCII byte. You can avoid that issue by using the
8383 @option{-T0} option or put @code{TABSIZE=0} in your environment, to tell
8384 @command{ls} to align using spaces, not tabs.
8386 If you set a terminal's hardware tabs to anything other than the default,
8387 you should also use a @command{--tabsize} option or @env{TABSIZE}
8388 environment variable either to match the hardware tabs, or to disable
8389 the use of hardware tabs. Otherwise, the output of @command{ls} may
8390 not line up. For example, if you run the shell command @samp{tabs -4}
8391 to set hardware tabs to every four columns, you should also run
8392 @samp{export TABSIZE=4} or @samp{export TABSIZE=0}, or use the
8393 corresponding @option{--tabsize} options.
8396 @itemx --width=@var{cols}
8400 Assume the screen is @var{cols} columns wide. The default is taken
8401 from the terminal settings if possible; otherwise the environment
8402 variable @env{COLUMNS} is used if it is set; otherwise the default
8403 is 80. With a @var{cols} value of @samp{0}, there is no limit on
8404 the length of the output line, and that single output line will
8405 be delimited with spaces, not tabs.
8410 This option is incompatible with the @option{--dired} (@option{-D}) option.
8411 This option also implies the options @option{--show-control-chars},
8412 @option{-1}, @option{--color=none}, and
8413 @option{--quoting-style=literal} (@option{-N}).
8418 @node Formatting file timestamps
8419 @subsection Formatting file timestamps
8421 By default, file timestamps are listed in abbreviated form, using
8422 a date like @samp{Mar 30@ @ 2020} for non-recent timestamps, and a
8423 date-without-year and time like @samp{Mar 30 23:45} for recent timestamps.
8424 This format can change depending on the current locale as detailed below.
8427 A timestamp is considered to be @dfn{recent} if it is less than six
8428 months old, and is not dated in the future. If a timestamp dated
8429 today is not listed in recent form, the timestamp is in the future,
8430 which means you probably have clock skew problems which may break
8431 programs like @command{make} that rely on file timestamps.
8432 @xref{File timestamps}.
8435 Timestamps are listed according to the time zone rules specified by
8436 the @env{TZ} environment variable, or by the system default rules if
8437 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
8438 with @env{TZ}, libc, The GNU C Library Reference Manual}.
8440 The following option changes how file timestamps are printed.
8443 @item --time-style=@var{style}
8444 @opindex --time-style
8446 List timestamps in style @var{style}. The @var{style} should
8447 be one of the following:
8452 List timestamps using @var{format}, where @var{format} is interpreted
8453 like the format argument of @command{date} (@pxref{date invocation}).
8454 For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
8455 @command{ls} to list timestamps like @samp{2020-03-30 23:45:56}. As
8456 with @command{date}, @var{format}'s interpretation is affected by the
8457 @env{LC_TIME} locale category.
8459 If @var{format} contains two format strings separated by a newline,
8460 the former is used for non-recent files and the latter for recent
8461 files; if you want output columns to line up, you may need to insert
8462 spaces in one of the two formats.
8465 List timestamps in full using ISO 8601-like date, time, and time zone
8466 components with nanosecond precision, e.g., @samp{2020-07-21
8467 23:45:56.477817180 -0400}. This style is equivalent to
8468 @samp{+%Y-%m-%d %H:%M:%S.%N %z}.
8470 This is useful because the time output includes all the information that
8471 is available from the operating system. For example, this can help
8472 explain @command{make}'s behavior, since GNU @command{make}
8473 uses the full timestamp to determine whether a file is out of date.
8476 List ISO 8601 date and time components with minute precision, e.g.,
8477 @samp{2020-03-30 23:45}. These timestamps are shorter than
8478 @samp{full-iso} timestamps, and are usually good enough for everyday
8479 work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
8482 List ISO 8601 dates for non-recent timestamps (e.g.,
8483 @samp{2020-03-30@ }), and ISO 8601-like month, day, hour, and
8484 minute for recent timestamps (e.g., @samp{03-30 23:45}). These
8485 timestamps are uglier than @samp{long-iso} timestamps, but they carry
8486 nearly the same information in a smaller space and their brevity helps
8487 @command{ls} output fit within traditional 80-column output lines.
8488 The following two @command{ls} invocations are equivalent:
8493 ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M"
8494 ls -l --time-style="iso"
8499 List timestamps in a locale-dependent form. For example, a French
8500 locale might list non-recent timestamps like @samp{30 mars@ @ @ 2020}
8501 and recent timestamps like @samp{30 mars@ @ 23:45}. Locale-dependent
8502 timestamps typically consume more space than @samp{iso} timestamps and
8503 are harder for programs to parse because locale conventions vary so
8504 widely, but they are easier for many people to read.
8506 The @env{LC_TIME} locale category specifies the timestamp format. The
8507 default POSIX locale uses timestamps like @samp{Mar 30@
8508 @ 2020} and @samp{Mar 30 23:45}; in this locale, the following two
8509 @command{ls} invocations are equivalent:
8514 ls -l --time-style="+%b %e %Y$newline%b %e %H:%M"
8515 ls -l --time-style="locale"
8518 Other locales behave differently. For example, in a German locale,
8519 @option{--time-style="locale"} might be equivalent to
8520 @option{--time-style="+%e. %b %Y $newline%e. %b %H:%M"}
8521 and might generate timestamps like @samp{30. M@"ar 2020@ } and
8522 @samp{30. M@"ar 23:45}.
8524 @item posix-@var{style}
8526 List POSIX-locale timestamps if the @env{LC_TIME} locale
8527 category is POSIX, @var{style} timestamps otherwise. For
8528 example, the @samp{posix-long-iso} style lists
8529 timestamps like @samp{Mar 30@ @ 2020} and @samp{Mar 30 23:45} when in
8530 the POSIX locale, and like @samp{2020-03-30 23:45} otherwise.
8535 You can specify the default value of the @option{--time-style} option
8536 with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
8537 the default style is @samp{locale}. GNU Emacs 21.3 and
8538 later use the @option{--dired} option and therefore can parse any date
8539 format, but if you are using Emacs 21.1 or 21.2 and specify a
8540 non-POSIX locale you may need to set
8541 @samp{TIME_STYLE="posix-long-iso"}.
8543 To avoid certain denial-of-service attacks, timestamps that would be
8544 longer than 1000 bytes may be treated as errors.
8547 @node Formatting the file names
8548 @subsection Formatting the file names
8550 These options change how file names themselves are printed.
8556 @itemx --quoting-style=escape
8559 @opindex --quoting-style
8560 @cindex backslash sequences for file names
8561 Quote nongraphic characters in file names using alphabetic and octal
8562 backslash sequences like those used in C.
8566 @itemx --quoting-style=literal
8569 @opindex --quoting-style
8570 Do not quote file names. However, with @command{ls} nongraphic
8571 characters are still printed as question marks if the output is a
8572 terminal and you do not specify the @option{--show-control-chars}
8576 @itemx --hide-control-chars
8578 @opindex --hide-control-chars
8579 Print question marks instead of nongraphic characters in file names.
8580 This is the default if the output is a terminal and the program is
8585 @itemx --quoting-style=c
8587 @opindex --quote-name
8588 @opindex --quoting-style
8589 Enclose file names in double quotes and quote nongraphic characters as
8592 @item --quoting-style=@var{word}
8593 @opindex --quoting-style
8594 @cindex quoting style
8595 Use style @var{word} to quote file names and other strings that may
8596 contain arbitrary characters. The @var{word} should
8597 be one of the following:
8599 @macro quotingStyles
8602 Output strings as-is; this is the same as the @option{--literal} (@option{-N})
8605 Quote strings for the shell if they contain shell metacharacters or would
8606 cause ambiguous output.
8607 The quoting is suitable for POSIX-compatible shells like
8608 @command{bash}, but it does not always work for incompatible shells
8611 Quote strings for the shell, even if they would normally not require quoting.
8613 Like @samp{shell}, but also quoting non-printable characters using the POSIX
8614 proposed @samp{$''} syntax suitable for most shells.
8615 @item shell-escape-always
8616 Like @samp{shell-escape}, but quote strings even if they would
8617 normally not require quoting.
8619 Quote strings as for C character string literals, including the
8620 surrounding double-quote characters; this is the same as the
8621 @option{--quote-name} (@option{-Q}) option.
8623 Quote strings as for C character string literals, except omit the
8624 surrounding double-quote
8625 characters; this is the same as the @option{--escape} (@option{-b}) option.
8627 Quote strings as for C character string literals, except use
8628 surrounding quotation marks appropriate for the
8631 @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
8632 Quote strings as for C character string literals, except use
8633 surrounding quotation marks appropriate for the locale, and quote
8634 @t{'like this'} instead of @t{"like
8635 this"} in the default C locale. This looks nicer on many displays.
8640 You can specify the default value of the @option{--quoting-style} option
8641 with the environment variable @env{QUOTING_STYLE}@. If that environment
8642 variable is not set, the default value is @samp{shell-escape} when the
8643 output is a terminal, and @samp{literal} otherwise.
8645 @item --show-control-chars
8646 @opindex --show-control-chars
8647 Print nongraphic characters as-is in file names.
8648 This is the default unless the output is a terminal and the program is
8654 @node dir invocation
8655 @section @command{dir}: Briefly list directory contents
8658 @cindex directory listing, brief
8660 @command{dir} is equivalent to @code{ls -C
8661 -b}; that is, by default files are listed in columns, sorted vertically,
8662 and special characters are represented by backslash escape sequences.
8664 @xref{ls invocation, @command{ls}}.
8667 @node vdir invocation
8668 @section @command{vdir}: Verbosely list directory contents
8671 @cindex directory listing, verbose
8673 @command{vdir} is equivalent to @code{ls -l
8674 -b}; that is, by default files are listed in long format and special
8675 characters are represented by backslash escape sequences.
8677 @xref{ls invocation, @command{ls}}.
8679 @node dircolors invocation
8680 @section @command{dircolors}: Color setup for @command{ls}
8684 @cindex setup for color
8686 @command{dircolors} outputs a sequence of shell commands to set up the
8687 terminal for color output from @command{ls} (and @command{dir}, etc.).
8691 eval "$(dircolors [@var{option}]@dots{} [@var{file}])"
8694 If @var{file} is specified, @command{dircolors} reads it to determine which
8695 colors to use for which file types and extensions. Otherwise, a
8696 precompiled database is used. For details on the format of these files,
8697 run @samp{dircolors --print-database}.
8699 To make @command{dircolors} read a @file{~/.dircolors} file if it
8700 exists, you can put the following lines in your @file{~/.bashrc} (or
8701 adapt them to your favorite shell):
8705 test -r $d && eval "$(dircolors $d)"
8709 @vindex SHELL @r{environment variable, and color}
8710 The output is a shell command to set the @env{LS_COLORS} environment
8711 variable. You can specify the shell syntax to use on the command line,
8712 or @command{dircolors} will guess it from the value of the @env{SHELL}
8713 environment variable.
8715 The program accepts the following options. Also see @ref{Common options}.
8720 @itemx --bourne-shell
8723 @opindex --bourne-shell
8724 @cindex Bourne shell syntax for color setup
8725 @cindex @command{sh} syntax for color setup
8726 Output Bourne shell commands. This is the default if the @env{SHELL}
8727 environment variable is set and does not end with @samp{csh} or
8736 @cindex C shell syntax for color setup
8737 @cindex @command{csh} syntax for color setup
8738 Output C shell commands. This is the default if @code{SHELL} ends with
8739 @command{csh} or @command{tcsh}.
8742 @itemx --print-database
8744 @opindex --print-database
8745 @cindex color database, printing
8746 @cindex database for color setup, printing
8747 @cindex printing color database
8748 Print the (compiled-in) default color configuration database. This
8749 output is itself a valid configuration file, and is fairly descriptive
8750 of the possibilities.
8752 @item --print-ls-colors
8753 @opindex --print-ls-colors
8754 @cindex printing ls colors
8755 Print the LS_COLORS entries on separate lines,
8756 each colored as per the color they represent.
8763 @node Basic operations
8764 @chapter Basic operations
8766 @cindex manipulating files
8768 This chapter describes the commands for basic file manipulation:
8769 copying, moving (renaming), and deleting (removing).
8772 * cp invocation:: Copy files.
8773 * dd invocation:: Convert and copy a file.
8774 * install invocation:: Copy files and set attributes.
8775 * mv invocation:: Move (rename) files.
8776 * rm invocation:: Remove files or directories.
8777 * shred invocation:: Remove files more securely.
8782 @section @command{cp}: Copy files and directories
8785 @cindex copying files and directories
8786 @cindex files, copying
8787 @cindex directories, copying
8789 @command{cp} copies files (or, optionally, directories). The copy is
8790 completely independent of the original. You can either copy one file to
8791 another, or copy arbitrarily many files to a destination directory.
8795 cp [@var{option}]@dots{} [-T] @var{source} @var{dest}
8796 cp [@var{option}]@dots{} @var{source}@dots{} @var{directory}
8797 cp [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
8802 If two file names are given, @command{cp} copies the first file to the
8806 If the @option{--target-directory} (@option{-t}) option is given, or
8807 failing that if the last file is a directory and the
8808 @option{--no-target-directory} (@option{-T}) option is not given,
8809 @command{cp} copies each @var{source} file to the specified directory,
8810 using the @var{source}s' names.
8813 Generally, files are written just as they are read. For exceptions,
8814 see the @option{--sparse} option below.
8816 By default, @command{cp} does not copy directories. However, the
8817 @option{-R}, @option{-a}, and @option{-r} options cause @command{cp} to
8818 copy recursively by descending into source directories and copying files
8819 to corresponding destination directories.
8821 When copying from a symbolic link, @command{cp} normally follows the
8822 link only when not copying recursively or when @option{--link}
8823 (@option{-l}) is used. This default can be overridden with the
8824 @option{--archive} (@option{-a}), @option{-d}, @option{--dereference}
8825 (@option{-L}), @option{--no-dereference} (@option{-P}), and
8826 @option{-H} options. If more than one of these options is specified,
8827 the last one silently overrides the others.
8829 When copying to a symbolic link, @command{cp} follows the
8830 link only when it refers to an existing regular file.
8831 However, when copying to a dangling symbolic link, @command{cp}
8832 refuses by default, and fails with a diagnostic, since the operation
8833 is inherently dangerous. This behavior is contrary to historical
8834 practice and to POSIX@.
8835 Set @env{POSIXLY_CORRECT} to make @command{cp} attempt to create
8836 the target of a dangling destination symlink, in spite of the possible risk.
8837 Also, when an option like
8838 @option{--backup} or @option{--link} acts to rename or remove the
8839 destination before copying, @command{cp} renames or removes the
8840 symbolic link rather than the file it points to.
8842 By default, @command{cp} copies the contents of special files only
8843 when not copying recursively. This default can be overridden with the
8844 @option{--copy-contents} option.
8846 @cindex self-backups
8847 @cindex backups, making only
8848 @command{cp} generally refuses to copy a file onto itself, with the
8849 following exception: if @option{--force --backup} is specified with
8850 @var{source} and @var{dest} identical, and referring to a regular file,
8851 @command{cp} will make a backup file, either regular or numbered, as
8852 specified in the usual ways (@pxref{Backup options}). This is useful when
8853 you simply want to make a backup of an existing file before changing it.
8855 The program accepts the following options. Also see @ref{Common options}.
8862 Preserve as much as possible of the structure and attributes of the
8863 original files in the copy (but do not attempt to preserve internal
8864 directory structure; i.e., @samp{ls -U} may list the entries in a copied
8865 directory in a different order).
8866 Try to preserve SELinux security context and extended attributes (xattr),
8867 but ignore any failure to do that and print no corresponding diagnostic.
8868 Equivalent to @option{-dR --preserve=all} with the reduced diagnostics.
8870 @item --attributes-only
8871 @opindex --attributes-only
8872 Copy only the specified attributes of the source file to the destination.
8873 If the destination already exists, do not alter its contents.
8874 See the @option{--preserve} option for controlling which attributes to copy.
8877 @itemx --backup[=@var{method}]
8880 @vindex VERSION_CONTROL
8881 @cindex backups, making
8882 @xref{Backup options}.
8883 Make a backup of each file that would otherwise be overwritten or removed.
8884 As a special case, @command{cp} makes a backup of @var{source} when the force
8885 and backup options are given and @var{source} and @var{dest} are the same
8886 name for an existing, regular file. One useful application of this
8887 combination of options is this tiny Bourne shell script:
8891 # Usage: backup FILE...
8892 # Create a GNU-style backup of each listed FILE.
8895 cp --backup --force --preserve=all -- "$i" "$i" || fail=1
8900 @item --copy-contents
8901 @cindex directories, copying recursively
8902 @cindex copying directories recursively
8903 @cindex recursively copying directories
8904 @cindex non-directories, copying as special files
8905 If copying recursively, copy the contents of any special files (e.g.,
8906 FIFOs and device files) as if they were regular files. This means
8907 trying to read the data in each source file and writing it to the
8908 destination. It is usually a mistake to use this option, as it
8909 normally has undesirable effects on special files like FIFOs and the
8910 ones typically found in the @file{/dev} directory. In most cases,
8911 @code{cp -R --copy-contents} will hang indefinitely trying to read
8912 from FIFOs and special files like @file{/dev/console}, and it will
8913 fill up your destination file system if you use it to copy @file{/dev/zero}.
8914 This option has no effect unless copying recursively, and it does not
8915 affect the copying of symbolic links.
8919 @cindex symbolic links, copying
8920 @cindex hard links, preserving
8921 Copy symbolic links as symbolic links rather than copying the files that
8922 they point to, and preserve hard links between source files in the copies.
8923 Equivalent to @option{--no-dereference --preserve=links}.
8929 When copying without this option and an existing destination file cannot
8930 be opened for writing, the copy fails. However, with @option{--force},
8931 when a destination file cannot be opened, @command{cp} then
8932 tries to recreate the file by first removing it. Note @option{--force}
8933 alone will not remove dangling symlinks.
8934 When this option is combined with
8935 @option{--link} (@option{-l}) or @option{--symbolic-link}
8936 (@option{-s}), the destination link is replaced, and unless
8937 @option{--backup} (@option{-b}) is also given there is no brief
8938 moment when the destination does not exist. Also see the
8939 description of @option{--remove-destination}.
8941 This option is independent of the @option{--interactive} or
8942 @option{-i} option: neither cancels the effect of the other.
8944 This option is ignored when the @option{--no-clobber} or @option{-n} option
8949 If a command line argument specifies a symbolic link, then copy the
8950 file it points to rather than the symbolic link itself. However,
8951 copy (preserving its nature) any symbolic link that is encountered
8952 via recursive traversal.
8955 @itemx --interactive
8957 @opindex --interactive
8958 When copying a file other than a directory, prompt whether to
8959 overwrite an existing destination file, and fail if the response
8960 is not affirmative. The @option{-i} option overrides
8961 a previous @option{-n} option.
8967 Make hard links instead of copies of non-directories.
8970 @itemx --dereference
8972 @opindex --dereference
8973 Follow symbolic links when copying from them.
8974 With this option, @command{cp} cannot create a symbolic link.
8975 For example, a symlink (to regular file) in the source tree will be copied to
8976 a regular file in the destination tree.
8981 @opindex --no-clobber
8982 Do not overwrite an existing file; silently fail instead.
8983 This option overrides a previous
8984 @option{-i} option. This option is mutually exclusive with @option{-b} or
8985 @option{--backup} option.
8988 @itemx --no-dereference
8990 @opindex --no-dereference
8991 @cindex symbolic links, copying
8992 Copy symbolic links as symbolic links rather than copying the files that
8993 they point to. This option affects only symbolic links in the source;
8994 symbolic links in the destination are always followed if possible.
8997 @itemx --preserve[=@var{attribute_list}]
9000 @cindex file information, preserving, extended attributes, xattr
9001 Preserve the specified attributes of the original files.
9002 If specified, the @var{attribute_list} must be a comma-separated list
9003 of one or more of the following strings:
9007 @cindex access control lists (ACLs)
9008 Preserve attributes relevant to access permissions,
9009 including file mode bits and (if possible) access control lists (ACLs).
9010 ACL preservation is system-dependent, and ACLs are not necessarily
9011 translated when the source and destination are on file systems with
9012 different ACL formats (e.g., NFSv4 versus POSIX formats).
9015 Preserve the owner and group. On most modern systems,
9016 only users with appropriate privileges may change the owner of a file,
9018 may preserve the group ownership of a file only if they happen to be
9019 a member of the desired group.
9021 Preserve the times of last access and last modification, when possible.
9022 On older systems, it is not possible to preserve these attributes
9023 when the affected file is a symbolic link.
9024 However, many systems now provide the @code{utimensat} function,
9025 which makes it possible even for symbolic links.
9027 Preserve in the destination files
9028 any links between corresponding source files.
9029 Note that with @option{-L} or @option{-H}, this option can convert
9030 symbolic links to hard links. For example,
9032 $ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c
9037 Note the inputs: @file{b} is a symlink to regular file @file{a},
9038 yet the files in destination directory, @file{c/}, are hard-linked.
9039 Since @option{-a} implies @option{--no-dereference} it would copy the symlink,
9040 but the later @option{-H} tells @command{cp} to dereference the command line
9041 arguments where it then sees two files with the same inode number.
9042 Then the @option{--preserve=links} option also implied by @option{-a}
9043 will preserve the perceived hard link.
9045 Here is a similar example that exercises @command{cp}'s @option{-L} option:
9047 $ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
9053 Preserve SELinux security context of the file, or fail with full diagnostics.
9055 @cindex access control lists (ACLs)
9056 Preserve extended attributes of the file, or fail with full diagnostics.
9057 If @command{cp} is built without xattr support, ignore this option.
9058 If SELinux context, ACLs or Capabilities are implemented using xattrs,
9059 they are preserved implicitly by this option as well, i.e., even without
9060 specifying @option{--preserve=mode} or @option{--preserve=context}.
9062 Preserve all file attributes.
9063 Equivalent to specifying all of the above, but with the difference
9064 that failure to preserve SELinux security context or extended attributes
9065 does not change @command{cp}'s exit status. In contrast to @option{-a},
9066 all but @samp{Operation not supported} warnings are output.
9069 Using @option{--preserve} with no @var{attribute_list} is equivalent
9070 to @option{--preserve=mode,ownership,timestamps}.
9072 In the absence of this option, the permissions of existing destination
9073 files are unchanged. Each new file is created with the mode of the
9074 corresponding source file minus the set-user-ID, set-group-ID, and
9075 sticky bits as the create mode; the operating system then applies either
9076 the umask or a default ACL, possibly resulting in a more restrictive
9078 @xref{File permissions}.
9080 @item --no-preserve=@var{attribute_list}
9081 @cindex file information, preserving
9082 Do not preserve the specified attributes. The @var{attribute_list}
9083 has the same form as for @option{--preserve}.
9087 @cindex parent directories and @command{cp}
9088 Form the name of each destination file by appending to the target
9089 directory a slash and the specified name of the source file. The last
9090 argument given to @command{cp} must be the name of an existing directory.
9091 For example, the command:
9094 cp --parents a/b/c existing_dir
9098 copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating
9099 any missing intermediate directories.
9106 @opindex --recursive
9107 @cindex directories, copying recursively
9108 @cindex copying directories recursively
9109 @cindex recursively copying directories
9110 @cindex non-directories, copying as special files
9111 Copy directories recursively. By default, do not follow symbolic
9112 links in the source unless used together with the @option{--link}
9113 (@option{-l}) option; see the @option{--archive} (@option{-a}), @option{-d},
9114 @option{--dereference} (@option{-L}), @option{--no-dereference}
9115 (@option{-P}), and @option{-H} options. Special files are copied by
9116 creating a destination file of the same type as the source; see the
9117 @option{--copy-contents} option. It is not portable to use
9118 @option{-r} to copy symbolic links or special files. On some
9119 non-GNU systems, @option{-r} implies the equivalent of
9120 @option{-L} and @option{--copy-contents} for historical reasons.
9121 Also, it is not portable to use @option{-R} to copy symbolic links
9122 unless you also specify @option{-P}, as POSIX allows
9123 implementations that dereference symbolic links by default.
9125 @item --reflink[=@var{when}]
9126 @opindex --reflink[=@var{when}]
9129 @cindex copy on write
9130 Perform a lightweight, copy-on-write (COW) copy, if supported by the
9131 file system. Once it has succeeded, beware that the source and destination
9132 files share the same data blocks as long as they remain unmodified.
9133 Thus, if an I/O error affects data blocks of one of the files,
9134 the other suffers the same fate.
9136 The @var{when} value can be one of the following:
9140 If the copy-on-write operation is not supported
9141 then report the failure for each file and exit with a failure status.
9142 Plain @option{--reflink} is equivalent to @option{--reflink=always}.
9145 If the copy-on-write operation is not supported then fall back
9146 to the standard copy behavior.
9147 This is the default if no @option{--reflink} option is given.
9150 Disable copy-on-write operation and use the standard copy behavior.
9153 This option is overridden by the @option{--link}, @option{--symbolic-link}
9154 and @option{--attributes-only} options, thus allowing it to be used
9155 to configure the default data copying behavior for @command{cp}.
9157 @item --remove-destination
9158 @opindex --remove-destination
9159 Remove each existing destination file before attempting to open it
9160 (contrast with @option{-f} above).
9162 @item --sparse=@var{when}
9163 @opindex --sparse=@var{when}
9164 @cindex sparse files, copying
9165 @cindex holes, copying files with
9166 @findex read @r{system call, and holes}
9167 A @dfn{sparse file} contains @dfn{holes} -- a sequence of zero bytes that
9168 does not occupy any file system blocks; the @samp{read} system call
9169 reads these as zeros. This can both save considerable space and
9170 increase speed, since many binary files contain lots of consecutive zero
9171 bytes. By default, @command{cp} detects holes in input source files via a crude
9172 heuristic and makes the corresponding output file sparse as well.
9173 Only regular files may be sparse.
9175 The @var{when} value can be one of the following:
9179 The default behavior: if the input file is sparse, attempt to make
9180 the output file sparse, too. However, if an output file exists but
9181 refers to a non-regular file, then do not attempt to make it sparse.
9184 For each sufficiently long sequence of zero bytes in the input file,
9185 attempt to create a corresponding hole in the output file, even if the
9186 input file does not appear to be sparse.
9187 This is useful when the input file resides on a file system
9188 that does not support sparse files
9189 (for example, @samp{efs} file systems in SGI IRIX 5.3 and earlier),
9190 but the output file is on a type of file system that does support them.
9191 Holes may be created only in regular files, so if the destination file
9192 is of some other type, @command{cp} does not even try to make it sparse.
9195 Never make the output file sparse.
9196 This is useful in creating a file for use with the @command{mkswap} command,
9197 since such a file must not have any holes.
9200 For example, with the following alias, @command{cp} will use the
9201 minimum amount of space supported by the file system.
9202 (Older versions of @command{cp} can also benefit from
9203 @option{--reflink=auto} here.)
9206 alias cp='cp --sparse=always'
9209 @optStripTrailingSlashes
9212 @itemx --symbolic-link
9214 @opindex --symbolic-link
9215 @cindex symbolic links, copying with
9216 Make symbolic links instead of copies of non-directories. All source
9217 file names must be absolute (starting with @samp{/}) unless the
9218 destination files are in the current directory. This option merely
9219 results in an error message on systems that do not support symbolic links.
9225 @optNoTargetDirectory
9231 @cindex newer files, copying only
9232 Do not copy a non-directory that has an existing destination with the
9233 same or newer modification timestamp; instead, silently skip the file
9234 without failing. If timestamps are being preserved,
9235 the comparison is to the source timestamp truncated to the
9236 resolutions of the destination file system and of the system calls
9237 used to update timestamps; this avoids duplicate work if several
9238 @samp{cp -pu} commands are executed with the same source and destination.
9239 This option is ignored if the @option{-n} or @option{--no-clobber}
9240 option is also specified.
9241 Also, if @option{--preserve=links} is also specified (like with @samp{cp -au}
9242 for example), that will take precedence; consequently, depending on the
9243 order that files are processed from the source, newer files in the destination
9244 may be replaced, to mirror hard links in the source.
9250 Print the name of each file before copying it.
9253 @itemx --one-file-system
9255 @opindex --one-file-system
9256 @cindex file systems, omitting copying to different
9257 Skip subdirectories that are on different file systems from the one that
9258 the copy started on.
9259 However, mount point directories @emph{are} copied.
9263 @itemx --context[=@var{context}]
9266 @cindex SELinux, setting/restoring security context
9267 @cindex security context
9268 Without a specified @var{context}, adjust the SELinux security context according
9269 to the system default type for destination files, similarly to the
9270 @command{restorecon} command.
9271 The long form of this option with a specific context specified,
9272 will set the context for newly created files only.
9273 With a specified context, if both SELinux and SMACK are disabled, a warning is
9277 This option is mutually exclusive with the @option{--preserve=context}
9278 option, and overrides the @option{--preserve=all} and @option{-a} options.
9286 @section @command{dd}: Convert and copy a file
9289 @cindex converting while copying a file
9291 @command{dd} copies input to output with a changeable I/O block size,
9292 while optionally performing conversions on the data. Synopses:
9295 dd [@var{operand}]@dots{}
9299 The only options are @option{--help} and @option{--version}.
9300 @xref{Common options}.
9302 By default, @command{dd} copies standard input to standard output.
9303 To copy, @command{dd} repeatedly does the following steps in order:
9307 Read an input block.
9310 If converting via @samp{sync}, pad as needed to meet the input block size.
9311 Pad with spaces if converting via @samp{block} or @samp{unblock}, NUL
9315 If @samp{bs=} is given and no conversion mentioned in steps (4) or (5)
9316 is given, output the data as a single block and skip all remaining steps.
9319 If the @samp{swab} conversion is given, swap each pair of input bytes.
9320 If the input data length is odd, preserve the last input byte
9321 (since there is nothing to swap it with).
9324 If any of the conversions @samp{swab}, @samp{block}, @samp{unblock},
9325 @samp{lcase}, @samp{ucase}, @samp{ascii}, @samp{ebcdic} and @samp{ibm}
9326 are given, do these conversions. These conversions operate
9327 independently of input blocking, and might deal with records that span
9331 Aggregate the resulting data into output blocks of the specified size,
9332 and output each output block in turn. Do not pad the last output block;
9333 it can be shorter than usual.
9336 @command{dd} accepts the following operands,
9337 whose syntax was inspired by the DD (data definition) statement of
9344 Read from @var{file} instead of standard input.
9348 Write to @var{file} instead of standard output. Unless
9349 @samp{conv=notrunc} is given, truncate @var{file} before writing it.
9351 @item ibs=@var{bytes}
9353 @cindex block size of input
9354 @cindex input block size
9355 Set the input block size to @var{bytes}.
9356 This makes @command{dd} read @var{bytes} per block.
9357 The default is 512 bytes.
9359 @item obs=@var{bytes}
9361 @cindex block size of output
9362 @cindex output block size
9363 Set the output block size to @var{bytes}.
9364 This makes @command{dd} write @var{bytes} per block.
9365 The default is 512 bytes.
9367 @item bs=@var{bytes}
9370 Set both input and output block sizes to @var{bytes}.
9371 This makes @command{dd} read and write @var{bytes} per block,
9372 overriding any @samp{ibs} and @samp{obs} settings.
9373 In addition, if no data-transforming @option{conv} operand is specified,
9374 input is copied to the output as soon as it's read,
9375 even if it is smaller than the block size.
9377 @item cbs=@var{bytes}
9379 @cindex block size of conversion
9380 @cindex conversion block size
9381 @cindex fixed-length records, converting to variable-length
9382 @cindex variable-length records, converting to fixed-length
9383 Set the conversion block size to @var{bytes}.
9384 When converting variable-length records to fixed-length ones
9385 (@option{conv=block}) or the reverse (@option{conv=unblock}),
9386 use @var{bytes} as the fixed record length.
9389 @itemx iseek=@var{n}
9392 Skip @var{n} @samp{ibs}-byte blocks in the input file before copying.
9393 If @var{n} ends in the letter @samp{B}, interpret @var{n}
9394 as a byte count rather than a block count.
9395 (@samp{B} and the @samp{iseek=} spelling are GNU extensions to POSIX.)
9398 @itemx oseek=@var{n}
9401 Skip @var{n} @samp{obs}-byte blocks in the output file before
9402 truncating or copying.
9403 If @var{n} ends in the letter @samp{B}, interpret @var{n}
9404 as a byte count rather than a block count.
9405 (@samp{B} and the @samp{oseek=} spelling are GNU extensions to POSIX.)
9409 Copy @var{n} @samp{ibs}-byte blocks from the input file, instead
9410 of everything until the end of the file.
9411 If @var{n} ends in the letter @samp{B},
9412 interpret @var{n} as a byte count rather than a block count;
9413 this is a GNU extension to POSIX.
9414 If short reads occur, as could be the case
9415 when reading from a pipe for example, @samp{iflag=fullblock}
9416 ensures that @samp{count=} counts complete input blocks
9417 rather than input read operations.
9418 As an extension to POSIX, @samp{count=0} copies zero blocks
9419 instead of copying all blocks.
9421 @item status=@var{level}
9423 Specify the amount of information printed.
9424 If this operand is given multiple times, the last one takes precedence.
9425 The @var{level} value can be one of the following:
9430 @opindex none @r{dd status=}
9431 Do not print any informational or warning messages to standard error.
9432 Error messages are output as normal.
9435 @opindex noxfer @r{dd status=}
9436 Do not print the final transfer rate and volume statistics
9437 that normally make up the last status line.
9440 @opindex progress @r{dd status=}
9441 Print the transfer rate and volume statistics on standard error,
9442 when processing each input block. Statistics are output
9443 on a single line at most once every second, but updates
9444 can be delayed when waiting on I/O.
9448 Transfer information is normally output to standard error upon
9449 receipt of the @samp{INFO} signal or when @command{dd} exits,
9450 and defaults to the following form in the C locale:
9454 116608+0 records out
9455 59703296 bytes (60 MB, 57 MiB) copied, 0.0427974 s, 1.4 GB/s
9458 The notation @samp{@var{w}+@var{p}} stands for @var{w} whole blocks
9459 and @var{p} partial blocks. A partial block occurs when a read or
9460 write operation succeeds but transfers less data than the block size.
9461 An additional line like @samp{1 truncated record} or @samp{10
9462 truncated records} is output after the @samp{records out} line if
9463 @samp{conv=block} processing truncated one or more input records.
9465 The @samp{status=} operand is a GNU extension to POSIX.
9467 @item conv=@var{conversion}[,@var{conversion}]@dots{}
9469 Convert the file as specified by the @var{conversion} argument(s).
9470 (No spaces around any comma(s).)
9477 @opindex ascii@r{, converting to}
9478 Convert EBCDIC to ASCII,
9479 using the conversion table specified by POSIX@.
9480 This provides a 1:1 translation for all 256 bytes.
9481 This implies @samp{conv=unblock}; input is converted to
9482 ASCII before trailing spaces are deleted.
9485 @opindex ebcdic@r{, converting to}
9486 Convert ASCII to EBCDIC@.
9487 This is the inverse of the @samp{ascii} conversion.
9488 This implies @samp{conv=block}; trailing spaces are added
9489 before being converted to EBCDIC@.
9492 @opindex alternate ebcdic@r{, converting to}
9493 This acts like @samp{conv=ebcdic}, except it
9494 uses the alternate conversion table specified by POSIX@.
9495 This is not a 1:1 translation, but reflects common historical practice
9496 for @samp{~}, @samp{[}, and @samp{]}.
9498 The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are
9499 mutually exclusive. If you use any of these conversions, you should also
9500 use the @samp{cbs=} operand.
9503 @opindex block @r{(space-padding)}
9504 For each line in the input, output @samp{cbs} bytes, replacing the
9505 input newline with a space and truncating or padding input lines with
9506 spaces as necessary.
9510 Remove any trailing spaces in each @samp{cbs}-sized input block,
9511 and append a newline.
9513 The @samp{block} and @samp{unblock} conversions are mutually exclusive.
9514 If you use either of these conversions, you should also use the
9515 @samp{cbs=} operand.
9518 @opindex lcase@r{, converting to}
9519 Change uppercase letters to lowercase.
9522 @opindex ucase@r{, converting to}
9523 Change lowercase letters to uppercase.
9525 The @samp{lcase} and @samp{ucase} conversions are mutually exclusive.
9529 Try to seek rather than write NUL output blocks.
9530 On a file system that supports sparse files, this will create
9531 sparse output when extending the output file.
9532 Be careful when using this conversion in conjunction with
9533 @samp{conv=notrunc} or @samp{oflag=append}.
9534 With @samp{conv=notrunc}, existing data in the output file
9535 corresponding to NUL blocks from the input, will be untouched.
9536 With @samp{oflag=append} the seeks performed will be ineffective.
9537 Similarly, when the output is a device rather than a file,
9538 NUL input blocks are not copied, and therefore this conversion
9539 is most useful with virtual or pre zeroed devices.
9541 The @samp{sparse} conversion is a GNU extension to POSIX.
9544 @opindex swab @r{(byte-swapping)}
9545 @cindex byte-swapping
9546 Swap every pair of input bytes.
9549 @opindex sync @r{(padding with ASCII NULs)}
9550 Pad every input block to size of @samp{ibs} with trailing zero bytes.
9551 When used with @samp{block} or @samp{unblock}, pad with spaces instead of
9556 The following ``conversions'' are really file flags
9557 and don't affect internal processing:
9562 @cindex creating output file, requiring
9563 Fail if the output file already exists; @command{dd} must create the
9568 @cindex creating output file, avoiding
9569 Do not create the output file; the output file must already exist.
9571 The @samp{excl} and @samp{nocreat} conversions are mutually exclusive,
9572 and are GNU extensions to POSIX.
9576 @cindex truncating output file, avoiding
9577 Do not truncate the output file.
9581 @cindex read errors, ignoring
9582 Continue after read errors.
9586 @cindex synchronized data writes, before finishing
9587 Synchronize output data just before finishing,
9588 even if there were write errors.
9589 This forces a physical write of output data,
9590 so that even if power is lost the output data will be preserved.
9591 If neither this nor @samp{fsync} are specified, output is treated as
9592 usual with file systems, i.e., output data and metadata may be cached
9593 in primary memory for some time before the operating system physically
9594 writes it, and thus output data and metadata may be lost if power is lost.
9595 @xref{sync invocation}.
9596 This conversion is a GNU extension to POSIX.
9600 @cindex synchronized data and metadata writes, before finishing
9601 Synchronize output data and metadata just before finishing,
9602 even if there were write errors.
9603 This acts like @samp{fdatasync} except it also preserves output metadata,
9604 such as the last-modified time of the output file; for this reason it
9605 may be a bit slower than @samp{fdatasync} although the performance
9606 difference is typically insignificant for @command{dd}.
9607 This conversion is a GNU extension to POSIX.
9611 @item iflag=@var{flag}[,@var{flag}]@dots{}
9613 Access the input file using the flags specified by the @var{flag}
9614 argument(s). (No spaces around any comma(s).)
9616 @item oflag=@var{flag}[,@var{flag}]@dots{}
9618 Access the output file using the flags specified by the @var{flag}
9619 argument(s). (No spaces around any comma(s).)
9627 @cindex appending to the output file
9628 Write in append mode, so that even if some other process is writing to
9629 this file, every @command{dd} write will append to the current
9630 contents of the file. This flag makes sense only for output.
9631 If you combine this flag with the @samp{of=@var{file}} operand,
9632 you should also specify @samp{conv=notrunc} unless you want the
9633 output file to be truncated before being appended to.
9637 @cindex concurrent I/O
9638 Use concurrent I/O mode for data. This mode performs direct I/O
9639 and drops the POSIX requirement to serialize all I/O to the same file.
9640 A file cannot be opened in CIO mode and with a standard open at the
9646 Use direct I/O for data, avoiding the buffer cache.
9647 Note that the kernel may impose restrictions on read or write buffer sizes.
9648 For example, with an ext4 destination file system and a Linux-based kernel,
9649 using @samp{oflag=direct} will cause writes to fail with @code{EINVAL} if the
9650 output buffer size is not a multiple of 512.
9654 @cindex directory I/O
9656 Fail unless the file is a directory. Most operating systems do not
9657 allow I/O to a directory, so this flag has limited utility.
9661 @cindex synchronized data reads
9662 Use synchronized I/O for data. For the output file, this forces a
9663 physical write of output data on each write. For the input file,
9664 this flag can matter when reading from a remote file that has been
9665 written to synchronously by some other process. Metadata (e.g.,
9666 last-access and last-modified time) is not necessarily synchronized.
9670 @cindex synchronized data and metadata I/O
9671 Use synchronized I/O for both data and metadata.
9675 @cindex discarding file cache
9676 Request to discard the system data cache for a file.
9677 When count=0 all cached data for the file is specified,
9678 otherwise the cache is dropped for the processed
9679 portion of the file. Also when count=0,
9680 failure to discard the cache is diagnosed
9681 and reflected in the exit status.
9683 Note data that is not already persisted to storage will not
9684 be discarded from cache, so note the use of the @samp{sync} conversions
9685 in the examples below, which are used to maximize the
9686 effectiveness of the @samp{nocache} flag.
9688 Here are some usage examples:
9691 # Advise to drop cache for whole file
9692 dd if=ifile iflag=nocache count=0
9694 # Ensure drop cache for the whole file
9695 dd of=ofile oflag=nocache conv=notrunc,fdatasync count=0
9697 # Advise to drop cache for part of file
9698 # Note the kernel will only consider complete and
9699 # already persisted pages.
9700 dd if=ifile iflag=nocache skip=10 count=10 of=/dev/null
9702 # Stream data using just the read-ahead cache.
9703 # See also the @samp{direct} flag.
9704 dd if=ifile of=ofile iflag=nocache oflag=nocache,sync
9709 @cindex nonblocking I/O
9710 Use non-blocking I/O.
9714 @cindex access timestamp
9715 Do not update the file's access timestamp.
9716 @xref{File timestamps}.
9717 Some older file systems silently ignore this flag, so it is a good
9718 idea to test it on your files before relying on it.
9722 @cindex controlling terminal
9723 Do not assign the file to be a controlling terminal for @command{dd}.
9724 This has no effect when the file is not a terminal.
9725 On many hosts (e.g., GNU/Linux hosts), this flag has no effect
9730 @cindex symbolic links, following
9731 Do not follow symbolic links.
9736 Fail if the file has multiple hard links.
9741 Use binary I/O@. This flag has an effect only on nonstandard
9742 platforms that distinguish binary from text I/O.
9747 Use text I/O@. Like @samp{binary}, this flag has no effect on
9752 Accumulate full blocks from input. The @code{read} system call
9753 may return early if a full block is not available.
9754 When that happens, continue calling @code{read} to fill the remainder
9756 This flag can be used only with @code{iflag}.
9757 This flag is useful with pipes for example
9758 as they may return short reads. In that case,
9759 this flag is needed to ensure that a @samp{count=} argument is
9760 interpreted as a block count rather than a count of read operations.
9764 These flags are all GNU extensions to POSIX.
9765 They are not supported on all systems, and @samp{dd} rejects
9766 attempts to use them when they are not supported. When reading from
9767 standard input or writing to standard output, the @samp{nofollow} and
9768 @samp{noctty} flags should not be specified, and the other flags
9769 (e.g., @samp{nonblock}) can affect how other processes behave with the
9770 affected file descriptors, even after @command{dd} exits.
9774 The behavior of @command{dd} is unspecified if operands other than
9775 @samp{conv=}, @samp{iflag=}, @samp{oflag=}, and @samp{status=} are
9776 specified more than once.
9778 @cindex multipliers after numbers
9779 The numeric-valued strings above (@var{n} and @var{bytes})
9780 are unsigned decimal integers that
9781 can be followed by a multiplier: @samp{b}=512, @samp{c}=1,
9782 @samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the
9783 standard block size suffixes like @samp{k}=1024 (@pxref{Block size}).
9784 These multipliers are GNU extensions to POSIX, except that
9785 POSIX allows @var{bytes} to be followed by @samp{k}, @samp{b}, and
9787 Block sizes (i.e., specified by @var{bytes} strings) must be nonzero.
9789 Any block size you specify via @samp{bs=}, @samp{ibs=}, @samp{obs=}, @samp{cbs=}
9790 should not be too large -- values larger than a few megabytes
9791 are generally wasteful or (as in the gigabyte..exabyte case) downright
9792 counterproductive or error-inducing.
9794 To process data with offset or size that is not a multiple of the I/O
9795 block size, you can use a numeric string @var{n} that ends in the
9797 For example, the following shell commands copy data
9798 in 1 MiB blocks between a flash drive and a tape, but do not save
9799 or restore a 512-byte area at the start of the flash drive:
9805 # Copy all but the initial 512 bytes from flash to tape.
9806 dd if=$flash iseek=512B bs=1MiB of=$tape
9808 # Copy from tape back to flash, leaving initial 512 bytes alone.
9809 dd if=$tape bs=1MiB of=$flash oseek=512B
9813 @cindex storage devices, failing
9814 For failing storage devices, other tools come with a great variety of extra
9815 functionality to ease the saving of as much data as possible before the
9816 device finally dies, e.g.
9817 @uref{https://www.gnu.org/software/ddrescue/, GNU @command{ddrescue}}.
9818 However, in some cases such a tool is not available or the administrator
9819 feels more comfortable with the handling of @command{dd}.
9820 As a simple rescue method, call @command{dd} as shown in the following
9821 example: the operand @samp{conv=noerror,sync} is used to continue
9822 after read errors and to pad out bad reads with NULs, while
9823 @samp{iflag=fullblock} caters for short reads (which traditionally never
9824 occur on flash or similar devices):
9827 # Rescue data from an (unmounted!) partition of a failing device.
9828 dd conv=noerror,sync iflag=fullblock </dev/sda1 > /mnt/rescue.img
9831 Sending an @samp{INFO} signal (or @samp{USR1} signal where that is unavailable)
9832 to a running @command{dd} process makes it print I/O statistics to
9833 standard error and then resume copying. In the example below,
9834 @command{dd} is run in the background to copy 5GB of data.
9835 The @command{kill} command makes it output intermediate I/O statistics,
9836 and when @command{dd} completes normally or is killed by the
9837 @code{SIGINT} signal, it outputs the final statistics.
9840 # Ignore the signal so we never inadvertently terminate the dd child.
9841 # Note this is not needed when SIGINFO is available.
9844 # Run dd with the fullblock iflag to avoid short reads
9845 # which can be triggered by reception of signals.
9846 dd iflag=fullblock if=/dev/zero of=/dev/null count=5000000 bs=1000 & pid=$!
9848 # Output stats every second.
9849 while kill -s USR1 $pid 2>/dev/null; do sleep 1; done
9852 The above script will output in the following format:
9855 3441325+0 records in
9856 3441325+0 records out
9857 3441325000 bytes (3.4 GB, 3.2 GiB) copied, 1.00036 s, 3.4 GB/s
9858 5000000+0 records in
9859 5000000+0 records out
9860 5000000000 bytes (5.0 GB, 4.7 GiB) copied, 1.44433 s, 3.5 GB/s
9863 The @samp{status=progress} operand periodically updates the last line
9864 of the transfer statistics above.
9866 @vindex POSIXLY_CORRECT
9867 On systems lacking the @samp{INFO} signal @command{dd} responds to the
9868 @samp{USR1} signal instead, unless the @env{POSIXLY_CORRECT}
9869 environment variable is set.
9874 @node install invocation
9875 @section @command{install}: Copy files and set attributes
9878 @cindex copying files and setting attributes
9880 @command{install} copies files while setting their file mode bits and, if
9881 possible, their owner and group. Synopses:
9884 install [@var{option}]@dots{} [-T] @var{source} @var{dest}
9885 install [@var{option}]@dots{} @var{source}@dots{} @var{directory}
9886 install [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
9887 install [@var{option}]@dots{} -d @var{directory}@dots{}
9892 If two file names are given, @command{install} copies the first file to the
9896 If the @option{--target-directory} (@option{-t}) option is given, or
9897 failing that if the last file is a directory and the
9898 @option{--no-target-directory} (@option{-T}) option is not given,
9899 @command{install} copies each @var{source} file to the specified
9900 directory, using the @var{source}s' names.
9903 If the @option{--directory} (@option{-d}) option is given,
9904 @command{install} creates each @var{directory} and any missing parent
9905 directories. Parent directories are created with mode
9906 @samp{u=rwx,go=rx} (755), regardless of the @option{-m} option or the
9907 current umask. @xref{Directory Setuid and Setgid}, for how the
9908 set-user-ID and set-group-ID bits of parent directories are inherited.
9911 @cindex Makefiles, installing programs in
9912 @command{install} is similar to @command{cp}, but allows you to control the
9913 attributes of destination files. It is typically used in Makefiles to
9914 copy programs into their destination directories. It refuses to copy
9915 files onto themselves.
9917 @cindex extended attributes, xattr
9918 @command{install} never preserves extended attributes (xattr).
9920 The program accepts the following options. Also see @ref{Common options}.
9930 Compare content of source and destination files, and if there would be no
9931 change to the destination content, owner, group, permissions, and possibly
9932 SELinux context, then do not modify the destination at all.
9933 Note this option is best used in conjunction with @option{--user},
9934 @option{--group} and @option{--mode} options, lest @command{install}
9935 incorrectly determines the default attributes that installed files would have
9936 (as it doesn't consider setgid directories and POSIX default ACLs for example).
9937 This could result in redundant copies or attributes that are not reset to the
9942 Ignored; for compatibility with old Unix versions of @command{install}.
9946 Create any missing parent directories of @var{dest},
9947 then copy @var{source} to @var{dest}.
9948 Explicitly specifying the @option{--target-directory=@var{dir}} will similarly
9949 ensure the presence of that hierarchy before copying @var{source} arguments.
9954 @opindex --directory
9955 @cindex directories, creating with given attributes
9956 @cindex parent directories, creating missing
9957 @cindex leading directories, creating missing
9958 Create any missing parent directories, giving them the default
9959 attributes. Then create each given directory, setting their owner,
9960 group and mode as given on the command line or to the defaults.
9962 @item -g @var{group}
9963 @itemx --group=@var{group}
9966 @cindex group ownership of installed files, setting
9967 Set the group ownership of installed files or directories to
9968 @var{group}. The default is the process's current group. @var{group}
9969 may be either a group name or a numeric group ID.
9972 @itemx --mode=@var{mode}
9975 @cindex permissions of installed files, setting
9976 Set the file mode bits for the installed file or directory to @var{mode},
9977 which can be either an octal number, or a symbolic mode as in
9978 @command{chmod}, with @samp{a=} (no access allowed to anyone) as the
9979 point of departure (@pxref{File permissions}).
9980 The default mode is @samp{u=rwx,go=rx,a-s} -- read, write, and
9981 execute for the owner, read and execute for group and other, and with
9982 set-user-ID and set-group-ID disabled.
9983 This default is not quite the same as @samp{755}, since it disables
9984 instead of preserving set-user-ID and set-group-ID on directories.
9985 @xref{Directory Setuid and Setgid}.
9987 @item -o @var{owner}
9988 @itemx --owner=@var{owner}
9991 @cindex ownership of installed files, setting
9992 @cindex appropriate privileges
9993 @vindex root @r{as default owner}
9994 If @command{install} has appropriate privileges (is run as root), set the
9995 ownership of installed files or directories to @var{owner}. The default
9996 is @code{root}. @var{owner} may be either a user name or a numeric user
9999 @item --preserve-context
10000 @opindex --preserve-context
10002 @cindex security context
10003 Preserve the SELinux security context of files and directories.
10004 Failure to preserve the context in all of the files or directories
10005 will result in an exit status of 1. If SELinux is disabled then
10006 print a warning and ignore the option.
10009 @itemx --preserve-timestamps
10011 @opindex --preserve-timestamps
10012 @cindex timestamps of installed files, preserving
10013 Set the time of last access and the time of last modification of each
10014 installed file to match those of each corresponding original file.
10015 When a file is installed without this option, its last access and
10016 last modification timestamps are both set to the time of installation.
10017 This option is useful if you want to use the last modification timestamps
10018 of installed files to keep track of when they were last built as opposed
10019 to when they were last installed.
10025 @cindex symbol table information, stripping
10026 @cindex stripping symbol table information
10027 Strip the symbol tables from installed binary executables.
10029 @item --strip-program=@var{program}
10030 @opindex --strip-program
10031 @cindex symbol table information, stripping, program
10032 Program used to strip binaries.
10036 @optTargetDirectory
10037 Also specifying the @option{-D} option will ensure the directory is present.
10039 @optNoTargetDirectory
10045 Print the name of each file before copying it.
10048 This option is mutually exclusive with the @option{--preserve-context} option.
10056 @node mv invocation
10057 @section @command{mv}: Move (rename) files
10061 @command{mv} moves or renames files (or directories). Synopses:
10064 mv [@var{option}]@dots{} [-T] @var{source} @var{dest}
10065 mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
10066 mv [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
10071 If two file names are given, @command{mv} moves the first file to the
10075 If the @option{--target-directory} (@option{-t}) option is given, or
10076 failing that if the last file is a directory and the
10077 @option{--no-target-directory} (@option{-T}) option is not given,
10078 @command{mv} moves each @var{source} file to the specified
10079 directory, using the @var{source}s' names.
10082 To move a file, @command{mv} ordinarily simply renames it.
10083 However, if renaming does not work because the destination's file
10084 system differs, @command{mv} falls back on copying as if by @code{cp -a},
10085 then (assuming the copy succeeded) it removes the original.
10086 If the copy fails, then @command{mv} removes any partially created
10087 copy in the destination. If you were to copy three directories from
10088 one file system to another and the copy of the first
10089 directory succeeded, but the second didn't, the first would be left on
10090 the destination file system and the second and third would be left on the
10091 original file system.
10093 @cindex extended attributes, xattr
10094 @command{mv} always tries to copy extended attributes (xattr), which may
10095 include SELinux context, ACLs or Capabilities.
10096 Upon failure all but @samp{Operation not supported} warnings are output.
10098 @cindex prompting, and @command{mv}
10099 If a destination file exists but is normally unwritable, standard input
10100 is a terminal, and the @option{-f} or @option{--force} option is not given,
10101 @command{mv} prompts the user for whether to replace the file. (You might
10102 own the file, or have write permission on its directory.) If the
10103 response is not affirmative, the file is skipped.
10105 @emph{Warning}: Avoid specifying a source name with a trailing slash,
10106 when it might be a symlink to a directory.
10107 Otherwise, @command{mv} may do something very surprising, since
10108 its behavior depends on the underlying rename system call.
10109 On a system with a modern Linux-based kernel, it fails with
10110 @code{errno=ENOTDIR}@.
10111 However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently
10112 renames not the symlink but rather the directory referenced by the symlink.
10113 @xref{Trailing slashes}.
10115 @emph{Note}: @command{mv} will only replace empty directories in the
10116 destination. Conflicting populated directories are skipped with a diagnostic.
10118 The program accepts the following options. Also see @ref{Common options}.
10128 @cindex prompts, omitting
10129 Do not prompt the user before removing a destination file.
10131 If you specify more than one of the @option{-i}, @option{-f}, @option{-n}
10132 options, only the final one takes effect.
10137 @itemx --interactive
10139 @opindex --interactive
10140 @cindex prompts, forcing
10141 Prompt whether to overwrite each existing destination file, regardless
10142 of its permissions, and fail if the response is not affirmative.
10146 @itemx --no-clobber
10148 @opindex --no-clobber
10149 @cindex prompts, omitting
10150 Do not overwrite an existing file; silently fail instead.
10152 This option is mutually exclusive with @option{-b} or @option{--backup} option.
10156 @cindex renaming files without copying them
10157 If a file cannot be renamed because the destination file system differs,
10158 fail with a diagnostic instead of copying and then removing the file.
10164 @cindex newer files, moving only
10165 Do not move a non-directory that has an existing destination with the
10166 same or newer modification timestamp;
10167 instead, silently skip the file without failing.
10168 If the move is across file system boundaries, the comparison is to the
10169 source timestamp truncated to the resolutions of the destination file
10170 system and of the system calls used to update timestamps; this avoids
10171 duplicate work if several @samp{mv -u} commands are executed with the
10172 same source and destination.
10173 This option is ignored if the @option{-n} or @option{--no-clobber}
10174 option is also specified.
10180 Print the name of each file before moving it.
10182 @optStripTrailingSlashes
10186 @optTargetDirectory
10188 @optNoTargetDirectory
10194 @cindex SELinux, restoring security context
10195 @cindex security context
10196 This option functions similarly to the @command{restorecon} command,
10197 by adjusting the SELinux security context according
10198 to the system default type for destination files and each created directory.
10205 @node rm invocation
10206 @section @command{rm}: Remove files or directories
10209 @cindex removing files or directories
10211 @command{rm} removes each given @var{file}. By default, it does not remove
10212 directories. Synopsis:
10215 rm [@var{option}]@dots{} [@var{file}]@dots{}
10218 @cindex prompting, and @command{rm}
10219 If the @option{-I} or @option{--interactive=once} option is given,
10220 and there are more than three files or the @option{-r}, @option{-R},
10221 or @option{--recursive} are given, then @command{rm} prompts the user
10222 for whether to proceed with the entire operation. If the response is
10223 not affirmative, the entire command is aborted.
10225 Otherwise, if a file is unwritable, standard input is a terminal, and
10226 the @option{-f} or @option{--force} option is not given, or the
10227 @option{-i} or @option{--interactive=always} option @emph{is} given,
10228 @command{rm} prompts the user for whether to remove the file.
10229 If the response is not affirmative, the file is skipped.
10231 Any attempt to remove a file whose last file name component is
10232 @file{.} or @file{..} is rejected without any prompting, as mandated
10235 @emph{Warning}: If you use @command{rm} to remove a file, it is usually
10236 possible to recover the contents of that file. If you want more assurance
10237 that the contents are unrecoverable, consider using @command{shred}.
10239 The program accepts the following options. Also see @ref{Common options}.
10247 @cindex directories, removing
10248 Remove the listed directories if they are empty.
10254 Ignore nonexistent files and missing operands, and never prompt the user.
10255 Ignore any previous @option{--interactive} (@option{-i}) option.
10259 Prompt whether to remove each file.
10260 If the response is not affirmative, silently skip the file without failing.
10261 Ignore any previous @option{--force} (@option{-f}) option.
10262 Equivalent to @option{--interactive=always}.
10266 Prompt once whether to proceed with the command, if more than three
10267 files are named or if a recursive removal is requested. Ignore any
10268 previous @option{--force} (@option{-f}) option. Equivalent to
10269 @option{--interactive=once}.
10271 @item --interactive [=@var{when}]
10272 @opindex --interactive
10273 Specify when to issue an interactive prompt. @var{when} may be
10274 omitted, or one of:
10277 @vindex never @r{interactive option}
10278 - Do not prompt at all.
10280 @vindex once @r{interactive option}
10281 - Prompt once if more than three files are named or if a recursive
10282 removal is requested. Equivalent to @option{-I}.
10284 @vindex always @r{interactive option}
10285 - Prompt for every file being removed. Equivalent to @option{-i}.
10287 @option{--interactive} with no @var{when} is equivalent to
10288 @option{--interactive=always}.
10290 @item --one-file-system
10291 @opindex --one-file-system
10292 @cindex one file system, restricting @command{rm} to
10293 When removing a hierarchy recursively, do not remove any directory that is on a
10294 file system different from that of the corresponding command line argument.
10296 This option is useful when removing a build ``chroot'' hierarchy,
10297 which normally contains no valuable data. However, it is not uncommon
10298 to bind-mount @file{/home} into such a hierarchy, to make it easier to
10299 use one's start-up file. The catch is that it's easy to forget to
10300 unmount @file{/home}. Then, when you use @command{rm -rf} to remove
10301 your normally throw-away chroot, that command will remove everything
10302 under @file{/home}, too.
10303 Use the @option{--one-file-system} option, and it will
10304 diagnose and skip directories on other file systems.
10305 Of course, this will not save your @file{/home} if it and your
10306 chroot happen to be on the same file system.
10307 See also @option{--preserve-root=all} to protect command line arguments
10310 @item --preserve-root [=all]
10311 @opindex --preserve-root
10312 @cindex root directory, disallow recursive destruction
10313 Fail upon any attempt to remove the root directory, @file{/},
10314 when used with the @option{--recursive} option.
10315 This is the default behavior.
10316 @xref{Treating / specially}.
10317 When @samp{all} is specified, reject any command line argument
10318 that is not on the same file system as its parent.
10320 @item --no-preserve-root
10321 @opindex --no-preserve-root
10322 @cindex root directory, allow recursive destruction
10323 Do not treat @file{/} specially when removing recursively.
10324 This option is not recommended unless you really want to
10325 remove all the files on your computer.
10326 @xref{Treating / specially}.
10333 @opindex --recursive
10334 @cindex directories, removing (recursively)
10335 Remove the listed directories and their contents recursively.
10341 Print the name of each file before removing it.
10345 @cindex files beginning with @samp{-}, removing
10346 @cindex @samp{-}, removing files beginning with
10347 One common question is how to remove files whose names begin with a
10348 @samp{-}. GNU @command{rm}, like every program that uses the @code{getopt}
10349 function to parse its arguments, lets you use the @samp{--} option to
10350 indicate that all following arguments are non-options. To remove a file
10351 called @file{-f} in the current directory, you could type either:
10364 @opindex - @r{and Unix @command{rm}}
10365 The Unix @command{rm} program's use of a single @samp{-} for this purpose
10366 predates the development of the @code{getopt} standard syntax.
10371 @node shred invocation
10372 @section @command{shred}: Remove files more securely
10375 @cindex data, erasing
10376 @cindex erasing data
10378 @command{shred} overwrites devices or files, to help prevent even
10379 extensive forensics from recovering the data.
10381 Ordinarily when you remove a file (@pxref{rm invocation}), its data
10382 and metadata are not actually destroyed. Only the file's directory
10383 entry is removed, and the file's storage is reclaimed only when no
10384 process has the file open and no other directory entry links to the
10385 file. And even if file's data and metadata's storage space is freed
10386 for further reuse, there are undelete utilities that will attempt to
10387 reconstruct the file from the data in freed storage, and that can
10388 bring the file back if the storage was not rewritten.
10390 On a busy system with a nearly-full device, space can get reused in a few
10391 seconds. But there is no way to know for sure. And although the
10392 undelete utilities and already-existing processes require insider or
10393 superuser access, you may be wary of the superuser,
10394 of processes running on your behalf, or of attackers
10395 that can physically access the storage device. So if you have sensitive
10396 data, you may want to be sure that recovery is not possible
10397 by plausible attacks like these.
10399 The best way to remove something irretrievably is to destroy the media
10400 it's on with acid, melt it down, or the like. For cheap removable media
10401 this is often the preferred method. However, some storage devices
10402 are expensive or are harder to destroy, so the @command{shred} utility tries
10403 to achieve a similar effect non-destructively, by overwriting the file
10404 with non-sensitive data.
10406 @strong{Please note} that @command{shred} relies on a crucial
10407 assumption: that the file system and hardware overwrite data in place.
10408 Although this is common and is the traditional
10409 way to do things, many modern file system designs do not satisfy this
10410 assumption. Exceptions include:
10415 Log-structured or journaled file systems, such as ext3/ext4 (in
10416 @code{data=journal} mode), Btrfs, NTFS, ReiserFS, XFS, ZFS, file
10417 systems supplied with AIX and Solaris, etc., when they are configured to
10421 File systems that write redundant data and carry on even if some writes
10422 fail, such as RAID-based file systems.
10425 File systems that make snapshots, such as Network Appliance's NFS server.
10428 File systems that cache in temporary locations, such as NFS version 3
10432 Compressed file systems.
10435 For ext3 and ext4 file systems, @command{shred} is less effective
10436 when the file system is in @code{data=journal}
10437 mode, which journals file data in addition to just metadata. In both
10438 the @code{data=ordered} (default) and @code{data=writeback} modes,
10439 @command{shred} works as usual. The ext3/ext4 journaling modes can be changed
10440 by adding the @code{data=something} option to the mount options for a
10441 particular file system in the @file{/etc/fstab} file, as documented in
10442 the @command{mount} man page (@samp{man mount}). Alternatively, if
10443 you know how large the journal is, you can shred the journal by
10444 shredding enough file data so that the journal cycles around and fills
10445 up with shredded data.
10447 If you are not sure how your file system operates, then you should assume
10448 that it does not overwrite data in place, which means @command{shred} cannot
10449 reliably operate on regular files in your file system.
10451 Generally speaking, it is more reliable to shred a device than a file,
10452 since this bypasses file system design issues mentioned above.
10453 However, devices are also problematic for shredding, for reasons
10454 such as the following:
10459 Solid-state storage devices (SSDs) typically do wear leveling to
10460 prolong service life, and this means writes are distributed to other
10461 blocks by the hardware, so ``overwritten'' data blocks are still
10462 present in the underlying device.
10465 Most storage devices map out bad blocks invisibly to
10466 the application; if the bad blocks contain sensitive data,
10467 @command{shred} won't be able to destroy it.
10470 With some obsolete storage technologies,
10471 it may be possible to take (say) a floppy disk back
10472 to a laboratory and use a lot of sensitive (and expensive) equipment
10473 to look for the faint ``echoes'' of the original data underneath the
10474 overwritten data. With these older technologies, if the file has been
10475 overwritten only once, it's reputedly not even that hard. Luckily,
10476 this kind of data recovery has become difficult, and there is no
10477 public evidence that today's higher-density storage devices can be
10478 analyzed in this way.
10480 The @command{shred} command can use many overwrite passes,
10481 with data patterns chosen to
10482 maximize the damage they do to the old data.
10483 By default the patterns are designed for best effect on hard drives using
10484 now-obsolete technology; for newer devices, a single pass should suffice.
10485 For more details, see the source code and Peter Gutmann's paper
10486 @uref{https://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html,
10487 @cite{Secure Deletion of Data from Magnetic and Solid-State Memory}},
10488 from the proceedings of the Sixth USENIX Security Symposium (San Jose,
10489 California, July 22--25, 1996).
10492 @command{shred} makes no attempt to detect or report these problems, just as
10493 it makes no attempt to do anything about backups. However, since it is
10494 more reliable to shred devices than files, @command{shred} by default does
10495 not deallocate or remove the output file. This default is more suitable
10496 for devices, which typically cannot be deallocated and should not be
10499 Finally, consider the risk of backups and mirrors.
10500 File system backups and remote mirrors may contain copies of the
10501 file that cannot be removed, and that will allow a shredded file
10502 to be recovered later. So if you keep any data you may later want
10503 to destroy using @command{shred}, be sure that it is not backed up or mirrored.
10506 shred [@var{option}]@dots{} @var{file}[@dots{}]
10509 The program accepts the following options. Also see @ref{Common options}.
10517 @cindex force deletion
10518 Override file permissions if necessary to allow overwriting.
10520 @item -n @var{number}
10521 @itemx --iterations=@var{number}
10522 @opindex -n @var{number}
10523 @opindex --iterations=@var{number}
10524 @cindex iterations, selecting the number of
10525 By default, @command{shred} uses @value{SHRED_DEFAULT_PASSES} passes of
10526 overwrite. You can reduce this to save time, or increase it if you think it's
10527 appropriate. After 25 passes all of the internal overwrite patterns will have
10528 been used at least once.
10530 @item --random-source=@var{file}
10531 @opindex --random-source
10532 @cindex random source for shredding
10533 Use @var{file} as a source of random data used to overwrite and to
10534 choose pass ordering. @xref{Random sources}.
10536 @item -s @var{bytes}
10537 @itemx --size=@var{bytes}
10538 @opindex -s @var{bytes}
10539 @opindex --size=@var{bytes}
10540 @cindex size of file to shred
10541 Shred the first @var{bytes} bytes of the file. The default is to shred
10542 the whole file. @var{bytes} can be followed by a size specification like
10543 @samp{K}, @samp{M}, or @samp{G} to specify a multiple. @xref{Block size}.
10546 @itemx --remove[=@var{how}]
10549 @opindex --remove=unlink
10550 @opindex --remove=wipe
10551 @opindex --remove=wipesync
10552 @cindex removing files after shredding
10553 After shredding a file, deallocate it (if possible) and then remove it.
10554 If a file has multiple links, only the named links will be removed.
10555 Often the file name is less sensitive than the file data, in which case
10556 the optional @var{how} parameter, supported with the long form option,
10557 gives control of how to more efficiently remove each directory entry.
10558 The @samp{unlink} parameter will just use a standard unlink call,
10559 @samp{wipe} will also first obfuscate bytes in the name, and
10560 @samp{wipesync} will also sync each obfuscated byte in the name to
10562 Note @samp{wipesync} is the default method, but can be expensive,
10563 requiring a sync for every character in every file. This can become
10564 significant with many files, or is redundant if your file system provides
10565 synchronous metadata updates.
10571 Display to standard error all status updates as sterilization proceeds.
10577 By default, @command{shred} rounds the size of a regular file up to the next
10578 multiple of the file system block size to fully erase the slack space in
10579 the last block of the file. This space may contain portions of the current
10580 system memory on some systems for example.
10581 Use @option{--exact} to suppress that behavior.
10582 Thus, by default if you shred a 10-byte regular file on a system with 512-byte
10583 blocks, the resulting file will be 512 bytes long. With this option,
10584 shred does not increase the apparent size of the file.
10590 Normally, the last pass that @command{shred} writes is made up of
10591 random data. If this would be conspicuous on your storage device (for
10592 example, because it looks like encrypted data), or you just think
10593 it's tidier, the @option{--zero} option adds an additional overwrite pass with
10594 all zero bits. This is in addition to the number of passes specified
10595 by the @option{--iterations} option.
10599 You might use the following command to erase the file system you
10600 created on a USB flash drive. This command typically takes several
10601 minutes, depending on the drive's size and write speed. On modern
10602 storage devices a single pass should be adequate, and will take one
10603 third the time of the default three-pass approach.
10606 shred -v -n 1 /dev/sdd1
10609 Similarly, to erase all data on a selected partition of
10610 your device, you could give a command like the following.
10613 # 1 pass, write pseudo-random data; 3x faster than the default
10614 shred -v -n1 /dev/sda5
10617 To be on the safe side, use at least one pass that overwrites using
10618 pseudo-random data. I.e., don't be tempted to use @samp{-n0 --zero},
10619 in case some device controller optimizes the process of writing blocks
10620 of all zeros, and thereby does not clear all bytes in a block.
10621 Some SSDs may do just that.
10623 A @var{file} of @samp{-} denotes standard output.
10624 The intended use of this is to shred a removed temporary file.
10631 echo "Hello, world" >&3
10636 However, the command @samp{shred - >file} does not shred the contents
10637 of @var{file}, since the shell truncates @var{file} before invoking
10638 @command{shred}. Use the command @samp{shred file} or (if using a
10639 Bourne-compatible shell) the command @samp{shred - 1<>file} instead.
10644 @node Special file types
10645 @chapter Special file types
10647 @cindex special file types
10648 @cindex file types, special
10650 This chapter describes commands which create special types of files (and
10651 @command{rmdir}, which removes directories, one special file type).
10653 @cindex special file types
10655 Although Unix-like operating systems have markedly fewer special file
10656 types than others, not @emph{everything} can be treated only as the
10657 undifferentiated byte stream of @dfn{normal files}. For example, when a
10658 file is created or removed, the system must record this information,
10659 which it does in a @dfn{directory} -- a special type of file. Although
10660 you can read directories as normal files, if you're curious, in order
10661 for the system to do its job it must impose a structure, a certain
10662 order, on the bytes of the file. Thus it is a ``special'' type of file.
10664 Besides directories, other special file types include named pipes
10665 (FIFOs), symbolic links, sockets, and so-called @dfn{special files}.
10668 * link invocation:: Make a hard link via the link syscall
10669 * ln invocation:: Make links between files.
10670 * mkdir invocation:: Make directories.
10671 * mkfifo invocation:: Make FIFOs (named pipes).
10672 * mknod invocation:: Make block or character special files.
10673 * readlink invocation:: Print value of a symlink or canonical file name.
10674 * rmdir invocation:: Remove empty directories.
10675 * unlink invocation:: Remove files via the unlink syscall
10679 @node link invocation
10680 @section @command{link}: Make a hard link via the link syscall
10683 @cindex links, creating
10684 @cindex hard links, creating
10685 @cindex creating links (hard only)
10687 @command{link} creates a single hard link at a time.
10688 It is a minimalist interface to the system-provided
10689 @code{link} function. @xref{Hard Links, , , libc,
10690 The GNU C Library Reference Manual}.
10691 It avoids the bells and whistles of the more commonly-used
10692 @command{ln} command (@pxref{ln invocation}).
10696 link @var{filename} @var{linkname}
10699 @var{filename} must specify an existing file, and @var{linkname}
10700 must specify a nonexistent entry in an existing directory.
10701 @command{link} simply calls @code{link (@var{filename}, @var{linkname})}
10702 to create the link.
10704 On a GNU system, this command acts like @samp{ln --directory
10705 --no-target-directory @var{filename} @var{linkname}}. However, the
10706 @option{--directory} and @option{--no-target-directory} options are
10707 not specified by POSIX, and the @command{link} command is
10708 more portable in practice.
10710 If @var{filename} is a symbolic link, it is unspecified whether
10711 @var{linkname} will be a hard link to the symbolic link or to the
10712 target of the symbolic link. Use @command{ln -P} or @command{ln -L}
10713 to specify which behavior is desired.
10718 @node ln invocation
10719 @section @command{ln}: Make links between files
10722 @cindex links, creating
10723 @cindex hard links, creating
10724 @cindex symbolic (soft) links, creating
10725 @cindex creating links (hard or soft)
10727 @cindex file systems and hard links
10728 @command{ln} makes links between files. By default, it makes hard links;
10729 with the @option{-s} option, it makes symbolic (or @dfn{soft}) links.
10733 ln [@var{option}]@dots{} [-T] @var{target} @var{linkname}
10734 ln [@var{option}]@dots{} @var{target}
10735 ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
10736 ln [@var{option}]@dots{} -t @var{directory} @var{target}@dots{}
10742 If two file names are given, @command{ln} creates a link to the first
10743 file from the second.
10746 If one @var{target} is given, @command{ln} creates a link to that file
10747 in the current directory.
10750 If the @option{--target-directory} (@option{-t}) option is given, or
10751 failing that if the last file is a directory and the
10752 @option{--no-target-directory} (@option{-T}) option is not given,
10753 @command{ln} creates a link to each @var{target} file in the specified
10754 directory, using the @var{target}s' names.
10758 Normally @command{ln} does not replace existing files. Use the
10759 @option{--force} (@option{-f}) option to replace them unconditionally,
10760 the @option{--interactive} (@option{-i}) option to replace them
10761 conditionally, and the @option{--backup} (@option{-b}) option to
10762 rename them. Unless the @option{--backup} (@option{-b}) option is
10763 used there is no brief moment when the destination does not exist;
10764 this is an extension to POSIX.
10766 @cindex hard link, defined
10767 @cindex inode, and hard links
10768 A @dfn{hard link} is another name for an existing file; the link and the
10769 original are indistinguishable. Technically speaking, they share the
10770 same inode, and the inode contains all the information about a
10771 file -- indeed, it is not incorrect to say that the inode @emph{is} the
10772 file. Most systems prohibit making a hard link to
10773 a directory; on those where it is allowed, only the super-user can do
10774 so (and with caution, since creating a cycle will cause problems to many
10775 other utilities). Hard links cannot cross file system boundaries. (These
10776 restrictions are not mandated by POSIX, however.)
10778 @cindex dereferencing symbolic links
10779 @cindex symbolic link, defined
10780 @dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are
10781 a special file type (which not all kernels support: System V release 3
10782 (and older) systems lack symlinks) in which the link file actually
10783 refers to a different file, by name. When most operations (opening,
10784 reading, writing, and so on) are passed the symbolic link file, the
10785 kernel automatically @dfn{dereferences} the link and operates on the
10786 target of the link. But some operations (e.g., removing) work on the
10787 link file itself, rather than on its target. The owner and group of a
10788 symlink are not significant to file access performed through
10789 the link, but do have implications on deleting a symbolic link from a
10790 directory with the restricted deletion bit set. On the GNU system,
10791 the mode of a symlink has no significance and cannot be changed, but
10792 on some BSD systems, the mode can be changed and will affect whether
10793 the symlink will be traversed in file name resolution. @xref{Symbolic Links,,,
10794 libc, The GNU C Library Reference Manual}.
10796 Symbolic links can contain arbitrary strings; a @dfn{dangling symlink}
10797 occurs when the string in the symlink does not resolve to a file.
10798 There are no restrictions against creating dangling symbolic links.
10799 There are trade-offs to using absolute or relative symlinks. An
10800 absolute symlink always points to the same file, even if the directory
10801 containing the link is moved. However, if the symlink is visible from
10802 more than one machine (such as on a networked file system), the file
10803 pointed to might not always be the same. A relative symbolic link is
10804 resolved in relation to the directory that contains the link, and is
10805 often useful in referring to files on the same device without regards
10806 to what name that device is mounted on when accessed via networked
10809 When creating a relative symlink in a different location than the
10810 current directory, the resolution of the symlink will be different
10811 than the resolution of the same string from the current directory.
10812 Therefore, many users prefer to first change directories to the
10813 location where the relative symlink will be created, so that
10814 tab-completion or other file resolution will find the same target as
10815 what will be placed in the symlink.
10817 The program accepts the following options. Also see @ref{Common options}.
10828 @opindex --directory
10829 @cindex hard links to directories
10830 Allow users with appropriate privileges to attempt to make hard links
10832 However, note that this will probably fail due to
10833 system restrictions, even for the super-user.
10839 Remove existing destination files.
10842 @itemx --interactive
10844 @opindex --interactive
10845 @cindex prompting, and @command{ln}
10846 Prompt whether to remove existing destination files,
10847 and fail if the response is not affirmative.
10853 If @option{-s} is not in effect, and the source file is a symbolic
10854 link, create the hard link to the file referred to by the symbolic
10855 link, rather than the symbolic link itself.
10858 @itemx --no-dereference
10860 @opindex --no-dereference
10861 Do not treat the last operand specially when it is a symbolic link to
10862 a directory. Instead, treat it as if it were a normal file.
10864 When the destination is an actual directory (not a symlink to one),
10865 there is no ambiguity. The link is created in that directory.
10866 But when the specified destination is a symlink to a directory,
10867 there are two ways to treat the user's request. @command{ln} can
10868 treat the destination just as it would a normal directory and create
10869 the link in it. On the other hand, the destination can be viewed as a
10870 non-directory -- as the symlink itself. In that case, @command{ln}
10871 must delete or backup that symlink before creating the new link.
10872 The default is to treat a destination that is a symlink to a directory
10873 just like a directory.
10875 This option is weaker than the @option{--no-target-directory}
10876 (@option{-T}) option, so it has no effect if both options are given.
10881 @opindex --physical
10882 If @option{-s} is not in effect, and the source file is a symbolic
10883 link, create the hard link to the symbolic link itself. On platforms
10884 where this is not supported by the kernel, this option creates a
10885 symbolic link with identical contents; since symbolic link contents
10886 cannot be edited, any file name resolution performed through either
10887 link will be the same as if a hard link had been created.
10892 @opindex --relative
10893 Make symbolic links relative to the link location.
10894 This option is only valid with the @option{--symbolic} option.
10899 ln -srv /a/file /tmp
10900 '/tmp/file' -> '../a/file'
10903 Relative symbolic links are generated based on their canonicalized
10904 containing directory, and canonicalized targets. I.e., all symbolic
10905 links in these file names will be resolved.
10906 @xref{realpath invocation}, which gives greater control
10907 over relative file name generation, as demonstrated in the following example:
10912 test "$1" = --no-symlinks && { nosym=$1; shift; }
10914 test -d "$2" && link="$2/." || link="$2"
10915 rtarget="$(realpath $nosym -m "$target" \
10916 --relative-to "$(dirname "$link")")"
10917 ln -s -v "$rtarget" "$link"
10925 @opindex --symbolic
10926 Make symbolic links instead of hard links. This option merely produces
10927 an error message on systems that do not support symbolic links.
10931 @optTargetDirectory
10933 @optNoTargetDirectory
10939 Print the name of each file after linking it successfully.
10943 @cindex hard links to symbolic links
10944 @cindex symbolic links and @command{ln}
10945 If @option{-L} and @option{-P} are both given, the last one takes
10946 precedence. If @option{-s} is also given, @option{-L} and @option{-P}
10947 are silently ignored. If neither option is given, then this
10948 implementation defaults to @option{-P} if the system @code{link} supports
10949 hard links to symbolic links (such as the GNU system), and @option{-L}
10950 if @code{link} follows symbolic links (such as on BSD).
10959 # Create link ../a pointing to a in that directory.
10960 # Not really useful because it points to itself.
10965 # Change to the target before creating symlinks to avoid being confused.
10971 # Hard coded file names don't move well.
10972 ln -s $(pwd)/a /some/dir/
10976 # Relative file names survive directory moves and also
10977 # work across networked file systems.
10978 ln -s afile anotherfile
10979 ln -s ../adir/afile yetanotherfile
10983 @node mkdir invocation
10984 @section @command{mkdir}: Make directories
10987 @cindex directories, creating
10988 @cindex creating directories
10990 @command{mkdir} creates directories with the specified names. Synopsis:
10993 mkdir [@var{option}]@dots{} @var{name}@dots{}
10996 @command{mkdir} creates each directory @var{name} in the order given.
10997 It reports an error if @var{name} already exists, unless the
10998 @option{-p} option is given and @var{name} is a directory.
11000 The program accepts the following options. Also see @ref{Common options}.
11004 @item -m @var{mode}
11005 @itemx --mode=@var{mode}
11008 @cindex modes of created directories, setting
11009 Set the file permission bits of created directories to @var{mode},
11010 which uses the same syntax as
11011 in @command{chmod} and uses @samp{a=rwx} (read, write and execute allowed for
11012 everyone) for the point of the departure. @xref{File permissions}.
11013 This option affects only directories given on the command line;
11014 it does not affect any parents that may be created via the @option{-p} option.
11016 Normally the directory has the desired file mode bits at the moment it
11017 is created. As a GNU extension, @var{mode} may also mention
11018 special mode bits, but in this case there may be a temporary window
11019 during which the directory exists but its special mode bits are
11020 incorrect. @xref{Directory Setuid and Setgid}, for how the
11021 set-user-ID and set-group-ID bits of directories are inherited unless
11022 overridden in this way.
11028 @cindex parent directories, creating
11029 Make any missing parent directories for each argument, setting their
11030 file permission bits to @samp{=rwx,u+wx},
11031 that is, with the umask modified by @samp{u+wx}. Ignore
11032 existing parent directories, and do not change their file permission
11035 If the @option{-m} option is also given, it does not affect
11036 file permission bits of any newly-created parent directories.
11037 To control these bits, set the
11038 umask before invoking @command{mkdir}. For example, if the shell
11039 command @samp{(umask u=rwx,go=rx; mkdir -p P/Q)} creates the parent
11040 @file{P} it sets the parent's file permission bits to @samp{u=rwx,go=rx}.
11041 (The umask must include @samp{u=wx} for this method to work.)
11042 To set a parent's special mode bits as well, you can invoke
11043 @command{chmod} after @command{mkdir}. @xref{Directory Setuid and
11044 Setgid}, for how the set-user-ID and set-group-ID bits of
11045 newly-created parent directories are inherited.
11051 Print a message for each created directory. This is most useful with
11052 @option{--parents}.
11061 @node mkfifo invocation
11062 @section @command{mkfifo}: Make FIFOs (named pipes)
11065 @cindex FIFOs, creating
11066 @cindex named pipes, creating
11067 @cindex creating FIFOs (named pipes)
11069 @command{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the
11070 specified names. Synopsis:
11073 mkfifo [@var{option}] @var{name}@dots{}
11076 A @dfn{FIFO} is a special file type that permits independent processes
11077 to communicate. One process opens the FIFO file for writing, and
11078 another for reading, after which data can flow as with the usual
11079 anonymous pipe in shells or elsewhere.
11081 The program accepts the following options. Also see @ref{Common options}.
11085 @item -m @var{mode}
11086 @itemx --mode=@var{mode}
11089 @cindex modes of created FIFOs, setting
11090 Set the mode of created FIFOs to @var{mode}, which is symbolic as in
11091 @command{chmod} and uses @samp{a=rw} (read and write allowed for everyone)
11092 for the point of departure. @var{mode} should specify only file
11093 permission bits. @xref{File permissions}.
11102 @node mknod invocation
11103 @section @command{mknod}: Make block or character special files
11106 @cindex block special files, creating
11107 @cindex character special files, creating
11109 @command{mknod} creates a FIFO, character special file, or block special
11110 file with the specified name. Synopsis:
11113 mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}]
11116 @cindex special files
11117 @cindex block special files
11118 @cindex character special files
11119 Unlike the phrase ``special file type'' above, the term @dfn{special
11120 file} has a technical meaning on Unix: something that can generate or
11121 receive data. Usually this corresponds to a physical piece of hardware,
11122 e.g., a printer or a flash drive. (These files are typically created at
11123 system-configuration time.) The @command{mknod} command is what creates
11124 files of this type. Such devices can be read either a character at a
11125 time or a ``block'' (many characters) at a time, hence we say there are
11126 @dfn{block special} files and @dfn{character special} files.
11128 @c mknod is a shell built-in at least with OpenBSD's /bin/sh
11129 @mayConflictWithShellBuiltIn{mknod}
11131 The arguments after @var{name} specify the type of file to make:
11136 @opindex p @r{for FIFO file}
11140 @opindex b @r{for block special file}
11141 for a block special file
11144 @c Don't document the 'u' option -- it's just a synonym for 'c'.
11145 @c Do *any* versions of mknod still use it?
11147 @opindex c @r{for character special file}
11148 @c @opindex u @r{for character special file}
11149 for a character special file
11153 When making a block or character special file, the major and minor
11154 device numbers must be given after the file type.
11155 If a major or minor device number begins with @samp{0x} or @samp{0X},
11156 it is interpreted as hexadecimal; otherwise, if it begins with @samp{0},
11157 as octal; otherwise, as decimal.
11159 The program accepts the following options. Also see @ref{Common options}.
11163 @item -m @var{mode}
11164 @itemx --mode=@var{mode}
11167 Set the mode of created files to @var{mode}, which is symbolic as in
11168 @command{chmod} and uses @samp{a=rw} as the point of departure.
11169 @var{mode} should specify only file permission bits.
11170 @xref{File permissions}.
11179 @node readlink invocation
11180 @section @command{readlink}: Print value of a symlink or canonical file name
11183 @cindex displaying value of a symbolic link
11184 @cindex canonical file name
11185 @cindex canonicalize a file name
11188 @command{readlink} may work in one of two supported modes:
11192 @item Readlink mode
11194 @command{readlink} outputs the value of the given symbolic links.
11195 If @command{readlink} is invoked with an argument other than the name
11196 of a symbolic link, it produces no output and exits with a nonzero exit code.
11198 @item Canonicalize mode
11200 @command{readlink} outputs the absolute name of the given files which contain
11201 no @file{.}, @file{..} components nor any repeated separators
11202 (@file{/}) or symbolic links. Note the @command{realpath} command is the
11203 preferred command to use for canonicalization. @xref{realpath invocation}.
11208 readlink [@var{option}]@dots{} @var{file}@dots{}
11211 By default, @command{readlink} operates in readlink mode.
11213 The program accepts the following options. Also see @ref{Common options}.
11218 @itemx --canonicalize
11220 @opindex --canonicalize
11221 Activate canonicalize mode.
11222 If any component of the file name except the last one is missing or unavailable,
11223 @command{readlink} produces no output and exits with a nonzero exit
11224 code. A trailing slash is ignored.
11227 @itemx --canonicalize-existing
11229 @opindex --canonicalize-existing
11230 Activate canonicalize mode.
11231 If any component is missing or unavailable, @command{readlink} produces
11232 no output and exits with a nonzero exit code. A trailing slash
11233 requires that the name resolve to a directory.
11236 @itemx --canonicalize-missing
11238 @opindex --canonicalize-missing
11239 Activate canonicalize mode.
11240 If any component is missing or unavailable, @command{readlink} treats it
11244 @itemx --no-newline
11246 @opindex --no-newline
11247 Do not print the output delimiter, when a single @var{file} is specified.
11248 Print a warning if specified along with multiple @var{file}s.
11258 Suppress most error messages. On by default.
11264 Report error messages.
11270 The @command{readlink} utility first appeared in OpenBSD 2.1.
11272 The @command{realpath} command without options, operates like
11273 @command{readlink} in canonicalize mode.
11278 @node rmdir invocation
11279 @section @command{rmdir}: Remove empty directories
11282 @cindex removing empty directories
11283 @cindex directories, removing empty
11285 @command{rmdir} removes empty directories. Synopsis:
11288 rmdir [@var{option}]@dots{} @var{directory}@dots{}
11291 If any @var{directory} argument does not refer to an existing empty
11292 directory, it is an error.
11294 The program accepts the following options. Also see @ref{Common options}.
11298 @item --ignore-fail-on-non-empty
11299 @opindex --ignore-fail-on-non-empty
11300 @cindex directory deletion, ignoring failures
11301 Ignore each failure to remove a directory that is non-empty.
11307 @cindex parent directories, removing
11308 Remove @var{directory}, then try to remove each component of @var{directory}.
11309 So, for example, @samp{rmdir -p a/b/c} is similar to @samp{rmdir a/b/c a/b a}.
11310 As such, it fails if any of those directories turns out not to be empty.
11311 Use the @option{--ignore-fail-on-non-empty} option to make it so such
11312 a failure does not evoke a diagnostic and does not cause @command{rmdir} to
11313 exit unsuccessfully.
11319 @cindex directory deletion, reporting
11320 Give a diagnostic for each successful removal.
11321 @var{directory} is removed.
11325 @xref{rm invocation}, for how to remove non-empty directories recursively.
11327 To remove all empty directories under @var{dirname}, including
11328 directories that become empty because other directories are removed,
11329 you can use either of the following commands:
11332 # This uses GNU extensions.
11333 find @var{dirname} -type d -empty -delete
11335 # This runs on any POSIX platform.
11336 find @var{dirname} -depth -type d -exec rmdir @{@} +
11342 @node unlink invocation
11343 @section @command{unlink}: Remove files via the unlink syscall
11346 @cindex removing files or directories (via the unlink syscall)
11348 @command{unlink} deletes a single specified file name.
11349 It is a minimalist interface to the system-provided
11350 @code{unlink} function. @xref{Deleting Files, , , libc,
11351 The GNU C Library Reference Manual}. Synopsis:
11352 It avoids the bells and whistles of the more commonly-used
11353 @command{rm} command (@pxref{rm invocation}).
11356 unlink @var{filename}
11359 On some systems @code{unlink} can be used to delete the name of a
11360 directory. On others, it can be used that way only by a privileged user.
11361 In the GNU system @code{unlink} can never delete the name of a directory.
11363 The @command{unlink} command honors the @option{--help} and
11364 @option{--version} options. To remove a file whose name begins with
11365 @samp{-}, prefix the name with @samp{./}, e.g., @samp{unlink ./--help}.
11370 @node Changing file attributes
11371 @chapter Changing file attributes
11373 @cindex changing file attributes
11374 @cindex file attributes, changing
11375 @cindex attributes, file
11377 A file is not merely its contents, a name, and a file type
11378 (@pxref{Special file types}). A file also has an owner (a user ID), a
11379 group (a group ID), permissions (what the owner can do with the file,
11380 what people in the group can do, and what everyone else can do), various
11381 timestamps, and other information. Collectively, we call these a file's
11384 These commands change file attributes.
11387 * chown invocation:: Change file owners and groups.
11388 * chgrp invocation:: Change file groups.
11389 * chmod invocation:: Change access permissions.
11390 * touch invocation:: Change file timestamps.
11394 @node chown invocation
11395 @section @command{chown}: Change file owner and group
11398 @cindex file ownership, changing
11399 @cindex group ownership, changing
11400 @cindex changing file ownership
11401 @cindex changing group ownership
11403 @command{chown} changes the user and/or group ownership of each given @var{file}
11404 to @var{new-owner} or to the user and group of an existing reference file.
11408 chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@}@c
11412 If used, @var{new-owner} specifies the new owner and/or group as follows
11413 (with no embedded white space):
11416 [@var{owner}] [ : [@var{group}] ]
11423 If only an @var{owner} (a user name or numeric user ID) is given, that
11424 user is made the owner of each given file, and the files' group is not
11427 @item owner@samp{:}group
11428 If the @var{owner} is followed by a colon and a @var{group} (a
11429 group name or numeric group ID), with no spaces between them, the group
11430 ownership of the files is changed as well (to @var{group}).
11432 @item owner@samp{:}
11433 If a colon but no group name follows @var{owner}, that user is
11434 made the owner of the files and the group of the files is changed to
11435 @var{owner}'s login group.
11437 @item @samp{:}group
11438 If the colon and following @var{group} are given, but the owner
11439 is omitted, only the group of the files is changed; in this case,
11440 @command{chown} performs the same function as @command{chgrp}.
11443 If only a colon is given, or if @var{new-owner} is empty, neither the
11444 owner nor the group is changed.
11448 If @var{owner} or @var{group} is intended to represent a numeric user
11449 or group ID, then you may specify it with a leading @samp{+}.
11450 @xref{Disambiguating names and IDs}.
11452 Some older scripts may still use @samp{.} in place of the @samp{:} separator.
11453 POSIX 1003.1-2001 (@pxref{Standards conformance}) does not
11454 require support for that, but for backward compatibility GNU
11455 @command{chown} supports @samp{.} so long as no ambiguity results,
11456 although it issues a warning and support may be removed in future versions.
11457 New scripts should avoid the use of @samp{.} because it is not
11458 portable, and because it has undesirable results if the entire
11459 @var{owner@samp{.}group} happens to identify a user whose name
11462 @macro chownGroupRestrictions
11463 It is system dependent whether a user can change the group to an arbitrary one,
11464 or the more portable behavior of being restricted to setting a group of
11465 which the user is a member.
11467 @chownGroupRestrictions
11469 The @command{chown} command sometimes clears the set-user-ID or
11470 set-group-ID permission bits. This behavior depends on the policy and
11471 functionality of the underlying @code{chown} system call, which may
11472 make system-dependent file mode modifications outside the control of
11473 the @command{chown} command. For example, the @command{chown} command
11474 might not affect those bits when invoked by a user with appropriate
11475 privileges, or when the
11476 bits signify some function other than executable permission (e.g.,
11477 mandatory locking).
11478 When in doubt, check the underlying system behavior.
11480 The program accepts the following options. Also see @ref{Common options}.
11488 @cindex changed owners, verbosely describing
11489 Verbosely describe the action for each @var{file} whose ownership
11498 @cindex error messages, omitting
11499 Do not print error messages about files whose ownership cannot be
11502 @item --from=@var{old-owner}
11504 @cindex symbolic links, changing owner
11505 Change a @var{file}'s ownership only if it has current attributes specified
11506 by @var{old-owner}. @var{old-owner} has the same form as @var{new-owner}
11508 This option is useful primarily from a security standpoint in that
11509 it narrows considerably the window of potential abuse.
11510 For example, to reflect a user ID numbering change for one user's files
11511 without an option like this, @code{root} might run
11514 find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER
11517 But that is dangerous because the interval between when the @command{find}
11518 tests the existing file's owner and when the @command{chown} is actually run
11519 may be quite large.
11520 One way to narrow the gap would be to invoke chown for each file
11524 find / -owner OLDUSER -exec chown -h NEWUSER @{@} \;
11527 But that is very slow if there are many affected files.
11528 With this option, it is safer (the gap is narrower still)
11529 though still not perfect:
11532 chown -h -R --from=OLDUSER NEWUSER /
11535 @item --dereference
11536 @opindex --dereference
11537 @cindex symbolic links, changing owner
11539 Do not act on symbolic links themselves but rather on what they point to.
11540 This is the default when not operating recursively.
11541 @warnOptDerefWithRec
11544 @itemx --no-dereference
11546 @opindex --no-dereference
11547 @cindex symbolic links, changing owner
11549 Act on symbolic links themselves instead of what they point to.
11550 This mode relies on the @code{lchown} system call.
11551 On systems that do not provide the @code{lchown} system call,
11552 @command{chown} fails when a file specified on the command line
11553 is a symbolic link.
11554 By default, no diagnostic is issued for symbolic links encountered
11555 during a recursive traversal, but see @option{--verbose}.
11557 @item --preserve-root
11558 @opindex --preserve-root
11559 @cindex root directory, disallow recursive modification
11560 Fail upon any attempt to recursively change the root directory, @file{/}.
11561 Without @option{--recursive}, this option has no effect.
11562 @xref{Treating / specially}.
11564 @item --no-preserve-root
11565 @opindex --no-preserve-root
11566 @cindex root directory, allow recursive modification
11567 Cancel the effect of any preceding @option{--preserve-root} option.
11568 @xref{Treating / specially}.
11570 @item --reference=@var{ref_file}
11571 @opindex --reference
11572 Change the user and group of each @var{file} to be the same as those of
11573 @var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
11574 user and group of the symbolic link, but rather those of the file it
11581 Output a diagnostic for every file processed.
11582 If a symbolic link is encountered during a recursive traversal
11583 on a system without the @code{lchown} system call, and @option{--no-dereference}
11584 is in effect, then issue a diagnostic saying neither the symbolic link nor
11585 its referent is being changed.
11590 @opindex --recursive
11591 @cindex recursively changing file ownership
11592 Recursively change ownership of directories and their contents.
11595 @xref{Traversing symlinks}.
11598 @warnOptDerefWithRec
11599 @xref{Traversing symlinks}.
11602 @xref{Traversing symlinks}.
11611 # Change the owner of /u to "root".
11614 # Likewise, but also change its group to "staff".
11615 chown root:staff /u
11617 # Change the owner of /u and subfiles to "root".
11622 @node chgrp invocation
11623 @section @command{chgrp}: Change group ownership
11626 @cindex group ownership, changing
11627 @cindex changing group ownership
11629 @command{chgrp} changes the group ownership of each given @var{file}
11630 to @var{group} (which can be either a group name or a numeric group ID)
11631 or to the group of an existing reference file. @xref{chown invocation}.
11635 chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@}@c
11639 If @var{group} is intended to represent a
11640 numeric group ID, then you may specify it with a leading @samp{+}.
11641 @xref{Disambiguating names and IDs}.
11643 @chownGroupRestrictions
11645 The program accepts the following options. Also see @ref{Common options}.
11653 @cindex changed files, verbosely describing
11654 Verbosely describe the action for each @var{file} whose group actually
11663 @cindex error messages, omitting
11664 Do not print error messages about files whose group cannot be
11667 @item --dereference
11668 @opindex --dereference
11669 @cindex symbolic links, changing owner
11671 Do not act on symbolic links themselves but rather on what they point to.
11672 This is the default when not operating recursively.
11673 @warnOptDerefWithRec
11676 @itemx --no-dereference
11678 @opindex --no-dereference
11679 @cindex symbolic links, changing group
11681 Act on symbolic links themselves instead of what they point to.
11682 This mode relies on the @code{lchown} system call.
11683 On systems that do not provide the @code{lchown} system call,
11684 @command{chgrp} fails when a file specified on the command line
11685 is a symbolic link.
11686 By default, no diagnostic is issued for symbolic links encountered
11687 during a recursive traversal, but see @option{--verbose}.
11689 @item --preserve-root
11690 @opindex --preserve-root
11691 @cindex root directory, disallow recursive modification
11692 Fail upon any attempt to recursively change the root directory, @file{/}.
11693 Without @option{--recursive}, this option has no effect.
11694 @xref{Treating / specially}.
11696 @item --no-preserve-root
11697 @opindex --no-preserve-root
11698 @cindex root directory, allow recursive modification
11699 Cancel the effect of any preceding @option{--preserve-root} option.
11700 @xref{Treating / specially}.
11702 @item --reference=@var{ref_file}
11703 @opindex --reference
11704 Change the group of each @var{file} to be the same as that of
11705 @var{ref_file}. If @var{ref_file} is a symbolic link, do not use the
11706 group of the symbolic link, but rather that of the file it refers to.
11712 Output a diagnostic for every file processed.
11713 If a symbolic link is encountered during a recursive traversal
11714 on a system without the @code{lchown} system call, and @option{--no-dereference}
11715 is in effect, then issue a diagnostic saying neither the symbolic link nor
11716 its referent is being changed.
11721 @opindex --recursive
11722 @cindex recursively changing group ownership
11723 Recursively change the group ownership of directories and their contents.
11726 @xref{Traversing symlinks}.
11729 @warnOptDerefWithRec
11730 @xref{Traversing symlinks}.
11733 @xref{Traversing symlinks}.
11742 # Change the group of /u to "staff".
11745 # Change the group of /u and subfiles to "staff".
11750 @node chmod invocation
11751 @section @command{chmod}: Change access permissions
11754 @cindex changing access permissions
11755 @cindex access permissions, changing
11756 @cindex permissions, changing access
11758 @command{chmod} changes the access permissions of the named files. Synopsis:
11761 chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@}@c
11765 @cindex symbolic links, permissions of
11766 @command{chmod} never changes the permissions of symbolic links, since
11767 the @command{chmod} system call cannot change their permissions.
11768 This is not a problem since the permissions of symbolic links are
11769 never used. However, for each symbolic link listed on the command
11770 line, @command{chmod} changes the permissions of the pointed-to file.
11771 In contrast, @command{chmod} ignores symbolic links encountered during
11772 recursive directory traversals.
11774 Only a process whose effective user ID matches the user ID of the file,
11775 or a process with appropriate privileges, is permitted to change the
11776 file mode bits of a file.
11778 A successful use of @command{chmod} clears the set-group-ID bit of a
11779 regular file if the file's group ID does not match the user's
11780 effective group ID or one of the user's supplementary group IDs,
11781 unless the user has appropriate privileges. Additional restrictions
11782 may cause the set-user-ID and set-group-ID bits of @var{mode} or
11783 @var{ref_file} to be ignored. This behavior depends on the policy and
11784 functionality of the underlying @code{chmod} system call. When in
11785 doubt, check the underlying system behavior.
11787 If used, @var{mode} specifies the new file mode bits.
11788 For details, see the section on @ref{File permissions}.
11789 If you really want @var{mode} to have a leading @samp{-}, you should
11790 use @option{--} first, e.g., @samp{chmod -- -w file}. Typically,
11791 though, @samp{chmod a-w file} is preferable, and @command{chmod -w
11792 file} (without the @option{--}) complains if it behaves differently
11793 from what @samp{chmod a-w file} would do.
11795 The program accepts the following options. Also see @ref{Common options}.
11803 Verbosely describe the action for each @var{file} whose permissions
11812 @cindex error messages, omitting
11813 Do not print error messages about files whose permissions cannot be
11816 @item --preserve-root
11817 @opindex --preserve-root
11818 @cindex root directory, disallow recursive modification
11819 Fail upon any attempt to recursively change the root directory, @file{/}.
11820 Without @option{--recursive}, this option has no effect.
11821 @xref{Treating / specially}.
11823 @item --no-preserve-root
11824 @opindex --no-preserve-root
11825 @cindex root directory, allow recursive modification
11826 Cancel the effect of any preceding @option{--preserve-root} option.
11827 @xref{Treating / specially}.
11833 Verbosely describe the action or non-action taken for every @var{file}.
11835 @item --reference=@var{ref_file}
11836 @opindex --reference
11837 Change the mode of each @var{file} to be the same as that of @var{ref_file}.
11838 @xref{File permissions}.
11839 If @var{ref_file} is a symbolic link, do not use the mode
11840 of the symbolic link, but rather that of the file it refers to.
11845 @opindex --recursive
11846 @cindex recursively changing access permissions
11847 Recursively change permissions of directories and their contents.
11856 # Change file permissions of FOO to be world readable
11857 # and user writable, with no other permissions.
11861 # Add user and group execute permissions to FOO.
11865 # Set file permissions of DIR and subsidiary files to
11866 # be the umask default, assuming execute permissions for
11867 # directories and for files already executable.
11868 chmod -R a=,+rwX dir
11872 @node touch invocation
11873 @section @command{touch}: Change file timestamps
11876 @cindex changing file timestamps
11877 @cindex file timestamps, changing
11878 @cindex timestamps, changing file
11880 @command{touch} changes the access and/or modification timestamps of the
11881 specified files. Synopsis:
11884 touch [@var{option}]@dots{} @var{file}@dots{}
11887 @cindex empty files, creating
11888 Any @var{file} argument that does not exist is created empty, unless
11889 option @option{--no-create} (@option{-c}) or @option{--no-dereference}
11890 (@option{-h}) was in effect.
11892 A @var{file} argument string of @samp{-} is handled specially and
11893 causes @command{touch} to change the times of the file associated with
11896 By default, @command{touch} sets file timestamps to the current time.
11897 Because @command{touch} acts on its operands left to right, the
11898 resulting timestamps of earlier and later operands may disagree.
11900 @cindex permissions, for changing file timestamps
11901 When setting file timestamps to the current time, @command{touch} can
11902 change the timestamps for files that the user does not own but has
11903 write permission for. Otherwise, the user must own the files. Some
11904 older systems have a further restriction: the user must own the files
11905 unless both the access and modification timestamps are being set to the
11908 The @command{touch} command cannot set a file's status change timestamp to
11909 a user-specified value, and cannot change the file's birth time (if
11910 supported) at all. Also, @command{touch} has issues similar to those
11911 affecting all programs that update file timestamps. For example,
11912 @command{touch} may set a file's timestamp to a value that differs
11913 slightly from the requested time. @xref{File timestamps}.
11916 Timestamps assume the time zone rules specified by the @env{TZ}
11917 environment variable, or by the system default rules if @env{TZ} is
11918 not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ},
11919 libc, The GNU C Library Reference Manual}.
11920 You can avoid ambiguities during
11921 daylight saving transitions by using UTC timestamps.
11923 The program accepts the following options. Also see @ref{Common options}.
11928 @itemx --time=atime
11929 @itemx --time=access
11933 @opindex atime@r{, changing}
11934 @opindex access @r{time, changing}
11935 @opindex use @r{time, changing}
11936 Change the access timestamp only. @xref{File timestamps}.
11941 @opindex --no-create
11942 Do not warn about or create files that do not exist.
11944 @item -d @var{time}
11945 @itemx --date=@var{time}
11949 Use @var{time} instead of the current time. It can contain month names,
11950 time zones, @samp{am} and @samp{pm}, @samp{yesterday}, etc. For
11951 example, @option{--date="2020-07-21 14:19:13.489392193 +0530"}
11952 specifies the instant of time that is 489,392,193 nanoseconds after
11953 July 21, 2020 at 2:19:13 PM in a time zone that is 5 hours and 30
11954 minutes east of UTC@. @xref{Date input formats}.
11955 File systems that do not support high-resolution timestamps
11956 silently ignore any excess precision here.
11960 @cindex BSD @command{touch} compatibility
11961 Ignored; for compatibility with BSD versions of @command{touch}.
11964 @itemx --no-dereference
11966 @opindex --no-dereference
11967 @cindex symbolic links, changing time
11969 Attempt to change the timestamps of a symbolic link, rather than what
11970 the link refers to. When using this option, empty files are not
11971 created, but option @option{-c} must also be used to avoid warning
11972 about files that do not exist. Not all systems support changing the
11973 timestamps of symlinks, since underlying system support for this
11974 action was not required until POSIX 2008. Also, on some
11975 systems, the mere act of examining a symbolic link changes the access
11976 timestamp, such that only changes to the modification timestamp will persist
11977 long enough to be observable. When coupled with option @option{-r}, a
11978 reference timestamp is taken from a symbolic link rather than the file
11982 @itemx --time=mtime
11983 @itemx --time=modify
11986 @opindex mtime@r{, changing}
11987 @opindex modify @r{time, changing}
11988 Change the modification timestamp only.
11990 @item -r @var{file}
11991 @itemx --reference=@var{file}
11993 @opindex --reference
11994 Use the times of the reference @var{file} instead of the current time.
11995 If this option is combined with the @option{--date=@var{time}}
11996 (@option{-d @var{time}}) option, the reference @var{file}'s time is
11997 the origin for any relative @var{time}s given, but is otherwise ignored.
11998 For example, @samp{-r foo -d '-5 seconds'} specifies a timestamp
11999 equal to five seconds before the corresponding timestamp for @file{foo}.
12000 If @var{file} is a symbolic link, the reference timestamp is taken
12001 from the target of the symlink, unless @option{-h} was also in effect.
12003 @item -t [[@var{cc}]@var{yy}]@var{mmddhhmm}[.@var{ss}]
12004 @cindex leap seconds
12005 Use the argument (optional four-digit or two-digit years, months,
12006 days, hours, minutes, optional seconds) instead of the current time.
12007 If the year is specified with only two digits, then @var{cc}
12008 is 20 for years in the range 0 @dots{} 68, and 19 for years in
12009 69 @dots{} 99. If no digits of the year are specified,
12010 the argument is interpreted as a date in the current year.
12011 On the atypical systems that support leap seconds, @var{ss} may be
12016 @vindex _POSIX2_VERSION
12017 On systems predating POSIX 1003.1-2001,
12018 @command{touch} supports an obsolete syntax, as follows.
12019 If no timestamp is given with any of the @option{-d}, @option{-r}, or
12020 @option{-t} options, and if there are two or more @var{file}s and the
12021 first @var{file} is of the form @samp{@var{mmddhhmm}[@var{yy}]} and this
12022 would be a valid argument to the @option{-t} option (if the @var{yy}, if
12023 any, were moved to the front), and if the represented year
12024 is in the range 1969--1999, that argument is interpreted as the time
12025 for the other files instead of as a file name.
12026 Although this obsolete behavior can be controlled with the
12027 @env{_POSIX2_VERSION} environment variable (@pxref{Standards
12028 conformance}), portable scripts should avoid commands whose
12029 behavior depends on this variable.
12030 For example, use @samp{touch ./12312359 main.c} or @samp{touch -t
12031 12312359 main.c} rather than the ambiguous @samp{touch 12312359 main.c}.
12036 @node File space usage
12037 @chapter File space usage
12039 @cindex File space usage
12042 No file system can hold an infinite amount of data. These commands report
12043 how much storage is in use or available, report other file and
12044 file status information, and write buffers to file systems.
12047 * df invocation:: Report file system space usage.
12048 * du invocation:: Estimate file space usage.
12049 * stat invocation:: Report file or file system status.
12050 * sync invocation:: Synchronize cached writes to persistent storage.
12051 * truncate invocation:: Shrink or extend the size of a file.
12055 @node df invocation
12056 @section @command{df}: Report file system space usage
12059 @cindex file system usage
12060 @cindex disk usage by file system
12062 @command{df} reports the amount of space used and available on
12063 file systems. Synopsis:
12066 df [@var{option}]@dots{} [@var{file}]@dots{}
12069 With no arguments, @command{df} reports the space used and available on all
12070 currently mounted file systems (of all types). Otherwise, @command{df}
12071 reports on the file system containing each argument @var{file}.
12073 Normally the space is printed in units of
12074 1024 bytes, but this can be overridden (@pxref{Block size}).
12075 Non-integer quantities are rounded up to the next higher unit.
12077 For bind mounts and without arguments, @command{df} only outputs the statistics
12078 for that device with the shortest mount point name in the list of file systems
12079 (@var{mtab}), i.e., it hides duplicate entries, unless the @option{-a} option is
12082 With the same logic, @command{df} elides a mount entry of a dummy pseudo device
12083 if there is another mount entry of a real block device for that mount point with
12084 the same device number, e.g. the early-boot pseudo file system @samp{rootfs} is
12085 not shown per default when already the real root device has been mounted.
12087 @cindex disk device file
12088 @cindex device file
12089 If an argument @var{file} resolves to a special file containing
12090 a mounted file system, @command{df} shows the space available on that
12091 file system rather than on the file system containing the device node.
12092 GNU @command{df} does not attempt to determine the usage
12093 on unmounted file systems, because on most kinds of systems doing so
12094 requires extremely nonportable intimate knowledge of file system structures.
12096 The program accepts the following options. Also see @ref{Common options}.
12104 @cindex ignore file systems
12105 Include in the listing dummy, duplicate, or inaccessible file systems, which
12106 are omitted by default. Dummy file systems are typically special purpose
12107 pseudo file systems such as @samp{/proc}, with no associated storage.
12108 Duplicate file systems are local or remote file systems that are mounted
12109 at separate locations in the local file hierarchy, or bind mounted locations.
12110 Inaccessible file systems are those which are mounted but subsequently
12111 over-mounted by another file system at that point, or otherwise inaccessible
12112 due to permissions of the mount point etc.
12114 @item -B @var{size}
12115 @itemx --block-size=@var{size}
12117 @opindex --block-size
12118 @cindex file system sizes
12119 Scale sizes by @var{size} before printing them (@pxref{Block size}).
12120 For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
12126 Equivalent to @option{--si}.
12132 @cindex inode usage
12133 List inode usage information instead of block usage. An inode (short
12134 for index node) contains information about a file such as its owner,
12135 permissions, timestamps, and location on the file system.
12139 @cindex kibibytes for file system sizes
12140 Print sizes in 1024-byte blocks, overriding the default block size
12141 (@pxref{Block size}).
12142 This option is equivalent to @option{--block-size=1K}.
12148 @cindex file system types, limiting output to certain
12149 Limit the listing to local file systems. By default, remote file systems
12154 @cindex file system space, retrieving old data more quickly
12155 Do not invoke the @code{sync} system call before getting any usage data.
12156 This may make @command{df} run significantly faster on systems with many
12157 file systems, but on some systems (notably Solaris) the results may be slightly
12158 out of date. This is the default.
12161 @itemx --output[=@var{field_list}]
12163 Use the output format defined by @var{field_list}, or print all fields if
12164 @var{field_list} is omitted. In the latter case, the order of the columns
12165 conforms to the order of the field descriptions below.
12167 The use of the @option{--output} together with each of the options @option{-i},
12168 @option{-P}, and @option{-T} is mutually exclusive.
12170 FIELD_LIST is a comma-separated list of columns to be included in @command{df}'s
12171 output and therefore effectively controls the order of output columns.
12172 Each field can thus be used at the place of choice, but yet must only be
12175 Valid field names in the @var{field_list} are:
12178 The source of the mount point, usually a device.
12183 Total number of inodes.
12185 Number of used inodes.
12187 Number of available inodes.
12189 Percentage of @var{iused} divided by @var{itotal}.
12192 Total number of blocks.
12194 Number of used blocks.
12196 Number of available blocks.
12198 Percentage of @var{used} divided by @var{size}.
12201 The file name if specified on the command line.
12206 The fields for block and inodes statistics are affected by the scaling
12207 options like @option{-h} as usual.
12209 The definition of the @var{field_list} can even be split among several
12210 @option{--output} uses.
12214 # Print the TARGET (i.e., the mount point) along with their percentage
12215 # statistic regarding the blocks and the inodes.
12216 df --out=target --output=pcent,ipcent
12218 # Print all available fields.
12224 @itemx --portability
12226 @opindex --portability
12227 @cindex one-line output format
12228 @cindex POSIX output format
12229 @cindex portable output format
12230 @cindex output format, portable
12231 Use the POSIX output format. This is like the default format except
12236 The information about each file system is always printed on exactly
12237 one line; a mount device is never put on a line by itself. This means
12238 that if the mount device name is more than 20 characters long (e.g., for
12239 some network mounts), the columns are misaligned.
12242 The labels in the header output line are changed to conform to POSIX.
12245 The default block size and output format are unaffected by the
12246 @env{DF_BLOCK_SIZE}, @env{BLOCK_SIZE} and @env{BLOCKSIZE} environment
12247 variables. However, the default block size is still affected by
12248 @env{POSIXLY_CORRECT}: it is 512 if @env{POSIXLY_CORRECT} is set, 1024
12249 otherwise. @xref{Block size}.
12256 @cindex file system space, retrieving current data more slowly
12257 Invoke the @code{sync} system call before getting any usage data. On
12258 some systems (notably Solaris), doing this yields more up to date results,
12259 but in general this option makes @command{df} much slower, especially when
12260 there are many or very busy file systems.
12264 @cindex grand total of file system size, usage and available space
12265 Print a grand total of all arguments after all arguments have
12266 been processed. This can be used to find out the total size, usage
12267 and available space of all listed devices. If no arguments are specified
12268 df will try harder to elide file systems insignificant to the total
12269 available space, by suppressing duplicate remote file systems.
12271 For the grand total line, @command{df} prints @samp{"total"} into the
12272 @var{source} column, and @samp{"-"} into the @var{target} column.
12273 If there is no @var{source} column (see @option{--output}), then
12274 @command{df} prints @samp{"total"} into the @var{target} column,
12277 @item -t @var{fstype}
12278 @itemx --type=@var{fstype}
12281 @cindex file system types, limiting output to certain
12282 Limit the listing to file systems of type @var{fstype}. Multiple
12283 file system types can be specified by giving multiple @option{-t} options.
12284 By default, nothing is omitted.
12287 @itemx --print-type
12289 @opindex --print-type
12290 @cindex file system types, printing
12291 Print each file system's type. The types printed here are the same ones
12292 you can include or exclude with @option{-t} and @option{-x}. The particular
12293 types printed are whatever is supported by the system. Here are some of
12294 the common names (this list is certainly not exhaustive):
12299 @cindex NFS file system type
12300 An NFS file system, i.e., one mounted over a network from another
12301 machine. This is the one type name which seems to be used uniformly by
12304 @item ext2@r{, }ext3@r{, }ext4@r{, }xfs@r{, }btrfs@dots{}
12305 @cindex Linux file system types
12306 @cindex local file system types
12307 @opindex ext2 @r{file system type}
12308 @opindex ext3 @r{file system type}
12309 @opindex ext4 @r{file system type}
12310 @opindex xfs @r{file system type}
12311 @opindex btrfs @r{file system type}
12312 A file system on a locally-mounted device. (The system might even
12313 support more than one type here; GNU/Linux does.)
12315 @item iso9660@r{, }cdfs
12316 @cindex CD-ROM file system type
12317 @cindex DVD file system type
12318 @cindex ISO9660 file system type
12319 @opindex iso9660 @r{file system type}
12320 @opindex cdfs @r{file system type}
12321 A file system on a CD or DVD drive. HP-UX uses @samp{cdfs}, most other
12322 systems use @samp{iso9660}.
12325 @cindex NTFS file system
12326 @cindex DOS file system
12327 @cindex MS-DOS file system
12328 @cindex MS-Windows file system
12329 @opindex ntfs @r{file system file}
12330 @opindex fat @r{file system file}
12331 File systems used by MS-Windows / MS-DOS.
12335 @item -x @var{fstype}
12336 @itemx --exclude-type=@var{fstype}
12338 @opindex --exclude-type
12339 Limit the listing to file systems not of type @var{fstype}.
12340 Multiple file system types can be eliminated by giving multiple
12341 @option{-x} options. By default, no file system types are omitted.
12344 Ignored; for compatibility with System V versions of @command{df}.
12348 @command{df} is installed only on systems that have usable mount tables,
12349 so portable scripts should not rely on its existence.
12352 Failure includes the case where no output is generated, so you can
12353 inspect the exit status of a command like @samp{df -t ext3 -t reiserfs
12354 @var{dir}} to test whether @var{dir} is on a file system of type
12355 @samp{ext3} or @samp{reiserfs}.
12357 Since the list of file systems (@var{mtab}) is needed to determine the
12358 file system type, failure includes the cases when that list cannot
12359 be read and one or more of the options @option{-a}, @option{-l}, @option{-t}
12360 or @option{-x} is used together with a file name argument.
12363 @node du invocation
12364 @section @command{du}: Estimate file space usage
12367 @cindex file space usage
12368 @cindex disk usage for files
12370 @command{du} reports the space needed to represent a set of files.
12374 du [@var{option}]@dots{} [@var{file}]@dots{}
12377 With no arguments, @command{du} reports the space needed to represent
12378 the files at or under the current directory.
12379 Normally the space is printed in units of
12380 1024 bytes, but this can be overridden (@pxref{Block size}).
12381 Non-integer quantities are rounded up to the next higher unit.
12383 If two or more hard links point to the same file, only one of the hard
12384 links is counted. The @var{file} argument order affects which links
12385 are counted, and changing the argument order may change the numbers
12386 and entries that @command{du} outputs.
12388 The program accepts the following options. Also see @ref{Common options}.
12398 Show counts for all files, not just directories.
12400 @item --apparent-size
12401 @opindex --apparent-size
12402 Print apparent sizes, rather than file system usage. The apparent size of a
12403 file is the number of bytes reported by @code{wc -c} on regular files,
12404 or more generally, @code{ls -l --block-size=1} or @code{stat --format=%s}.
12405 For example, a file containing the word @samp{zoo} with no newline would,
12406 of course, have an apparent size of 3. Such a small file may require
12407 anywhere from 0 to 16 KiB or more of file system space, depending on
12408 the type and configuration of the file system on which the file resides.
12409 However, a sparse file created with this command:
12412 dd bs=1 seek=2GiB if=/dev/null of=big
12416 has an apparent size of 2 GiB, yet on most modern
12417 file systems, it actually uses almost no space.
12419 @item -B @var{size}
12420 @itemx --block-size=@var{size}
12422 @opindex --block-size
12424 Scale sizes by @var{size} before printing them (@pxref{Block size}).
12425 For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
12431 Equivalent to @code{--apparent-size --block-size=1}.
12437 @cindex grand total of file system space
12438 Print a grand total of all arguments after all arguments have
12439 been processed. This can be used to find out the total file system usage of
12440 a given set of files or directories.
12443 @itemx --dereference-args
12445 @opindex --dereference-args
12446 Dereference symbolic links that are command line arguments.
12447 Does not affect other symbolic links. This is helpful for finding
12448 out the file system usage of directories, such as @file{/usr/tmp}, which
12449 are often symbolic links.
12451 @item -d @var{depth}
12452 @itemx --max-depth=@var{depth}
12453 @opindex -d @var{depth}
12454 @opindex --max-depth=@var{depth}
12455 @cindex limiting output of @command{du}
12456 Show the total for each directory (and file if @option{--all}) that is at
12457 most MAX_DEPTH levels down from the root of the hierarchy. The root
12458 is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}.
12460 @c --files0-from=FILE
12461 @filesZeroFromOption{du,, with the @option{--total} (@option{-c}) option}
12465 Equivalent to @option{--dereference-args} (@option{-D}).
12471 @cindex inode usage, dereferencing in @command{du}
12472 List inode usage information instead of block usage.
12473 This option is useful for finding directories which contain many files, and
12474 therefore eat up most of the inodes space of a file system (see @command{df},
12475 option @option{--inodes}).
12476 It can well be combined with the options @option{-a}, @option{-c},
12477 @option{-h}, @option{-l}, @option{-s}, @option{-S}, @option{-t} and
12478 @option{-x}; however, passing other options regarding the block size, for
12479 example @option{-b}, @option{-m} and @option{--apparent-size}, is ignored.
12483 @cindex kibibytes for file sizes
12484 Print sizes in 1024-byte blocks, overriding the default block size
12485 (@pxref{Block size}).
12486 This option is equivalent to @option{--block-size=1K}.
12489 @itemx --dereference
12491 @opindex --dereference
12492 @cindex symbolic links, dereferencing in @command{du}
12493 Dereference symbolic links (show the file system space used by the file
12494 or directory that the link points to instead of the space used by
12498 @itemx --count-links
12500 @opindex --count-links
12501 @cindex hard links, counting in @command{du}
12502 Count the size of all files, even if they have appeared already (as a
12507 @cindex mebibytes for file sizes
12508 Print sizes in 1,048,576-byte blocks, overriding the default block size
12509 (@pxref{Block size}).
12510 This option is equivalent to @option{--block-size=1M}.
12513 @itemx --no-dereference
12515 @opindex --no-dereference
12516 @cindex symbolic links, dereferencing in @command{du}
12517 For each symbolic link encountered by @command{du},
12518 consider the file system space used by the symbolic link itself.
12521 @itemx --separate-dirs
12523 @opindex --separate-dirs
12524 Normally, in the output of @command{du} (when not using @option{--summarize}),
12525 the size listed next to a directory name, @var{d}, represents the sum
12526 of sizes of all entries beneath @var{d} as well as the size of @var{d} itself.
12527 With @option{--separate-dirs}, the size reported for a directory name,
12528 @var{d}, will exclude the size of any subdirectories.
12535 @opindex --summarize
12536 Display only a total for each argument.
12538 @item -t @var{size}
12539 @itemx --threshold=@var{size}
12541 @opindex --threshold
12542 Exclude entries based on a given @var{size}. The @var{size} refers to used
12543 blocks in normal mode (@pxref{Block size}), or inodes count in conjunction
12544 with the @option{--inodes} option.
12546 If @var{size} is positive, then @command{du} will only print entries with a size
12547 greater than or equal to that.
12549 If @var{size} is negative, then @command{du} will only print entries with a size
12550 smaller than or equal to that.
12552 Although GNU @command{find} can be used to find files of a certain size,
12553 @command{du}'s @option{--threshold} option can be used to also filter
12554 directories based on a given size.
12556 When combined with the @option{--apparent-size} option, the
12557 @option{--threshold} option elides entries based on apparent size.
12558 When combined with the @option{--inodes} option, it elides entries
12559 based on inode counts.
12561 Here's how you would use @option{--threshold} to find directories with a size
12562 greater than or equal to 200 megabytes:
12565 du --threshold=200MB
12568 Here's how you would use @option{--threshold} to find directories and
12569 files -- note the @option{-a} -- with an apparent size smaller than or
12570 equal to 500 bytes:
12573 du -a -t -500 --apparent-size
12576 Here's how you would use @option{--threshold} to find directories on the root
12577 file system with more than 20000 inodes used in the directory tree below:
12580 du --inodes -x --threshold=20000 /
12586 @cindex last modified dates, displaying in @command{du}
12587 Show the most recent modification timestamp (mtime) of any file in the
12588 directory, or any of its subdirectories. @xref{File timestamps}.
12591 @itemx --time=status
12594 @opindex ctime@r{, show the most recent}
12595 @opindex status time@r{, show the most recent}
12596 @opindex use time@r{, show the most recent}
12597 Show the most recent status change timestamp (ctime) of any file in
12598 the directory, or any of its subdirectories. @xref{File timestamps}.
12601 @itemx --time=access
12603 @opindex atime@r{, show the most recent}
12604 @opindex access timestamp@r{, show the most recent}
12605 Show the most recent access timestamp (atime) of any file in the
12606 directory, or any of its subdirectories. @xref{File timestamps}.
12608 @item --time-style=@var{style}
12609 @opindex --time-style
12611 List timestamps in style @var{style}. This option has an effect only if
12612 the @option{--time} option is also specified. The @var{style} should
12613 be one of the following:
12616 @item +@var{format}
12618 List timestamps using @var{format}, where @var{format} is interpreted
12619 like the format argument of @command{date} (@pxref{date invocation}).
12620 For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
12621 @command{du} to list timestamps like @samp{2020-07-21 23:45:56}. As
12622 with @command{date}, @var{format}'s interpretation is affected by the
12623 @env{LC_TIME} locale category.
12626 List timestamps in full using ISO 8601-like date, time, and time zone
12627 components with nanosecond precision, e.g., @samp{2020-07-21
12628 23:45:56.477817180 -0400}. This style is equivalent to
12629 @samp{+%Y-%m-%d %H:%M:%S.%N %z}.
12632 List ISO 8601 date and time components with minute precision, e.g.,
12633 @samp{2020-07-21 23:45}. These timestamps are shorter than
12634 @samp{full-iso} timestamps, and are usually good enough for everyday
12635 work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
12638 List ISO 8601 dates for timestamps, e.g., @samp{2020-07-21}.
12639 This style is equivalent to @samp{+%Y-%m-%d}.
12643 You can specify the default value of the @option{--time-style} option
12644 with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
12645 the default style is @samp{long-iso}. For compatibility with @command{ls},
12646 if @env{TIME_STYLE} begins with @samp{+} and contains a newline,
12647 the newline and any later characters are ignored; if @env{TIME_STYLE}
12648 begins with @samp{posix-} the @samp{posix-} is ignored; and if
12649 @env{TIME_STYLE} is @samp{locale} it is ignored.
12651 @item -X @var{file}
12652 @itemx --exclude-from=@var{file}
12653 @opindex -X @var{file}
12654 @opindex --exclude-from=@var{file}
12655 @cindex excluding files from @command{du}
12656 Like @option{--exclude}, except take the patterns to exclude from @var{file},
12657 one per line. If @var{file} is @samp{-}, take the patterns from standard
12660 @item --exclude=@var{pattern}
12661 @opindex --exclude=@var{pattern}
12662 @cindex excluding files from @command{du}
12663 When recursing, skip subdirectories or files matching @var{pattern}.
12664 For example, @code{du --exclude='*.o'} excludes files whose names
12668 @itemx --one-file-system
12670 @opindex --one-file-system
12671 @cindex one file system, restricting @command{du} to
12672 Skip directories that are on different file systems from the one that
12673 the argument being processed is on.
12677 Since @command{du} relies on information reported by the operating
12678 system, its output might not reflect the space consumed in the
12679 underlying devices. For example;
12683 Operating systems normally do not report device space consumed by
12684 duplicate or backup blocks, error correction bits, and so forth.
12685 This causes @command{du} to underestimate the device space actually used.
12688 @cindex copy-on-write and @command{du}
12689 In file systems that use copy-on-write, if two distinct files share
12690 space the output of @command{du} typically counts the space that would
12691 be consumed if all files' non-holes were rewritten, not the space
12692 currently consumed.
12695 @cindex compression and @command{du}
12696 In file systems that use compression, the operating system might
12697 report the uncompressed space. (If it does report the compressed space,
12698 that report might change after one merely overwrites existing file data.)
12701 @cindex networked file systems and @command{du}
12702 Networked file systems historically have had difficulty communicating
12703 accurate file system information from server to client.
12707 For these reasons @command{du} might better be thought of as an
12708 estimate of the size of a @command{tar} or other conventional backup
12709 for a set of files, rather than as a measure of space consumed in the
12710 underlying devices.
12715 @node stat invocation
12716 @section @command{stat}: Report file or file system status
12719 @cindex file status
12720 @cindex file system status
12722 @command{stat} displays information about the specified file(s). Synopsis:
12725 stat [@var{option}]@dots{} [@var{file}]@dots{}
12728 With no option, @command{stat} reports all information about the given files.
12729 But it also can be used to report the information of the file systems the
12730 given files are located on. If the files are links, @command{stat} can
12731 also give information about the files the links point to.
12733 @mayConflictWithShellBuiltIn{stat}
12738 @itemx --dereference
12740 @opindex --dereference
12741 @cindex symbolic links, dereferencing in @command{stat}
12742 Change how @command{stat} treats symbolic links.
12743 With this option, @command{stat} acts on the file referenced
12744 by each symbolic link argument.
12745 Without it, @command{stat} acts on any symbolic link argument directly.
12748 @itemx --file-system
12750 @opindex --file-system
12751 @cindex file systems
12752 Report information about the file systems where the given files are located
12753 instead of information about the files themselves.
12754 This option implies the @option{-L} option.
12756 @item --cached=@var{mode}
12757 @opindex --cached=@var{mode}
12758 @cindex attribute caching
12759 Control how attributes are read from the file system;
12760 if supported by the system. This allows one to
12761 control the trade-off between freshness and efficiency
12762 of attribute access, especially useful with remote file systems.
12767 Always read the already cached attributes if available.
12770 Always sychronize with the latest file system attributes.
12771 This also mounts automounted files.
12774 Leave the caching behavior to the underlying file system.
12779 @itemx --format=@var{format}
12781 @opindex --format=@var{format}
12782 @cindex output format
12783 Use @var{format} rather than the default format.
12784 @var{format} is automatically newline-terminated, so
12785 running a command like the following with two or more @var{file}
12786 operands produces a line of output for each operand:
12788 $ stat --format=%d:%i / /usr
12793 @item --printf=@var{format}
12794 @opindex --printf=@var{format}
12795 @cindex output format
12796 Use @var{format} rather than the default format.
12797 Like @option{--format}, but interpret backslash escapes,
12798 and do not output a mandatory trailing newline.
12799 If you want a newline, include @samp{\n} in the @var{format}.
12800 Here's how you would use @option{--printf} to print the device
12801 and inode numbers of @file{/} and @file{/usr}:
12803 $ stat --printf='%d:%i\n' / /usr
12812 @cindex terse output
12813 Print the information in terse form, suitable for parsing by other programs.
12815 The output of the following commands are identical and the @option{--format}
12816 also identifies the items printed (in fuller form) in the default format.
12817 Note the format string would include another @samp{%C} at the end with an
12818 active SELinux security context.
12820 $ stat --format="%n %s %b %f %u %g %D %i %h %t %T %X %Y %Z %W %o" ...
12824 The same illustrating terse output in @option{--file-system} mode:
12826 $ stat -f --format="%n %i %l %t %s %S %b %f %a %c %d" ...
12827 $ stat -f --terse ...
12831 The valid @var{format} directives for files with @option{--format} and
12832 @option{--printf} are:
12835 @item %a -- Permission bits in octal (note @samp{#} and @samp{0} printf flags)
12836 @item %A -- Permission bits in symbolic form (similar to @command{ls -ld})
12837 @item %b -- Number of blocks allocated (see @samp{%B})
12838 @item %B -- The size in bytes of each block reported by @samp{%b}
12839 @item %C -- The SELinux security context of a file, if available
12840 @item %d -- Device number in decimal (st_dev)
12841 @item %D -- Device number in hex (st_dev)
12842 @item %Hd -- Major device number in decimal
12843 @item %Ld -- Minor device number in decimal
12844 @item %f -- Raw mode in hex
12845 @item %F -- File type
12846 @item %g -- Group ID of owner
12847 @item %G -- Group name of owner
12848 @item %h -- Number of hard links
12849 @item %i -- Inode number
12850 @item %m -- Mount point (See note below)
12851 @item %n -- File name
12852 @item %N -- Quoted file name with dereference if symbolic link (see below)
12853 @item %o -- Optimal I/O transfer size hint
12854 @item %s -- Total size, in bytes
12855 @item %r -- Device type in decimal (st_rdev)
12856 @item %R -- Device type in hex (st_rdev)
12857 @item %Hr -- Major device type in decimal (see below)
12858 @item %Lr -- Minor device type in decimal (see below)
12859 @item %t -- Major device type in hex (see below)
12860 @item %T -- Minor device type in hex (see below)
12861 @item %u -- User ID of owner
12862 @item %U -- User name of owner
12863 @item %w -- Time of file birth, or @samp{-} if unknown
12864 @item %W -- Time of file birth as seconds since Epoch, or @samp{0}
12865 @item %x -- Time of last access
12866 @item %X -- Time of last access as seconds since Epoch
12867 @item %y -- Time of last data modification
12868 @item %Y -- Time of last data modification as seconds since Epoch
12869 @item %z -- Time of last status change
12870 @item %Z -- Time of last status change as seconds since Epoch
12873 The @samp{%a} format prints the octal mode, and so it is useful
12874 to control the zero padding of the output with the @samp{#} and @samp{0}
12875 printf flags. For example to pad to at least 3 wide while making larger
12876 numbers unambiguously octal, you can use @samp{%#03a}.
12878 The @samp{%N} format can be set with the environment variable
12879 @env{QUOTING_STYLE}@. If that environment variable is not set,
12880 the default value is @samp{shell-escape-always}. Valid quoting styles are:
12883 The @samp{r}, @samp{R}, @samp{%t}, and @samp{%T} formats operate on the st_rdev
12884 member of the stat(2) structure, i.e., the represented device rather than
12885 the containing device, and so are only defined for character and block
12886 special files. On some systems or file types, st_rdev may be used to
12887 represent other quantities.
12889 The @samp{%W}, @samp{%X}, @samp{%Y}, and @samp{%Z} formats accept a
12890 precision preceded by a period to specify the number of digits to
12891 print after the decimal point. For example, @samp{%.3X} outputs the
12892 access timestamp to millisecond precision. If a period is given but no
12893 precision, @command{stat} uses 9 digits, so @samp{%.X} is equivalent to
12894 @samp{%.9X}@. When discarding excess precision, timestamps are truncated
12895 toward minus infinity.
12899 $ stat -c '[%015Y]' /usr
12902 $ stat -c '[%15Y]' /usr
12904 $ stat -c '[%-15Y]' /usr
12907 $ stat -c '[%.3Y]' /usr
12909 $ stat -c '[%.Y]' /usr
12910 [1288929712.114951834]
12913 The mount point printed by @samp{%m} is similar to that output
12914 by @command{df}, except that:
12917 stat does not dereference symlinks by default
12918 (unless @option{-L} is specified)
12920 stat does not search for specified device nodes in the
12921 file system list, instead operating on them directly
12924 stat outputs the alias for a bind mounted file, rather than
12925 the initial mount point of its backing device.
12926 One can recursively call stat until there is no change in output,
12927 to get the current base mount point
12930 When listing file system information (@option{--file-system} (@option{-f})),
12931 you must use a different set of @var{format} directives:
12934 @item %a -- Free blocks available to non-super-user
12935 @item %b -- Total data blocks in file system
12936 @item %c -- Total file nodes in file system
12937 @item %d -- Free file nodes in file system
12938 @item %f -- Free blocks in file system
12939 @item %i -- File System ID in hex
12940 @item %l -- Maximum length of file names
12941 @item %n -- File name
12942 @item %s -- Block size (for faster transfers)
12943 @item %S -- Fundamental block size (for block counts)
12944 @item %t -- Type in hex
12945 @item %T -- Type in human readable form
12949 Timestamps are listed according to the time zone rules specified by
12950 the @env{TZ} environment variable, or by the system default rules if
12951 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
12952 with @env{TZ}, libc, The GNU C Library Reference Manual}.
12957 @node sync invocation
12958 @section @command{sync}: Synchronize cached writes to persistent storage
12961 @cindex synchronize file system and memory
12962 @cindex Synchronize cached writes to persistent storage
12964 @command{sync} synchronizes in memory files or file systems to persistent
12968 sync [@var{option}] [@var{file}]@dots{}
12971 @cindex superblock, writing
12972 @cindex inodes, written buffered
12973 @command{sync} writes any data buffered in memory out to the storage device.
12975 include (but is not limited to) modified superblocks, modified inodes,
12976 and delayed reads and writes. This must be implemented by the kernel;
12977 The @command{sync} program does nothing but exercise the @code{sync},
12978 @code{syncfs}, @code{fsync}, and @code{fdatasync} system calls.
12980 @cindex crashes and corruption
12981 The kernel keeps data in memory to avoid doing (relatively slow) device
12982 reads and writes. This improves performance, but if the computer
12983 crashes, data may be lost or the file system corrupted as a
12984 result. The @command{sync} command instructs the kernel to write
12985 data in memory to persistent storage.
12987 If any argument is specified then only those files will be
12988 synchronized using the fsync(2) syscall by default.
12990 If at least one file is specified, it is possible to change the
12991 synchronization method with the following options. Also see
12992 @ref{Common options}.
12998 Use fdatasync(2) to sync only the data for the file,
12999 and any metadata required to maintain file system consistency.
13002 @itemx --file-system
13003 @opindex --file-system
13004 Synchronize all the I/O waiting for the file systems that contain the file,
13005 using the syscall syncfs(2). Note you would usually @emph{not} specify
13006 this option if passing a device node like @samp{/dev/sda} for example,
13007 as that would sync the containing file system rather than the referenced one.
13008 Note also that depending on the system, passing individual device nodes or files
13009 may have different sync characteristics than using no arguments.
13010 I.e., arguments passed to fsync(2) may provide greater guarantees through
13011 write barriers, than a global sync(2) used when no arguments are provided.
13017 @node truncate invocation
13018 @section @command{truncate}: Shrink or extend the size of a file
13021 @cindex truncating, file sizes
13023 @command{truncate} shrinks or extends the size of each @var{file} to the
13024 specified size. Synopsis:
13027 truncate @var{option}@dots{} @var{file}@dots{}
13030 @cindex files, creating
13031 Any @var{file} that does not exist is created.
13033 @cindex sparse files, creating
13034 @cindex holes, creating files with
13035 If a @var{file} is larger than the specified size, the extra data is lost.
13036 If a @var{file} is shorter, it is extended and the sparse extended part
13037 (or hole) reads as zero bytes.
13039 The program accepts the following options. Also see @ref{Common options}.
13046 @opindex --no-create
13047 Do not create files that do not exist.
13052 @opindex --io-blocks
13053 Treat @var{size} as number of I/O blocks of the @var{file} rather than bytes.
13055 @item -r @var{rfile}
13056 @itemx --reference=@var{rfile}
13058 @opindex --reference
13059 Base the size of each @var{file} on the size of @var{rfile}.
13061 @item -s @var{size}
13062 @itemx --size=@var{size}
13065 Set or adjust the size of each @var{file} according to @var{size}.
13066 @var{size} is in bytes unless @option{--io-blocks} is specified.
13067 @multiplierSuffixesNoBlocks{size}
13069 @var{size} may also be prefixed by one of the following to adjust
13070 the size of each @var{file} based on its current size:
13072 @samp{+} => extend by
13073 @samp{-} => reduce by
13074 @samp{<} => at most
13075 @samp{>} => at least
13076 @samp{/} => round down to multiple of
13077 @samp{%} => round up to multiple of
13085 @node Printing text
13086 @chapter Printing text
13088 @cindex printing text, commands for
13089 @cindex commands for printing text
13091 This section describes commands that display text strings.
13094 * echo invocation:: Print a line of text.
13095 * printf invocation:: Format and print data.
13096 * yes invocation:: Print a string until interrupted.
13100 @node echo invocation
13101 @section @command{echo}: Print a line of text
13104 @cindex displaying text
13105 @cindex printing text
13106 @cindex text, displaying
13107 @cindex arbitrary text, displaying
13109 @command{echo} writes each given @var{string} to standard output, with a
13110 space between each and a newline after the last one. Synopsis:
13113 echo [@var{option}]@dots{} [@var{string}]@dots{}
13116 @mayConflictWithShellBuiltIn{echo}
13118 Due to historical and backwards compatibility reasons, certain bare option-like
13119 strings cannot be passed to @command{echo} as non-option arguments.
13120 It is therefore not advisable to use @command{echo} for printing unknown or
13121 variable arguments. The @command{printf} command is recommended as a more
13122 portable and flexible replacement for tasks historically performed by
13123 @command{echo}. @xref{printf invocation}.
13125 The program accepts the following options. Also see @ref{Common options}.
13126 Options must precede operands, and the normally-special argument
13127 @samp{--} has no special meaning and is treated like any other
13133 Do not output the trailing newline.
13137 @cindex backslash escapes
13138 Enable interpretation of the following backslash-escaped characters in
13147 produce no further output
13163 the eight-bit value that is the octal number @var{nnn}
13164 (zero to three octal digits), if @var{nnn} is
13165 a nine-bit value, the ninth bit is ignored
13167 the eight-bit value that is the octal number @var{nnn}
13168 (one to three octal digits), if @var{nnn} is
13169 a nine-bit value, the ninth bit is ignored
13171 the eight-bit value that is the hexadecimal number @var{hh}
13172 (one or two hexadecimal digits)
13177 @cindex backslash escapes
13178 Disable interpretation of backslash escapes in each @var{string}.
13179 This is the default. If @option{-e} and @option{-E} are both
13180 specified, the last one given takes effect.
13184 @vindex POSIXLY_CORRECT
13185 If the @env{POSIXLY_CORRECT} environment variable is set, then when
13186 @command{echo}'s first argument is not @option{-n} it outputs
13187 option-like arguments instead of treating them as options. For
13188 example, @code{echo -ne hello} outputs @samp{-ne hello} instead of
13189 plain @samp{hello}. Also backslash escapes are always enabled.
13190 Note to echo the string @samp{-n}, one of the characters
13191 can be escaped in either octal or hexadecimal representation.
13192 For example, @code{echo -e '\x2dn'}.
13194 POSIX does not require support for any options, and says
13195 that the behavior of @command{echo} is implementation-defined if any
13196 @var{string} contains a backslash or if the first argument is @option{-n}.
13197 Portable programs should use the @command{printf} command instead.
13198 @xref{printf invocation}.
13203 @node printf invocation
13204 @section @command{printf}: Format and print data
13207 @command{printf} does formatted printing of text. Synopsis:
13210 printf @var{format} [@var{argument}]@dots{}
13213 @command{printf} prints the @var{format} string, interpreting @samp{%}
13214 directives and @samp{\} escapes to format numeric and string arguments
13215 in a way that is mostly similar to the C @samp{printf} function.
13216 @xref{Output Conversion Syntax,, @command{printf} format directives,
13217 libc, The GNU C Library Reference Manual}, for details.
13218 The differences are listed below.
13220 @mayConflictWithShellBuiltIn{printf}
13225 The @var{format} argument is reused as necessary to convert all the
13226 given @var{argument}s. For example, the command @samp{printf %s a b}
13230 Missing @var{argument}s are treated as null strings or as zeros,
13231 depending on whether the context expects a string or a number. For
13232 example, the command @samp{printf %sx%d} prints @samp{x0}.
13236 An additional escape, @samp{\c}, causes @command{printf} to produce no
13237 further output. For example, the command @samp{printf 'A%sC\cD%sF' B
13238 E} prints @samp{ABC}.
13241 The hexadecimal escape sequence @samp{\x@var{hh}} has at most two
13242 digits, as opposed to C where it can have an unlimited number of
13243 digits. For example, the command @samp{printf '\x07e'} prints two
13244 bytes, whereas the C statement @samp{printf ("\x07e")} prints just
13249 An additional directive @samp{%b}, prints its
13250 argument string with @samp{\} escapes interpreted in the same way as in
13251 the @var{format} string, except that octal escapes are of the form
13252 @samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits. If
13253 @samp{\@var{ooo}} is nine-bit value, ignore the ninth bit.
13254 If a precision is also given, it limits the number of bytes printed
13255 from the converted string.
13259 An additional directive @samp{%q}, prints its argument string
13260 in a format that can be reused as input by most shells.
13261 Non-printable characters are escaped with the POSIX proposed @samp{$''} syntax,
13262 and shell metacharacters are quoted appropriately.
13263 This is an equivalent format to @command{ls --quoting=shell-escape} output.
13266 Numeric arguments must be single C constants, possibly with leading
13267 @samp{+} or @samp{-}. For example, @samp{printf %.4d -3} outputs
13271 @vindex POSIXLY_CORRECT
13272 If the leading character of a numeric argument is @samp{"} or @samp{'}
13273 then its value is the numeric value of the immediately following
13274 character. Any remaining characters are silently ignored if the
13275 @env{POSIXLY_CORRECT} environment variable is set; otherwise, a
13276 warning is printed. For example, @samp{printf "%d" "'a"} outputs
13277 @samp{97} on hosts that use the ASCII character set, since
13278 @samp{a} has the numeric value 97 in ASCII.
13283 A floating point argument is interpreted according to
13284 the @env{LC_NUMERIC} category of either the current or the C locale,
13285 and is printed according to the current locale.
13286 For example, in a locale whose decimal point character is a comma,
13287 the command @samp{printf '%g %g' 2,5 2.5} outputs @samp{2,5 2,5}.
13288 @xref{Floating point}.
13292 @command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number
13293 (if @var{ooo} is 1 to 3 octal digits) specifying a byte to print,
13294 and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex
13295 digits) specifying a character to print.
13296 Note however that when @samp{\@var{ooo}} specifies a number larger than 255,
13297 @command{printf} ignores the ninth bit.
13298 For example, @samp{printf '\400'} is equivalent to @samp{printf '\0'}.
13303 @cindex ISO/IEC 10646
13305 @command{printf} interprets two syntaxes for specifying Unicode
13306 (ISO/IEC 10646) characters.
13307 @samp{\u} for 16-bit Unicode characters, specified as
13308 four hexadecimal digits @var{hhhh}, and @samp{\U} for 32-bit Unicode
13309 characters, specified as eight hexadecimal digits @var{hhhhhhhh}.
13310 @command{printf} outputs the Unicode characters
13311 according to the @env{LC_CTYPE} locale. Unicode characters in the range
13312 U+D800@dots{}U+DFFF cannot be specified by this syntax.
13313 This syntax fully supports the universal character subset
13314 introduced in ISO C 99.
13316 The processing of @samp{\u} and @samp{\U} requires a full-featured
13317 @code{iconv} facility. It is activated on systems with glibc 2.2 (or newer),
13318 or when @code{libiconv} is installed prior to this package. Otherwise
13319 @samp{\u} and @samp{\U} will print as-is.
13321 The Unicode character syntaxes are useful for writing strings in a locale
13322 independent way. For example, a string containing the Euro currency symbol
13325 $ env printf '\u20AC 14.95'
13329 will be output correctly in all locales supporting the Euro symbol
13330 (ISO-8859-15, UTF-8, and others). Similarly, a Chinese string
13333 $ env printf '\u4e2d\u6587'
13337 will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc).
13339 Note that in these examples, the @command{printf} command has been
13340 invoked via @command{env} to ensure that we run the program found via
13341 your shell's search path, and not a shell alias or a built-in function.
13343 For larger strings, you don't need to look up the hexadecimal code
13344 values of each character one by one. ASCII characters mixed with \u
13345 escape sequences is also known as the JAVA source file encoding. You can
13346 use GNU recode 3.5c (or newer) to convert strings to this encoding. Here
13347 is how to convert a piece of text into a shell script which will output
13348 this text in a locale-independent way:
13351 $ LC_CTYPE=zh_TW.big5 env printf \
13352 '\u4e2d\u6587\n' > sample.txt
13353 $ recode BIG5..JAVA < sample.txt \
13354 | sed -e "s|^|env printf '|" -e "s|%|%%|g" -e "s|$|\\\\n'|" \
13358 The only options are a lone @option{--help} or
13359 @option{--version}. @xref{Common options}.
13360 Options must precede operands.
13365 @node yes invocation
13366 @section @command{yes}: Print a string until interrupted
13369 @cindex repeated output of a string
13371 @command{yes} prints the command line arguments, separated by spaces and
13372 followed by a newline, forever until it is killed. If no arguments are
13373 given, it prints @samp{y} followed by a newline forever until killed.
13375 Upon a write error, @command{yes} exits with status @samp{1}.
13377 The only options are a lone @option{--help} or @option{--version}.
13378 To output an argument that begins with
13379 @samp{-}, precede it with @option{--}, e.g., @samp{yes -- --help}.
13380 @xref{Common options}.
13384 @chapter Conditions
13387 @cindex commands for exit status
13388 @cindex exit status commands
13390 This section describes commands that are primarily useful for their exit
13391 status, rather than their output. Thus, they are often used as the
13392 condition of shell @code{if} statements, or as the last command in a
13396 * false invocation:: Do nothing, unsuccessfully.
13397 * true invocation:: Do nothing, successfully.
13398 * test invocation:: Check file types and compare values.
13399 * expr invocation:: Evaluate expressions.
13403 @node false invocation
13404 @section @command{false}: Do nothing, unsuccessfully
13407 @cindex do nothing, unsuccessfully
13408 @cindex failure exit status
13409 @cindex exit status of @command{false}
13411 @command{false} does nothing except return an exit status of 1, meaning
13412 @dfn{failure}. It can be used as a place holder in shell scripts
13413 where an unsuccessful command is needed.
13414 In most modern shells, @command{false} is a built-in command, so when
13415 you use @samp{false} in a script, you're probably using the built-in
13416 command, not the one documented here.
13418 @command{false} honors the @option{--help} and @option{--version} options.
13420 This version of @command{false} is implemented as a C program, and is thus
13421 more secure and faster than a shell script implementation, and may safely
13422 be used as a dummy shell for the purpose of disabling accounts.
13424 Note that @command{false} (unlike all other programs documented herein)
13425 exits unsuccessfully, even when invoked with
13426 @option{--help} or @option{--version}.
13428 Portable programs should not assume that the exit status of
13429 @command{false} is 1, as it is greater than 1 on some
13433 @node true invocation
13434 @section @command{true}: Do nothing, successfully
13437 @cindex do nothing, successfully
13439 @cindex successful exit
13440 @cindex exit status of @command{true}
13442 @command{true} does nothing except return an exit status of 0, meaning
13443 @dfn{success}. It can be used as a place holder in shell scripts
13444 where a successful command is needed, although the shell built-in
13445 command @code{:} (colon) may do the same thing faster.
13446 In most modern shells, @command{true} is a built-in command, so when
13447 you use @samp{true} in a script, you're probably using the built-in
13448 command, not the one documented here.
13450 @command{true} honors the @option{--help} and @option{--version} options.
13452 Note, however, that it is possible to cause @command{true}
13453 to exit with nonzero status: with the @option{--help} or @option{--version}
13454 option, and with standard
13455 output already closed or redirected to a file that evokes an I/O error.
13456 For example, using a Bourne-compatible shell:
13459 $ ./true --version >&-
13460 ./true: write error: Bad file number
13461 $ ./true --version > /dev/full
13462 ./true: write error: No space left on device
13465 This version of @command{true} is implemented as a C program, and is thus
13466 more secure and faster than a shell script implementation, and may safely
13467 be used as a dummy shell for the purpose of disabling accounts.
13469 @node test invocation
13470 @section @command{test}: Check file types and compare values
13473 @cindex check file types
13474 @cindex compare values
13475 @cindex expression evaluation
13477 @command{test} returns a status of 0 (true) or 1 (false) depending on the
13478 evaluation of the conditional expression @var{expr}. Each part of the
13479 expression must be a separate argument.
13481 @command{test} has file status checks, string operators, and numeric
13482 comparison operators.
13484 @command{test} has an alternate form that uses opening and closing
13485 square brackets instead a leading @samp{test}. For example, instead
13486 of @samp{test -d /}, you can write @samp{[ -d / ]}. The square
13487 brackets must be separate arguments; for example, @samp{[-d /]} does
13488 not have the desired effect. Since @samp{test @var{expr}} and @samp{[
13489 @var{expr} ]} have the same meaning, only the former form is discussed
13495 test @var{expression}
13497 [ @var{expression} ]
13502 @mayConflictWithShellBuiltIn{test}
13504 If @var{expression} is omitted, @command{test} returns false.
13505 If @var{expression} is a single argument,
13506 @command{test} returns false if the argument is null and true
13507 otherwise. The argument
13508 can be any string, including strings like @samp{-d}, @samp{-1},
13509 @samp{--}, @samp{--help}, and @samp{--version} that most other
13510 programs would treat as options. To get help and version information,
13511 invoke the commands @samp{[ --help} and @samp{[ --version}, without
13512 the usual closing brackets. @xref{Common options}.
13514 @cindex exit status of @command{test}
13518 0 if the expression is true,
13519 1 if the expression is false,
13520 2 if an error occurred.
13524 * File type tests:: @code{-[bcdfhLpSt]}
13525 * Access permission tests:: @code{-[gkruwxOG]}
13526 * File characteristic tests:: @code{-e -s -nt -ot -ef}
13527 * String tests:: @code{-z -n = == !=}
13528 * Numeric tests:: @code{-eq -ne -lt -le -gt -ge}
13529 * Connectives for test:: @code{! -a -o}
13533 @node File type tests
13534 @subsection File type tests
13536 @cindex file type tests
13538 These options test for particular types of files. (Everything's a file,
13539 but not all files are the same!)
13543 @item -b @var{file}
13545 @cindex block special check
13546 True if @var{file} exists and is a block special device.
13548 @item -c @var{file}
13550 @cindex character special check
13551 True if @var{file} exists and is a character special device.
13553 @item -d @var{file}
13555 @cindex directory check
13556 True if @var{file} exists and is a directory.
13558 @item -f @var{file}
13560 @cindex regular file check
13561 True if @var{file} exists and is a regular file.
13563 @item -h @var{file}
13564 @itemx -L @var{file}
13567 @cindex symbolic link check
13568 True if @var{file} exists and is a symbolic link.
13569 Unlike all other file-related tests, this test does not dereference
13570 @var{file} if it is a symbolic link.
13572 @item -p @var{file}
13574 @cindex named pipe check
13575 True if @var{file} exists and is a named pipe.
13577 @item -S @var{file}
13579 @cindex socket check
13580 True if @var{file} exists and is a socket.
13584 @cindex terminal check
13585 True if @var{fd} is a file descriptor that is associated with a
13591 @node Access permission tests
13592 @subsection Access permission tests
13594 @cindex access permission tests
13595 @cindex permission tests
13597 These options test for particular access permissions.
13601 @item -g @var{file}
13603 @cindex set-group-ID check
13604 True if @var{file} exists and has its set-group-ID bit set.
13606 @item -k @var{file}
13608 @cindex sticky bit check
13609 True if @var{file} exists and has its @dfn{sticky} bit set.
13611 @item -r @var{file}
13613 @cindex readable file check
13614 True if @var{file} exists and the user has read access.
13616 @item -u @var{file}
13618 @cindex set-user-ID check
13619 True if @var{file} exists and has its set-user-ID bit set.
13621 @item -w @var{file}
13623 @cindex writable file check
13624 True if @var{file} exists and the user has write access.
13626 @item -x @var{file}
13628 @cindex executable file check
13629 True if @var{file} exists and the user has execute access
13630 (or search permission, if it is a directory).
13632 @item -O @var{file}
13634 @cindex owned by effective user ID check
13635 True if @var{file} exists and is owned by the current effective user ID.
13637 @item -G @var{file}
13639 @cindex owned by effective group ID check
13640 True if @var{file} exists and is owned by the current effective group ID.
13644 @node File characteristic tests
13645 @subsection File characteristic tests
13647 @cindex file characteristic tests
13649 These options test other file characteristics.
13653 @item -e @var{file}
13655 @cindex existence-of-file check
13656 True if @var{file} exists.
13658 @item -s @var{file}
13660 @cindex nonempty file check
13661 True if @var{file} exists and has a size greater than zero.
13663 @item @var{file1} -nt @var{file2}
13665 @cindex newer-than file check
13666 True if @var{file1} is newer (according to modification date) than
13667 @var{file2}, or if @var{file1} exists and @var{file2} does not.
13669 @item @var{file1} -ot @var{file2}
13671 @cindex older-than file check
13672 True if @var{file1} is older (according to modification date) than
13673 @var{file2}, or if @var{file2} exists and @var{file1} does not.
13675 @item @var{file1} -ef @var{file2}
13677 @cindex same file check
13678 @cindex hard link check
13679 True if @var{file1} and @var{file2} have the same device and inode
13680 numbers, i.e., if they are hard links to each other.
13682 @item -N @var{file}
13684 @cindex mtime-greater-atime file check
13685 True if @var{file} exists and has been modified (mtime) since it was
13692 @subsection String tests
13694 @cindex string tests
13696 These options test string characteristics. You may need to quote
13697 @var{string} arguments for the shell. For example:
13703 The quotes here prevent the wrong arguments from being passed to
13704 @command{test} if @samp{$V} is empty or contains special characters.
13708 @item -z @var{string}
13710 @cindex zero-length string check
13711 True if the length of @var{string} is zero.
13713 @item -n @var{string}
13714 @itemx @var{string}
13716 @cindex nonzero-length string check
13717 True if the length of @var{string} is nonzero.
13719 @item @var{string1} = @var{string2}
13721 @cindex equal string check
13722 True if the strings are equal.
13724 @item @var{string1} == @var{string2}
13726 @cindex equal string check
13727 True if the strings are equal (synonym for =).
13728 Note this form is not as portable to other
13729 shells and systems.
13731 @item @var{string1} != @var{string2}
13733 @cindex not-equal string check
13734 True if the strings are not equal.
13739 @node Numeric tests
13740 @subsection Numeric tests
13742 @cindex numeric tests
13743 @cindex arithmetic tests
13745 Numeric relational operators. The arguments must be entirely numeric
13746 (possibly negative), or the special expression @w{@code{-l @var{string}}},
13747 which evaluates to the length of @var{string}.
13751 @item @var{arg1} -eq @var{arg2}
13752 @itemx @var{arg1} -ne @var{arg2}
13753 @itemx @var{arg1} -lt @var{arg2}
13754 @itemx @var{arg1} -le @var{arg2}
13755 @itemx @var{arg1} -gt @var{arg2}
13756 @itemx @var{arg1} -ge @var{arg2}
13763 These arithmetic binary operators return true if @var{arg1} is equal,
13764 not-equal, less-than, less-than-or-equal, greater-than, or
13765 greater-than-or-equal than @var{arg2}, respectively.
13772 test -1 -gt -2 && echo yes
13774 test -l abc -gt 1 && echo yes
13777 @error{} test: integer expression expected before -eq
13781 @node Connectives for test
13782 @subsection Connectives for @command{test}
13784 @cindex logical connectives
13785 @cindex connectives, logical
13787 Note it's preferred to use shell logical primitives
13788 rather than these logical connectives internal to @command{test},
13789 because an expression may become ambiguous
13790 depending on the expansion of its parameters.
13792 For example, this becomes ambiguous when @samp{$1}
13793 is set to @samp{'!'} and @samp{$2} to the empty string @samp{''}:
13799 and should be written as:
13802 test "$1" && test "$2"
13805 Note the shell logical primitives also benefit from
13806 short circuit operation, which can be significant
13807 for file attribute tests.
13813 True if @var{expr} is false.
13814 @samp{!} has lower precedence than all parts of @var{expr}.
13815 Note @samp{!} needs to be specified to the left
13816 of a binary expression, I.e., @samp{'!' 1 -gt 2}
13817 rather than @samp{1 '!' -gt 2}.
13818 Also @samp{!} is often a shell special character
13819 and is best used quoted.
13822 @item @var{expr1} -a @var{expr2}
13824 @cindex logical and operator
13825 @cindex and operator
13826 True if both @var{expr1} and @var{expr2} are true.
13827 @samp{-a} is left associative,
13828 and has a higher precedence than @samp{-o}.
13830 @item @var{expr1} -o @var{expr2}
13832 @cindex logical or operator
13833 @cindex or operator
13834 True if either @var{expr1} or @var{expr2} is true.
13835 @samp{-o} is left associative.
13840 @node expr invocation
13841 @section @command{expr}: Evaluate expressions
13844 @cindex expression evaluation
13845 @cindex evaluation of expressions
13847 @command{expr} evaluates an expression and writes the result on standard
13848 output. Each token of the expression must be a separate argument.
13850 Operands are either integers or strings. Integers consist of one or
13851 more decimal digits, with an optional leading @samp{-}.
13852 @command{expr} converts
13853 anything appearing in an operand position to an integer or a string
13854 depending on the operation being applied to it.
13856 Strings are not quoted for @command{expr} itself, though you may need to
13857 quote them to protect characters with special meaning to the shell,
13858 e.g., spaces. However, regardless of whether it is quoted, a string
13859 operand should not be a parenthesis or any of @command{expr}'s
13860 operators like @code{+}, so you cannot safely pass an arbitrary string
13861 @code{$str} to expr merely by quoting it to the shell. One way to
13862 work around this is to use the GNU extension @code{+},
13863 (e.g., @code{+ "$str" = foo}); a more portable way is to use
13864 @code{@w{" $str"}} and to adjust the rest of the expression to take
13865 the leading space into account (e.g., @code{@w{" $str" = " foo"}}).
13867 You should not pass a negative integer or a string with leading
13868 @samp{-} as @command{expr}'s first argument, as it might be
13869 misinterpreted as an option; this can be avoided by parenthesization.
13870 Also, portable scripts should not use a string operand that happens to
13871 take the form of an integer; this can be worked around by inserting
13872 leading spaces as mentioned above.
13874 @cindex parentheses for grouping
13875 Operators may be given as infix symbols or prefix keywords. Parentheses
13876 may be used for grouping in the usual manner. You must quote
13877 parentheses and many operators to avoid the shell evaluating them,
13880 Because @command{expr} uses multiple-precision arithmetic, it works
13881 with integers wider than those of machine registers.
13883 The only options are @option{--help} and @option{--version}. @xref{Common
13884 options}. Options must precede operands.
13886 @cindex exit status of @command{expr}
13890 0 if the expression is neither null nor 0,
13891 1 if the expression is null or 0,
13892 2 if the expression is invalid,
13893 3 if an internal error occurred (e.g., arithmetic overflow).
13897 * String expressions:: @code{+ : match substr index length}
13898 * Numeric expressions:: @code{+ - * / %}
13899 * Relations for expr:: @code{| & < <= = == != >= >}
13900 * Examples of expr:: Examples.
13904 @node String expressions
13905 @subsection String expressions
13907 @cindex string expressions
13908 @cindex expressions, string
13910 @command{expr} supports pattern matching and other string operators. These
13911 have higher precedence than both the numeric and relational operators (in
13912 the next sections).
13916 @item @var{string} : @var{regex}
13917 @cindex pattern matching
13918 @cindex regular expression matching
13919 @cindex matching patterns
13920 Perform pattern matching. The arguments are converted to strings and the
13921 second is considered to be a (basic, a la GNU @code{grep}) regular
13922 expression, with a @code{^} implicitly prepended. The first argument is
13923 then matched against this regular expression.
13925 If @var{regex} does not use @samp{\(} and @samp{\)}, the @code{:}
13926 expression returns the number of characters matched, or 0 if the match
13929 If @var{regex} uses @samp{\(} and @samp{\)}, the @code{:} expression
13930 returns the part of @var{string} that matched the subexpression, or
13931 the null string if the match failed or the subexpression did not
13932 contribute to the match.
13934 @kindex \( @r{regexp operator}
13935 Only the first @samp{\( @dots{} \)} pair is relevant to the return
13936 value; additional pairs are meaningful only for grouping the regular
13937 expression operators.
13939 @kindex \+ @r{regexp operator}
13940 @kindex \? @r{regexp operator}
13941 @kindex \| @r{regexp operator}
13942 In the regular expression, @code{\+}, @code{\?}, and @code{\|} are
13943 operators which respectively match one or more, zero or one, or separate
13944 alternatives. These operators are GNU extensions. @xref{Regular Expressions,,
13945 Regular Expressions, grep, The GNU Grep Manual}, for details of
13946 regular expression syntax. Some examples are in @ref{Examples of expr}.
13948 @item match @var{string} @var{regex}
13950 An alternative way to do pattern matching. This is the same as
13951 @w{@samp{@var{string} : @var{regex}}}.
13953 @item substr @var{string} @var{position} @var{length}
13955 Returns the substring of @var{string} beginning at @var{position}
13956 with length at most @var{length}. If either @var{position} or
13957 @var{length} is negative, zero, or non-numeric, returns the null string.
13959 @item index @var{string} @var{charset}
13961 Returns the first position in @var{string} where the first character in
13962 @var{charset} was found. If no character in @var{charset} is found in
13963 @var{string}, return 0.
13965 @item length @var{string}
13967 Returns the length of @var{string}.
13969 @item + @var{token}
13971 Interpret @var{token} as a string, even if it is a keyword like @var{match}
13972 or an operator like @code{/}.
13973 This makes it possible to test @code{expr length + "$x"} or
13974 @code{expr + "$x" : '.*/\(.\)'} and have it do the right thing even if
13975 the value of @var{$x} happens to be (for example) @code{/} or @code{index}.
13976 This operator is a GNU extension. Portable shell scripts should use
13977 @code{@w{" $token"} : @w{' \(.*\)'}} instead of @code{+ "$token"}.
13981 To make @command{expr} interpret keywords as strings, you must use the
13982 @code{quote} operator.
13985 @node Numeric expressions
13986 @subsection Numeric expressions
13988 @cindex numeric expressions
13989 @cindex expressions, numeric
13991 @command{expr} supports the usual numeric operators, in order of increasing
13992 precedence. These numeric operators have lower precedence than the
13993 string operators described in the previous section, and higher precedence
13994 than the connectives (next section).
14002 @cindex subtraction
14003 Addition and subtraction. Both arguments are converted to integers;
14004 an error occurs if this cannot be done.
14010 @cindex multiplication
14013 Multiplication, division, remainder. Both arguments are converted to
14014 integers; an error occurs if this cannot be done.
14019 @node Relations for expr
14020 @subsection Relations for @command{expr}
14022 @cindex connectives, logical
14023 @cindex logical connectives
14024 @cindex relations, numeric or string
14026 @command{expr} supports the usual logical connectives and relations. These
14027 have lower precedence than the string and numeric operators
14028 (previous sections). Here is the list, lowest-precedence operator first.
14034 @cindex logical or operator
14035 @cindex or operator
14036 Returns its first argument if that is neither null nor zero, otherwise
14037 its second argument if it is neither null nor zero, otherwise 0. It
14038 does not evaluate its second argument if its first argument is neither
14043 @cindex logical and operator
14044 @cindex and operator
14045 Return its first argument if neither argument is null or zero, otherwise
14046 0. It does not evaluate its second argument if its first argument is
14049 @item < <= = == != >= >
14056 @cindex comparison operators
14058 Compare the arguments and return 1 if the relation is true, 0 otherwise.
14059 @code{==} is a synonym for @code{=}. @command{expr} first tries to convert
14060 both arguments to integers and do a numeric comparison; if either
14061 conversion fails, it does a lexicographic comparison using the character
14062 collating sequence specified by the @env{LC_COLLATE} locale.
14067 @node Examples of expr
14068 @subsection Examples of using @command{expr}
14070 @cindex examples of @command{expr}
14071 Here are a few examples, including quoting for shell metacharacters.
14073 To add 1 to the shell variable @code{foo}, in Bourne-compatible shells:
14076 foo=$(expr $foo + 1)
14079 To print the non-directory part of the file name stored in
14080 @code{$fname}, which need not contain a @code{/}:
14083 expr $fname : '.*/\(.*\)' '|' $fname
14086 An example showing that @code{\+} is an operator:
14094 expr abc : 'a\(.\)c'
14096 expr index abcdef cz
14099 @error{} expr: syntax error
14100 expr index + index a
14106 @chapter Redirection
14108 @cindex redirection
14109 @cindex commands for redirection
14111 Unix shells commonly provide several forms of @dfn{redirection} -- ways
14112 to change the input source or output destination of a command. But one
14113 useful redirection is performed by a separate command, not by the shell;
14114 it's described here.
14117 * tee invocation:: Redirect output to multiple files or processes.
14121 @node tee invocation
14122 @section @command{tee}: Redirect output to multiple files or processes
14125 @cindex pipe fitting
14126 @cindex destinations, multiple output
14127 @cindex read from standard input and write to standard output and files
14129 The @command{tee} command copies standard input to standard output and also
14130 to any files given as arguments. This is useful when you want not only
14131 to send some data down a pipe, but also to save a copy. Synopsis:
14134 tee [@var{option}]@dots{} [@var{file}]@dots{}
14137 If a file being written to does not already exist, it is created. If a
14138 file being written to already exists, the data it previously contained
14139 is overwritten unless the @option{-a} option is used.
14141 In previous versions of GNU Coreutils (5.3.0--8.23),
14142 a @var{file} of @samp{-}
14143 caused @command{tee} to send another copy of input to standard output.
14144 However, as the interleaved output was not very useful, @command{tee} now
14145 conforms to POSIX and treats @samp{-} as a file name.
14147 The program accepts the following options. Also see @ref{Common options}.
14154 Append standard input to the given files rather than overwriting
14158 @itemx --ignore-interrupts
14160 @opindex --ignore-interrupts
14161 Ignore interrupt signals.
14164 @itemx --output-error[=@var{mode}]
14166 @opindex --output-error
14167 Adjust the behavior with errors on the outputs.
14168 In summary @option{-p} allows @command{tee} to operate in a more
14169 standard manner with pipes, and to continue to process data
14170 to any remaining outputs, if any pipe outputs exit early.
14171 The default operation when @option{--output-error} is @emph{not}
14172 specified is to exit immediately on error writing to a pipe,
14173 and diagnose errors writing to a non-pipe.
14174 The long form @option{--output-error} option supports selection
14175 between the following @var{mode}s:
14179 Warn on error opening or writing any output, including pipes.
14180 Writing is continued to still open files/pipes.
14181 Exit status indicates failure if any output has an error.
14184 This is the default @var{mode} when not specified,
14185 or when the short form @option{-p} is used.
14186 Warn on error opening or writing any output, except pipes.
14187 Writing is continued to still open files/pipes.
14188 Exit status indicates failure if any non pipe output had an error.
14191 Exit on error opening or writing any output, including pipes.
14194 Exit on error opening or writing any output, except pipes.
14199 The @command{tee} command is useful when you happen to be transferring a large
14200 amount of data and also want to summarize that data without reading
14201 it a second time. For example, when you are downloading a DVD image,
14202 you often want to verify its signature or checksum right away.
14203 The inefficient way to do it is simply:
14206 wget https://example.com/some.iso && sha1sum some.iso
14209 One problem with the above is that it makes you wait for the
14210 download to complete before starting the time-consuming SHA1 computation.
14211 Perhaps even more importantly, the above requires reading
14212 the DVD image a second time (the first was from the network).
14214 The efficient way to do it is to interleave the download
14215 and SHA1 computation. Then, you'll get the checksum for
14216 free, because the entire process parallelizes so well:
14219 # slightly contrived, to demonstrate process substitution
14220 wget -O - https://example.com/dvd.iso \
14221 | tee >(sha1sum > dvd.sha1) > dvd.iso
14224 That makes @command{tee} write not just to the expected output file,
14225 but also to a pipe running @command{sha1sum} and saving the final
14226 checksum in a file named @file{dvd.sha1}.
14228 Note, however, that this example relies on a feature of modern shells
14229 called @dfn{process substitution}
14230 (the @samp{>(command)} syntax, above;
14231 @xref{Process Substitution,,Process Substitution, bash,
14232 The Bash Reference Manual}.),
14233 so it works with @command{zsh}, @command{bash}, and @command{ksh},
14234 but not with @command{/bin/sh}. So if you write code like this
14235 in a shell script, be sure to start the script with @samp{#!/bin/bash}.
14237 Note also that if any of the process substitutions (or piped standard output)
14238 might exit early without consuming all the data, the @option{-p} option
14239 is needed to allow @command{tee} to continue to process the input
14240 to any remaining outputs.
14242 Since the above example writes to one file and one process,
14243 a more conventional and portable use of @command{tee} is even better:
14246 wget -O - https://example.com/dvd.iso \
14247 | tee dvd.iso | sha1sum > dvd.sha1
14250 You can extend this example to make @command{tee} write to two processes,
14251 computing MD5 and SHA1 checksums in parallel. In this case,
14252 process substitution is required:
14255 wget -O - https://example.com/dvd.iso \
14256 | tee >(sha1sum > dvd.sha1) \
14257 >(md5sum > dvd.md5) \
14261 This technique is also useful when you want to make a @emph{compressed}
14262 copy of the contents of a pipe.
14263 Consider a tool to graphically summarize file system usage data from
14265 For a large hierarchy, @samp{du -ak} can run for a long time,
14266 and can easily produce terabytes of data, so you won't want to
14267 rerun the command unnecessarily. Nor will you want to save
14268 the uncompressed output.
14270 Doing it the inefficient way, you can't even start the GUI
14271 until after you've compressed all of the @command{du} output:
14274 du -ak | gzip -9 > /tmp/du.gz
14275 gzip -d /tmp/du.gz | checkspace -a
14278 With @command{tee} and process substitution, you start the GUI
14279 right away and eliminate the decompression completely:
14282 du -ak | tee >(gzip -9 > /tmp/du.gz) | checkspace -a
14285 Finally, if you regularly create more than one type of
14286 compressed tarball at once, for example when @code{make dist} creates
14287 both @command{gzip}-compressed and @command{bzip2}-compressed tarballs,
14288 there may be a better way.
14289 Typical @command{automake}-generated @file{Makefile} rules create
14290 the two compressed tar archives with commands in sequence, like this
14291 (slightly simplified):
14294 tardir=your-pkg-M.N
14295 tar chof - "$tardir" | gzip -9 -c > your-pkg-M.N.tar.gz
14296 tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2
14299 However, if the hierarchy you are archiving and compressing is larger
14300 than a couple megabytes, and especially if you are using a multi-processor
14301 system with plenty of memory, then you can do much better by reading the
14302 directory contents only once and running the compression programs in parallel:
14305 tardir=your-pkg-M.N
14306 tar chof - "$tardir" \
14307 | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \
14308 | bzip2 -9 -c > your-pkg-M.N.tar.bz2
14311 If you want to further process the output from process substitutions,
14312 and those processes write atomically (i.e., write less than the system's
14313 PIPE_BUF size at a time), that's possible with a construct like:
14316 tardir=your-pkg-M.N
14317 tar chof - "$tardir" \
14318 | tee >(md5sum --tag) > >(sha256sum --tag) \
14319 | sort | gpg --clearsign > your-pkg-M.N.tar.sig
14325 @node File name manipulation
14326 @chapter File name manipulation
14328 @cindex file name manipulation
14329 @cindex manipulation of file names
14330 @cindex commands for file name manipulation
14332 This section describes commands that manipulate file names.
14335 * basename invocation:: Strip directory and suffix from a file name.
14336 * dirname invocation:: Strip last file name component.
14337 * pathchk invocation:: Check file name validity and portability.
14338 * mktemp invocation:: Create temporary file or directory.
14339 * realpath invocation:: Print resolved file names.
14343 @node basename invocation
14344 @section @command{basename}: Strip directory and suffix from a file name
14347 @cindex strip directory and suffix from file names
14348 @cindex directory, stripping from file names
14349 @cindex suffix, stripping from file names
14350 @cindex file names, stripping directory and suffix
14351 @cindex leading directory components, stripping
14353 @command{basename} removes any leading directory components from
14354 @var{name}. Synopsis:
14357 basename @var{name} [@var{suffix}]
14358 basename @var{option}@dots{} @var{name}@dots{}
14361 If @var{suffix} is specified and is identical to the end of @var{name},
14362 it is removed from @var{name} as well. Note that since trailing slashes
14363 are removed prior to suffix matching, @var{suffix} will do nothing if it
14364 contains slashes. @command{basename} prints the result on standard
14367 @c This test is used both here and in the section on dirname.
14368 @macro basenameAndDirname
14369 Together, @command{basename} and @command{dirname} are designed such
14370 that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd
14371 "$(dirname "$name")"; ls "$(basename "$name")"} will, too. This works
14372 for everything except file names containing a trailing newline.
14374 @basenameAndDirname
14376 POSIX allows the implementation to define the results if
14377 @var{name} is empty or @samp{//}. In the former case, GNU
14378 @command{basename} returns the empty string. In the latter case, the
14379 result is @samp{//} on platforms where @var{//} is distinct from
14380 @var{/}, and @samp{/} on platforms where there is no difference.
14382 The program accepts the following options. Also see @ref{Common options}.
14383 Options must precede operands.
14390 @opindex --multiple
14391 Support more than one argument. Treat every argument as a @var{name}.
14392 With this, an optional @var{suffix} must be specified using the
14393 @option{-s} option.
14395 @item -s @var{suffix}
14396 @itemx --suffix=@var{suffix}
14399 Remove a trailing @var{suffix}.
14400 This option implies the @option{-a} option.
14412 basename /usr/bin/sort
14415 basename include/stdio.h .h
14418 basename -s .h include/stdio.h
14420 # Output "stdio" followed by "stdlib"
14421 basename -a -s .h include/stdio.h include/stdlib.h
14425 @node dirname invocation
14426 @section @command{dirname}: Strip last file name component
14429 @cindex directory components, printing
14430 @cindex stripping non-directory suffix
14431 @cindex non-directory suffix, stripping
14433 @command{dirname} prints all but the final slash-delimited component
14434 of each @var{name}. Slashes on either side of the final component are
14435 also removed. If the string contains no slash, @command{dirname}
14436 prints @samp{.} (meaning the current directory). Synopsis:
14439 dirname [@var{option}] @var{name}@dots{}
14442 @var{name} need not be a file name, but if it is, this operation
14443 effectively lists the directory that contains the final component,
14444 including the case when the final component is itself a directory.
14446 @basenameAndDirname
14448 POSIX allows the implementation to define the results if
14449 @var{name} is @samp{//}. With GNU @command{dirname}, the
14450 result is @samp{//} on platforms where @var{//} is distinct from
14451 @var{/}, and @samp{/} on platforms where there is no difference.
14453 The program accepts the following option. Also see @ref{Common options}.
14466 # Output "/usr/bin".
14467 dirname /usr/bin/sort
14468 dirname /usr/bin//.//
14470 # Output "dir1" followed by "dir2"
14471 dirname dir1/str dir2/str
14478 @node pathchk invocation
14479 @section @command{pathchk}: Check file name validity and portability
14482 @cindex file names, checking validity and portability
14483 @cindex valid file names, checking for
14484 @cindex portable file names, checking for
14486 @command{pathchk} checks validity and portability of file names. Synopsis:
14489 pathchk [@var{option}]@dots{} @var{name}@dots{}
14492 For each @var{name}, @command{pathchk} prints an error message if any of
14493 these conditions is true:
14497 One of the existing directories in @var{name} does not have search
14498 (execute) permission,
14500 The length of @var{name} is larger than the maximum supported by the
14503 The length of one component of @var{name} is longer than
14504 its file system's maximum.
14507 A nonexistent @var{name} is not an error, so long as a file with that
14508 name could be created under the above conditions.
14510 The program accepts the following options. Also see @ref{Common options}.
14511 Options must precede operands.
14517 Instead of performing checks based on the underlying file system,
14518 print an error message if any of these conditions is true:
14522 A file name is empty.
14525 A file name contains a character outside the POSIX portable file
14526 name character set, namely, the ASCII letters and digits, @samp{.},
14527 @samp{_}, @samp{-}, and @samp{/}.
14530 The length of a file name or one of its components exceeds the
14531 POSIX minimum limits for portability.
14536 Print an error message if a file name is empty, or if it contains a component
14537 that begins with @samp{-}.
14539 @item --portability
14540 @opindex --portability
14541 Print an error message if a file name is not portable to all POSIX
14542 hosts. This option is equivalent to @samp{-p -P}.
14546 @cindex exit status of @command{pathchk}
14550 0 if all specified file names passed all checks,
14554 @node mktemp invocation
14555 @section @command{mktemp}: Create temporary file or directory
14558 @cindex file names, creating temporary
14559 @cindex directory, creating temporary
14560 @cindex temporary files and directories
14562 @command{mktemp} manages the creation of temporary files and
14563 directories. Synopsis:
14566 mktemp [@var{option}]@dots{} [@var{template}]
14569 Safely create a temporary file or directory based on @var{template},
14570 and print its name. If given, @var{template} must include at least
14571 three consecutive @samp{X}s in the last component. If omitted, the template
14572 @samp{tmp.XXXXXXXXXX} is used, and option @option{--tmpdir} is
14573 implied. The final run of @samp{X}s in the @var{template} will be replaced
14574 by alpha-numeric characters; thus, on a case-sensitive file system,
14575 and with a @var{template} including a run of @var{n} instances of @samp{X},
14576 there are @samp{62**@var{n}} potential file names.
14578 Older scripts used to create temporary files by simply joining the
14579 name of the program with the process id (@samp{$$}) as a suffix.
14580 However, that naming scheme is easily predictable, and suffers from a
14581 race condition where the attacker can create an appropriately named
14582 symbolic link, such that when the script then opens a handle to what
14583 it thought was an unused file, it is instead modifying an existing
14584 file. Using the same scheme to create a directory is slightly safer,
14585 since the @command{mkdir} will fail if the target already exists, but
14586 it is still inferior because it allows for denial of service attacks.
14587 Therefore, modern scripts should use the @command{mktemp} command to
14588 guarantee that the generated name will be unpredictable, and that
14589 knowledge of the temporary file name implies that the file was created
14590 by the current script and cannot be modified by other users.
14592 When creating a file, the resulting file has read and write
14593 permissions for the current user, but no permissions for the group or
14594 others; these permissions are reduced if the current umask is more
14597 Here are some examples (although note that if you repeat them, you
14598 will most likely get different file names):
14603 Create a temporary file in the current directory.
14610 Create a temporary file with a known suffix.
14612 $ mktemp --suffix=.txt file-XXXX
14614 $ mktemp file-XXXX-XXXX.txt
14619 Create a secure fifo relative to the user's choice of @env{TMPDIR},
14620 but falling back to the current directory rather than @file{/tmp}.
14621 Note that @command{mktemp} does not create fifos, but can create a
14622 secure directory in which the fifo can live. Exit the shell if the
14623 directory or fifo could not be created.
14625 $ dir=$(mktemp -p "$@{TMPDIR:-.@}" -d dir-XXXX) || exit 1
14627 $ mkfifo "$fifo" || @{ rmdir "$dir"; exit 1; @}
14631 Create and use a temporary file if possible, but ignore failure. The
14632 file will reside in the directory named by @env{TMPDIR}, if specified,
14633 or else in @file{/tmp}.
14635 $ file=$(mktemp -q) && @{
14636 > # Safe to use $file only within this block. Use quotes,
14637 > # since $TMPDIR, and thus $file, may contain whitespace.
14638 > echo ... > "$file"
14644 Act as a semi-random character generator (it is not fully random,
14645 since it is impacted by the contents of the current directory). To
14646 avoid security holes, do not use the resulting names to create a file.
14656 The program accepts the following options. Also see @ref{Common options}.
14663 @opindex --directory
14664 Create a directory rather than a file. The directory will have read,
14665 write, and search permissions for the current user, but no permissions
14666 for the group or others; these permissions are reduced if the current
14667 umask is more restrictive.
14673 Suppress diagnostics about failure to create a file or directory. The
14674 exit status will still reflect whether a file was created.
14680 Generate a temporary name that does not name an existing file, without
14681 changing the file system contents. Using the output of this command
14682 to create a new file is inherently unsafe, as there is a window of
14683 time between generating the name and using it where another process
14684 can create an object by the same name.
14687 @itemx --tmpdir[=@var{dir}]
14690 Treat @var{template} relative to the directory @var{dir}. If
14691 @var{dir} is not specified (only possible with the long option
14692 @option{--tmpdir}) or is the empty string, use the value of
14693 @env{TMPDIR} if available, otherwise use @samp{/tmp}. If this is
14694 specified, @var{template} must not be absolute. However,
14695 @var{template} can still contain slashes, although intermediate
14696 directories must already exist.
14698 @item --suffix=@var{suffix}
14700 Append @var{suffix} to the @var{template}. @var{suffix} must not
14701 contain slash. If @option{--suffix} is specified, @var{template} must
14702 end in @samp{X}; if it is not specified, then an appropriate
14703 @option{--suffix} is inferred by finding the last @samp{X} in
14704 @var{template}. This option exists for use with the default
14705 @var{template} and for the creation of a @var{suffix} that starts with
14710 Treat @var{template} as a single file relative to the value of
14711 @env{TMPDIR} if available, or to the directory specified by
14712 @option{-p}, otherwise to @samp{/tmp}. @var{template} must not
14713 contain slashes. This option is deprecated; the use of @option{-p}
14714 without @option{-t} offers better defaults (by favoring the command
14715 line over @env{TMPDIR}) and more flexibility (by allowing intermediate
14720 @cindex exit status of @command{mktemp}
14724 0 if the file was created,
14729 @node realpath invocation
14730 @section @command{realpath}: Print the resolved file name.
14733 @cindex file names, canonicalization
14734 @cindex symlinks, resolution
14735 @cindex canonical file name
14736 @cindex canonicalize a file name
14740 @command{realpath} expands all symbolic links and resolves references to
14741 @samp{/./}, @samp{/../} and extra @samp{/} characters. By default,
14742 all but the last component of the specified files must exist. Synopsis:
14745 realpath [@var{option}]@dots{} @var{file}@dots{}
14748 The file name canonicalization functionality overlaps with that of the
14749 @command{readlink} command. This is the preferred command for
14750 canonicalization as it's a more suitable and standard name. In addition
14751 this command supports relative file name processing functionality.
14753 The program accepts the following options. Also see @ref{Common options}.
14758 @itemx --canonicalize-existing
14760 @opindex --canonicalize-existing
14761 Ensure that all components of the specified file names exist.
14762 If any component is missing or unavailable, @command{realpath} will output
14763 a diagnostic unless the @option{-q} option is specified, and exit with a
14764 nonzero exit code. A trailing slash requires that the name resolve to a
14768 @itemx --canonicalize-missing
14770 @opindex --canonicalize-missing
14771 If any component of a specified file name is missing or unavailable,
14772 treat it as a directory.
14778 Symbolic links are resolved in the specified file names,
14779 but they are resolved after any subsequent @samp{..} components are processed.
14784 @opindex --physical
14785 Symbolic links are resolved in the specified file names,
14786 and they are resolved before any subsequent @samp{..} components are processed.
14787 This is the default mode of operation.
14793 Suppress diagnostic messages for specified file names.
14795 @item --relative-to=@var{dir}
14796 @opindex --relative-to
14798 Print the resolved file names relative to the specified directory.
14799 Note this option honors the @option{-m} and @option{-e} options
14800 pertaining to file existence.
14802 @item --relative-base=@var{dir}
14803 @opindex --relative-base
14804 Print the resolved file names as relative @emph{if} the files
14805 are descendants of @var{dir}.
14806 Otherwise, print the resolved file names as absolute.
14807 Note this option honors the @option{-m} and @option{-e} options
14808 pertaining to file existence.
14809 For details about combining @option{--relative-to} and @option{--relative-base},
14810 @pxref{Realpath usage examples}.
14814 @itemx --no-symlinks
14817 @opindex --no-symlinks
14818 Do not resolve symbolic links. Only resolve references to
14819 @samp{/./}, @samp{/../} and remove extra @samp{/} characters.
14820 When combined with the @option{-m} option, realpath operates
14821 only on the file name, and does not touch any actual file.
14827 @cindex exit status of @command{realpath}
14831 0 if all file names were printed without issue.
14836 * Realpath usage examples:: Realpath usage examples.
14840 @node Realpath usage examples
14841 @subsection Realpath usage examples
14843 @opindex --relative-to
14844 @opindex --relative-base
14846 By default, @command{realpath} prints the absolute file name of given files
14847 (symlinks are resolved, @file{words} is resolved to @file{american-english}):
14852 realpath /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
14853 @result{} /usr/bin/sort
14855 @result{} /usr/share/dict/american-english
14856 @result{} /home/user/1.txt
14860 With @option{--relative-to}, file names are printed relative to
14861 the given directory:
14865 realpath --relative-to=/usr/bin \
14866 /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
14868 @result{} ../../tmp/foo
14869 @result{} ../share/dict/american-english
14870 @result{} ../../home/user/1.txt
14874 With @option{--relative-base}, relative file names are printed @emph{if}
14875 the resolved file name is below the given base directory. For files outside the
14876 base directory absolute file names are printed:
14880 realpath --relative-base=/usr \
14881 /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
14884 @result{} share/dict/american-english
14885 @result{} /home/user/1.txt
14889 When both @option{--relative-to=DIR1} and @option{--relative-base=DIR2}
14890 are used, file names are printed relative to @var{dir1} @emph{if} they are
14891 located below @var{dir2}. If the files are not below @var{dir2}, they are
14892 printed as absolute file names:
14896 realpath --relative-to=/usr/bin --relative-base=/usr \
14897 /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
14900 @result{} ../share/dict/american-english
14901 @result{} /home/user/1.txt
14905 When both @option{--relative-to=DIR1} and @option{--relative-base=DIR2}
14906 are used, @var{dir1} @emph{must} be a subdirectory of @var{dir2}. Otherwise,
14907 @command{realpath} prints absolutes file names.
14910 @node Working context
14911 @chapter Working context
14913 @cindex working context
14914 @cindex commands for printing the working context
14916 This section describes commands that display or alter the context in
14917 which you are working: the current directory, the terminal settings, and
14918 so forth. See also the user-related commands in the next section.
14921 * pwd invocation:: Print working directory.
14922 * stty invocation:: Print or change terminal characteristics.
14923 * printenv invocation:: Print environment variables.
14924 * tty invocation:: Print file name of terminal on standard input.
14928 @node pwd invocation
14929 @section @command{pwd}: Print working directory
14932 @cindex print name of current directory
14933 @cindex current working directory, printing
14934 @cindex working directory, printing
14937 @command{pwd} prints the name of the current directory. Synopsis:
14940 pwd [@var{option}]@dots{}
14943 The program accepts the following options. Also see @ref{Common options}.
14950 If the contents of the environment variable @env{PWD} provide an
14951 absolute name of the current directory with no @samp{.} or @samp{..}
14952 components, but possibly with symbolic links, then output those
14953 contents. Otherwise, fall back to default @option{-P} handling.
14958 @opindex --physical
14959 Print a fully resolved name for the current directory. That is, all
14960 components of the printed name will be actual directory names -- none
14961 will be symbolic links.
14964 @cindex symbolic links and @command{pwd}
14965 If @option{-L} and @option{-P} are both given, the last one takes
14966 precedence. If neither option is given, then this implementation uses
14967 @option{-P} as the default unless the @env{POSIXLY_CORRECT}
14968 environment variable is set.
14970 @mayConflictWithShellBuiltIn{pwd}
14975 @node stty invocation
14976 @section @command{stty}: Print or change terminal characteristics
14979 @cindex change or print terminal settings
14980 @cindex terminal settings
14981 @cindex line settings of terminal
14983 @command{stty} prints or changes terminal characteristics, such as baud rate.
14987 stty [@var{option}] [@var{setting}]@dots{}
14988 stty [@var{option}]
14991 If given no line settings, @command{stty} prints the baud rate, line
14992 discipline number (on systems that support it), and line settings
14993 that have been changed from the values set by @samp{stty sane}.
14994 By default, mode reading and setting are performed on the tty line
14995 connected to standard input, although this can be modified by the
14996 @option{--file} option.
14998 @command{stty} accepts many non-option arguments that change aspects of
14999 the terminal line operation, as described below.
15001 The program accepts the following options. Also see @ref{Common options}.
15008 Print all current settings in human-readable form. This option may not
15009 be used in combination with any line settings.
15011 @item -F @var{device}
15012 @itemx --file=@var{device}
15015 Set the line opened by the file name specified in @var{device} instead of
15016 the tty line connected to standard input. This option is necessary
15017 because opening a POSIX tty requires use of the
15018 @code{O_NONDELAY} flag to prevent a POSIX tty from blocking
15019 until the carrier detect line is high if
15020 the @code{clocal} flag is not set. Hence, it is not always possible
15021 to allow the shell to open the device in the traditional manner.
15027 @cindex machine-readable @command{stty} output
15028 Print all current settings in a form that can be used as an argument to
15029 another @command{stty} command to restore the current settings. This option
15030 may not be used in combination with any line settings.
15034 Many settings can be turned off by preceding them with a @samp{-}.
15035 Such arguments are marked below with ``May be negated'' in their
15036 description. The descriptions themselves refer to the positive
15037 case, that is, when @emph{not} negated (unless stated otherwise,
15040 Some settings are not available on all POSIX systems, since they use
15041 extensions. Such arguments are marked below with
15042 ``Non-POSIX'' in their description. On non-POSIX
15043 systems, those or other settings also may not
15044 be available, but it's not feasible to document all the variations: just
15047 @command{stty} is installed only on platforms with the POSIX terminal
15048 interface, so portable scripts should not rely on its existence on
15049 non-POSIX platforms.
15054 * Control:: Control settings
15055 * Input:: Input settings
15056 * Output:: Output settings
15057 * Local:: Local settings
15058 * Combination:: Combination settings
15059 * Characters:: Special characters
15060 * Special:: Special settings
15065 @subsection Control settings
15067 @cindex control settings
15073 @cindex two-way parity
15074 Generate parity bit in output and expect parity bit in input.
15080 @cindex even parity
15081 Set odd parity (even if negated). May be negated.
15085 @cindex constant parity
15086 @cindex stick parity
15087 @cindex mark parity
15088 @cindex space parity
15089 Use "stick" (mark/space) parity. If parodd is set, the parity bit is
15090 always 1; if parodd is not set, the parity bit is always zero.
15091 Non-POSIX@. May be negated.
15098 @cindex character size
15099 @cindex eight-bit characters
15100 Set character size to 5, 6, 7, or 8 bits.
15105 Send a hangup signal when the last process closes the tty. May be
15111 Use two stop bits per character (one if negated). May be negated.
15115 Allow input to be received. May be negated.
15119 @cindex modem control
15120 Disable modem control signals. May be negated.
15124 @cindex hardware flow control
15125 @cindex flow control, hardware
15126 @cindex RTS/CTS flow control
15127 Enable RTS/CTS flow control. Non-POSIX@. May be negated.
15131 @cindex hardware flow control
15132 @cindex flow control, hardware
15133 @cindex DTR/DSR flow control
15134 Enable DTR/DSR flow control. Non-POSIX@. May be negated.
15139 @subsection Input settings
15141 @cindex input settings
15142 These settings control operations on data received from the terminal.
15147 @cindex breaks, ignoring
15148 Ignore break characters. May be negated.
15152 @cindex breaks, cause interrupts
15153 Make breaks cause an interrupt signal. May be negated.
15157 @cindex parity, ignoring
15158 Ignore characters with parity errors. May be negated.
15162 @cindex parity errors, marking
15163 Mark parity errors (with a 255-0-character sequence). May be negated.
15167 Enable input parity checking. May be negated.
15171 @cindex eight-bit input
15172 Clear high (8th) bit of input characters. May be negated.
15176 @cindex newline, translating to return
15177 Translate newline to carriage return. May be negated.
15181 @cindex return, ignoring
15182 Ignore carriage return. May be negated.
15186 @cindex return, translating to newline
15187 Translate carriage return to newline. May be negated.
15191 @cindex input encoding, UTF-8
15192 Assume input characters are UTF-8 encoded. May be negated.
15196 @kindex C-s/C-q flow control
15197 @cindex XON/XOFF flow control
15198 Enable XON/XOFF flow control (that is, @kbd{Ctrl-S}/@kbd{Ctrl-Q}). May
15205 @cindex software flow control
15206 @cindex flow control, software
15207 Enable sending of @code{stop} character when the system input buffer
15208 is almost full, and @code{start} character when it becomes almost
15209 empty again. May be negated.
15213 @cindex uppercase, translating to lowercase
15214 Translate uppercase characters to lowercase. Non-POSIX@. May be
15215 negated. Note ilcuc is not implemented, as one would not be able to issue
15216 almost any (lowercase) Unix command, after invoking it.
15220 Allow any character to restart output (only the start character
15221 if negated). Non-POSIX@. May be negated.
15225 @cindex beeping at input buffer full
15226 Enable beeping and not flushing input buffer if a character arrives
15227 when the input buffer is full. Non-POSIX@. May be negated.
15232 @subsection Output settings
15234 @cindex output settings
15235 These settings control operations on data sent to the terminal.
15240 Postprocess output. May be negated.
15244 @cindex lowercase, translating to output
15245 Translate lowercase characters to uppercase. Non-POSIX@. May be
15246 negated. (Note ouclc is not currently implemented.)
15250 @cindex return, translating to newline
15251 Translate carriage return to newline. Non-POSIX@. May be negated.
15255 @cindex newline, translating to crlf
15256 Translate newline to carriage return-newline. Non-POSIX@. May be
15261 Do not print carriage returns in the first column. Non-POSIX@.
15266 Newline performs a carriage return. Non-POSIX@. May be negated.
15270 @cindex pad instead of timing for delaying
15271 Use fill (padding) characters instead of timing for delays.
15277 @cindex pad character
15278 Use ASCII DEL characters for fill instead of
15279 ASCII NUL characters. Non-POSIX@.
15285 Newline delay style. Non-POSIX.
15292 Carriage return delay style. Non-POSIX.
15298 @opindex tab@var{n}
15299 Horizontal tab delay style. Non-POSIX.
15304 Backspace delay style. Non-POSIX.
15309 Vertical tab delay style. Non-POSIX.
15314 Form feed delay style. Non-POSIX.
15319 @subsection Local settings
15321 @cindex local settings
15326 Enable @code{interrupt}, @code{quit}, and @code{suspend} special
15327 characters. May be negated.
15331 Enable @code{erase}, @code{kill}, @code{werase}, and @code{rprnt}
15332 special characters. May be negated.
15336 Enable non-POSIX special characters. May be negated.
15340 Echo input characters. May be negated.
15346 Echo @code{erase} characters as backspace-space-backspace. May be
15351 @cindex newline echoing after @code{kill}
15352 Echo a newline after a @code{kill} character. May be negated.
15356 @cindex newline, echoing
15357 Echo newline even if not echoing other characters. May be negated.
15361 @cindex flushing, disabling
15362 Disable flushing after @code{interrupt} and @code{quit} special
15363 characters. May be negated.
15367 @cindex case translation
15368 Enable input and output of uppercase characters by preceding their
15369 lowercase equivalents with @samp{\}, when @code{icanon} is set.
15370 Non-POSIX@. May be negated.
15374 @cindex background jobs, stopping at terminal write
15375 Stop background jobs that try to write to the terminal. Non-POSIX@.
15382 Echo erased characters backward, between @samp{\} and @samp{/}.
15383 Non-POSIX@. May be negated.
15389 @cindex control characters, using @samp{^@var{c}}
15390 @cindex hat notation for control characters
15391 Echo control characters in hat notation (@samp{^@var{c}}) instead
15392 of literally. Non-POSIX@. May be negated.
15398 Echo the @code{kill} special character by erasing each character on
15399 the line as indicated by the @code{echoprt} and @code{echoe} settings,
15400 instead of by the @code{echoctl} and @code{echok} settings.
15406 Enable @samp{LINEMODE}, which is used to avoid echoing
15407 each character over high latency links. See also
15408 @uref{https://tools.ietf.org/search/rfc1116, Internet RFC 1116}.
15415 Note this setting is currently ignored on GNU/Linux systems.
15422 @subsection Combination settings
15424 @cindex combination settings
15425 Combination settings:
15432 Same as @code{parenb -parodd cs7}. May be negated. If negated, same
15433 as @code{-parenb cs8}.
15437 Same as @code{parenb parodd cs7}. May be negated. If negated, same
15438 as @code{-parenb cs8}.
15442 Same as @code{-icrnl -onlcr}. May be negated. If negated, same as
15443 @code{icrnl -inlcr -igncr onlcr -ocrnl -onlret}.
15447 Reset the @code{erase} and @code{kill} special characters to their default
15454 @c This is too long to write inline.
15456 cread -ignbrk brkint -inlcr -igncr icrnl
15457 icanon iexten echo echoe echok -echonl -noflsh
15458 -ixoff -iutf8 -iuclc -ixany imaxbel -xcase -olcuc -ocrnl
15459 opost -ofill onlcr -onocr -onlret nl0 cr0 tab0 bs0 vt0 ff0
15460 isig -tostop -ofdel -echoprt echoctl echoke -extproc
15464 and also sets all special characters to their default values.
15468 Same as @code{brkint ignpar istrip icrnl ixon opost isig icanon}, plus
15469 sets the @code{eof} and @code{eol} characters to their default values
15470 if they are the same as the @code{min} and @code{time} characters.
15471 May be negated. If negated, same as @code{raw}.
15478 -ignbrk -brkint -ignpar -parmrk -inpck -istrip
15479 -inlcr -igncr -icrnl -ixon -ixoff -icanon -opost
15480 -isig -iuclc -ixany -imaxbel -xcase min 1 time 0
15484 May be negated. If negated, same as @code{cooked}.
15488 Same as @option{-icanon}. May be negated. If negated, same as
15493 @cindex eight-bit characters
15494 Same as @code{-parenb -istrip cs8}. May be negated. If negated,
15495 same as @code{parenb istrip cs7}.
15499 Same as @option{-parenb -istrip -opost cs8}. May be negated.
15500 If negated, same as @code{parenb istrip opost cs7}.
15504 Same as @option{-ixany}. Non-POSIX@. May be negated.
15508 Same as @code{tab0}. Non-POSIX@. May be negated. If negated, same
15515 Same as @code{xcase iuclc olcuc}. Non-POSIX@. May be negated.
15516 (Used for terminals with uppercase characters only.)
15520 Same as @code{echoe echoctl echoke}.
15524 Same as @code{echoe echoctl echoke -ixany intr ^C erase ^? kill C-u}.
15529 @subsection Special characters
15531 @cindex special characters
15532 @cindex characters, special
15534 The special characters' default values vary from system to system.
15535 They are set with the syntax @samp{name value}, where the names are
15536 listed below and the value can be given either literally, in hat
15537 notation (@samp{^@var{c}}), or as an integer which may start with
15538 @samp{0x} to indicate hexadecimal, @samp{0} to indicate octal, or
15539 any other digit to indicate decimal.
15541 @cindex disabling special characters
15542 @kindex u@r{, and disabling special characters}
15543 For GNU stty, giving a value of @code{^-} or @code{undef} disables that
15544 special character. (This is incompatible with Ultrix @command{stty},
15545 which uses a value of @samp{u} to disable a special character. GNU
15546 @command{stty} treats a value @samp{u} like any other, namely to set that
15547 special character to @key{U}.)
15553 Send an interrupt signal.
15557 Send a quit signal.
15561 Erase the last character typed.
15565 Erase the current line.
15569 Send an end of file (terminate the input).
15577 Alternate character to end the line. Non-POSIX.
15582 Alternate character to toggle discarding of output. Non-POSIX.
15586 Switch to a different shell layer. Non-POSIX.
15590 Send an info signal. Not currently supported on GNU/Linux. Non-POSIX.
15594 Restart the output after stopping it.
15602 Send a terminal stop signal.
15606 Send a terminal stop signal after flushing the input. Non-POSIX.
15610 Redraw the current line. Non-POSIX.
15614 Erase the last word typed. Non-POSIX.
15618 Enter the next character typed literally, even if it is a special
15619 character. Non-POSIX.
15624 @subsection Special settings
15626 @cindex special settings
15631 Set the minimum number of characters that will satisfy a read until
15632 the time value has expired, when @option{-icanon} is set.
15636 Set the number of tenths of a second before reads time out if the minimum
15637 number of characters have not been read, when @option{-icanon} is set.
15639 @item ispeed @var{n}
15641 Set the input speed to @var{n}.
15643 @item ospeed @var{n}
15645 Set the output speed to @var{n}.
15649 Tell the tty kernel driver that the terminal has @var{n} rows.
15653 @itemx columns @var{n}
15656 Tell the kernel that the terminal has @var{n} columns. Non-POSIX.
15660 @cindex nonblocking @command{stty} setting
15661 Apply settings after first waiting for pending output to be transmitted.
15662 This is enabled by default for GNU @command{stty}.
15663 Note this is treated as an option rather than a line setting,
15664 and will follow the option processing rules described in the summary above.
15665 It is useful to disable this option
15666 in cases where the system may be in a state where serial transmission
15668 For example, if the system has received the @samp{DC3} character
15669 with @code{ixon} (software flow control) enabled, then @command{stty} would
15670 block without @code{-drain} being specified.
15671 May be negated. Non-POSIX.
15677 Print the number of rows and columns that the kernel thinks the
15678 terminal has. (Systems that don't support rows and columns in the kernel
15679 typically use the environment variables @env{LINES} and @env{COLUMNS}
15680 instead; however, GNU @command{stty} does not know anything about them.)
15685 Use line discipline @var{n}. Non-POSIX.
15689 Print the terminal speed.
15692 @cindex baud rate, setting
15693 Set the input and output speeds to @var{n}. @var{n} can be one of: 0
15694 50 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 19200
15695 38400 @code{exta} @code{extb}. @code{exta} is the same as 19200;
15696 @code{extb} is the same as 38400. Many systems, including GNU/Linux,
15697 support higher speeds. The @command{stty} command includes support
15714 4000000 where the system supports these.
15715 0 hangs up the line if @option{-clocal} is set.
15719 @node printenv invocation
15720 @section @command{printenv}: Print all or some environment variables
15723 @cindex printing all or some environment variables
15724 @cindex environment variables, printing
15726 @command{printenv} prints environment variable values. Synopsis:
15729 printenv [@var{option}] [@var{variable}]@dots{}
15732 If no @var{variable}s are specified, @command{printenv} prints the value of
15733 every environment variable. Otherwise, it prints the value of each
15734 @var{variable} that is set, and nothing for those that are not set.
15736 The program accepts the following option. Also see @ref{Common options}.
15744 @cindex exit status of @command{printenv}
15748 0 if all variables specified were found
15749 1 if at least one specified variable was not found
15750 2 if a write error occurred
15754 @node tty invocation
15755 @section @command{tty}: Print file name of terminal on standard input
15758 @cindex print terminal file name
15759 @cindex terminal file name, printing
15761 @command{tty} prints the file name of the terminal connected to its standard
15762 input. It prints @samp{not a tty} if standard input is not a terminal.
15766 tty [@var{option}]@dots{}
15769 The program accepts the following option. Also see @ref{Common options}.
15779 Print nothing; only return an exit status.
15783 @cindex exit status of @command{tty}
15787 0 if standard input is a terminal
15788 1 if standard input is a non-terminal file
15789 2 if given incorrect arguments
15790 3 if a write error occurs
15794 @node User information
15795 @chapter User information
15797 @cindex user information, commands for
15798 @cindex commands for printing user information
15800 This section describes commands that print user-related information:
15801 logins, groups, and so forth.
15804 * id invocation:: Print user identity.
15805 * logname invocation:: Print current login name.
15806 * whoami invocation:: Print effective user ID.
15807 * groups invocation:: Print group names a user is in.
15808 * users invocation:: Print login names of users currently logged in.
15809 * who invocation:: Print who is currently logged in.
15813 @node id invocation
15814 @section @command{id}: Print user identity
15817 @cindex real user and group IDs, printing
15818 @cindex effective user and group IDs, printing
15819 @cindex printing real and effective user and group IDs
15821 @command{id} prints information about the given user, or the process
15822 running it if no user is specified. Synopsis:
15825 id [@var{option}]@dots{} [@var{user}]@dots{}
15828 @var{user} can be either a user ID or a name, with name look-up
15829 taking precedence unless the ID is specified with a leading @samp{+}.
15830 @xref{Disambiguating names and IDs}.
15832 @vindex POSIXLY_CORRECT
15833 By default, it prints the real user ID, real group ID, effective user ID
15834 if different from the real user ID, effective group ID if different from
15835 the real group ID, and supplemental group IDs.
15836 In addition, if SELinux
15837 is enabled and the @env{POSIXLY_CORRECT} environment variable is not set,
15838 then print @samp{context=@var{c}}, where @var{c} is the security context.
15840 Each of these numeric values is preceded by an identifying string and
15841 followed by the corresponding user or group name in parentheses.
15843 The options cause @command{id} to print only part of the above information.
15844 Also see @ref{Common options}.
15851 Print only the group ID.
15857 Print only the group ID and the supplementary groups.
15863 Print the user or group name instead of the ID number. Requires
15864 @option{-u}, @option{-g}, or @option{-G}.
15870 Print the real, instead of effective, user or group ID@. Requires
15871 @option{-u}, @option{-g}, or @option{-G}.
15877 Print only the user ID.
15884 @cindex security context
15885 Print only the security context of the process, which is generally
15886 the user's security context inherited from the parent process.
15887 If neither SELinux or SMACK is enabled then print a warning and
15888 set the exit status to 1.
15894 Delimit output items with ASCII NUL characters.
15895 This option is not permitted when using the default format.
15896 When multiple users are specified, and the @option{--groups} option
15897 is also in effect, groups are delimited with a single NUL character,
15898 while users are delimited with two NUL characters.
15903 users <NUL> devs <NUL>
15908 @macro primaryAndSupplementaryGroups{cmd,arg}
15909 Primary and supplementary groups for a process are normally inherited
15910 from its parent and are usually unchanged since login. This means
15911 that if you change the group database after logging in, @command{\cmd\}
15912 will not reflect your changes within your existing login session.
15913 Running @command{\cmd\} with a \arg\ causes the user and group
15914 database to be consulted afresh, and so will give a different result.
15916 @primaryAndSupplementaryGroups{id,user argument}
15920 @node logname invocation
15921 @section @command{logname}: Print current login name
15924 @cindex printing user's login name
15925 @cindex login name, printing
15926 @cindex user name, printing
15929 @command{logname} prints the calling user's name, as found in a
15930 system-maintained file (often @file{/var/run/utmp} or
15931 @file{/etc/utmp}), and exits with a status of 0. If there is no entry
15932 for the calling process, @command{logname} prints
15933 an error message and exits with a status of 1.
15935 The only options are @option{--help} and @option{--version}. @xref{Common
15941 @node whoami invocation
15942 @section @command{whoami}: Print effective user name
15945 @cindex effective user name, printing
15946 @cindex printing the effective user ID
15948 @command{whoami} prints the user name associated with the current
15949 effective user ID@. It is equivalent to the command @samp{id -un}.
15951 The only options are @option{--help} and @option{--version}. @xref{Common
15957 @node groups invocation
15958 @section @command{groups}: Print group names a user is in
15961 @cindex printing groups a user is in
15962 @cindex supplementary groups, printing
15964 @command{groups} prints the names of the primary and any supplementary
15965 groups for each given @var{username}, or the current process if no names
15966 are given. If more than one name is given, the name of each user is
15968 the list of that user's groups and the user name is separated from the
15969 group list by a colon. Synopsis:
15972 groups [@var{username}]@dots{}
15975 The group lists are equivalent to the output of the command @samp{id -Gn}.
15977 The only options are @option{--help} and @option{--version}. @xref{Common
15980 @primaryAndSupplementaryGroups{groups,list of users}
15984 @node users invocation
15985 @section @command{users}: Print login names of users currently logged in
15988 @cindex printing current usernames
15989 @cindex usernames, printing current
15991 @cindex login sessions, printing users with
15992 @command{users} prints on a single line a blank-separated list of user
15993 names of users currently logged in to the current host. Each user name
15994 corresponds to a login session, so if a user has more than one login
15995 session, that user's name will appear the same number of times in the
16004 With no @var{file} argument, @command{users} extracts its information from
16005 a system-maintained file (often @file{/var/run/utmp} or
16006 @file{/etc/utmp}). If a file argument is given, @command{users} uses
16007 that file instead. A common choice is @file{/var/log/wtmp}.
16009 The only options are @option{--help} and @option{--version}. @xref{Common
16012 The @command{users} command is installed only on platforms with the
16013 POSIX @code{<utmpx.h>} include file or equivalent, so portable scripts
16014 should not rely on its existence on non-POSIX platforms.
16019 @node who invocation
16020 @section @command{who}: Print who is currently logged in
16023 @cindex printing current user information
16024 @cindex information, about current users
16026 @command{who} prints information about users who are currently logged on.
16030 @command{who} [@var{option}] [@var{file}] [am i]
16033 @cindex terminal lines, currently used
16035 @cindex remote hostname
16036 If given no non-option arguments, @command{who} prints the following
16037 information for each user currently logged on: login name, terminal
16038 line, login time, and remote hostname or X display.
16042 If given one non-option argument, @command{who} uses that instead of
16043 a default system-maintained file (often @file{/var/run/utmp} or
16044 @file{/etc/utmp}) as the name of the file containing the record of
16045 users logged on. @file{/var/log/wtmp} is commonly given as an argument
16046 to @command{who} to look at who has previously logged on.
16050 If given two non-option arguments, @command{who} prints only the entry
16051 for the user running it (determined from its standard input), preceded
16052 by the hostname. Traditionally, the two arguments given are @samp{am
16053 i}, as in @samp{who am i}.
16056 Timestamps are listed according to the time zone rules specified by
16057 the @env{TZ} environment variable, or by the system default rules if
16058 @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone
16059 with @env{TZ}, libc, The GNU C Library Reference Manual}.
16061 The program accepts the following options. Also see @ref{Common options}.
16069 Same as @samp{-b -d --login -p -r -t -T -u}.
16075 Print the date and time of last system boot.
16081 Print information corresponding to dead processes.
16087 Print a line of column headings.
16093 List only the entries that correspond to processes via which the
16094 system is waiting for a user to login. The user name is always @samp{LOGIN}.
16098 Attempt to canonicalize hostnames found in utmp through a DNS lookup. This
16099 is not the default because it can cause significant delays on systems with
16100 automatic dial-up internet access.
16104 Same as @samp{who am i}.
16110 List active processes spawned by init.
16116 Print only the login names and the number of users logged on.
16117 Overrides all other options.
16122 @opindex --runlevel
16123 Print the current (and maybe previous) run-level of the init process.
16127 Ignored; for compatibility with other versions of @command{who}.
16133 Print last system clock change.
16138 After the login time, print the number of hours and minutes that the
16139 user has been idle. @samp{.} means the user was active in the last minute.
16140 @samp{old} means the user has been idle for more than 24 hours.
16151 @opindex --writable
16152 @cindex message status
16153 @pindex write@r{, allowed}
16154 After each login name print a character indicating the user's message status:
16157 @samp{+} allowing @code{write} messages
16158 @samp{-} disallowing @code{write} messages
16159 @samp{?} cannot find terminal device
16164 The @command{who} command is installed only on platforms with the
16165 POSIX @code{<utmpx.h>} include file or equivalent, so portable scripts
16166 should not rely on its existence on non-POSIX platforms.
16171 @node System context
16172 @chapter System context
16174 @cindex system context
16175 @cindex context, system
16176 @cindex commands for system context
16178 This section describes commands that print or change system-wide
16182 * date invocation:: Print or set system date and time.
16183 * arch invocation:: Print machine hardware name.
16184 * nproc invocation:: Print the number of processors.
16185 * uname invocation:: Print system information.
16186 * hostname invocation:: Print or set system name.
16187 * hostid invocation:: Print numeric host identifier.
16188 * uptime invocation:: Print system uptime and load.
16191 @node date invocation
16192 @section @command{date}: Print or set system date and time
16195 @cindex time, printing or setting
16196 @cindex printing the current time
16201 date [@var{option}]@dots{} [+@var{format}]
16202 date [-u|--utc|--universal] @c this avoids a newline in the output
16203 [ MMDDhhmm[[CC]YY][.ss] ]
16206 The @command{date} command displays the date and time.
16207 With the @option{--set} (@option{-s}) option, or with
16208 @samp{MMDDhhmm[[CC]YY][.ss]},
16209 it sets the date and time.
16212 Invoking @command{date} with no @var{format} argument is equivalent to invoking
16213 it with a default format that depends on the @env{LC_TIME} locale category.
16214 In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'},
16215 so the output looks like @samp{Thu Jul @ 9 17:00:00 EDT 2020}.
16218 Normally, @command{date} uses the time zone rules indicated by the
16219 @env{TZ} environment variable, or the system default rules if @env{TZ}
16220 is not set. @xref{TZ Variable,, Specifying the Time Zone with
16221 @env{TZ}, libc, The GNU C Library Reference Manual}.
16223 @findex strftime @r{and @command{date}}
16224 @cindex time formats
16225 @cindex formatting times
16226 If given an argument that starts with a @samp{+}, @command{date} prints the
16227 current date and time (or the date and time specified by the
16228 @option{--date} option, see below) in the format defined by that argument,
16229 which is similar to that of the @code{strftime} function. Except for
16230 conversion specifiers, which start with @samp{%}, characters in the
16231 format string are printed unchanged. The conversion specifiers are
16237 * Time conversion specifiers:: %[HIklMNpPrRsSTXzZ]
16238 * Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY]
16239 * Literal conversion specifiers:: %[%nt]
16240 * Padding and other flags:: Pad with zeros, spaces, etc.
16241 * Setting the time:: Changing the system clock.
16242 * Options for date:: Instead of the current time.
16244 * Date input formats:: Specifying date strings.
16246 * Examples of date:: Examples.
16249 @node Time conversion specifiers
16250 @subsection Time conversion specifiers
16252 @cindex time conversion specifiers
16253 @cindex conversion specifiers, time
16255 @command{date} conversion specifiers related to times.
16259 hour (@samp{00}@dots{}@samp{23})
16261 hour (@samp{01}@dots{}@samp{12})
16263 hour, space padded (@samp{ 0}@dots{}@samp{23}); equivalent to @samp{%_H}@.
16264 This is a GNU extension.
16266 hour, space padded (@samp{ 1}@dots{}@samp{12}); equivalent to @samp{%_I}@.
16267 This is a GNU extension.
16269 minute (@samp{00}@dots{}@samp{59})
16271 nanoseconds (@samp{000000000}@dots{}@samp{999999999}).
16272 This is a GNU extension.
16274 locale's equivalent of either @samp{AM} or @samp{PM};
16275 blank in many locales.
16276 Noon is treated as @samp{PM} and midnight as @samp{AM}.
16278 like @samp{%p}, except lower case.
16279 This is a GNU extension.
16281 locale's 12-hour clock time (e.g., @samp{11:11:04 PM})
16283 24-hour hour and minute. Same as @samp{%H:%M}.
16285 @cindex Epoch, seconds since
16286 @cindex seconds since the Epoch
16287 @cindex beginning of time
16288 @cindex leap seconds
16289 seconds since the Epoch, i.e., since 1970-01-01 00:00 UTC@.
16290 Leap seconds are not counted unless leap second support is available.
16291 @xref{%s-examples}, for examples.
16292 This is a GNU extension.
16294 @cindex leap seconds
16295 second (@samp{00}@dots{}@samp{60}).
16296 This may be @samp{60} if leap seconds are supported.
16298 24-hour hour, minute, and second. Same as @samp{%H:%M:%S}.
16300 locale's time representation (e.g., @samp{23:13:48})
16302 Four-digit numeric time zone, e.g., @samp{-0600} or @samp{+0530}, or
16304 time zone is determinable. This value reflects the numeric time zone
16305 appropriate for the current time, using the time zone rules specified
16306 by the @env{TZ} environment variable. A time zone is not determinable if
16307 its numeric offset is zero and its abbreviation begins with @samp{-}.
16308 The time (and optionally, the time zone rules) can be overridden
16309 by the @option{--date} option.
16311 Numeric time zone with @samp{:}, e.g., @samp{-06:00} or
16312 @samp{+05:30}), or @samp{-00:00} if no time zone is determinable.
16313 This is a GNU extension.
16315 Numeric time zone to the nearest second with @samp{:} (e.g.,
16316 @samp{-06:00:00} or @samp{+05:30:00}), or @samp{-00:00:00} if no time zone is
16318 This is a GNU extension.
16320 Numeric time zone with @samp{:} using the minimum necessary precision
16321 (e.g., @samp{-06}, @samp{+05:30}, or @samp{-04:56:02}), or @samp{-00} if
16322 no time zone is determinable.
16323 This is a GNU extension.
16325 alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no
16326 time zone is determinable. See @samp{%z} for how it is determined.
16330 @node Date conversion specifiers
16331 @subsection Date conversion specifiers
16333 @cindex date conversion specifiers
16334 @cindex conversion specifiers, date
16336 @command{date} conversion specifiers related to dates.
16340 locale's abbreviated weekday name (e.g., @samp{Sun})
16342 locale's full weekday name, variable length (e.g., @samp{Sunday})
16344 locale's abbreviated month name (e.g., @samp{Jan})
16346 locale's full month name, variable length (e.g., @samp{January})
16348 locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2020})
16350 century. This is like @samp{%Y}, except the last two digits are omitted.
16351 For example, it is @samp{20} if @samp{%Y} is @samp{2019},
16352 and is @samp{-0} if @samp{%Y} is @samp{-001}.
16353 It is normally at least two characters, but it may be more.
16355 day of month (e.g., @samp{01})
16357 date; same as @samp{%m/%d/%y}
16359 day of month, space padded; same as @samp{%_d}
16361 full date in ISO 8601 format; like @samp{%+4Y-%m-%d}
16362 except that any flags or field width override the @samp{+}
16363 and (after subtracting 6) the @samp{4}.
16364 This is a good choice for a date format, as it is standard and
16365 is easy to sort in the usual case where years are in the range
16368 year corresponding to the ISO week number, but without the century
16369 (range @samp{00} through @samp{99}). This has the same format and value
16370 as @samp{%y}, except that if the ISO week number (see
16372 to the previous or next year, that year is used instead.
16374 year corresponding to the ISO week number. This has the
16375 same format and value as @samp{%Y}, except that if the ISO
16377 @samp{%V}) belongs to the previous or next year, that year is used
16379 It is normally useful only if @samp{%V} is also used;
16380 for example, the format @samp{%G-%m-%d} is probably a mistake,
16381 since it combines the ISO week number year with the conventional month and day.
16385 day of year (@samp{001}@dots{}@samp{366})
16387 month (@samp{01}@dots{}@samp{12})
16389 quarter of year (@samp{1}@dots{}@samp{4})
16391 day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday
16393 week number of year, with Sunday as the first day of the week
16394 (@samp{00}@dots{}@samp{53}).
16395 Days in a new year preceding the first Sunday are in week zero.
16397 ISO week number, that is, the
16398 week number of year, with Monday as the first day of the week
16399 (@samp{01}@dots{}@samp{53}).
16400 If the week containing January 1 has four or more days in
16401 the new year, then it is considered week 1; otherwise, it is week 53 of
16402 the previous year, and the next week is week 1. (See the ISO 8601
16405 day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday
16407 week number of year, with Monday as first day of week
16408 (@samp{00}@dots{}@samp{53}).
16409 Days in a new year preceding the first Monday are in week zero.
16411 locale's date representation (e.g., @samp{12/31/99})
16413 last two digits of year (@samp{00}@dots{}@samp{99})
16415 year. This is normally at least four characters, but it may be more.
16416 Year @samp{0000} precedes year @samp{0001}, and year @samp{-001}
16417 precedes year @samp{0000}.
16421 @node Literal conversion specifiers
16422 @subsection Literal conversion specifiers
16424 @cindex literal conversion specifiers
16425 @cindex conversion specifiers, literal
16427 @command{date} conversion specifiers that produce literal strings.
16439 @node Padding and other flags
16440 @subsection Padding and other flags
16442 @cindex numeric field padding
16443 @cindex padding of numeric fields
16444 @cindex fields, padding numeric
16446 Unless otherwise specified, @command{date} normally pads numeric fields
16447 with zeros, so that, for
16448 example, numeric months are always output as two digits.
16449 Most numeric fields are padded on the left.
16450 However, nanoseconds are padded on the right since they are commonly
16451 used after decimal points in formats like @samp{%s.%-N}.
16452 Also, seconds since the Epoch are not padded
16453 since there is no natural width for them.
16455 The following optional flags can appear after the @samp{%}:
16459 (hyphen) Do not pad the field; useful if the output is intended for
16461 This is a GNU extension.
16462 As a special case, @samp{%-N} outputs only enough trailing digits to
16463 not lose information, assuming that the timestamp's resolution is the
16464 same as the current hardware clock. For example, if the hardware
16465 clock resolution is 1 microsecond, @samp{%s.%-N} outputs something
16466 like @samp{1640890100.395710}.
16469 (underscore) Pad with spaces; useful if you need a fixed
16470 number of characters in the output, but zeros are too distracting.
16471 This is a GNU extension.
16473 (zero) Pad with zeros even if the conversion specifier
16474 would normally pad with spaces.
16476 Pad with zeros, like @samp{0}. In addition, precede any year number
16477 with @samp{+} if it exceeds 9999 or if its field width exceeds 4;
16478 similarly, precede any century number with @samp{+} if it exceeds 99
16479 or if its field width exceeds 2. This supports ISO 8601 formats
16480 for dates far in the future; for example, the command @code{date
16481 --date=12019-02-25 +%+13F} outputs the string @samp{+012019-02-25}.
16483 Use upper case characters if possible.
16484 This is a GNU extension.
16486 Use opposite case characters if possible.
16487 A field that is normally upper case becomes lower case, and vice versa.
16488 This is a GNU extension.
16492 Here are some examples of padding:
16495 date +%d/%m -d "Feb 1"
16497 date +%-d/%-m -d "Feb 1"
16499 date +%_d/%_m -d "Feb 1"
16503 You can optionally specify the field width
16504 (after any flag, if present) as a decimal number. If the natural size of the
16505 output of the field has less than the specified number of characters,
16506 the result is normally written right adjusted and padded to the given
16507 size. For example, @samp{%9B} prints the right adjusted month name in
16508 a field of width 9. Nanoseconds are left adjusted, and are truncated
16509 or padded to the field width.
16511 An optional modifier can follow the optional flag and width
16512 specification. The modifiers are:
16516 Use the locale's alternate representation for date and time. This
16517 modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X},
16518 @samp{%y} and @samp{%Y} conversion specifiers. In a Japanese locale, for
16519 example, @samp{%Ex} might yield a date format based on the Japanese
16523 Use the locale's alternate numeric symbols for numbers. This modifier
16524 applies only to numeric conversion specifiers.
16527 If the format supports the modifier but no alternate representation
16528 is available, it is ignored.
16530 POSIX specifies the behavior of flags and field widths only for
16531 @samp{%C}, @samp{%F}, @samp{%G}, and @samp{%Y} (all without
16532 modifiers), and requires a flag to be present if and only if a field
16533 width is also present. Other combinations of flags, field widths and
16534 modifiers are GNU extensions.
16537 @node Setting the time
16538 @subsection Setting the time
16540 @cindex setting the time
16541 @cindex time setting
16542 @cindex appropriate privileges
16544 You must have appropriate privileges to set the
16545 system clock. For changes to persist across a reboot, the
16546 hardware clock may need to be updated from the system clock, which
16547 might not happen automatically on your system.
16549 To set the clock, you can use the @option{--set} (@option{-s}) option
16550 (@pxref{Options for date}). To set the clock without using GNU
16551 extensions, you can give @command{date} an argument of the form
16552 @samp{MMDDhhmm[[CC]YY][.ss]} where each two-letter
16553 component stands for two digits with the following meanings:
16565 first two digits of year (optional)
16567 last two digits of year (optional)
16572 Note, the @option{--date} and @option{--set} options may not be used with an
16573 argument in the above format. The @option{--universal} option may be used
16574 with such an argument to indicate that the specified date and time are
16575 relative to Universal Time rather than to the local time zone.
16578 @node Options for date
16579 @subsection Options for @command{date}
16581 @cindex @command{date} options
16582 @cindex options for @command{date}
16584 The program accepts the following options. Also see @ref{Common options}.
16585 Except for @option{-u}, these options are all GNU extensions to POSIX.
16587 All options that specify the date to display are mutually exclusive.
16588 I.e.: @option{--date}, @option{--file}, @option{--reference},
16589 @option{--resolution}.
16593 @item -d @var{datestr}
16594 @itemx --date=@var{datestr}
16597 @cindex parsing date strings
16598 @cindex date strings, parsing
16599 @cindex arbitrary date strings, parsing
16602 @opindex next @var{day}
16603 @opindex last @var{day}
16604 Display the date and time specified in @var{datestr} instead of the
16605 current date and time. @var{datestr} can be in almost any common
16606 format. It can contain month names, time zones, @samp{am} and @samp{pm},
16607 @samp{yesterday}, etc. For example, @option{--date="2020-07-21
16608 14:19:13.489392193 +0530"} specifies the instant of time that is
16609 489,392,193 nanoseconds after July 21, 2020 at 2:19:13 PM in a
16610 time zone that is 5 hours and 30 minutes east of UTC.@*
16611 Note: input currently must be in locale independent format. E.g., the
16612 LC_TIME=C below is needed to print back the correct date in many locales:
16614 date -d "$(LC_TIME=C date)"
16616 @xref{Date input formats}.
16620 @cindex debugging date strings
16621 @cindex date strings, debugging
16622 @cindex arbitrary date strings, debugging
16623 Annotate the parsed date, display the effective time zone, and warn about
16626 @item -f @var{datefile}
16627 @itemx --file=@var{datefile}
16630 Parse each line in @var{datefile} as with @option{-d} and display the
16631 resulting date and time. If @var{datefile} is @samp{-}, use standard
16632 input. This is useful when you have many dates to process, because the
16633 system overhead of starting up the @command{date} executable many times can
16636 @item -I[@var{timespec}]
16637 @itemx --iso-8601[=@var{timespec}]
16638 @opindex -I[@var{timespec}]
16639 @opindex --iso-8601[=@var{timespec}]
16640 Display the date using an ISO 8601 format, @samp{%Y-%m-%d}.
16642 The argument @var{timespec} specifies the number of additional
16643 terms of the time to include. It can be one of the following:
16646 Print just the date. This is the default if @var{timespec} is omitted.
16647 This is like the format @code{%Y-%m-%d}.
16650 Also print hours and time zone.
16651 This is like the format @code{%Y-%m-%dT%H%:z}.
16654 Also print minutes.
16655 This is like the format @code{%Y-%m-%dT%H:%M%:z}.
16658 Also print seconds.
16659 This is like the format @code{%Y-%m-%dT%H:%M:%S%:z}.
16662 Also print nanoseconds.
16663 This is like the format @code{%Y-%m-%dT%H:%M:%S,%N%:z}.
16666 @macro dateParseNote
16667 This format is always suitable as input
16668 for the @option{--date} (@option{-d}) and @option{--file}
16669 (@option{-f}) options, regardless of the current locale.
16673 @item -r @var{file}
16674 @itemx --reference=@var{file}
16676 @opindex --reference
16677 Display the date and time of the last modification of @var{file},
16678 instead of the current date and time.
16681 @opindex --resolution
16682 Display the timestamp resolution instead of the time.
16683 Current clock timestamps that are output by @command{date}
16684 are integer multiples of the timestamp resolution.
16685 With this option, the format defaults to @samp{%s.%N}.
16686 For example, if the clock resolution is 1 millsecond,
16696 @opindex --rfc-email
16697 Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S
16698 %z}, evaluated in the C locale so abbreviations are always in English.
16702 Mon, 09 Jul 2020 17:00:00 -0400
16706 @opindex --rfc-2822
16707 This format conforms to Internet RFCs
16708 @uref{https://tools.ietf.org/search/rfc5322, 5322},
16709 @uref{https://tools.ietf.org/search/rfc2822, 2822} and
16710 @uref{https://tools.ietf.org/search/rfc822, 822}, the
16711 current and previous standards for Internet email.
16712 For compatibility with older versions of @command{date},
16713 @option{--rfc-2822} and @option{--rfc-822} are aliases for
16714 @option{--rfc-email}.
16716 @item --rfc-3339=@var{timespec}
16717 @opindex --rfc-3339=@var{timespec}
16718 Display the date using a format specified by
16719 @uref{https://tools.ietf.org/search/rfc3339, Internet
16720 RFC 3339}. This is like @option{--iso-8601}, except that a space rather
16721 than a @samp{T} separates dates from times, and a period rather than
16722 a comma separates seconds from subseconds.
16725 The argument @var{timespec} specifies how much of the time to include.
16726 It can be one of the following:
16730 Print just the full-date, e.g., @samp{2020-07-21}.
16731 This is like the format @samp{%Y-%m-%d}.
16734 Print the full-date and full-time separated by a space, e.g.,
16735 @samp{2020-07-21 04:30:37+05:30}. The output ends with a numeric
16736 time-offset; here the @samp{+05:30} means that local time is five
16737 hours and thirty minutes east of UTC@. This is like
16738 the format @samp{%Y-%m-%d %H:%M:%S%:z}.
16741 Like @samp{seconds}, but also print nanoseconds, e.g.,
16742 @samp{2020-07-21 04:30:37.998458565+05:30}.
16743 This is like the format @samp{%Y-%m-%d %H:%M:%S.%N%:z}.
16747 @item -s @var{datestr}
16748 @itemx --set=@var{datestr}
16751 Set the date and time to @var{datestr}. See @option{-d} above.
16752 See also @ref{Setting the time}.
16759 @opindex --universal
16760 @cindex Coordinated Universal Time
16762 @cindex Greenwich Mean Time
16764 @cindex leap seconds
16766 @cindex Universal Time
16767 Use Universal Time by operating as if the
16768 @env{TZ} environment variable were set to the string @samp{UTC0}.
16769 UTC stands for Coordinated Universal Time, established in 1960.
16770 Universal Time is often called ``Greenwich Mean Time'' (GMT) for
16771 historical reasons.
16772 Typically, systems ignore leap seconds and thus implement an
16773 approximation to UTC rather than true UTC.
16777 @node Examples of date
16778 @subsection Examples of @command{date}
16780 @cindex examples of @command{date}
16782 Here are a few examples. Also see the documentation for the @option{-d}
16783 option in the previous section.
16788 To print the date of the day before yesterday:
16791 date --date='2 days ago'
16795 To print the date of the day three months and one day hence:
16798 date --date='3 months 1 day'
16802 To print the day of year of Christmas in the current year:
16805 date --date='25 Dec' +%j
16809 To print the current full month name and the day of the month:
16815 But this may not be what you want because for the first nine days of
16816 the month, the @samp{%d} expands to a zero-padded two-digit field,
16817 for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}.
16820 To print a date without the leading zero for one-digit days
16821 of the month, you can use the (GNU extension)
16822 @samp{-} flag to suppress
16823 the padding altogether:
16826 date -d 1may '+%B %-d'
16830 To print the current date and time in the format required by many
16831 non-GNU versions of @command{date} when setting the system clock:
16834 date +%m%d%H%M%Y.%S
16838 To set the system clock forward by two minutes:
16841 date --set='+2 minutes'
16845 To print the date in Internet RFC 5322 format,
16846 use @samp{date --rfc-email}. Here is some example output:
16849 Tue, 09 Jul 2020 19:00:37 -0400
16852 @anchor{%s-examples}
16854 To convert a date string to the number of seconds since the Epoch
16855 (which is 1970-01-01 00:00 UTC), use the @option{--date} option with
16856 the @samp{%s} format. That can be useful in sorting and/or graphing
16857 and/or comparing data by date. The following command outputs the
16858 number of the seconds since the Epoch for the time two minutes after the
16862 date --date='1970-01-01 00:02:00 +0000' +%s
16866 If you do not specify time zone information in the date string,
16867 @command{date} uses your computer's idea of the time zone when
16868 interpreting the string. For example, if your computer's time zone is
16869 that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000
16870 seconds) behind UTC:
16873 # local time zone used
16874 date --date='1970-01-01 00:02:00' +%s
16879 If you're sorting or graphing dated data, your raw date values may be
16880 represented as seconds since the Epoch. But few people can look at
16881 the date @samp{1577836800} and casually note ``Oh, that's the first
16882 second of the year 2020 in Greenwich, England.''
16885 date --date='2020-01-01 UTC' +%s
16889 An alternative is to use the @option{--utc} (@option{-u}) option.
16890 Then you may omit @samp{UTC} from the date string. Although this
16891 produces the same result for @samp{%s} and many other format sequences,
16892 with a time zone offset different from zero, it would give a different
16893 result for zone-dependent formats like @samp{%z}.
16896 date -u --date=2020-07-21 +%s
16900 To convert such an unwieldy number of seconds back to
16901 a more readable form, use a command like this:
16904 date -d @@1595289600 +"%F %T %z"
16905 2020-07-20 20:00:00 -0400
16908 Often it is better to output UTC-relative date and time:
16911 date -u -d @@1595289600 +"%F %T %z"
16912 2020-07-21 00:00:00 +0000
16916 @cindex leap seconds
16917 Typically the seconds count omits leap seconds, but some systems are
16918 exceptions. Because leap seconds are not predictable, the mapping
16919 between the seconds count and a future timestamp is not reliable on
16920 the atypical systems that include leap seconds in their counts.
16922 Here is how the two kinds of systems handle the leap second at
16923 the end of the year 2016:
16926 # Typical systems ignore leap seconds:
16927 date --date='2016-12-31 23:59:59 +0000' +%s
16929 date --date='2016-12-31 23:59:60 +0000' +%s
16930 date: invalid date '2016-12-31 23:59:60 +0000'
16931 date --date='2017-01-01 00:00:00 +0000' +%s
16936 # Atypical systems count leap seconds:
16937 date --date='2016-12-31 23:59:59 +0000' +%s
16939 date --date='2016-12-31 23:59:60 +0000' +%s
16941 date --date='2017-01-01 00:00:00 +0000' +%s
16948 @node arch invocation
16949 @section @command{arch}: Print machine hardware name
16952 @cindex print machine hardware name
16953 @cindex system information, printing
16955 @command{arch} prints the machine hardware name,
16956 and is equivalent to @samp{uname -m}.
16960 arch [@var{option}]
16963 The program accepts the @ref{Common options} only.
16965 @command{arch} is not installed by default, so portable scripts should
16966 not rely on its existence.
16971 @node nproc invocation
16972 @section @command{nproc}: Print the number of available processors
16975 @cindex Print the number of processors
16976 @cindex system information, printing
16978 Print the number of processing units available to the current process,
16979 which may be less than the number of online processors.
16980 If this information is not accessible, then print the number of
16981 processors installed. If the @env{OMP_NUM_THREADS} or @env{OMP_THREAD_LIMIT}
16982 environment variables are set, then they will determine the minimum
16983 and maximum returned value respectively. The result is guaranteed to be
16984 greater than zero. Synopsis:
16987 nproc [@var{option}]
16990 The program accepts the following options. Also see @ref{Common options}.
16996 Print the number of installed processors on the system, which may
16997 be greater than the number online or available to the current process.
16998 The @env{OMP_NUM_THREADS} or @env{OMP_THREAD_LIMIT} environment variables
16999 are not honored in this case.
17001 @item --ignore=@var{number}
17003 If possible, exclude this @var{number} of processing units.
17010 @node uname invocation
17011 @section @command{uname}: Print system information
17014 @cindex print system information
17015 @cindex system information, printing
17017 @command{uname} prints information about the machine and operating system
17018 it is run on. If no options are given, @command{uname} acts as if the
17019 @option{-s} option were given. Synopsis:
17022 uname [@var{option}]@dots{}
17025 If multiple options or @option{-a} are given, the selected information is
17026 printed in this order:
17029 @var{kernel-name} @var{nodename} @var{kernel-release} @var{kernel-version}
17030 @var{machine} @var{processor} @var{hardware-platform} @var{operating-system}
17033 The information may contain internal spaces, so such output cannot be
17034 parsed reliably. In the following example, @var{kernel-version} is
17035 @samp{#1 SMP Fri Jul 17 17:18:38 UTC 2020}:
17039 @result{} Linux dumdum.example.org 5.9.16-200.fc33.x86_64@c
17040 #1 SMP Mon Dec 21 14:08:22 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux
17044 The program accepts the following options. Also see @ref{Common options}.
17052 Print all of the below information, except omit the processor type
17053 and the hardware platform name if they are unknown.
17056 @itemx --hardware-platform
17058 @opindex --hardware-platform
17059 @cindex implementation, hardware
17060 @cindex hardware platform
17061 @cindex platform, hardware
17062 Print the hardware platform name
17063 (sometimes called the hardware implementation).
17064 Print @samp{unknown} if this information is not available.
17065 Note this is non-portable (even across GNU/Linux distributions).
17071 @cindex machine type
17072 @cindex hardware class
17073 @cindex hardware type
17074 Print the machine hardware name (sometimes called the hardware class
17080 @opindex --nodename
17083 @cindex network node name
17084 Print the network node hostname.
17089 @opindex --processor
17090 @cindex host processor type
17091 Print the processor type (sometimes called the instruction set
17092 architecture or ISA).
17093 Print @samp{unknown} if this information is not available.
17094 Note this is non-portable (even across GNU/Linux distributions).
17097 @itemx --operating-system
17099 @opindex --operating-system
17100 @cindex operating system name
17101 Print the name of the operating system.
17104 @itemx --kernel-release
17106 @opindex --kernel-release
17107 @cindex kernel release
17108 @cindex release of kernel
17109 Print the kernel release.
17112 @itemx --kernel-name
17114 @opindex --kernel-name
17115 @cindex kernel name
17116 @cindex name of kernel
17117 Print the kernel name.
17118 POSIX 1003.1-2001 (@pxref{Standards conformance}) calls this
17119 ``the implementation of the operating system'', because the
17120 POSIX specification itself has no notion of ``kernel''.
17121 The kernel name might be the same as the operating system name printed
17122 by the @option{-o} or @option{--operating-system} option, but it might
17123 differ. Some operating systems (e.g., FreeBSD, HP-UX) have the same
17124 name as their underlying kernels; others (e.g., GNU/Linux, Solaris)
17128 @itemx --kernel-version
17130 @opindex --kernel-version
17131 @cindex kernel version
17132 @cindex version of kernel
17133 Print the kernel version.
17140 @node hostname invocation
17141 @section @command{hostname}: Print or set system name
17144 @cindex setting the hostname
17145 @cindex printing the hostname
17146 @cindex system name, printing
17147 @cindex appropriate privileges
17149 With no arguments, @command{hostname} prints the name of the current host
17150 system. With one argument, it sets the current host name to the
17151 specified string. You must have appropriate privileges to set the host
17155 hostname [@var{name}]
17158 The only options are @option{--help} and @option{--version}. @xref{Common
17161 @command{hostname} is not installed by default, and other packages
17162 also supply a @command{hostname} command, so portable scripts should
17163 not rely on its existence or on the exact behavior documented above.
17168 @node hostid invocation
17169 @section @command{hostid}: Print numeric host identifier
17172 @cindex printing the host identifier
17174 @command{hostid} prints the numeric identifier of the current host
17175 in hexadecimal. This command accepts no arguments.
17176 The only options are @option{--help} and @option{--version}.
17177 @xref{Common options}.
17179 For example, here's what it prints on one system I use:
17186 On that system, the 32-bit quantity happens to be closely
17187 related to the system's Internet address, but that isn't always
17190 @command{hostid} is installed only on systems that have the
17191 @code{gethostid} function, so portable scripts should not rely on its
17196 @node uptime invocation
17197 @section @command{uptime}: Print system uptime and load
17200 @cindex printing the system uptime and load
17202 @command{uptime} prints the current time, the system's uptime, the
17203 number of logged-in users and the current load average.
17205 If an argument is specified, it is used as the file to be read
17206 to discover how many users are logged in. If no argument is
17207 specified, a system default is used (@command{uptime --help} indicates
17208 the default setting).
17210 The only options are @option{--help} and @option{--version}.
17211 @xref{Common options}.
17213 For example, here's what it prints right now on one system I use:
17217 14:07 up 3:35, 3 users, load average: 1.39, 1.15, 1.04
17220 The precise method of calculation of load average varies somewhat
17221 between systems. Some systems calculate it as the average number of
17222 runnable processes over the last 1, 5 and 15 minutes, but some systems
17223 also include processes in the uninterruptible sleep state (that is,
17224 those processes which are waiting for device I/O). The Linux kernel
17225 includes uninterruptible processes.
17227 @command{uptime} is installed only on platforms with infrastructure
17228 for obtaining the boot time, and other packages also supply an
17229 @command{uptime} command, so portable scripts should not rely on its
17230 existence or on the exact behavior documented above.
17234 @node SELinux context
17235 @chapter SELinux context
17237 @cindex SELinux context
17238 @cindex SELinux, context
17239 @cindex commands for SELinux context
17241 This section describes commands for operations with SELinux
17245 * chcon invocation:: Change SELinux context of file
17246 * runcon invocation:: Run a command in specified SELinux context
17249 @node chcon invocation
17250 @section @command{chcon}: Change SELinux context of file
17253 @cindex changing security context
17254 @cindex change SELinux context
17256 @command{chcon} changes the SELinux security context of the selected files.
17260 chcon [@var{option}]@dots{} @var{context} @var{file}@dots{}
17261 chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}]@c
17262 [-t @var{type}] @var{file}@dots{}
17263 chcon [@var{option}]@dots{} --reference=@var{rfile} @var{file}@dots{}
17266 Change the SELinux security context of each @var{file} to @var{context}.
17267 With @option{--reference}, change the security context of each @var{file}
17268 to that of @var{rfile}.
17270 The program accepts the following options. Also see @ref{Common options}.
17274 @item --dereference
17275 @opindex --dereference
17276 Do not affect symbolic links but what they refer to; this is the default.
17279 @itemx --no-dereference
17281 @opindex --no-dereference
17282 @cindex no dereference
17283 Affect the symbolic links themselves instead of any referenced file.
17285 @item --reference=@var{rfile}
17286 @opindex --reference
17287 @cindex reference file
17288 Use @var{rfile}'s security context rather than specifying a @var{context} value.
17293 @opindex --recursive
17294 Operate on files and directories recursively.
17296 @item --preserve-root
17297 @opindex --preserve-root
17298 Refuse to operate recursively on the root directory, @file{/},
17299 when used together with the @option{--recursive} option.
17300 @xref{Treating / specially}.
17302 @item --no-preserve-root
17303 @opindex --no-preserve-root
17304 Do not treat the root directory, @file{/}, specially when operating
17305 recursively; this is the default.
17306 @xref{Treating / specially}.
17309 @xref{Traversing symlinks}.
17312 @xref{Traversing symlinks}.
17315 @xref{Traversing symlinks}.
17322 Output a diagnostic for every file processed.
17324 @item -u @var{user}
17325 @itemx --user=@var{user}
17328 Set user @var{user} in the target security context.
17330 @item -r @var{role}
17331 @itemx --role=@var{role}
17334 Set role @var{role} in the target security context.
17336 @item -t @var{type}
17337 @itemx --type=@var{type}
17340 Set type @var{type} in the target security context.
17342 @item -l @var{range}
17343 @itemx --range=@var{range}
17346 Set range @var{range} in the target security context.
17352 @node runcon invocation
17353 @section @command{runcon}: Run a command in specified SELinux context
17356 @cindex run with security context
17359 @command{runcon} runs file in specified SELinux security context.
17363 runcon @var{context} @var{command} [@var{args}]
17364 runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}]@c
17365 [-l @var{range}] @var{command} [@var{args}]
17368 Run @var{command} with completely-specified @var{context}, or with
17369 current or transitioned security context modified by one or more of @var{level},
17370 @var{role}, @var{type} and @var{user}.
17372 If none of @option{-c}, @option{-t}, @option{-u}, @option{-r}, or @option{-l}
17373 is specified, the first argument is used as the complete context.
17374 Any additional arguments after @var{command}
17375 are interpreted as arguments to the command.
17377 With neither @var{context} nor @var{command}, print the current
17380 @cindex restricted security context
17381 @cindex NO_NEW_PRIVS
17382 Note also the @command{setpriv} command which can be used to set the
17383 NO_NEW_PRIVS bit using @command{setpriv --no-new-privs runcon ...},
17384 thus disallowing usage of a security context with more privileges
17385 than the process would normally have.
17387 @command{runcon} accepts the following options. Also see @ref{Common options}.
17395 Compute process transition context before modifying.
17397 @item -u @var{user}
17398 @itemx --user=@var{user}
17401 Set user @var{user} in the target security context.
17403 @item -r @var{role}
17404 @itemx --role=@var{role}
17407 Set role @var{role} in the target security context.
17409 @item -t @var{type}
17410 @itemx --type=@var{type}
17413 Set type @var{type} in the target security context.
17415 @item -l @var{range}
17416 @itemx --range=@var{range}
17419 Set range @var{range} in the target security context.
17423 @cindex exit status of @command{runcon}
17427 125 if @command{runcon} itself fails
17428 126 if @var{command} is found but cannot be invoked
17429 127 if @var{command} cannot be found
17430 the exit status of @var{command} otherwise
17433 @node Modified command invocation
17434 @chapter Modified command invocation
17436 @cindex modified command invocation
17437 @cindex invocation of commands, modified
17438 @cindex commands for invoking other commands
17440 This section describes commands that run other commands in some context
17441 different than the current one: a modified environment, as a different
17445 * chroot invocation:: Modify the root directory.
17446 * env invocation:: Modify environment variables.
17447 * nice invocation:: Modify niceness.
17448 * nohup invocation:: Immunize to hangups.
17449 * stdbuf invocation:: Modify buffering of standard streams.
17450 * timeout invocation:: Run with time limit.
17454 @node chroot invocation
17455 @section @command{chroot}: Run a command with a different root directory
17458 @cindex running a program in a specified root directory
17459 @cindex root directory, running a program in a specified
17461 @command{chroot} runs a command with a specified root directory.
17462 On many systems, only the super-user can do this.@footnote{However,
17463 some systems (e.g., FreeBSD) can be configured to allow certain regular
17464 users to use the @code{chroot} system call, and hence to run this program.
17465 Also, on Cygwin, anyone can run the @command{chroot} command, because the
17466 underlying function is non-privileged due to lack of support in MS-Windows.
17467 Furthermore, the @command{chroot} command avoids the @code{chroot} system call
17468 when @var{newroot} is identical to the old @file{/} directory for consistency
17469 with systems where this is allowed for non-privileged users.}.
17473 chroot @var{option} @var{newroot} [@var{command} [@var{args}]@dots{}]
17474 chroot @var{option}
17477 Ordinarily, file names are looked up starting at the root of the
17478 directory structure, i.e., @file{/}. @command{chroot} changes the root to
17479 the directory @var{newroot} (which must exist), then changes the working
17480 directory to @file{/}, and finally runs @var{command} with optional @var{args}.
17481 If @var{command} is not specified, the default is the value of the @env{SHELL}
17482 environment variable or @command{/bin/sh} if not set, invoked with the
17483 @option{-i} option.
17484 @var{command} must not be a special built-in utility
17485 (@pxref{Special built-in utilities}).
17487 The program accepts the following options. Also see @ref{Common options}.
17488 Options must precede operands.
17492 @item --groups=@var{groups}
17494 Use this option to override the supplementary @var{groups} to be
17495 used by the new process.
17496 The items in the list (names or numeric IDs) must be separated by commas.
17497 Use @samp{--groups=''} to disable the supplementary group look-up
17498 implicit in the @option{--userspec} option.
17500 @item --userspec=@var{user}[:@var{group}]
17501 @opindex --userspec
17502 By default, @var{command} is run with the same credentials
17503 as the invoking process.
17504 Use this option to run it as a different @var{user} and/or with a
17505 different primary @var{group}.
17506 If a @var{user} is specified then the supplementary groups
17507 are set according to the system defined list for that user,
17508 unless overridden with the @option{--groups} option.
17511 @opindex --skip-chdir
17512 Use this option to not change the working directory to @file{/} after changing
17513 the root directory to @var{newroot}, i.e., inside the chroot.
17514 This option is only permitted when @var{newroot} is the old @file{/} directory,
17515 and therefore is mostly useful together with the @option{--groups} and
17516 @option{--userspec} options to retain the previous working directory.
17520 The user and group name look-up performed by the @option{--userspec}
17521 and @option{--groups} options, is done both outside and inside
17522 the chroot, with successful look-ups inside the chroot taking precedence.
17523 If the specified user or group items are intended to represent a numeric ID,
17524 then a name to ID resolving step is avoided by specifying a leading @samp{+}.
17525 @xref{Disambiguating names and IDs}.
17527 Here are a few tips to help avoid common problems in using chroot.
17528 To start with a simple example, make @var{command} refer to a statically
17529 linked binary. If you were to use a dynamically linked executable, then
17530 you'd have to arrange to have the shared libraries in the right place under
17531 your new root directory.
17533 For example, if you create a statically linked @command{ls} executable,
17534 and put it in @file{/tmp/empty}, you can run this command as root:
17537 $ chroot /tmp/empty /ls -Rl /
17540 Then you'll see output like this:
17545 -rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls
17548 If you want to use a dynamically linked executable, say @command{bash},
17549 then first run @samp{ldd bash} to see what shared objects it needs.
17550 Then, in addition to copying the actual binary, also copy the listed
17551 files to the required positions under your intended new root directory.
17552 Finally, if the executable requires any other files (e.g., data, state,
17553 device files), copy them into place, too.
17555 @command{chroot} is installed only on systems that have the
17556 @code{chroot} function, so portable scripts should not rely on its
17559 @cindex exit status of @command{chroot}
17563 125 if @command{chroot} itself fails
17564 126 if @var{command} is found but cannot be invoked
17565 127 if @var{command} cannot be found
17566 the exit status of @var{command} otherwise
17570 @node env invocation
17571 @section @command{env}: Run a command in a modified environment
17574 @cindex environment, running a program in a modified
17575 @cindex modified environment, running a program in a
17576 @cindex running a program in a modified environment
17578 @command{env} runs a command with a modified environment. Synopses:
17581 env [@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
17582 [@var{command} [@var{args}]@dots{}]
17583 env -[v]S'[@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
17584 [@var{command} [@var{args}]@dots{}]'
17588 @command{env} is commonly used on first line of scripts (shebang line):
17590 #!/usr/bin/env @var{command}
17591 #!/usr/bin/env -[v]S[@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
17592 @var{command} [@var{args}]@dots{}
17595 Operands of the form @samp{@var{variable}=@var{value}} set
17596 the environment variable @var{variable} to value @var{value}.
17597 @var{value} may be empty (@samp{@var{variable}=}). Setting a variable
17598 to an empty value is different from unsetting it.
17599 These operands are evaluated left-to-right, so if two operands
17600 mention the same variable the earlier is ignored.
17602 Environment variable names can be empty, and can contain any
17603 characters other than @samp{=} and ASCII NUL.
17604 However, it is wise to limit yourself to names that
17605 consist solely of underscores, digits, and ASCII letters,
17606 and that begin with a non-digit, as applications like the shell do not
17607 work well with other names.
17610 The first operand that does not contain the character @samp{=}
17611 specifies the program to invoke; it is
17612 searched for according to the @env{PATH} environment variable. Any
17613 remaining arguments are passed as arguments to that program.
17614 The program should not be a special built-in utility
17615 (@pxref{Special built-in utilities}).
17617 Modifications to @env{PATH} take effect prior to searching for
17618 @var{command}. Use caution when reducing @env{PATH}; behavior is
17619 not portable when @env{PATH} is undefined or omits key directories
17620 such as @file{/bin}.
17622 In the rare case that a utility contains a @samp{=} in the name, the
17623 only way to disambiguate it from a variable assignment is to use an
17624 intermediate command for @var{command}, and pass the problematic
17625 program name via @var{args}. For example, if @file{./prog=} is an
17626 executable in the current @env{PATH}:
17629 env prog= true # runs 'true', with prog= in environment
17630 env ./prog= true # runs 'true', with ./prog= in environment
17631 env -- prog= true # runs 'true', with prog= in environment
17632 env sh -c '\prog= true' # runs 'prog=' with argument 'true'
17633 env sh -c 'exec "$@@"' sh prog= true # also runs 'prog='
17636 @cindex environment, printing
17638 If no command name is specified following the environment
17639 specifications, the resulting environment is printed. This is like
17640 specifying the @command{printenv} program.
17642 For some examples, suppose the environment passed to @command{env}
17643 contains @samp{LOGNAME=rms}, @samp{EDITOR=emacs}, and
17644 @samp{PATH=.:/gnubin:/hacks}:
17649 Output the current environment.
17651 $ env | LC_ALL=C sort
17654 PATH=.:/gnubin:/hacks
17658 Run @command{foo} with a reduced environment, preserving only the
17659 original @env{PATH} to avoid problems in locating @command{foo}.
17661 env - PATH="$PATH" foo
17665 Run @command{foo} with the environment containing @samp{LOGNAME=rms},
17666 @samp{EDITOR=emacs}, and @samp{PATH=.:/gnubin:/hacks}, and guarantees
17667 that @command{foo} was found in the file system rather than as a shell
17674 Run @command{nemacs} with the environment containing @samp{LOGNAME=foo},
17675 @samp{EDITOR=emacs}, @samp{PATH=.:/gnubin:/hacks}, and
17676 @samp{DISPLAY=gnu:0}.
17678 env DISPLAY=gnu:0 LOGNAME=foo nemacs
17682 Attempt to run the program @command{/energy/--} (as that is the only
17683 possible path search result); if the command exists, the environment
17684 will contain @samp{LOGNAME=rms} and @samp{PATH=/energy}, and the
17685 arguments will be @samp{e=mc2}, @samp{bar}, and @samp{baz}.
17687 env -u EDITOR PATH=/energy -- e=mc2 bar baz
17693 @subsection General options
17695 The program accepts the following options. Also see @ref{Common options}.
17696 Options must precede operands.
17702 @item -u @var{name}
17703 @itemx --unset=@var{name}
17706 Remove variable @var{name} from the environment, if it was in the
17711 @itemx --ignore-environment
17714 @opindex --ignore-environment
17715 Start with an empty environment, ignoring the inherited environment.
17718 @itemx --chdir=@var{dir}
17721 Change the working directory to @var{dir} before invoking @var{command}.
17722 This differs from the shell built-in @command{cd} in that it starts
17723 @var{command} as a subprocess rather than altering the shell's own working
17724 directory; this allows it to be chained with other commands that run commands
17725 in a different context. For example:
17728 # Run 'true' with /chroot as its root directory and /srv as its working
17730 chroot /chroot env --chdir=/srv true
17731 # Run 'true' with /build as its working directory, FOO=bar in its
17732 # environment, and a time limit of five seconds.
17733 env --chdir=/build FOO=bar timeout 5 true
17736 @item --default-signal[=@var{sig}]
17737 Unblock and reset signal @var{sig} to its default signal handler.
17738 Without @var{sig} all known signals are unblocked and reset to their defaults.
17739 Multiple signals can be comma-separated. An empty @var{sig} argument is a no-op.
17740 The following command runs @command{seq} with SIGINT and SIGPIPE set to their
17741 default (which is to terminate the program):
17744 env --default-signal=PIPE,INT seq 1000 | head -n1
17747 In the following example, we see how this is not
17748 possible to do with traditional shells.
17749 Here the first trap command sets SIGPIPE to ignore.
17750 The second trap command ostensibly sets it back to its default,
17751 but POSIX mandates that the shell must not change inherited
17752 state of the signal -- so it is a no-op.
17755 trap '' PIPE && sh -c 'trap - PIPE ; seq inf | head -n1'
17758 Using @option{--default-signal=PIPE} we can
17759 ensure the signal handling is set to its default behavior:
17762 trap '' PIPE && sh -c 'env --default-signal=PIPE seq inf | head -n1'
17766 @item --ignore-signal[=@var{sig}]
17767 Ignore signal @var{sig} when running a program. Without @var{sig} all
17768 known signals are set to ignore. Multiple signals can be comma-separated.
17769 An empty @var{sig} argument is a no-op. The following command runs @command{seq}
17770 with SIGINT set to be ignored -- pressing @kbd{Ctrl-C} will not terminate it:
17773 env --ignore-signal=INT seq inf > /dev/null
17776 @samp{SIGCHLD} is special, in that @option{--ignore-signal=CHLD} might have
17777 no effect (POSIX says it's unspecified).
17779 Most operating systems do not allow ignoring @samp{SIGKILL}, @samp{SIGSTOP}
17780 (and possibly other signals). Attempting to ignore these signals will fail.
17782 Multiple (and contradictory) @option{--default-signal=SIG} and
17783 @option{--ignore-signal=SIG} options are processed left-to-right,
17784 with the latter taking precedence. In the following example, @samp{SIGPIPE} is
17785 set to default while @samp{SIGINT} is ignored:
17788 env --default-signal=INT,PIPE --ignore-signal=INT
17791 @item --block-signal[=@var{sig}]
17792 Block signal(s) @var{sig} from being delivered. Without @var{sig} all
17793 known signals are set to blocked. Multiple signals can be comma-separated.
17794 An empty @var{sig} argument is a no-op.
17796 @item --list-signal-handling
17797 List blocked or ignored signals to standard error, before executing a command.
17803 Show verbose information for each processing step.
17806 $ env -v -uTERM A=B uname -s
17815 When combined with @option{-S} it is recommended to list @option{-v}
17816 first, e.g. @command{env -vS'string'}.
17818 @item -S @var{string}
17819 @itemx --split-string=@var{string}
17821 @opindex --split-string
17822 @cindex shebang arguments
17823 @cindex scripts arguments
17824 @cindex env in scripts
17825 process and split @var{string} into separate arguments used to pass
17826 multiple arguments on shebang lines. @command{env} supports FreeBSD's
17827 syntax of several escape sequences and environment variable
17828 expansions. See below for details and examples.
17832 @cindex exit status of @command{env}
17836 0 if no @var{command} is specified and the environment is output
17837 125 if @command{env} itself fails
17838 126 if @var{command} is found but cannot be invoked
17839 127 if @var{command} cannot be found
17840 the exit status of @var{command} otherwise
17843 @subsection @option{-S}/@option{--split-string} usage in scripts
17845 The @option{-S}/@option{--split-string} option enables use of multiple
17846 arguments on the first line of scripts (the shebang line, @samp{#!}).
17848 When a script's interpreter is in a known location, scripts typically
17849 contain the absolute file name in their first line:
17851 @multitable {Python Script:} {#!/usr/bin/python3}
17852 @item Shell script:
17866 @item Python script:
17875 When a script's interpreter is in a non-standard location
17876 in the @env{PATH} environment variable, it is recommended
17877 to use @command{env} on the first line of the script to
17878 find the executable and run it:
17880 @multitable {Python Script:} {#!/usr/bin/env python3}
17881 @item Shell script:
17884 #!/usr/bin/env bash
17891 #!/usr/bin/env perl
17895 @item Python script:
17898 #!/usr/bin/env python3
17904 Most operating systems (e.g. GNU/Linux, BSDs) treat all text after the
17905 first space as a single argument. When using @command{env} in a script
17906 it is thus not possible to specify multiple arguments.
17908 In the following example:
17910 #!/usr/bin/env perl -T -w
17914 The operating system treats @samp{perl -T -w} as one argument (the
17915 program's name), and executing the script fails with:
17918 /usr/bin/env: 'perl -T -w': No such file or directory
17921 The @option{-S} option instructs @command{env} to split the single string
17922 into multiple arguments. The following example works as expected:
17926 #!/usr/bin/env -S perl -T -w
17929 $ chmod a+x hello.pl
17934 And is equivalent to running @command{perl -T -w hello.pl} on the command line
17937 @unnumberedsubsubsec Testing and troubleshooting
17939 @cindex single quotes, and @command{env -S}
17940 @cindex @command{env -S}, and single quotes
17941 @cindex @option{-S}, env and single quotes
17942 To test @command{env -S} on the command line, use single quotes for the
17943 @option{-S} string to emulate a single paramter. Single quotes are not
17944 needed when using @command{env -S} in a shebang line on the first line of a
17945 script (the operating system already treats it as one argument).
17947 The following command is equivalent to the @file{hello.pl} script above:
17950 $ env -S'perl -T -w' hello.pl
17953 @cindex @command{env -S}, debugging
17954 @cindex debugging, @command{env -S}
17956 To troubleshoot @option{-S} usage add the @option{-v} as the first
17957 argument (before @option{-S}).
17959 Using @option{-vS} on a shebang line in a script:
17962 $ cat hello-debug.pl
17963 #!/usr/bin/env -vS perl -T -w
17966 $ chmod a+x hello-debug.pl
17968 split -S: 'perl -T -w'
17976 arg[3]= './hello-debug.pl'
17980 Using @option{-vS} on the command line prompt (adding single quotes):
17983 $ env -vS'perl -T -w' hello-debug.pl
17984 split -S: 'perl -T -w'
17992 arg[3]= 'hello-debug.pl'
17996 @subsection @option{-S}/@option{--split-string} syntax
17998 @unnumberedsubsubsec Splitting arguments by whitespace
18000 Running @command{env -Sstring} splits the @var{string} into
18001 arguments based on unquoted spaces or tab characters.
18002 (Newlines, carriage returns, vertical tabs and form feeds are treated
18003 like spaces and tabs.)
18005 In the following contrived example the @command{awk} variable
18006 @samp{OFS} will be @code{<space>xyz<space>} as these spaces are inside
18007 double quotes. The other space characters are used as argument separators:
18011 #!/usr/bin/env -S awk -v OFS=" xyz " -f
18012 BEGIN @{print 1,2,3@}
18014 $ chmod a+x one.awk
18019 When using @option{-S} on the command line prompt, remember to add
18020 single quotes around the entire string:
18023 $ env -S'awk -v OFS=" xyz " -f' one.awk
18027 @unnumberedsubsubsec Escape sequences
18029 @command{env} supports several escape sequences. These sequences
18030 are processed when unquoted or inside double quotes (unless otherwise noted).
18031 Single quotes disable escape sequences except @samp{\'} and @samp{\\}.
18033 @multitable @columnfractions .10 .90
18036 @tab Ignore the remaining characters in the string.
18037 Cannot be used inside double quotes.
18040 @tab form-feed character (ASCII 0x0C)
18043 @tab new-line character (ASCII 0x0A)
18046 @tab carriage-return character (ASCII 0x0D)
18049 @tab tab character (ASCII 0x09)
18052 @tab vertical tab character (ASCII 0x0B)
18055 @tab A hash @samp{#} character. Used when a @samp{#} character
18056 is needed as the first character of an argument (see 'comments' section
18060 @tab A dollar-sign character @samp{$}. Unescaped @samp{$} characters
18061 are used to expand environment variables (see 'variables' section below).
18064 @tab Inside double-quotes, replaced with a single space character.
18065 Outside quotes, treated as an argument separator. @samp{\_} can be used
18066 to avoid space characters in a shebang line (see examples below).
18069 @tab A double-quote character.
18072 @tab A single-quote character.
18073 This escape sequence works inside single-quoted strings.
18076 @tab A backslash character.
18077 This escape sequence works inside single-quoted strings.
18081 The following @command{awk} script will use tab character as input and output
18082 field separator (instead of spaces and tabs):
18086 #!/usr/bin/env -S awk -v FS="\t" -v OFS="\t" -f
18090 @unnumberedsubsubsec Comments
18092 The escape sequence @samp{\c} (used outside single/double quotes)
18093 causes @command{env} to ignore the rest of the string.
18095 The @samp{#} character causes @command{env} to ignore the rest of
18096 the string when it appears as the first character of an argument.
18097 Use @samp{\#} to reverse this behavior.
18100 $ env -S'printf %s\n A B C'
18105 $ env -S'printf %s\n A# B C'
18110 $ env -S'printf %s\n A #B C'
18113 $ env -S'printf %s\n A \#B C'
18118 $ env -S'printf %s\n A\cB C'
18122 NOTE: The above examples use single quotes as they are executed
18123 on the command-line.
18127 @unnumberedsubsubsec Environment variable expansion
18129 The pattern @samp{$@{VARNAME@}} is used to substitute a value from
18130 the environment variable. The pattern must include the curly braces
18131 (@samp{@{},@samp{@}}). Without them @command{env} will reject the string.
18132 Special shell variables (such as @samp{$@@}, @samp{$*}, @samp{$$}) are
18135 If the environment variable is empty or not set, the pattern will be replaced
18136 by an empty string. The value of @samp{$@{VARNAME@}} will be that of
18137 the executed @command{env}, before any modifications using
18138 @option{-i}/@option{--ignore-environment}/@option{-u}/@option{--unset} or
18139 setting new values using @samp{VAR=VALUE}.
18141 The following python script prepends @file{/opt/custom/modules} to the python
18142 module search path environment variable (@samp{PYTHONPATH}):
18146 #!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$@{PYTHONPATH@} python
18151 The expansion of @samp{$@{PYTHONPATH@}} is performed by @command{env},
18152 not by a shell. If the curly braces are omitted, @command{env} will fail:
18156 #!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$PYTHONPATH python
18160 $ chmod a+x custom.py
18162 /usr/bin/env: only $@{VARNAME@} expansion is supported, error at: $PYTHONPATH @c
18166 Environment variable expansion happens before clearing the environment
18167 (with @option{-i}) or unsetting specific variables (with @option{-u}):
18170 $ env -S'-i OLDUSER=$@{USER@} env'
18174 Use @option{-v} to diagnose the operations step-by-step:
18177 $ env -vS'-i OLDUSER=$@{USER@} env'
18178 expanding $@{USER@} into 'gordon'
18179 split -S: '-i OLDUSER=$@{USER@} env'
18184 setenv: OLDUSER=gordon
18192 @node nice invocation
18193 @section @command{nice}: Run a command with modified niceness
18197 @cindex scheduling, affecting
18198 @cindex appropriate privileges
18200 @command{nice} prints a process's @dfn{niceness}, or runs
18201 a command with modified niceness. @dfn{niceness} affects how
18202 favorably the process is scheduled in the system.
18206 nice [@var{option}]@dots{} [@var{command} [@var{arg}]@dots{}]
18209 If no arguments are given, @command{nice} prints the current niceness.
18210 Otherwise, @command{nice} runs the given @var{command} with its
18211 niceness adjusted. By default, its niceness is incremented by 10.
18213 Niceness values range at least from @minus{}20 (process has high priority
18214 and gets more resources, thus slowing down other processes) through 19
18215 (process has lower priority and runs slowly itself, but has less impact
18216 on the speed of other running processes). Some systems
18217 may have a wider range of niceness values; conversely, other systems may
18218 enforce more restrictive limits. An attempt to set the niceness
18219 outside the supported range is treated as an attempt to use the
18220 minimum or maximum supported value.
18222 A niceness should not be confused with a scheduling priority, which
18223 lets applications determine the order in which threads are scheduled
18224 to run. Unlike a priority, a niceness is merely advice to the
18225 scheduler, which the scheduler is free to ignore. Also, as a point of
18226 terminology, POSIX defines the behavior of @command{nice} in
18227 terms of a @dfn{nice value}, which is the non-negative difference
18228 between a niceness and the minimum niceness. Though @command{nice}
18229 conforms to POSIX, its documentation and diagnostics use the
18230 term ``niceness'' for compatibility with historical practice.
18232 @var{command} must not be a special built-in utility (@pxref{Special
18233 built-in utilities}).
18235 @mayConflictWithShellBuiltIn{nice}
18237 Note to change the @dfn{niceness} of an existing process,
18238 one needs to use the @command{renice} command.
18240 The program accepts the following option. Also see @ref{Common options}.
18241 Options must precede operands.
18244 @item -n @var{adjustment}
18245 @itemx --adjustment=@var{adjustment}
18247 @opindex --adjustment
18248 Add @var{adjustment} instead of 10 to the command's niceness. If
18249 @var{adjustment} is negative and you lack appropriate privileges,
18250 @command{nice} issues a warning but otherwise acts as if you specified
18253 For compatibility @command{nice} also supports an obsolete
18254 option syntax @option{-@var{adjustment}}. New scripts should use
18255 @option{-n @var{adjustment}} instead.
18259 @command{nice} is installed only on systems that have the POSIX
18260 @code{setpriority} function, so portable scripts should not rely on
18261 its existence on non-POSIX platforms.
18263 @cindex exit status of @command{nice}
18267 0 if no @var{command} is specified and the niceness is output
18268 125 if @command{nice} itself fails
18269 126 if @var{command} is found but cannot be invoked
18270 127 if @var{command} cannot be found
18271 the exit status of @var{command} otherwise
18274 It is sometimes useful to run a non-interactive program with reduced niceness.
18277 $ nice factor 4611686018427387903
18280 Since @command{nice} prints the current niceness,
18281 you can invoke it through itself to demonstrate how it works.
18283 The default behavior is to increase the niceness by @samp{10}:
18294 The @var{adjustment} is relative to the current niceness. In the
18295 next example, the first @command{nice} invocation runs the second one
18296 with niceness 10, and it in turn runs the final one with a niceness
18300 $ nice nice -n 3 nice
18304 Specifying a niceness larger than the supported range
18305 is the same as specifying the maximum supported value:
18308 $ nice -n 10000000000 nice
18312 Only a privileged user may run a process with lower niceness:
18316 nice: cannot set niceness: Permission denied
18318 $ sudo nice -n -1 nice
18323 @node nohup invocation
18324 @section @command{nohup}: Run a command immune to hangups
18327 @cindex hangups, immunity to
18328 @cindex immunity to hangups
18329 @cindex logging out and continuing to run
18332 @command{nohup} runs the given @var{command} with hangup signals ignored,
18333 so that the command can continue running in the background after you log
18337 nohup @var{command} [@var{arg}]@dots{}
18340 If standard input is a terminal, redirect it so that terminal sessions
18341 do not mistakenly consider the terminal to be used by the command.
18342 Make the substitute file descriptor unreadable, so that commands that
18343 mistakenly attempt to read from standard input can report an error.
18344 This redirection is a GNU extension; programs intended to be portable
18345 to non-GNU hosts can use @samp{nohup @var{command} [@var{arg}]@dots{}
18346 0>/dev/null} instead.
18349 If standard output is a terminal, the command's standard output is appended
18350 to the file @file{nohup.out}; if that cannot be written to, it is appended
18351 to the file @file{$HOME/nohup.out}; and if that cannot be written to, the
18352 command is not run.
18353 Any @file{nohup.out} or @file{$HOME/nohup.out} file created by
18354 @command{nohup} is made readable and writable only to the user,
18355 regardless of the current umask settings.
18357 If standard error is a terminal, it is normally redirected to the same file
18358 descriptor as the (possibly-redirected) standard output.
18359 However, if standard output is closed, standard error terminal output
18360 is instead appended to the file @file{nohup.out} or
18361 @file{$HOME/nohup.out} as above.
18363 To capture the command's output to a file other than @file{nohup.out}
18364 you can redirect it. For example, to capture the output of
18368 nohup make > make.log
18371 @command{nohup} does not automatically put the command it runs in the
18372 background; you must do that explicitly, by ending the command line
18373 with an @samp{&}. Also, @command{nohup} does not alter the
18374 niceness of @var{command}; use @command{nice} for that,
18375 e.g., @samp{nohup nice @var{command}}.
18377 @var{command} must not be a special built-in utility (@pxref{Special
18378 built-in utilities}).
18380 The only options are @option{--help} and @option{--version}. @xref{Common
18381 options}. Options must precede operands.
18383 @cindex exit status of @command{nohup}
18387 125 if @command{nohup} itself fails, and @env{POSIXLY_CORRECT} is not set
18388 126 if @var{command} is found but cannot be invoked
18389 127 if @var{command} cannot be found
18390 the exit status of @var{command} otherwise
18393 If @env{POSIXLY_CORRECT} is set, internal failures give status 127
18397 @node stdbuf invocation
18398 @section @command{stdbuf}: Run a command with modified I/O stream buffering
18401 @cindex standard streams, buffering
18402 @cindex line buffered
18404 @command{stdbuf} allows one to modify the buffering operations of the
18405 three standard I/O streams associated with a program. Synopsis:
18408 stdbuf @var{option}@dots{} @var{command}
18411 @var{command} must start with the name of a program that
18414 uses the ISO C @code{FILE} streams for input/output (note the
18415 programs @command{dd} and @command{cat} don't do that),
18418 does not adjust the buffering of its standard streams (note the
18419 program @command{tee} is not in this category).
18422 Any additional @var{arg}s are passed as additional arguments to the
18425 The program accepts the following options. Also see @ref{Common options}.
18429 @item -i @var{mode}
18430 @itemx --input=@var{mode}
18433 Adjust the standard input stream buffering.
18435 @item -o @var{mode}
18436 @itemx --output=@var{mode}
18439 Adjust the standard output stream buffering.
18441 @item -e @var{mode}
18442 @itemx --error=@var{mode}
18445 Adjust the standard error stream buffering.
18449 The @var{mode} can be specified as follows:
18454 Set the stream to line buffered mode.
18455 In this mode data is coalesced until a newline is output or
18456 input is read from any stream attached to a terminal device.
18457 This option is invalid with standard input.
18460 Disable buffering of the selected stream.
18461 In this mode, data is output immediately and only the
18462 amount of data requested is read from input.
18463 Note the difference in function for input and output.
18464 Disabling buffering for input will not influence the responsiveness
18465 or blocking behavior of the stream input functions.
18466 For example @code{fread} will still block until @code{EOF} or error,
18467 even if the underlying @code{read} returns less data than requested.
18470 Specify the size of the buffer to use in fully buffered mode.
18471 @multiplierSuffixesNoBlocks{size}
18475 @command{stdbuf} is installed only on platforms that use the
18476 Executable and Linkable Format (ELF) and support the
18477 @code{constructor} attribute, so portable scripts should not rely on
18480 @cindex exit status of @command{stdbuf}
18484 125 if @command{stdbuf} itself fails
18485 126 if @var{command} is found but cannot be invoked
18486 127 if @var{command} cannot be found
18487 the exit status of @var{command} otherwise
18491 @node timeout invocation
18492 @section @command{timeout}: Run a command with a time limit
18496 @cindex run commands with bounded time
18498 @command{timeout} runs the given @var{command} and kills it if it is
18499 still running after the specified time interval. Synopsis:
18502 timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{}
18505 @var{command} must not be a special built-in utility (@pxref{Special
18506 built-in utilities}).
18508 The program accepts the following options. Also see @ref{Common options}.
18509 Options must precede operands.
18512 @item --preserve-status
18513 @opindex --preserve-status
18514 Return the exit status of the managed @var{command} on timeout, rather than
18515 a specific exit status indicating a timeout. This is useful if the
18516 managed @var{command} supports running for an indeterminate amount of time.
18519 @opindex --foreground
18520 Don't create a separate background program group, so that
18521 the managed @var{command} can use the foreground TTY normally.
18522 This is needed to support two situations when timing out commands,
18523 when not invoking @command{timeout} from an interactive shell.
18526 @var{command} is interactive and needs to read from the terminal for example
18528 the user wants to support sending signals directly to @var{command}
18529 from the terminal (like Ctrl-C for example)
18532 Note in this mode of operation, any children of @var{command}
18533 will not be timed out. Also SIGCONT will not be sent to @var{command},
18534 as it's generally not needed with foreground processes, and can
18535 cause intermittent signal delivery issues with programs that are monitors
18536 themselves (like GDB for example).
18538 @item -k @var{duration}
18539 @itemx --kill-after=@var{duration}
18541 @opindex --kill-after
18542 Ensure the monitored @var{command} is killed by also sending a @samp{KILL}
18545 The specified @var{duration} starts from the point in time when
18546 @command{timeout} sends the initial signal to @var{command}, i.e.,
18547 not from the beginning when the @var{command} is started.
18549 This option has no effect if either the main @var{duration}
18550 of the @command{timeout} command, or the @var{duration} specified
18551 to this option, is 0.
18553 This option may be useful if the selected signal did not kill the @var{command},
18554 either because the signal was blocked or ignored, or if the @var{command} takes
18555 too long (e.g. for cleanup work) to terminate itself within a certain amount
18558 @item -s @var{signal}
18559 @itemx --signal=@var{signal}
18562 Send this @var{signal} to @var{command} on timeout, rather than the
18563 default @samp{TERM} signal. @var{signal} may be a name like @samp{HUP}
18564 or a number. @xref{Signal specifications}.
18570 Diagnose to standard error, any signal sent upon timeout.
18574 @var{duration} is a floating point number in either the current or the
18575 C locale (@pxref{Floating point}) followed by an optional unit:
18577 @samp{s} for seconds (the default)
18578 @samp{m} for minutes
18582 A duration of 0 disables the associated timeout.
18583 Note that the actual timeout duration is dependent on system conditions,
18584 which should be especially considered when specifying sub-second timeouts.
18586 @cindex exit status of @command{timeout}
18590 124 if @var{command} times out, and @option{--preserve-status} is not specified
18591 125 if @command{timeout} itself fails
18592 126 if @var{command} is found but cannot be invoked
18593 127 if @var{command} cannot be found
18594 137 if @var{command} or @command{timeout} is sent the KILL(9) signal (128+9)
18595 the exit status of @var{command} otherwise
18598 In the case of the @samp{KILL(9)} signal, @command{timeout} returns with
18599 exit status 137, regardless of whether that signal is sent to @var{command}
18600 or to @command{timeout} itself, i.e., these cases cannot be distinguished.
18601 In the latter case, the @var{command} process may still be alive after
18602 @command{timeout} has forcefully been terminated.
18607 # Send the default TERM signal after 20s to a short-living 'sleep 1'.
18608 # As that terminates long before the given duration, 'timeout' returns
18609 # with the same exit status as the command, 0 in this case.
18612 # Send the INT signal after 5s to the 'sleep' command. Returns after
18613 # 5 seconds with exit status 124 to indicate the sending of the signal.
18614 timeout -s INT 5 sleep 20
18616 # Likewise, but the command ignoring the INT signal due to being started
18617 # via 'env --ignore-signal'. Thus, 'sleep' terminates regularly after
18618 # the full 20 seconds, still 'timeout' returns with exit status 124.
18619 timeout -s INT 5s env --ignore-signal=INT sleep 20
18621 # Likewise, but sending the KILL signal 3 seconds after the initial
18622 # INT signal. Hence, 'sleep' is forcefully terminated after about
18623 # 8 seconds (5+3), and 'timeout' returns with an exit status of 137.
18624 timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20
18627 @node Process control
18628 @chapter Process control
18630 @cindex processes, commands for controlling
18631 @cindex commands for controlling processes
18634 * kill invocation:: Sending a signal to processes.
18638 @node kill invocation
18639 @section @command{kill}: Send a signal to processes
18642 @cindex send a signal to processes
18644 The @command{kill} command sends a signal to processes, causing them
18645 to terminate or otherwise act upon receiving the signal in some way.
18646 Alternatively, it lists information about signals. Synopses:
18649 kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{}
18650 kill [-l | --list | -t | --table] [@var{signal}]@dots{}
18653 @mayConflictWithShellBuiltIn{kill}
18655 The first form of the @command{kill} command sends a signal to all
18656 @var{pid} arguments. The default signal to send if none is specified
18657 is @samp{TERM}@. The special signal number @samp{0} does not denote a
18658 valid signal, but can be used to test whether the @var{pid} arguments
18659 specify processes to which a signal could be sent.
18661 If @var{pid} is positive, the signal is sent to the process with the
18662 process ID @var{pid}. If @var{pid} is zero, the signal is sent to all
18663 processes in the process group of the current process. If @var{pid}
18664 is @minus{}1, the signal is sent to all processes for which the user has
18665 permission to send a signal. If @var{pid} is less than @minus{}1, the signal
18666 is sent to all processes in the process group that equals the absolute
18667 value of @var{pid}.
18669 If @var{pid} is not positive, a system-dependent set of system
18670 processes is excluded from the list of processes to which the signal
18673 If a negative @var{pid} argument is desired as the first one, it
18674 should be preceded by @option{--}. However, as a common extension to
18675 POSIX, @option{--} is not required with @samp{kill
18676 -@var{signal} -@var{pid}}. The following commands are equivalent:
18685 The first form of the @command{kill} command succeeds if every @var{pid}
18686 argument specifies at least one process that the signal was sent to.
18688 The second form of the @command{kill} command lists signal information.
18689 Either the @option{-l} or @option{--list} option, or the @option{-t}
18690 or @option{--table} option must be specified. Without any
18691 @var{signal} argument, all supported signals are listed. The output
18692 of @option{-l} or @option{--list} is a list of the signal names, one
18693 per line; if @var{signal} is already a name, the signal number is
18694 printed instead. The output of @option{-t} or @option{--table} is a
18695 table of signal numbers, names, and descriptions. This form of the
18696 @command{kill} command succeeds if all @var{signal} arguments are valid
18697 and if there is no output error.
18699 The @command{kill} command also supports the @option{--help} and
18700 @option{--version} options. @xref{Common options}.
18702 A @var{signal} may be a signal name like @samp{HUP}, or a signal
18703 number like @samp{1}, or an exit status of a process terminated by the
18704 signal. A signal name can be given in canonical form or prefixed by
18705 @samp{SIG}@. The case of the letters is ignored, except for the
18706 @option{-@var{signal}} option which must use upper case to avoid
18707 ambiguity with lower case option letters.
18708 @xref{Signal specifications}, for a list of supported
18709 signal names and numbers.
18714 @cindex delaying commands
18715 @cindex commands for delaying
18717 @c Perhaps @command{wait} or other commands should be described here also?
18720 * sleep invocation:: Delay for a specified time.
18724 @node sleep invocation
18725 @section @command{sleep}: Delay for a specified time
18728 @cindex delay for a specified time
18730 @command{sleep} pauses for an amount of time specified by the sum of
18731 the values of the command line arguments.
18735 sleep @var{number}[smhd]@dots{}
18739 Each argument is a non-negative number followed by an optional unit; the default
18740 is seconds. The units are:
18753 Although portable POSIX scripts must give @command{sleep} a single
18754 non-negative integer argument without a suffix, GNU @command{sleep}
18755 also accepts two or more arguments, unit suffixes, and floating-point
18756 numbers in either the current or the C locale. @xref{Floating point}.
18758 For instance, the following could be used to @command{sleep} for
18759 1 second, 234 milli-, 567 micro- and 890 nanoseconds:
18762 sleep 1234e-3 567.89e-6
18765 Also one could sleep indefinitely like:
18771 The only options are @option{--help} and @option{--version}. @xref{Common
18774 @c sleep is a shell built-in at least with Solaris 11's /bin/sh
18775 @mayConflictWithShellBuiltIn{sleep}
18780 @node Numeric operations
18781 @chapter Numeric operations
18783 @cindex numeric operations
18784 These programs do numerically-related operations.
18787 * factor invocation:: Show factors of numbers.
18788 * numfmt invocation:: Reformat numbers.
18789 * seq invocation:: Print sequences of numbers.
18793 @node factor invocation
18794 @section @command{factor}: Print prime factors
18797 @cindex prime factors
18799 @command{factor} prints prime factors. Synopsis:
18802 factor [@var{option}]@dots{} [@var{number}]@dots{}
18805 If no @var{number} is specified on the command line, @command{factor} reads
18806 numbers from standard input, delimited by newlines, tabs, or spaces.
18808 The program accepts the following options. Also see @ref{Common options}.
18814 @opindex --exponents
18815 print factors in the form @math{p^e}, rather than repeating
18816 the prime @samp{p}, @samp{e} times. If the exponent @samp{e} is 1,
18817 then it is omitted.
18820 $ factor --exponents 3000
18825 If the number to be factored is small (less than @math{2^{127}} on
18826 typical machines), @command{factor} uses a faster algorithm.
18827 For example, on a circa-2017 Intel Xeon Silver 4116, factoring the
18828 product of the eighth and ninth Mersenne primes (approximately
18829 @math{2^{92}}) takes about 4 ms of CPU time:
18832 $ M8=$(echo 2^31-1 | bc)
18833 $ M9=$(echo 2^61-1 | bc)
18834 $ n=$(echo "$M8 * $M9" | bc)
18835 $ bash -c "time factor $n"
18836 4951760154835678088235319297: 2147483647 2305843009213693951
18843 For larger numbers, @command{factor} uses a slower algorithm. On the
18844 same platform, factoring the eighth Fermat number @math{2^{256} + 1}
18845 takes about 14 seconds, and the slower algorithm would have taken
18846 about 750 ms to factor @math{2^{127} - 3} instead of the 50 ms needed by
18847 the faster algorithm.
18849 Factoring large numbers is, in general, hard. The Pollard-Brent rho
18850 algorithm used by @command{factor} is particularly effective for
18851 numbers with relatively small factors. If you wish to factor large
18852 numbers which do not have small factors (for example, numbers which
18853 are the product of two large primes), other methods are far better.
18858 @node numfmt invocation
18859 @section @command{numfmt}: Reformat numbers
18863 @command{numfmt} reads numbers in various representations and reformats them
18864 as requested. The most common usage is converting numbers to/from @emph{human}
18865 representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}).
18868 numfmt [@var{option}]@dots{} [@var{number}]
18871 @command{numfmt} converts each @var{number} on the command-line according to the
18872 specified options (see below). If no @var{number}s are given, it reads numbers
18873 from standard input. @command{numfmt} can optionally extract numbers from
18874 specific columns, maintaining proper line padding and alignment.
18878 See @option{--invalid} for additional information regarding exit status.
18880 @subsection General options
18882 The program accepts the following options. Also see @ref{Common options}.
18888 Print (to standard error) warning messages about possible erroneous usage.
18891 @itemx --delimiter=@var{d}
18893 @opindex --delimiter
18894 Use the character @var{d} as input field separator (default: whitespace).
18895 @emph{Note}: Using non-default delimiter turns off automatic padding.
18897 @item --field=@var{fields}
18899 Convert the number in input field @var{fields} (default: 1).
18900 @var{fields} supports @command{cut} style field ranges:
18903 N N'th field, counted from 1
18904 N- from N'th field, to end of line
18905 N-M from N'th to M'th field (inclusive)
18906 -M from first to M'th field (inclusive)
18911 @item --format=@var{format}
18913 Use printf-style floating FORMAT string. The @var{format} string must contain
18914 one @samp{%f} directive, optionally with @samp{'}, @samp{-}, @samp{0}, width
18915 or precision modifiers. The @samp{'} modifier will enable @option{--grouping},
18916 the @samp{-} modifier will enable left-aligned @option{--padding} and the width
18917 modifier will enable right-aligned @option{--padding}. The @samp{0} width
18918 modifier (without the @samp{-} modifier) will generate leading zeros on the
18919 number, up to the specified width. A precision specification like @samp{%.1f}
18920 will override the precision determined from the input data or set due to
18921 @option{--to} option auto scaling.
18923 @item --from=@var{unit}
18925 Auto-scales input numbers according to @var{unit}. See UNITS below.
18926 The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will
18929 @item --from-unit=@var{n}
18930 @opindex --from-unit
18931 Specify the input unit size (instead of the default 1). Use this option when
18932 the input numbers represent other units (e.g. if the input number @samp{10}
18933 represents 10 units of 512 bytes, use @samp{--from-unit=512}).
18934 Suffixes are handled as with @samp{--from=auto}.
18937 @opindex --grouping
18938 Group digits in output numbers according to the current locale's grouping rules
18939 (e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,}
18940 comma). This option has no effect in @samp{POSIX/C} locale.
18942 @item --header[=@var{n}]
18944 @opindex --header=N
18945 Print the first @var{n} (default: 1) lines without any conversion.
18947 @item --invalid=@var{mode}
18949 The default action on input errors is to exit immediately with status code 2.
18950 @option{--invalid=@samp{abort}} explicitly specifies this default mode.
18951 With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion
18952 error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with
18953 status 0, even in the presence of conversion errors, and with a @var{mode} of
18954 @samp{ignore} do not even print diagnostics.
18956 @item --padding=@var{n}
18958 Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is
18959 a positive number, numbers will be right-aligned. If @var{n} is a negative
18960 number, numbers will be left-aligned. By default, numbers are automatically
18961 aligned based on the input line's width (only with the default delimiter).
18963 @item --round=@var{method}
18965 @opindex --round=up
18966 @opindex --round=down
18967 @opindex --round=from-zero
18968 @opindex --round=towards-zero
18969 @opindex --round=nearest
18970 When converting number representations, round the number according to
18971 @var{method}, which can be @samp{up}, @samp{down},
18972 @samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}.
18974 @item --suffix=@var{suffix}
18976 Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
18979 @item --to=@var{unit}
18981 Auto-scales output numbers according to @var{unit}. See @emph{Units} below.
18982 The default is no scaling, meaning all the digits of the number are printed.
18984 @item --to-unit=@var{n}
18986 Specify the output unit size (instead of the default 1). Use this option when
18987 the output numbers represent other units (e.g. to represent @samp{4,000,000}
18988 bytes in blocks of 1KB, use @samp{--to=si --to-unit=1000}).
18989 Suffixes are handled as with @samp{--from=auto}.
18992 @newlineFieldSeparator
18996 @subsection Possible @var{unit}s:
18998 The following are the possible @var{unit} options with @option{--from=UNITS} and
18999 @option{--to=UNITS}:
19004 No scaling is performed. For input numbers, no suffixes are accepted, and any
19005 trailing characters following the number will trigger an error. For output
19006 numbers, all digits of the numbers will be printed.
19009 Auto-scale numbers according to the @emph{International System of Units (SI)}
19011 For input numbers, accept one of the following suffixes.
19012 For output numbers, values larger than 1000 will be rounded, and printed with
19013 one of the following suffixes:
19016 @samp{K} => @math{1000^1 = 10^3} (Kilo)
19017 @samp{M} => @math{1000^2 = 10^6} (Mega)
19018 @samp{G} => @math{1000^3 = 10^9} (Giga)
19019 @samp{T} => @math{1000^4 = 10^{12}} (Tera)
19020 @samp{P} => @math{1000^5 = 10^{15}} (Peta)
19021 @samp{E} => @math{1000^6 = 10^{18}} (Exa)
19022 @samp{Z} => @math{1000^7 = 10^{21}} (Zetta)
19023 @samp{Y} => @math{1000^8 = 10^{24}} (Yotta)
19024 @samp{R} => @math{1000^9 = 10^{27}} (Ronna)
19025 @samp{Q} => @math{1000^{10} = 10^{30}} (Quetta)
19029 Auto-scale numbers according to the @emph{International Electrotechnical
19030 Commission (IEC)} standard.
19031 For input numbers, accept one of the following suffixes.
19032 For output numbers, values larger than 1024 will be rounded, and printed with
19033 one of the following suffixes:
19036 @samp{K} => @math{1024^1 = 2^{10}} (Kibi)
19037 @samp{M} => @math{1024^2 = 2^{20}} (Mebi)
19038 @samp{G} => @math{1024^3 = 2^{30}} (Gibi)
19039 @samp{T} => @math{1024^4 = 2^{40}} (Tebi)
19040 @samp{P} => @math{1024^5 = 2^{50}} (Pebi)
19041 @samp{E} => @math{1024^6 = 2^{60}} (Exbi)
19042 @samp{Z} => @math{1024^7 = 2^{70}} (Zebi)
19043 @samp{Y} => @math{1024^8 = 2^{80}} (Yobi)
19044 @samp{R} => @math{1024^9 = 2^{90}} (Robi)
19045 @samp{Q} => @math{1024^{10} = 2^{100}} (Quebi)
19048 The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is
19049 not fully standard, as the @emph{iec} standard recommends a two-letter symbol
19050 (e.g @samp{Gi}) -- but in practice, this method is common. Compare with
19051 the @option{iec-i} option.
19054 Auto-scale numbers according to the @emph{International Electrotechnical
19055 Commission (IEC)} standard.
19056 For input numbers, accept one of the following suffixes.
19057 For output numbers, values larger than 1024 will be rounded, and printed with
19058 one of the following suffixes:
19061 @samp{Ki} => @math{1024^1 = 2^{10}} (Kibi)
19062 @samp{Mi} => @math{1024^2 = 2^{20}} (Mebi)
19063 @samp{Gi} => @math{1024^3 = 2^{30}} (Gibi)
19064 @samp{Ti} => @math{1024^4 = 2^{40}} (Tebi)
19065 @samp{Pi} => @math{1024^5 = 2^{50}} (Pebi)
19066 @samp{Ei} => @math{1024^6 = 2^{60}} (Exbi)
19067 @samp{Zi} => @math{1024^7 = 2^{70}} (Zebi)
19068 @samp{Yi} => @math{1024^8 = 2^{80}} (Yobi)
19069 @samp{Ri} => @math{1024^9 = 2^{90}} (Robi)
19070 @samp{Qi} => @math{1024^{10} = 2^{100}} (Quebi)
19073 The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}),
19074 as the @emph{iec} standard recommends, but this is not always common in
19075 practice. Compare with the @option{iec} option.
19078 @samp{auto} can only be used with @option{--from}. With this method, numbers
19079 with single-letter suffixes like @samp{K}
19080 suffixes are interpreted as @emph{SI} values, and numbers with
19081 two-letter suffixes like @samp{Ki}
19082 are interpreted as @emph{IEC} values.
19086 @subsection Examples of using @command{numfmt}
19088 Converting a single number from/to @emph{human} representation:
19090 $ numfmt --to=si 500000
19093 $ numfmt --to=iec 500000
19096 $ numfmt --to=iec-i 500000
19099 $ numfmt --from=si 1M
19102 $ numfmt --from=iec 1M
19105 # with '--from=auto', M=Mega, Mi=Mebi
19106 $ numfmt --from=auto 1M
19108 $ numfmt --from=auto 1Mi
19112 Converting from @samp{SI} to @samp{IEC} scales (e.g. when a drive's capacity is
19113 advertised as @samp{1TB}, while checking the drive's capacity gives lower
19117 $ numfmt --from=si --to=iec 1T
19121 With both input and output scales specified,
19122 the largest defined prefixes are supported:
19125 $ numfmt --from=si --to=iec-i 2000R
19129 Converting a single field from an input file / piped input (these contrived
19130 examples are for demonstration purposes only, as both @command{ls} and
19131 @command{df} support the @option{--human-readable} option to
19132 output sizes in human-readable format):
19135 # Third field (file size) will be shown in SI representation
19136 $ ls -log | numfmt --field 3 --header --to=si | head -n4
19137 -rw-r--r-- 1 94K Aug 23 2011 ABOUT-NLS
19138 -rw-r--r-- 1 3.7K Jan 7 16:15 AUTHORS
19139 -rw-r--r-- 1 36K Jun 1 2011 COPYING
19140 -rw-r--r-- 1 0 Jan 7 15:15 ChangeLog
19142 # Second field (size) will be shown in IEC representation
19143 $ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
19144 File system 1B-blocks Used Available Use% Mounted on
19145 rootfs 132G 104741408 26554036 80% /
19146 tmpfs 794M 7580 804960 1% /run/shm
19147 /dev/sdb1 694G 651424756 46074696 94% /home
19151 Output can be tweaked using @option{--padding} or @option{--format}:
19154 # Pad to 10 characters, right-aligned
19155 $ du -s * | numfmt --to=si --padding=10
19161 # Pad to 10 characters, left-aligned
19162 $ du -s * | numfmt --to=si --padding=-10
19168 # Pad to 10 characters, left-aligned, using 'format'
19169 $ du -s * | numfmt --to=si --format="%10f"
19175 # Pad to 10 characters, left-aligned, using 'format'
19176 $ du -s * | numfmt --to=si --padding="%-10f"
19183 With locales that support grouping digits, using @option{--grouping} or
19184 @option{--format} enables grouping. In @samp{POSIX} locale, grouping is
19188 $ LC_ALL=C numfmt --from=iec --grouping 2G
19191 $ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
19194 $ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
19197 $ LC_ALL=C numfmt --from=iec --format="==%'15f==" 2G
19200 $ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'15f==" 2G
19203 $ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'-15f==" 2G
19206 $ LC_ALL=ta_IN numfmt --from=iec --format="==%'15f==" 2G
19207 == 2,14,74,83,648==
19211 @node seq invocation
19212 @section @command{seq}: Print numeric sequences
19215 @cindex numeric sequences
19216 @cindex sequence of numbers
19218 @command{seq} prints a sequence of numbers to standard output. Synopses:
19221 seq [@var{option}]@dots{} @var{last}
19222 seq [@var{option}]@dots{} @var{first} @var{last}
19223 seq [@var{option}]@dots{} @var{first} @var{increment} @var{last}
19226 @command{seq} prints the numbers from @var{first} to @var{last} by
19227 @var{increment}. By default, each number is printed on a separate line.
19228 When @var{increment} is not specified, it defaults to @samp{1},
19229 even when @var{first} is larger than @var{last}.
19230 @var{first} also defaults to @samp{1}. So @code{seq 1} prints
19231 @samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
19232 The sequence of numbers ends when the sum of the current number and
19233 @var{increment} would become greater than @var{last},
19234 so @code{seq 1 10 10} only produces @samp{1}.
19235 @var{increment} must not be @samp{0}; use the tool @command{yes} to get
19236 repeated output of a constant number.
19237 @var{first}, @var{increment} and @var{last} must not be @code{NaN},
19238 but @code{inf} is supported.
19239 Floating-point numbers may be specified in either the current or
19240 the C locale. @xref{Floating point}.
19242 The program accepts the following options. Also see @ref{Common options}.
19243 Options must precede operands.
19246 @item -f @var{format}
19247 @itemx --format=@var{format}
19250 @cindex formatting of numbers in @command{seq}
19251 Print all numbers using @var{format}.
19252 @var{format} must contain exactly one of the @samp{printf}-style
19253 floating point conversion specifications @samp{%a}, @samp{%e},
19254 @samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}@.
19255 The @samp{%} may be followed by zero or more flags taken from the set
19256 @samp{-+#0 '}, then an optional width containing one or more digits,
19257 then an optional precision consisting of a @samp{.} followed by zero
19258 or more digits. @var{format} may also contain any number of @samp{%%}
19259 conversion specifications. All conversion specifications have the
19260 same meaning as with @samp{printf}.
19262 The default format is derived from @var{first}, @var{step}, and
19263 @var{last}. If these all use a fixed point decimal representation,
19264 the default format is @samp{%.@var{p}f}, where @var{p} is the minimum
19265 precision that can represent the output numbers exactly. Otherwise,
19266 the default format is @samp{%g}.
19268 @item -s @var{string}
19269 @itemx --separator=@var{string}
19271 @opindex --separator
19272 @cindex separator for numbers in @command{seq}
19273 Separate numbers with @var{string}; default is a newline.
19274 The output always terminates with a newline.
19277 @itemx --equal-width
19279 @opindex --equal-width
19280 Print all numbers with the same width, by padding with leading zeros.
19281 @var{first}, @var{step}, and @var{last} should all use a fixed point
19282 decimal representation.
19283 (To have other kinds of padding, use @option{--format}).
19287 You can get finer-grained control over output with @option{-f}:
19290 $ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6
19296 If you want hexadecimal integer output, you can use @command{printf}
19297 to perform the conversion:
19300 $ printf '%x\n' $(seq 1048575 1024 1050623)
19306 For very long lists of numbers, use xargs to avoid
19307 system limitations on the length of an argument list:
19310 $ seq 1000000 | xargs printf '%x\n' | tail -n 3
19316 To generate octal output, use the printf @code{%o} format instead
19319 On most systems, seq can produce whole-number output for values up to
19320 at least @math{2^{53}}. Larger integers are approximated. The details
19321 differ depending on your floating-point implementation.
19322 @xref{Floating point}. A common
19323 case is that @command{seq} works with integers through @math{2^{64}},
19324 and larger integers may not be numerically correct:
19327 $ seq 50000000000000000000 2 50000000000000000004
19328 50000000000000000000
19329 50000000000000000000
19330 50000000000000000004
19333 However, note that when limited to non-negative whole numbers,
19334 an increment of less than 200, and no format-specifying option,
19335 seq can print arbitrarily large numbers.
19336 Therefore @command{seq inf} can be used to
19337 generate an infinite sequence of numbers.
19339 Be careful when using @command{seq} with outlandish values: otherwise
19340 you may see surprising results, as @command{seq} uses floating point
19341 internally. For example, on the x86 platform, where the internal
19342 representation uses a 64-bit fraction, the command:
19345 seq 1 0.0000000000000000001 1.0000000000000000009
19348 outputs 1.0000000000000000007 twice and skips 1.0000000000000000008.
19353 @node File permissions
19354 @chapter File permissions
19358 @node File timestamps
19359 @chapter File timestamps
19365 Standard POSIX files have three timestamps: the access timestamp
19366 (atime) of the last read, the modification timestamp (mtime) of the
19367 last write, and the status change timestamp (ctime) of the last change
19368 to the file's meta-information. Some file systems support a
19369 fourth time: the birth timestamp (birthtime) of when the file was
19370 created; by definition, birthtime never changes.
19372 One common example of a ctime change is when the permissions of a file
19373 change. Changing the permissions doesn't access the file, so atime
19374 doesn't change, nor does it modify the file, so the mtime doesn't
19375 change. Yet, something about the file itself has changed, and this
19376 must be noted somewhere. This is the job of the ctime field. This is
19377 necessary, so that, for example, a backup program can make a fresh
19378 copy of the file, including the new permissions value. Another
19379 operation that modifies a file's ctime without affecting the others is
19382 Naively, a file's atime, mtime, and ctime are set to the current time
19383 whenever you read, write, or change the attributes of the file
19384 respectively, and searching a directory counts as reading it. A
19385 file's atime and mtime can also be set directly, via the
19386 @command{touch} command (@pxref{touch invocation}). In practice,
19387 though, timestamps are not updated quite that way.
19389 For efficiency reasons, many systems are lazy about updating atimes:
19390 when a program accesses a file, they may delay updating the file's
19391 atime, or may not update the file's atime if the file has been
19392 accessed recently, or may not update the atime at all. Similar
19393 laziness, though typically not quite so extreme, applies to mtimes and
19396 Some systems emulate timestamps instead of supporting them directly,
19397 and these emulations may disagree with the naive interpretation. For
19398 example, a system may fake an atime or ctime by using the mtime.
19401 The determination of what time is ``current'' depends on the
19402 platform. Platforms with network file systems often use different
19403 clocks for the operating system and for file systems; because
19404 updates typically uses file systems' clocks by default, clock
19405 skew can cause the resulting file timestamps to appear to be in a
19406 program's ``future'' or ``past''.
19408 @cindex file timestamp resolution
19409 When the system updates a file timestamp to a desired time @var{t}
19410 (which is either the current time, or a time specified via the
19411 @command{touch} command), there are several reasons the file's
19412 timestamp may be set to a value that differs from @var{t}. First,
19413 @var{t} may have a higher resolution than supported. Second, a file
19414 system may use different resolutions for different types of times.
19415 Third, file timestamps may use a different resolution than operating
19416 system timestamps. Fourth, the operating system primitives used to
19417 update timestamps may employ yet a different resolution. For example,
19418 in theory a file system might use 10-microsecond resolution for access
19419 timestamp and 100-nanosecond resolution for modification timestamp, and the
19420 operating system might use nanosecond resolution for the current time
19421 and microsecond resolution for the primitive that @command{touch} uses
19422 to set a file's timestamp to an arbitrary value.
19425 @include parse-datetime.texi
19427 @include sort-version.texi
19431 @node Opening the software toolbox
19432 @chapter Opening the Software Toolbox
19434 An earlier version of this chapter appeared in
19435 @uref{https://www.linuxjournal.com/article.php?sid=2762, the
19436 @cite{What's GNU@?} column of the June 1994 @cite{Linux Journal}}.
19437 It was written by Arnold Robbins.
19440 * Toolbox introduction:: Toolbox introduction
19441 * I/O redirection:: I/O redirection
19442 * The who command:: The @command{who} command
19443 * The cut command:: The @command{cut} command
19444 * The sort command:: The @command{sort} command
19445 * The uniq command:: The @command{uniq} command
19446 * Putting the tools together:: Putting the tools together
19450 @node Toolbox introduction
19451 @unnumberedsec Toolbox Introduction
19453 This month's column is only peripherally related to the GNU Project, in
19454 that it describes a number of the GNU tools on your GNU/Linux system
19456 might be used. What it's really about is the ``Software Tools'' philosophy
19457 of program development and usage.
19459 The software tools philosophy was an important and integral concept
19460 in the initial design and development of Unix (of which GNU/Linux and GNU are
19461 essentially clones). Unfortunately, in the modern day press of
19462 Internetworking and flashy GUIs, it seems to have fallen by the
19463 wayside. This is a shame, since it provides a powerful mental model
19464 for solving many kinds of problems.
19466 Many people carry a Swiss Army knife around in their pants pockets (or
19467 purse). A Swiss Army knife is a handy tool to have: it has several knife
19468 blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps
19469 a number of other things on it. For the everyday, small miscellaneous jobs
19470 where you need a simple, general purpose tool, it's just the thing.
19472 On the other hand, an experienced carpenter doesn't build a house using
19473 a Swiss Army knife. Instead, he has a toolbox chock full of specialized
19474 tools -- a saw, a hammer, a screwdriver, a plane, and so on. And he knows
19475 exactly when and where to use each tool; you won't catch him hammering nails
19476 with the handle of his screwdriver.
19478 The Unix developers at Bell Labs were all professional programmers and trained
19479 computer scientists. They had found that while a one-size-fits-all program
19480 might appeal to a user because there's only one program to use, in practice
19485 difficult to write,
19488 difficult to maintain and
19492 difficult to extend to meet new situations.
19495 Instead, they felt that programs should be specialized tools. In short, each
19496 program ``should do one thing well.'' No more and no less. Such programs are
19497 simpler to design, write, and get right -- they only do one thing.
19499 Furthermore, they found that with the right machinery for hooking programs
19500 together, that the whole was greater than the sum of the parts. By combining
19501 several special purpose programs, you could accomplish a specific task
19502 that none of the programs was designed for, and accomplish it much more
19503 quickly and easily than if you had to write a special purpose program.
19504 We will see some (classic) examples of this further on in the column.
19505 (An important additional point was that, if necessary, take a detour
19506 and build any software tools you may need first, if you don't already
19507 have something appropriate in the toolbox.)
19509 @node I/O redirection
19510 @unnumberedsec I/O Redirection
19512 Hopefully, you are familiar with the basics of I/O redirection in the
19513 shell, in particular the concepts of ``standard input,'' ``standard output,''
19514 and ``standard error''. Briefly, ``standard input'' is a data source, where
19515 data comes from. A program should not need to either know or care if the
19516 data source is a regular file, a keyboard, a magnetic tape, or even a punched
19517 card reader. Similarly, ``standard output'' is a data sink, where data goes
19518 to. The program should neither know nor care where this might be.
19519 Programs that only read their standard input, do something to the data,
19520 and then send it on, are called @dfn{filters}, by analogy to filters in a
19523 With the Unix shell, it's very easy to set up data pipelines:
19526 program_to_create_data | filter1 | ... | filterN > final.pretty.data
19529 We start out by creating the raw data; each filter applies some successive
19530 transformation to the data, until by the time it comes out of the pipeline,
19531 it is in the desired form.
19533 This is fine and good for standard input and standard output. Where does the
19534 standard error come in to play? Well, think about @command{filter1} in
19535 the pipeline above. What happens if it encounters an error in the data it
19536 sees? If it writes an error message to standard output, it will just
19537 disappear down the pipeline into @command{filter2}'s input, and the
19538 user will probably never see it. So programs need a place where they can send
19539 error messages so that the user will notice them. This is standard error,
19540 and it is usually connected to your console or window, even if you have
19541 redirected standard output of your program away from your screen.
19543 For filter programs to work together, the format of the data has to be
19544 agreed upon. The most straightforward and easiest format to use is simply
19545 lines of text. Unix data files are generally just streams of bytes, with
19546 lines delimited by the ASCII LF (Line Feed) character,
19547 conventionally called a ``newline'' in the Unix literature. (This is
19548 @code{'\n'} if you're a C programmer.) This is the format used by all
19549 the traditional filtering programs. (Many earlier operating systems
19550 had elaborate facilities and special purpose programs for managing
19551 binary data. Unix has always shied away from such things, under the
19552 philosophy that it's easiest to simply be able to view and edit your
19553 data with a text editor.)
19555 OK, enough introduction. Let's take a look at some of the tools, and then
19556 we'll see how to hook them together in interesting ways. In the following
19557 discussion, we will only present those command line options that interest
19558 us. As you should always do, double check your system documentation
19559 for the full story.
19561 @node The who command
19562 @unnumberedsec The @command{who} Command
19564 The first program is the @command{who} command. By itself, it generates a
19565 list of the users who are currently logged in. Although I'm writing
19566 this on a single-user system, we'll pretend that several people are
19571 @print{} arnold console Jan 22 19:57
19572 @print{} miriam ttyp0 Jan 23 14:19(:0.0)
19573 @print{} bill ttyp1 Jan 21 09:32(:0.0)
19574 @print{} arnold ttyp2 Jan 23 20:48(:0.0)
19577 Here, the @samp{$} is the usual shell prompt, at which I typed @samp{who}.
19578 There are three people logged in, and I am logged in twice. On traditional
19579 Unix systems, user names are never more than eight characters long. This
19580 little bit of trivia will be useful later. The output of @command{who} is nice,
19581 but the data is not all that exciting.
19583 @node The cut command
19584 @unnumberedsec The @command{cut} Command
19586 The next program we'll look at is the @command{cut} command. This program
19587 cuts out columns or fields of input data. For example, we can tell it
19588 to print just the login name and full name from the @file{/etc/passwd}
19589 file. The @file{/etc/passwd} file has seven fields, separated by
19593 arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash
19596 To get the first and fifth fields, we would use @command{cut} like this:
19599 $ cut -d: -f1,5 /etc/passwd
19600 @print{} root:Operator
19602 @print{} arnold:Arnold D. Robbins
19603 @print{} miriam:Miriam A. Robbins
19607 With the @option{-c} option, @command{cut} will cut out specific characters
19608 (i.e., columns) in the input lines. This is useful for input data
19609 that has fixed width fields, and does not have a field separator. For
19610 example, list the Monday dates for the current month:
19612 @c Is using cal ok? Looked at gcal, but I don't like it.
19623 @node The sort command
19624 @unnumberedsec The @command{sort} Command
19626 Next we'll look at the @command{sort} command. This is one of the most
19627 powerful commands on a Unix-style system; one that you will often find
19628 yourself using when setting up fancy data plumbing.
19631 command reads and sorts each file named on the command line. It then
19632 merges the sorted data and writes it to standard output. It will read
19633 standard input if no files are given on the command line (thus
19634 making it into a filter). The sort is based on the character collating
19635 sequence or based on user-supplied ordering criteria.
19638 @node The uniq command
19639 @unnumberedsec The @command{uniq} Command
19641 Finally (at least for now), we'll look at the @command{uniq} program. When
19642 sorting data, you will often end up with duplicate lines, lines that
19643 are identical. Usually, all you need is one instance of each line.
19644 This is where @command{uniq} comes in. The @command{uniq} program reads its
19645 standard input. It prints only one
19646 copy of each repeated line. It does have several options. Later on,
19647 we'll use the @option{-c} option, which prints each unique line, preceded
19648 by a count of the number of times that line occurred in the input.
19651 @node Putting the tools together
19652 @unnumberedsec Putting the Tools Together
19654 Now, let's suppose this is a large ISP server system with dozens of users
19655 logged in. The management wants the system administrator to write a
19657 generate a sorted list of logged in users. Furthermore, even if a user
19658 is logged in multiple times, his or her name should only show up in the
19661 The administrator could sit down with the system documentation and write a C
19662 program that did this. It would take perhaps a couple of hundred lines
19663 of code and about two hours to write it, test it, and debug it.
19664 However, knowing the software toolbox, the administrator can instead start out
19665 by generating just a list of logged on users:
19675 Next, sort the list:
19678 $ who | cut -c1-8 | sort
19685 Finally, run the sorted list through @command{uniq}, to weed out duplicates:
19688 $ who | cut -c1-8 | sort | uniq
19694 The @command{sort} command actually has a @option{-u} option that does what
19695 @command{uniq} does. However, @command{uniq} has other uses for which one
19696 cannot substitute @samp{sort -u}.
19698 The administrator puts this pipeline into a shell script, and makes it
19700 all the users on the system (@samp{#} is the system administrator,
19701 or @code{root}, prompt):
19704 # cat > /usr/local/bin/listusers
19705 who | cut -c1-8 | sort | uniq
19707 # chmod +x /usr/local/bin/listusers
19710 There are four major points to note here. First, with just four
19711 programs, on one command line, the administrator was able to save about two
19712 hours worth of work. Furthermore, the shell pipeline is just about as
19713 efficient as the C program would be, and it is much more efficient in
19714 terms of programmer time. People time is much more expensive than
19715 computer time, and in our modern ``there's never enough time to do
19716 everything'' society, saving two hours of programmer time is no mean
19719 Second, it is also important to emphasize that with the
19720 @emph{combination} of the tools, it is possible to do a special
19721 purpose job never imagined by the authors of the individual programs.
19723 Third, it is also valuable to build up your pipeline in stages, as we did here.
19724 This allows you to view the data at each stage in the pipeline, which helps
19725 you acquire the confidence that you are indeed using these tools correctly.
19727 Finally, by bundling the pipeline in a shell script, other users can use
19728 your command, without having to remember the fancy plumbing you set up for
19729 them. In terms of how you run them, shell scripts and compiled programs are
19732 After the previous warm-up exercise, we'll look at two additional, more
19733 complicated pipelines. For them, we need to introduce two more tools.
19735 The first is the @command{tr} command, which stands for ``transliterate.''
19736 The @command{tr} command works on a character-by-character basis, changing
19737 characters. Normally it is used for things like mapping upper case to
19741 $ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]'
19742 @print{} this example has mixed case!
19745 There are several options of interest:
19749 work on the complement of the listed characters, i.e.,
19750 operations apply to characters not in the given set
19753 delete characters in the first set from the output
19756 squeeze repeated characters in the output into just one character.
19759 We will be using all three options in a moment.
19761 The other command we'll look at is @command{comm}. The @command{comm}
19762 command takes two sorted input files as input data, and prints out the
19763 files' lines in three columns. The output columns are the data lines
19764 unique to the first file, the data lines unique to the second file, and
19765 the data lines that are common to both. The @option{-1}, @option{-2}, and
19766 @option{-3} command line options @emph{omit} the respective columns. (This is
19767 non-intuitive and takes a little getting used to.) For example:
19789 The file name @file{-} tells @command{comm} to read standard input
19790 instead of a regular file.
19792 Now we're ready to build a fancy pipeline. The first application is a word
19793 frequency counter. This helps an author determine if he or she is over-using
19796 The first step is to change the case of all the letters in our input file
19797 to one case. ``The'' and ``the'' are the same word when doing counting.
19800 $ tr '[:upper:]' '[:lower:]' < whats.gnu | ...
19803 The next step is to get rid of punctuation. Quoted words and unquoted words
19804 should be treated identically; it's easiest to just get the punctuation out of
19808 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ...
19811 The second @command{tr} command operates on the complement of the listed
19812 characters, which are all the letters, the digits, the underscore, and
19813 the blank. The @samp{\n} represents the newline character; it has to
19814 be left alone. (The ASCII tab character should also be included for
19815 good measure in a production script.)
19817 At this point, we have data consisting of words separated by blank space.
19818 The words only contain alphanumeric characters (and the underscore). The
19819 next step is break the data apart so that we have one word per line. This
19820 makes the counting operation much easier, as we will see shortly.
19823 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
19824 > tr -s ' ' '\n' | ...
19827 This command turns blanks into newlines. The @option{-s} option squeezes
19828 multiple newline characters in the output into just one, removing
19829 blank lines. (The @samp{>} is the shell's ``secondary prompt.''
19830 This is what the shell prints when it notices you haven't finished
19831 typing in all of a command.)
19833 We now have data consisting of one word per line, no punctuation, all one
19834 case. We're ready to count each word:
19837 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
19838 > tr -s ' ' '\n' | sort | uniq -c | ...
19841 At this point, the data might look something like this:
19854 The output is sorted by word, not by count! What we want is the most
19855 frequently used words first. Fortunately, this is easy to accomplish,
19856 with the help of two more @command{sort} options:
19860 do a numeric sort, not a textual one
19863 reverse the order of the sort
19866 The final pipeline looks like this:
19869 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
19870 > tr -s ' ' '\n' | sort | uniq -c | sort -n -r
19879 Whew! That's a lot to digest. Yet, the same principles apply. With six
19880 commands, on two lines (really one long one split for convenience), we've
19881 created a program that does something interesting and useful, in much
19882 less time than we could have written a C program to do the same thing.
19884 A minor modification to the above pipeline can give us a simple spelling
19885 checker! To determine if you've spelled a word correctly, all you have to
19886 do is look it up in a dictionary. If it is not there, then chances are
19887 that your spelling is incorrect. So, we need a dictionary.
19888 The conventional location for a dictionary is @file{/usr/share/dict/words}.
19890 Now, how to compare our file with the dictionary? As before, we generate
19891 a sorted list of words, one per line:
19894 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
19895 > tr -s ' ' '\n' | sort -u | ...
19898 Now, all we need is a list of words that are @emph{not} in the
19899 dictionary. Here is where the @command{comm} command comes in.
19900 Unfortunately @command{comm} operates on sorted input and
19901 @file{/usr/share/dict/words} is not sorted the way that @command{sort}
19902 and @command{comm} normally use, so we first create a properly-sorted
19903 copy of the dictionary and then run a pipeline that uses the copy.
19906 $ sort /usr/share/dict/words > sorted-words
19907 $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
19908 > tr -s ' ' '\n' | sort -u |
19909 > comm -23 - sorted-words
19912 The @option{-2} and @option{-3} options eliminate lines that are only in the
19913 dictionary (the second file), and lines that are in both files. Lines
19914 only in the first file (standard input, our stream of words), are
19915 words that are not in the dictionary. These are likely candidates for
19916 spelling errors. This pipeline was the first cut at a production
19917 spelling checker on Unix.
19919 There are some other tools that deserve brief mention.
19923 search files for text that matches a regular expression
19926 count lines, words, characters
19929 a T-fitting for data pipes, copies data to files and to standard output
19932 the stream editor, an advanced tool
19935 a data manipulation language, another advanced tool
19938 The software tools philosophy also espoused the following bit of
19939 advice: ``Let someone else do the hard part.'' This means, take
19940 something that gives you most of what you need, and then massage it the
19941 rest of the way until it's in the form that you want.
19947 Each program should do one thing well. No more, no less.
19950 Combining programs with appropriate plumbing leads to results where
19951 the whole is greater than the sum of the parts. It also leads to novel
19952 uses of programs that the authors might never have imagined.
19955 Programs should never print extraneous header or trailer data, since these
19956 could get sent on down a pipeline. (A point we didn't mention earlier.)
19959 Let someone else do the hard part.
19962 Know your toolbox! Use each program appropriately. If you don't have an
19963 appropriate tool, build one.
19966 All the programs discussed are available as described in
19967 @uref{https://www.gnu.org/software/coreutils/coreutils.html,
19968 GNU core utilities}.
19970 None of what I have presented in this column is new. The Software Tools
19971 philosophy was first introduced in the book @cite{Software Tools}, by
19972 Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X).
19973 This book showed how to write and use software tools. It was written in
19974 1976, using a preprocessor for FORTRAN named @command{ratfor} (RATional
19975 FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN
19976 was. The last chapter presented a @command{ratfor} to FORTRAN
19977 processor, written in @command{ratfor}. @command{ratfor} looks an awful
19978 lot like C; if you know C, you won't have any problem following the
19981 In 1981, the book was updated and made available as @cite{Software Tools
19982 in Pascal} (Addison-Wesley, ISBN 0-201-10342-7). Both books are
19983 still in print and are well worth
19984 reading if you're a programmer. They certainly made a major change in
19985 how I view programming.
19987 The programs in both books are available from
19988 @uref{https://www.cs.princeton.edu/~bwk/, Brian Kernighan's home page}.
19989 For a number of years, there was an active
19990 Software Tools Users Group, whose members had ported the original
19991 @command{ratfor} programs to essentially every computer system with a
19992 FORTRAN compiler. The popularity of the group waned in the middle 1980s
19993 as Unix began to spread beyond universities.
19995 With the current proliferation of GNU code and other clones of Unix programs,
19996 these programs now receive little attention; modern C versions are
19997 much more efficient and do more than these programs do. Nevertheless, as
19998 exposition of good programming style, and evangelism for a still-valuable
19999 philosophy, these books are unparalleled, and I recommend them highly.
20001 Acknowledgment: I would like to express my gratitude to Brian Kernighan
20002 of Bell Labs, the original Software Toolsmith, for reviewing this column.
20004 @node GNU Free Documentation License
20005 @appendix GNU Free Documentation License
20009 @node Concept index
20016 @c Local variables:
20017 @c texinfo-column-for-description: 32