Adding upstream version 9.4.upstream/9.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

10 files changed, 44807 insertions, 0 deletions

diff --git a/doc/constants.texi b/doc/constants.texi
new file mode 100644
index 0000000..afbc6a0
--- /dev/null
+++ b/doc/constants.texi
@@ -0,0 +1,2 @@
+@set DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS 5
+@set SHRED_DEFAULT_PASSES 3
diff --git a/doc/coreutils.info b/doc/coreutils.info
new file mode 100644
index 0000000..8071e5b
--- /dev/null
+++ b/doc/coreutils.info
@@ -0,0 +1,21870 @@
+This is coreutils.info, produced by makeinfo version 7.0.2 from
+coreutils.texi.
+
+This manual documents version 9.4 of the GNU core utilities, including
+the standard programs for text and file manipulation.
+
+   Copyright © 1994–2023 Free Software Foundation, Inc.
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; with no Invariant Sections, with no Front-Cover Texts,
+     and with no Back-Cover Texts.  A copy of the license is included in
+     the section entitled “GNU Free Documentation License”.
+INFO-DIR-SECTION Basics
+START-INFO-DIR-ENTRY
+* Coreutils: (coreutils).       Core GNU (file, text, shell) utilities.
+* Common options: (coreutils)Common options.
+* File permissions: (coreutils)File permissions.  Access modes.
+* Date input formats: (coreutils)Date input formats.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* arch: (coreutils)arch invocation.             Print machine hardware name.
+* b2sum: (coreutils)b2sum invocation.           Print or check BLAKE2 digests.
+* base32: (coreutils)base32 invocation.         Base32 encode/decode data.
+* base64: (coreutils)base64 invocation.         Base64 encode/decode data.
+* basename: (coreutils)basename invocation.     Strip directory and suffix.
+* basenc: (coreutils)basenc invocation.         Encoding/decoding of data.
+* cat: (coreutils)cat invocation.               Concatenate and write files.
+* chcon: (coreutils)chcon invocation.           Change SELinux CTX of files.
+* chgrp: (coreutils)chgrp invocation.           Change file groups.
+* chmod: (coreutils)chmod invocation.           Change access permissions.
+* chown: (coreutils)chown invocation.           Change file owners and groups.
+* chroot: (coreutils)chroot invocation.         Specify the root directory.
+* cksum: (coreutils)cksum invocation.           Print POSIX CRC checksum.
+* comm: (coreutils)comm invocation.             Compare sorted files by line.
+* cp: (coreutils)cp invocation.                 Copy files.
+* csplit: (coreutils)csplit invocation.         Split by context.
+* cut: (coreutils)cut invocation.               Print selected parts of lines.
+* date: (coreutils)date invocation.             Print/set system date and time.
+* dd: (coreutils)dd invocation.                 Copy and convert a file.
+* df: (coreutils)df invocation.                 Report file system usage.
+* dir: (coreutils)dir invocation.               List directories briefly.
+* dircolors: (coreutils)dircolors invocation.   Color setup for ls.
+* dirname: (coreutils)dirname invocation.       Strip last file name component.
+* du: (coreutils)du invocation.                 Report file usage.
+* echo: (coreutils)echo invocation.             Print a line of text.
+* env: (coreutils)env invocation.               Modify the environment.
+* expand: (coreutils)expand invocation.         Convert tabs to spaces.
+* expr: (coreutils)expr invocation.             Evaluate expressions.
+* factor: (coreutils)factor invocation.         Print prime factors
+* false: (coreutils)false invocation.           Do nothing, unsuccessfully.
+* fmt: (coreutils)fmt invocation.               Reformat paragraph text.
+* fold: (coreutils)fold invocation.             Wrap long input lines.
+* groups: (coreutils)groups invocation.         Print group names a user is in.
+* head: (coreutils)head invocation.             Output the first part of files.
+* hostid: (coreutils)hostid invocation.         Print numeric host identifier.
+* hostname: (coreutils)hostname invocation.     Print or set system name.
+* id: (coreutils)id invocation.                 Print user identity.
+* install: (coreutils)install invocation.       Copy files and set attributes.
+* join: (coreutils)join invocation.             Join lines on a common field.
+* kill: (coreutils)kill invocation.             Send a signal to processes.
+* link: (coreutils)link invocation.             Make hard links between files.
+* ln: (coreutils)ln invocation.                 Make links between files.
+* logname: (coreutils)logname invocation.       Print current login name.
+* ls: (coreutils)ls invocation.                 List directory contents.
+* md5sum: (coreutils)md5sum invocation.         Print or check MD5 digests.
+* mkdir: (coreutils)mkdir invocation.           Create directories.
+* mkfifo: (coreutils)mkfifo invocation.         Create FIFOs (named pipes).
+* mknod: (coreutils)mknod invocation.           Create special files.
+* mktemp: (coreutils)mktemp invocation.         Create temporary files.
+* mv: (coreutils)mv invocation.                 Rename files.
+* nice: (coreutils)nice invocation.             Modify niceness.
+* nl: (coreutils)nl invocation.                 Number lines and write files.
+* nohup: (coreutils)nohup invocation.           Immunize to hangups.
+* nproc: (coreutils)nproc invocation.           Print the number of processors.
+* numfmt: (coreutils)numfmt invocation.         Reformat numbers.
+* od: (coreutils)od invocation.                 Dump files in octal, etc.
+* paste: (coreutils)paste invocation.           Merge lines of files.
+* pathchk: (coreutils)pathchk invocation.       Check file name portability.
+* pr: (coreutils)pr invocation.                 Paginate or columnate files.
+* printenv: (coreutils)printenv invocation.     Print environment variables.
+* printf: (coreutils)printf invocation.         Format and print data.
+* ptx: (coreutils)ptx invocation.               Produce permuted indexes.
+* pwd: (coreutils)pwd invocation.               Print working directory.
+* readlink: (coreutils)readlink invocation.     Print referent of a symlink.
+* realpath: (coreutils)realpath invocation.     Print resolved file names.
+* rm: (coreutils)rm invocation.                 Remove files.
+* rmdir: (coreutils)rmdir invocation.           Remove empty directories.
+* runcon: (coreutils)runcon invocation.         Run in specified SELinux CTX.
+* seq: (coreutils)seq invocation.               Print numeric sequences
+* sha1sum: (coreutils)sha1sum invocation.       Print or check SHA-1 digests.
+* sha2: (coreutils)sha2 utilities.              Print or check SHA-2 digests.
+* shred: (coreutils)shred invocation.           Remove files more securely.
+* shuf: (coreutils)shuf invocation.             Shuffling text files.
+* sleep: (coreutils)sleep invocation.           Delay for a specified time.
+* sort: (coreutils)sort invocation.             Sort text files.
+* split: (coreutils)split invocation.           Split into pieces.
+* stat: (coreutils)stat invocation.             Report file(system) status.
+* stdbuf: (coreutils)stdbuf invocation.         Modify stdio buffering.
+* stty: (coreutils)stty invocation.             Print/change terminal settings.
+* sum: (coreutils)sum invocation.               Print traditional checksum.
+* sync: (coreutils)sync invocation.             Sync files to stable storage.
+* tac: (coreutils)tac invocation.               Reverse files.
+* tail: (coreutils)tail invocation.             Output the last part of files.
+* tee: (coreutils)tee invocation.               Redirect to multiple files.
+* test: (coreutils)test invocation.             File/string tests.
+* timeout: (coreutils)timeout invocation.       Run with time limit.
+* touch: (coreutils)touch invocation.           Change file timestamps.
+* tr: (coreutils)tr invocation.                 Translate characters.
+* true: (coreutils)true invocation.             Do nothing, successfully.
+* truncate: (coreutils)truncate invocation.     Shrink/extend size of a file.
+* tsort: (coreutils)tsort invocation.           Topological sort.
+* tty: (coreutils)tty invocation.               Print terminal name.
+* uname: (coreutils)uname invocation.           Print system information.
+* unexpand: (coreutils)unexpand invocation.     Convert spaces to tabs.
+* uniq: (coreutils)uniq invocation.             Uniquify files.
+* unlink: (coreutils)unlink invocation.         Removal via unlink(2).
+* uptime: (coreutils)uptime invocation.         Print uptime and load.
+* users: (coreutils)users invocation.           Print current user names.
+* vdir: (coreutils)vdir invocation.             List directories verbosely.
+* wc: (coreutils)wc invocation.                 Line, word, and byte counts.
+* who: (coreutils)who invocation.               Print who is logged in.
+* whoami: (coreutils)whoami invocation.         Print effective user ID.
+* yes: (coreutils)yes invocation.               Print a string indefinitely.
+END-INFO-DIR-ENTRY
+
+
+File: coreutils.info,  Node: Top,  Next: Introduction,  Up: (dir)
+
+GNU Coreutils
+*************
+
+This manual documents version 9.4 of the GNU core utilities, including
+the standard programs for text and file manipulation.
+
+   Copyright © 1994–2023 Free Software Foundation, Inc.
+
+     Permission is granted to copy, distribute and/or modify this
+     document under the terms of the GNU Free Documentation License,
+     Version 1.3 or any later version published by the Free Software
+     Foundation; with no Invariant Sections, with no Front-Cover Texts,
+     and with no Back-Cover Texts.  A copy of the license is included in
+     the section entitled “GNU Free Documentation License”.
+
+* Menu:
+
+* Introduction::                 Caveats, overview, and authors
+* Common options::               Common options
+* Output of entire files::       cat tac nl od base32 base64 basenc
+* Formatting file contents::     fmt pr fold
+* Output of parts of files::     head tail split csplit
+* Summarizing files::            wc sum cksum b2sum md5sum sha1sum sha2
+* Operating on sorted files::    sort shuf uniq comm ptx tsort
+* Operating on fields::          cut paste join
+* Operating on characters::      tr expand unexpand
+* Directory listing::            ls dir vdir dircolors
+* Basic operations::             cp dd install mv rm shred
+* Special file types::         mkdir rmdir unlink mkfifo mknod ln link readlink
+* Changing file attributes::     chgrp chmod chown touch
+* File space usage::             df du stat sync truncate
+* Printing text::                echo printf yes
+* Conditions::                   false true test expr
+* Redirection::                  tee
+* File name manipulation::       dirname basename pathchk mktemp realpath
+* Working context::              pwd stty printenv tty
+* User information::             id logname whoami groups users who
+* System context::               date arch nproc uname hostname hostid uptime
+* SELinux context::              chcon runcon
+* Modified command invocation::  chroot env nice nohup stdbuf timeout
+* Process control::              kill
+* Delaying::                     sleep
+* Numeric operations::           factor numfmt seq
+* File permissions::             Access modes
+* File timestamps::              File timestamp issues
+* Date input formats::           Specifying date strings
+* Version sort ordering::        Details on version-sort algorithm
+* Opening the software toolbox:: The software tools philosophy
+* GNU Free Documentation License:: Copying and sharing this manual
+* Concept index::                General index
+
+ — The Detailed Node Listing —
+
+Common Options
+
+* Exit status::                  Indicating program success or failure
+* Backup options::               Backup options
+* Block size::                   Block size
+* Floating point::               Floating point number representation
+* Signal specifications::        Specifying signals
+* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax
+* Random sources::               Sources of random data
+* Target directory::             Target directory
+* Trailing slashes::             Trailing slashes
+* Traversing symlinks::          Traversing symlinks to directories
+* Treating / specially::         Treating / specially
+* Standards conformance::        Standards conformance
+* Multi-call invocation::        Multi-call program invocation
+
+Output of entire files
+
+* cat invocation::               Concatenate and write files
+* tac invocation::               Concatenate and write files in reverse
+* nl invocation::                Number lines and write files
+* od invocation::                Write files in octal or other formats
+* base32 invocation::            Transform data into printable data
+* base64 invocation::            Transform data into printable data
+* basenc invocation::            Transform data into printable data
+
+Formatting file contents
+
+* fmt invocation::               Reformat paragraph text
+* pr invocation::                Paginate or columnate files for printing
+* fold invocation::              Wrap input lines to fit in specified width
+
+Output of parts of files
+
+* head invocation::              Output the first part of files
+* tail invocation::              Output the last part of files
+* split invocation::             Split a file into fixed-size pieces
+* csplit invocation::            Split a file into context-determined pieces
+
+Summarizing files
+
+* wc invocation::                Print newline, word, and byte counts
+* sum invocation::               Print checksum and block counts
+* cksum invocation::             Print CRC checksum and byte counts
+* md5sum invocation::            Print or check MD5 digests
+* b2sum invocation::             Print or check BLAKE2 digests
+* sha1sum invocation::           Print or check SHA-1 digests
+* sha2 utilities::               Print or check SHA-2 digests
+
+Operating on sorted files
+
+* sort invocation::              Sort text files
+* shuf invocation::              Shuffle text files
+* uniq invocation::              Uniquify files
+* comm invocation::              Compare two sorted files line by line
+* ptx invocation::               Produce a permuted index of file contents
+* tsort invocation::             Topological sort
+
+‘ptx’: Produce permuted indexes
+
+* General options in ptx::       Options which affect general program behavior
+* Charset selection in ptx::     Underlying character set considerations
+* Input processing in ptx::      Input fields, contexts, and keyword selection
+* Output formatting in ptx::     Types of output format, and sizing the fields
+* Compatibility in ptx::         The GNU extensions to ‘ptx’
+
+Operating on fields
+
+* cut invocation::               Print selected parts of lines
+* paste invocation::             Merge lines of files
+* join invocation::              Join lines on a common field
+
+Operating on characters
+
+* tr invocation::                Translate, squeeze, and/or delete characters
+* expand invocation::            Convert tabs to spaces
+* unexpand invocation::          Convert spaces to tabs
+
+‘tr’: Translate, squeeze, and/or delete characters
+
+* Character arrays::             Specifying arrays of characters
+* Translating::                  Changing one set of characters to another
+* Squeezing and deleting::       Removing characters
+
+Directory listing
+
+* ls invocation::                List directory contents
+* dir invocation::               Briefly list directory contents
+* vdir invocation::              Verbosely list directory contents
+* dircolors invocation::         Color setup for ‘ls’
+
+‘ls’:  List directory contents
+
+* Which files are listed::       Which files are listed
+* What information is listed::   What information is listed
+* Sorting the output::           Sorting the output
+* General output formatting::    General output formatting
+* Formatting the file names::    Formatting the file names
+
+Basic operations
+
+* cp invocation::                Copy files and directories
+* dd invocation::                Convert and copy a file
+* install invocation::           Copy files and set attributes
+* mv invocation::                Move (rename) files
+* rm invocation::                Remove files or directories
+* shred invocation::             Remove files more securely
+
+Special file types
+
+* link invocation::              Make a hard link via the link syscall
+* ln invocation::                Make links between files
+* mkdir invocation::             Make directories
+* mkfifo invocation::            Make FIFOs (named pipes)
+* mknod invocation::             Make block or character special files
+* readlink invocation::          Print value of a symlink or canonical file name
+* rmdir invocation::             Remove empty directories
+* unlink invocation::            Remove files via unlink syscall
+
+Changing file attributes
+
+* chown invocation::             Change file owner and group
+* chgrp invocation::             Change group ownership
+* chmod invocation::             Change access permissions
+* touch invocation::             Change file timestamps
+
+File space usage
+
+* df invocation::                Report file system space usage
+* du invocation::                Estimate file space usage
+* stat invocation::              Report file or file system status
+* sync invocation::              Synchronize cached writes to persistent storage
+* truncate invocation::          Shrink or extend the size of a file
+
+Printing text
+
+* echo invocation::              Print a line of text
+* printf invocation::            Format and print data
+* yes invocation::               Print a string until interrupted
+
+Conditions
+
+* false invocation::             Do nothing, unsuccessfully
+* true invocation::              Do nothing, successfully
+* test invocation::              Check file types and compare values
+* expr invocation::              Evaluate expressions
+
+‘test’: Check file types and compare values
+
+* File type tests::              File type tests
+* Access permission tests::      Access permission tests
+* File characteristic tests::    File characteristic tests
+* String tests::                 String tests
+* Numeric tests::                Numeric tests
+
+‘expr’: Evaluate expression
+
+* String expressions::           ‘+ : match substr index length’
+* Numeric expressions::          ‘+ - * / %’
+* Relations for expr::           ‘| & < <= = == != >= >’
+* Examples of expr::             Examples of using ‘expr’
+
+Redirection
+
+* tee invocation::               Redirect output to multiple files or processes
+
+File name manipulation
+
+* basename invocation::          Strip directory and suffix from a file name
+* dirname invocation::           Strip last file name component
+* pathchk invocation::           Check file name validity and portability
+* mktemp invocation::            Create temporary file or directory
+* realpath invocation::          Print resolved file names
+
+Working context
+
+* pwd invocation::               Print working directory
+* stty invocation::              Print or change terminal characteristics
+* printenv invocation::          Print all or some environment variables
+* tty invocation::               Print file name of terminal on standard input
+
+‘stty’: Print or change terminal characteristics
+
+* Control::                      Control settings
+* Input::                        Input settings
+* Output::                       Output settings
+* Local::                        Local settings
+* Combination::                  Combination settings
+* Characters::                   Special characters
+* Special::                      Special settings
+
+User information
+
+* id invocation::                Print user identity
+* logname invocation::           Print current login name
+* whoami invocation::            Print effective user ID
+* groups invocation::            Print group names a user is in
+* users invocation::             Print login names of users currently logged in
+* who invocation::               Print who is currently logged in
+
+System context
+
+* arch invocation::              Print machine hardware name
+* date invocation::              Print or set system date and time
+* nproc invocation::             Print the number of processors
+* uname invocation::             Print system information
+* hostname invocation::          Print or set system name
+* hostid invocation::            Print numeric host identifier
+* uptime invocation::            Print system uptime and load
+
+‘date’: Print or set system date and time
+
+* Time conversion specifiers::   %[HIklMNpPrRsSTXzZ]
+* Date conversion specifiers::   %[aAbBcCdDeFgGhjmuUVwWxyY]
+* Literal conversion specifiers:: %[%nt]
+* Padding and other flags::      Pad with zeros, spaces, etc.
+* Setting the time::             Changing the system clock
+* Options for date::             Instead of the current time
+* Date input formats::           Specifying date strings
+* Examples of date::             Examples
+
+SELinux context
+
+* chcon invocation::             Change SELinux context of file
+* runcon invocation::            Run a command in specified SELinux context
+
+Modified command invocation
+
+* chroot invocation::            Run a command with a different root directory
+* env invocation::               Run a command in a modified environment
+* nice invocation::              Run a command with modified niceness
+* nohup invocation::             Run a command immune to hangups
+* stdbuf invocation::            Run a command with modified I/O buffering
+* timeout invocation::           Run a command with a time limit
+
+Process control
+
+* kill invocation::              Sending a signal to processes.
+
+Delaying
+
+* sleep invocation::             Delay for a specified time
+
+Numeric operations
+
+* factor invocation::            Print prime factors
+* numfmt invocation::            Reformat numbers
+* seq invocation::               Print numeric sequences
+
+
+File timestamps
+
+* File timestamps::              File timestamp issues
+
+File permissions
+
+* Mode Structure::               Structure of file mode bits
+* Symbolic Modes::               Mnemonic representation of file mode bits
+* Numeric Modes::                File mode bits as octal numbers
+* Directory Setuid and Setgid::  Set-user-ID and set-group-ID on directories
+
+Date input formats
+
+* General date syntax::          Common rules
+* Calendar date items::          ‘14 Nov 2022’
+* Time of day items::            ‘9:02pm’
+* Time zone items::              ‘UTC’, ‘-0700’, ‘+0900’, ...
+* Combined date and time of day items:: ‘2022-11-14T21:02:42,000000-0500’
+* Day of week items::            ‘Monday’ and others
+* Relative items in date strings:: ‘next tuesday, 2 years ago’
+* Pure numbers in date strings:: ‘20221114’, ‘2102’
+* Seconds since the Epoch::      ‘@1668477762’
+* Specifying time zone rules::   ‘TZ="America/New_York"’, ‘TZ="UTC0"’
+* Authors of parse_datetime::    Bellovin, Eggert, Salz, Berets, et al.
+
+Version sorting order
+
+* Version sort overview::
+* Version sort implementation::
+* Differences from Debian version sort::
+* Advanced version sort topics::
+
+Opening the software toolbox
+
+* Toolbox introduction::         Toolbox introduction
+* I/O redirection::              I/O redirection
+* The who command::              The ‘who’ command
+* The cut command::              The ‘cut’ command
+* The sort command::             The ‘sort’ command
+* The uniq command::             The ‘uniq’ command
+* Putting the tools together::   Putting the tools together
+
+Copying This Manual
+
+* GNU Free Documentation License::     Copying and sharing this manual
+
+
+
+File: coreutils.info,  Node: Introduction,  Next: Common options,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+This manual is a work in progress: many sections make no attempt to
+explain basic concepts in a way suitable for novices.  Thus, if you are
+interested, please get involved in improving this manual.  The entire
+GNU community will benefit.
+
+   The GNU utilities documented here are mostly compatible with the
+POSIX standard.
+
+   Please report bugs to <bug-coreutils@gnu.org>.  Include the version
+number, machine architecture, input files, and any other information
+needed to reproduce the bug: your input, what you expected, what you
+got, and why it is wrong.
+
+   If you have a problem with ‘sort’ or ‘date’, try using the ‘--debug’
+option, as it can often help find and fix problems without having to
+wait for an answer to a bug report.  If the debug output does not
+suffice to fix the problem on your own, please compress and attach it to
+the rest of your bug report.
+
+   Although diffs are welcome, please include a description of the
+problem as well, since this is sometimes difficult to infer.  *Note
+(gcc)Bugs::.
+
+   This manual was originally derived from the Unix man pages in the
+distributions, which were written by David MacKenzie and updated by Jim
+Meyering.  What you are reading now is the authoritative documentation
+for these utilities; the man pages are no longer being maintained.  The
+original ‘fmt’ man page was written by Ross Paterson.  François Pinard
+did the initial conversion to Texinfo format.  Karl Berry did the
+indexing, some reorganization, and editing of the results.  Brian
+Youmans of the Free Software Foundation office staff combined the
+manuals for textutils, fileutils, and sh-utils to produce the present
+omnibus manual.  Richard Stallman contributed his usual invaluable
+insights to the overall process.
+
+
+File: coreutils.info,  Node: Common options,  Next: Output of entire files,  Prev: Introduction,  Up: Top
+
+2 Common options
+****************
+
+Certain options are available in all of these programs.  Rather than
+writing identical descriptions for each of the programs, they are
+described here.  (In fact, every GNU program accepts (or should accept)
+these options.)
+
+   Normally options and operands can appear in any order, and programs
+act as if all the options appear before any operands.  For example,
+‘sort -r passwd -t :’ acts like ‘sort -r -t : passwd’, since ‘:’ is an
+option-argument of ‘-t’.  However, if the ‘POSIXLY_CORRECT’ environment
+variable is set, options must appear before operands, unless otherwise
+specified for a particular command.
+
+   A few programs can usefully have trailing operands with leading ‘-’.
+With such a program, options must precede operands even if
+‘POSIXLY_CORRECT’ is not set, and this fact is noted in the program
+description.  For example, the ‘env’ command’s options must appear
+before its operands, since in some cases the operands specify a command
+that itself contains options.
+
+   Most programs that accept long options recognize unambiguous
+abbreviations of those options.  For example, ‘rmdir
+--ignore-fail-on-non-empty’ can be invoked as ‘rmdir --ignore-fail’ or
+even ‘rmdir --i’.  Ambiguous options, such as ‘ls --h’, are identified
+as such.
+
+   Some of these programs recognize the ‘--help’ and ‘--version’ options
+only when one of them is the sole command line argument.  For these
+programs, abbreviations of the long options are not always recognized.
+
+‘--help’
+     Print a usage message listing all available options, then exit
+     successfully.
+
+‘--version’
+     Print the version number, then exit successfully.
+
+‘--’
+     Delimit the option list.  Later arguments, if any, are treated as
+     operands even if they begin with ‘-’.  For example, ‘sort -- -r’
+     reads from the file named ‘-r’.
+
+   A single ‘-’ operand is not really an option, though it looks like
+one.  It stands for a file operand, and some tools treat it as standard
+input, or as standard output if that is clear from the context.  For
+example, ‘sort -’ reads from standard input, and is equivalent to plain
+‘sort’.  Unless otherwise specified, a ‘-’ can appear as any operand
+that requires a file name.
+
+* Menu:
+
+Items shared between some programs:
+
+* Backup options::               ‘-b’ ‘-S’.
+* Block size::                   BLOCK_SIZE and ‘--block-size’.
+* Signal specifications::        Specifying signals with ‘--signal’.
+* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax
+* Random sources::               ‘--random-source’.
+* Target directory::             Specifying a target directory.
+* Trailing slashes::             ‘--strip-trailing-slashes’.
+* Traversing symlinks::          ‘-H’, ‘-L’, or ‘-P’.
+* Treating / specially::         ‘--preserve-root’ and the converse.
+* Special built-in utilities::   ‘break’, ‘:’, ...
+
+Items applicable to all programs:
+
+* Exit status::                  Indicating program success or failure.
+* Floating point::               Floating point number representation.
+* Standards conformance::        Conformance to the POSIX standard.
+* Multi-call invocation::        Multi-call program invocation.
+
+
+File: coreutils.info,  Node: Backup options,  Next: Block size,  Up: Common options
+
+2.1 Backup options
+==================
+
+Some GNU programs (at least ‘cp’, ‘install’, ‘ln’, and ‘mv’) optionally
+make backups of files before writing new versions.  These options
+control the details of these backups.  The options are also briefly
+mentioned in the descriptions of the particular programs.
+
+‘-b’
+‘--backup[=METHOD]’
+     Make a backup of each file that would otherwise be overwritten or
+     removed.  Without this option, the original versions are destroyed.
+     Use METHOD to determine the type of backups to make.  When this
+     option is used but METHOD is not specified, then the value of the
+     ‘VERSION_CONTROL’ environment variable is used.  And if
+     ‘VERSION_CONTROL’ is not set, the default backup type is
+     ‘existing’.
+
+     Note that the short form of this option, ‘-b’ does not accept any
+     argument.  Using ‘-b’ is equivalent to using ‘--backup=existing’.
+
+     This option corresponds to the Emacs variable ‘version-control’;
+     the values for METHOD are the same as those used in Emacs.  This
+     option also accepts more descriptive names.  The valid METHODs are
+     (unique abbreviations are accepted):
+
+     ‘none’
+     ‘off’
+          Never make backups.
+
+     ‘numbered’
+     ‘t’
+          Always make numbered backups.
+
+     ‘existing’
+     ‘nil’
+          Make numbered backups of files that already have them, simple
+          backups of the others.
+
+     ‘simple’
+     ‘never’
+          Always make simple backups.  Please note ‘never’ is not to be
+          confused with ‘none’.
+
+‘-S SUFFIX’
+‘--suffix=SUFFIX’
+     Append SUFFIX to each backup file made with ‘-b’.  If this option
+     is not specified, the value of the ‘SIMPLE_BACKUP_SUFFIX’
+     environment variable is used.  And if ‘SIMPLE_BACKUP_SUFFIX’ is not
+     set, the default is ‘~’, just as in Emacs.
+
+
+File: coreutils.info,  Node: Block size,  Next: Signal specifications,  Prev: Backup options,  Up: Common options
+
+2.2 Block size
+==============
+
+Some GNU programs (at least ‘df’, ‘du’, and ‘ls’) display sizes in
+“blocks”.  You can adjust the block size and method of display to make
+sizes easier to read.  The block size used for display is independent of
+any file system block size.  Fractional block counts are rounded up to
+the nearest integer.
+
+   The default block size is chosen by examining the following
+environment variables in turn; the first one that is set determines the
+block size.
+
+‘DF_BLOCK_SIZE’
+     This specifies the default block size for the ‘df’ command.
+     Similarly, ‘DU_BLOCK_SIZE’ specifies the default for ‘du’ and
+     ‘LS_BLOCK_SIZE’ for ‘ls’.
+
+‘BLOCK_SIZE’
+     This specifies the default block size for all three commands, if
+     the above command-specific environment variables are not set.
+
+‘BLOCKSIZE’
+     This specifies the default block size for all values that are
+     normally printed as blocks, if neither ‘BLOCK_SIZE’ nor the above
+     command-specific environment variables are set.  Unlike the other
+     environment variables, ‘BLOCKSIZE’ does not affect values that are
+     normally printed as byte counts, e.g., the file sizes contained in
+     ‘ls -l’ output.
+
+‘POSIXLY_CORRECT’
+     If neither ‘COMMAND_BLOCK_SIZE’, nor ‘BLOCK_SIZE’, nor ‘BLOCKSIZE’
+     is set, but this variable is set, the block size defaults to 512.
+
+   If none of the above environment variables are set, the block size
+currently defaults to 1024 bytes in most contexts, but this number may
+change in the future.  For ‘ls’ file sizes, the block size defaults to 1
+byte.
+
+   A block size specification can be a positive integer specifying the
+number of bytes per block, or it can be ‘human-readable’ or ‘si’ to
+select a human-readable format.  Integers may be followed by suffixes
+that are upward compatible with the SI prefixes
+(http://www.bipm.org/en/publications/si-brochure/chapter3.html) for
+decimal multiples and with the ISO/IEC 80000-13 (formerly IEC 60027-2)
+prefixes (https://physics.nist.gov/cuu/Units/binary.html) for binary
+multiples.
+
+   With human-readable formats, output sizes are followed by a size
+letter such as ‘M’ for megabytes.  ‘BLOCK_SIZE=human-readable’ uses
+powers of 1024; ‘M’ stands for 1,048,576 bytes.  ‘BLOCK_SIZE=si’ is
+similar, but uses powers of 1000 and appends ‘B’; ‘MB’ stands for
+1,000,000 bytes.
+
+   A block size specification preceded by ‘'’ causes output sizes to be
+displayed with thousands separators.  The ‘LC_NUMERIC’ locale specifies
+the thousands separator and grouping.  For example, in an American
+English locale, ‘--block-size="'1kB"’ would cause a size of 1234000
+bytes to be displayed as ‘1,234’.  In the default C locale, there is no
+thousands separator so a leading ‘'’ has no effect.
+
+   An integer block size can be followed by a suffix to specify a
+multiple of that size.  A bare size letter, or one followed by ‘iB’,
+specifies a multiple using powers of 1024.  A size letter followed by
+‘B’ specifies powers of 1000 instead.  For example, ‘1M’ and ‘1MiB’ are
+equivalent to ‘1048576’, whereas ‘1MB’ is equivalent to ‘1000000’.
+
+   A plain suffix without a preceding integer acts as if ‘1’ were
+prepended, except that it causes a size indication to be appended to the
+output.  For example, ‘--block-size="kB"’ displays 3000 as ‘3kB’.
+
+   The following suffixes are defined.  Large sizes like ‘1Q’ may be
+rejected by your computer due to limitations of its arithmetic.
+
+‘kB’
+     kilobyte: 10^3 = 1000.
+‘k’
+‘K’
+‘KiB’
+     kibibyte: 2^{10} = 1024.  ‘K’ is special: the SI prefix is ‘k’ and
+     the ISO/IEC 80000-13 prefix is ‘Ki’, but tradition and POSIX use
+     ‘k’ to mean ‘KiB’.
+‘MB’
+     megabyte: 10^6 = 1,000,000.
+‘M’
+‘MiB’
+     mebibyte: 2^{20} = 1,048,576.
+‘GB’
+     gigabyte: 10^9 = 1,000,000,000.
+‘G’
+‘GiB’
+     gibibyte: 2^{30} = 1,073,741,824.
+‘TB’
+     terabyte: 10^{12} = 1,000,000,000,000.
+‘T’
+‘TiB’
+     tebibyte: 2^{40} = 1,099,511,627,776.
+‘PB’
+     petabyte: 10^{15} = 1,000,000,000,000,000.
+‘P’
+‘PiB’
+     pebibyte: 2^{50} = 1,125,899,906,842,624.
+‘EB’
+     exabyte: 10^{18} = 1,000,000,000,000,000,000.
+‘E’
+‘EiB’
+     exbibyte: 2^{60} = 1,152,921,504,606,846,976.
+‘ZB’
+     zettabyte: 10^{21} = 1,000,000,000,000,000,000,000
+‘Z’
+‘ZiB’
+     zebibyte: 2^{70} = 1,180,591,620,717,411,303,424.
+‘YB’
+     yottabyte: 10^{24} = 1,000,000,000,000,000,000,000,000.
+‘Y’
+‘YiB’
+     yobibyte: 2^{80} = 1,208,925,819,614,629,174,706,176.
+‘RB’
+     ronnabyte: 10^{27} = 1,000,000,000,000,000,000,000,000,000.
+‘R’
+‘RiB’
+     robibyte: 2^{90} = 1,237,940,039,285,380,274,899,124,224.
+‘QB’
+     quettabyte: 10^{30} = 1,000,000,000,000,000,000,000,000,000,000.
+‘Q’
+‘QiB’
+     quebibyte: 2^{100} = 1,267,650,600,228,229,401,496,703,205,376.
+
+   Block size defaults can be overridden by an explicit
+‘--block-size=SIZE’ option.  The ‘-k’ option is equivalent to
+‘--block-size=1K’, which is the default unless the ‘POSIXLY_CORRECT’
+environment variable is set.  The ‘-h’ or ‘--human-readable’ option is
+equivalent to ‘--block-size=human-readable’.  The ‘--si’ option is
+equivalent to ‘--block-size=si’.  Note for ‘ls’ the ‘-k’ option does not
+control the display of the apparent file sizes, whereas the
+‘--block-size’ option does.
+
+
+File: coreutils.info,  Node: Signal specifications,  Next: Disambiguating names and IDs,  Prev: Block size,  Up: Common options
+
+2.3 Signal specifications
+=========================
+
+A SIGNAL may be a signal name like ‘HUP’, or a signal number like ‘1’,
+or an exit status of a process terminated by the signal.  A signal name
+can be given in canonical form or prefixed by ‘SIG’.  The case of the
+letters is ignored.  The following signal names and numbers are
+supported on all POSIX compliant systems:
+
+‘HUP’
+     1.  Hangup.
+‘INT’
+     2.  Terminal interrupt.
+‘QUIT’
+     3.  Terminal quit.
+‘ABRT’
+     6.  Process abort.
+‘KILL’
+     9.  Kill (cannot be caught or ignored).
+‘ALRM’
+     14.  Alarm Clock.
+‘TERM’
+     15.  Termination.
+
+Other supported signal names have system-dependent corresponding
+numbers.  All systems conforming to POSIX 1003.1-2001 also support the
+following signals:
+
+‘BUS’
+     Access to an undefined portion of a memory object.
+‘CHLD’
+     Child process terminated, stopped, or continued.
+‘CONT’
+     Continue executing, if stopped.
+‘FPE’
+     Erroneous arithmetic operation.
+‘ILL’
+     Illegal Instruction.
+‘PIPE’
+     Write on a pipe with no one to read it.
+‘SEGV’
+     Invalid memory reference.
+‘STOP’
+     Stop executing (cannot be caught or ignored).
+‘TSTP’
+     Terminal stop.
+‘TTIN’
+     Background process attempting read.
+‘TTOU’
+     Background process attempting write.
+‘URG’
+     High bandwidth data is available at a socket.
+‘USR1’
+     User-defined signal 1.
+‘USR2’
+     User-defined signal 2.
+
+POSIX 1003.1-2001 systems that support the XSI extension also support
+the following signals:
+
+‘POLL’
+     Pollable event.
+‘PROF’
+     Profiling timer expired.
+‘SYS’
+     Bad system call.
+‘TRAP’
+     Trace/breakpoint trap.
+‘VTALRM’
+     Virtual timer expired.
+‘XCPU’
+     CPU time limit exceeded.
+‘XFSZ’
+     File size limit exceeded.
+
+POSIX 1003.1-2001 systems that support the XRT extension also support at
+least eight real-time signals called ‘RTMIN’, ‘RTMIN+1’, ..., ‘RTMAX-1’,
+‘RTMAX’.
+
+
+File: coreutils.info,  Node: Disambiguating names and IDs,  Next: Random sources,  Prev: Signal specifications,  Up: Common options
+
+2.4 chown, chgrp, chroot, id: Disambiguating user names and IDs
+===============================================================
+
+Since the USER and GROUP arguments to these commands may be specified as
+names or numeric IDs, there is an apparent ambiguity.  What if a user or
+group _name_ is a string of digits?  Should the command interpret it as
+a user name or as an ID?  (Using a number as a user name is common in
+some environments.)  POSIX requires that these commands first attempt to
+resolve the specified string as a name, and only once that fails, then
+try to interpret it as an ID.  This is troublesome when you want to
+specify a numeric ID, say 42, and it must work even in a pathological
+situation where ‘42’ is a user name that maps to some other user ID, say
+1000.  Simply invoking ‘chown 42 F’, will set ‘F’s owner ID to 1000 –
+not what you intended.
+
+   GNU ‘chown’, ‘chgrp’, ‘chroot’, and ‘id’ provide a way to work around
+this, that at the same time may result in a significant performance
+improvement by eliminating a database look-up.  Simply precede each
+numeric user ID and/or group ID with a ‘+’, in order to force its
+interpretation as an integer:
+
+     chown +42 F
+     chgrp +$numeric_group_id another-file
+     chown +0:+0 /
+
+   The name look-up process is skipped for each ‘+’-prefixed string,
+because a string containing ‘+’ is never a valid user or group name.
+This syntax is accepted on most common Unix systems, but not on Solaris
+10.
+
+
+File: coreutils.info,  Node: Random sources,  Next: Target directory,  Prev: Disambiguating names and IDs,  Up: Common options
+
+2.5 Sources of random data
+==========================
+
+The ‘shuf’, ‘shred’, and ‘sort’ commands sometimes need random data to
+do their work.  For example, ‘sort -R’ must choose a hash function at
+random, and it needs random data to make this selection.
+
+   By default these commands use an internal pseudo-random generator
+initialized by a small amount of entropy, but can be directed to use an
+external source with the ‘--random-source=FILE’ option.  An error is
+reported if FILE does not contain enough bytes.
+
+   For example, the device file ‘/dev/urandom’ could be used as the
+source of random data.  Typically, this device gathers environmental
+noise from device drivers and other sources into an entropy pool, and
+uses the pool to generate random bits.  If the pool is short of data,
+the device reuses the internal pool to produce more bits, using a
+cryptographically secure pseudo-random number generator.  But be aware
+that this device is not designed for bulk random data generation and is
+relatively slow.
+
+   ‘/dev/urandom’ suffices for most practical uses, but applications
+requiring high-value or long-term protection of private data may require
+an alternate data source like ‘/dev/random’ or ‘/dev/arandom’.  The set
+of available sources depends on your operating system.
+
+   To reproduce the results of an earlier invocation of a command, you
+can save some random data into a file and then use that file as the
+random source in earlier and later invocations of the command.  Rather
+than depending on a file, one can generate a reproducible arbitrary
+amount of pseudo-random data given a seed value, using for example:
+
+     get_seeded_random()
+     {
+       seed="$1"
+       openssl enc -aes-256-ctr -pass pass:"$seed" -nosalt \
+         </dev/zero 2>/dev/null
+     }
+
+     shuf -i1-100 --random-source=<(get_seeded_random 42)
+
+
+File: coreutils.info,  Node: Target directory,  Next: Trailing slashes,  Prev: Random sources,  Up: Common options
+
+2.6 Target directory
+====================
+
+The ‘cp’, ‘install’, ‘ln’, and ‘mv’ commands normally treat the last
+operand specially when it is a directory or a symbolic link to a
+directory.  For example, ‘cp source dest’ is equivalent to ‘cp source
+dest/source’ if ‘dest’ is a directory.  Sometimes this behavior is not
+exactly what is wanted, so these commands support the following options
+to allow more fine-grained control:
+
+‘-T’
+‘--no-target-directory’
+     Do not treat the last operand specially when it is a directory or a
+     symbolic link to a directory.  This can help avoid race conditions
+     in programs that operate in a shared area.  For example, when the
+     command ‘mv /tmp/source /tmp/dest’ succeeds, there is no guarantee
+     that ‘/tmp/source’ was renamed to ‘/tmp/dest’: it could have been
+     renamed to ‘/tmp/dest/source’ instead, if some other process
+     created ‘/tmp/dest’ as a directory.  However, if ‘mv -T /tmp/source
+     /tmp/dest’ succeeds, there is no question that ‘/tmp/source’ was
+     renamed to ‘/tmp/dest’.
+
+     In the opposite situation, where you want the last operand to be
+     treated as a directory and want a diagnostic otherwise, you can use
+     the ‘--target-directory’ (‘-t’) option.
+
+‘-t DIRECTORY’
+‘--target-directory=DIRECTORY’
+     Use DIRECTORY as the directory component of each destination file
+     name.
+
+     The interface for most programs is that after processing options
+     and a finite (possibly zero) number of fixed-position arguments,
+     the remaining argument list is either expected to be empty, or is a
+     list of items (usually files) that will all be handled identically.
+     The ‘xargs’ program is designed to work well with this convention.
+
+     The commands in the ‘mv’-family are unusual in that they take a
+     variable number of arguments with a special case at the _end_
+     (namely, the target directory).  This makes it nontrivial to
+     perform some operations, e.g., “move all files from here to ../d/”,
+     because ‘mv * ../d/’ might exhaust the argument space, and ‘ls |
+     xargs ...’ doesn’t have a clean way to specify an extra final
+     argument for each invocation of the subject command.  (It can be
+     done by going through a shell command, but that requires more human
+     labor and brain power than it should.)
+
+     The ‘--target-directory’ (‘-t’) option allows the ‘cp’, ‘install’,
+     ‘ln’, and ‘mv’ programs to be used conveniently with ‘xargs’.  For
+     example, you can move the files from the current directory to a
+     sibling directory, ‘d’ like this:
+
+          ls | xargs mv -t ../d --
+
+     However, this doesn’t move files whose names begin with ‘.’.  If
+     you use the GNU ‘find’ program, you can move those files too, with
+     this command:
+
+          find . -mindepth 1 -maxdepth 1 \
+            | xargs mv -t ../d
+
+     But both of the above approaches fail if there are no files in the
+     current directory, or if any file has a name containing a blank or
+     some other special characters.  The following example removes those
+     limitations and requires both GNU ‘find’ and GNU ‘xargs’:
+
+          find . -mindepth 1 -maxdepth 1 -print0 \
+            | xargs --null --no-run-if-empty \
+                mv -t ../d
+
+The ‘--target-directory’ (‘-t’) and ‘--no-target-directory’ (‘-T’)
+options cannot be combined.
+
+
+File: coreutils.info,  Node: Trailing slashes,  Next: Traversing symlinks,  Prev: Target directory,  Up: Common options
+
+2.7 Trailing slashes
+====================
+
+Some GNU programs (at least ‘cp’ and ‘mv’) allow you to remove any
+trailing slashes from each SOURCE argument before operating on it.  The
+‘--strip-trailing-slashes’ option enables this behavior.
+
+   This is useful when a SOURCE argument may have a trailing slash and
+specify a symbolic link to a directory.  This scenario is in fact rather
+common because some shells can automatically append a trailing slash
+when performing file name completion on such symbolic links.  Without
+this option, ‘mv’, for example, (via the system’s rename function) must
+interpret a trailing slash as a request to dereference the symbolic link
+and so must rename the indirectly referenced _directory_ and not the
+symbolic link.  Although it may seem surprising that such behavior be
+the default, it is required by POSIX and is consistent with other parts
+of that standard.
+
+
+File: coreutils.info,  Node: Traversing symlinks,  Next: Treating / specially,  Prev: Trailing slashes,  Up: Common options
+
+2.8 Traversing symlinks
+=======================
+
+The following options modify how ‘chown’ and ‘chgrp’ traverse a
+hierarchy when the ‘--recursive’ (‘-R’) option is also specified.  If
+more than one of the following options is specified, only the final one
+takes effect.  These options specify whether processing a symbolic link
+to a directory entails operating on just the symbolic link or on all
+files in the hierarchy rooted at that directory.
+
+   These options are independent of ‘--dereference’ and
+‘--no-dereference’ (‘-h’), which control whether to modify a symlink or
+its referent.
+
+‘-H’
+     If ‘--recursive’ (‘-R’) is specified and a command line argument is
+     a symbolic link to a directory, traverse it.
+
+‘-L’
+     In a recursive traversal, traverse every symbolic link to a
+     directory that is encountered.
+
+‘-P’
+     Do not traverse any symbolic links.  This is the default if none of
+     ‘-H’, ‘-L’, or ‘-P’ is specified.
+
+
+File: coreutils.info,  Node: Treating / specially,  Next: Special built-in utilities,  Prev: Traversing symlinks,  Up: Common options
+
+2.9 Treating ‘/’ specially
+==========================
+
+Certain commands can operate destructively on entire hierarchies.  For
+example, if a user with appropriate privileges mistakenly runs ‘rm -rf /
+tmp/junk’, that may remove all files on the entire system.  Since there
+are so few legitimate uses for such a command, GNU ‘rm’ normally
+declines to operate on any directory that resolves to ‘/’.  If you
+really want to try to remove all the files on your system, you can use
+the ‘--no-preserve-root’ option, but the default behavior, specified by
+the ‘--preserve-root’ option, is safer for most purposes.
+
+   The commands ‘chgrp’, ‘chmod’ and ‘chown’ can also operate
+destructively on entire hierarchies, so they too support these options.
+Although, unlike ‘rm’, they don’t actually unlink files, these commands
+are arguably more dangerous when operating recursively on ‘/’, since
+they often work much more quickly, and hence damage more files before an
+alert user can interrupt them.  Tradition and POSIX require these
+commands to operate recursively on ‘/’, so they default to
+‘--no-preserve-root’, but using the ‘--preserve-root’ option makes them
+safer for most purposes.  For convenience you can specify
+‘--preserve-root’ in an alias or in a shell function.
+
+   Note that the ‘--preserve-root’ option also ensures that ‘chgrp’ and
+‘chown’ do not modify ‘/’ even when dereferencing a symlink pointing to
+‘/’.
+
+
+File: coreutils.info,  Node: Special built-in utilities,  Next: Exit status,  Prev: Treating / specially,  Up: Common options
+
+2.10 Special built-in utilities
+===============================
+
+Some programs like ‘nice’ can invoke other programs; for example, the
+command ‘nice cat file’ invokes the program ‘cat’ by executing the
+command ‘cat file’.  However, “special built-in utilities” like ‘exit’
+cannot be invoked this way.  For example, the command ‘nice exit’ does
+not have a well-defined behavior: it may generate an error message
+instead of exiting.
+
+   Here is a list of the special built-in utilities that are
+standardized by POSIX 1003.1-2004.
+
+     . : break continue eval exec exit export readonly return set shift
+     times trap unset
+
+   For example, because ‘.’, ‘:’, and ‘exec’ are special, the commands
+‘nice . foo.sh’, ‘nice :’, and ‘nice exec pwd’ do not work as you might
+expect.
+
+   Many shells extend this list.  For example, Bash has several extra
+special built-in utilities like ‘history’, and ‘suspend’, and with Bash
+the command ‘nice suspend’ generates an error message instead of
+suspending.
+
+
+File: coreutils.info,  Node: Exit status,  Next: Floating point,  Prev: Special built-in utilities,  Up: Common options
+
+2.11 Exit status
+================
+
+Nearly every command invocation yields an integral “exit status” that
+can be used to change how other commands work.  For the vast majority of
+commands, an exit status of zero indicates success.  Failure is
+indicated by a nonzero value – typically ‘1’, though it may differ on
+unusual platforms as POSIX requires only that it be nonzero.
+
+   However, some of the programs documented here do produce other exit
+status values and a few associate different meanings with the values ‘0’
+and ‘1’.  Here are the exceptions: ‘chroot’, ‘env’, ‘expr’, ‘ls’,
+‘nice’, ‘nohup’, ‘numfmt’, ‘printenv’, ‘runcon’, ‘sort’, ‘stdbuf’,
+‘test’, ‘timeout’, ‘tty’.
+
+
+File: coreutils.info,  Node: Floating point,  Next: Standards conformance,  Prev: Exit status,  Up: Common options
+
+2.12 Floating point numbers
+===========================
+
+Commands that accept or produce floating point numbers employ the
+floating point representation of the underlying system, and suffer from
+rounding error, overflow, and similar floating-point issues.  Almost all
+modern systems use IEEE-754 floating point, and it is typically portable
+to assume IEEE-754 behavior these days.  IEEE-754 has positive and
+negative infinity, distinguishes positive from negative zero, and uses
+special values called NaNs to represent invalid computations such as
+dividing zero by itself.  For more information, please see David
+Goldberg’s paper What Every Computer Scientist Should Know About
+Floating-Point Arithmetic
+(https://docs.oracle.com/cd/E19957-01/806-3568/ncg_goldberg.html).
+
+   Commands that accept floating point numbers as options, operands or
+input use the standard C functions ‘strtod’ and ‘strtold’ to convert
+from text to floating point numbers.  These floating point numbers
+therefore can use scientific notation like ‘1.0e-34’ and ‘-10e100’.
+Commands that parse floating point also understand case-insensitive
+‘inf’, ‘infinity’, and ‘NaN’, although whether such values are useful
+depends on the command in question.  Modern C implementations also
+accept hexadecimal floating point numbers such as ‘-0x.ep-3’, which
+stands for −14/16 times 2^-3, which equals −0.109375.  *Note
+(libc)Parsing of Floats::.
+
+   Normally the ‘LC_NUMERIC’ locale determines the decimal-point
+character.  However, some commands’ descriptions specify that they
+accept numbers in either the current or the C locale; for example, they
+treat ‘3.14’ like ‘3,14’ if the current locale uses comma as a decimal
+point.
+
+
+File: coreutils.info,  Node: Standards conformance,  Next: Multi-call invocation,  Prev: Floating point,  Up: Common options
+
+2.13 Standards conformance
+==========================
+
+In a few cases, the GNU utilities’ default behavior is incompatible with
+the POSIX standard.  To suppress these incompatibilities, define the
+‘POSIXLY_CORRECT’ environment variable.  Unless you are checking for
+POSIX conformance, you probably do not need to define ‘POSIXLY_CORRECT’.
+
+   Newer versions of POSIX are occasionally incompatible with older
+versions.  For example, older versions of POSIX required the command
+‘sort +1’ to sort based on the second and succeeding fields in each
+input line, but in POSIX 1003.1-2001 the same command is required to
+sort the file named ‘+1’, and you must instead use the command ‘sort -k
+2’ to get the field-based sort.  To complicate things further, POSIX
+1003.1-2008 allows an implementation to have either the old or the new
+behavior.
+
+   The GNU utilities normally conform to the version of POSIX that is
+standard for your system.  To cause them to conform to a different
+version of POSIX, define the ‘_POSIX2_VERSION’ environment variable to a
+value of the form YYYYMM specifying the year and month the standard was
+adopted.  Three values are currently supported for ‘_POSIX2_VERSION’:
+‘199209’ stands for POSIX 1003.2-1992, ‘200112’ stands for POSIX
+1003.1-2001, and ‘200809’ stands for POSIX 1003.1-2008.  For example, if
+you have a POSIX 1003.1-2001 system but are running software containing
+traditional usage like ‘sort +1’ or ‘tail +10’, you can work around the
+compatibility problems by setting ‘_POSIX2_VERSION=200809’ in your
+environment.
+
+
+File: coreutils.info,  Node: Multi-call invocation,  Prev: Standards conformance,  Up: Common options
+
+2.14 ‘coreutils’: Multi-call program
+====================================
+
+The ‘coreutils’ command invokes an individual utility, either implicitly
+selected by the last component of the name used to invoke ‘coreutils’,
+or explicitly with the ‘--coreutils-prog’ option.  Synopsis:
+
+     coreutils --coreutils-prog=PROGRAM ...
+
+   The ‘coreutils’ command is not installed by default, so portable
+scripts should not rely on its existence.
+
+
+File: coreutils.info,  Node: Output of entire files,  Next: Formatting file contents,  Prev: Common options,  Up: Top
+
+3 Output of entire files
+************************
+
+These commands read and write entire files, possibly transforming them
+in some way.
+
+* Menu:
+
+* cat invocation::              Concatenate and write files.
+* tac invocation::              Concatenate and write files in reverse.
+* nl invocation::               Number lines and write files.
+* od invocation::               Write files in octal or other formats.
+* base32 invocation::           Transform data into printable data.
+* base64 invocation::           Transform data into printable data.
+* basenc invocation::           Transform data into printable data.
+
+
+File: coreutils.info,  Node: cat invocation,  Next: tac invocation,  Up: Output of entire files
+
+3.1 ‘cat’: Concatenate and write files
+======================================
+
+‘cat’ copies each FILE (‘-’ means standard input), or standard input if
+none are given, to standard output.  Synopsis:
+
+     cat [OPTION] [FILE]...
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-A’
+‘--show-all’
+     Equivalent to ‘-vET’.
+
+‘-b’
+‘--number-nonblank’
+     Number all nonempty output lines, starting with 1.
+
+‘-e’
+     Equivalent to ‘-vE’.
+
+‘-E’
+‘--show-ends’
+     Display a ‘$’ after the end of each line.  The ‘\r\n’ combination
+     is shown as ‘^M$’.
+
+‘-n’
+‘--number’
+     Number all output lines, starting with 1.  This option is ignored
+     if ‘-b’ is in effect.
+
+‘-s’
+‘--squeeze-blank’
+     Suppress repeated adjacent blank lines; output just one empty line
+     instead of several.
+
+‘-t’
+     Equivalent to ‘-vT’.
+
+‘-T’
+‘--show-tabs’
+     Display TAB characters as ‘^I’.
+
+‘-u’
+     Ignored; for POSIX compatibility.
+
+‘-v’
+‘--show-nonprinting’
+     Display control characters except for LFD and TAB using ‘^’
+     notation and precede characters that have the high bit set with
+     ‘M-’.
+
+   On systems like MS-DOS that distinguish between text and binary
+files, ‘cat’ normally reads and writes in binary mode.  However, ‘cat’
+reads in text mode if one of the options ‘-bensAE’ is used or if ‘cat’
+is reading from standard input and standard input is a terminal.
+Similarly, ‘cat’ writes in text mode if one of the options ‘-bensAE’ is
+used or if standard output is a terminal.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Examples:
+
+     # Output f's contents, then standard input, then g's contents.
+     cat f - g
+
+     # Copy standard input to standard output.
+     cat
+
+
+File: coreutils.info,  Node: tac invocation,  Next: nl invocation,  Prev: cat invocation,  Up: Output of entire files
+
+3.2 ‘tac’: Concatenate and write files in reverse
+=================================================
+
+‘tac’ copies each FILE (‘-’ means standard input), or standard input if
+none are given, to standard output, reversing the records (lines by
+default) in each separately.  Synopsis:
+
+     tac [OPTION]... [FILE]...
+
+   “Records” are separated by instances of a string (newline by
+default).  By default, this separator string is attached to the end of
+the record that it follows in the file.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b’
+‘--before’
+     The separator is attached to the beginning of the record that it
+     precedes in the file.
+
+‘-r’
+‘--regex’
+     Treat the separator string as a regular expression.
+
+‘-s SEPARATOR’
+‘--separator=SEPARATOR’
+     Use SEPARATOR as the record separator, instead of newline.  Note an
+     empty SEPARATOR is treated as a zero byte.  I.e., input and output
+     items are delimited with ASCII NUL.
+
+   On systems like MS-DOS that distinguish between text and binary
+files, ‘tac’ reads and writes in binary mode.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Example:
+
+     # Reverse a file character by character.
+     tac -r -s 'x\|[^x]'
+
+
+File: coreutils.info,  Node: nl invocation,  Next: od invocation,  Prev: tac invocation,  Up: Output of entire files
+
+3.3 ‘nl’: Number lines and write files
+======================================
+
+‘nl’ writes each FILE (‘-’ means standard input), or standard input if
+none are given, to standard output, with line numbers added to some or
+all of the lines.  Synopsis:
+
+     nl [OPTION]... [FILE]...
+
+   ‘nl’ decomposes its input into (logical) page sections; by default,
+the line number is reset to 1 at each logical page section.  ‘nl’ treats
+all of the input files as a single document; it does not reset line
+numbers or logical pages between files.
+
+   A logical page consists of three sections: header, body, and footer.
+Any of the sections can be empty.  Each can be numbered in a different
+style from the others.
+
+   The beginnings of the sections of logical pages are indicated in the
+input file by a line containing exactly one of these delimiter strings:
+
+‘\:\:\:’
+     start of header;
+‘\:\:’
+     start of body;
+‘\:’
+     start of footer.
+
+   The characters from which these strings are made can be changed from
+‘\’ and ‘:’ via options (see below), but the pattern of each string
+cannot be changed.
+
+   A section delimiter is replaced by an empty line on output.  Any text
+that comes before the first section delimiter string in the input file
+is considered to be part of a body section, so ‘nl’ treats a file that
+contains no section delimiters as a single body section.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b STYLE’
+‘--body-numbering=STYLE’
+     Select the numbering style for lines in the body section of each
+     logical page.  When a line is not numbered, the current line number
+     is not incremented, but the line number separator character is
+     still prepended to the line.  The styles are:
+
+     ‘a’
+          number all lines,
+     ‘t’
+          number only nonempty lines (default for body),
+     ‘n’
+          do not number lines (default for header and footer),
+     ‘pBRE’
+          number only lines that contain a match for the basic regular
+          expression BRE.  *Note Regular Expressions: (grep)Regular
+          Expressions.
+
+‘-d CD’
+‘--section-delimiter=CD’
+     Set the section delimiter characters to CD; default is ‘\:’.  If
+     only C is given, the second remains ‘:’.  As a GNU extension more
+     than two characters can be specified, and also if CD is empty (‘-d
+     ''’), then section matching is disabled.  (Remember to protect ‘\’
+     or other metacharacters from shell expansion with quotes or extra
+     backslashes.)
+
+‘-f STYLE’
+‘--footer-numbering=STYLE’
+     Analogous to ‘--body-numbering’.
+
+‘-h STYLE’
+‘--header-numbering=STYLE’
+     Analogous to ‘--body-numbering’.
+
+‘-i NUMBER’
+‘--line-increment=NUMBER’
+     Increment line numbers by NUMBER (default 1).  NUMBER can be
+     negative to decrement.
+
+‘-l NUMBER’
+‘--join-blank-lines=NUMBER’
+     Consider NUMBER (default 1) consecutive empty lines to be one
+     logical line for numbering, and only number the last one.  Where
+     fewer than NUMBER consecutive empty lines occur, do not number
+     them.  An empty line is one that contains no characters, not even
+     spaces or tabs.
+
+‘-n FORMAT’
+‘--number-format=FORMAT’
+     Select the line numbering format (default is ‘rn’):
+
+     ‘ln’
+          left justified, no leading zeros;
+     ‘rn’
+          right justified, no leading zeros;
+     ‘rz’
+          right justified, leading zeros.
+
+‘-p’
+‘--no-renumber’
+     Do not reset the line number at the start of a logical page.
+
+‘-s STRING’
+‘--number-separator=STRING’
+     Separate the line number from the text line in the output with
+     STRING (default is the TAB character).
+
+‘-v NUMBER’
+‘--starting-line-number=NUMBER’
+     Set the initial line number on each logical page to NUMBER (default
+     1).  The starting NUMBER can be negative.
+
+‘-w NUMBER’
+‘--number-width=NUMBER’
+     Use NUMBER characters for line numbers (default 6).
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: od invocation,  Next: base32 invocation,  Prev: nl invocation,  Up: Output of entire files
+
+3.4 ‘od’: Write files in octal or other formats
+===============================================
+
+‘od’ writes an unambiguous representation of each FILE (‘-’ means
+standard input), or standard input if none are given.  Synopses:
+
+     od [OPTION]... [FILE]...
+     od [-abcdfilosx]... [FILE] [[+]OFFSET[.][b]]
+     od [OPTION]... --traditional [FILE] [[+]OFFSET[.][b] [[+]LABEL[.][b]]]
+
+   Each line of output consists of the offset in the input, followed by
+groups of data from the file.  By default, ‘od’ prints the offset in
+octal, and each group of file data is a C ‘short int’’s worth of input
+printed as a single octal number.
+
+   If OFFSET is given, it specifies how many input bytes to skip before
+formatting and writing.  By default, it is interpreted as an octal
+number, but the optional trailing decimal point causes it to be
+interpreted as decimal.  If no decimal is specified and the offset
+begins with ‘0x’ or ‘0X’ it is interpreted as a hexadecimal number.  If
+there is a trailing ‘b’, the number of bytes skipped will be OFFSET
+multiplied by 512.
+
+   If a command is of both the first and second forms, the second form
+is assumed if the last operand begins with ‘+’ or (if there are two
+operands) a digit.  For example, in ‘od foo 10’ and ‘od +10’ the ‘10’ is
+an offset, whereas in ‘od 10’ the ‘10’ is a file name.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-A RADIX’
+‘--address-radix=RADIX’
+     Select the base in which file offsets are printed.  RADIX can be
+     one of the following:
+
+     ‘d’
+          decimal;
+     ‘o’
+          octal;
+     ‘x’
+          hexadecimal;
+     ‘n’
+          none (do not print offsets).
+
+     The default is octal.
+
+‘--endian=ORDER’
+     Reorder input bytes, to handle inputs with differing byte orders,
+     or to provide consistent output independent of the endian
+     convention of the current system.  Swapping is performed according
+     to the specified ‘--type’ size and endian ORDER, which can be
+     ‘little’ or ‘big’.
+
+‘-j BYTES’
+‘--skip-bytes=BYTES’
+     Skip BYTES input bytes before formatting and writing.  If BYTES
+     begins with ‘0x’ or ‘0X’, it is interpreted in hexadecimal;
+     otherwise, if it begins with ‘0’, in octal; otherwise, in decimal.
+     BYTES may be, or may be an integer optionally followed by, one of
+     the following multiplicative suffixes:
+          ‘b’  =>            512 ("blocks")
+          ‘KB’ =>           1000 (KiloBytes)
+          ‘K’  =>           1024 (KibiBytes)
+          ‘MB’ =>      1000*1000 (MegaBytes)
+          ‘M’  =>      1024*1024 (MebiBytes)
+          ‘GB’ => 1000*1000*1000 (GigaBytes)
+          ‘G’  => 1024*1024*1024 (GibiBytes)
+     and so on for ‘T’, ‘P’, ‘E’, ‘Z’, ‘Y’, ‘R’, and ‘Q’.  Binary
+     prefixes can be used, too: ‘KiB’=‘K’, ‘MiB’=‘M’, and so on.
+
+‘-N BYTES’
+‘--read-bytes=BYTES’
+     Output at most BYTES bytes of the input.  Prefixes and suffixes on
+     ‘bytes’ are interpreted as for the ‘-j’ option.
+
+‘-S BYTES’
+‘--strings[=BYTES]’
+     Instead of the normal output, output only “string constants”: at
+     least BYTES consecutive printable characters, followed by a zero
+     byte (ASCII NUL). Prefixes and suffixes on BYTES are interpreted as
+     for the ‘-j’ option.
+
+     If BYTES is omitted with ‘--strings’, the default is 3.
+
+‘-t TYPE’
+‘--format=TYPE’
+     Select the format in which to output the file data.  TYPE is a
+     string of one or more of the below type indicator characters.  If
+     you include more than one type indicator character in a single TYPE
+     string, or use this option more than once, ‘od’ writes one copy of
+     each output line using each of the data types that you specified,
+     in the order that you specified.
+
+     Adding a trailing “z” to any type specification appends a display
+     of the single byte character representation of the printable
+     characters to the output line generated by the type specification.
+
+     ‘a’
+          named character, ignoring high-order bit
+     ‘c’
+          printable single byte character, C backslash escape or a 3
+          digit octal sequence
+     ‘d’
+          signed decimal
+     ‘f’
+          floating point (*note Floating point::)
+     ‘o’
+          octal
+     ‘u’
+          unsigned decimal
+     ‘x’
+          hexadecimal
+
+     The type ‘a’ outputs things like ‘sp’ for space, ‘nl’ for newline,
+     and ‘nul’ for a zero byte.  Only the least significant seven bits
+     of each byte is used; the high-order bit is ignored.  Type ‘c’
+     outputs ‘ ’, ‘\n’, and ‘\0’, respectively.
+
+     Except for types ‘a’ and ‘c’, you can specify the number of bytes
+     to use in interpreting each number in the given data type by
+     following the type indicator character with a decimal integer.
+     Alternately, you can specify the size of one of the C compiler’s
+     built-in data types by following the type indicator character with
+     one of the following characters.  For integers (‘d’, ‘o’, ‘u’,
+     ‘x’):
+
+     ‘C’
+          char
+     ‘S’
+          short
+     ‘I’
+          int
+     ‘L’
+          long
+
+     For floating point (‘f’):
+
+     F
+          float
+     D
+          double
+     L
+          long double
+
+‘-v’
+‘--output-duplicates’
+     Output consecutive lines that are identical.  By default, when two
+     or more consecutive output lines would be identical, ‘od’ outputs
+     only the first line, and puts just an asterisk on the following
+     line to indicate the elision.
+
+‘-w[N]’
+‘--width[=N]’
+     Dump ‘n’ input bytes per output line.  This must be a multiple of
+     the least common multiple of the sizes associated with the
+     specified output types.
+
+     If this option is not given at all, the default is 16.  If N is
+     omitted, the default is 32.
+
+   The next several options are shorthands for format specifications.
+GNU ‘od’ accepts any combination of shorthands and format specification
+options.  These options accumulate.
+
+‘-a’
+     Output as named characters.  Equivalent to ‘-t a’.
+
+‘-b’
+     Output as octal bytes.  Equivalent to ‘-t o1’.
+
+‘-c’
+     Output as printable single byte characters, C backslash escapes or
+     3 digit octal sequences.  Equivalent to ‘-t c’.
+
+‘-d’
+     Output as unsigned decimal two-byte units.  Equivalent to ‘-t u2’.
+
+‘-f’
+     Output as floats.  Equivalent to ‘-t fF’.
+
+‘-i’
+     Output as decimal ints.  Equivalent to ‘-t dI’.
+
+‘-l’
+     Output as decimal long ints.  Equivalent to ‘-t dL’.
+
+‘-o’
+     Output as octal two-byte units.  Equivalent to ‘-t o2’.
+
+‘-s’
+     Output as decimal two-byte units.  Equivalent to ‘-t d2’.
+
+‘-x’
+     Output as hexadecimal two-byte units.  Equivalent to ‘-t x2’.
+
+‘--traditional’
+     Recognize the non-option label argument that traditional ‘od’
+     accepted.  The following syntax:
+
+          od --traditional [FILE] [[+]OFFSET[.][b] [[+]LABEL[.][b]]]
+
+     can be used to specify at most one file and optional arguments
+     specifying an offset and a pseudo-start address, LABEL.  The LABEL
+     argument is interpreted just like OFFSET, but it specifies an
+     initial pseudo-address.  The pseudo-addresses are displayed in
+     parentheses following any normal address.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: base32 invocation,  Next: base64 invocation,  Prev: od invocation,  Up: Output of entire files
+
+3.5 ‘base32’: Transform data into printable data
+================================================
+
+‘base32’ transforms data read from a file, or standard input, into (or
+from) base32 encoded form.  The base32 encoded form uses printable ASCII
+characters to represent binary data.  The usage and options of this
+command are precisely the same as for ‘base64’.  *Note base64
+invocation::.  For more general encoding functionality see *note basenc
+invocation::.
+
+
+File: coreutils.info,  Node: base64 invocation,  Next: basenc invocation,  Prev: base32 invocation,  Up: Output of entire files
+
+3.6 ‘base64’: Transform data into printable data
+================================================
+
+‘base64’ transforms data read from a file, or standard input, into (or
+from) base64 encoded form.  The base64 encoded form uses printable ASCII
+characters to represent binary data.  Synopses:
+
+     base64 [OPTION]... [FILE]
+     base64 --decode [OPTION]... [FILE]
+
+   The base64 encoding expands data to roughly 133% of the original.
+The base32 encoding expands data to roughly 160% of the original.  The
+format conforms to RFC 4648 (https://tools.ietf.org/search/rfc4648).
+
+   For more general encoding functionality see *note basenc
+invocation::.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-w COLS’
+‘--wrap=COLS’
+     During encoding, wrap lines after COLS characters.  This must be a
+     positive number.
+
+     The default is to wrap after 76 characters.  Use the value 0 to
+     disable line wrapping altogether.
+
+‘-d’
+‘--decode’
+     Change the mode of operation, from the default of encoding data, to
+     decoding data.  Input is expected to be base64 encoded data, and
+     the output will be the original data.
+
+‘-i’
+‘--ignore-garbage’
+     When decoding, newlines are always accepted.  During decoding,
+     ignore unrecognized bytes, to permit distorted data to be decoded.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: basenc invocation,  Prev: base64 invocation,  Up: Output of entire files
+
+3.7 ‘basenc’: Transform data into printable data
+================================================
+
+‘basenc’ transforms data read from a file, or standard input, into (or
+from) various common encoding forms.  The encoded form uses printable
+ASCII characters to represent binary data.
+
+   Synopses:
+
+     basenc ENCODING [OPTION]... [FILE]
+     basenc ENCODING --decode [OPTION]... [FILE]
+
+   The ENCODING argument is required.  If FILE is omitted, ‘basenc’
+reads from standard input.  The ‘-w/--wrap’,‘-i/--ignore-garbage’,
+‘-d/--decode’ options of this command are precisely the same as for
+‘base64’.  *Note base64 invocation::.
+
+   Supported ENCODINGs are:
+
+‘--base64’
+     Encode into (or decode from with ‘-d/--decode’) base64 form.  The
+     format conforms to RFC 4648#4
+     (https://tools.ietf.org/search/rfc4648#section-4).  Equivalent to
+     the ‘base64’ command.
+
+‘--base64url’
+     Encode into (or decode from with ‘-d/--decode’) file-and-url-safe
+     base64 form (using ‘_’ and ‘-’ instead of ‘+’ and ‘/’).  The format
+     conforms to RFC 4648#5
+     (https://tools.ietf.org/search/rfc4648#section-5).
+
+‘--base32’
+     Encode into (or decode from with ‘-d/--decode’) base32 form.  The
+     encoded data uses the ‘ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=’
+     characters.  The format conforms to RFC 4648#6
+     (https://tools.ietf.org/search/rfc4648#section-6).  Equivalent to
+     the ‘base32’ command.
+
+‘--base32hex’
+     Encode into (or decode from with ‘-d/--decode’) Extended Hex
+     Alphabet base32 form.  The encoded data uses the
+     ‘0123456789ABCDEFGHIJKLMNOPQRSTUV=’ characters.  The format
+     conforms to RFC 4648#7
+     (https://tools.ietf.org/search/rfc4648#section-7).
+
+‘--base16’
+     Encode into (or decode from with ‘-d/--decode’) base16
+     (hexadecimal) form.  The encoded data uses the ‘0123456789ABCDEF’
+     characters.  The format conforms to RFC 4648#8
+     (https://tools.ietf.org/search/rfc4648#section-8).
+
+‘--base2lsbf’
+     Encode into (or decode from with ‘-d/--decode’) binary string form
+     (‘0’ and ‘1’) with the _least_ significant bit of every byte first.
+
+‘--base2msbf’
+     Encode into (or decode from with ‘-d/--decode’) binary string form
+     (‘0’ and ‘1’) with the _most_ significant bit of every byte first.
+
+‘--z85’
+     Encode into (or decode from with ‘-d/--decode’) Z85 form (a
+     modified Ascii85 form).  The encoded data uses the
+     ‘0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU VWXYZ.-:+=^!/*?&<>()[]{}@%$#’.
+     characters.  The format conforms to ZeroMQ spec:32/Z85
+     (https://rfc.zeromq.org/spec:32/Z85/).
+
+     When encoding with ‘--z85’, input length must be a multiple of 4;
+     when decoding with ‘--z85’, input length must be a multiple of 5.
+
+   Encoding/decoding examples:
+
+     $ printf '\376\117\202' | basenc --base64
+     /k+C
+
+     $ printf '\376\117\202' | basenc --base64url
+     _k-C
+
+     $ printf '\376\117\202' | basenc --base32
+     7ZHYE===
+
+     $ printf '\376\117\202' | basenc --base32hex
+     VP7O4===
+
+     $ printf '\376\117\202' | basenc --base16
+     FE4F82
+
+     $ printf '\376\117\202' | basenc --base2lsbf
+     011111111111001001000001
+
+     $ printf '\376\117\202' | basenc --base2msbf
+     111111100100111110000010
+
+     $ printf '\376\117\202\000' | basenc --z85
+     @.FaC
+
+     $ printf 01010100 | basenc --base2msbf --decode
+     T
+
+     $ printf 01010100 | basenc --base2lsbf --decode
+     *
+
+
+File: coreutils.info,  Node: Formatting file contents,  Next: Output of parts of files,  Prev: Output of entire files,  Up: Top
+
+4 Formatting file contents
+**************************
+
+These commands reformat the contents of files.
+
+* Menu:
+
+* fmt invocation::              Reformat paragraph text.
+* pr invocation::               Paginate or columnate files for printing.
+* fold invocation::             Wrap input lines to fit in specified width.
+
+
+File: coreutils.info,  Node: fmt invocation,  Next: pr invocation,  Up: Formatting file contents
+
+4.1 ‘fmt’: Reformat paragraph text
+==================================
+
+‘fmt’ fills and joins lines to produce output lines of (at most) a given
+number of characters (75 by default).  Synopsis:
+
+     fmt [OPTION]... [FILE]...
+
+   ‘fmt’ reads from the specified FILE arguments (or standard input if
+none are given), and writes to standard output.
+
+   By default, blank lines, spaces between words, and indentation are
+preserved in the output; successive input lines with different
+indentation are not joined; tabs are expanded on input and introduced on
+output.
+
+   ‘fmt’ prefers breaking lines at the end of a sentence, and tries to
+avoid line breaks after the first word of a sentence or before the last
+word of a sentence.  A “sentence break” is defined as either the end of
+a paragraph or a word ending in any of ‘.?!’, followed by two spaces or
+end of line, ignoring any intervening parentheses or quotes.  Like TeX,
+‘fmt’ reads entire “paragraphs” before choosing line breaks; the
+algorithm is a variant of that given by Donald E. Knuth and Michael F.
+Plass in “Breaking Paragraphs Into Lines”, ‘Software: Practice &
+Experience’ 11, 11 (November 1981), 1119–1184.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c’
+‘--crown-margin’
+     “Crown margin” mode: preserve the indentation of the first two
+     lines within a paragraph, and align the left margin of each
+     subsequent line with that of the second line.
+
+‘-t’
+‘--tagged-paragraph’
+     “Tagged paragraph” mode: like crown margin mode, except that if
+     indentation of the first line of a paragraph is the same as the
+     indentation of the second, the first line is treated as a one-line
+     paragraph.
+
+‘-s’
+‘--split-only’
+     Split lines only.  Do not join short lines to form longer ones.
+     This prevents sample lines of code, and other such “formatted” text
+     from being unduly combined.
+
+‘-u’
+‘--uniform-spacing’
+     Uniform spacing.  Reduce spacing between words to one space, and
+     spacing between sentences to two spaces.
+
+‘-WIDTH’
+‘-w WIDTH’
+‘--width=WIDTH’
+     Fill output lines up to WIDTH characters (default 75 or GOAL plus
+     10, if GOAL is provided).
+
+‘-g GOAL’
+‘--goal=GOAL’
+     ‘fmt’ initially tries to make lines GOAL characters wide.  By
+     default, this is 7% shorter than WIDTH.
+
+‘-p PREFIX’
+‘--prefix=PREFIX’
+     Only lines beginning with PREFIX (possibly preceded by whitespace)
+     are subject to formatting.  The prefix and any preceding whitespace
+     are stripped for the formatting and then re-attached to each
+     formatted output line.  One use is to format certain kinds of
+     program comments, while leaving the code unchanged.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: pr invocation,  Next: fold invocation,  Prev: fmt invocation,  Up: Formatting file contents
+
+4.2 ‘pr’: Paginate or columnate files for printing
+==================================================
+
+‘pr’ writes each FILE (‘-’ means standard input), or standard input if
+none are given, to standard output, paginating and optionally outputting
+in multicolumn format; optionally merges all FILEs, printing all in
+parallel, one per column.  Synopsis:
+
+     pr [OPTION]... [FILE]...
+
+   By default, a 5-line header is printed at each page: two blank lines;
+a line with the date, the file name, and the page count; and two more
+blank lines.  A footer of five blank lines is also printed.  The default
+PAGE_LENGTH is 66 lines.  The default number of text lines is therefore
+56.  The text line of the header takes the form ‘DATE STRING PAGE’, with
+spaces inserted around STRING so that the line takes up the full
+PAGE_WIDTH.  Here, DATE is the date (see the ‘-D’ or ‘--date-format’
+option for details), STRING is the centered header string, and PAGE
+identifies the page number.  The ‘LC_MESSAGES’ locale category affects
+the spelling of PAGE; in the default C locale, it is ‘Page NUMBER’ where
+NUMBER is the decimal page number.
+
+   Form feeds in the input cause page breaks in the output.  Multiple
+form feeds produce empty pages.
+
+   Columns are of equal width, separated by an optional string (default
+is ‘space’).  For multicolumn output, lines will always be truncated to
+PAGE_WIDTH (default 72), unless you use the ‘-J’ option.  For single
+column output no line truncation occurs by default.  Use ‘-W’ option to
+truncate lines in that case.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘+FIRST_PAGE[:LAST_PAGE]’
+‘--pages=FIRST_PAGE[:LAST_PAGE]’
+     Begin printing with page FIRST_PAGE and stop with LAST_PAGE.
+     Missing ‘:LAST_PAGE’ implies end of file.  While estimating the
+     number of skipped pages each form feed in the input file results in
+     a new page.  Page counting with and without ‘+FIRST_PAGE’ is
+     identical.  By default, counting starts with the first page of
+     input file (not first page printed).  Line numbering may be altered
+     by ‘-N’ option.
+
+‘-COLUMN’
+‘--columns=COLUMN’
+     With each single FILE, produce COLUMN columns of output (default is
+     1) and print columns down, unless ‘-a’ is used.  The column width
+     is automatically decreased as COLUMN increases; unless you use the
+     ‘-W/-w’ option to increase PAGE_WIDTH as well.  This option might
+     well cause some lines to be truncated.  The number of lines in the
+     columns on each page are balanced.  The options ‘-e’ and ‘-i’ are
+     on for multiple text-column output.  Together with ‘-J’ option
+     column alignment and line truncation is turned off.  Lines of full
+     length are joined in a free field format and ‘-S’ option may set
+     field separators.  ‘-COLUMN’ may not be used with ‘-m’ option.
+
+‘-a’
+‘--across’
+     With each single FILE, print columns across rather than down.  The
+     ‘-COLUMN’ option must be given with COLUMN greater than one.  If a
+     line is too long to fit in a column, it is truncated.
+
+‘-c’
+‘--show-control-chars’
+     Print control characters using hat notation (e.g., ‘^G’); print
+     other nonprinting characters in octal backslash notation.  By
+     default, nonprinting characters are not changed.
+
+‘-d’
+‘--double-space’
+     Double space the output.
+
+‘-D FORMAT’
+‘--date-format=FORMAT’
+     Format header dates using FORMAT, using the same conventions as for
+     the command ‘date +FORMAT’.  *Note date invocation::.  Except for
+     directives, which start with ‘%’, characters in FORMAT are printed
+     unchanged.  You can use this option to specify an arbitrary string
+     in place of the header date, e.g., ‘--date-format="Monday
+     morning"’.
+
+     The default date format is ‘%Y-%m-%d %H:%M’ (for example,
+     ‘2020-07-09 23:59’); but if the ‘POSIXLY_CORRECT’ environment
+     variable is set and the ‘LC_TIME’ locale category specifies the
+     POSIX locale, the default is ‘%b %e %H:%M %Y’ (for example, ‘Jul  9
+     23:59 2020’.
+
+     Timestamps are listed according to the time zone rules specified by
+     the ‘TZ’ environment variable, or by the system default rules if
+     ‘TZ’ is not set.  *Note Specifying the Time Zone with ‘TZ’:
+     (libc)TZ Variable.
+
+‘-e[IN-TABCHAR[IN-TABWIDTH]]’
+‘--expand-tabs[=IN-TABCHAR[IN-TABWIDTH]]’
+     Expand TABs to spaces on input.  Optional argument IN-TABCHAR is
+     the input tab character (default is the TAB character).  Second
+     optional argument IN-TABWIDTH is the input tab character’s width
+     (default is 8).
+
+‘-f’
+‘-F’
+‘--form-feed’
+     Use a form feed instead of newlines to separate output pages.  This
+     does not alter the default page length of 66 lines.
+
+‘-h HEADER’
+‘--header=HEADER’
+     Replace the file name in the header with the centered string
+     HEADER.  When using the shell, HEADER should be quoted and should
+     be separated from ‘-h’ by a space.
+
+‘-i[OUT-TABCHAR[OUT-TABWIDTH]]’
+‘--output-tabs[=OUT-TABCHAR[OUT-TABWIDTH]]’
+     Replace spaces with TABs on output.  Optional argument OUT-TABCHAR
+     is the output tab character (default is the TAB character).  Second
+     optional argument OUT-TABWIDTH is the output tab character’s width
+     (default is 8).
+
+‘-J’
+‘--join-lines’
+     Merge lines of full length.  Used together with the column options
+     ‘-COLUMN’, ‘-a -COLUMN’ or ‘-m’.  Turns off ‘-W/-w’ line
+     truncation; no column alignment used; may be used with
+     ‘--sep-string[=STRING]’.  ‘-J’ has been introduced (together with
+     ‘-W’ and ‘--sep-string’) to disentangle the old (POSIX-compliant)
+     options ‘-w’ and ‘-s’ along with the three column options.
+
+‘-l PAGE_LENGTH’
+‘--length=PAGE_LENGTH’
+     Set the page length to PAGE_LENGTH (default 66) lines, including
+     the lines of the header [and the footer].  If PAGE_LENGTH is less
+     than or equal to 10, the header and footer are omitted, as if the
+     ‘-t’ option had been given.
+
+‘-m’
+‘--merge’
+     Merge and print all FILEs in parallel, one in each column.  If a
+     line is too long to fit in a column, it is truncated, unless the
+     ‘-J’ option is used.  ‘--sep-string[=STRING]’ may be used.  Empty
+     pages in some FILEs (form feeds set) produce empty columns, still
+     marked by STRING.  The result is a continuous line numbering and
+     column marking throughout the whole merged file.  Completely empty
+     merged pages show no separators or line numbers.  The default
+     header becomes ‘DATE PAGE’ with spaces inserted in the middle; this
+     may be used with the ‘-h’ or ‘--header’ option to fill up the
+     middle blank part.
+
+‘-n[NUMBER-SEPARATOR[DIGITS]]’
+‘--number-lines[=NUMBER-SEPARATOR[DIGITS]]’
+     Provide DIGITS digit line numbering (default for DIGITS is 5).
+     With multicolumn output the number occupies the first DIGITS column
+     positions of each text column or only each line of ‘-m’ output.
+     With single column output the number precedes each line just as
+     ‘-m’ does.  Default counting of the line numbers starts with the
+     first line of the input file (not the first line printed, compare
+     the ‘--page’ option and ‘-N’ option).  Optional argument
+     NUMBER-SEPARATOR is the character appended to the line number to
+     separate it from the text followed.  The default separator is the
+     TAB character.  In a strict sense a TAB is always printed with
+     single column output only.  The TAB width varies with the TAB
+     position, e.g., with the left MARGIN specified by ‘-o’ option.
+     With multicolumn output priority is given to ‘equal width of output
+     columns’ (a POSIX specification).  The TAB width is fixed to the
+     value of the first column and does not change with different values
+     of left MARGIN.  That means a fixed number of spaces is always
+     printed in the place of the NUMBER-SEPARATOR TAB.  The tabification
+     depends upon the output position.
+
+‘-N LINE_NUMBER’
+‘--first-line-number=LINE_NUMBER’
+     Start line counting with the number LINE_NUMBER at first line of
+     first page printed (in most cases not the first line of the input
+     file).
+
+‘-o MARGIN’
+‘--indent=MARGIN’
+     Indent each line with a margin MARGIN spaces wide (default is
+     zero).  The total page width is the size of the margin plus the
+     PAGE_WIDTH set with the ‘-W/-w’ option.  A limited overflow may
+     occur with numbered single column output (compare ‘-n’ option).
+
+‘-r’
+‘--no-file-warnings’
+     Do not print a warning message when an argument FILE cannot be
+     opened.  (The exit status will still be nonzero, however.)
+
+‘-s[CHAR]’
+‘--separator[=CHAR]’
+     Separate columns by a single character CHAR.  The default for CHAR
+     is the TAB character without ‘-w’ and ‘no character’ with ‘-w’.
+     Without ‘-s’ the default separator ‘space’ is set.  ‘-s[char]’
+     turns off line truncation of all three column options
+     (‘-COLUMN’|‘-a -COLUMN’|‘-m’) unless ‘-w’ is set.  This is a
+     POSIX-compliant formulation.
+
+‘-S[STRING]’
+‘--sep-string[=STRING]’
+     Use STRING to separate output columns.  The ‘-S’ option doesn’t
+     affect the ‘-W/-w’ option, unlike the ‘-s’ option which does.  It
+     does not affect line truncation or column alignment.  Without ‘-S’,
+     and with ‘-J’, ‘pr’ uses the default output separator, TAB.
+     Without ‘-S’ or ‘-J’, ‘pr’ uses a ‘space’ (same as ‘-S" "’).  If no
+     ‘STRING’ argument is specified, ‘""’ is assumed.
+
+‘-t’
+‘--omit-header’
+     Do not print the usual header [and footer] on each page, and do not
+     fill out the bottom of pages (with blank lines or a form feed).  No
+     page structure is produced, but form feeds set in the input files
+     are retained.  The predefined pagination is not changed.  ‘-t’ or
+     ‘-T’ may be useful together with other options; e.g.: ‘-t -e4’,
+     expand TAB characters in the input file to 4 spaces but don’t make
+     any other changes.  Use of ‘-t’ overrides ‘-h’.
+
+‘-T’
+‘--omit-pagination’
+     Do not print header [and footer].  In addition eliminate all form
+     feeds set in the input files.
+
+‘-v’
+‘--show-nonprinting’
+     Print nonprinting characters in octal backslash notation.
+
+‘-w PAGE_WIDTH’
+‘--width=PAGE_WIDTH’
+     Set page width to PAGE_WIDTH characters for multiple text-column
+     output only (default for PAGE_WIDTH is 72).  The specified
+     PAGE_WIDTH is rounded down so that columns have equal width.
+     ‘-s[CHAR]’ turns off the default page width and any line truncation
+     and column alignment.  Lines of full length are merged, regardless
+     of the column options set.  No PAGE_WIDTH setting is possible with
+     single column output.  A POSIX-compliant formulation.
+
+‘-W PAGE_WIDTH’
+‘--page_width=PAGE_WIDTH’
+     Set the page width to PAGE_WIDTH characters, honored with and
+     without a column option.  With a column option, the specified
+     PAGE_WIDTH is rounded down so that columns have equal width.  Text
+     lines are truncated, unless ‘-J’ is used.  Together with one of the
+     three column options (‘-COLUMN’, ‘-a -COLUMN’ or ‘-m’) column
+     alignment is always used.  The separator options ‘-S’ or ‘-s’ don’t
+     disable the ‘-W’ option.  Default is 72 characters.  Without ‘-W
+     PAGE_WIDTH’ and without any of the column options NO line
+     truncation is used (defined to keep downward compatibility and to
+     meet most frequent tasks).  That’s equivalent to ‘-W 72 -J’.  The
+     header line is never truncated.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: fold invocation,  Prev: pr invocation,  Up: Formatting file contents
+
+4.3 ‘fold’: Wrap input lines to fit in specified width
+======================================================
+
+‘fold’ writes each FILE (‘-’ means standard input), or standard input if
+none are given, to standard output, breaking long lines.  Synopsis:
+
+     fold [OPTION]... [FILE]...
+
+   By default, ‘fold’ breaks lines wider than 80 columns.  The output is
+split into as many lines as necessary.
+
+   ‘fold’ counts screen columns by default; thus, a tab may count more
+than one column, backspace decreases the column count, and carriage
+return sets the column to zero.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b’
+‘--bytes’
+     Count bytes rather than columns, so that tabs, backspaces, and
+     carriage returns are each counted as taking up one column, just
+     like other characters.
+
+‘-s’
+‘--spaces’
+     Break at word boundaries: the line is broken after the last blank
+     before the maximum line length.  If the line contains no such
+     blanks, the line is broken at the maximum line length as usual.
+
+‘-w WIDTH’
+‘--width=WIDTH’
+     Use a maximum line length of WIDTH columns instead of 80.
+
+     For compatibility ‘fold’ supports an obsolete option syntax
+     ‘-WIDTH’.  New scripts should use ‘-w WIDTH’ instead.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Output of parts of files,  Next: Summarizing files,  Prev: Formatting file contents,  Up: Top
+
+5 Output of parts of files
+**************************
+
+These commands output pieces of the input.
+
+* Menu:
+
+* head invocation::             Output the first part of files.
+* tail invocation::             Output the last part of files.
+* split invocation::            Split a file into pieces.
+* csplit invocation::           Split a file into context-determined pieces.
+
+
+File: coreutils.info,  Node: head invocation,  Next: tail invocation,  Up: Output of parts of files
+
+5.1 ‘head’: Output the first part of files
+==========================================
+
+‘head’ prints the first part (10 lines by default) of each FILE; it
+reads from standard input if no files are given or when given a FILE of
+‘-’.  Synopsis:
+
+     head [OPTION]... [FILE]...
+
+   If more than one FILE is specified, ‘head’ prints a one-line header
+consisting of:
+
+     ==> FILE NAME <==
+
+before the output for each FILE.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c [-]NUM’
+‘--bytes=[-]NUM’
+     Print the first NUM bytes, instead of initial lines.  However, if
+     NUM is prefixed with a ‘-’, print all but the last NUM bytes of
+     each file.  NUM may be, or may be an integer optionally followed
+     by, one of the following multiplicative suffixes:
+          ‘b’  =>            512 ("blocks")
+          ‘KB’ =>           1000 (KiloBytes)
+          ‘K’  =>           1024 (KibiBytes)
+          ‘MB’ =>      1000*1000 (MegaBytes)
+          ‘M’  =>      1024*1024 (MebiBytes)
+          ‘GB’ => 1000*1000*1000 (GigaBytes)
+          ‘G’  => 1024*1024*1024 (GibiBytes)
+     and so on for ‘T’, ‘P’, ‘E’, ‘Z’, ‘Y’, ‘R’, and ‘Q’.  Binary
+     prefixes can be used, too: ‘KiB’=‘K’, ‘MiB’=‘M’, and so on.
+
+‘-n [-]NUM’
+‘--lines=[-]NUM’
+     Output the first NUM lines.  However, if NUM is prefixed with a
+     ‘-’, print all but the last NUM lines of each file.  Size
+     multiplier suffixes are the same as with the ‘-c’ option.
+
+‘-q’
+‘--quiet’
+‘--silent’
+     Never print file name headers.
+
+‘-v’
+‘--verbose’
+     Always print file name headers.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).
+
+   For compatibility ‘head’ also supports an obsolete option syntax
+‘-[NUM][bkm][cqv]’, which is recognized only if it is specified first.
+NUM is a decimal number optionally followed by a size letter (‘b’, ‘k’,
+‘m’) as in ‘-c’, or ‘l’ to mean count by lines, or other option letters
+(‘cqv’).  Scripts intended for standard hosts should use ‘-c NUM’ or ‘-n
+NUM’ instead.  If your script must also run on hosts that support only
+the obsolete syntax, it is usually simpler to avoid ‘head’, e.g., by
+using ‘sed 5q’ instead of ‘head -5’.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: tail invocation,  Next: split invocation,  Prev: head invocation,  Up: Output of parts of files
+
+5.2 ‘tail’: Output the last part of files
+=========================================
+
+‘tail’ prints the last part (10 lines by default) of each FILE; it reads
+from standard input if no files are given or when given a FILE of ‘-’.
+Synopsis:
+
+     tail [OPTION]... [FILE]...
+
+   If more than one FILE is specified, ‘tail’ prints a one-line header
+before the output for each FILE, consisting of:
+
+     ==> FILE NAME <==
+
+   For further processing of tail output, it can be useful to convert
+the file headers to line prefixes, which can be done like:
+
+     tail ... |
+     awk '
+       /^==> .* <==$/ {prefix=substr($0,5,length-8)":"; next}
+       {print prefix$0}
+     ' | ...
+
+   GNU ‘tail’ can output any amount of data (some other versions of
+‘tail’ cannot).  It also has no ‘-r’ option (print in reverse), since
+reversing a file is really a different job from printing the end of a
+file; BSD ‘tail’ (which is the one with ‘-r’) can only reverse files
+that are at most as large as its buffer, which is typically 32 KiB.  A
+more reliable and versatile way to reverse files is the GNU ‘tac’
+command.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c [+]NUM’
+‘--bytes=[+]NUM’
+     Output the last NUM bytes, instead of final lines.  If NUM is
+     prefixed with a ‘+’, start printing with byte NUM from the start of
+     each file.  For example to skip the first byte use ‘tail -c +2’,
+     while to skip all but the last byte use ‘tail -c 1’.  NUM may be,
+     or may be an integer optionally followed by, one of the following
+     multiplicative suffixes:
+          ‘b’  =>            512 ("blocks")
+          ‘KB’ =>           1000 (KiloBytes)
+          ‘K’  =>           1024 (KibiBytes)
+          ‘MB’ =>      1000*1000 (MegaBytes)
+          ‘M’  =>      1024*1024 (MebiBytes)
+          ‘GB’ => 1000*1000*1000 (GigaBytes)
+          ‘G’  => 1024*1024*1024 (GibiBytes)
+     and so on for ‘T’, ‘P’, ‘E’, ‘Z’, ‘Y’, ‘R’, and ‘Q’.  Binary
+     prefixes can be used, too: ‘KiB’=‘K’, ‘MiB’=‘M’, and so on.
+
+‘-f’
+‘--follow[=HOW]’
+     Loop forever trying to read more characters at the end of the file,
+     presumably because the file is growing.  If more than one file is
+     given, ‘tail’ prints a header whenever it gets output from a
+     different file, to indicate which file that output is from.
+
+     There are two ways to specify how you’d like to track files with
+     this option, but that difference is noticeable only when a followed
+     file is removed or renamed.  If you’d like to continue to track the
+     end of a growing file even after it has been unlinked, use
+     ‘--follow=descriptor’.  This is the default behavior, but it is not
+     useful if you’re tracking a log file that may be rotated (removed
+     or renamed, then reopened).  In that case, use ‘--follow=name’ to
+     track the named file, perhaps by reopening it periodically to see
+     if it has been removed and recreated by some other program.  Note
+     that the inotify-based implementation handles this case without the
+     need for any periodic reopening.
+
+     No matter which method you use, if the tracked file is determined
+     to have shrunk, ‘tail’ prints a message saying the file has been
+     truncated and resumes tracking from the start of the file, assuming
+     it has been truncated to 0, which is the usual truncation operation
+     for log files.
+
+     When a file is removed, ‘tail’’s behavior depends on whether it is
+     following the name or the descriptor.  When following by name, tail
+     can detect that a file has been removed and gives a message to that
+     effect, and if ‘--retry’ has been specified it will continue
+     checking periodically to see if the file reappears.  When following
+     a descriptor, tail does not detect that the file has been unlinked
+     or renamed and issues no message; even though the file may no
+     longer be accessible via its original name, it may still be
+     growing.
+
+     The option values ‘descriptor’ and ‘name’ may be specified only
+     with the long form of the option, not with ‘-f’.
+
+     The ‘-f’ option is ignored if no FILE operand is specified and
+     standard input is a FIFO or a pipe.  Likewise, the ‘-f’ option has
+     no effect for any operand specified as ‘-’, when standard input is
+     a FIFO or a pipe.
+
+     With kernel inotify support, output is triggered by file changes
+     and is generally very prompt.  Otherwise, ‘tail’ sleeps for one
+     second between checks – use ‘--sleep-interval=N’ to change that
+     default – which can make the output appear slightly less responsive
+     or bursty.  When using tail without inotify support, you can make
+     it more responsive by using a sub-second sleep interval, e.g., via
+     an alias like this:
+
+          alias tail='tail -s.1'
+
+‘-F’
+     This option is the same as ‘--follow=name --retry’.  That is, tail
+     will attempt to reopen a file when it is removed.  Should this
+     fail, tail will keep trying until it becomes accessible again.
+
+‘--max-unchanged-stats=N’
+     When tailing a file by name, if there have been N (default n=5)
+     consecutive iterations for which the file has not changed, then
+     ‘open’/‘fstat’ the file to determine if that file name is still
+     associated with the same device/inode-number pair as before.  When
+     following a log file that is rotated, this is approximately the
+     number of seconds between when tail prints the last pre-rotation
+     lines and when it prints the lines that have accumulated in the new
+     log file.  This option is meaningful only when polling (i.e.,
+     without inotify) and when following by name.
+
+‘-n [+]NUM’
+‘--lines=[+]’
+     Output the last NUM lines.  If NUM is prefixed with a ‘+’, start
+     printing with line NUM from the start of each file.  For example to
+     skip the first line use ‘tail -n +2’, while to skip all but the
+     last line use ‘tail -n 1’.  Size multiplier suffixes are the same
+     as with the ‘-c’ option.
+
+‘--pid=PID’
+     When following by name or by descriptor, you may specify the
+     process ID, PID, of the sole writer of all FILE arguments.  Then,
+     shortly after that process terminates, tail will also terminate.
+     This will work properly only if the writer and the tailing process
+     are running on the same machine.  For example, to save the output
+     of a build in a file and to watch the file grow, if you invoke
+     ‘make’ and ‘tail’ like this then the tail process will stop when
+     your build completes.  Without this option, you would have had to
+     kill the ‘tail -f’ process yourself.
+
+          $ make >& makerr & tail --pid=$! -f makerr
+
+     If you specify a PID that is not in use or that does not correspond
+     to the process that is writing to the tailed files, then ‘tail’ may
+     terminate long before any FILEs stop growing or it may not
+     terminate until long after the real writer has terminated.  Note
+     that ‘--pid’ cannot be supported on some systems; ‘tail’ will print
+     a warning if this is the case.
+
+‘-q’
+‘--quiet’
+‘--silent’
+     Never print file name headers.
+
+‘--retry’
+     Indefinitely try to open the specified file.  This option is useful
+     mainly when following (and otherwise issues a warning).
+
+     When following by file descriptor (i.e., with
+     ‘--follow=descriptor’), this option only affects the initial open
+     of the file, as after a successful open, ‘tail’ will start
+     following the file descriptor.
+
+     When following by name (i.e., with ‘--follow=name’), ‘tail’
+     infinitely retries to re-open the given files until killed.
+
+     Without this option, when ‘tail’ encounters a file that doesn’t
+     exist or is otherwise inaccessible, it reports that fact and never
+     checks it again.
+
+‘-s NUMBER’
+‘--sleep-interval=NUMBER’
+     Change the number of seconds to wait between iterations (the
+     default is 1.0).  During one iteration, every specified file is
+     checked to see if it has changed size.  When ‘tail’ uses inotify,
+     this polling-related option is usually ignored.  However, if you
+     also specify ‘--pid=P’, ‘tail’ checks whether process P is alive at
+     least every NUMBER seconds.  The NUMBER must be non-negative and
+     can be a floating-point number in either the current or the C
+     locale.  *Note Floating point::.
+
+‘-v’
+‘--verbose’
+     Always print file name headers.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).
+
+   For compatibility ‘tail’ also supports an obsolete usage ‘tail
+-[NUM][bcl][f] [FILE]’, which is recognized only if it does not conflict
+with the usage described above.  This obsolete form uses exactly one
+option and at most one file.  In the option, NUM is an optional decimal
+number optionally followed by a size letter (‘b’, ‘c’, ‘l’) to mean
+count by 512-byte blocks, bytes, or lines, optionally followed by ‘f’
+which has the same meaning as ‘-f’.
+
+   On systems not conforming to POSIX 1003.1-2001, the leading ‘-’ can
+be replaced by ‘+’ in the traditional option syntax with the same
+meaning as in counts, and on obsolete systems predating POSIX
+1003.1-2001 traditional usage overrides normal usage when the two
+conflict.  This behavior can be controlled with the ‘_POSIX2_VERSION’
+environment variable (*note Standards conformance::).
+
+   Scripts intended for use on standard hosts should avoid traditional
+syntax and should use ‘-c NUM[b]’, ‘-n NUM’, and/or ‘-f’ instead.  If
+your script must also run on hosts that support only the traditional
+syntax, you can often rewrite it to avoid problematic usages, e.g., by
+using ‘sed -n '$p'’ rather than ‘tail -1’.  If that’s not possible, the
+script can use a test like ‘if tail -c +1 </dev/null >/dev/null 2>&1;
+then ...’ to decide which syntax to use.
+
+   Even if your script assumes the standard behavior, you should still
+beware usages whose behaviors differ depending on the POSIX version.
+For example, avoid ‘tail - main.c’, since it might be interpreted as
+either ‘tail main.c’ or as ‘tail -- - main.c’; avoid ‘tail -c 4’, since
+it might mean either ‘tail -c4’ or ‘tail -c 10 4’; and avoid ‘tail +4’,
+since it might mean either ‘tail ./+4’ or ‘tail -n +4’.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: split invocation,  Next: csplit invocation,  Prev: tail invocation,  Up: Output of parts of files
+
+5.3 ‘split’: Split a file into pieces.
+======================================
+
+‘split’ creates output files containing consecutive or interleaved
+sections of INPUT (standard input if none is given or INPUT is ‘-’).
+Synopsis:
+
+     split [OPTION] [INPUT [PREFIX]]
+
+   By default, ‘split’ puts 1000 lines of INPUT (or whatever is left
+over for the last section), into each output file.
+
+   The output files’ names consist of PREFIX (‘x’ by default) followed
+by a group of characters (‘aa’, ‘ab’, ... by default), such that
+concatenating the output files in traditional sorted order by file name
+produces the original input file (except ‘-nr/N’).  By default split
+will initially create files with two generated suffix characters, and
+will increase this width by two when the next most significant position
+reaches the last character.  (‘yz’, ‘zaaa’, ‘zaab’, ...).  In this way
+an arbitrary number of output files are supported, which sort as
+described above, even in the presence of an ‘--additional-suffix’
+option.  If the ‘-a’ option is specified and the output file names are
+exhausted, ‘split’ reports an error without deleting the output files
+that it did create.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-l LINES’
+‘--lines=LINES’
+     Put LINES lines of INPUT into each output file.  If ‘--separator’
+     is specified, then LINES determines the number of records.
+
+     For compatibility ‘split’ also supports an obsolete option syntax
+     ‘-LINES’.  New scripts should use ‘-l LINES’ instead.
+
+‘-b SIZE’
+‘--bytes=SIZE’
+     Put SIZE bytes of INPUT into each output file.  SIZE may be, or may
+     be an integer optionally followed by, one of the following
+     multiplicative suffixes:
+          ‘b’  =>            512 ("blocks")
+          ‘KB’ =>           1000 (KiloBytes)
+          ‘K’  =>           1024 (KibiBytes)
+          ‘MB’ =>      1000*1000 (MegaBytes)
+          ‘M’  =>      1024*1024 (MebiBytes)
+          ‘GB’ => 1000*1000*1000 (GigaBytes)
+          ‘G’  => 1024*1024*1024 (GibiBytes)
+     and so on for ‘T’, ‘P’, ‘E’, ‘Z’, ‘Y’, ‘R’, and ‘Q’.  Binary
+     prefixes can be used, too: ‘KiB’=‘K’, ‘MiB’=‘M’, and so on.
+
+‘-C SIZE’
+‘--line-bytes=SIZE’
+     Put into each output file as many complete lines of INPUT as
+     possible without exceeding SIZE bytes.  Individual lines or records
+     longer than SIZE bytes are broken into multiple files.  SIZE has
+     the same format as for the ‘--bytes’ option.  If ‘--separator’ is
+     specified, then LINES determines the number of records.
+
+‘--filter=COMMAND’
+     With this option, rather than simply writing to each output file,
+     write through a pipe to the specified shell COMMAND for each output
+     file.  COMMAND should use the $FILE environment variable, which is
+     set to a different output file name for each invocation of the
+     command.  For example, imagine that you have a 1TiB compressed file
+     that, if uncompressed, would be too large to reside on secondary
+     storage, yet you must split it into individually-compressed pieces
+     of a more manageable size.  To do that, you might run this command:
+
+          xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big-
+
+     Assuming a 10:1 compression ratio, that would create about fifty
+     20GiB files with names ‘big-aa.xz’, ‘big-ab.xz’, ‘big-ac.xz’, etc.
+
+‘-n CHUNKS’
+‘--number=CHUNKS’
+
+     Split INPUT to CHUNKS output files where CHUNKS may be:
+
+          N      generate N files based on current size of INPUT
+          K/N    output only Kth of N to standard output
+          l/N    generate N files without splitting lines or records
+          l/K/N  likewise but output only Kth of N to stdout
+          r/N    like ‘l’ but use round robin distribution
+          r/K/N  likewise but output only Kth of N to stdout
+
+     If the input size is not a multiple of N, early output files are
+     one byte longer than later output files, to make up the difference.
+     Any excess bytes appearing after the initial calculation are
+     discarded (except when using ‘r’ mode).
+
+     All N files are created even if there are fewer than N lines, or
+     the INPUT is truncated.
+
+     For ‘l’ mode, chunks are approximately INPUT size / N.  Although
+     the INPUT is still partitioned as before into N regions of
+     approximately equal size, if a line _starts_ within a partition it
+     is written completely to the corresponding file.  Since lines or
+     records are not split even if they overlap a partition, the files
+     written can be larger or smaller than the partition size, and even
+     empty if a line/record is so long as to completely overlap the
+     partition.
+
+     When the input is a pipe or some other special file where the size
+     cannot easily be determined, there is no trouble for ‘r’ mode
+     because the size of the input is irrelevant.  For other modes, such
+     an input is first copied to a temporary to determine its size.
+
+‘-a LENGTH’
+‘--suffix-length=LENGTH’
+     Use suffixes of length LENGTH.  If a LENGTH of 0 is specified, this
+     is the same as if (any previous) ‘-a’ was not specified, and thus
+     enables the default behavior, which starts the suffix length at 2,
+     and unless ‘-n’ or ‘--numeric-suffixes=FROM’ is specified, will
+     auto increase the length by 2 as required.
+
+‘-d’
+‘--numeric-suffixes[=FROM]’
+     Use digits in suffixes rather than lower-case letters.  The
+     numerical suffix counts from FROM if specified, 0 otherwise.
+
+     FROM is supported with the long form option, and is used to either
+     set the initial suffix for a single run, or to set the suffix
+     offset for independently split inputs, and consequently the auto
+     suffix length expansion described above is disabled.  Therefore you
+     may also want to use option ‘-a’ to allow suffixes beyond ‘99’.
+     Note if option ‘--number’ is specified and the number of files is
+     less than FROM, a single run is assumed and the minimum suffix
+     length required is automatically determined.
+
+‘-x’
+‘--hex-suffixes[=FROM]’
+     Like ‘--numeric-suffixes’, but use hexadecimal numbers (in lower
+     case).
+
+‘--additional-suffix=SUFFIX’
+     Append an additional SUFFIX to output file names.  SUFFIX must not
+     contain slash.
+
+‘-e’
+‘--elide-empty-files’
+     Suppress the generation of zero-length output files.  This can
+     happen with the ‘--number’ option if a file is (truncated to be)
+     shorter than the number requested, or if a line is so long as to
+     completely span a chunk.  The output file sequence numbers, always
+     run consecutively even when this option is specified.
+
+‘-t SEPARATOR’
+‘--separator=SEPARATOR’
+     Use character SEPARATOR as the record separator instead of the
+     default newline character (ASCII LF). To specify ASCII NUL as the
+     separator, use the two-character string ‘\0’, e.g., ‘split -t
+     '\0'’.
+
+‘-u’
+‘--unbuffered’
+     Immediately copy input to output in ‘--number r/...’ mode, which is
+     a much slower mode of operation.
+
+‘--verbose’
+     Write a diagnostic just before each output file is opened.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Here are a few examples to illustrate how the ‘--number’ (‘-n’)
+option works:
+
+   Notice how, by default, one line may be split onto two or more:
+
+     $ seq -w 6 10 > k; split -n3 k; head xa?
+     ==> xaa <==
+     06
+     07
+     ==> xab <==
+
+     08
+     0
+     ==> xac <==
+     9
+     10
+
+   Use the "l/" modifier to suppress that:
+
+     $ seq -w 6 10 > k; split -nl/3 k; head xa?
+     ==> xaa <==
+     06
+     07
+
+     ==> xab <==
+     08
+     09
+
+     ==> xac <==
+     10
+
+   Use the "r/" modifier to distribute lines in a round-robin fashion:
+
+     $ seq -w 6 10 > k; split -nr/3 k; head xa?
+     ==> xaa <==
+     06
+     09
+
+     ==> xab <==
+     07
+     10
+
+     ==> xac <==
+     08
+
+   You can also extract just the Kth chunk.  This extracts and prints
+just the 7th "chunk" of 33:
+
+     $ seq 100 > k; split -nl/7/33 k
+     20
+     21
+     22
+
+
+File: coreutils.info,  Node: csplit invocation,  Prev: split invocation,  Up: Output of parts of files
+
+5.4 ‘csplit’: Split a file into context-determined pieces
+=========================================================
+
+‘csplit’ creates zero or more output files containing sections of INPUT
+(standard input if INPUT is ‘-’).  Synopsis:
+
+     csplit [OPTION]... INPUT PATTERN...
+
+   The contents of the output files are determined by the PATTERN
+arguments, as detailed below.  An error occurs if a PATTERN argument
+refers to a nonexistent line of the input file (e.g., if no remaining
+line matches a given regular expression).  After every PATTERN has been
+matched, any remaining input is copied into one last output file.
+
+   By default, ‘csplit’ prints the number of bytes written to each
+output file after it has been created.
+
+   The types of pattern arguments are:
+
+‘N’
+     Create an output file containing the input up to but not including
+     line N (a positive integer).  If followed by a repeat count, also
+     create an output file containing the next N lines of the input file
+     once for each repeat.
+
+‘/REGEXP/[OFFSET]’
+     Create an output file containing the current line up to (but not
+     including) the next line of the input file that contains a match
+     for REGEXP.  The optional OFFSET is an integer, that can be
+     preceded by ‘+’ or ‘-’.  If it is given, the input up to (but not
+     including) the matching line plus or minus OFFSET is put into the
+     output file, and the line after that begins the next section of
+     input.  Note lines within a negative offset of a regexp pattern are
+     not matched in subsequent regexp patterns.
+
+‘%REGEXP%[OFFSET]’
+     Like the previous type, except that it does not create an output
+     file, so that section of the input file is effectively ignored.
+
+‘{REPEAT-COUNT}’
+     Repeat the previous pattern REPEAT-COUNT additional times.  The
+     REPEAT-COUNT can either be a positive integer or an asterisk,
+     meaning repeat as many times as necessary until the input is
+     exhausted.
+
+   The output files’ names consist of a prefix (‘xx’ by default)
+followed by a suffix.  By default, the suffix is an ascending sequence
+of two-digit decimal numbers from ‘00’ to ‘99’.  In any case,
+concatenating the output files in sorted order by file name produces the
+original input file, excluding portions skipped with a %REGEXP% pattern
+or the ‘--suppress-matched’ option.
+
+   By default, if ‘csplit’ encounters an error or receives a hangup,
+interrupt, quit, or terminate signal, it removes any output files that
+it has created so far before it exits.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-f PREFIX’
+‘--prefix=PREFIX’
+     Use PREFIX as the output file name prefix.
+
+‘-b FORMAT’
+‘--suffix-format=FORMAT’
+     Use FORMAT as the output file name suffix.  When this option is
+     specified, the suffix string must include exactly one
+     ‘printf(3)’-style conversion specification, possibly including
+     format specification flags, a field width, a precision
+     specification, or all of these kinds of modifiers.  The format
+     letter must convert a binary unsigned integer argument to readable
+     form.  The format letters ‘d’ and ‘i’ are aliases for ‘u’, and the
+     ‘u’, ‘o’, ‘x’, and ‘X’ conversions are allowed.  The entire FORMAT
+     is given (with the current output file number) to ‘sprintf(3)’ to
+     form the file name suffixes for each of the individual output files
+     in turn.  If this option is used, the ‘--digits’ option is ignored.
+
+‘-n DIGITS’
+‘--digits=DIGITS’
+     Use output file names containing numbers that are DIGITS digits
+     long instead of the default 2.
+
+‘-k’
+‘--keep-files’
+     Do not remove output files when errors are encountered.
+
+‘--suppress-matched’
+     Do not output lines matching the specified PATTERN.  I.e., suppress
+     the boundary line from the start of the second and subsequent
+     splits.
+
+‘-z’
+‘--elide-empty-files’
+     Suppress the generation of zero-length output files.  (In cases
+     where the section delimiters of the input file are supposed to mark
+     the first lines of each of the sections, the first output file will
+     generally be a zero-length file unless you use this option.)  The
+     output file sequence numbers always run consecutively starting from
+     0, even when this option is specified.
+
+‘-s’
+‘-q’
+‘--silent’
+‘--quiet’
+     Do not print counts of output file sizes.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Here is an example of its usage.  First, create an empty directory
+for the exercise, and cd into it:
+
+     $ mkdir d && cd d
+
+   Now, split the sequence of 1..14 on lines that end with 0 or 5:
+
+     $ seq 14 | csplit - '/[05]$/' '{*}'
+     8
+     10
+     15
+
+   Each number printed above is the size of an output file that csplit
+has just created.  List the names of those output files:
+
+     $ ls
+     xx00  xx01  xx02
+
+   Use ‘head’ to show their contents:
+
+     $ head xx*
+     ==> xx00 <==
+     1
+     2
+     3
+     4
+
+     ==> xx01 <==
+     5
+     6
+     7
+     8
+     9
+
+     ==> xx02 <==
+     10
+     11
+     12
+     13
+     14
+
+   Example of splitting input by empty lines:
+
+     $ csplit --suppress-matched INPUT.TXT '/^$/' '{*}'
+
+
+File: coreutils.info,  Node: Summarizing files,  Next: Operating on sorted files,  Prev: Output of parts of files,  Up: Top
+
+6 Summarizing files
+*******************
+
+These commands generate just a few numbers representing entire contents
+of files.
+
+* Menu:
+
+* wc invocation::               Print newline, word, and byte counts.
+* sum invocation::              Print checksum and block counts.
+* cksum invocation::            Print CRC checksum and byte counts.
+* md5sum invocation::           Print or check MD5 digests.
+* b2sum invocation::            Print or check BLAKE2 digests.
+* sha1sum invocation::          Print or check SHA-1 digests.
+* sha2 utilities::              Print or check SHA-2 digests.
+
+
+File: coreutils.info,  Node: wc invocation,  Next: sum invocation,  Up: Summarizing files
+
+6.1 ‘wc’: Print newline, word, and byte counts
+==============================================
+
+‘wc’ counts the number of bytes, characters, words, and newlines in each
+given FILE, or standard input if none are given or for a FILE of ‘-’.  A
+word is a nonzero length sequence of printable characters delimited by
+white space.  Synopsis:
+
+     wc [OPTION]... [FILE]...
+
+   ‘wc’ prints one line of counts for each file, and if the file was
+given as an argument, it prints the file name following the counts.  By
+default if more than one FILE is given, ‘wc’ prints a final line
+containing the cumulative counts, with the file name ‘total’.  This
+‘total’ line can be controlled with the ‘--total’ option, which is a GNU
+extension.  The counts are printed in this order: newlines, words,
+characters, bytes, maximum line length.  Each count is printed
+right-justified in a field with at least one space between fields so
+that the numbers and file names normally line up nicely in columns.  The
+width of the count fields varies depending on the inputs, so you should
+not depend on a particular field width.  However, as a GNU extension, if
+only one count is printed, it is guaranteed to be printed without
+leading spaces.
+
+   By default, ‘wc’ prints three counts: the newline, words, and byte
+counts.  Options can specify that only certain counts be printed.
+Options do not undo others previously given, so
+
+     wc --bytes --words
+
+prints both the byte counts and the word counts.
+
+   With the ‘--max-line-length’ option, ‘wc’ prints the length of the
+longest line per file, and if there is more than one file it prints the
+maximum (not the sum) of those lengths.  The line lengths here are
+measured in screen columns, according to the current locale and assuming
+tab positions in every 8th column.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c’
+‘--bytes’
+     Print only the byte counts.
+
+‘-m’
+‘--chars’
+     Print only the character counts, as per the current locale.
+     Invalid characters are not counted.
+
+‘-w’
+‘--words’
+     Print only the word counts.  A word is a nonzero length sequence of
+     printable characters separated by white space.
+
+‘-l’
+‘--lines’
+     Print only the newline character counts.  Note a file without a
+     trailing newline character, will not have that last portion
+     included in the line count.
+
+‘-L’
+‘--max-line-length’
+     Print only the maximum display widths.  Tabs are set at every 8th
+     column.  Display widths of wide characters are considered.
+     Non-printable characters are given 0 width.
+
+‘--total=WHEN’
+     Control when and how the final line with cumulative counts is
+     printed.  WHEN is one of:
+        • auto - This is the default mode of ‘wc’ when no ‘--total’
+          option is specified.  Output a total line if more than one
+          FILE is specified.
+        • always - Always output a total line, irrespective of the
+          number of files processed.
+        • only - Only output total counts.  I.e., don’t print individual
+          file counts, suppress any leading spaces, and don’t print the
+          ‘total’ word itself, to simplify subsequent processing.
+        • never - Never output a total line.
+
+‘--files0-from=FILE’
+     Disallow processing files named on the command line, and instead
+     process those named in file FILE; each name being terminated by a
+     zero byte (ASCII NUL). This is useful when the list of file names
+     is so long that it may exceed a command line length limitation.  In
+     such cases, running ‘wc’ via ‘xargs’ is undesirable because it
+     splits the list into pieces and makes ‘wc’ print a total for each
+     sublist rather than for the entire list.  One way to produce a list
+     of ASCII NUL terminated file names is with GNU ‘find’, using its
+     ‘-print0’ predicate.  If FILE is ‘-’ then the ASCII NUL terminated
+     file names are read from standard input.
+
+     For example, to find the length of the longest line in any ‘.c’ or
+     ‘.h’ file in the current hierarchy, do this:
+
+          find . -name '*.[ch]' -print0 |
+            wc -L --files0-from=- | tail -n1
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: sum invocation,  Next: cksum invocation,  Prev: wc invocation,  Up: Summarizing files
+
+6.2 ‘sum’: Print checksum and block counts
+==========================================
+
+‘sum’ computes a 16-bit checksum for each given FILE, or standard input
+if none are given or for a FILE of ‘-’.  Synopsis:
+
+     sum [OPTION]... [FILE]...
+
+   ‘sum’ prints the checksum for each FILE followed by the number of
+blocks in the file (rounded up).  If at least one FILE is given, file
+names are also printed.
+
+   By default, GNU ‘sum’ computes checksums using an algorithm
+compatible with BSD ‘sum’ and prints file sizes in units of 1024-byte
+blocks.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-r’
+     Use the default (BSD compatible) algorithm.  This option is
+     included for compatibility with the System V ‘sum’.  Unless ‘-s’
+     was also given, it has no effect.
+
+‘-s’
+‘--sysv’
+     Compute checksums using an algorithm compatible with System V
+     ‘sum’’s default, and print file sizes in units of 512-byte blocks.
+
+   ‘sum’ is provided for compatibility; the ‘cksum’ program (see next
+section) is preferable in new applications.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: cksum invocation,  Next: md5sum invocation,  Prev: sum invocation,  Up: Summarizing files
+
+6.3 ‘cksum’: Print and verify file checksums
+============================================
+
+‘cksum’ by default computes a 32-bit cyclic redundancy check (CRC)
+checksum for each given FILE, or standard input if none are given or for
+a FILE of ‘-’.
+
+   cksum also supports the ‘-a/--algorithm’ option to select the digest
+algorithm to use.  ‘cksum’ is the preferred interface to these digests,
+subsuming the other standalone checksumming utilities, which can be
+emulated using ‘cksum -a md5 --untagged "$@"’ etc.  Synopsis:
+
+     cksum [OPTION]... [FILE]...
+
+   ‘cksum’ is typically used to ensure that files have not been
+corrupted, by comparing the ‘cksum’ output for the received files with
+the ‘cksum’ output for the original files (typically given in the
+distribution).
+
+* Menu:
+
+* cksum output modes::          Legacy and non Legacy output formats
+* cksum general options::       Options supported only by cksum
+* cksum common options::        Options supported also by standalone utilities
+
+
+File: coreutils.info,  Node: cksum output modes,  Next: cksum general options,  Up: cksum invocation
+
+Legacy output format
+     ‘cksum’ by default prints the POSIX standard CRC checksum for each
+     file along with the number of bytes in the file, and the file name
+     unless no arguments were given.  The 32-bit CRC used is based on
+     the polynomial used for CRC error checking in the ISO/IEC
+     8802-3:1996 standard (Ethernet).  Similar output formats are used
+     for the other legacy checksums selectable with ‘--algorithm=sysv’
+     or ‘--algorithm=bsd’, detailed at *note sum invocation::.
+
+Tagged output format
+     With the ‘--algorithm’ option selecting non legacy checksums, the
+     ‘cksum’ command defaults to output of the form:
+          DIGEST_NAME (FILE NAME) = DIGEST
+     Note the standalone checksum utilities can select this output mode
+     by using the ‘--tag’ option.
+
+Untagged output format
+     With the ‘--untagged’ option and the ‘--algorithm’ option selecting
+     non legacy checksums, the following output format is used.  Note
+     this is the default output format of the standalone checksum
+     utilities.  For each FILE, we print the checksum, a space, a flag
+     indicating binary or text input mode, and the file name.  Binary
+     mode is indicated with ‘*’, text mode with ‘ ’ (space).  Binary
+     mode is the default on systems where it’s significant, otherwise
+     text mode is the default.
+
+   Note without ‘--zero’, and with non legacy output formats, if FILE
+contains a backslash, newline, or carriage return, the line is started
+with a backslash, and each problematic character in the file name is
+escaped with a backslash, making the output unambiguous even in the
+presence of arbitrary file names.  Since the backslash character itself
+is escaped, any other backslash escape sequences are reserved for future
+use.
+
+
+File: coreutils.info,  Node: cksum general options,  Next: cksum common options,  Prev: cksum output modes,  Up: cksum invocation
+
+‘-a’
+‘--algorithm’
+     Compute checksums using the specified digest algorithm.
+
+     Supported legacy checksums (which are not supported by ‘--check’):
+          ‘sysv’      equivalent to sum -s
+          ‘bsd’       equivalent to sum -r
+          ‘crc’       equivalent to cksum (the default)
+
+     Supported more modern digest algorithms are:
+          ‘md5’       equivalent to md5sum
+          ‘sha1’      equivalent to sha1sum
+          ‘sha224’    equivalent to sha224sum
+          ‘sha256’    equivalent to sha256sum
+          ‘sha384’    equivalent to sha384sum
+          ‘sha512’    equivalent to sha512sum
+          ‘blake2b’   equivalent to b2sum
+          ‘sm3’       only available through cksum
+
+‘--base64’
+     Print base64-encoded digests not hexadecimal.  This option is
+     ignored with ‘--check’.  The format conforms to RFC 4648#4
+     (https://tools.ietf.org/search/rfc4648#section-4).
+
+     Note that each base64-encoded digest has zero, one or two trailing
+     padding (‘=’) bytes.  The length of that padding is the
+     checksum-bit-length modulo 3, and the ‘--check’ parser requires
+     precisely the same input digest string as what is output.  I.e.,
+     removing or adding any ‘=’ padding renders a digest non-matching.
+
+‘--debug’
+     Output extra information to stderr, like the checksum
+     implementation being used.
+
+‘-l’
+‘--length’
+     Change (shorten) the default digest length.  This is specified in
+     bits and thus must be a multiple of 8.  This option is ignored when
+     ‘--check’ is specified, as the length is automatically determined
+     when checking.
+
+‘--raw’
+     Print only the unencoded raw binary digest for a single input.  Do
+     not output the file name or anything else.  Use network byte order
+     (big endian) where applicable: for ‘bsd’, ‘crc’, and ‘sysv’.  This
+     option works only with a single input.  Unlike other output
+     formats, ‘cksum’ provides no way to ‘--check’ a ‘--raw’ checksum.
+
+‘--untagged’
+     Output using the original Coreutils format used by the other
+     standalone checksum utilities like ‘md5sum’ for example.  This
+     format has the checksum at the start of the line, and may be more
+     amenable to further processing by other utilities, especially in
+     combination with the ‘--zero’ option.  Note this does not identify
+     the digest algorithm used for the checksum.  *Note cksum output
+     modes:: for details of this format.
+
+
+File: coreutils.info,  Node: cksum common options,  Prev: cksum general options,  Up: cksum invocation
+
+‘-b’
+‘--binary’
+     Note this option is not supported by the ‘cksum’ command, as it
+     operates in binary mode exclusively.  Treat each input file as
+     binary, by reading it in binary mode and outputting a ‘*’ flag.
+     This is the inverse of ‘--text’.  On systems like GNU that do not
+     distinguish between binary and text files, this option merely flags
+     each input mode as binary: the checksum is unaffected.  This option
+     is the default on systems like MS-DOS that distinguish between
+     binary and text files, except for reading standard input when
+     standard input is a terminal.
+
+‘-c’
+‘--check’
+     Read file names and checksum information (not data) from each FILE
+     (or from standard input if no FILE was specified) and report
+     whether the checksums match the contents of the named files.  The
+     input to this mode is usually the output of a prior,
+     checksum-generating run of the command.
+
+     Three input formats are supported.  Either the default output
+     format described above, the ‘--tag’ output format, or the BSD
+     reversed mode format which is similar to the default mode, but
+     doesn’t use a character to distinguish binary and text modes.
+
+     For the ‘cksum’ command, the ‘--check’ option supports
+     auto-detecting the digest algorithm to use, when presented with
+     checksum information in the ‘--tag’ output format.
+
+     Also for the ‘cksum’ command, the ‘--check’ option auto-detects the
+     digest encoding, accepting both standard hexadecimal checksums and
+     those generated via ‘cksum’ with its ‘--base64’ option.
+
+     Output with ‘--zero’ enabled is not supported by ‘--check’.
+
+     For each such line, ‘cksum’ reads the named file and computes its
+     checksum.  Then, if the computed message digest does not match the
+     one on the line with the file name, the file is noted as having
+     failed the test.  Otherwise, the file passes the test.  By default,
+     for each valid line, one line is written to standard output
+     indicating whether the named file passed the test.  After all
+     checks have been performed, if there were any failures, a warning
+     is issued to standard error.  Use the ‘--status’ option to inhibit
+     that output.  If any listed file cannot be opened or read, if any
+     valid line has a checksum inconsistent with the associated file, or
+     if no valid line is found, ‘cksum’ exits with nonzero status.
+     Otherwise, it exits successfully.  Note the ‘cksum’ command doesn’t
+     support ‘--check’ with the older ‘sysv’, ‘bsd’, or ‘crc’
+     algorithms.
+
+‘--ignore-missing’
+     This option is useful only when verifying checksums.  When
+     verifying checksums, don’t fail or report any status for missing
+     files.  This is useful when verifying a subset of downloaded files
+     given a larger list of checksums.
+
+‘--quiet’
+     This option is useful only when verifying checksums.  When
+     verifying checksums, don’t generate an ’OK’ message per
+     successfully checked file.  Files that fail the verification are
+     reported in the default one-line-per-file format.  If there is any
+     checksum mismatch, print a warning summarizing the failures to
+     standard error.
+
+‘--status’
+     This option is useful only when verifying checksums.  When
+     verifying checksums, don’t generate the default one-line-per-file
+     diagnostic and don’t output the warning summarizing any failures.
+     Failures to open or read a file still evoke individual diagnostics
+     to standard error.  If all listed files are readable and are
+     consistent with the associated checksums, exit successfully.
+     Otherwise exit with a status code indicating there was a failure.
+
+‘--tag’
+     Output BSD style checksums, which indicate the checksum algorithm
+     used.  As a GNU extension, if ‘--zero’ is not used, file names with
+     problematic characters are escaped as described above, using the
+     same escaping indicator of ‘\’ at the start of the line, as used
+     with the other output format.  The ‘--tag’ option implies binary
+     mode, and is disallowed with ‘--text’ mode as supporting that would
+     unnecessarily complicate the output format, while providing little
+     benefit.  *Note cksum output modes:: for details of this format.
+     The ‘cksum’ command, uses ‘--tag’ as its default output format.
+
+‘-t’
+‘--text’
+     Note this option is not supported by the ‘cksum’ command.  Treat
+     each input file as text, by reading it in text mode and outputting
+     a ‘ ’ flag.  This is the inverse of ‘--binary’.  This option is the
+     default on systems like GNU that do not distinguish between binary
+     and text files.  On other systems, it is the default for reading
+     standard input when standard input is a terminal.  This mode is
+     never defaulted to if ‘--tag’ is used.
+
+‘-w’
+‘--warn’
+     When verifying checksums, warn about improperly formatted checksum
+     lines.  This option is useful only if all but a few lines in the
+     checked input are valid.
+
+‘--strict’
+     When verifying checksums, if one or more input line is invalid,
+     exit nonzero after all warnings have been issued.
+
+‘-z’
+‘--zero’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+     Also file name escaping is not used.
+
+
+File: coreutils.info,  Node: md5sum invocation,  Next: b2sum invocation,  Prev: cksum invocation,  Up: Summarizing files
+
+6.4 ‘md5sum’: Print or check MD5 digests
+========================================
+
+‘md5sum’ computes a 128-bit checksum (or “fingerprint” or
+“message-digest”) for each specified FILE.
+
+   Note: The MD5 digest is more reliable than a simple CRC (provided by
+the ‘cksum’ command) for detecting accidental file corruption, as the
+chances of accidentally having two files with identical MD5 are
+vanishingly small.  However, it should not be considered secure against
+malicious tampering: although finding a file with a given MD5
+fingerprint is considered infeasible at the moment, it is known how to
+modify certain files, including digital certificates, so that they
+appear valid when signed with an MD5 digest.  For more secure hashes,
+consider using SHA-2, or the newer ‘b2sum’ command.  *Note sha2
+utilities::.  *Note b2sum invocation::.
+
+   If a FILE is specified as ‘-’ or if no files are given ‘md5sum’
+computes the checksum for the standard input.  ‘md5sum’ can also
+determine whether a file and checksum are consistent.  Synopsis:
+
+     md5sum [OPTION]... [FILE]...
+
+   ‘md5sum’ uses the ‘Untagged output format’ for each specified file,
+as described at *note cksum output modes::.
+
+   The program accepts *note cksum common options::.  Also see *note
+Common options::.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: b2sum invocation,  Next: sha1sum invocation,  Prev: md5sum invocation,  Up: Summarizing files
+
+6.5 ‘b2sum’: Print or check BLAKE2 digests
+==========================================
+
+‘b2sum’ computes a 512-bit checksum for each specified FILE.
+
+   If a FILE is specified as ‘-’ or if no files are given ‘b2sum’
+computes the checksum for the standard input.  ‘b2sum’ can also
+determine whether a file and checksum are consistent.  Synopsis:
+
+     b2sum [OPTION]... [FILE]...
+
+   ‘b2sum’ uses the ‘Untagged output format’ for each specified file, as
+described at *note cksum output modes::.
+
+   The program accepts *note cksum common options::.  Also see *note
+Common options::.
+
+   In addition ‘b2sum’ supports the following options.
+
+‘-l’
+‘--length’
+     Change (shorten) the default digest length.  This is specified in
+     bits and thus must be a multiple of 8.  This option is ignored when
+     ‘--check’ is specified, as the length is automatically determined
+     when checking.
+
+
+File: coreutils.info,  Node: sha1sum invocation,  Next: sha2 utilities,  Prev: b2sum invocation,  Up: Summarizing files
+
+6.6 ‘sha1sum’: Print or check SHA-1 digests
+===========================================
+
+‘sha1sum’ computes a 160-bit checksum for each specified FILE.
+
+   Note: The SHA-1 digest is more reliable than a simple CRC (provided
+by the ‘cksum’ command) for detecting accidental file corruption, as the
+chances of accidentally having two files with identical SHA-1 are
+vanishingly small.  However, it should not be considered secure against
+malicious tampering: although finding a file with a given SHA-1
+fingerprint is considered infeasible at the moment, it is known how to
+modify certain files, including digital certificates, so that they
+appear valid when signed with an SHA-1 digest.  For more secure hashes,
+consider using SHA-2, or the newer ‘b2sum’ command.  *Note sha2
+utilities::.  *Note b2sum invocation::.
+
+   If a FILE is specified as ‘-’ or if no files are given ‘sha1sum’
+computes the checksum for the standard input.  ‘sha1sum’ can also
+determine whether a file and checksum are consistent.  Synopsis:
+
+     sha1sum [OPTION]... [FILE]...
+
+   ‘sha1sum’ uses the ‘Untagged output format’ for each specified file,
+as described at *note cksum output modes::.
+
+   The program accepts *note cksum common options::.  Also see *note
+Common options::.
+
+
+File: coreutils.info,  Node: sha2 utilities,  Prev: sha1sum invocation,  Up: Summarizing files
+
+6.7 sha2 utilities: Print or check SHA-2 digests
+================================================
+
+The commands ‘sha224sum’, ‘sha256sum’, ‘sha384sum’ and ‘sha512sum’
+compute checksums of various lengths (respectively 224, 256, 384 and 512
+bits), collectively known as the SHA-2 hashes.
+
+   If a FILE is specified as ‘-’ or if no files are given ‘sha???sum’
+computes the checksum for the standard input.  ‘sha???sum’ can also
+determine whether a file and checksum are consistent.  Synopsis:
+
+     sha???sum [OPTION]... [FILE]...
+
+   ‘sha???sum’ uses the ‘Untagged output format’ for each specified
+file, as described at *note cksum output modes::.
+
+   The program accepts *note cksum common options::.  Also see *note
+Common options::.
+
+
+File: coreutils.info,  Node: Operating on sorted files,  Next: Operating on fields,  Prev: Summarizing files,  Up: Top
+
+7 Operating on sorted files
+***************************
+
+These commands work with (or produce) sorted files.
+
+* Menu:
+
+* sort invocation::             Sort text files.
+* shuf invocation::             Shuffle text files.
+* uniq invocation::             Uniquify files.
+* comm invocation::             Compare two sorted files line by line.
+* ptx invocation::              Produce a permuted index of file contents.
+* tsort invocation::            Topological sort.
+
+
+File: coreutils.info,  Node: sort invocation,  Next: shuf invocation,  Up: Operating on sorted files
+
+7.1 ‘sort’: Sort text files
+===========================
+
+‘sort’ sorts, merges, or compares all the lines from the given files, or
+standard input if none are given or for a FILE of ‘-’.  By default,
+‘sort’ writes the results to standard output.  Synopsis:
+
+     sort [OPTION]... [FILE]...
+
+   Many options affect how ‘sort’ compares lines; if the results are
+unexpected, try the ‘--debug’ option to see what happened.  A pair of
+lines is compared as follows: ‘sort’ compares each pair of fields (see
+‘--key’), in the order specified on the command line, according to the
+associated ordering options, until a difference is found or no fields
+are left.  If no key fields are specified, ‘sort’ uses a default key of
+the entire line.  Finally, as a last resort when all keys compare equal,
+‘sort’ compares entire lines as if no ordering options other than
+‘--reverse’ (‘-r’) were specified.  The ‘--stable’ (‘-s’) option
+disables this “last-resort comparison” so that lines in which all fields
+compare equal are left in their original relative order.  The ‘--unique’
+(‘-u’) option also disables the last-resort comparison.
+
+   Unless otherwise specified, all comparisons use the character
+collating sequence specified by the ‘LC_COLLATE’ locale.(1)  A line’s
+trailing newline is not part of the line for comparison purposes.  If
+the final byte of an input file is not a newline, GNU ‘sort’ silently
+supplies one.  GNU ‘sort’ (as specified for all GNU utilities) has no
+limit on input line length or restrictions on bytes allowed within
+lines.
+
+   ‘sort’ has three modes of operation: sort (the default), merge, and
+check for order.  The following options change the operation mode:
+
+‘-c’
+‘--check’
+‘--check=diagnose-first’
+     Check whether the given file is already sorted: if it is not all
+     sorted, print a diagnostic containing the first out-of-order line
+     and exit with a status of 1.  Otherwise, exit successfully.  At
+     most one input file can be given.
+
+‘-C’
+‘--check=quiet’
+‘--check=silent’
+     Exit successfully if the given file is already sorted, and exit
+     with status 1 otherwise.  At most one input file can be given.
+     This is like ‘-c’, except it does not print a diagnostic.
+
+‘-m’
+‘--merge’
+     Merge the given files by sorting them as a group.  Each input file
+     must always be individually sorted.  It always works to sort
+     instead of merge; merging is provided because it is faster, in the
+     case where it works.
+
+   Exit status:
+
+     0 if no error occurred
+     1 if invoked with ‘-c’ or ‘-C’ and the input is not sorted
+     2 if an error occurred
+
+   If the environment variable ‘TMPDIR’ is set, ‘sort’ uses its value as
+the directory for temporary files instead of ‘/tmp’.  The
+‘--temporary-directory’ (‘-T’) option in turn overrides the environment
+variable.
+
+   The following options affect the ordering of output lines.  They may
+be specified globally or as part of a specific key field.  If no key
+fields are specified, global options apply to comparison of entire
+lines; otherwise the global options are inherited by key fields that do
+not specify any special options of their own.  In pre-POSIX versions of
+‘sort’, global options affect only later key fields, so portable shell
+scripts should specify global options first.
+
+‘-b’
+‘--ignore-leading-blanks’
+     Ignore leading blanks when finding sort keys in each line.  By
+     default a blank is a space or a tab, but the ‘LC_CTYPE’ locale can
+     change this.  Note blanks may be ignored by your locale’s collating
+     rules, but without this option they will be significant for
+     character positions specified in keys with the ‘-k’ option.
+
+‘-d’
+‘--dictionary-order’
+     Sort in “phone directory” order: ignore all characters except
+     letters, digits and blanks when sorting.  By default letters and
+     digits are those of ASCII and a blank is a space or a tab, but the
+     ‘LC_CTYPE’ locale can change this.
+
+‘-f’
+‘--ignore-case’
+     Fold lowercase characters into the equivalent uppercase characters
+     when comparing so that, for example, ‘b’ and ‘B’ sort as equal.
+     The ‘LC_CTYPE’ locale determines character types.  When used with
+     ‘--unique’ those lower case equivalent lines are thrown away.
+     (There is currently no way to throw away the upper case equivalent
+     instead.  (Any ‘--reverse’ given would only affect the final
+     result, after the throwing away.))
+
+‘-g’
+‘--general-numeric-sort’
+‘--sort=general-numeric’
+     Sort numerically, converting a prefix of each line to a long
+     double-precision floating point number.  *Note Floating point::.
+     Do not report overflow, underflow, or conversion errors.  Use the
+     following collating sequence:
+
+        • Lines that do not start with numbers (all considered to be
+          equal).
+        • NaNs (“Not a Number” values, in IEEE floating point
+          arithmetic) in a consistent but machine-dependent order.
+        • Minus infinity.
+        • Finite numbers in ascending numeric order (with -0 and +0
+          equal).
+        • Plus infinity.
+
+     Use this option only if there is no alternative; it is much slower
+     than ‘--numeric-sort’ (‘-n’) and it can lose information when
+     converting to floating point.
+
+     You can use this option to sort hexadecimal numbers prefixed with
+     ‘0x’ or ‘0X’, where those numbers are not fixed width, or of
+     varying case.  However for hex numbers of consistent case, and left
+     padded with ‘0’ to a consistent width, a standard lexicographic
+     sort will be faster.
+
+‘-h’
+‘--human-numeric-sort’
+‘--sort=human-numeric’
+     Sort numerically, first by numeric sign (negative, zero, or
+     positive); then by SI suffix (either empty, or ‘k’ or ‘K’, or one
+     of ‘MGTPEZYRQ’, in that order; *note Block size::); and finally by
+     numeric value.  For example, ‘1023M’ sorts before ‘1G’ because ‘M’
+     (mega) precedes ‘G’ (giga) as an SI suffix.  This option sorts
+     values that are consistently scaled to the nearest suffix,
+     regardless of whether suffixes denote powers of 1000 or 1024, and
+     it therefore sorts the output of any single invocation of the ‘df’,
+     ‘du’, or ‘ls’ commands that are invoked with their
+     ‘--human-readable’ or ‘--si’ options.  The syntax for numbers is
+     the same as for the ‘--numeric-sort’ option; the SI suffix must
+     immediately follow the number.  Note also the ‘numfmt’ command,
+     which can be used to reformat numbers to human format _after_ the
+     sort, thus often allowing sort to operate on more accurate numbers.
+
+‘-i’
+‘--ignore-nonprinting’
+     Ignore nonprinting characters.  The ‘LC_CTYPE’ locale determines
+     character types.  This option has no effect if the stronger
+     ‘--dictionary-order’ (‘-d’) option is also given.
+
+‘-M’
+‘--month-sort’
+‘--sort=month’
+     An initial string, consisting of any amount of blanks, followed by
+     a month name abbreviation, is folded to UPPER case and compared in
+     the order ‘JAN’ < ‘FEB’ < ... < ‘DEC’.  Invalid names compare low
+     to valid names.  The ‘LC_TIME’ locale category determines the month
+     spellings.  By default a blank is a space or a tab, but the
+     ‘LC_CTYPE’ locale can change this.
+
+‘-n’
+‘--numeric-sort’
+‘--sort=numeric’
+     Sort numerically.  The number begins each line and consists of
+     optional blanks, an optional ‘-’ sign, and zero or more digits
+     possibly separated by thousands separators, optionally followed by
+     a decimal-point character and zero or more digits.  An empty number
+     is treated as ‘0’.  The ‘LC_NUMERIC’ locale specifies the
+     decimal-point character and thousands separator.  By default a
+     blank is a space or a tab, but the ‘LC_CTYPE’ locale can change
+     this.
+
+     Comparison is exact; there is no rounding error.
+
+     Neither a leading ‘+’ nor exponential notation is recognized.  To
+     compare such strings numerically, use the ‘--general-numeric-sort’
+     (‘-g’) option.
+
+‘-V’
+‘--version-sort’
+     Sort by version name and number.  It behaves like a standard sort,
+     except that each sequence of decimal digits is treated numerically
+     as an index/version number.  (*Note Version sort ordering::.)
+
+‘-r’
+‘--reverse’
+     Reverse the result of comparison, so that lines with greater key
+     values appear earlier in the output instead of later.
+
+‘-R’
+‘--random-sort’
+‘--sort=random’
+     Sort by hashing the input keys and then sorting the hash values.
+     Choose the hash function at random, ensuring that it is free of
+     collisions so that differing keys have differing hash values.  This
+     is like a random permutation of the inputs (*note shuf
+     invocation::), except that keys with the same value sort together.
+
+     If multiple random sort fields are specified, the same random hash
+     function is used for all fields.  To use different random hash
+     functions for different fields, you can invoke ‘sort’ more than
+     once.
+
+     The choice of hash function is affected by the ‘--random-source’
+     option.
+
+   Other options are:
+
+‘--compress-program=PROG’
+     Compress any temporary files with the program PROG.
+
+     With no arguments, PROG must compress standard input to standard
+     output, and when given the ‘-d’ option it must decompress standard
+     input to standard output.
+
+     Terminate with an error if PROG exits with nonzero status.
+
+     White space and the backslash character should not appear in PROG;
+     they are reserved for future use.
+
+‘--files0-from=FILE’
+     Disallow processing files named on the command line, and instead
+     process those named in file FILE; each name being terminated by a
+     zero byte (ASCII NUL). This is useful when the list of file names
+     is so long that it may exceed a command line length limitation.  In
+     such cases, running ‘sort’ via ‘xargs’ is undesirable because it
+     splits the list into pieces and makes ‘sort’ print sorted output
+     for each sublist rather than for the entire list.  One way to
+     produce a list of ASCII NUL terminated file names is with GNU
+     ‘find’, using its ‘-print0’ predicate.  If FILE is ‘-’ then the
+     ASCII NUL terminated file names are read from standard input.
+
+‘-k POS1[,POS2]’
+‘--key=POS1[,POS2]’
+     Specify a sort field that consists of the part of the line between
+     POS1 and POS2 (or the end of the line, if POS2 is omitted),
+     _inclusive_.
+
+     In its simplest form POS specifies a field number (starting with
+     1), with fields being separated by runs of blank characters, and by
+     default those blanks being included in the comparison at the start
+     of each field.  To adjust the handling of blank characters see the
+     ‘-b’ and ‘-t’ options.
+
+     More generally, each POS has the form ‘F[.C][OPTS]’, where F is the
+     number of the field to use, and C is the number of the first
+     character from the beginning of the field.  Fields and character
+     positions are numbered starting with 1; a character position of
+     zero in POS2 indicates the field’s last character.  If ‘.C’ is
+     omitted from POS1, it defaults to 1 (the beginning of the field);
+     if omitted from POS2, it defaults to 0 (the end of the field).
+     OPTS are ordering options, allowing individual keys to be sorted
+     according to different rules; see below for details.  Keys can span
+     multiple fields.
+
+     Example: To sort on the second field, use ‘--key=2,2’ (‘-k 2,2’).
+     See below for more notes on keys and more examples.  See also the
+     ‘--debug’ option to help determine the part of the line being used
+     in the sort.
+
+‘--debug’
+     Highlight the portion of each line used for sorting.  Also issue
+     warnings about questionable usage to standard error.
+
+‘--batch-size=NMERGE’
+     Merge at most NMERGE inputs at once.
+
+     When ‘sort’ has to merge more than NMERGE inputs, it merges them in
+     groups of NMERGE, saving the result in a temporary file, which is
+     then used as an input in a subsequent merge.
+
+     A large value of NMERGE may improve merge performance and decrease
+     temporary storage utilization at the expense of increased memory
+     usage and I/O.  Conversely a small value of NMERGE may reduce
+     memory requirements and I/O at the expense of temporary storage
+     consumption and merge performance.
+
+     The value of NMERGE must be at least 2.  The default value is
+     currently 16, but this is implementation-dependent and may change
+     in the future.
+
+     The value of NMERGE may be bounded by a resource limit for open
+     file descriptors.  The commands ‘ulimit -n’ or ‘getconf OPEN_MAX’
+     may display limits for your systems; these limits may be modified
+     further if your program already has some files open, or if the
+     operating system has other limits on the number of open files.  If
+     the value of NMERGE exceeds the resource limit, ‘sort’ silently
+     uses a smaller value.
+
+‘-o OUTPUT-FILE’
+‘--output=OUTPUT-FILE’
+     Write output to OUTPUT-FILE instead of standard output.  Normally,
+     ‘sort’ reads all input before opening OUTPUT-FILE, so you can sort
+     a file in place by using commands like ‘sort -o F F’ and ‘cat F |
+     sort -o F’.  However, it is often safer to output to an
+     otherwise-unused file, as data may be lost if the system crashes or
+     ‘sort’ encounters an I/O or other serious error while a file is
+     being sorted in place.  Also, ‘sort’ with ‘--merge’ (‘-m’) can open
+     the output file before reading all input, so a command like ‘cat F
+     | sort -m -o F - G’ is not safe as ‘sort’ might start writing ‘F’
+     before ‘cat’ is done reading it.
+
+     On newer systems, ‘-o’ cannot appear after an input file if
+     ‘POSIXLY_CORRECT’ is set, e.g., ‘sort F -o F’.  Portable scripts
+     should specify ‘-o OUTPUT-FILE’ before any input files.
+
+‘--random-source=FILE’
+     Use FILE as a source of random data used to determine which random
+     hash function to use with the ‘-R’ option.  *Note Random sources::.
+
+‘-s’
+‘--stable’
+
+     Make ‘sort’ stable by disabling its last-resort comparison.  This
+     option has no effect if no fields or global ordering options other
+     than ‘--reverse’ (‘-r’) are specified.
+
+‘-S SIZE’
+‘--buffer-size=SIZE’
+     Use a main-memory sort buffer of the given SIZE.  By default, SIZE
+     is in units of 1024 bytes.  Appending ‘%’ causes SIZE to be
+     interpreted as a percentage of physical memory.  Appending ‘K’
+     multiplies SIZE by 1024 (the default), ‘M’ by 1,048,576, ‘G’ by
+     1,073,741,824, and so on for ‘T’, ‘P’, ‘E’, ‘Z’, ‘Y’, ‘R’, and ‘Q’.
+     Appending ‘b’ causes SIZE to be interpreted as a byte count, with
+     no multiplication.
+
+     This option can improve the performance of ‘sort’ by causing it to
+     start with a larger or smaller sort buffer than the default.
+     However, this option affects only the initial buffer size.  The
+     buffer grows beyond SIZE if ‘sort’ encounters input lines larger
+     than SIZE.
+
+‘-t SEPARATOR’
+‘--field-separator=SEPARATOR’
+     Use character SEPARATOR as the field separator when finding the
+     sort keys in each line.  By default, fields are separated by the
+     empty string between a non-blank character and a blank character.
+     By default a blank is a space or a tab, but the ‘LC_CTYPE’ locale
+     can change this.
+
+     That is, given the input line ‘ foo bar’, ‘sort’ breaks it into
+     fields ‘ foo’ and ‘ bar’.  The field separator is not considered to
+     be part of either the field preceding or the field following, so
+     with ‘sort -t " "’ the same input line has three fields: an empty
+     field, ‘foo’, and ‘bar’.  However, fields that extend to the end of
+     the line, as ‘-k 2’, or fields consisting of a range, as ‘-k 2,3’,
+     retain the field separators present between the endpoints of the
+     range.
+
+     To specify ASCII NUL as the field separator, use the two-character
+     string ‘\0’, e.g., ‘sort -t '\0'’.
+
+‘-T TEMPDIR’
+‘--temporary-directory=TEMPDIR’
+     Use directory TEMPDIR to store temporary files, overriding the
+     ‘TMPDIR’ environment variable.  If this option is given more than
+     once, temporary files are stored in all the directories given.  If
+     you have a large sort or merge that is I/O-bound, you can often
+     improve performance by using this option to specify directories on
+     different file systems.
+
+‘--parallel=N’
+     Set the number of sorts run in parallel to N.  By default, N is set
+     to the number of available processors, but limited to 8, as there
+     are diminishing performance gains after that.  Note also that using
+     N threads increases the memory usage by a factor of log N.  Also
+     see *note nproc invocation::.
+
+‘-u’
+‘--unique’
+
+     Normally, output only the first of a sequence of lines that compare
+     equal.  For the ‘--check’ (‘-c’ or ‘-C’) option, check that no pair
+     of consecutive lines compares equal.
+
+     This option also disables the default last-resort comparison.
+
+     The commands ‘sort -u’ and ‘sort | uniq’ are equivalent, but this
+     equivalence does not extend to arbitrary ‘sort’ options.  For
+     example, ‘sort -n -u’ inspects only the value of the initial
+     numeric string when checking for uniqueness, whereas ‘sort -n |
+     uniq’ inspects the entire line.  *Note uniq invocation::.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).
+
+   Historical (BSD and System V) implementations of ‘sort’ have differed
+in their interpretation of some options, particularly ‘-b’, ‘-f’, and
+‘-n’.  GNU sort follows the POSIX behavior, which is usually (but not
+always!)  like the System V behavior.  According to POSIX, ‘-n’ no
+longer implies ‘-b’.  For consistency, ‘-M’ has been changed in the same
+way.  This may affect the meaning of character positions in field
+specifications in obscure cases.  The only fix is to add an explicit
+‘-b’.
+
+   A position in a sort field specified with ‘-k’ may have any of the
+option letters ‘MbdfghinRrV’ appended to it, in which case no global
+ordering options are inherited by that particular field.  The ‘-b’
+option may be independently attached to either or both of the start and
+end positions of a field specification, and if it is inherited from the
+global options it will be attached to both.  If input lines can contain
+leading or adjacent blanks and ‘-t’ is not used, then ‘-k’ is typically
+combined with ‘-b’ or an option that implicitly ignores leading blanks
+(‘Mghn’) as otherwise the varying numbers of leading blanks in fields
+can cause confusing results.
+
+   If the start position in a sort field specifier falls after the end
+of the line or after the end field, the field is empty.  If the ‘-b’
+option was specified, the ‘.C’ part of a field specification is counted
+from the first nonblank character of the field.
+
+   On systems not conforming to POSIX 1003.1-2001, ‘sort’ supports a
+traditional origin-zero syntax ‘+POS1 [-POS2]’ for specifying sort keys.
+The traditional command ‘sort +A.X -B.Y’ is equivalent to ‘sort -k
+A+1.X+1,B’ if Y is ‘0’ or absent, otherwise it is equivalent to ‘sort -k
+A+1.X+1,B+1.Y’.
+
+   This traditional behavior can be controlled with the
+‘_POSIX2_VERSION’ environment variable (*note Standards conformance::);
+it can also be enabled when ‘POSIXLY_CORRECT’ is not set by using the
+traditional syntax with ‘-POS2’ present.
+
+   Scripts intended for use on standard hosts should avoid traditional
+syntax and should use ‘-k’ instead.  For example, avoid ‘sort +2’, since
+it might be interpreted as either ‘sort ./+2’ or ‘sort -k 3’.  If your
+script must also run on hosts that support only the traditional syntax,
+it can use a test like ‘if sort -k 1 </dev/null >/dev/null 2>&1; then
+...’ to decide which syntax to use.
+
+   Here are some examples to illustrate various combinations of options.
+
+   • Sort in descending (reverse) numeric order.
+
+          sort -n -r
+
+   • Run no more than 4 sorts concurrently, using a buffer size of 10M.
+
+          sort --parallel=4 -S 10M
+
+   • Sort alphabetically, omitting the first and second fields and the
+     blanks at the start of the third field.  This uses a single key
+     composed of the characters beginning at the start of the first
+     nonblank character in field three and extending to the end of each
+     line.
+
+          sort -k 3b
+
+   • Sort numerically on the second field and resolve ties by sorting
+     alphabetically on the third and fourth characters of field five.
+     Use ‘:’ as the field delimiter.
+
+          sort -t : -k 2,2n -k 5.3,5.4
+
+     Note that if you had written ‘-k 2n’ instead of ‘-k 2,2n’ ‘sort’
+     would have used all characters beginning in the second field and
+     extending to the end of the line as the primary _numeric_ key.  For
+     the large majority of applications, treating keys spanning more
+     than one field as numeric will not do what you expect.
+
+     Also note that the ‘n’ modifier was applied to the field-end
+     specifier for the first key.  It would have been equivalent to
+     specify ‘-k 2n,2’ or ‘-k 2n,2n’.  All modifiers except ‘b’ apply to
+     the associated _field_, regardless of whether the modifier
+     character is attached to the field-start and/or the field-end part
+     of the key specifier.
+
+   • Sort the password file on the fifth field and ignore any leading
+     blanks.  Sort lines with equal values in field five on the numeric
+     user ID in field three.  Fields are separated by ‘:’.
+
+          sort -t : -k 5b,5 -k 3,3n /etc/passwd
+          sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
+          sort -t : -b -k 5,5 -k 3,3n /etc/passwd
+
+     These three commands have equivalent effect.  The first specifies
+     that the first key’s start position ignores leading blanks and the
+     second key is sorted numerically.  The other two commands rely on
+     global options being inherited by sort keys that lack modifiers.
+     The inheritance works in this case because ‘-k 5b,5b’ and ‘-k 5b,5’
+     are equivalent, as the location of a field-end lacking a ‘.C’
+     character position is not affected by whether initial blanks are
+     skipped.
+
+   • Sort a set of log files, primarily by IPv4 address and secondarily
+     by timestamp.  If two lines’ primary and secondary keys are
+     identical, output the lines in the same order that they were input.
+     The log files contain lines that look like this:
+
+          4.150.156.3 - - [01/Apr/2020:06:31:51 +0000] message 1
+          211.24.3.231 - - [24/Apr/2020:20:17:39 +0000] message 2
+
+     Fields are separated by exactly one space.  Sort IPv4 addresses
+     lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201
+     because 61 is less than 129.
+
+          sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log |
+          sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n
+
+     This example cannot be done with a single POSIX ‘sort’ invocation,
+     since IPv4 address components are separated by ‘.’ while dates come
+     just after a space.  So it is broken down into two invocations of
+     ‘sort’: the first sorts by timestamp and the second by IPv4
+     address.  The timestamp is sorted by year, then month, then day,
+     and finally by hour-minute-second field, using ‘-k’ to isolate each
+     field.  Except for hour-minute-second there’s no need to specify
+     the end of each key field, since the ‘n’ and ‘M’ modifiers sort
+     based on leading prefixes that cannot cross field boundaries.  The
+     IPv4 addresses are sorted lexicographically.  The second sort uses
+     ‘-s’ so that ties in the primary key are broken by the secondary
+     key; the first sort uses ‘-s’ so that the combination of the two
+     sorts is stable.  Note as a GNU extension, the above example could
+     be achieved in a single ‘sort’ invocation by sorting the IPv4
+     address field using a ‘V’ version type, like ‘-k1,1V’.
+
+   • Generate a tags file in case-insensitive sorted order.
+
+          find src -type f -print0 | sort -z -f | xargs -0 etags --append
+
+     The use of ‘-print0’, ‘-z’, and ‘-0’ in this case means that file
+     names that contain blanks or other special characters are not
+     broken up by the sort operation.
+
+   • Use the common DSU, Decorate Sort Undecorate idiom to sort lines
+     according to their length.
+
+          awk '{print length, $0}' /etc/passwd | sort -n | cut -f2- -d' '
+
+     In general this technique can be used to sort data that the ‘sort’
+     command does not support, or is inefficient at, sorting directly.
+
+   • Shuffle a list of directories, but preserve the order of files
+     within each directory.  For instance, one could use this to
+     generate a music playlist in which albums are shuffled but the
+     songs of each album are played in order.
+
+          ls */* | sort -t / -k 1,1R -k 2,2
+
+   ---------- Footnotes ----------
+
+   (1) If you use a non-POSIX locale (e.g., by setting ‘LC_ALL’ to
+‘en_US’), then ‘sort’ may produce output that is sorted differently than
+you’re accustomed to.  In that case, set the ‘LC_ALL’ environment
+variable to ‘C’.  Note that setting only ‘LC_COLLATE’ has two problems.
+First, it is ineffective if ‘LC_ALL’ is also set.  Second, it has
+undefined behavior if ‘LC_CTYPE’ (or ‘LANG’, if ‘LC_CTYPE’ is unset) is
+set to an incompatible value.  For example, you get undefined behavior
+if ‘LC_CTYPE’ is ‘ja_JP.PCK’ but ‘LC_COLLATE’ is ‘en_US.UTF-8’.
+
+
+File: coreutils.info,  Node: shuf invocation,  Next: uniq invocation,  Prev: sort invocation,  Up: Operating on sorted files
+
+7.2 ‘shuf’: Shuffling text
+==========================
+
+‘shuf’ shuffles its input by outputting a random permutation of its
+input lines.  Each output permutation is equally likely.  Synopses:
+
+     shuf [OPTION]... [FILE]
+     shuf -e [OPTION]... [ARG]...
+     shuf -i LO-HI [OPTION]...
+
+   ‘shuf’ has three modes of operation that affect where it obtains its
+input lines.  By default, it reads lines from standard input.  The
+following options change the operation mode:
+
+‘-e’
+‘--echo’
+     Treat each command-line operand as an input line.
+
+‘-i LO-HI’
+‘--input-range=LO-HI’
+     Act as if input came from a file containing the range of unsigned
+     decimal integers LO...HI, one per line.
+
+   ‘shuf’’s other options can affect its behavior in all operation
+modes:
+
+‘-n COUNT’
+‘--head-count=COUNT’
+     Output at most COUNT lines.  By default, all input lines are
+     output.
+
+‘-o OUTPUT-FILE’
+‘--output=OUTPUT-FILE’
+     Write output to OUTPUT-FILE instead of standard output.  ‘shuf’
+     reads all input before opening OUTPUT-FILE, so you can safely
+     shuffle a file in place by using commands like ‘shuf -o F <F’ and
+     ‘cat F | shuf -o F’.
+
+‘--random-source=FILE’
+     Use FILE as a source of random data used to determine which
+     permutation to generate.  *Note Random sources::.
+
+‘-r’
+‘--repeat’
+     Repeat output values, that is, select with replacement.  With this
+     option the output is not a permutation of the input; instead, each
+     output line is randomly chosen from all the inputs.  This option is
+     typically combined with ‘--head-count’; if ‘--head-count’ is not
+     given, ‘shuf’ repeats indefinitely.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).
+
+   For example:
+
+     shuf <<EOF
+     A man,
+     a plan,
+     a canal:
+     Panama!
+     EOF
+
+might produce the output
+
+     Panama!
+     A man,
+     a canal:
+     a plan,
+
+Similarly, the command:
+
+     shuf -e clubs hearts diamonds spades
+
+might output:
+
+     clubs
+     diamonds
+     spades
+     hearts
+
+and the command ‘shuf -i 1-4’ might output:
+
+     4
+     2
+     1
+     3
+
+The above examples all have four input lines, so ‘shuf’ might produce
+any of the twenty-four possible permutations of the input.  In general,
+if there are N input lines, there are N!  (i.e., N factorial, or N * (N
+- 1) * ... * 1) possible output permutations.
+
+To output 50 random numbers each in the range 0 through 9, use:
+
+     shuf -r -n 50 -i 0-9
+
+To simulate 100 coin flips, use:
+
+     shuf -r -n 100 -e Head Tail
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: uniq invocation,  Next: comm invocation,  Prev: shuf invocation,  Up: Operating on sorted files
+
+7.3 ‘uniq’: Uniquify files
+==========================
+
+‘uniq’ writes the unique lines in the given ‘input’, or standard input
+if nothing is given or for an INPUT name of ‘-’.  Synopsis:
+
+     uniq [OPTION]... [INPUT [OUTPUT]]
+
+   By default, ‘uniq’ prints its input lines, except that it discards
+all but the first of adjacent repeated lines, so that no output lines
+are repeated.  Optionally, it can instead discard lines that are not
+repeated, or all repeated lines.
+
+   The input need not be sorted, but repeated input lines are detected
+only if they are adjacent.  If you want to discard non-adjacent
+duplicate lines, perhaps you want to use ‘sort -u’.  *Note sort
+invocation::.
+
+   Comparisons honor the rules specified by the ‘LC_COLLATE’ locale
+category.
+
+   If no OUTPUT file is specified, ‘uniq’ writes to standard output.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-f N’
+‘--skip-fields=N’
+     Skip N fields on each line before checking for uniqueness.  Use a
+     null string for comparison if a line has fewer than N fields.
+     Fields are a sequence of blank characters followed by non-blank
+     characters.  Field numbers are one based, i.e., ‘-f 1’ will skip
+     the first field (which may optionally have leading blanks).
+
+     For compatibility ‘uniq’ supports a traditional option syntax ‘-N’.
+     New scripts should use ‘-f N’ instead.
+
+‘-s N’
+‘--skip-chars=N’
+     Skip N characters before checking for uniqueness.  Use a null
+     string for comparison if a line has fewer than N characters.  If
+     you use both the field and character skipping options, fields are
+     skipped over first.
+
+     On systems not conforming to POSIX 1003.1-2001, ‘uniq’ supports a
+     traditional option syntax ‘+N’.  Although this traditional behavior
+     can be controlled with the ‘_POSIX2_VERSION’ environment variable
+     (*note Standards conformance::), portable scripts should avoid
+     commands whose behavior depends on this variable.  For example, use
+     ‘uniq ./+10’ or ‘uniq -s 10’ rather than the ambiguous ‘uniq +10’.
+
+‘-c’
+‘--count’
+     Print the number of times each line occurred along with the line.
+
+‘-i’
+‘--ignore-case’
+     Ignore differences in case when comparing lines.
+
+‘-d’
+‘--repeated’
+     Discard lines that are not repeated.  When used by itself, this
+     option causes ‘uniq’ to print the first copy of each repeated line,
+     and nothing else.
+
+‘-D’
+‘--all-repeated[=DELIMIT-METHOD]’
+     Do not discard the second and subsequent repeated input lines, but
+     discard lines that are not repeated.  This option is useful mainly
+     in conjunction with other options e.g., to ignore case or to
+     compare only selected fields.  The optional DELIMIT-METHOD,
+     supported with the long form option, specifies how to delimit
+     groups of repeated lines, and must be one of the following:
+
+     ‘none’
+          Do not delimit groups of repeated lines.  This is equivalent
+          to ‘--all-repeated’ (‘-D’).
+
+     ‘prepend’
+          Output a newline before each group of repeated lines.  With
+          ‘--zero-terminated’ (‘-z’), use a zero byte (ASCII NUL)
+          instead of a newline as the delimiter.
+
+     ‘separate’
+          Separate groups of repeated lines with a single newline.  This
+          is the same as using ‘prepend’, except that no delimiter is
+          inserted before the first group, and hence may be better
+          suited for output direct to users.  With ‘--zero-terminated’
+          (‘-z’), use a zero byte (ASCII NUL) instead of a newline as
+          the delimiter.
+
+     Note that when groups are delimited and the input stream contains
+     blank lines, then the output is ambiguous.  To avoid that, filter
+     the input through ‘tr -s '\n'’ to remove blank lines.
+
+     This is a GNU extension.
+
+‘--group[=DELIMIT-METHOD]’
+     Output all lines, and delimit each unique group.  With
+     ‘--zero-terminated’ (‘-z’), use a zero byte (ASCII NUL) instead of
+     a newline as the delimiter.  The optional DELIMIT-METHOD specifies
+     how to delimit groups, and must be one of the following:
+
+     ‘separate’
+          Separate unique groups with a single delimiter.  This is the
+          default delimiting method if none is specified, and better
+          suited for output direct to users.
+
+     ‘prepend’
+          Output a delimiter before each group of unique items.
+
+     ‘append’
+          Output a delimiter after each group of unique items.
+
+     ‘both’
+          Output a delimiter around each group of unique items.
+
+     Note that when groups are delimited and the input stream contains
+     blank lines, then the output is ambiguous.  To avoid that, filter
+     the input through ‘tr -s '\n'’ to remove blank lines.
+
+     This is a GNU extension.
+
+‘-u’
+‘--unique’
+     Discard the last line that would be output for a repeated input
+     group.  When used by itself, this option causes ‘uniq’ to print
+     unique lines, and nothing else.
+
+‘-w N’
+‘--check-chars=N’
+     Compare at most N characters on each line (after skipping any
+     specified fields and characters).  By default the entire rest of
+     the lines are compared.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).  Note with
+     ‘-z’ the newline character is treated as a field separator.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: comm invocation,  Next: ptx invocation,  Prev: uniq invocation,  Up: Operating on sorted files
+
+7.4 ‘comm’: Compare two sorted files line by line
+=================================================
+
+‘comm’ writes to standard output lines that are common, and lines that
+are unique, to two input files; a file name of ‘-’ means standard input.
+Synopsis:
+
+     comm [OPTION]... FILE1 FILE2
+
+   Before ‘comm’ can be used, the input files must be sorted using the
+collating sequence specified by the ‘LC_COLLATE’ locale.  If an input
+file ends in a non-newline character, a newline is silently appended.
+The ‘sort’ command with no options always outputs a file that is
+suitable input to ‘comm’.
+
+   With no options, ‘comm’ produces three-column output.  Column one
+contains lines unique to FILE1, column two contains lines unique to
+FILE2, and column three contains lines common to both files.  Columns
+are separated by a single TAB character.
+
+   The options ‘-1’, ‘-2’, and ‘-3’ suppress printing of the
+corresponding columns (and separators).  Also see *note Common
+options::.
+
+   Unlike some other comparison utilities, ‘comm’ has an exit status
+that does not depend on the result of the comparison.  Upon normal
+completion ‘comm’ produces an exit code of zero.  If there is an error
+it exits with nonzero status.
+
+   If the ‘--check-order’ option is given, unsorted inputs will cause a
+fatal error message.  If the option ‘--nocheck-order’ is given, unsorted
+inputs will never cause an error message.  If neither of these options
+is given, wrongly sorted inputs are diagnosed only if an input file is
+found to contain unpairable lines.  If an input file is diagnosed as
+being unsorted, the ‘comm’ command will exit with a nonzero status (and
+the output should not be used).
+
+   Forcing ‘comm’ to process wrongly sorted input files containing
+unpairable lines by specifying ‘--nocheck-order’ is not guaranteed to
+produce any particular output.  The output will probably not correspond
+with whatever you hoped it would be.
+
+‘--check-order’
+     Fail with an error message if either input file is wrongly ordered.
+
+‘--nocheck-order’
+     Do not check that both input files are in sorted order.
+
+     Other options are:
+
+‘--output-delimiter=STR’
+     Print STR between adjacent output columns, rather than the default
+     of a single TAB character.
+
+     The delimiter STR may be empty, in which case the ASCII NUL
+     character is used to delimit output columns.
+
+‘--total’
+     Output a summary at the end.
+
+     Similar to the regular output, column one contains the total number
+     of lines unique to FILE1, column two contains the total number of
+     lines unique to FILE2, and column three contains the total number
+     of lines common to both files, followed by the word ‘total’ in the
+     additional column four.
+
+     In the following example, ‘comm’ omits the regular output (‘-123’),
+     thus just printing the summary:
+
+          $ printf '%s\n' a b c d e     > file1
+          $ printf '%s\n'   b c d e f g > file2
+          $ comm --total -123 file1 file2
+          1       2       4       total
+
+     This option is a GNU extension.  Portable scripts should use ‘wc’
+     to get the totals, e.g.  for the above example files:
+
+          $ comm -23 file1 file2 | wc -l    # number of lines only in file1
+          1
+          $ comm -13 file1 file2 | wc -l    # number of lines only in file2
+          2
+          $ comm -12 file1 file2 | wc -l    # number of lines common to both files
+          4
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).
+
+
+File: coreutils.info,  Node: ptx invocation,  Next: tsort invocation,  Prev: comm invocation,  Up: Operating on sorted files
+
+7.5 ‘ptx’: Produce permuted indexes
+===================================
+
+‘ptx’ reads a text file and essentially produces a permuted index, with
+each keyword in its context.  The calling sketch is either one of:
+
+     ptx [OPTION ...] [FILE ...]
+     ptx -G [OPTION ...] [INPUT [OUTPUT]]
+
+   The ‘-G’ (or its equivalent: ‘--traditional’) option disables all GNU
+extensions and reverts to traditional mode, thus introducing some
+limitations and changing several of the program’s default option values.
+When ‘-G’ is not specified, GNU extensions are always enabled.  GNU
+extensions to ‘ptx’ are documented wherever appropriate in this
+document.  *Note Compatibility in ptx::, for the full list.
+
+   Individual options are explained in the following sections.
+
+   When GNU extensions are enabled, there may be zero, one or several
+FILEs after the options.  If there is no FILE, the program reads the
+standard input.  If there is one or several FILEs, they give the name of
+input files which are all read in turn, as if all the input files were
+concatenated.  However, there is a full contextual break between each
+file and, when automatic referencing is requested, file names and line
+numbers refer to individual text input files.  In all cases, the program
+outputs the permuted index to the standard output.
+
+   When GNU extensions are _not_ enabled, that is, when the program
+operates in traditional mode, there may be zero, one or two parameters
+besides the options.  If there are no parameters, the program reads the
+standard input and outputs the permuted index to the standard output.
+If there is only one parameter, it names the text INPUT to be read
+instead of the standard input.  If two parameters are given, they give
+respectively the name of the INPUT file to read and the name of the
+OUTPUT file to produce.  _Be very careful_ to note that, in this case,
+the contents of file given by the second parameter is destroyed.  This
+behavior is dictated by System V ‘ptx’ compatibility; GNU Standards
+normally discourage output parameters not introduced by an option.
+
+   Note that for _any_ file named as the value of an option or as an
+input text file, a single dash ‘-’ may be used, in which case standard
+input is assumed.  However, it would not make sense to use this
+convention more than once per program invocation.
+
+* Menu:
+
+* General options in ptx::      Options which affect general program behavior.
+* Charset selection in ptx::    Underlying character set considerations.
+* Input processing in ptx::     Input fields, contexts, and keyword selection.
+* Output formatting in ptx::    Types of output format, and sizing the fields.
+* Compatibility in ptx::
+
+
+File: coreutils.info,  Node: General options in ptx,  Next: Charset selection in ptx,  Up: ptx invocation
+
+7.5.1 General options
+---------------------
+
+‘-G’
+‘--traditional’
+     As already explained, this option disables all GNU extensions to
+     ‘ptx’ and switches to traditional mode.
+
+‘--help’
+     Print a short help on standard output, then exit without further
+     processing.
+
+‘--version’
+     Print the program version on standard output, then exit without
+     further processing.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Charset selection in ptx,  Next: Input processing in ptx,  Prev: General options in ptx,  Up: ptx invocation
+
+7.5.2 Charset selection
+-----------------------
+
+As it is set up now, ‘ptx’ assumes that the input file is coded using
+8-bit characters, and it may not work well in multibyte locales.  In a
+single-byte locale, the default regular expression for a keyword allows
+foreign or diacriticized letters.  Keyword sorting, however, is still
+crude; it obeys the underlying character set ordering quite blindly.
+
+   The output of ‘ptx’ assumes the locale’s character encoding.  For
+example, with ‘ptx’’s ‘-T’ option, if the locale uses the Latin-1
+encoding you may need a LaTeX directive like
+‘\usepackage[latin1]{inputenc}’ to render non-ASCII characters
+correctly.
+
+‘-f’
+‘--ignore-case’
+     Fold lower case letters to upper case for sorting.
+
+
+File: coreutils.info,  Node: Input processing in ptx,  Next: Output formatting in ptx,  Prev: Charset selection in ptx,  Up: ptx invocation
+
+7.5.3 Word selection and input processing
+-----------------------------------------
+
+‘-b FILE’
+‘--break-file=FILE’
+
+     This option provides an alternative (to ‘-W’) method of describing
+     which characters make up words.  It introduces the name of a file
+     which contains a list of characters which can_not_ be part of one
+     word; this file is called the “Break file”.  Any character which is
+     not part of the Break file is a word constituent.  If both options
+     ‘-b’ and ‘-W’ are specified, then ‘-W’ has precedence and ‘-b’ is
+     ignored.
+
+     When GNU extensions are enabled, the only way to avoid newline as a
+     break character is to write all the break characters in the file
+     with no newline at all, not even at the end of the file.  When GNU
+     extensions are disabled, spaces, tabs and newlines are always
+     considered as break characters even if not included in the Break
+     file.
+
+‘-i FILE’
+‘--ignore-file=FILE’
+
+     The file associated with this option contains a list of words which
+     will never be taken as keywords in concordance output.  It is
+     called the “Ignore file”.  The file contains exactly one word in
+     each line; the end of line separation of words is not subject to
+     the value of the ‘-S’ option.
+
+‘-o FILE’
+‘--only-file=FILE’
+
+     The file associated with this option contains a list of words which
+     will be retained in concordance output; any word not mentioned in
+     this file is ignored.  The file is called the “Only file”.  The
+     file contains exactly one word in each line; the end of line
+     separation of words is not subject to the value of the ‘-S’ option.
+
+     There is no default for the Only file.  When both an Only file and
+     an Ignore file are specified, a word is considered a keyword only
+     if it is listed in the Only file and not in the Ignore file.
+
+‘-r’
+‘--references’
+
+     On each input line, the leading sequence of non-white space
+     characters will be taken to be a reference that has the purpose of
+     identifying this input line in the resulting permuted index.  *Note
+     Output formatting in ptx::, for more information about reference
+     production.  Using this option changes the default value for option
+     ‘-S’.
+
+     Using this option, the program does not try very hard to remove
+     references from contexts in output, but it succeeds in doing so
+     _when_ the context ends exactly at the newline.  If option ‘-r’ is
+     used with ‘-S’ default value, or when GNU extensions are disabled,
+     this condition is always met and references are completely excluded
+     from the output contexts.
+
+‘-S REGEXP’
+‘--sentence-regexp=REGEXP’
+
+     This option selects which regular expression will describe the end
+     of a line or the end of a sentence.  In fact, this regular
+     expression is not the only distinction between end of lines or end
+     of sentences, and input line boundaries have no special
+     significance outside this option.  By default, when GNU extensions
+     are enabled and if ‘-r’ option is not used, end of sentences are
+     used.  In this case, this REGEX is imported from GNU Emacs:
+
+          [.?!][]\"')}]*\\($\\|\t\\|  \\)[ \t\n]*
+
+     Whenever GNU extensions are disabled or if ‘-r’ option is used, end
+     of lines are used; in this case, the default REGEXP is just:
+
+          \n
+
+     Using an empty REGEXP is equivalent to completely disabling end of
+     line or end of sentence recognition.  In this case, the whole file
+     is considered to be a single big line or sentence.  The user might
+     want to disallow all truncation flag generation as well, through
+     option ‘-F ""’.  *Note Syntax of Regular Expressions:
+     (emacs)Regexps.
+
+     When the keywords happen to be near the beginning of the input line
+     or sentence, this often creates an unused area at the beginning of
+     the output context line; when the keywords happen to be near the
+     end of the input line or sentence, this often creates an unused
+     area at the end of the output context line.  The program tries to
+     fill those unused areas by wrapping around context in them; the
+     tail of the input line or sentence is used to fill the unused area
+     on the left of the output line; the head of the input line or
+     sentence is used to fill the unused area on the right of the output
+     line.
+
+     As a matter of convenience to the user, many usual backslashed
+     escape sequences from the C language are recognized and converted
+     to the corresponding characters by ‘ptx’ itself.
+
+‘-W REGEXP’
+‘--word-regexp=REGEXP’
+
+     This option selects which regular expression will describe each
+     keyword.  By default, if GNU extensions are enabled, a word is a
+     sequence of letters; the REGEXP used is ‘\w+’.  When GNU extensions
+     are disabled, a word is by default anything which ends with a
+     space, a tab or a newline; the REGEXP used is ‘[^ \t\n]+’.
+
+     An empty REGEXP is equivalent to not using this option.  *Note
+     Syntax of Regular Expressions: (emacs)Regexps.
+
+     As a matter of convenience to the user, many usual backslashed
+     escape sequences, as found in the C language, are recognized and
+     converted to the corresponding characters by ‘ptx’ itself.
+
+
+File: coreutils.info,  Node: Output formatting in ptx,  Next: Compatibility in ptx,  Prev: Input processing in ptx,  Up: ptx invocation
+
+7.5.4 Output formatting
+-----------------------
+
+Output format is mainly controlled by the ‘-O’ and ‘-T’ options
+described in the table below.  When neither ‘-O’ nor ‘-T’ are selected,
+and if GNU extensions are enabled, the program chooses an output format
+suitable for a dumb terminal.  Each keyword occurrence is output to the
+center of one line, surrounded by its left and right contexts.  Each
+field is properly justified, so the concordance output can be readily
+observed.  As a special feature, if automatic references are selected by
+option ‘-A’ and are output before the left context, that is, if option
+‘-R’ is _not_ selected, then a colon is added after the reference; this
+nicely interfaces with GNU Emacs ‘next-error’ processing.  In this
+default output format, each white space character, like newline and tab,
+is merely changed to exactly one space, with no special attempt to
+compress consecutive spaces.  This might change in the future.  Except
+for those white space characters, every other character of the
+underlying set of 256 characters is transmitted verbatim.
+
+   Output format is further controlled by the following options.
+
+‘-g NUMBER’
+‘--gap-size=NUMBER’
+
+     Select the size of the minimum white space gap between the fields
+     on the output line.
+
+‘-w NUMBER’
+‘--width=NUMBER’
+
+     Select the maximum output width of each final line.  If references
+     are used, they are included or excluded from the maximum output
+     width depending on the value of option ‘-R’.  If this option is not
+     selected, that is, when references are output before the left
+     context, the maximum output width takes into account the maximum
+     length of all references.  If this option is selected, that is,
+     when references are output after the right context, the maximum
+     output width does not take into account the space taken by
+     references, nor the gap that precedes them.
+
+‘-A’
+‘--auto-reference’
+
+     Select automatic references.  Each input line will have an
+     automatic reference made up of the file name and the line ordinal,
+     with a single colon between them.  However, the file name will be
+     empty when standard input is being read.  If both ‘-A’ and ‘-r’ are
+     selected, then the input reference is still read and skipped, but
+     the automatic reference is used at output time, overriding the
+     input reference.
+
+‘-R’
+‘--right-side-refs’
+
+     In the default output format, when option ‘-R’ is not used, any
+     references produced by the effect of options ‘-r’ or ‘-A’ are
+     placed to the far right of output lines, after the right context.
+     With default output format, when the ‘-R’ option is specified,
+     references are rather placed at the beginning of each output line,
+     before the left context.  For any other output format, option ‘-R’
+     is ignored, with one exception: with ‘-R’ the width of references
+     is _not_ taken into account in total output width given by ‘-w’.
+
+     This option is automatically selected whenever GNU extensions are
+     disabled.
+
+‘-F STRING’
+‘--flag-truncation=STRING’
+
+     This option will request that any truncation in the output be
+     reported using the string STRING.  Most output fields theoretically
+     extend towards the beginning or the end of the current line, or
+     current sentence, as selected with option ‘-S’.  But there is a
+     maximum allowed output line width, changeable through option ‘-w’,
+     which is further divided into space for various output fields.
+     When a field has to be truncated because it cannot extend beyond
+     the beginning or the end of the current line to fit in, then a
+     truncation occurs.  By default, the string used is a single slash,
+     as in ‘-F /’.
+
+     STRING may have more than one character, as in ‘-F ...’.  Also, in
+     the particular case when STRING is empty (‘-F ""’), truncation
+     flagging is disabled, and no truncation marks are appended in this
+     case.
+
+     As a matter of convenience to the user, many usual backslashed
+     escape sequences, as found in the C language, are recognized and
+     converted to the corresponding characters by ‘ptx’ itself.
+
+‘-M STRING’
+‘--macro-name=STRING’
+
+     Select another STRING to be used instead of ‘xx’, while generating
+     output suitable for ‘nroff’, ‘troff’ or TeX.
+
+‘-O’
+‘--format=roff’
+
+     Choose an output format suitable for ‘nroff’ or ‘troff’ processing.
+     Each output line will look like:
+
+          .xx "TAIL" "BEFORE" "KEYWORD_AND_AFTER" "HEAD" "REF"
+
+     so it will be possible to write a ‘.xx’ roff macro to take care of
+     the output typesetting.  This is the default output format when GNU
+     extensions are disabled.  Option ‘-M’ can be used to change ‘xx’ to
+     another macro name.
+
+     In this output format, each non-graphical character, like newline
+     and tab, is merely changed to exactly one space, with no special
+     attempt to compress consecutive spaces.  Each quote character ‘"’
+     is doubled so it will be correctly processed by ‘nroff’ or ‘troff’.
+
+‘-T’
+‘--format=tex’
+
+     Choose an output format suitable for TeX processing.  Each output
+     line will look like:
+
+          \xx {TAIL}{BEFORE}{KEYWORD}{AFTER}{HEAD}{REF}
+
+     so it will be possible to write a ‘\xx’ definition to take care of
+     the output typesetting.  Note that when references are not being
+     produced, that is, neither option ‘-A’ nor option ‘-r’ is selected,
+     the last parameter of each ‘\xx’ call is inhibited.  Option ‘-M’
+     can be used to change ‘xx’ to another macro name.
+
+     In this output format, some special characters, like ‘$’, ‘%’, ‘&’,
+     ‘#’ and ‘_’ are automatically protected with a backslash.  Curly
+     brackets ‘{’, ‘}’ are protected with a backslash and a pair of
+     dollar signs (to force mathematical mode).  The backslash itself
+     produces the sequence ‘\backslash{}’.  Circumflex and tilde
+     diacritical marks produce the sequence ‘^\{ }’ and ‘~\{ }’
+     respectively.  Other diacriticized characters of the underlying
+     character set produce an appropriate TeX sequence as far as
+     possible.  The other non-graphical characters, like newline and
+     tab, and all other characters which are not part of ASCII, are
+     merely changed to exactly one space, with no special attempt to
+     compress consecutive spaces.  Let me know how to improve this
+     special character processing for TeX.
+
+
+File: coreutils.info,  Node: Compatibility in ptx,  Prev: Output formatting in ptx,  Up: ptx invocation
+
+7.5.5 The GNU extensions to ‘ptx’
+---------------------------------
+
+This version of ‘ptx’ contains a few features which do not exist in
+System V ‘ptx’.  These extra features are suppressed by using the ‘-G’
+command line option, unless overridden by other command line options.
+Some GNU extensions cannot be recovered by overriding, so the simple
+rule is to avoid ‘-G’ if you care about GNU extensions.  Here are the
+differences between this program and System V ‘ptx’.
+
+   • This program can read many input files at once, it always writes
+     the resulting concordance on standard output.  On the other hand,
+     System V ‘ptx’ reads only one file and sends the result to standard
+     output or, if a second FILE parameter is given on the command, to
+     that FILE.
+
+     Having output parameters not introduced by options is a dangerous
+     practice which GNU avoids as far as possible.  So, for using ‘ptx’
+     portably between GNU and System V, you should always use it with a
+     single input file, and always expect the result on standard output.
+     You might also want to automatically configure in a ‘-G’ option to
+     ‘ptx’ calls in products using ‘ptx’, if the configurator finds that
+     the installed ‘ptx’ accepts ‘-G’.
+
+   • The only options available in System V ‘ptx’ are options ‘-b’,
+     ‘-f’, ‘-g’, ‘-i’, ‘-o’, ‘-r’, ‘-t’ and ‘-w’.  All other options are
+     GNU extensions and are not repeated in this enumeration.  Moreover,
+     some options have a slightly different meaning when GNU extensions
+     are enabled, as explained below.
+
+   • By default, concordance output is not formatted for ‘troff’ or
+     ‘nroff’.  It is rather formatted for a dumb terminal.  ‘troff’ or
+     ‘nroff’ output may still be selected through option ‘-O’.
+
+   • Unless ‘-R’ option is used, the maximum reference width is
+     subtracted from the total output line width.  With GNU extensions
+     disabled, width of references is not taken into account in the
+     output line width computations.
+
+   • All 256 bytes, even ASCII NUL bytes, are always read and processed
+     from input file with no adverse effect, even if GNU extensions are
+     disabled.  However, System V ‘ptx’ does not accept 8-bit
+     characters, a few control characters are rejected, and the tilde
+     ‘~’ is also rejected.
+
+   • Input line length is only limited by available memory, even if GNU
+     extensions are disabled.  However, System V ‘ptx’ processes only
+     the first 200 characters in each line.
+
+   • The break (non-word) characters default to be every character
+     except all letters of the underlying character set, diacriticized
+     or not.  When GNU extensions are disabled, the break characters
+     default to space, tab and newline only.
+
+   • The program makes better use of output line width.  If GNU
+     extensions are disabled, the program rather tries to imitate System
+     V ‘ptx’, but still, there are some slight disposition glitches this
+     program does not completely reproduce.
+
+   • The user can specify both an Ignore file and an Only file.  This is
+     not allowed with System V ‘ptx’.
+
+
+File: coreutils.info,  Node: tsort invocation,  Prev: ptx invocation,  Up: Operating on sorted files
+
+7.6 ‘tsort’: Topological sort
+=============================
+
+‘tsort’ performs a topological sort on the given FILE, or standard input
+if no input file is given or for a FILE of ‘-’.  For more details and
+some history, see *note tsort background::.  Synopsis:
+
+     tsort [OPTION] [FILE]
+
+   ‘tsort’ reads its input as pairs of strings, separated by blanks,
+indicating a partial ordering.  The output is a total ordering that
+corresponds to the given partial ordering.
+
+   For example
+
+     tsort <<EOF
+     a b c
+     d
+     e f
+     b c d e
+     EOF
+
+will produce the output
+
+     a
+     b
+     c
+     d
+     e
+     f
+
+   Consider a more realistic example.  You have a large set of functions
+all in one file, and they may all be declared static except one.
+Currently that one (say ‘main’) is the first function defined in the
+file, and the ones it calls directly follow it, followed by those they
+call, etc.  Let’s say that you are determined to take advantage of
+prototypes, so you have to choose between declaring all of those
+functions (which means duplicating a lot of information from the
+definitions) and rearranging the functions so that as many as possible
+are defined before they are used.  One way to automate the latter
+process is to get a list for each function of the functions it calls
+directly.  Many programs can generate such lists.  They describe a call
+graph.  Consider the following list, in which a given line indicates
+that the function on the left calls the one on the right directly.
+
+     main parse_options
+     main tail_file
+     main tail_forever
+     tail_file pretty_name
+     tail_file write_header
+     tail_file tail
+     tail_forever recheck
+     tail_forever pretty_name
+     tail_forever write_header
+     tail_forever dump_remainder
+     tail tail_lines
+     tail tail_bytes
+     tail_lines start_lines
+     tail_lines dump_remainder
+     tail_lines file_lines
+     tail_lines pipe_lines
+     tail_bytes xlseek
+     tail_bytes start_bytes
+     tail_bytes dump_remainder
+     tail_bytes pipe_bytes
+     file_lines dump_remainder
+     recheck pretty_name
+
+   then you can use ‘tsort’ to produce an ordering of those functions
+that satisfies your requirement.
+
+     example$ tsort call-graph | tac
+     dump_remainder
+     start_lines
+     file_lines
+     pipe_lines
+     xlseek
+     start_bytes
+     pipe_bytes
+     tail_lines
+     tail_bytes
+     pretty_name
+     write_header
+     tail
+     recheck
+     parse_options
+     tail_file
+     tail_forever
+     main
+
+   ‘tsort’ detects any cycles in the input and writes the first cycle
+encountered to standard error.
+
+   Note that for a given partial ordering, generally there is no unique
+total ordering.  In the context of the call graph above, the function
+‘parse_options’ may be placed anywhere in the list as long as it
+precedes ‘main’.
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+* Menu:
+
+* tsort background::            Where tsort came from.
+
+
+File: coreutils.info,  Node: tsort background,  Up: tsort invocation
+
+7.6.1 ‘tsort’: Background
+-------------------------
+
+‘tsort’ exists because very early versions of the Unix linker processed
+an archive file exactly once, and in order.  As ‘ld’ read each object in
+the archive, it decided whether it was needed in the program based on
+whether it defined any symbols which were undefined at that point in the
+link.
+
+   This meant that dependencies within the archive had to be handled
+specially.  For example, ‘scanf’ probably calls ‘read’.  That means that
+in a single pass through an archive, it was important for ‘scanf.o’ to
+appear before read.o, because otherwise a program which calls ‘scanf’
+but not ‘read’ might end up with an unexpected unresolved reference to
+‘read’.
+
+   The way to address this problem was to first generate a set of
+dependencies of one object file on another.  This was done by a shell
+script called ‘lorder’.  The GNU tools don’t provide a version of
+lorder, as far as I know, but you can still find it in BSD
+distributions.
+
+   Then you ran ‘tsort’ over the ‘lorder’ output, and you used the
+resulting sort to define the order in which you added objects to the
+archive.
+
+   This whole procedure has been obsolete since about 1980, because Unix
+archives now contain a symbol table (traditionally built by ‘ranlib’,
+now generally built by ‘ar’ itself), and the Unix linker uses the symbol
+table to effectively make multiple passes over an archive file.
+
+   Anyhow, that’s where tsort came from.  To solve an old problem with
+the way the linker handled archive files, which has since been solved in
+different ways.
+
+
+File: coreutils.info,  Node: Operating on fields,  Next: Operating on characters,  Prev: Operating on sorted files,  Up: Top
+
+8 Operating on fields
+*********************
+
+* Menu:
+
+* cut invocation::              Print selected parts of lines.
+* paste invocation::            Merge lines of files.
+* join invocation::             Join lines on a common field.
+
+
+File: coreutils.info,  Node: cut invocation,  Next: paste invocation,  Up: Operating on fields
+
+8.1 ‘cut’: Print selected parts of lines
+========================================
+
+‘cut’ writes to standard output selected parts of each line of each
+input file, or standard input if no files are given or for a file name
+of ‘-’.  Synopsis:
+
+     cut OPTION... [FILE]...
+
+   In the table which follows, the BYTE-LIST, CHARACTER-LIST, and
+FIELD-LIST are one or more numbers or ranges (two numbers separated by a
+dash) separated by commas.  Bytes, characters, and fields are numbered
+starting at 1.  Incomplete ranges may be given: ‘-M’ means ‘1-M’; ‘N-’
+means ‘N’ through end of line or last field.  The list elements can be
+repeated, can overlap, and can be specified in any order; but the
+selected input is written in the same order that it is read, and is
+written exactly once.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b BYTE-LIST’
+‘--bytes=BYTE-LIST’
+     Select for printing only the bytes in positions listed in
+     BYTE-LIST.  Tabs and backspaces are treated like any other
+     character; they take up 1 byte.  If an output delimiter is
+     specified, (see the description of ‘--output-delimiter’), then
+     output that string between ranges of selected bytes.
+
+‘-c CHARACTER-LIST’
+‘--characters=CHARACTER-LIST’
+     Select for printing only the characters in positions listed in
+     CHARACTER-LIST.  The same as ‘-b’ for now, but internationalization
+     will change that.  Tabs and backspaces are treated like any other
+     character; they take up 1 character.  If an output delimiter is
+     specified, (see the description of ‘--output-delimiter’), then
+     output that string between ranges of selected bytes.
+
+‘-f FIELD-LIST’
+‘--fields=FIELD-LIST’
+     Select for printing only the fields listed in FIELD-LIST.  Fields
+     are separated by a TAB character by default.  Also print any line
+     that contains no delimiter character, unless the ‘--only-delimited’
+     (‘-s’) option is specified.
+
+     Note ‘awk’ supports more sophisticated field processing, like
+     reordering fields, and handling fields aligned with blank
+     characters.  By default ‘awk’ uses (and discards) runs of blank
+     characters to separate fields, and ignores leading and trailing
+     blanks.
+          awk '{print $2}'      # print the second field
+          awk '{print $(NF-1)}' # print the penultimate field
+          awk '{print $2,$1}'   # reorder the first two fields
+     Note while ‘cut’ accepts field specifications in arbitrary order,
+     output is always in the order encountered in the file.
+
+     In the unlikely event that ‘awk’ is unavailable, one can use the
+     ‘join’ command, to process blank characters as ‘awk’ does above.
+          join -a1 -o 1.2     - /dev/null # print the second field
+          join -a1 -o 1.2,1.1 - /dev/null # reorder the first two fields
+
+‘-d INPUT_DELIM_BYTE’
+‘--delimiter=INPUT_DELIM_BYTE’
+     With ‘-f’, use the first byte of INPUT_DELIM_BYTE as the input
+     fields separator (default is TAB).
+
+‘-n’
+     Do not split multi-byte characters (no-op for now).
+
+‘-s’
+‘--only-delimited’
+     For ‘-f’, do not print lines that do not contain the field
+     separator character.  Normally, any line without a field separator
+     is printed verbatim.
+
+‘--output-delimiter=OUTPUT_DELIM_STRING’
+     With ‘-f’, output fields are separated by OUTPUT_DELIM_STRING.  The
+     default with ‘-f’ is to use the input delimiter.  When using ‘-b’
+     or ‘-c’ to select ranges of byte or character offsets (as opposed
+     to ranges of fields), output OUTPUT_DELIM_STRING between
+     non-overlapping ranges of selected bytes.
+
+‘--complement’
+     This option is a GNU extension.  Select for printing the complement
+     of the bytes, characters or fields selected with the ‘-b’, ‘-c’ or
+     ‘-f’ options.  In other words, do _not_ print the bytes, characters
+     or fields specified via those options.  This option is useful when
+     you have many fields and want to print all but a few of them.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: paste invocation,  Next: join invocation,  Prev: cut invocation,  Up: Operating on fields
+
+8.2 ‘paste’: Merge lines of files
+=================================
+
+‘paste’ writes to standard output lines consisting of sequentially
+corresponding lines of each given file, separated by a TAB character.
+Standard input is used for a file name of ‘-’ or if no input files are
+given.
+
+   Synopsis:
+
+     paste [OPTION]... [FILE]...
+
+   For example, with:
+     $ cat num2
+     1
+     2
+     $ cat let3
+     a
+     b
+     c
+
+   Take lines sequentially from each file:
+     $ paste num2 let3
+     1       a
+     2       b
+             c
+
+   Duplicate lines from a file:
+     $ paste num2 let3 num2
+     1       a      1
+     2       b      2
+             c
+
+   Intermix lines from standard input:
+     $ paste - let3 - < num2
+     1       a      2
+             b
+             c
+
+   Join consecutive lines with a space:
+     $ seq 4 | paste -d ' ' - -
+     1 2
+     3 4
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-s’
+‘--serial’
+     Paste the lines of one file at a time rather than one line from
+     each file.  Using the above example data:
+
+          $ paste -s num2 let3
+          1       2
+          a       b       c
+
+‘-d DELIM-LIST’
+‘--delimiters=DELIM-LIST’
+     Consecutively use the characters in DELIM-LIST instead of TAB to
+     separate merged lines.  When DELIM-LIST is exhausted, start again
+     at its beginning.  Using the above example data:
+
+          $ paste -d '%_' num2 let3 num2
+          1%a_1
+          2%b_2
+          %c_
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: join invocation,  Prev: paste invocation,  Up: Operating on fields
+
+8.3 ‘join’: Join lines on a common field
+========================================
+
+‘join’ writes to standard output a line for each pair of input lines
+that have identical join fields.  Synopsis:
+
+     join [OPTION]... FILE1 FILE2
+
+   Either FILE1 or FILE2 (but not both) can be ‘-’, meaning standard
+input.  FILE1 and FILE2 should be sorted on the join fields.
+
+     $ cat file1
+     a 1
+     b 2
+     e 5
+
+     $ cat file2
+     a X
+     e Y
+     f Z
+
+     $ join file1 file2
+     a 1 X
+     e 5 Y
+
+‘join’’s default behavior (when no options are given):
+   • the join field is the first field in each line;
+   • fields in the input are separated by one or more blanks, with
+     leading blanks on the line ignored;
+   • fields in the output are separated by a space;
+   • each output line consists of the join field, the remaining fields
+     from FILE1, then the remaining fields from FILE2.
+
+* Menu:
+
+* General options in join::      Options which affect general program behavior.
+* Sorting files for join::       Using ‘sort’ before ‘join’.
+* Working with fields::          Joining on different fields.
+* Paired and unpaired lines::    Controlling ‘join’’s field matching.
+* Header lines::                 Working with header lines in files.
+* Set operations::               Union, Intersection and Difference of files.
+
+
+File: coreutils.info,  Node: General options in join,  Next: Sorting files for join,  Up: join invocation
+
+8.3.1 General options
+---------------------
+
+The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a FILE-NUMBER’
+     Print a line for each unpairable line in file FILE-NUMBER (either
+     ‘1’ or ‘2’), in addition to the normal output.
+
+‘--check-order’
+     Fail with an error message if either input file is wrongly ordered.
+
+‘--nocheck-order’
+     Do not check that both input files are in sorted order.  This is
+     the default.
+
+‘-e STRING’
+     Replace those output fields that are missing in the input with
+     STRING.  I.e., missing fields specified with the ‘-12jo’ options.
+
+‘--header’
+     Treat the first line of each input file as a header line.  The
+     header lines will be joined and printed as the first output line.
+     If ‘-o’ is used to specify output format, the header line will be
+     printed according to the specified format.  The header lines will
+     not be checked for ordering even if ‘--check-order’ is specified.
+     Also if the header lines from each file do not match, the heading
+     fields from the first file will be used.
+
+‘-i’
+‘--ignore-case’
+     Ignore differences in case when comparing keys.  With this option,
+     the lines of the input files must be ordered in the same way.  Use
+     ‘sort -f’ to produce this ordering.
+
+‘-1 FIELD’
+     Join on field FIELD (a positive integer) of file 1.
+
+‘-2 FIELD’
+     Join on field FIELD (a positive integer) of file 2.
+
+‘-j FIELD’
+     Equivalent to ‘-1 FIELD -2 FIELD’.
+
+‘-o FIELD-LIST’
+‘-o auto’
+     If the keyword ‘auto’ is specified, infer the output format from
+     the first line in each file.  This is the same as the default
+     output format but also ensures the same number of fields are output
+     for each line.  Missing fields are replaced with the ‘-e’ option
+     and extra fields are discarded.
+
+     Otherwise, construct each output line according to the format in
+     FIELD-LIST.  Each element in FIELD-LIST is either the single
+     character ‘0’ or has the form M.N where the file number, M, is ‘1’
+     or ‘2’ and N is a positive field number.
+
+     A field specification of ‘0’ denotes the join field.  In most
+     cases, the functionality of the ‘0’ field spec may be reproduced
+     using the explicit M.N that corresponds to the join field.
+     However, when printing unpairable lines (using either of the ‘-a’
+     or ‘-v’ options), there is no way to specify the join field using
+     M.N in FIELD-LIST if there are unpairable lines in both files.  To
+     give ‘join’ that functionality, POSIX invented the ‘0’ field
+     specification notation.
+
+     The elements in FIELD-LIST are separated by commas or blanks.
+     Blank separators typically need to be quoted for the shell.  For
+     example, the commands ‘join -o 1.2,2.2’ and ‘join -o '1.2 2.2'’ are
+     equivalent.
+
+     All output lines – including those printed because of any ‘-a’ or
+     ‘-v’ option – are subject to the specified FIELD-LIST.
+
+‘-t CHAR’
+     Use character CHAR as the input and output field separator.  Treat
+     as significant each occurrence of CHAR in the input file.  Use
+     ‘sort -t CHAR’, without the ‘-b’ option of ‘sort’, to produce this
+     ordering.  If ‘join -t ''’ is specified, the whole line is
+     considered, matching the default operation of sort.  If ‘-t '\0'’
+     is specified then the ASCII NUL character is used to delimit the
+     fields.
+
+‘-v FILE-NUMBER’
+     Print a line for each unpairable line in file FILE-NUMBER (either
+     ‘1’ or ‘2’), instead of the normal output.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).  Note with
+     ‘-z’ the newline character is treated as a field separator.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   If the ‘--check-order’ option is given, unsorted inputs will cause a
+fatal error message.  If the option ‘--nocheck-order’ is given, unsorted
+inputs will never cause an error message.  If neither of these options
+is given, wrongly sorted inputs are diagnosed only if an input file is
+found to contain unpairable lines, and when both input files are non
+empty.  If an input file is diagnosed as being unsorted, the ‘join’
+command will exit with a nonzero status (and the output should not be
+used).
+
+   Forcing ‘join’ to process wrongly sorted input files containing
+unpairable lines by specifying ‘--nocheck-order’ is not guaranteed to
+produce any particular output.  The output will probably not correspond
+with whatever you hoped it would be.
+
+
+File: coreutils.info,  Node: Sorting files for join,  Next: Working with fields,  Prev: General options in join,  Up: join invocation
+
+8.3.2 Pre-sorting
+-----------------
+
+‘join’ requires sorted input files.  Each input file should be sorted
+according to the key (=field/column number) used in ‘join’.  The
+recommended sorting option is ‘sort -k 1b,1’ (assuming the desired key
+is in the first column).
+
+Typical usage:
+     $ sort -k 1b,1 file1 > file1.sorted
+     $ sort -k 1b,1 file2 > file2.sorted
+     $ join file1.sorted file2.sorted > file3
+
+   Normally, the sort order is that of the collating sequence specified
+by the ‘LC_COLLATE’ locale.  Unless the ‘-t’ option is given, the sort
+comparison ignores blanks at the start of the join field, as in ‘sort
+-b’.  If the ‘--ignore-case’ option is given, the sort comparison
+ignores the case of characters in the join field, as in ‘sort -f’:
+
+     $ sort -k 1bf,1 file1 > file1.sorted
+     $ sort -k 1bf,1 file2 > file2.sorted
+     $ join --ignore-case file1.sorted file2.sorted > file3
+
+   The ‘sort’ and ‘join’ commands should use consistent locales and
+options if the output of ‘sort’ is fed to ‘join’.  You can use a command
+like ‘sort -k 1b,1’ to sort a file on its default join field, but if you
+select a non-default locale, join field, separator, or comparison
+options, then you should do so consistently between ‘join’ and ‘sort’.
+
+To avoid any locale-related issues, it is recommended to use the ‘C’
+locale for both commands:
+
+     $ LC_ALL=C sort -k 1b,1 file1 > file1.sorted
+     $ LC_ALL=C sort -k 1b,1 file2 > file2.sorted
+     $ LC_ALL=C join file1.sorted file2.sorted > file3
+
+
+File: coreutils.info,  Node: Working with fields,  Next: Paired and unpaired lines,  Prev: Sorting files for join,  Up: join invocation
+
+8.3.3 Working with fields
+-------------------------
+
+Use ‘-1’,‘-2’ to set the key fields for each of the input files.  Ensure
+the preceding ‘sort’ commands operated on the same fields.
+
+The following example joins two files, using the values from seventh
+field of the first file and the third field of the second file:
+
+     $ sort -k 7b,7 file1 > file1.sorted
+     $ sort -k 3b,3 file2 > file2.sorted
+     $ join -1 7 -2 3 file1.sorted file2.sorted > file3
+
+If the field number is the same for both files, use ‘-j’:
+
+     $ sort -k4b,4 file1 > file1.sorted
+     $ sort -k4b,4 file2 > file2.sorted
+     $ join -j4    file1.sorted file2.sorted > file3
+
+Both ‘sort’ and ‘join’ operate of whitespace-delimited fields.  To
+specify a different delimiter, use ‘-t’ in _both_:
+
+     $ sort -t, -k3b,3 file1 > file1.sorted
+     $ sort -t, -k3b,3 file2 > file2.sorted
+     $ join -t, -j3    file1.sorted file2.sorted > file3
+
+To specify a tab (ASCII 0x09) character instead of whitespace, use:(1)
+
+     $ sort -t$'\t' -k3b,3 file1 > file1.sorted
+     $ sort -t$'\t' -k3b,3 file2 > file2.sorted
+     $ join -t$'\t' -j3    file1.sorted file2.sorted > file3
+
+If ‘join -t ''’ is specified then the whole line is considered which
+matches the default operation of sort:
+
+     $ sort file1 > file1.sorted
+     $ sort file2 > file2.sorted
+     $ join -t '' file1.sorted file2.sorted > file3
+
+   ---------- Footnotes ----------
+
+   (1) the ‘$'\t'’ is supported in most modern shells.  For older
+shells, use a literal tab.
+
+
+File: coreutils.info,  Node: Paired and unpaired lines,  Next: Header lines,  Prev: Working with fields,  Up: join invocation
+
+8.3.4 Controlling ‘join’’s field matching
+-----------------------------------------
+
+In this section the ‘sort’ commands are omitted for brevity.  Sorting
+the files before joining is still required.
+
+   ‘join’’s default behavior is to print only lines common to both input
+files.  Use ‘-a’ and ‘-v’ to print unpairable lines from one or both
+files.
+
+All examples below use the following two (pre-sorted) input files:
+
+     $ cat file1                          $ cat file2
+     a 1                                  a A
+     b 2                                  c C
+
+Command                              Outcome
+                                     
+--------------------------------------------------------------------------
+     $ join file1 file2              common lines (_intersection_)
+     a 1 A                           
+     $ join -a 1 file1 file2         common lines _and_ unpaired lines
+     a 1 A                           from the first file
+     b 2                             
+     $ join -a 2 file1 file2         common lines _and_ unpaired lines
+     a 1 A                           from the second file
+     c C                             
+     $ join -a 1 -a 2 file1 file2    all lines (paired and unpaired)
+     a 1 A                           from both files (_union_).
+     b 2                             see note below regarding ‘-o
+     c C                             auto’.
+                                     
+     $ join -v 1 file1 file2         unpaired lines from the first file
+     b 2                             (_difference_)
+                                     
+     $ join -v 2 file1 file2         unpaired lines from the second
+     c C                             file (_difference_)
+                                     
+     $ join -v 1 -v 2 file1 file2    unpaired lines from both files,
+     b 2                             omitting common lines (_symmetric
+     c C                             difference_).
+                                     
+
+The ‘-o auto -e X’ options are useful when dealing with unpaired lines.
+The following example prints all lines (common and unpaired) from both
+files.  Without ‘-o auto’ it is not easy to discern which fields
+originate from which file:
+
+     $ join -a 1 -a 2 file1 file2
+     a 1 A
+     b 2
+     c C
+
+     $ join -o auto -e X -a 1 -a 2 file1 file2
+     a 1 A
+     b 2 X
+     c X C
+
+   If the input has no unpairable lines, a GNU extension is available;
+the sort order can be any order that considers two fields to be equal if
+and only if the sort comparison described above considers them to be
+equal.  For example:
+
+     $ cat file1
+     a a1
+     c c1
+     b b1
+
+     $ cat file2
+     a a2
+     c c2
+     b b2
+
+     $ join file1 file2
+     a a1 a2
+     c c1 c2
+     b b1 b2
+
+
+File: coreutils.info,  Node: Header lines,  Next: Set operations,  Prev: Paired and unpaired lines,  Up: join invocation
+
+8.3.5 Header lines
+------------------
+
+The ‘--header’ option can be used when the files to join have a header
+line which is not sorted:
+
+     $ cat file1
+     Name     Age
+     Alice    25
+     Charlie  34
+
+     $ cat file2
+     Name   Country
+     Alice  France
+     Bob    Spain
+
+     $ join --header -o auto -e NA -a1 -a2 file1 file2
+     Name     Age   Country
+     Alice    25    France
+     Bob      NA    Spain
+     Charlie  34    NA
+
+   To sort a file with a header line, use GNU ‘sed -u’.  The following
+example sort the files but keeps the first line of each file in place:
+
+     $ ( sed -u 1q ; sort -k2b,2 ) < file1 > file1.sorted
+     $ ( sed -u 1q ; sort -k2b,2 ) < file2 > file2.sorted
+     $ join --header -o auto -e NA -a1 -a2 file1.sorted file2.sorted > file3
+
+
+File: coreutils.info,  Node: Set operations,  Prev: Header lines,  Up: join invocation
+
+8.3.6 Union, Intersection and Difference of files
+-------------------------------------------------
+
+Combine ‘sort’, ‘uniq’ and ‘join’ to perform the equivalent of set
+operations on files:
+
+Command                              outcome
+--------------------------------------------------------------------------
+‘sort -u file1 file2’                Union of unsorted files
+                                     
+‘sort file1 file2 | uniq -d’         Intersection of unsorted files
+                                     
+‘sort file1 file1 file2 | uniq -u’   Difference of unsorted files
+                                     
+‘sort file1 file2 | uniq -u’         Symmetric Difference of unsorted
+                                     files
+                                     
+‘join -t '' -a1 -a2 file1 file2’     Union of sorted files
+                                     
+‘join -t '' file1 file2’             Intersection of sorted files
+                                     
+‘join -t '' -v2 file1 file2’         Difference of sorted files
+                                     
+‘join -t '' -v1 -v2 file1 file2’     Symmetric Difference of sorted
+                                     files
+                                     
+
+   All examples above operate on entire lines and not on specific
+fields: ‘sort’ without ‘-k’ and ‘join -t ''’ both consider entire lines
+as the key.
+
+
+File: coreutils.info,  Node: Operating on characters,  Next: Directory listing,  Prev: Operating on fields,  Up: Top
+
+9 Operating on characters
+*************************
+
+These commands operate on individual characters.
+
+* Menu:
+
+* tr invocation::               Translate, squeeze, and/or delete characters.
+* expand invocation::           Convert tabs to spaces.
+* unexpand invocation::         Convert spaces to tabs.
+
+
+File: coreutils.info,  Node: tr invocation,  Next: expand invocation,  Up: Operating on characters
+
+9.1 ‘tr’: Translate, squeeze, and/or delete characters
+======================================================
+
+Synopsis:
+
+     tr [OPTION]... STRING1 [STRING2]
+
+   ‘tr’ copies standard input to standard output, performing one of the
+following operations:
+
+   • translate, and optionally squeeze repeated characters in the
+     result,
+   • squeeze repeated characters,
+   • delete characters,
+   • delete characters, then squeeze repeated characters from the
+     result.
+
+   The STRING1 and STRING2 operands define arrays of characters ARRAY1
+and ARRAY2.  By default ARRAY1 lists input characters that ‘tr’ operates
+on, and ARRAY2 lists corresponding translations.  In some cases the
+second operand is omitted.
+
+   The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands.
+
+‘-c’
+‘-C’
+‘--complement’
+     Instead of ARRAY1, use its complement (all characters not specified
+     by STRING1), in ascending order.  Use this option with caution in
+     multibyte locales where its meaning is not always clear or
+     portable; see *note Character arrays::.
+
+‘-d’
+‘--delete’
+     Delete characters in ARRAY1; do not translate.
+
+‘-s’
+‘--squeeze-repeats’
+     Replace each sequence of a repeated character that is listed in the
+     last specified ARRAY, with a single occurrence of that character.
+
+‘-t’
+‘--truncate-set1’
+     Truncate ARRAY1 to the length of ARRAY2.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+* Menu:
+
+* Character arrays::            Specifying arrays of characters.
+* Translating::                 Changing characters to other characters.
+* Squeezing and deleting::      Removing characters.
+
+
+File: coreutils.info,  Node: Character arrays,  Next: Translating,  Up: tr invocation
+
+9.1.1 Specifying arrays of characters
+-------------------------------------
+
+The STRING1 and STRING2 operands are not regular expressions, even
+though they may look similar.  Instead, they merely represent arrays of
+characters.  As a GNU extension to POSIX, an empty string operand
+represents an empty array of characters.
+
+   The interpretation of STRING1 and STRING2 depends on locale.  GNU
+‘tr’ fully supports only safe single-byte locales, where each possible
+input byte represents a single character.  Unfortunately, this means GNU
+‘tr’ will not handle commands like ‘tr ö Ł’ the way you might expect,
+since (assuming a UTF-8 encoding) this is equivalent to ‘tr '\303\266'
+'\305\201'’ and GNU ‘tr’ will simply transliterate all ‘\303’ bytes to
+‘\305’ bytes, etc.  POSIX does not clearly specify the behavior of ‘tr’
+in locales where characters are represented by byte sequences instead of
+by individual bytes, or where data might contain invalid bytes that are
+encoding errors.  To avoid problems in this area, you can run ‘tr’ in a
+safe single-byte locale by using a shell command like ‘LC_ALL=C tr’
+instead of plain ‘tr’.
+
+   Although most characters simply represent themselves in STRING1 and
+STRING2, the strings can contain shorthands listed below, for
+convenience.  Some shorthands can be used only in STRING1 or STRING2, as
+noted below.
+
+Backslash escapes
+
+     The following backslash escape sequences are recognized:
+
+     ‘\a’
+          Bell (BEL, Control-G).
+     ‘\b’
+          Backspace (BS, Control-H).
+     ‘\f’
+          Form feed (FF, Control-L).
+     ‘\n’
+          Newline (LF, Control-J).
+     ‘\r’
+          Carriage return (CR, Control-M).
+     ‘\t’
+          Tab (HT, Control-I).
+     ‘\v’
+          Vertical tab (VT, Control-K).
+     ‘\OOO’
+          The eight-bit byte with the value given by OOO, which is the
+          longest sequence of one to three octal digits following the
+          backslash.  For portability, OOO should represent a value that
+          fits in eight bits.  As a GNU extension to POSIX, if the value
+          would not fit, then only the first two digits of OOO are used,
+          e.g., ‘\400’ is equivalent to ‘\0400’ and represents a
+          two-byte sequence.
+     ‘\\’
+          A backslash.
+
+     It is an error if no character follows an unescaped backslash.  As
+     a GNU extension, a backslash followed by a character not listed
+     above is interpreted as that character, removing any special
+     significance; this can be used to escape the characters ‘[’ and ‘-’
+     when they would otherwise be special.
+
+Ranges
+
+     The notation ‘M-N’ expands to the characters from M through N, in
+     ascending order.  M should not collate after N; if it does, an
+     error results.  As an example, ‘0-9’ is the same as ‘0123456789’.
+
+     GNU ‘tr’ does not support the System V syntax that uses square
+     brackets to enclose ranges.  Translations specified in that format
+     sometimes work as expected, since the brackets are often
+     transliterated to themselves.  However, they should be avoided
+     because they sometimes behave unexpectedly.  For example, ‘tr -d
+     '[0-9]'’ deletes brackets as well as digits.
+
+     Many historically common and even accepted uses of ranges are not
+     fully portable.  For example, on EBCDIC hosts using the ‘A-Z’ range
+     will not do what most would expect because ‘A’ through ‘Z’ are not
+     contiguous as they are in ASCII.  One way to work around this is to
+     use character classes (see below).  Otherwise, it is most portable
+     (and most ugly) to enumerate the members of the ranges.
+
+Repeated characters
+
+     The notation ‘[C*N]’ in STRING2 expands to N copies of character C.
+     Thus, ‘[y*6]’ is the same as ‘yyyyyy’.  The notation ‘[C*]’ in
+     STRING2 expands to as many copies of C as are needed to make ARRAY2
+     as long as ARRAY1.  If N begins with ‘0’, it is interpreted in
+     octal, otherwise in decimal.  A zero-valued N is treated as if it
+     were absent.
+
+Character classes
+
+     The notation ‘[:CLASS:]’ expands to all characters in the
+     (predefined) class CLASS.  When the ‘--delete’ (‘-d’) and
+     ‘--squeeze-repeats’ (‘-s’) options are both given, any character
+     class can be used in STRING2.  Otherwise, only the character
+     classes ‘lower’ and ‘upper’ are accepted in STRING2, and then only
+     if the corresponding character class (‘upper’ and ‘lower’,
+     respectively) is specified in the same relative position in
+     STRING1.  Doing this specifies case conversion.  Except for case
+     conversion, a class’s characters appear in no particular order.
+     The class names are given below; an error results when an invalid
+     class name is given.
+
+     ‘alnum’
+          Letters and digits.
+     ‘alpha’
+          Letters.
+     ‘blank’
+          Horizontal whitespace.
+     ‘cntrl’
+          Control characters.
+     ‘digit’
+          Digits.
+     ‘graph’
+          Printable characters, not including space.
+     ‘lower’
+          Lowercase letters.
+     ‘print’
+          Printable characters, including space.
+     ‘punct’
+          Punctuation characters.
+     ‘space’
+          Horizontal or vertical whitespace.
+     ‘upper’
+          Uppercase letters.
+     ‘xdigit’
+          Hexadecimal digits.
+
+Equivalence classes
+
+     The syntax ‘[=C=]’ expands to all characters equivalent to C, in no
+     particular order.  These equivalence classes are allowed in STRING2
+     only when ‘--delete’ (‘-d’) and ‘--squeeze-repeats’ ‘-s’ are both
+     given.
+
+     Although equivalence classes are intended to support non-English
+     alphabets, there seems to be no standard way to define them or
+     determine their contents.  Therefore, they are not fully
+     implemented in GNU ‘tr’; each character’s equivalence class
+     consists only of that character, which is of no particular use.
+
+
+File: coreutils.info,  Node: Translating,  Next: Squeezing and deleting,  Prev: Character arrays,  Up: tr invocation
+
+9.1.2 Translating
+-----------------
+
+‘tr’ performs translation when STRING1 and STRING2 are both given and
+the ‘--delete’ (‘-d’) option is not given.  ‘tr’ translates each
+character of its input that is in ARRAY1 to the corresponding character
+in ARRAY2.  Characters not in ARRAY1 are passed through unchanged.
+
+   As a GNU extension to POSIX, when a character appears more than once
+in ARRAY1, only the final instance is used.  For example, these two
+commands are equivalent:
+
+     tr aaa xyz
+     tr a z
+
+   A common use of ‘tr’ is to convert lowercase characters to uppercase.
+This can be done in many ways.  Here are three of them:
+
+     tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
+     tr a-z A-Z
+     tr '[:lower:]' '[:upper:]'
+
+However, ranges like ‘a-z’ are not portable outside the C locale.
+
+   When ‘tr’ is performing translation, ARRAY1 and ARRAY2 typically have
+the same length.  If ARRAY1 is shorter than ARRAY2, the extra characters
+at the end of ARRAY2 are ignored.
+
+   On the other hand, making ARRAY1 longer than ARRAY2 is not portable;
+POSIX says that the result is undefined.  In this situation, BSD ‘tr’
+pads ARRAY2 to the length of ARRAY1 by repeating the last character of
+ARRAY2 as many times as necessary.  System V ‘tr’ truncates ARRAY1 to
+the length of ARRAY2.
+
+   By default, GNU ‘tr’ handles this case like BSD ‘tr’.  When the
+‘--truncate-set1’ (‘-t’) option is given, GNU ‘tr’ handles this case
+like the System V ‘tr’ instead.  This option is ignored for operations
+other than translation.
+
+   Acting like System V ‘tr’ in this case breaks the relatively common
+BSD idiom:
+
+     tr -cs A-Za-z0-9 '\012'
+
+because it converts only zero bytes (the first element in the complement
+of ARRAY1), rather than all non-alphanumerics, to newlines.
+
+By the way, the above idiom is not portable because it uses ranges, and
+it assumes that the octal code for newline is 012.  Here is a better way
+to write it:
+
+     tr -cs '[:alnum:]' '[\n*]'
+
+
+File: coreutils.info,  Node: Squeezing and deleting,  Prev: Translating,  Up: tr invocation
+
+9.1.3 Squeezing repeats and deleting
+------------------------------------
+
+When given just the ‘--delete’ (‘-d’) option, ‘tr’ removes any input
+characters that are in ARRAY1.
+
+   When given just the ‘--squeeze-repeats’ (‘-s’) option and not
+translating, ‘tr’ replaces each input sequence of a repeated character
+that is in ARRAY1 with a single occurrence of that character.
+
+   When given both ‘--delete’ and ‘--squeeze-repeats’, ‘tr’ first
+performs any deletions using ARRAY1, then squeezes repeats from any
+remaining characters using ARRAY2.
+
+   The ‘--squeeze-repeats’ option may also be used when translating, in
+which case ‘tr’ first performs translation, then squeezes repeats from
+any remaining characters using ARRAY2.
+
+   Here are some examples to illustrate various combinations of options:
+
+   • Remove all zero bytes:
+
+          tr -d '\0'
+
+   • Put all words on lines by themselves.  This converts all
+     non-alphanumeric characters to newlines, then squeezes each string
+     of repeated newlines into a single newline:
+
+          tr -cs '[:alnum:]' '[\n*]'
+
+   • Convert each sequence of repeated newlines to a single newline.
+     I.e., delete empty lines:
+
+          tr -s '\n'
+
+   • Find doubled occurrences of words in a document.  For example,
+     people often write “the the” with the repeated words separated by a
+     newline.  The Bourne shell script below works first by converting
+     each sequence of punctuation and blank characters to a single
+     newline.  That puts each “word” on a line by itself.  Next it maps
+     all uppercase characters to lower case, and finally it runs ‘uniq’
+     with the ‘-d’ option to print out only the words that were
+     repeated.
+
+          #!/bin/sh
+          cat -- "$@" \
+            | tr -s '[:punct:][:blank:]' '[\n*]' \
+            | tr '[:upper:]' '[:lower:]' \
+            | uniq -d
+
+   • Deleting a small set of characters is usually straightforward.  For
+     example, to remove all ‘a’s, ‘x’s, and ‘M’s you would do this:
+
+          tr -d axM
+
+     However, when ‘-’ is one of those characters, it can be tricky
+     because ‘-’ has special meanings.  Performing the same task as
+     above but also removing all ‘-’ characters, we might try ‘tr -d
+     -axM’, but that would fail because ‘tr’ would try to interpret ‘-a’
+     as a command-line option.  Alternatively, we could try putting the
+     hyphen inside the string, ‘tr -d a-xM’, but that wouldn’t work
+     either because it would make ‘tr’ interpret ‘a-x’ as the range of
+     characters ‘a’...‘x’ rather than the three.  One way to solve the
+     problem is to put the hyphen at the end of the list of characters:
+
+          tr -d axM-
+
+     Or you can use ‘--’ to terminate option processing:
+
+          tr -d -- -axM
+
+
+File: coreutils.info,  Node: expand invocation,  Next: unexpand invocation,  Prev: tr invocation,  Up: Operating on characters
+
+9.2 ‘expand’: Convert tabs to spaces
+====================================
+
+‘expand’ writes the contents of each given FILE, or standard input if
+none are given or for a FILE of ‘-’, to standard output, with tab
+characters converted to the appropriate number of spaces.  Synopsis:
+
+     expand [OPTION]... [FILE]...
+
+   By default, ‘expand’ converts all tabs to spaces.  It preserves
+backspace characters in the output; they decrement the column count for
+tab calculations.  The default action is equivalent to ‘-t 8’ (set tabs
+every 8 columns).
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-t TAB1[,TAB2]...’
+‘--tabs=TAB1[,TAB2]...’
+     If only one tab stop is given, set the tabs TAB1 spaces apart
+     (default is 8).  Otherwise, set the tabs at columns TAB1, TAB2, ...
+     (numbered from 0), and replace any tabs beyond the last tab stop
+     given with single spaces.  Tab stops can be separated by blanks as
+     well as by commas.
+
+     As a GNU extension the last TAB specified can be prefixed with a
+     ‘/’ to indicate a tab size to use for remaining positions.  For
+     example, ‘--tabs=2,4,/8’ will set tab stops at position 2 and 4,
+     and every multiple of 8 after that.
+
+     Also the last TAB specified can be prefixed with a ‘+’ to indicate
+     a tab size to use for remaining positions, offset from the final
+     explicitly specified tab stop.  For example, to ignore the 1
+     character gutter present in diff output, one can specify a 1
+     character offset using ‘--tabs=1,+8’, which will set tab stops at
+     positions 1,9,17,...
+
+     For compatibility, GNU ‘expand’ also accepts the obsolete option
+     syntax, ‘-T1[,T2]...’.  New scripts should use ‘-t T1[,T2]...’
+     instead.
+
+‘-i’
+‘--initial’
+     Only convert initial tabs (those that precede all non-space or
+     non-tab characters) on each line to spaces.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: unexpand invocation,  Prev: expand invocation,  Up: Operating on characters
+
+9.3 ‘unexpand’: Convert spaces to tabs
+======================================
+
+‘unexpand’ writes the contents of each given FILE, or standard input if
+none are given or for a FILE of ‘-’, to standard output, converting
+blanks at the beginning of each line into as many tab characters as
+needed.  In the default POSIX locale, a “blank” is a space or a tab;
+other locales may specify additional blank characters.  Synopsis:
+
+     unexpand [OPTION]... [FILE]...
+
+   By default, ‘unexpand’ converts only initial blanks (those that
+precede all non-blank characters) on each line.  It preserves backspace
+characters in the output; they decrement the column count for tab
+calculations.  By default, tabs are set at every 8th column.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-t TAB1[,TAB2]...’
+‘--tabs=TAB1[,TAB2]...’
+     If only one tab stop is given, set the tabs TAB1 columns apart
+     instead of the default 8.  Otherwise, set the tabs at columns TAB1,
+     TAB2, ... (numbered from 0), and leave blanks beyond the tab stops
+     given unchanged.  Tab stops can be separated by blanks as well as
+     by commas.
+
+     As a GNU extension the last TAB specified can be prefixed with a
+     ‘/’ to indicate a tab size to use for remaining positions.  For
+     example, ‘--tabs=2,4,/8’ will set tab stops at position 2 and 4,
+     and every multiple of 8 after that.
+
+     Also the last TAB specified can be prefixed with a ‘+’ to indicate
+     a tab size to use for remaining positions, offset from the final
+     explicitly specified tab stop.  For example, to ignore the 1
+     character gutter present in diff output, one can specify a 1
+     character offset using ‘--tabs=1,+8’, which will set tab stops at
+     positions 1,9,17,...
+
+     This option implies the ‘-a’ option.
+
+     For compatibility, GNU ‘unexpand’ supports the obsolete option
+     syntax, ‘-TAB1[,TAB2]...’, where tab stops must be separated by
+     commas.  (Unlike ‘-t’, this obsolete option does not imply ‘-a’.)
+     New scripts should use ‘--first-only -t TAB1[,TAB2]...’ instead.
+
+‘-a’
+‘--all’
+     Also convert all sequences of two or more blanks just before a tab
+     stop, even if they occur after non-blank characters in a line.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Directory listing,  Next: Basic operations,  Prev: Operating on characters,  Up: Top
+
+10 Directory listing
+********************
+
+This chapter describes the ‘ls’ command and its variants ‘dir’ and
+‘vdir’, which list information about files.
+
+* Menu:
+
+* ls invocation::               List directory contents.
+* dir invocation::              Briefly ls.
+* vdir invocation::             Verbosely ls.
+* dircolors invocation::        Color setup for ls, etc.
+
+
+File: coreutils.info,  Node: ls invocation,  Next: dir invocation,  Up: Directory listing
+
+10.1 ‘ls’: List directory contents
+==================================
+
+The ‘ls’ program lists information about files (of any type, including
+directories).  Options and file arguments can be intermixed arbitrarily,
+as usual.  Later options override earlier options that are incompatible.
+
+   For non-option command-line arguments that are directories, by
+default ‘ls’ lists the contents of directories, not recursively, and
+omitting files with names beginning with ‘.’.  For other non-option
+arguments, by default ‘ls’ lists just the file name.  If no non-option
+argument is specified, ‘ls’ operates on the current directory, acting as
+if it had been invoked with a single argument of ‘.’.
+
+   By default, the output is sorted alphabetically, according to the
+locale settings in effect.(1)  If standard output is a terminal, the
+output is in columns (sorted vertically) and control characters are
+output as question marks; otherwise, the output is listed one per line
+and control characters are output as-is.
+
+   Because ‘ls’ is such a fundamental program, it has accumulated many
+options over the years.  They are described in the subsections below;
+within each section, options are listed alphabetically (ignoring case).
+The division of options into the subsections is not absolute, since some
+options affect more than one aspect of ‘ls’’s operation.
+
+   Exit status:
+
+     0 success
+     1 minor problems  (e.g., failure to access a file or directory not
+       specified as a command line argument.  This happens when listing a
+       directory in which entries are actively being removed or renamed.)
+     2 serious trouble (e.g., memory exhausted, invalid option, failure
+       to access a file or directory specified as a command line argument
+       or a directory loop)
+
+   Also see *note Common options::.
+
+* Menu:
+
+* Which files are listed::
+* What information is listed::
+* Sorting the output::
+* General output formatting::
+* Formatting file timestamps::
+* Formatting the file names::
+
+   ---------- Footnotes ----------
+
+   (1) If you use a non-POSIX locale (e.g., by setting ‘LC_ALL’ to
+‘en_US’), then ‘ls’ may produce output that is sorted differently than
+you’re accustomed to.  In that case, set the ‘LC_ALL’ environment
+variable to ‘C’.
+
+
+File: coreutils.info,  Node: Which files are listed,  Next: What information is listed,  Up: ls invocation
+
+10.1.1 Which files are listed
+-----------------------------
+
+These options determine which files ‘ls’ lists information for.  By
+default, ‘ls’ lists files and the contents of any directories on the
+command line, except that in directories it ignores files whose names
+start with ‘.’.
+
+‘-a’
+‘--all’
+     In directories, do not ignore file names that start with ‘.’.
+
+‘-A’
+‘--almost-all’
+     In directories, do not ignore all file names that start with ‘.’;
+     ignore only ‘.’ and ‘..’.  The ‘--all’ (‘-a’) option overrides this
+     option.
+
+‘-B’
+‘--ignore-backups’
+     In directories, ignore files that end with ‘~’.  This option is
+     equivalent to ‘--ignore='*~' --ignore='.*~'’.
+
+‘-d’
+‘--directory’
+     List just the names of directories, as with other types of files,
+     rather than listing their contents.  Do not follow symbolic links
+     listed on the command line unless the ‘--dereference-command-line’
+     (‘-H’), ‘--dereference’ (‘-L’), or
+     ‘--dereference-command-line-symlink-to-dir’ options are specified.
+
+‘-H’
+‘--dereference-command-line’
+     If a command line argument specifies a symbolic link, show
+     information for the file the link references rather than for the
+     link itself.
+
+‘--dereference-command-line-symlink-to-dir’
+     Do not dereference symbolic links, with one exception: if a command
+     line argument specifies a symbolic link that refers to a directory,
+     show information for that directory rather than for the link
+     itself.  This is the default behavior unless long format is being
+     used or any of the following options is in effect: ‘--classify’
+     (‘-F’), ‘--directory’ (‘-d’), ‘--dereference’ (‘-L’), or
+     ‘--dereference-command-line’ (‘-H’)).
+
+‘--group-directories-first’
+     Group all the directories before the files and then sort the
+     directories and the files separately using the selected sort key
+     (see ‘--sort’ option).  That is, this option specifies a primary
+     sort key, and the ‘--sort’ option specifies a secondary key.
+     However, any use of ‘--sort=none’ (‘-U’) disables this option
+     altogether.
+
+‘--hide=PATTERN’
+     In directories, ignore files whose names match the shell pattern
+     PATTERN, unless the ‘--all’ (‘-a’) or ‘--almost-all’ (‘-A’) is also
+     given.  This option acts like ‘--ignore=PATTERN’ except that it has
+     no effect if ‘--all’ (‘-a’) or ‘--almost-all’ (‘-A’) is also given.
+
+     This option can be useful in shell aliases.  For example, if ‘lx’
+     is an alias for ‘ls --hide='*~'’ and ‘ly’ is an alias for ‘ls
+     --ignore='*~'’, then the command ‘lx -A’ lists the file ‘README~’
+     even though ‘ly -A’ would not.
+
+‘-I PATTERN’
+‘--ignore=PATTERN’
+     In directories, ignore files whose names match the shell pattern
+     (not regular expression) PATTERN.  As in the shell, an initial ‘.’
+     in a file name does not match a wildcard at the start of PATTERN.
+     Sometimes it is useful to give this option several times.  For
+     example,
+
+          $ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
+
+     The first option ignores names of length 3 or more that start with
+     ‘.’, the second ignores all two-character names that start with ‘.’
+     except ‘..’, and the third ignores names that start with ‘#’.
+
+‘-L’
+‘--dereference’
+     When showing file information for a symbolic link, show information
+     for the file the link references rather than the link itself.
+     However, even with this option, ‘ls’ still prints the name of the
+     link itself, not the name of the file that the link points to.
+
+‘-R’
+‘--recursive’
+     List the contents of all directories recursively.
+
+
+File: coreutils.info,  Node: What information is listed,  Next: Sorting the output,  Prev: Which files are listed,  Up: ls invocation
+
+10.1.2 What information is listed
+---------------------------------
+
+These options affect the information that ‘ls’ displays.  By default,
+only file names are shown.
+
+‘--author’
+     In long format, list each file’s author.  In GNU/Hurd, file authors
+     can differ from their owners, but in other operating systems the
+     two are the same.
+
+‘-D’
+‘--dired’
+     Print an additional line after the main output:
+
+          //DIRED// BEG1 END1 BEG2 END2 ...
+
+     The BEGN and ENDN are unsigned integers that record the byte
+     position of the beginning and end of each file name in the output.
+     This makes it easy for Emacs to find the names, even when they
+     contain unusual characters such as space or newline, without fancy
+     searching.
+
+     If directories are being listed recursively via ‘--recursive’
+     (‘-R’), output a similar line with offsets for each subdirectory
+     name:
+
+          //SUBDIRED// BEG1 END1 ...
+
+     Finally, output a line of the form:
+
+          //DIRED-OPTIONS// --quoting-style=WORD
+
+     where WORD is the quoting style (*note Formatting the file
+     names::).
+
+     Here is an actual example:
+
+          $ mkdir -p a/sub/deeper a/sub2
+          $ touch a/f1 a/f2
+          $ touch a/sub/deeper/file
+          $ ls -gloRF --dired a
+            a:
+            total 8
+            -rw-r--r-- 1    0 Jun 10 12:27 f1
+            -rw-r--r-- 1    0 Jun 10 12:27 f2
+            drwxr-xr-x 3 4096 Jun 10 12:27 sub/
+            drwxr-xr-x 2 4096 Jun 10 12:27 sub2/
+
+            a/sub:
+            total 4
+            drwxr-xr-x 2 4096 Jun 10 12:27 deeper/
+
+            a/sub/deeper:
+            total 0
+            -rw-r--r-- 1 0 Jun 10 12:27 file
+
+            a/sub2:
+            total 0
+          //DIRED// 48 50 84 86 120 123 158 162 217 223 282 286
+          //SUBDIRED// 2 3 167 172 228 240 290 296
+          //DIRED-OPTIONS// --quoting-style=literal
+
+     The pairs of offsets on the ‘//DIRED//’ line above delimit these
+     names: ‘f1’, ‘f2’, ‘sub’, ‘sub2’, ‘deeper’, ‘file’.  The offsets on
+     the ‘//SUBDIRED//’ line delimit the following directory names: ‘a’,
+     ‘a/sub’, ‘a/sub/deeper’, ‘a/sub2’.
+
+     Here is an example of how to extract the fifth entry name,
+     ‘deeper’, corresponding to the pair of offsets, 222 and 228:
+
+          $ ls -gloRF --dired a > out
+          $ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo
+          deeper
+
+     Although the listing above includes a trailing slash for the
+     ‘deeper’ entry, the offsets select the name without the trailing
+     slash.  However, if you invoke ‘ls’ with ‘--dired’ (‘-D’) along
+     with an option like ‘--escape’ (‘-b’) and operate on a file whose
+     name contains special characters, the backslash _is_ included:
+
+          $ touch 'a b'
+          $ ls -blog --dired 'a b'
+            -rw-r--r-- 1 0 Jun 10 12:28 a\ b
+          //DIRED// 30 34
+          //DIRED-OPTIONS// --quoting-style=escape
+
+     If you use a quoting style like ‘--quoting-style=c’ (‘-Q’) that
+     adds quote marks, then the offsets include the quote marks.  So
+     beware that the user may select the quoting style via the
+     environment variable ‘QUOTING_STYLE’.  Hence, applications using
+     ‘--dired’ should either specify an explicit
+     ‘--quoting-style=literal’ (‘-N’) option on the command line, or
+     else be prepared to parse the escaped names.
+
+     The ‘--dired’ (‘-D’) option has well-defined behavior only when
+     long format is in effect and hyperlinks are disabled (e.g.,
+     ‘--hyperlink=none’).
+
+‘--full-time’
+     Produce long format, and list times in full.  It is equivalent to
+     using ‘--format=long’ (‘-l’) with ‘--time-style=full-iso’ (*note
+     Formatting file timestamps::).
+
+‘-g’
+     Produce long format, but omit owner information.
+
+‘-G’
+‘--no-group’
+     Inhibit display of group information in long format.  (This is the
+     default in some non-GNU versions of ‘ls’, so we provide this option
+     for compatibility.)
+
+‘-h’
+‘--human-readable’
+     Append a size letter to each size, such as ‘M’ for mebibytes.
+     Powers of 1024 are used, not 1000; ‘M’ stands for 1,048,576 bytes.
+     This option is equivalent to ‘--block-size=human-readable’.  Use
+     the ‘--si’ option if you prefer powers of 1000.
+
+‘-i’
+‘--inode’
+     Print the inode number (also called the file serial number and
+     index number) of each file to the left of the file name.  (This
+     number uniquely identifies each file within a particular file
+     system.)
+
+‘-l’
+‘--format=long’
+‘--format=verbose’
+     Produce long format.  In addition to the name of each file, print
+     the file type, file mode bits, number of hard links, owner name,
+     group name, size, and timestamp (*note Formatting file
+     timestamps::), normally the modification timestamp (the mtime,
+     *note File timestamps::).  If the owner or group name cannot be
+     determined, print the owner or group ID instead, right-justified as
+     a cue that it is a number rather than a textual name.  Print
+     question marks for other information that cannot be determined.
+
+     Normally the size is printed as a byte count without punctuation,
+     but this can be overridden (*note Block size::).  For example,
+     ‘--human-readable’ (‘-h’) prints an abbreviated, human-readable
+     count, and ‘--block-size="'1"’ prints a byte count with the
+     thousands separator of the current locale.
+
+     For each directory that is listed, preface the files with a line
+     ‘total BLOCKS’, where BLOCKS is the file system allocation for all
+     files in that directory.  The block size currently defaults to 1024
+     bytes, but this can be overridden (*note Block size::).  The BLOCKS
+     computed counts each hard link separately; this is arguably a
+     deficiency.
+
+     The file type is one of the following characters:
+
+     ‘-’
+          regular file
+     ‘b’
+          block special file
+     ‘c’
+          character special file
+     ‘C’
+          high performance (“contiguous data”) file
+     ‘d’
+          directory
+     ‘D’
+          door (Solaris)
+     ‘l’
+          symbolic link
+     ‘M’
+          off-line (“migrated”) file (Cray DMF)
+     ‘n’
+          network special file (HP-UX)
+     ‘p’
+          FIFO (named pipe)
+     ‘P’
+          port (Solaris)
+     ‘s’
+          socket
+     ‘?’
+          some other file type
+
+     The file mode bits listed are similar to symbolic mode
+     specifications (*note Symbolic Modes::).  But ‘ls’ combines
+     multiple bits into the third character of each set of permissions
+     as follows:
+
+     ‘s’
+          If the set-user-ID or set-group-ID bit and the corresponding
+          executable bit are both set.
+
+     ‘S’
+          If the set-user-ID or set-group-ID bit is set but the
+          corresponding executable bit is not set.
+
+     ‘t’
+          If the restricted deletion flag or sticky bit, and the
+          other-executable bit, are both set.  The restricted deletion
+          flag is another name for the sticky bit.  *Note Mode
+          Structure::.
+
+     ‘T’
+          If the restricted deletion flag or sticky bit is set but the
+          other-executable bit is not set.
+
+     ‘x’
+          If the executable bit is set and none of the above apply.
+
+     ‘-’
+          Otherwise.
+
+     Following the file mode bits is a single character that specifies
+     whether an alternate access method such as an access control list
+     applies to the file.  When the character following the file mode
+     bits is a space, there is no alternate access method.  When it is a
+     printing character, then there is such a method.
+
+     GNU ‘ls’ uses a ‘.’ character to indicate a file with a security
+     context, but no other alternate access method.
+
+     A file with any other combination of alternate access methods is
+     marked with a ‘+’ character.
+
+‘-n’
+‘--numeric-uid-gid’
+     Produce long format, but display right-justified numeric user and
+     group IDs instead of left-justified owner and group names.
+
+‘-o’
+     Produce long format, but omit group information.  It is equivalent
+     to using ‘--format=long’ (‘-l’) with ‘--no-group’ (‘-G’).
+
+‘-s’
+‘--size’
+     Print the file system allocation of each file to the left of the
+     file name.  This is the amount of file system space used by the
+     file, which is usually a bit more than the file’s size, but it can
+     be less if the file has holes.
+
+     Normally the allocation is printed in units of 1024 bytes, but this
+     can be overridden (*note Block size::).
+
+     For files that are NFS-mounted from an HP-UX system to a BSD
+     system, this option reports sizes that are half the correct values.
+     On HP-UX systems, it reports sizes that are twice the correct
+     values for files that are NFS-mounted from BSD systems.  This is
+     due to a flaw in HP-UX; it also affects the HP-UX ‘ls’ program.
+
+‘--si’
+     Append an SI-style abbreviation to each size, such as ‘M’ for
+     megabytes.  Powers of 1000 are used, not 1024; ‘M’ stands for
+     1,000,000 bytes.  This option is equivalent to ‘--block-size=si’.
+     Use the ‘-h’ or ‘--human-readable’ option if you prefer powers of
+     1024.
+
+‘-Z’
+‘--context’
+     Display the SELinux security context or ‘?’ if none is found.  In
+     long format, print the security context to the left of the size
+     column.
+
+
+File: coreutils.info,  Node: Sorting the output,  Next: General output formatting,  Prev: What information is listed,  Up: ls invocation
+
+10.1.3 Sorting the output
+-------------------------
+
+These options change the order in which ‘ls’ sorts the information it
+outputs.  By default, sorting is done by character code (e.g., ASCII
+order).
+
+‘-c’
+‘--time=ctime’
+‘--time=status’
+     In long format, print the status change timestamp (the ctime)
+     instead of the mtime.  When sorting by time or when not using long
+     format, sort according to the ctime.  *Note File timestamps::.
+
+‘-f’
+     Produce an unsorted directory listing.  This is equivalent to the
+     combination of ‘--all’ (‘-a’), ‘--sort=none’ (‘-U’), ‘-1’,
+     ‘--color=none’, and ‘--hyperlink=none’, while also disabling any
+     previous use of ‘--size’ (‘-s’).
+
+‘-r’
+‘--reverse’
+     Reverse whatever the sorting method is – e.g., list files in
+     reverse alphabetical order, youngest first, smallest first, or
+     whatever.  This option has no effect when ‘--sort=none’ (‘-U’) is
+     in effect.
+
+‘-S’
+‘--sort=size’
+     Sort by file size, largest first.
+
+‘-t’
+‘--sort=time’
+     Sort by modification timestamp (mtime) by default, newest first.
+     The timestamp to order by can be changed with the ‘--time’ option.
+     *Note File timestamps::.
+
+‘-u’
+‘--time=atime’
+‘--time=access’
+‘--time=use’
+     In long format, print the last access timestamp (the atime).  When
+     sorting by time or when not using long format, sort according to
+     the atime.  *Note File timestamps::.
+
+‘--time=mtime’
+‘--time=modification’
+     This is the default timestamp display and sorting mode.  In long
+     format, print the last data modification timestamp (the mtime).
+     When sorting by time or when not using long format, sort according
+     to the mtime.  *Note File timestamps::.
+
+‘--time=birth’
+‘--time=creation’
+     In long format, print the file creation timestamp if available,
+     falling back to the file modification timestamp (mtime) if not.
+     When sorting by time or when not using long format, sort according
+     to the birth time.  *Note File timestamps::.
+
+‘-U’
+‘--sort=none’
+     Do not sort; list the files in whatever order they are stored in
+     the directory.  (Do not do any of the other unrelated things that
+     ‘-f’ does.)  This can be useful when listing large directories,
+     where sorting can take some time.
+
+‘-v’
+‘--sort=version’
+     Sort by version name and number, lowest first.  It behaves like a
+     default sort, except that each sequence of decimal digits is
+     treated numerically as an index/version number.  *Note Version sort
+     ordering::.
+
+‘--sort=width’
+     Sort by printed width of file names.  This can be useful with the
+     ‘--format=vertical’ (‘-C’) output format, to most densely display
+     the listed files.
+
+‘-X’
+‘--sort=extension’
+     Sort directory contents alphabetically by file extension
+     (characters after the last ‘.’); files with no extension are sorted
+     first.
+
+
+File: coreutils.info,  Node: General output formatting,  Next: Formatting file timestamps,  Prev: Sorting the output,  Up: ls invocation
+
+10.1.4 General output formatting
+--------------------------------
+
+These options affect the appearance of the overall output.
+
+‘--format=single-column’
+     List one file name per line, with no other information.  This is
+     the default for ‘ls’ when standard output is not a terminal.  See
+     also the ‘--escape’ (‘-b’), ‘--hide-control-chars’ (‘-q’), and
+     ‘--zero’ options to disambiguate output of file names containing
+     newline characters.
+
+‘-1’
+     List one file per line.  This is like ‘--format=single-column’
+     except that it has no effect if long format is also in effect.
+
+‘-C’
+‘--format=vertical’
+     List files in columns, sorted vertically, with no other
+     information.  This is the default for ‘ls’ if standard output is a
+     terminal.  It is always the default for the ‘dir’ program.  GNU
+     ‘ls’ uses variable width columns to display as many files as
+     possible in the fewest lines.
+
+‘--color [=WHEN]’
+     Specify whether to use color for distinguishing file types; WHEN
+     may be omitted, or one of:
+        • none - Do not use color at all.  This is the default.
+        • auto - Only use color if standard output is a terminal.
+        • always - Always use color.
+     Specifying ‘--color’ and no WHEN is equivalent to ‘--color=always’.
+     If piping a colored listing through a pager like ‘less’, use the
+     pager’s ‘-R’ option to pass the color codes to the terminal.
+
+     Using the ‘--color’ option may incur a noticeable performance
+     penalty when run in a large directory, because the default settings
+     require that ‘ls’ ‘stat’ every single file it lists.  However, if
+     you would like most of the file-type coloring but can live without
+     the other coloring options (e.g., executable, orphan, sticky,
+     other-writable, capability), use ‘dircolors’ to set the ‘LS_COLORS’
+     environment variable like this,
+          eval $(dircolors -p | perl -pe \
+            's/^((CAP|S[ET]|O[TR]|M|E)\w+).*/$1 00/' | dircolors -)
+     and on a ‘dirent.d_type’-capable file system, ‘ls’ will perform
+     only one ‘stat’ call per command line argument.
+
+‘-F’
+‘--classify [=WHEN]’
+‘--indicator-style=classify’
+     Append a character to each file name indicating the file type.
+     Also, for regular files that are executable, append ‘*’.  The file
+     type indicators are ‘/’ for directories, ‘@’ for symbolic links,
+     ‘|’ for FIFOs, ‘=’ for sockets, ‘>’ for doors, and nothing for
+     regular files.  WHEN may be omitted, or one of:
+        • none - Do not classify.  This is the default.
+        • auto - Only classify if standard output is a terminal.
+        • always - Always classify.
+     Specifying ‘--classify’ and no WHEN is equivalent to
+     ‘--classify=always’.  Do not follow symbolic links listed on the
+     command line unless the ‘--dereference-command-line’ (‘-H’),
+     ‘--dereference’ (‘-L’), or
+     ‘--dereference-command-line-symlink-to-dir’ options are specified.
+
+‘--file-type’
+‘--indicator-style=file-type’
+     Append a character to each file name indicating the file type.
+     This is like ‘--classify’ (‘-F’, except that executables are not
+     marked.
+
+‘--hyperlink [=WHEN]’
+     Output codes recognized by some terminals to link to files using
+     the ‘file://’ URI format.  WHEN may be omitted, or one of:
+        • none - Do not use hyperlinks at all.  This is the default.
+        • auto - Only use hyperlinks if standard output is a terminal.
+        • always - Always use hyperlinks.
+     Specifying ‘--hyperlink’ and no WHEN is equivalent to
+     ‘--hyperlink=always’.
+
+‘--indicator-style=WORD’
+     Append a character indicator with style WORD to entry names, as
+     follows:
+
+     ‘none’
+          Do not append any character indicator; this is the default.
+     ‘slash’
+          Append ‘/’ for directories.  This is the same as the ‘-p’
+          option.
+     ‘file-type’
+          Append ‘/’ for directories, ‘@’ for symbolic links, ‘|’ for
+          FIFOs, ‘=’ for sockets, and nothing for regular files.  This
+          is the same as the ‘--file-type’ option.
+     ‘classify’
+          Append ‘*’ for executable regular files, otherwise behave as
+          for ‘file-type’.  This is the same as the ‘--classify’ (‘-F’)
+          option.
+
+‘-k’
+‘--kibibytes’
+     Set the default block size to its normal value of 1024 bytes,
+     overriding any contrary specification in environment variables
+     (*note Block size::).  If ‘--block-size’, ‘--human-readable’
+     (‘-h’), or ‘--si’ options are used, they take precedence even if
+     ‘--kibibytes’ (‘-k’) is placed after
+
+     The ‘--kibibytes’ (‘-k’) option affects the per-directory block
+     count written in long format, and the file system allocation
+     written by the ‘--size’ (‘-s’) option.  It does not affect the file
+     size in bytes that is written in long format.
+
+‘-m’
+‘--format=commas’
+     List files horizontally, with as many as will fit on each line,
+     separated by ‘, ’ (a comma and a space), and with no other
+     information.
+
+‘-p’
+‘--indicator-style=slash’
+     Append a ‘/’ to directory names.
+
+‘-x’
+‘--format=across’
+‘--format=horizontal’
+     List the files in columns, sorted horizontally.
+
+‘-T COLS’
+‘--tabsize=COLS’
+     Assume that each tab stop is COLS columns wide.  The default is 8.
+     ‘ls’ uses tabs where possible in the output, for efficiency.  If
+     COLS is zero, do not use tabs at all.
+
+     Some terminal emulators might not properly align columns to the
+     right of a TAB following a non-ASCII byte.  You can avoid that
+     issue by using the ‘-T0’ option or put ‘TABSIZE=0’ in your
+     environment, to tell ‘ls’ to align using spaces, not tabs.
+
+     If you set a terminal’s hardware tabs to anything other than the
+     default, you should also use a ‘--tabsize’ option or ‘TABSIZE’
+     environment variable either to match the hardware tabs, or to
+     disable the use of hardware tabs.  Otherwise, the output of ‘ls’
+     may not line up.  For example, if you run the shell command ‘tabs
+     -4’ to set hardware tabs to every four columns, you should also run
+     ‘export TABSIZE=4’ or ‘export TABSIZE=0’, or use the corresponding
+     ‘--tabsize’ options.
+
+‘-w COLS’
+‘--width=COLS’
+     Assume the screen is COLS columns wide.  The default is taken from
+     the terminal settings if possible; otherwise the environment
+     variable ‘COLUMNS’ is used if it is set; otherwise the default is
+     80.  With a COLS value of ‘0’, there is no limit on the length of
+     the output line, and that single output line will be delimited with
+     spaces, not tabs.
+
+‘--zero’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+     This option is incompatible with the ‘--dired’ (‘-D’) option.  This
+     option also implies the options ‘--show-control-chars’, ‘-1’,
+     ‘--color=none’, and ‘--quoting-style=literal’ (‘-N’).
+
+
+File: coreutils.info,  Node: Formatting file timestamps,  Next: Formatting the file names,  Prev: General output formatting,  Up: ls invocation
+
+10.1.5 Formatting file timestamps
+---------------------------------
+
+By default, file timestamps are listed in abbreviated form, using a date
+like ‘Mar 30  2020’ for non-recent timestamps, and a date-without-year
+and time like ‘Mar 30 23:45’ for recent timestamps.  This format can
+change depending on the current locale as detailed below.
+
+   A timestamp is considered to be “recent” if it is less than six
+months old, and is not dated in the future.  If a timestamp dated today
+is not listed in recent form, the timestamp is in the future, which
+means you probably have clock skew problems which may break programs
+like ‘make’ that rely on file timestamps.  *Note File timestamps::.
+
+   Timestamps are listed according to the time zone rules specified by
+the ‘TZ’ environment variable, or by the system default rules if ‘TZ’ is
+not set.  *Note Specifying the Time Zone with ‘TZ’: (libc)TZ Variable.
+
+   The following option changes how file timestamps are printed.
+
+‘--time-style=STYLE’
+     List timestamps in style STYLE.  The STYLE should be one of the
+     following:
+
+     ‘+FORMAT’
+          List timestamps using FORMAT, where FORMAT is interpreted like
+          the format argument of ‘date’ (*note date invocation::).  For
+          example, ‘--time-style="+%Y-%m-%d %H:%M:%S"’ causes ‘ls’ to
+          list timestamps like ‘2020-03-30 23:45:56’.  As with ‘date’,
+          FORMAT’s interpretation is affected by the ‘LC_TIME’ locale
+          category.
+
+          If FORMAT contains two format strings separated by a newline,
+          the former is used for non-recent files and the latter for
+          recent files; if you want output columns to line up, you may
+          need to insert spaces in one of the two formats.
+
+     ‘full-iso’
+          List timestamps in full using ISO 8601-like date, time, and
+          time zone components with nanosecond precision, e.g.,
+          ‘2020-07-21 23:45:56.477817180 -0400’.  This style is
+          equivalent to ‘+%Y-%m-%d %H:%M:%S.%N %z’.
+
+          This is useful because the time output includes all the
+          information that is available from the operating system.  For
+          example, this can help explain ‘make’’s behavior, since GNU
+          ‘make’ uses the full timestamp to determine whether a file is
+          out of date.
+
+     ‘long-iso’
+          List ISO 8601 date and time components with minute precision,
+          e.g., ‘2020-03-30 23:45’.  These timestamps are shorter than
+          ‘full-iso’ timestamps, and are usually good enough for
+          everyday work.  This style is equivalent to ‘+%Y-%m-%d %H:%M’.
+
+     ‘iso’
+          List ISO 8601 dates for non-recent timestamps (e.g.,
+          ‘2020-03-30 ’), and ISO 8601-like month, day, hour, and minute
+          for recent timestamps (e.g., ‘03-30 23:45’).  These timestamps
+          are uglier than ‘long-iso’ timestamps, but they carry nearly
+          the same information in a smaller space and their brevity
+          helps ‘ls’ output fit within traditional 80-column output
+          lines.  The following two ‘ls’ invocations are equivalent:
+
+               newline='
+               '
+               ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M"
+               ls -l --time-style="iso"
+
+     ‘locale’
+          List timestamps in a locale-dependent form.  For example, a
+          French locale might list non-recent timestamps like ‘30
+          mars   2020’ and recent timestamps like ‘30 mars  23:45’.
+          Locale-dependent timestamps typically consume more space than
+          ‘iso’ timestamps and are harder for programs to parse because
+          locale conventions vary so widely, but they are easier for
+          many people to read.
+
+          The ‘LC_TIME’ locale category specifies the timestamp format.
+          The default POSIX locale uses timestamps like ‘Mar 30  2020’
+          and ‘Mar 30 23:45’; in this locale, the following two ‘ls’
+          invocations are equivalent:
+
+               newline='
+               '
+               ls -l --time-style="+%b %e  %Y$newline%b %e %H:%M"
+               ls -l --time-style="locale"
+
+          Other locales behave differently.  For example, in a German
+          locale, ‘--time-style="locale"’ might be equivalent to
+          ‘--time-style="+%e. %b %Y $newline%e. %b %H:%M"’ and might
+          generate timestamps like ‘30. Mär 2020 ’ and ‘30. Mär 23:45’.
+
+     ‘posix-STYLE’
+          List POSIX-locale timestamps if the ‘LC_TIME’ locale category
+          is POSIX, STYLE timestamps otherwise.  For example, the
+          ‘posix-long-iso’ style lists timestamps like ‘Mar 30  2020’
+          and ‘Mar 30 23:45’ when in the POSIX locale, and like
+          ‘2020-03-30 23:45’ otherwise.
+
+   You can specify the default value of the ‘--time-style’ option with
+the environment variable ‘TIME_STYLE’; if ‘TIME_STYLE’ is not set the
+default style is ‘locale’.  GNU Emacs 21.3 and later use the ‘--dired’
+option and therefore can parse any date format, but if you are using
+Emacs 21.1 or 21.2 and specify a non-POSIX locale you may need to set
+‘TIME_STYLE="posix-long-iso"’.
+
+   To avoid certain denial-of-service attacks, timestamps that would be
+longer than 1000 bytes may be treated as errors.
+
+
+File: coreutils.info,  Node: Formatting the file names,  Prev: Formatting file timestamps,  Up: ls invocation
+
+10.1.6 Formatting the file names
+--------------------------------
+
+These options change how file names themselves are printed.
+
+‘-b’
+‘--escape’
+‘--quoting-style=escape’
+     Quote nongraphic characters in file names using alphabetic and
+     octal backslash sequences like those used in C.
+
+‘-N’
+‘--literal’
+‘--quoting-style=literal’
+     Do not quote file names.  However, with ‘ls’ nongraphic characters
+     are still printed as question marks if the output is a terminal and
+     you do not specify the ‘--show-control-chars’ option.
+
+‘-q’
+‘--hide-control-chars’
+     Print question marks instead of nongraphic characters in file
+     names.  This is the default if the output is a terminal and the
+     program is ‘ls’.
+
+‘-Q’
+‘--quote-name’
+‘--quoting-style=c’
+     Enclose file names in double quotes and quote nongraphic characters
+     as in C.
+
+‘--quoting-style=WORD’
+     Use style WORD to quote file names and other strings that may
+     contain arbitrary characters.  The WORD should be one of the
+     following:
+
+     ‘literal’
+          Output strings as-is; this is the same as the ‘--literal’
+          (‘-N’) option.
+     ‘shell’
+          Quote strings for the shell if they contain shell
+          metacharacters or would cause ambiguous output.  The quoting
+          is suitable for POSIX-compatible shells like ‘bash’, but it
+          does not always work for incompatible shells like ‘csh’.
+     ‘shell-always’
+          Quote strings for the shell, even if they would normally not
+          require quoting.
+     ‘shell-escape’
+          Like ‘shell’, but also quoting non-printable characters using
+          the POSIX proposed ‘$''’ syntax suitable for most shells.
+     ‘shell-escape-always’
+          Like ‘shell-escape’, but quote strings even if they would
+          normally not require quoting.
+     ‘c’
+          Quote strings as for C character string literals, including
+          the surrounding double-quote characters; this is the same as
+          the ‘--quote-name’ (‘-Q’) option.
+     ‘escape’
+          Quote strings as for C character string literals, except omit
+          the surrounding double-quote characters; this is the same as
+          the ‘--escape’ (‘-b’) option.
+     ‘clocale’
+          Quote strings as for C character string literals, except use
+          surrounding quotation marks appropriate for the locale.
+     ‘locale’
+          Quote strings as for C character string literals, except use
+          surrounding quotation marks appropriate for the locale, and
+          quote 'like this' instead of "like this" in the default C
+          locale.  This looks nicer on many displays.
+
+     You can specify the default value of the ‘--quoting-style’ option
+     with the environment variable ‘QUOTING_STYLE’.  If that environment
+     variable is not set, the default value is ‘shell-escape’ when the
+     output is a terminal, and ‘literal’ otherwise.
+
+‘--show-control-chars’
+     Print nongraphic characters as-is in file names.  This is the
+     default unless the output is a terminal and the program is ‘ls’.
+
+
+File: coreutils.info,  Node: dir invocation,  Next: vdir invocation,  Prev: ls invocation,  Up: Directory listing
+
+10.2 ‘dir’: Briefly list directory contents
+===========================================
+
+‘dir’ is equivalent to ‘ls -C -b’; that is, by default files are listed
+in columns, sorted vertically, and special characters are represented by
+backslash escape sequences.
+
+   *Note ‘ls’: ls invocation.
+
+
+File: coreutils.info,  Node: vdir invocation,  Next: dircolors invocation,  Prev: dir invocation,  Up: Directory listing
+
+10.3 ‘vdir’: Verbosely list directory contents
+==============================================
+
+‘vdir’ is equivalent to ‘ls -l -b’; that is, by default files are listed
+in long format and special characters are represented by backslash
+escape sequences.
+
+   *Note ‘ls’: ls invocation.
+
+
+File: coreutils.info,  Node: dircolors invocation,  Prev: vdir invocation,  Up: Directory listing
+
+10.4 ‘dircolors’: Color setup for ‘ls’
+======================================
+
+‘dircolors’ outputs a sequence of shell commands to set up the terminal
+for color output from ‘ls’ (and ‘dir’, etc.).  Typical usage:
+
+     eval "$(dircolors [OPTION]... [FILE])"
+
+   If FILE is specified, ‘dircolors’ reads it to determine which colors
+to use for which file types and extensions.  Otherwise, a precompiled
+database is used.  For details on the format of these files, run
+‘dircolors --print-database’.
+
+   To make ‘dircolors’ read a ‘~/.dircolors’ file if it exists, you can
+put the following lines in your ‘~/.bashrc’ (or adapt them to your
+favorite shell):
+
+     d=.dircolors
+     test -r $d && eval "$(dircolors $d)"
+
+   The output is a shell command to set the ‘LS_COLORS’ environment
+variable.  You can specify the shell syntax to use on the command line,
+or ‘dircolors’ will guess it from the value of the ‘SHELL’ environment
+variable.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b’
+‘--sh’
+‘--bourne-shell’
+     Output Bourne shell commands.  This is the default if the ‘SHELL’
+     environment variable is set and does not end with ‘csh’ or ‘tcsh’.
+
+‘-c’
+‘--csh’
+‘--c-shell’
+     Output C shell commands.  This is the default if ‘SHELL’ ends with
+     ‘csh’ or ‘tcsh’.
+
+‘-p’
+‘--print-database’
+     Print the (compiled-in) default color configuration database.  This
+     output is itself a valid configuration file, and is fairly
+     descriptive of the possibilities.
+
+‘--print-ls-colors’
+     Print the LS_COLORS entries on separate lines, each colored as per
+     the color they represent.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Basic operations,  Next: Special file types,  Prev: Directory listing,  Up: Top
+
+11 Basic operations
+*******************
+
+This chapter describes the commands for basic file manipulation:
+copying, moving (renaming), and deleting (removing).
+
+* Menu:
+
+* cp invocation::               Copy files.
+* dd invocation::               Convert and copy a file.
+* install invocation::          Copy files and set attributes.
+* mv invocation::               Move (rename) files.
+* rm invocation::               Remove files or directories.
+* shred invocation::            Remove files more securely.
+
+
+File: coreutils.info,  Node: cp invocation,  Next: dd invocation,  Up: Basic operations
+
+11.1 ‘cp’: Copy files and directories
+=====================================
+
+‘cp’ copies files (or, optionally, directories).  The copy is completely
+independent of the original.  You can either copy one file to another,
+or copy arbitrarily many files to a destination directory.  Synopses:
+
+     cp [OPTION]... [-T] SOURCE DEST
+     cp [OPTION]... SOURCE... DIRECTORY
+     cp [OPTION]... -t DIRECTORY SOURCE...
+
+   • If two file names are given, ‘cp’ copies the first file to the
+     second.
+
+   • If the ‘--target-directory’ (‘-t’) option is given, or failing that
+     if the last file is a directory and the ‘--no-target-directory’
+     (‘-T’) option is not given, ‘cp’ copies each SOURCE file to the
+     specified directory, using the SOURCEs’ names.
+
+   Generally, files are written just as they are read.  For exceptions,
+see the ‘--sparse’ option below.
+
+   By default, ‘cp’ does not copy directories.  However, the ‘-R’, ‘-a’,
+and ‘-r’ options cause ‘cp’ to copy recursively by descending into
+source directories and copying files to corresponding destination
+directories.
+
+   When copying from a symbolic link, ‘cp’ normally follows the link
+only when not copying recursively or when ‘--link’ (‘-l’) is used.  This
+default can be overridden with the ‘--archive’ (‘-a’), ‘-d’,
+‘--dereference’ (‘-L’), ‘--no-dereference’ (‘-P’), and ‘-H’ options.  If
+more than one of these options is specified, the last one silently
+overrides the others.
+
+   When copying to a symbolic link, ‘cp’ follows the link only when it
+refers to an existing regular file.  However, when copying to a dangling
+symbolic link, ‘cp’ refuses by default, and fails with a diagnostic,
+since the operation is inherently dangerous.  This behavior is contrary
+to historical practice and to POSIX.  Set ‘POSIXLY_CORRECT’ to make ‘cp’
+attempt to create the target of a dangling destination symlink, in spite
+of the possible risk.  Also, when an option like ‘--backup’ or ‘--link’
+acts to rename or remove the destination before copying, ‘cp’ renames or
+removes the symbolic link rather than the file it points to.
+
+   By default, ‘cp’ copies the contents of special files only when not
+copying recursively.  This default can be overridden with the
+‘--copy-contents’ option.
+
+   ‘cp’ generally refuses to copy a file onto itself, with the following
+exception: if ‘--force --backup’ is specified with SOURCE and DEST
+identical, and referring to a regular file, ‘cp’ will make a backup
+file, either regular or numbered, as specified in the usual ways (*note
+Backup options::).  This is useful when you simply want to make a backup
+of an existing file before changing it.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a’
+‘--archive’
+     Preserve as much as possible of the structure and attributes of the
+     original files in the copy (but do not attempt to preserve internal
+     directory structure; i.e., ‘ls -U’ may list the entries in a copied
+     directory in a different order).  Try to preserve SELinux security
+     context and extended attributes (xattr), but ignore any failure to
+     do that and print no corresponding diagnostic.  Equivalent to ‘-dR
+     --preserve=all’ with the reduced diagnostics.
+
+‘--attributes-only’
+     Copy only the specified attributes of the source file to the
+     destination.  If the destination already exists, do not alter its
+     contents.  See the ‘--preserve’ option for controlling which
+     attributes to copy.
+
+‘-b’
+‘--backup[=METHOD]’
+     *Note Backup options::.  Make a backup of each file that would
+     otherwise be overwritten or removed.  As a special case, ‘cp’ makes
+     a backup of SOURCE when the force and backup options are given and
+     SOURCE and DEST are the same name for an existing, regular file.
+     One useful application of this combination of options is this tiny
+     Bourne shell script:
+
+          #!/bin/sh
+          # Usage: backup FILE...
+          # Create a GNU-style backup of each listed FILE.
+          fail=0
+          for i; do
+            cp --backup --force --preserve=all -- "$i" "$i" || fail=1
+          done
+          exit $fail
+
+‘--copy-contents’
+     If copying recursively, copy the contents of any special files
+     (e.g., FIFOs and device files) as if they were regular files.  This
+     means trying to read the data in each source file and writing it to
+     the destination.  It is usually a mistake to use this option, as it
+     normally has undesirable effects on special files like FIFOs and
+     the ones typically found in the ‘/dev’ directory.  In most cases,
+     ‘cp -R --copy-contents’ will hang indefinitely trying to read from
+     FIFOs and special files like ‘/dev/console’, and it will fill up
+     your destination file system if you use it to copy ‘/dev/zero’.
+     This option has no effect unless copying recursively, and it does
+     not affect the copying of symbolic links.
+
+‘-d’
+     Copy symbolic links as symbolic links rather than copying the files
+     that they point to, and preserve hard links between source files in
+     the copies.  Equivalent to ‘--no-dereference --preserve=links’.
+
+‘--debug’
+     Print extra information to stdout, explaining how files are copied.
+     This option implies the ‘--verbose’ option.
+
+‘-f’
+‘--force’
+     When copying without this option and an existing destination file
+     cannot be opened for writing, the copy fails.  However, with
+     ‘--force’, when a destination file cannot be opened, ‘cp’ then
+     tries to recreate the file by first removing it.  Note ‘--force’
+     alone will not remove dangling symlinks.  When this option is
+     combined with ‘--link’ (‘-l’) or ‘--symbolic-link’ (‘-s’), the
+     destination link is replaced, and unless ‘--backup’ (‘-b’) is also
+     given there is no brief moment when the destination does not exist.
+     Also see the description of ‘--remove-destination’.
+
+     This option is independent of the ‘--interactive’ or ‘-i’ option:
+     neither cancels the effect of the other.
+
+     This option is ignored when the ‘--no-clobber’ or ‘-n’ option is
+     also used.
+
+‘-H’
+     If a command line argument specifies a symbolic link, then copy the
+     file it points to rather than the symbolic link itself.  However,
+     copy (preserving its nature) any symbolic link that is encountered
+     via recursive traversal.
+
+‘-i’
+‘--interactive’
+     When copying a file other than a directory, prompt whether to
+     overwrite an existing destination file, and fail if the response is
+     not affirmative.  The ‘-i’ option overrides a previous ‘-n’ option.
+
+‘-l’
+‘--link’
+     Make hard links instead of copies of non-directories.
+
+‘-L’
+‘--dereference’
+     Follow symbolic links when copying from them.  With this option,
+     ‘cp’ cannot create a symbolic link.  For example, a symlink (to
+     regular file) in the source tree will be copied to a regular file
+     in the destination tree.
+
+‘-n’
+‘--no-clobber’
+     Do not overwrite an existing file; silently fail instead.  This
+     option overrides a previous ‘-i’ option.  This option is mutually
+     exclusive with ‘-b’ or ‘--backup’ option.
+
+‘-P’
+‘--no-dereference’
+     Copy symbolic links as symbolic links rather than copying the files
+     that they point to.  This option affects only symbolic links in the
+     source; symbolic links in the destination are always followed if
+     possible.
+
+‘-p’
+‘--preserve[=ATTRIBUTE_LIST]’
+     Preserve the specified attributes of the original files.  If
+     specified, the ATTRIBUTE_LIST must be a comma-separated list of one
+     or more of the following strings:
+
+     ‘mode’
+          Preserve attributes relevant to access permissions, including
+          file mode bits and (if possible) access control lists (ACLs).
+          ACL preservation is system-dependent, and ACLs are not
+          necessarily translated when the source and destination are on
+          file systems with different ACL formats (e.g., NFSv4 versus
+          POSIX formats).
+
+     ‘ownership’
+          Preserve the owner and group.  On most modern systems, only
+          users with appropriate privileges may change the owner of a
+          file, and ordinary users may preserve the group ownership of a
+          file only if they happen to be a member of the desired group.
+     ‘timestamps’
+          Preserve the times of last access and last modification, when
+          possible.  On older systems, it is not possible to preserve
+          these attributes when the affected file is a symbolic link.
+          However, many systems now provide the ‘utimensat’ function,
+          which makes it possible even for symbolic links.
+     ‘links’
+          Preserve in the destination files any links between
+          corresponding source files.  Note that with ‘-L’ or ‘-H’, this
+          option can convert symbolic links to hard links.  For example,
+               $ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c
+               74161745 a
+               74161745 b
+          Note the inputs: ‘b’ is a symlink to regular file ‘a’, yet the
+          files in destination directory, ‘c/’, are hard-linked.  Since
+          ‘-a’ implies ‘--no-dereference’ it would copy the symlink, but
+          the later ‘-H’ tells ‘cp’ to dereference the command line
+          arguments where it then sees two files with the same inode
+          number.  Then the ‘--preserve=links’ option also implied by
+          ‘-a’ will preserve the perceived hard link.
+
+          Here is a similar example that exercises ‘cp’’s ‘-L’ option:
+               $ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
+               74163295 a
+               74163295 b
+
+     ‘context’
+          Preserve SELinux security context of the file, or fail with
+          full diagnostics.
+     ‘xattr’
+          Preserve extended attributes of the file, or fail with full
+          diagnostics.  If ‘cp’ is built without xattr support, ignore
+          this option.  If SELinux context, ACLs or Capabilities are
+          implemented using xattrs, they are preserved implicitly by
+          this option as well, i.e., even without specifying
+          ‘--preserve=mode’ or ‘--preserve=context’.
+     ‘all’
+          Preserve all file attributes.  Equivalent to specifying all of
+          the above, but with the difference that failure to preserve
+          SELinux security context or extended attributes does not
+          change ‘cp’’s exit status.  In contrast to ‘-a’, all but
+          ‘Operation not supported’ warnings are output.
+
+     Using ‘--preserve’ with no ATTRIBUTE_LIST is equivalent to
+     ‘--preserve=mode,ownership,timestamps’.
+
+     In the absence of this option, the permissions of existing
+     destination files are unchanged.  Each new file is created with the
+     mode of the corresponding source file minus the set-user-ID,
+     set-group-ID, and sticky bits as the create mode; the operating
+     system then applies either the umask or a default ACL, possibly
+     resulting in a more restrictive file mode.  *Note File
+     permissions::.
+
+‘--no-preserve=ATTRIBUTE_LIST’
+     Do not preserve the specified attributes.  The ATTRIBUTE_LIST has
+     the same form as for ‘--preserve’.
+
+‘--parents’
+     Form the name of each destination file by appending to the target
+     directory a slash and the specified name of the source file.  The
+     last argument given to ‘cp’ must be the name of an existing
+     directory.  For example, the command:
+
+          cp --parents a/b/c existing_dir
+
+     copies the file ‘a/b/c’ to ‘existing_dir/a/b/c’, creating any
+     missing intermediate directories.
+
+‘-R’
+‘-r’
+‘--recursive’
+     Copy directories recursively.  By default, do not follow symbolic
+     links in the source unless used together with the ‘--link’ (‘-l’)
+     option; see the ‘--archive’ (‘-a’), ‘-d’, ‘--dereference’ (‘-L’),
+     ‘--no-dereference’ (‘-P’), and ‘-H’ options.  Special files are
+     copied by creating a destination file of the same type as the
+     source; see the ‘--copy-contents’ option.  It is not portable to
+     use ‘-r’ to copy symbolic links or special files.  On some non-GNU
+     systems, ‘-r’ implies the equivalent of ‘-L’ and ‘--copy-contents’
+     for historical reasons.  Also, it is not portable to use ‘-R’ to
+     copy symbolic links unless you also specify ‘-P’, as POSIX allows
+     implementations that dereference symbolic links by default.
+
+‘--reflink[=WHEN]’
+     Perform a lightweight, copy-on-write (COW) copy, if supported by
+     the file system.  Once it has succeeded, beware that the source and
+     destination files share the same data blocks as long as they remain
+     unmodified.  Thus, if an I/O error affects data blocks of one of
+     the files, the other suffers the same fate.
+
+     The WHEN value can be one of the following:
+
+     ‘always’
+          If the copy-on-write operation is not supported then report
+          the failure for each file and exit with a failure status.
+          Plain ‘--reflink’ is equivalent to ‘--reflink=always’.
+
+     ‘auto’
+          If the copy-on-write operation is not supported then fall back
+          to the standard copy behavior.  This is the default if no
+          ‘--reflink’ option is given.
+
+     ‘never’
+          Disable copy-on-write operation and use the standard copy
+          behavior.
+
+     This option is overridden by the ‘--link’, ‘--symbolic-link’ and
+     ‘--attributes-only’ options, thus allowing it to be used to
+     configure the default data copying behavior for ‘cp’.
+
+‘--remove-destination’
+     Remove each existing destination file before attempting to open it
+     (contrast with ‘-f’ above).
+
+‘--sparse=WHEN’
+     A “sparse file” contains “holes” – a sequence of zero bytes that
+     does not occupy any file system blocks; the ‘read’ system call
+     reads these as zeros.  This can both save considerable space and
+     increase speed, since many binary files contain lots of consecutive
+     zero bytes.  By default, ‘cp’ detects holes in input source files
+     via a crude heuristic and makes the corresponding output file
+     sparse as well.  Only regular files may be sparse.
+
+     The WHEN value can be one of the following:
+
+     ‘auto’
+          The default behavior: if the input file is sparse, attempt to
+          make the output file sparse, too.  However, if an output file
+          exists but refers to a non-regular file, then do not attempt
+          to make it sparse.
+
+     ‘always’
+          For each sufficiently long sequence of zero bytes in the input
+          file, attempt to create a corresponding hole in the output
+          file, even if the input file does not appear to be sparse.
+          This is useful when the input file resides on a file system
+          that does not support sparse files (for example, ‘efs’ file
+          systems in SGI IRIX 5.3 and earlier), but the output file is
+          on a type of file system that does support them.  Holes may be
+          created only in regular files, so if the destination file is
+          of some other type, ‘cp’ does not even try to make it sparse.
+
+     ‘never’
+          Never make the output file sparse.  This is useful in creating
+          a file for use with the ‘mkswap’ command, since such a file
+          must not have any holes.
+
+     For example, with the following alias, ‘cp’ will use the minimum
+     amount of space supported by the file system.  (Older versions of
+     ‘cp’ can also benefit from ‘--reflink=auto’ here.)
+
+          alias cp='cp --sparse=always'
+
+‘--strip-trailing-slashes’
+     Remove any trailing slashes from each SOURCE argument.  *Note
+     Trailing slashes::.
+
+‘-s’
+‘--symbolic-link’
+     Make symbolic links instead of copies of non-directories.  All
+     source file names must be absolute (starting with ‘/’) unless the
+     destination files are in the current directory.  This option merely
+     results in an error message on systems that do not support symbolic
+     links.
+
+‘-S SUFFIX’
+‘--suffix=SUFFIX’
+     Append SUFFIX to each backup file made with ‘-b’.  *Note Backup
+     options::.
+
+‘-t DIRECTORY’
+‘--target-directory=DIRECTORY’
+     Specify the destination DIRECTORY.  *Note Target directory::.
+
+‘-T’
+‘--no-target-directory’
+     Do not treat the last operand specially when it is a directory or a
+     symbolic link to a directory.  *Note Target directory::.
+
+‘-u’
+‘--update[=WHICH]’
+     Do not copy a non-directory that has an existing destination with
+     the same or newer modification timestamp; instead, silently skip
+     the file without failing.  If timestamps are being preserved, the
+     comparison is to the source timestamp truncated to the resolutions
+     of the destination file system and of the system calls used to
+     update timestamps; this avoids duplicate work if several ‘cp -pu’
+     commands are executed with the same source and destination.  This
+     option is ignored if the ‘-n’ or ‘--no-clobber’ option is also
+     specified.  Also, if ‘--preserve=links’ is also specified (like
+     with ‘cp -au’ for example), that will take precedence;
+     consequently, depending on the order that files are processed from
+     the source, newer files in the destination may be replaced, to
+     mirror hard links in the source.
+
+     WHICH gives more control over which existing files in the
+     destination are replaced, and its value can be one of the
+     following:
+
+     ‘all’
+          This is the default operation when an ‘--update’ option is not
+          specified, and results in all existing files in the
+          destination being replaced.
+
+     ‘none’
+          This is similar to the ‘--no-clobber’ option, in that no files
+          in the destination are replaced, but also skipping a file does
+          not induce a failure.
+
+     ‘older’
+          This is the default operation when ‘--update’ is specified,
+          and results in files being replaced if they’re older than the
+          corresponding source file.
+
+‘-v’
+‘--verbose’
+     Print the name of each file before copying it.
+
+‘-x’
+‘--one-file-system’
+     Skip subdirectories that are on different file systems from the one
+     that the copy started on.  However, mount point directories _are_
+     copied.
+
+‘-Z’
+‘--context[=CONTEXT]’
+     Without a specified CONTEXT, adjust the SELinux security context
+     according to the system default type for destination files,
+     similarly to the ‘restorecon’ command.  The long form of this
+     option with a specific context specified, will set the context for
+     newly created files only.  With a specified context, if both
+     SELinux and SMACK are disabled, a warning is issued.  This option
+     is mutually exclusive with the ‘--preserve=context’ option, and
+     overrides the ‘--preserve=all’ and ‘-a’ options.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: dd invocation,  Next: install invocation,  Prev: cp invocation,  Up: Basic operations
+
+11.2 ‘dd’: Convert and copy a file
+==================================
+
+‘dd’ copies input to output with a changeable I/O block size, while
+optionally performing conversions on the data.  Synopses:
+
+     dd [OPERAND]...
+     dd OPTION
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   By default, ‘dd’ copies standard input to standard output.  To copy,
+‘dd’ repeatedly does the following steps in order:
+
+  1. Read an input block.
+
+  2. If converting via ‘sync’, pad as needed to meet the input block
+     size.  Pad with spaces if converting via ‘block’ or ‘unblock’, NUL
+     bytes otherwise.
+
+  3. If ‘bs=’ is given and no conversion mentioned in steps (4) or (5)
+     is given, output the data as a single block and skip all remaining
+     steps.
+
+  4. If the ‘swab’ conversion is given, swap each pair of input bytes.
+     If the input data length is odd, preserve the last input byte
+     (since there is nothing to swap it with).
+
+  5. If any of the conversions ‘swab’, ‘block’, ‘unblock’, ‘lcase’,
+     ‘ucase’, ‘ascii’, ‘ebcdic’ and ‘ibm’ are given, do these
+     conversions.  These conversions operate independently of input
+     blocking, and might deal with records that span block boundaries.
+
+  6. Aggregate the resulting data into output blocks of the specified
+     size, and output each output block in turn.  Do not pad the last
+     output block; it can be shorter than usual.
+
+   ‘dd’ accepts the following operands, whose syntax was inspired by the
+DD (data definition) statement of OS/360 JCL.
+
+‘if=FILE’
+     Read from FILE instead of standard input.
+
+‘of=FILE’
+     Write to FILE instead of standard output.  Unless ‘conv=notrunc’ is
+     given, truncate FILE before writing it.
+
+‘ibs=BYTES’
+     Set the input block size to BYTES.  This makes ‘dd’ read BYTES per
+     block.  The default is 512 bytes.
+
+‘obs=BYTES’
+     Set the output block size to BYTES.  This makes ‘dd’ write BYTES
+     per block.  The default is 512 bytes.
+
+‘bs=BYTES’
+     Set both input and output block sizes to BYTES.  This makes ‘dd’
+     read and write BYTES per block, overriding any ‘ibs’ and ‘obs’
+     settings.  In addition, if no data-transforming ‘conv’ operand is
+     specified, input is copied to the output as soon as it’s read, even
+     if it is smaller than the block size.
+
+‘cbs=BYTES’
+     Set the conversion block size to BYTES.  When converting
+     variable-length records to fixed-length ones (‘conv=block’) or the
+     reverse (‘conv=unblock’), use BYTES as the fixed record length.
+
+‘skip=N’
+‘iseek=N’
+     Skip N ‘ibs’-byte blocks in the input file before copying.  If N
+     ends in the letter ‘B’, interpret N as a byte count rather than a
+     block count.  (‘B’ and the ‘iseek=’ spelling are GNU extensions to
+     POSIX.)
+
+‘seek=N’
+‘oseek=N’
+     Skip N ‘obs’-byte blocks in the output file before truncating or
+     copying.  If N ends in the letter ‘B’, interpret N as a byte count
+     rather than a block count.  (‘B’ and the ‘oseek=’ spelling are GNU
+     extensions to POSIX.)
+
+‘count=N’
+     Copy N ‘ibs’-byte blocks from the input file, instead of everything
+     until the end of the file.  If N ends in the letter ‘B’, interpret
+     N as a byte count rather than a block count; this is a GNU
+     extension to POSIX. If short reads occur, as could be the case when
+     reading from a pipe for example, ‘iflag=fullblock’ ensures that
+     ‘count=’ counts complete input blocks rather than input read
+     operations.  As an extension to POSIX, ‘count=0’ copies zero blocks
+     instead of copying all blocks.
+
+‘status=LEVEL’
+     Specify the amount of information printed.  If this operand is
+     given multiple times, the last one takes precedence.  The LEVEL
+     value can be one of the following:
+
+     ‘none’
+          Do not print any informational or warning messages to standard
+          error.  Error messages are output as normal.
+
+     ‘noxfer’
+          Do not print the final transfer rate and volume statistics
+          that normally make up the last status line.
+
+     ‘progress’
+          Print the transfer rate and volume statistics on standard
+          error, when processing each input block.  Statistics are
+          output on a single line at most once every second, but updates
+          can be delayed when waiting on I/O.
+
+     Transfer information is normally output to standard error upon
+     receipt of the ‘INFO’ signal or when ‘dd’ exits, and defaults to
+     the following form in the C locale:
+
+          7287+1 records in
+          116608+0 records out
+          59703296 bytes (60 MB, 57 MiB) copied, 0.0427974 s, 1.4 GB/s
+
+     The notation ‘W+P’ stands for W whole blocks and P partial blocks.
+     A partial block occurs when a read or write operation succeeds but
+     transfers less data than the block size.  An additional line like
+     ‘1 truncated record’ or ‘10 truncated records’ is output after the
+     ‘records out’ line if ‘conv=block’ processing truncated one or more
+     input records.
+
+     The ‘status=’ operand is a GNU extension to POSIX.
+
+‘conv=CONVERSION[,CONVERSION]...’
+     Convert the file as specified by the CONVERSION argument(s).  (No
+     spaces around any comma(s).)
+
+     Conversions:
+
+     ‘ascii’
+          Convert EBCDIC to ASCII, using the conversion table specified
+          by POSIX.  This provides a 1:1 translation for all 256 bytes.
+          This implies ‘conv=unblock’; input is converted to ASCII
+          before trailing spaces are deleted.
+
+     ‘ebcdic’
+          Convert ASCII to EBCDIC.  This is the inverse of the ‘ascii’
+          conversion.  This implies ‘conv=block’; trailing spaces are
+          added before being converted to EBCDIC.
+
+     ‘ibm’
+          This acts like ‘conv=ebcdic’, except it uses the alternate
+          conversion table specified by POSIX.  This is not a 1:1
+          translation, but reflects common historical practice for ‘~’,
+          ‘[’, and ‘]’.
+
+          The ‘ascii’, ‘ebcdic’, and ‘ibm’ conversions are mutually
+          exclusive.  If you use any of these conversions, you should
+          also use the ‘cbs=’ operand.
+
+     ‘block’
+          For each line in the input, output ‘cbs’ bytes, replacing the
+          input newline with a space and truncating or padding input
+          lines with spaces as necessary.
+
+     ‘unblock’
+          Remove any trailing spaces in each ‘cbs’-sized input block,
+          and append a newline.
+
+          The ‘block’ and ‘unblock’ conversions are mutually exclusive.
+          If you use either of these conversions, you should also use
+          the ‘cbs=’ operand.
+
+     ‘lcase’
+          Change uppercase letters to lowercase.
+
+     ‘ucase’
+          Change lowercase letters to uppercase.
+
+          The ‘lcase’ and ‘ucase’ conversions are mutually exclusive.
+
+     ‘sparse’
+          Try to seek rather than write NUL output blocks.  On a file
+          system that supports sparse files, this will create sparse
+          output when extending the output file.  Be careful when using
+          this conversion in conjunction with ‘conv=notrunc’ or
+          ‘oflag=append’.  With ‘conv=notrunc’, existing data in the
+          output file corresponding to NUL blocks from the input, will
+          be untouched.  With ‘oflag=append’ the seeks performed will be
+          ineffective.  Similarly, when the output is a device rather
+          than a file, NUL input blocks are not copied, and therefore
+          this conversion is most useful with virtual or pre zeroed
+          devices.
+
+          The ‘sparse’ conversion is a GNU extension to POSIX.
+
+     ‘swab’
+          Swap every pair of input bytes.
+
+     ‘sync’
+          Pad every input block to size of ‘ibs’ with trailing zero
+          bytes.  When used with ‘block’ or ‘unblock’, pad with spaces
+          instead of zero bytes.
+
+     The following “conversions” are really file flags and don’t affect
+     internal processing:
+
+     ‘excl’
+          Fail if the output file already exists; ‘dd’ must create the
+          output file itself.
+
+     ‘nocreat’
+          Do not create the output file; the output file must already
+          exist.
+
+          The ‘excl’ and ‘nocreat’ conversions are mutually exclusive,
+          and are GNU extensions to POSIX.
+
+     ‘notrunc’
+          Do not truncate the output file.
+
+     ‘noerror’
+          Continue after read errors.
+
+     ‘fdatasync’
+          Synchronize output data just before finishing, even if there
+          were write errors.  This forces a physical write of output
+          data, so that even if power is lost the output data will be
+          preserved.  If neither this nor ‘fsync’ are specified, output
+          is treated as usual with file systems, i.e., output data and
+          metadata may be cached in primary memory for some time before
+          the operating system physically writes it, and thus output
+          data and metadata may be lost if power is lost.  *Note sync
+          invocation::.  This conversion is a GNU extension to POSIX.
+
+     ‘fsync’
+          Synchronize output data and metadata just before finishing,
+          even if there were write errors.  This acts like ‘fdatasync’
+          except it also preserves output metadata, such as the
+          last-modified time of the output file; for this reason it may
+          be a bit slower than ‘fdatasync’ although the performance
+          difference is typically insignificant for ‘dd’.  This
+          conversion is a GNU extension to POSIX.
+
+‘iflag=FLAG[,FLAG]...’
+     Access the input file using the flags specified by the FLAG
+     argument(s).  (No spaces around any comma(s).)
+
+‘oflag=FLAG[,FLAG]...’
+     Access the output file using the flags specified by the FLAG
+     argument(s).  (No spaces around any comma(s).)
+
+     Here are the flags.
+
+     ‘append’
+          Write in append mode, so that even if some other process is
+          writing to this file, every ‘dd’ write will append to the
+          current contents of the file.  This flag makes sense only for
+          output.  If you combine this flag with the ‘of=FILE’ operand,
+          you should also specify ‘conv=notrunc’ unless you want the
+          output file to be truncated before being appended to.
+
+     ‘cio’
+          Use concurrent I/O mode for data.  This mode performs direct
+          I/O and drops the POSIX requirement to serialize all I/O to
+          the same file.  A file cannot be opened in CIO mode and with a
+          standard open at the same time.
+
+     ‘direct’
+          Use direct I/O for data, avoiding the buffer cache.  Note that
+          the kernel may impose restrictions on read or write buffer
+          sizes.  For example, with an ext4 destination file system and
+          a Linux-based kernel, using ‘oflag=direct’ will cause writes
+          to fail with ‘EINVAL’ if the output buffer size is not a
+          multiple of 512.
+
+     ‘directory’
+
+          Fail unless the file is a directory.  Most operating systems
+          do not allow I/O to a directory, so this flag has limited
+          utility.
+
+     ‘dsync’
+          Use synchronized I/O for data.  For the output file, this
+          forces a physical write of output data on each write.  For the
+          input file, this flag can matter when reading from a remote
+          file that has been written to synchronously by some other
+          process.  Metadata (e.g., last-access and last-modified time)
+          is not necessarily synchronized.
+
+     ‘sync’
+          Use synchronized I/O for both data and metadata.
+
+     ‘nocache’
+          Request to discard the system data cache for a file.  When
+          count=0 all cached data for the file is specified, otherwise
+          the cache is dropped for the processed portion of the file.
+          Also when count=0, failure to discard the cache is diagnosed
+          and reflected in the exit status.
+
+          Note data that is not already persisted to storage will not be
+          discarded from cache, so note the use of the ‘sync’
+          conversions in the examples below, which are used to maximize
+          the effectiveness of the ‘nocache’ flag.
+
+          Here are some usage examples:
+
+               # Advise to drop cache for whole file
+               dd if=ifile iflag=nocache count=0
+
+               # Ensure drop cache for the whole file
+               dd of=ofile oflag=nocache conv=notrunc,fdatasync count=0
+
+               # Advise to drop cache for part of file
+               # Note the kernel will only consider complete and
+               # already persisted pages.
+               dd if=ifile iflag=nocache skip=10 count=10 of=/dev/null
+
+               # Stream data using just the read-ahead cache.
+               # See also the ‘direct’ flag.
+               dd if=ifile of=ofile iflag=nocache oflag=nocache,sync
+
+     ‘nonblock’
+          Use non-blocking I/O.
+
+     ‘noatime’
+          Do not update the file’s access timestamp.  *Note File
+          timestamps::.  Some older file systems silently ignore this
+          flag, so it is a good idea to test it on your files before
+          relying on it.
+
+     ‘noctty’
+          Do not assign the file to be a controlling terminal for ‘dd’.
+          This has no effect when the file is not a terminal.  On many
+          hosts (e.g., GNU/Linux hosts), this flag has no effect at all.
+
+     ‘nofollow’
+          Do not follow symbolic links.
+
+     ‘nolinks’
+          Fail if the file has multiple hard links.
+
+     ‘binary’
+          Use binary I/O.  This flag has an effect only on nonstandard
+          platforms that distinguish binary from text I/O.
+
+     ‘text’
+          Use text I/O.  Like ‘binary’, this flag has no effect on
+          standard platforms.
+
+     ‘fullblock’
+          Accumulate full blocks from input.  The ‘read’ system call may
+          return early if a full block is not available.  When that
+          happens, continue calling ‘read’ to fill the remainder of the
+          block.  This flag can be used only with ‘iflag’.  This flag is
+          useful with pipes for example as they may return short reads.
+          In that case, this flag is needed to ensure that a ‘count=’
+          argument is interpreted as a block count rather than a count
+          of read operations.
+
+     These flags are all GNU extensions to POSIX. They are not supported
+     on all systems, and ‘dd’ rejects attempts to use them when they are
+     not supported.  When reading from standard input or writing to
+     standard output, the ‘nofollow’ and ‘noctty’ flags should not be
+     specified, and the other flags (e.g., ‘nonblock’) can affect how
+     other processes behave with the affected file descriptors, even
+     after ‘dd’ exits.
+
+   The behavior of ‘dd’ is unspecified if operands other than ‘conv=’,
+‘iflag=’, ‘oflag=’, and ‘status=’ are specified more than once.
+
+   The numeric-valued strings above (N and BYTES) are unsigned decimal
+integers that can be followed by a multiplier: ‘b’=512, ‘c’=1, ‘w’=2,
+‘xM’=M, or any of the standard block size suffixes like ‘k’=1024 (*note
+Block size::).  These multipliers are GNU extensions to POSIX, except
+that POSIX allows BYTES to be followed by ‘k’, ‘b’, and ‘xM’.  Note ‘xM’
+can be used more than once in a number.  Block sizes (i.e., specified by
+BYTES strings) must be nonzero.
+
+   Any block size you specify via ‘bs=’, ‘ibs=’, ‘obs=’, ‘cbs=’ should
+not be too large – values larger than a few megabytes are generally
+wasteful or (as in the gigabyte..exabyte case) downright
+counterproductive or error-inducing.
+
+   To process data with offset or size that is not a multiple of the I/O
+block size, you can use a numeric string N that ends in the letter ‘B’.
+For example, the following shell commands copy data in 1 MiB blocks
+between a flash drive and a tape, but do not save or restore a 512-byte
+area at the start of the flash drive:
+
+     flash=/dev/sda
+     tape=/dev/st0
+
+     # Copy all but the initial 512 bytes from flash to tape.
+     dd if=$flash iseek=512B bs=1MiB of=$tape
+
+     # Copy from tape back to flash, leaving initial 512 bytes alone.
+     dd if=$tape bs=1MiB of=$flash oseek=512B
+
+   For failing storage devices, other tools come with a great variety of
+extra functionality to ease the saving of as much data as possible
+before the device finally dies, e.g.  GNU ‘ddrescue’
+(https://www.gnu.org/software/ddrescue/).  However, in some cases such a
+tool is not available or the administrator feels more comfortable with
+the handling of ‘dd’.  As a simple rescue method, call ‘dd’ as shown in
+the following example: the operand ‘conv=noerror,sync’ is used to
+continue after read errors and to pad out bad reads with NULs, while
+‘iflag=fullblock’ caters for short reads (which traditionally never
+occur on flash or similar devices):
+
+     # Rescue data from an (unmounted!) partition of a failing device.
+     dd conv=noerror,sync iflag=fullblock </dev/sda1 > /mnt/rescue.img
+
+   Sending an ‘INFO’ signal (or ‘USR1’ signal where that is unavailable)
+to a running ‘dd’ process makes it print I/O statistics to standard
+error and then resume copying.  In the example below, ‘dd’ is run in the
+background to copy 5GB of data.  The ‘kill’ command makes it output
+intermediate I/O statistics, and when ‘dd’ completes normally or is
+killed by the ‘SIGINT’ signal, it outputs the final statistics.
+
+     # Ignore the signal so we never inadvertently terminate the dd child.
+     # Note this is not needed when SIGINFO is available.
+     trap '' USR1
+
+     # Run dd with the fullblock iflag to avoid short reads
+     # which can be triggered by reception of signals.
+     dd iflag=fullblock if=/dev/zero of=/dev/null count=5000000 bs=1000 & pid=$!
+
+     # Output stats every second.
+     while kill -s USR1 $pid 2>/dev/null; do sleep 1; done
+
+   The above script will output in the following format:
+
+     3441325+0 records in
+     3441325+0 records out
+     3441325000 bytes (3.4 GB, 3.2 GiB) copied, 1.00036 s, 3.4 GB/s
+     5000000+0 records in
+     5000000+0 records out
+     5000000000 bytes (5.0 GB, 4.7 GiB) copied, 1.44433 s, 3.5 GB/s
+
+   The ‘status=progress’ operand periodically updates the last line of
+the transfer statistics above.
+
+   On systems lacking the ‘INFO’ signal ‘dd’ responds to the ‘USR1’
+signal instead, unless the ‘POSIXLY_CORRECT’ environment variable is
+set.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: install invocation,  Next: mv invocation,  Prev: dd invocation,  Up: Basic operations
+
+11.3 ‘install’: Copy files and set attributes
+=============================================
+
+‘install’ copies files while setting their file mode bits and, if
+possible, their owner and group.  Synopses:
+
+     install [OPTION]... [-T] SOURCE DEST
+     install [OPTION]... SOURCE... DIRECTORY
+     install [OPTION]... -t DIRECTORY SOURCE...
+     install [OPTION]... -d DIRECTORY...
+
+   • If two file names are given, ‘install’ copies the first file to the
+     second.
+
+   • If the ‘--target-directory’ (‘-t’) option is given, or failing that
+     if the last file is a directory and the ‘--no-target-directory’
+     (‘-T’) option is not given, ‘install’ copies each SOURCE file to
+     the specified directory, using the SOURCEs’ names.
+
+   • If the ‘--directory’ (‘-d’) option is given, ‘install’ creates each
+     DIRECTORY and any missing parent directories.  Parent directories
+     are created with mode ‘u=rwx,go=rx’ (755), regardless of the ‘-m’
+     option or the current umask.  *Note Directory Setuid and Setgid::,
+     for how the set-user-ID and set-group-ID bits of parent directories
+     are inherited.
+
+   ‘install’ is similar to ‘cp’, but allows you to control the
+attributes of destination files.  It is typically used in Makefiles to
+copy programs into their destination directories.  It refuses to copy
+files onto themselves.
+
+   ‘install’ never preserves extended attributes (xattr).
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b’
+‘--backup[=METHOD]’
+     *Note Backup options::.  Make a backup of each file that would
+     otherwise be overwritten or removed.
+
+‘-C’
+‘--compare’
+     Compare content of source and destination files, and if there would
+     be no change to the destination content, owner, group, permissions,
+     and possibly SELinux context, then do not modify the destination at
+     all.  Note this option is best used in conjunction with ‘--user’,
+     ‘--group’ and ‘--mode’ options, lest ‘install’ incorrectly
+     determines the default attributes that installed files would have
+     (as it doesn’t consider setgid directories and POSIX default ACLs
+     for example).  This could result in redundant copies or attributes
+     that are not reset to the correct defaults.
+
+‘-c’
+     Ignored; for compatibility with old Unix versions of ‘install’.
+
+‘-D’
+     Create any missing parent directories of DEST, then copy SOURCE to
+     DEST.  Explicitly specifying the ‘--target-directory=DIR’ will
+     similarly ensure the presence of that hierarchy before copying
+     SOURCE arguments.
+
+‘-d’
+‘--directory’
+     Create any missing parent directories, giving them the default
+     attributes.  Then create each given directory, setting their owner,
+     group and mode as given on the command line or to the defaults.
+
+‘--debug’
+     Print extra information to stdout, explaining how files are copied.
+     This option implies the ‘--verbose’ option.
+
+‘-g GROUP’
+‘--group=GROUP’
+     Set the group ownership of installed files or directories to GROUP.
+     The default is the process’s current group.  GROUP may be either a
+     group name or a numeric group ID.
+
+‘-m MODE’
+‘--mode=MODE’
+     Set the file mode bits for the installed file or directory to MODE,
+     which can be either an octal number, or a symbolic mode as in
+     ‘chmod’, with ‘a=’ (no access allowed to anyone) as the point of
+     departure (*note File permissions::).  The default mode is
+     ‘u=rwx,go=rx,a-s’ – read, write, and execute for the owner, read
+     and execute for group and other, and with set-user-ID and
+     set-group-ID disabled.  This default is not quite the same as
+     ‘755’, since it disables instead of preserving set-user-ID and
+     set-group-ID on directories.  *Note Directory Setuid and Setgid::.
+
+‘-o OWNER’
+‘--owner=OWNER’
+     If ‘install’ has appropriate privileges (is run as root), set the
+     ownership of installed files or directories to OWNER.  The default
+     is ‘root’.  OWNER may be either a user name or a numeric user ID.
+
+‘--preserve-context’
+     Preserve the SELinux security context of files and directories.
+     Failure to preserve the context in all of the files or directories
+     will result in an exit status of 1.  If SELinux is disabled then
+     print a warning and ignore the option.
+
+‘-p’
+‘--preserve-timestamps’
+     Set the time of last access and the time of last modification of
+     each installed file to match those of each corresponding original
+     file.  When a file is installed without this option, its last
+     access and last modification timestamps are both set to the time of
+     installation.  This option is useful if you want to use the last
+     modification timestamps of installed files to keep track of when
+     they were last built as opposed to when they were last installed.
+
+‘-s’
+‘--strip’
+     Strip the symbol tables from installed binary executables.
+
+‘--strip-program=PROGRAM’
+     Program used to strip binaries.
+
+‘-S SUFFIX’
+‘--suffix=SUFFIX’
+     Append SUFFIX to each backup file made with ‘-b’.  *Note Backup
+     options::.
+
+‘-t DIRECTORY’
+‘--target-directory=DIRECTORY’
+     Specify the destination DIRECTORY.  *Note Target directory::.  Also
+     specifying the ‘-D’ option will ensure the directory is present.
+
+‘-T’
+‘--no-target-directory’
+     Do not treat the last operand specially when it is a directory or a
+     symbolic link to a directory.  *Note Target directory::.
+
+‘-v’
+‘--verbose’
+     Print the name of each file before copying it.
+
+‘-Z’
+‘--context[=CONTEXT]’
+     Without a specified CONTEXT, adjust the SELinux security context
+     according to the system default type for destination files,
+     similarly to the ‘restorecon’ command.  The long form of this
+     option with a specific context specified, will set the context for
+     newly created files only.  With a specified context, if both
+     SELinux and SMACK are disabled, a warning is issued.  This option
+     is mutually exclusive with the ‘--preserve-context’ option.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: mv invocation,  Next: rm invocation,  Prev: install invocation,  Up: Basic operations
+
+11.4 ‘mv’: Move (rename) files
+==============================
+
+‘mv’ moves or renames files (or directories).  Synopses:
+
+     mv [OPTION]... [-T] SOURCE DEST
+     mv [OPTION]... SOURCE... DIRECTORY
+     mv [OPTION]... -t DIRECTORY SOURCE...
+
+   • If two file names are given, ‘mv’ moves the first file to the
+     second.
+
+   • If the ‘--target-directory’ (‘-t’) option is given, or failing that
+     if the last file is a directory and the ‘--no-target-directory’
+     (‘-T’) option is not given, ‘mv’ moves each SOURCE file to the
+     specified directory, using the SOURCEs’ names.
+
+   To move a file, ‘mv’ ordinarily simply renames it.  However, if
+renaming does not work because the destination’s file system differs,
+‘mv’ falls back on copying as if by ‘cp -a’, then (assuming the copy
+succeeded) it removes the original.  If the copy fails, then ‘mv’
+removes any partially created copy in the destination.  If you were to
+copy three directories from one file system to another and the copy of
+the first directory succeeded, but the second didn’t, the first would be
+left on the destination file system and the second and third would be
+left on the original file system.
+
+   ‘mv’ always tries to copy extended attributes (xattr), which may
+include SELinux context, ACLs or Capabilities.  Upon failure all but
+‘Operation not supported’ warnings are output.
+
+   If a destination file exists but is normally unwritable, standard
+input is a terminal, and the ‘-f’ or ‘--force’ option is not given, ‘mv’
+prompts the user for whether to replace the file.  (You might own the
+file, or have write permission on its directory.)  If the response is
+not affirmative, the file is skipped.
+
+   _Warning_: Avoid specifying a source name with a trailing slash, when
+it might be a symlink to a directory.  Otherwise, ‘mv’ may do something
+very surprising, since its behavior depends on the underlying rename
+system call.  On a system with a modern Linux-based kernel, it fails
+with ‘errno=ENOTDIR’.  However, on other systems (at least FreeBSD 6.1
+and Solaris 10) it silently renames not the symlink but rather the
+directory referenced by the symlink.  *Note Trailing slashes::.
+
+   _Note_: ‘mv’ will only replace empty directories in the destination.
+Conflicting populated directories are skipped with a diagnostic.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b’
+‘--backup[=METHOD]’
+     *Note Backup options::.  Make a backup of each file that would
+     otherwise be overwritten or removed.
+
+‘--debug’
+     Print extra information to stdout, explaining how files are copied.
+     This option implies the ‘--verbose’ option.
+
+‘-f’
+‘--force’
+     Do not prompt the user before removing a destination file.  If you
+     specify more than one of the ‘-i’, ‘-f’, ‘-n’ options, only the
+     final one takes effect.
+
+‘-i’
+‘--interactive’
+     Prompt whether to overwrite each existing destination file,
+     regardless of its permissions, and fail if the response is not
+     affirmative.  If you specify more than one of the ‘-i’, ‘-f’, ‘-n’
+     options, only the final one takes effect.
+
+‘-n’
+‘--no-clobber’
+     Do not overwrite an existing file; silently fail instead.  If you
+     specify more than one of the ‘-i’, ‘-f’, ‘-n’ options, only the
+     final one takes effect.  This option is mutually exclusive with
+     ‘-b’ or ‘--backup’ option.  See also the ‘--update=none’ option
+     which will skip existing files but not fail.
+
+‘--no-copy’
+     If a file cannot be renamed because the destination file system
+     differs, fail with a diagnostic instead of copying and then
+     removing the file.
+
+‘-u’
+‘--update’
+     Do not move a non-directory that has an existing destination with
+     the same or newer modification timestamp; instead, silently skip
+     the file without failing.  If the move is across file system
+     boundaries, the comparison is to the source timestamp truncated to
+     the resolutions of the destination file system and of the system
+     calls used to update timestamps; this avoids duplicate work if
+     several ‘mv -u’ commands are executed with the same source and
+     destination.  This option is ignored if the ‘-n’ or ‘--no-clobber’
+     option is also specified.
+
+     WHICH gives more control over which existing files in the
+     destination are replaced, and its value can be one of the
+     following:
+
+     ‘all’
+          This is the default operation when an ‘--update’ option is not
+          specified, and results in all existing files in the
+          destination being replaced.
+
+     ‘none’
+          This is similar to the ‘--no-clobber’ option, in that no files
+          in the destination are replaced, but also skipping a file does
+          not induce a failure.
+
+     ‘older’
+          This is the default operation when ‘--update’ is specified,
+          and results in files being replaced if they’re older than the
+          corresponding source file.
+
+‘-v’
+‘--verbose’
+     Print the name of each file before moving it.
+
+‘--strip-trailing-slashes’
+     Remove any trailing slashes from each SOURCE argument.  *Note
+     Trailing slashes::.
+
+‘-S SUFFIX’
+‘--suffix=SUFFIX’
+     Append SUFFIX to each backup file made with ‘-b’.  *Note Backup
+     options::.
+
+‘-t DIRECTORY’
+‘--target-directory=DIRECTORY’
+     Specify the destination DIRECTORY.  *Note Target directory::.
+
+‘-T’
+‘--no-target-directory’
+     Do not treat the last operand specially when it is a directory or a
+     symbolic link to a directory.  *Note Target directory::.
+
+‘-Z’
+‘--context’
+     This option functions similarly to the ‘restorecon’ command, by
+     adjusting the SELinux security context according to the system
+     default type for destination files and each created directory.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: rm invocation,  Next: shred invocation,  Prev: mv invocation,  Up: Basic operations
+
+11.5 ‘rm’: Remove files or directories
+======================================
+
+‘rm’ removes each given FILE.  By default, it does not remove
+directories.  Synopsis:
+
+     rm [OPTION]... [FILE]...
+
+   If the ‘-I’ or ‘--interactive=once’ option is given, and there are
+more than three files or the ‘-r’, ‘-R’, or ‘--recursive’ are given,
+then ‘rm’ prompts the user for whether to proceed with the entire
+operation.  If the response is not affirmative, the entire command is
+aborted.
+
+   Otherwise, if a file is unwritable, standard input is a terminal, and
+the ‘-f’ or ‘--force’ option is not given, or the ‘-i’ or
+‘--interactive=always’ option _is_ given, ‘rm’ prompts the user for
+whether to remove the file.  If the response is not affirmative, the
+file is skipped.
+
+   Any attempt to remove a file whose last file name component is ‘.’ or
+‘..’ is rejected without any prompting, as mandated by POSIX.
+
+   _Warning_: If you use ‘rm’ to remove a file, it is usually possible
+to recover the contents of that file.  If you want more assurance that
+the contents are unrecoverable, consider using ‘shred’.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-d’
+‘--dir’
+     Remove the listed directories if they are empty.
+
+‘-f’
+‘--force’
+     Ignore nonexistent files and missing operands, and never prompt the
+     user.  Ignore any previous ‘--interactive’ (‘-i’) option.
+
+‘-i’
+     Prompt whether to remove each file.  If the response is not
+     affirmative, silently skip the file without failing.  Ignore any
+     previous ‘--force’ (‘-f’) option.  Equivalent to
+     ‘--interactive=always’.
+
+‘-I’
+     Prompt once whether to proceed with the command, if more than three
+     files are named or if a recursive removal is requested.  Ignore any
+     previous ‘--force’ (‘-f’) option.  Equivalent to
+     ‘--interactive=once’.
+
+‘--interactive [=WHEN]’
+     Specify when to issue an interactive prompt.  WHEN may be omitted,
+     or one of:
+        • never - Do not prompt at all.
+        • once - Prompt once if more than three files are named or if a
+          recursive removal is requested.  Equivalent to ‘-I’.
+        • always - Prompt for every file being removed.  Equivalent to
+          ‘-i’.
+     ‘--interactive’ with no WHEN is equivalent to
+     ‘--interactive=always’.
+
+‘--one-file-system’
+     When removing a hierarchy recursively, do not remove any directory
+     that is on a file system different from that of the corresponding
+     command line argument.  This option is useful when removing a build
+     “chroot” hierarchy, which normally contains no valuable data.
+     However, it is not uncommon to bind-mount ‘/home’ into such a
+     hierarchy, to make it easier to use one’s start-up file.  The catch
+     is that it’s easy to forget to unmount ‘/home’.  Then, when you use
+     ‘rm -rf’ to remove your normally throw-away chroot, that command
+     will remove everything under ‘/home’, too.  Use the
+     ‘--one-file-system’ option, and it will diagnose and skip
+     directories on other file systems.  Of course, this will not save
+     your ‘/home’ if it and your chroot happen to be on the same file
+     system.  See also ‘--preserve-root=all’ to protect command line
+     arguments themselves.
+
+‘--preserve-root [=all]’
+     Fail upon any attempt to remove the root directory, ‘/’, when used
+     with the ‘--recursive’ option.  This is the default behavior.
+     *Note Treating / specially::.  When ‘all’ is specified, reject any
+     command line argument that is not on the same file system as its
+     parent.
+
+‘--no-preserve-root’
+     Do not treat ‘/’ specially when removing recursively.  This option
+     is not recommended unless you really want to remove all the files
+     on your computer.  *Note Treating / specially::.
+
+‘-r’
+‘-R’
+‘--recursive’
+     Remove the listed directories and their contents recursively.
+
+‘-v’
+‘--verbose’
+     Print the name of each file before removing it.
+
+   One common question is how to remove files whose names begin with a
+‘-’.  GNU ‘rm’, like every program that uses the ‘getopt’ function to
+parse its arguments, lets you use the ‘--’ option to indicate that all
+following arguments are non-options.  To remove a file called ‘-f’ in
+the current directory, you could type either:
+
+     rm -- -f
+
+or:
+
+     rm ./-f
+
+   The Unix ‘rm’ program’s use of a single ‘-’ for this purpose predates
+the development of the ‘getopt’ standard syntax.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: shred invocation,  Prev: rm invocation,  Up: Basic operations
+
+11.6 ‘shred’: Remove files more securely
+========================================
+
+‘shred’ overwrites devices or files, to help prevent even extensive
+forensics from recovering the data.
+
+   Ordinarily when you remove a file (*note rm invocation::), its data
+and metadata are not actually destroyed.  Only the file’s directory
+entry is removed, and the file’s storage is reclaimed only when no
+process has the file open and no other directory entry links to the
+file.  And even if file’s data and metadata’s storage space is freed for
+further reuse, there are undelete utilities that will attempt to
+reconstruct the file from the data in freed storage, and that can bring
+the file back if the storage was not rewritten.
+
+   On a busy system with a nearly-full device, space can get reused in a
+few seconds.  But there is no way to know for sure.  And although the
+undelete utilities and already-existing processes require insider or
+superuser access, you may be wary of the superuser, of processes running
+on your behalf, or of attackers that can physically access the storage
+device.  So if you have sensitive data, you may want to be sure that
+recovery is not possible by plausible attacks like these.
+
+   The best way to remove something irretrievably is to destroy the
+media it’s on with acid, melt it down, or the like.  For cheap removable
+media this is often the preferred method.  However, some storage devices
+are expensive or are harder to destroy, so the ‘shred’ utility tries to
+achieve a similar effect non-destructively, by overwriting the file with
+non-sensitive data.
+
+   *Please note* that ‘shred’ relies on a crucial assumption: that the
+file system and hardware overwrite data in place.  Although this is
+common and is the traditional way to do things, many modern file system
+designs do not satisfy this assumption.  Exceptions include:
+
+   • Log-structured or journaled file systems, such as ext3/ext4 (in
+     ‘data=journal’ mode), Btrfs, NTFS, ReiserFS, XFS, ZFS, file systems
+     supplied with AIX and Solaris, etc., when they are configured to
+     journal data.
+
+   • File systems that write redundant data and carry on even if some
+     writes fail, such as RAID-based file systems.
+
+   • File systems that make snapshots, such as Network Appliance’s NFS
+     server.
+
+   • File systems that cache in temporary locations, such as NFS version
+     3 clients.
+
+   • Compressed file systems.
+
+   For ext3 and ext4 file systems, ‘shred’ is less effective when the
+file system is in ‘data=journal’ mode, which journals file data in
+addition to just metadata.  In both the ‘data=ordered’ (default) and
+‘data=writeback’ modes, ‘shred’ works as usual.  The ext3/ext4
+journaling modes can be changed by adding the ‘data=something’ option to
+the mount options for a particular file system in the ‘/etc/fstab’ file,
+as documented in the ‘mount’ man page (‘man mount’).  Alternatively, if
+you know how large the journal is, you can shred the journal by
+shredding enough file data so that the journal cycles around and fills
+up with shredded data.
+
+   If you are not sure how your file system operates, then you should
+assume that it does not overwrite data in place, which means ‘shred’
+cannot reliably operate on regular files in your file system.
+
+   Generally speaking, it is more reliable to shred a device than a
+file, since this bypasses file system design issues mentioned above.
+However, devices are also problematic for shredding, for reasons such as
+the following:
+
+   • Solid-state storage devices (SSDs) typically do wear leveling to
+     prolong service life, and this means writes are distributed to
+     other blocks by the hardware, so “overwritten” data blocks are
+     still present in the underlying device.
+
+   • Most storage devices map out bad blocks invisibly to the
+     application; if the bad blocks contain sensitive data, ‘shred’
+     won’t be able to destroy it.
+
+   • With some obsolete storage technologies, it may be possible to take
+     (say) a floppy disk back to a laboratory and use a lot of sensitive
+     (and expensive) equipment to look for the faint “echoes” of the
+     original data underneath the overwritten data.  With these older
+     technologies, if the file has been overwritten only once, it’s
+     reputedly not even that hard.  Luckily, this kind of data recovery
+     has become difficult, and there is no public evidence that today’s
+     higher-density storage devices can be analyzed in this way.
+
+     The ‘shred’ command can use many overwrite passes, with data
+     patterns chosen to maximize the damage they do to the old data.  By
+     default the patterns are designed for best effect on hard drives
+     using now-obsolete technology; for newer devices, a single pass
+     should suffice.  For more details, see the source code and Peter
+     Gutmann’s paper ‘Secure Deletion of Data from Magnetic and
+     Solid-State Memory’
+     (https://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html), from
+     the proceedings of the Sixth USENIX Security Symposium (San Jose,
+     California, July 22–25, 1996).
+
+   ‘shred’ makes no attempt to detect or report these problems, just as
+it makes no attempt to do anything about backups.  However, since it is
+more reliable to shred devices than files, ‘shred’ by default does not
+deallocate or remove the output file.  This default is more suitable for
+devices, which typically cannot be deallocated and should not be
+removed.
+
+   Finally, consider the risk of backups and mirrors.  File system
+backups and remote mirrors may contain copies of the file that cannot be
+removed, and that will allow a shredded file to be recovered later.  So
+if you keep any data you may later want to destroy using ‘shred’, be
+sure that it is not backed up or mirrored.
+
+     shred [OPTION]... FILE[...]
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-f’
+‘--force’
+     Override file permissions if necessary to allow overwriting.
+
+‘-n NUMBER’
+‘--iterations=NUMBER’
+     By default, ‘shred’ uses 3 passes of overwrite.  You can reduce
+     this to save time, or increase it if you think it’s appropriate.
+     After 25 passes all of the internal overwrite patterns will have
+     been used at least once.
+
+‘--random-source=FILE’
+     Use FILE as a source of random data used to overwrite and to choose
+     pass ordering.  *Note Random sources::.
+
+‘-s BYTES’
+‘--size=BYTES’
+     Shred the first BYTES bytes of the file.  The default is to shred
+     the whole file.  BYTES can be followed by a size specification like
+     ‘K’, ‘M’, or ‘G’ to specify a multiple.  *Note Block size::.
+
+‘-u’
+‘--remove[=HOW]’
+     After shredding a file, deallocate it (if possible) and then remove
+     it.  If a file has multiple links, only the named links will be
+     removed.  Often the file name is less sensitive than the file data,
+     in which case the optional HOW parameter, supported with the long
+     form option, gives control of how to more efficiently remove each
+     directory entry.  The ‘unlink’ parameter will just use a standard
+     unlink call, ‘wipe’ will also first obfuscate bytes in the name,
+     and ‘wipesync’ will also sync each obfuscated byte in the name to
+     the file system.  Note ‘wipesync’ is the default method, but can be
+     expensive, requiring a sync for every character in every file.
+     This can become significant with many files, or is redundant if
+     your file system provides synchronous metadata updates.
+
+‘-v’
+‘--verbose’
+     Display to standard error all status updates as sterilization
+     proceeds.
+
+‘-x’
+‘--exact’
+     By default, ‘shred’ rounds the size of a regular file up to the
+     next multiple of the file system block size to fully erase the
+     slack space in the last block of the file.  This space may contain
+     portions of the current system memory on some systems for example.
+     Use ‘--exact’ to suppress that behavior.  Thus, by default if you
+     shred a 10-byte regular file on a system with 512-byte blocks, the
+     resulting file will be 512 bytes long.  With this option, shred
+     does not increase the apparent size of the file.
+
+‘-z’
+‘--zero’
+     Normally, the last pass that ‘shred’ writes is made up of random
+     data.  If this would be conspicuous on your storage device (for
+     example, because it looks like encrypted data), or you just think
+     it’s tidier, the ‘--zero’ option adds an additional overwrite pass
+     with all zero bits.  This is in addition to the number of passes
+     specified by the ‘--iterations’ option.
+
+   You might use the following command to erase the file system you
+created on a USB flash drive.  This command typically takes several
+minutes, depending on the drive’s size and write speed.  On modern
+storage devices a single pass should be adequate, and will take one
+third the time of the default three-pass approach.
+
+     shred -v -n 1 /dev/sdd1
+
+   Similarly, to erase all data on a selected partition of your device,
+you could give a command like the following.
+
+     # 1 pass, write pseudo-random data; 3x faster than the default
+     shred -v -n1 /dev/sda5
+
+   To be on the safe side, use at least one pass that overwrites using
+pseudo-random data.  I.e., don’t be tempted to use ‘-n0 --zero’, in case
+some device controller optimizes the process of writing blocks of all
+zeros, and thereby does not clear all bytes in a block.  Some SSDs may
+do just that.
+
+   A FILE of ‘-’ denotes standard output.  The intended use of this is
+to shred a removed temporary file.  For example:
+
+     i=$(mktemp)
+     exec 3<>"$i"
+     rm -- "$i"
+     echo "Hello, world" >&3
+     shred - >&3
+     exec 3>-
+
+   However, the command ‘shred - >file’ does not shred the contents of
+FILE, since the shell truncates FILE before invoking ‘shred’.  Use the
+command ‘shred file’ or (if using a Bourne-compatible shell) the command
+‘shred - 1<>file’ instead.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Special file types,  Next: Changing file attributes,  Prev: Basic operations,  Up: Top
+
+12 Special file types
+*********************
+
+This chapter describes commands which create special types of files (and
+‘rmdir’, which removes directories, one special file type).
+
+   Although Unix-like operating systems have markedly fewer special file
+types than others, not _everything_ can be treated only as the
+undifferentiated byte stream of “normal files”.  For example, when a
+file is created or removed, the system must record this information,
+which it does in a “directory” – a special type of file.  Although you
+can read directories as normal files, if you’re curious, in order for
+the system to do its job it must impose a structure, a certain order, on
+the bytes of the file.  Thus it is a “special” type of file.
+
+   Besides directories, other special file types include named pipes
+(FIFOs), symbolic links, sockets, and so-called “special files”.
+
+* Menu:
+
+* link invocation::             Make a hard link via the link syscall
+* ln invocation::               Make links between files.
+* mkdir invocation::            Make directories.
+* mkfifo invocation::           Make FIFOs (named pipes).
+* mknod invocation::            Make block or character special files.
+* readlink invocation::         Print value of a symlink or canonical file name.
+* rmdir invocation::            Remove empty directories.
+* unlink invocation::           Remove files via the unlink syscall
+
+
+File: coreutils.info,  Node: link invocation,  Next: ln invocation,  Up: Special file types
+
+12.1 ‘link’: Make a hard link via the link syscall
+==================================================
+
+‘link’ creates a single hard link at a time.  It is a minimalist
+interface to the system-provided ‘link’ function.  *Note (libc)Hard
+Links::.  It avoids the bells and whistles of the more commonly-used
+‘ln’ command (*note ln invocation::).  Synopsis:
+
+     link FILENAME LINKNAME
+
+   FILENAME must specify an existing file, and LINKNAME must specify a
+nonexistent entry in an existing directory.  ‘link’ simply calls ‘link
+(FILENAME, LINKNAME)’ to create the link.
+
+   On a GNU system, this command acts like ‘ln --directory
+--no-target-directory FILENAME LINKNAME’.  However, the ‘--directory’
+and ‘--no-target-directory’ options are not specified by POSIX, and the
+‘link’ command is more portable in practice.
+
+   If FILENAME is a symbolic link, it is unspecified whether LINKNAME
+will be a hard link to the symbolic link or to the target of the
+symbolic link.  Use ‘ln -P’ or ‘ln -L’ to specify which behavior is
+desired.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: ln invocation,  Next: mkdir invocation,  Prev: link invocation,  Up: Special file types
+
+12.2 ‘ln’: Make links between files
+===================================
+
+‘ln’ makes links between files.  By default, it makes hard links; with
+the ‘-s’ option, it makes symbolic (or “soft”) links.  Synopses:
+
+     ln [OPTION]... [-T] TARGET LINKNAME
+     ln [OPTION]... TARGET
+     ln [OPTION]... TARGET... DIRECTORY
+     ln [OPTION]... -t DIRECTORY TARGET...
+
+   • If two file names are given, ‘ln’ creates a link to the first file
+     from the second.
+
+   • If one TARGET is given, ‘ln’ creates a link to that file in the
+     current directory.
+
+   • If the ‘--target-directory’ (‘-t’) option is given, or failing that
+     if the last file is a directory and the ‘--no-target-directory’
+     (‘-T’) option is not given, ‘ln’ creates a link to each TARGET file
+     in the specified directory, using the TARGETs’ names.
+
+   Normally ‘ln’ does not replace existing files.  Use the ‘--force’
+(‘-f’) option to replace them unconditionally, the ‘--interactive’
+(‘-i’) option to replace them conditionally, and the ‘--backup’ (‘-b’)
+option to rename them.  Unless the ‘--backup’ (‘-b’) option is used
+there is no brief moment when the destination does not exist; this is an
+extension to POSIX.
+
+   A “hard link” is another name for an existing file; the link and the
+original are indistinguishable.  Technically speaking, they share the
+same inode, and the inode contains all the information about a file –
+indeed, it is not incorrect to say that the inode _is_ the file.  Most
+systems prohibit making a hard link to a directory; on those where it is
+allowed, only the super-user can do so (and with caution, since creating
+a cycle will cause problems to many other utilities).  Hard links cannot
+cross file system boundaries.  (These restrictions are not mandated by
+POSIX, however.)
+
+   “Symbolic links” (“symlinks” for short), on the other hand, are a
+special file type (which not all kernels support: System V release 3
+(and older) systems lack symlinks) in which the link file actually
+refers to a different file, by name.  When most operations (opening,
+reading, writing, and so on) are passed the symbolic link file, the
+kernel automatically “dereferences” the link and operates on the target
+of the link.  But some operations (e.g., removing) work on the link file
+itself, rather than on its target.  The owner and group of a symlink are
+not significant to file access performed through the link, but do have
+implications on deleting a symbolic link from a directory with the
+restricted deletion bit set.  On the GNU system, the mode of a symlink
+has no significance and cannot be changed, but on some BSD systems, the
+mode can be changed and will affect whether the symlink will be
+traversed in file name resolution.  *Note (libc)Symbolic Links::.
+
+   Symbolic links can contain arbitrary strings; a “dangling symlink”
+occurs when the string in the symlink does not resolve to a file.  There
+are no restrictions against creating dangling symbolic links.  There are
+trade-offs to using absolute or relative symlinks.  An absolute symlink
+always points to the same file, even if the directory containing the
+link is moved.  However, if the symlink is visible from more than one
+machine (such as on a networked file system), the file pointed to might
+not always be the same.  A relative symbolic link is resolved in
+relation to the directory that contains the link, and is often useful in
+referring to files on the same device without regards to what name that
+device is mounted on when accessed via networked machines.
+
+   When creating a relative symlink in a different location than the
+current directory, the resolution of the symlink will be different than
+the resolution of the same string from the current directory.
+Therefore, many users prefer to first change directories to the location
+where the relative symlink will be created, so that tab-completion or
+other file resolution will find the same target as what will be placed
+in the symlink.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-b’
+‘--backup[=METHOD]’
+     *Note Backup options::.  Make a backup of each file that would
+     otherwise be overwritten or removed.
+
+‘-d’
+‘-F’
+‘--directory’
+     Allow users with appropriate privileges to attempt to make hard
+     links to directories.  However, note that this will probably fail
+     due to system restrictions, even for the super-user.
+
+‘-f’
+‘--force’
+     Remove existing destination files.
+
+‘-i’
+‘--interactive’
+     Prompt whether to remove existing destination files, and fail if
+     the response is not affirmative.
+
+‘-L’
+‘--logical’
+     If ‘-s’ is not in effect, and the source file is a symbolic link,
+     create the hard link to the file referred to by the symbolic link,
+     rather than the symbolic link itself.
+
+‘-n’
+‘--no-dereference’
+     Do not treat the last operand specially when it is a symbolic link
+     to a directory.  Instead, treat it as if it were a normal file.
+
+     When the destination is an actual directory (not a symlink to one),
+     there is no ambiguity.  The link is created in that directory.  But
+     when the specified destination is a symlink to a directory, there
+     are two ways to treat the user’s request.  ‘ln’ can treat the
+     destination just as it would a normal directory and create the link
+     in it.  On the other hand, the destination can be viewed as a
+     non-directory – as the symlink itself.  In that case, ‘ln’ must
+     delete or backup that symlink before creating the new link.  The
+     default is to treat a destination that is a symlink to a directory
+     just like a directory.
+
+     This option is weaker than the ‘--no-target-directory’ (‘-T’)
+     option, so it has no effect if both options are given.
+
+‘-P’
+‘--physical’
+     If ‘-s’ is not in effect, and the source file is a symbolic link,
+     create the hard link to the symbolic link itself.  On platforms
+     where this is not supported by the kernel, this option creates a
+     symbolic link with identical contents; since symbolic link contents
+     cannot be edited, any file name resolution performed through either
+     link will be the same as if a hard link had been created.
+
+‘-r’
+‘--relative’
+     Make symbolic links relative to the link location.  This option is
+     only valid with the ‘--symbolic’ option.
+
+     Example:
+
+          ln -srv /a/file /tmp
+          '/tmp/file' -> '../a/file'
+
+     Relative symbolic links are generated based on their canonicalized
+     containing directory, and canonicalized targets.  I.e., all
+     symbolic links in these file names will be resolved.  *Note
+     realpath invocation::, which gives greater control over relative
+     file name generation, as demonstrated in the following example:
+
+          ln--relative() {
+            test "$1" = --no-symlinks && { nosym=$1; shift; }
+            target="$1";
+            test -d "$2" && link="$2/." || link="$2"
+            rtarget="$(realpath $nosym -m "$target" \
+                        --relative-to "$(dirname "$link")")"
+            ln -s -v "$rtarget" "$link"
+          }
+
+‘-s’
+‘--symbolic’
+     Make symbolic links instead of hard links.  This option merely
+     produces an error message on systems that do not support symbolic
+     links.
+
+‘-S SUFFIX’
+‘--suffix=SUFFIX’
+     Append SUFFIX to each backup file made with ‘-b’.  *Note Backup
+     options::.
+
+‘-t DIRECTORY’
+‘--target-directory=DIRECTORY’
+     Specify the destination DIRECTORY.  *Note Target directory::.
+
+‘-T’
+‘--no-target-directory’
+     Do not treat the last operand specially when it is a directory or a
+     symbolic link to a directory.  *Note Target directory::.
+
+‘-v’
+‘--verbose’
+     Print the name of each file after linking it successfully.
+
+   If ‘-L’ and ‘-P’ are both given, the last one takes precedence.  If
+‘-s’ is also given, ‘-L’ and ‘-P’ are silently ignored.  If neither
+option is given, then this implementation defaults to ‘-P’ if the system
+‘link’ supports hard links to symbolic links (such as the GNU system),
+and ‘-L’ if ‘link’ follows symbolic links (such as on BSD).
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Examples:
+
+     Bad Example:
+
+     # Create link ../a pointing to a in that directory.
+     # Not really useful because it points to itself.
+     ln -s a ..
+
+     Better Example:
+
+     # Change to the target before creating symlinks to avoid being confused.
+     cd ..
+     ln -s adir/a .
+
+     Bad Example:
+
+     # Hard coded file names don't move well.
+     ln -s $(pwd)/a /some/dir/
+
+     Better Example:
+
+     # Relative file names survive directory moves and also
+     # work across networked file systems.
+     ln -s afile anotherfile
+     ln -s ../adir/afile yetanotherfile
+
+
+File: coreutils.info,  Node: mkdir invocation,  Next: mkfifo invocation,  Prev: ln invocation,  Up: Special file types
+
+12.3 ‘mkdir’: Make directories
+==============================
+
+‘mkdir’ creates directories with the specified names.  Synopsis:
+
+     mkdir [OPTION]... NAME...
+
+   ‘mkdir’ creates each directory NAME in the order given.  It reports
+an error if NAME already exists, unless the ‘-p’ option is given and
+NAME is a directory.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-m MODE’
+‘--mode=MODE’
+     Set the file permission bits of created directories to MODE, which
+     uses the same syntax as in ‘chmod’ and uses ‘a=rwx’ (read, write
+     and execute allowed for everyone) for the point of the departure.
+     *Note File permissions::.  This option affects only directories
+     given on the command line; it does not affect any parents that may
+     be created via the ‘-p’ option.
+
+     Normally the directory has the desired file mode bits at the moment
+     it is created.  As a GNU extension, MODE may also mention special
+     mode bits, but in this case there may be a temporary window during
+     which the directory exists but its special mode bits are incorrect.
+     *Note Directory Setuid and Setgid::, for how the set-user-ID and
+     set-group-ID bits of directories are inherited unless overridden in
+     this way.
+
+‘-p’
+‘--parents’
+     Make any missing parent directories for each argument, setting
+     their file permission bits to ‘=rwx,u+wx’, that is, with the umask
+     modified by ‘u+wx’.  Ignore existing parent directories, and do not
+     change their file permission bits.
+
+     If the ‘-m’ option is also given, it does not affect file
+     permission bits of any newly-created parent directories.  To
+     control these bits, set the umask before invoking ‘mkdir’.  For
+     example, if the shell command ‘(umask u=rwx,go=rx; mkdir -p P/Q)’
+     creates the parent ‘P’ it sets the parent’s file permission bits to
+     ‘u=rwx,go=rx’.  (The umask must include ‘u=wx’ for this method to
+     work.)  To set a parent’s special mode bits as well, you can invoke
+     ‘chmod’ after ‘mkdir’.  *Note Directory Setuid and Setgid::, for
+     how the set-user-ID and set-group-ID bits of newly-created parent
+     directories are inherited.
+
+‘-v’
+‘--verbose’
+     Print a message for each created directory.  This is most useful
+     with ‘--parents’.
+
+‘-Z’
+‘--context[=CONTEXT]’
+     Without a specified CONTEXT, adjust the SELinux security context
+     according to the system default type for destination files,
+     similarly to the ‘restorecon’ command.  The long form of this
+     option with a specific context specified, will set the context for
+     newly created files only.  With a specified context, if both
+     SELinux and SMACK are disabled, a warning is issued.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: mkfifo invocation,  Next: mknod invocation,  Prev: mkdir invocation,  Up: Special file types
+
+12.4 ‘mkfifo’: Make FIFOs (named pipes)
+=======================================
+
+‘mkfifo’ creates FIFOs (also called “named pipes”) with the specified
+names.  Synopsis:
+
+     mkfifo [OPTION] NAME...
+
+   A “FIFO” is a special file type that permits independent processes to
+communicate.  One process opens the FIFO file for writing, and another
+for reading, after which data can flow as with the usual anonymous pipe
+in shells or elsewhere.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-m MODE’
+‘--mode=MODE’
+     Set the mode of created FIFOs to MODE, which is symbolic as in
+     ‘chmod’ and uses ‘a=rw’ (read and write allowed for everyone) for
+     the point of departure.  MODE should specify only file permission
+     bits.  *Note File permissions::.
+
+‘-Z’
+‘--context[=CONTEXT]’
+     Without a specified CONTEXT, adjust the SELinux security context
+     according to the system default type for destination files,
+     similarly to the ‘restorecon’ command.  The long form of this
+     option with a specific context specified, will set the context for
+     newly created files only.  With a specified context, if both
+     SELinux and SMACK are disabled, a warning is issued.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: mknod invocation,  Next: readlink invocation,  Prev: mkfifo invocation,  Up: Special file types
+
+12.5 ‘mknod’: Make block or character special files
+===================================================
+
+‘mknod’ creates a FIFO, character special file, or block special file
+with the specified name.  Synopsis:
+
+     mknod [OPTION]... NAME TYPE [MAJOR MINOR]
+
+   Unlike the phrase “special file type” above, the term “special file”
+has a technical meaning on Unix: something that can generate or receive
+data.  Usually this corresponds to a physical piece of hardware, e.g., a
+printer or a flash drive.  (These files are typically created at
+system-configuration time.)  The ‘mknod’ command is what creates files
+of this type.  Such devices can be read either a character at a time or
+a “block” (many characters) at a time, hence we say there are “block
+special” files and “character special” files.
+
+   Due to shell aliases and built-in ‘mknod’ functions, using an
+unadorned ‘mknod’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+mknod ...’) to avoid interference from the shell.
+
+   The arguments after NAME specify the type of file to make:
+
+‘p’
+     for a FIFO
+
+‘b’
+     for a block special file
+
+‘c’
+     for a character special file
+
+   When making a block or character special file, the major and minor
+device numbers must be given after the file type.  If a major or minor
+device number begins with ‘0x’ or ‘0X’, it is interpreted as
+hexadecimal; otherwise, if it begins with ‘0’, as octal; otherwise, as
+decimal.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-m MODE’
+‘--mode=MODE’
+     Set the mode of created files to MODE, which is symbolic as in
+     ‘chmod’ and uses ‘a=rw’ as the point of departure.  MODE should
+     specify only file permission bits.  *Note File permissions::.
+
+‘-Z’
+‘--context[=CONTEXT]’
+     Without a specified CONTEXT, adjust the SELinux security context
+     according to the system default type for destination files,
+     similarly to the ‘restorecon’ command.  The long form of this
+     option with a specific context specified, will set the context for
+     newly created files only.  With a specified context, if both
+     SELinux and SMACK are disabled, a warning is issued.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: readlink invocation,  Next: rmdir invocation,  Prev: mknod invocation,  Up: Special file types
+
+12.6 ‘readlink’: Print value of a symlink or canonical file name
+================================================================
+
+‘readlink’ may work in one of two supported modes:
+
+‘Readlink mode’
+
+     ‘readlink’ outputs the value of the given symbolic links.  If
+     ‘readlink’ is invoked with an argument other than the name of a
+     symbolic link, it produces no output and exits with a nonzero exit
+     code.
+
+‘Canonicalize mode’
+
+     ‘readlink’ outputs the absolute name of the given files which
+     contain no ‘.’, ‘..’ components nor any repeated separators (‘/’)
+     or symbolic links.  Note the ‘realpath’ command is the preferred
+     command to use for canonicalization.  *Note realpath invocation::.
+
+     readlink [OPTION]... FILE...
+
+   By default, ‘readlink’ operates in readlink mode.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-f’
+‘--canonicalize’
+     Activate canonicalize mode.  If any component of the file name
+     except the last one is missing or unavailable, ‘readlink’ produces
+     no output and exits with a nonzero exit code.  A trailing slash is
+     ignored.
+
+‘-e’
+‘--canonicalize-existing’
+     Activate canonicalize mode.  If any component is missing or
+     unavailable, ‘readlink’ produces no output and exits with a nonzero
+     exit code.  A trailing slash requires that the name resolve to a
+     directory.
+
+‘-m’
+‘--canonicalize-missing’
+     Activate canonicalize mode.  If any component is missing or
+     unavailable, ‘readlink’ treats it as a directory.
+
+‘-n’
+‘--no-newline’
+     Do not print the output delimiter, when a single FILE is specified.
+     Print a warning if specified along with multiple FILEs.
+
+‘-s’
+‘-q’
+‘--silent’
+‘--quiet’
+     Suppress most error messages.  On by default.
+
+‘-v’
+‘--verbose’
+     Report error messages.
+
+‘-z’
+‘--zero’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+
+   The ‘readlink’ utility first appeared in OpenBSD 2.1.
+
+   The ‘realpath’ command without options, operates like ‘readlink’ in
+canonicalize mode.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: rmdir invocation,  Next: unlink invocation,  Prev: readlink invocation,  Up: Special file types
+
+12.7 ‘rmdir’: Remove empty directories
+======================================
+
+‘rmdir’ removes empty directories.  Synopsis:
+
+     rmdir [OPTION]... DIRECTORY...
+
+   If any DIRECTORY argument does not refer to an existing empty
+directory, it is an error.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘--ignore-fail-on-non-empty’
+     Ignore each failure to remove a directory that is non-empty.
+
+‘-p’
+‘--parents’
+     Remove DIRECTORY, then try to remove each component of DIRECTORY.
+     So, for example, ‘rmdir -p a/b/c’ is similar to ‘rmdir a/b/c a/b
+     a’.  As such, it fails if any of those directories turns out not to
+     be empty.  Use the ‘--ignore-fail-on-non-empty’ option to make it
+     so such a failure does not evoke a diagnostic and does not cause
+     ‘rmdir’ to exit unsuccessfully.
+
+‘-v’
+‘--verbose’
+     Give a diagnostic for each successful removal.  DIRECTORY is
+     removed.
+
+   *Note rm invocation::, for how to remove non-empty directories
+recursively.
+
+   To remove all empty directories under DIRNAME, including directories
+that become empty because other directories are removed, you can use
+either of the following commands:
+
+     # This uses GNU extensions.
+     find DIRNAME -type d -empty -delete
+
+     # This runs on any POSIX platform.
+     find DIRNAME -depth -type d -exec rmdir {} +
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: unlink invocation,  Prev: rmdir invocation,  Up: Special file types
+
+12.8 ‘unlink’: Remove files via the unlink syscall
+==================================================
+
+‘unlink’ deletes a single specified file name.  It is a minimalist
+interface to the system-provided ‘unlink’ function.  *Note
+(libc)Deleting Files::.  Synopsis: It avoids the bells and whistles of
+the more commonly-used ‘rm’ command (*note rm invocation::).
+
+     unlink FILENAME
+
+   On some systems ‘unlink’ can be used to delete the name of a
+directory.  On others, it can be used that way only by a privileged
+user.  In the GNU system ‘unlink’ can never delete the name of a
+directory.
+
+   The ‘unlink’ command honors the ‘--help’ and ‘--version’ options.  To
+remove a file whose name begins with ‘-’, prefix the name with ‘./’,
+e.g., ‘unlink ./--help’.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Changing file attributes,  Next: File space usage,  Prev: Special file types,  Up: Top
+
+13 Changing file attributes
+***************************
+
+A file is not merely its contents, a name, and a file type (*note
+Special file types::).  A file also has an owner (a user ID), a group (a
+group ID), permissions (what the owner can do with the file, what people
+in the group can do, and what everyone else can do), various timestamps,
+and other information.  Collectively, we call these a file’s
+“attributes”.
+
+   These commands change file attributes.
+
+* Menu:
+
+* chown invocation::            Change file owners and groups.
+* chgrp invocation::            Change file groups.
+* chmod invocation::            Change access permissions.
+* touch invocation::            Change file timestamps.
+
+
+File: coreutils.info,  Node: chown invocation,  Next: chgrp invocation,  Up: Changing file attributes
+
+13.1 ‘chown’: Change file owner and group
+=========================================
+
+‘chown’ changes the user and/or group ownership of each given FILE to
+NEW-OWNER or to the user and group of an existing reference file.
+Synopsis:
+
+     chown [OPTION]... {NEW-OWNER | --reference=REF_FILE} FILE...
+
+   If used, NEW-OWNER specifies the new owner and/or group as follows
+(with no embedded white space):
+
+     [OWNER] [ : [GROUP] ]
+
+   Specifically:
+
+OWNER
+     If only an OWNER (a user name or numeric user ID) is given, that
+     user is made the owner of each given file, and the files’ group is
+     not changed.
+
+OWNER‘:’GROUP
+     If the OWNER is followed by a colon and a GROUP (a group name or
+     numeric group ID), with no spaces between them, the group ownership
+     of the files is changed as well (to GROUP).
+
+OWNER‘:’
+     If a colon but no group name follows OWNER, that user is made the
+     owner of the files and the group of the files is changed to OWNER’s
+     login group.
+
+‘:’GROUP
+     If the colon and following GROUP are given, but the owner is
+     omitted, only the group of the files is changed; in this case,
+     ‘chown’ performs the same function as ‘chgrp’.
+
+‘:’
+     If only a colon is given, or if NEW-OWNER is empty, neither the
+     owner nor the group is changed.
+
+   If OWNER or GROUP is intended to represent a numeric user or group
+ID, then you may specify it with a leading ‘+’.  *Note Disambiguating
+names and IDs::.
+
+   Some older scripts may still use ‘.’ in place of the ‘:’ separator.
+POSIX 1003.1-2001 (*note Standards conformance::) does not require
+support for that, but for backward compatibility GNU ‘chown’ supports
+‘.’ so long as no ambiguity results, although it issues a warning and
+support may be removed in future versions.  New scripts should avoid the
+use of ‘.’ because it is not portable, and because it has undesirable
+results if the entire OWNER‘.’GROUP happens to identify a user whose
+name contains ‘.’.
+
+   It is system dependent whether a user can change the group to an
+arbitrary one, or the more portable behavior of being restricted to
+setting a group of which the user is a member.
+
+   The ‘chown’ command sometimes clears the set-user-ID or set-group-ID
+permission bits.  This behavior depends on the policy and functionality
+of the underlying ‘chown’ system call, which may make system-dependent
+file mode modifications outside the control of the ‘chown’ command.  For
+example, the ‘chown’ command might not affect those bits when invoked by
+a user with appropriate privileges, or when the bits signify some
+function other than executable permission (e.g., mandatory locking).
+When in doubt, check the underlying system behavior.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c’
+‘--changes’
+     Verbosely describe the action for each FILE whose ownership
+     actually changes.
+
+‘-f’
+‘--silent’
+‘--quiet’
+     Do not print error messages about files whose ownership cannot be
+     changed.
+
+‘--from=OLD-OWNER’
+     Change a FILE’s ownership only if it has current attributes
+     specified by OLD-OWNER.  OLD-OWNER has the same form as NEW-OWNER
+     described above.  This option is useful primarily from a security
+     standpoint in that it narrows considerably the window of potential
+     abuse.  For example, to reflect a user ID numbering change for one
+     user’s files without an option like this, ‘root’ might run
+
+          find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER
+
+     But that is dangerous because the interval between when the ‘find’
+     tests the existing file’s owner and when the ‘chown’ is actually
+     run may be quite large.  One way to narrow the gap would be to
+     invoke chown for each file as it is found:
+
+          find / -owner OLDUSER -exec chown -h NEWUSER {} \;
+
+     But that is very slow if there are many affected files.  With this
+     option, it is safer (the gap is narrower still) though still not
+     perfect:
+
+          chown -h -R --from=OLDUSER NEWUSER /
+
+‘--dereference’
+     Do not act on symbolic links themselves but rather on what they
+     point to.  This is the default when not operating recursively.
+
+     Combining this dereferencing option with the ‘--recursive’ option
+     may create a security risk: During the traversal of the directory
+     tree, an attacker may be able to introduce a symlink to an
+     arbitrary target; when the tool reaches that, the operation will be
+     performed on the target of that symlink, possibly allowing the
+     attacker to escalate privileges.
+
+‘-h’
+‘--no-dereference’
+     Act on symbolic links themselves instead of what they point to.
+     This mode relies on the ‘lchown’ system call.  On systems that do
+     not provide the ‘lchown’ system call, ‘chown’ fails when a file
+     specified on the command line is a symbolic link.  By default, no
+     diagnostic is issued for symbolic links encountered during a
+     recursive traversal, but see ‘--verbose’.
+
+‘--preserve-root’
+     Fail upon any attempt to recursively change the root directory,
+     ‘/’.  Without ‘--recursive’, this option has no effect.  *Note
+     Treating / specially::.
+
+‘--no-preserve-root’
+     Cancel the effect of any preceding ‘--preserve-root’ option.  *Note
+     Treating / specially::.
+
+‘--reference=REF_FILE’
+     Change the user and group of each FILE to be the same as those of
+     REF_FILE.  If REF_FILE is a symbolic link, do not use the user and
+     group of the symbolic link, but rather those of the file it refers
+     to.
+
+‘-v’
+‘--verbose’
+     Output a diagnostic for every file processed.  If a symbolic link
+     is encountered during a recursive traversal on a system without the
+     ‘lchown’ system call, and ‘--no-dereference’ is in effect, then
+     issue a diagnostic saying neither the symbolic link nor its
+     referent is being changed.
+
+‘-R’
+‘--recursive’
+     Recursively change ownership of directories and their contents.
+
+‘-H’
+     If ‘--recursive’ (‘-R’) is specified and a command line argument is
+     a symbolic link to a directory, traverse it.  *Note Traversing
+     symlinks::.
+
+‘-L’
+     In a recursive traversal, traverse every symbolic link to a
+     directory that is encountered.
+
+     Combining this dereferencing option with the ‘--recursive’ option
+     may create a security risk: During the traversal of the directory
+     tree, an attacker may be able to introduce a symlink to an
+     arbitrary target; when the tool reaches that, the operation will be
+     performed on the target of that symlink, possibly allowing the
+     attacker to escalate privileges.
+
+     *Note Traversing symlinks::.
+
+‘-P’
+     Do not traverse any symbolic links.  This is the default if none of
+     ‘-H’, ‘-L’, or ‘-P’ is specified.  *Note Traversing symlinks::.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Examples:
+
+     # Change the owner of /u to "root".
+     chown root /u
+
+     # Likewise, but also change its group to "staff".
+     chown root:staff /u
+
+     # Change the owner of /u and subfiles to "root".
+     chown -hR root /u
+
+
+File: coreutils.info,  Node: chgrp invocation,  Next: chmod invocation,  Prev: chown invocation,  Up: Changing file attributes
+
+13.2 ‘chgrp’: Change group ownership
+====================================
+
+‘chgrp’ changes the group ownership of each given FILE to GROUP (which
+can be either a group name or a numeric group ID) or to the group of an
+existing reference file.  *Note chown invocation::.  Synopsis:
+
+     chgrp [OPTION]... {GROUP | --reference=REF_FILE} FILE...
+
+   If GROUP is intended to represent a numeric group ID, then you may
+specify it with a leading ‘+’.  *Note Disambiguating names and IDs::.
+
+   It is system dependent whether a user can change the group to an
+arbitrary one, or the more portable behavior of being restricted to
+setting a group of which the user is a member.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c’
+‘--changes’
+     Verbosely describe the action for each FILE whose group actually
+     changes.
+
+‘-f’
+‘--silent’
+‘--quiet’
+     Do not print error messages about files whose group cannot be
+     changed.
+
+‘--dereference’
+     Do not act on symbolic links themselves but rather on what they
+     point to.  This is the default when not operating recursively.
+
+     Combining this dereferencing option with the ‘--recursive’ option
+     may create a security risk: During the traversal of the directory
+     tree, an attacker may be able to introduce a symlink to an
+     arbitrary target; when the tool reaches that, the operation will be
+     performed on the target of that symlink, possibly allowing the
+     attacker to escalate privileges.
+
+‘-h’
+‘--no-dereference’
+     Act on symbolic links themselves instead of what they point to.
+     This mode relies on the ‘lchown’ system call.  On systems that do
+     not provide the ‘lchown’ system call, ‘chgrp’ fails when a file
+     specified on the command line is a symbolic link.  By default, no
+     diagnostic is issued for symbolic links encountered during a
+     recursive traversal, but see ‘--verbose’.
+
+‘--preserve-root’
+     Fail upon any attempt to recursively change the root directory,
+     ‘/’.  Without ‘--recursive’, this option has no effect.  *Note
+     Treating / specially::.
+
+‘--no-preserve-root’
+     Cancel the effect of any preceding ‘--preserve-root’ option.  *Note
+     Treating / specially::.
+
+‘--reference=REF_FILE’
+     Change the group of each FILE to be the same as that of REF_FILE.
+     If REF_FILE is a symbolic link, do not use the group of the
+     symbolic link, but rather that of the file it refers to.
+
+‘-v’
+‘--verbose’
+     Output a diagnostic for every file processed.  If a symbolic link
+     is encountered during a recursive traversal on a system without the
+     ‘lchown’ system call, and ‘--no-dereference’ is in effect, then
+     issue a diagnostic saying neither the symbolic link nor its
+     referent is being changed.
+
+‘-R’
+‘--recursive’
+     Recursively change the group ownership of directories and their
+     contents.
+
+‘-H’
+     If ‘--recursive’ (‘-R’) is specified and a command line argument is
+     a symbolic link to a directory, traverse it.  *Note Traversing
+     symlinks::.
+
+‘-L’
+     In a recursive traversal, traverse every symbolic link to a
+     directory that is encountered.
+
+     Combining this dereferencing option with the ‘--recursive’ option
+     may create a security risk: During the traversal of the directory
+     tree, an attacker may be able to introduce a symlink to an
+     arbitrary target; when the tool reaches that, the operation will be
+     performed on the target of that symlink, possibly allowing the
+     attacker to escalate privileges.
+
+     *Note Traversing symlinks::.
+
+‘-P’
+     Do not traverse any symbolic links.  This is the default if none of
+     ‘-H’, ‘-L’, or ‘-P’ is specified.  *Note Traversing symlinks::.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Examples:
+
+     # Change the group of /u to "staff".
+     chgrp staff /u
+
+     # Change the group of /u and subfiles to "staff".
+     chgrp -hR staff /u
+
+
+File: coreutils.info,  Node: chmod invocation,  Next: touch invocation,  Prev: chgrp invocation,  Up: Changing file attributes
+
+13.3 ‘chmod’: Change access permissions
+=======================================
+
+‘chmod’ changes the access permissions of the named files.  Synopsis:
+
+     chmod [OPTION]... {MODE | --reference=REF_FILE} FILE...
+
+   ‘chmod’ never changes the permissions of symbolic links, since the
+‘chmod’ system call cannot change their permissions.  This is not a
+problem since the permissions of symbolic links are never used.
+However, for each symbolic link listed on the command line, ‘chmod’
+changes the permissions of the pointed-to file.  In contrast, ‘chmod’
+ignores symbolic links encountered during recursive directory
+traversals.
+
+   Only a process whose effective user ID matches the user ID of the
+file, or a process with appropriate privileges, is permitted to change
+the file mode bits of a file.
+
+   A successful use of ‘chmod’ clears the set-group-ID bit of a regular
+file if the file’s group ID does not match the user’s effective group ID
+or one of the user’s supplementary group IDs, unless the user has
+appropriate privileges.  Additional restrictions may cause the
+set-user-ID and set-group-ID bits of MODE or REF_FILE to be ignored.
+This behavior depends on the policy and functionality of the underlying
+‘chmod’ system call.  When in doubt, check the underlying system
+behavior.
+
+   If used, MODE specifies the new file mode bits.  For details, see the
+section on *note File permissions::.  If you really want MODE to have a
+leading ‘-’, you should use ‘--’ first, e.g., ‘chmod -- -w file’.
+Typically, though, ‘chmod a-w file’ is preferable, and ‘chmod -w file’
+(without the ‘--’) complains if it behaves differently from what ‘chmod
+a-w file’ would do.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c’
+‘--changes’
+     Verbosely describe the action for each FILE whose permissions
+     actually change.
+
+‘-f’
+‘--silent’
+‘--quiet’
+     Do not print error messages about files whose permissions cannot be
+     changed.
+
+‘--preserve-root’
+     Fail upon any attempt to recursively change the root directory,
+     ‘/’.  Without ‘--recursive’, this option has no effect.  *Note
+     Treating / specially::.
+
+‘--no-preserve-root’
+     Cancel the effect of any preceding ‘--preserve-root’ option.  *Note
+     Treating / specially::.
+
+‘-v’
+‘--verbose’
+     Verbosely describe the action or non-action taken for every FILE.
+
+‘--reference=REF_FILE’
+     Change the mode of each FILE to be the same as that of REF_FILE.
+     *Note File permissions::.  If REF_FILE is a symbolic link, do not
+     use the mode of the symbolic link, but rather that of the file it
+     refers to.
+
+‘-R’
+‘--recursive’
+     Recursively change permissions of directories and their contents.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Examples:
+
+     # Change file permissions of FOO to be world readable
+     # and user writable, with no other permissions.
+     chmod 644 foo
+     chmod a=r,u+w foo
+
+     # Add user and group execute permissions to FOO.
+     chmod +110 file
+     chmod ug+x file
+
+     # Set file permissions of DIR and subsidiary files to
+     # be the umask default, assuming execute permissions for
+     # directories and for files already executable.
+     chmod -R a=,+rwX dir
+
+
+File: coreutils.info,  Node: touch invocation,  Prev: chmod invocation,  Up: Changing file attributes
+
+13.4 ‘touch’: Change file timestamps
+====================================
+
+‘touch’ changes the access and/or modification timestamps of the
+specified files.  Synopsis:
+
+     touch [OPTION]... FILE...
+
+   Any FILE argument that does not exist is created empty, unless option
+‘--no-create’ (‘-c’) or ‘--no-dereference’ (‘-h’) was in effect.
+
+   A FILE argument string of ‘-’ is handled specially and causes ‘touch’
+to change the times of the file associated with standard output.
+
+   By default, ‘touch’ sets file timestamps to the current time.
+Because ‘touch’ acts on its operands left to right, the resulting
+timestamps of earlier and later operands may disagree.
+
+   When setting file timestamps to the current time, ‘touch’ can change
+the timestamps for files that the user does not own but has write
+permission for.  Otherwise, the user must own the files.  Some older
+systems have a further restriction: the user must own the files unless
+both the access and modification timestamps are being set to the current
+time.
+
+   The ‘touch’ command cannot set a file’s status change timestamp to a
+user-specified value, and cannot change the file’s birth time (if
+supported) at all.  Also, ‘touch’ has issues similar to those affecting
+all programs that update file timestamps.  For example, ‘touch’ may set
+a file’s timestamp to a value that differs slightly from the requested
+time.  *Note File timestamps::.
+
+   Timestamps assume the time zone rules specified by the ‘TZ’
+environment variable, or by the system default rules if ‘TZ’ is not set.
+*Note Specifying the Time Zone with ‘TZ’: (libc)TZ Variable.  You can
+avoid ambiguities during daylight saving transitions by using UTC
+timestamps.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a’
+‘--time=atime’
+‘--time=access’
+‘--time=use’
+     Change the access timestamp only.  *Note File timestamps::.
+
+‘-c’
+‘--no-create’
+     Do not warn about or create files that do not exist.
+
+‘-d TIME’
+‘--date=TIME’
+     Use TIME instead of the current time.  It can contain month names,
+     time zones, ‘am’ and ‘pm’, ‘yesterday’, etc.  For example,
+     ‘--date="2020-07-21 14:19:13.489392193 +0530"’ specifies the
+     instant of time that is 489,392,193 nanoseconds after July 21, 2020
+     at 2:19:13 PM in a time zone that is 5 hours and 30 minutes east of
+     UTC.  *Note Date input formats::.  File systems that do not support
+     high-resolution timestamps silently ignore any excess precision
+     here.
+
+‘-f’
+     Ignored; for compatibility with BSD versions of ‘touch’.
+
+‘-h’
+‘--no-dereference’
+     Attempt to change the timestamps of a symbolic link, rather than
+     what the link refers to.  When using this option, empty files are
+     not created, but option ‘-c’ must also be used to avoid warning
+     about files that do not exist.  Not all systems support changing
+     the timestamps of symlinks, since underlying system support for
+     this action was not required until POSIX 2008.  Also, on some
+     systems, the mere act of examining a symbolic link changes the
+     access timestamp, such that only changes to the modification
+     timestamp will persist long enough to be observable.  When coupled
+     with option ‘-r’, a reference timestamp is taken from a symbolic
+     link rather than the file it refers to.
+
+‘-m’
+‘--time=mtime’
+‘--time=modify’
+     Change the modification timestamp only.
+
+‘-r FILE’
+‘--reference=FILE’
+     Use the times of the reference FILE instead of the current time.
+     If this option is combined with the ‘--date=TIME’ (‘-d TIME’)
+     option, the reference FILE’s time is the origin for any relative
+     TIMEs given, but is otherwise ignored.  For example, ‘-r foo -d '-5
+     seconds'’ specifies a timestamp equal to five seconds before the
+     corresponding timestamp for ‘foo’.  If FILE is a symbolic link, the
+     reference timestamp is taken from the target of the symlink, unless
+     ‘-h’ was also in effect.
+
+‘-t [[CC]YY]MMDDHHMM[.SS]’
+     Use the argument (optional four-digit or two-digit years, months,
+     days, hours, minutes, optional seconds) instead of the current
+     time.  If the year is specified with only two digits, then CC is 20
+     for years in the range 0 ... 68, and 19 for years in 69 ... 99.  If
+     no digits of the year are specified, the argument is interpreted as
+     a date in the current year.  On the atypical systems that support
+     leap seconds, SS may be ‘60’.
+
+   On systems predating POSIX 1003.1-2001, ‘touch’ supports an obsolete
+syntax, as follows.  If no timestamp is given with any of the ‘-d’,
+‘-r’, or ‘-t’ options, and if there are two or more FILEs and the first
+FILE is of the form ‘MMDDHHMM[YY]’ and this would be a valid argument to
+the ‘-t’ option (if the YY, if any, were moved to the front), and if the
+represented year is in the range 1969–1999, that argument is interpreted
+as the time for the other files instead of as a file name.  Although
+this obsolete behavior can be controlled with the ‘_POSIX2_VERSION’
+environment variable (*note Standards conformance::), portable scripts
+should avoid commands whose behavior depends on this variable.  For
+example, use ‘touch ./12312359 main.c’ or ‘touch -t 12312359 main.c’
+rather than the ambiguous ‘touch 12312359 main.c’.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: File space usage,  Next: Printing text,  Prev: Changing file attributes,  Up: Top
+
+14 File space usage
+*******************
+
+No file system can hold an infinite amount of data.  These commands
+report how much storage is in use or available, report other file and
+file status information, and write buffers to file systems.
+
+* Menu:
+
+* df invocation::               Report file system space usage.
+* du invocation::               Estimate file space usage.
+* stat invocation::             Report file or file system status.
+* sync invocation::             Synchronize cached writes to persistent storage.
+* truncate invocation::         Shrink or extend the size of a file.
+
+
+File: coreutils.info,  Node: df invocation,  Next: du invocation,  Up: File space usage
+
+14.1 ‘df’: Report file system space usage
+=========================================
+
+‘df’ reports the amount of space used and available on file systems.
+Synopsis:
+
+     df [OPTION]... [FILE]...
+
+   With no arguments, ‘df’ reports the space used and available on all
+currently mounted file systems (of all types).  Otherwise, ‘df’ reports
+on the file system containing each argument FILE.
+
+   Normally the space is printed in units of 1024 bytes, but this can be
+overridden (*note Block size::).  Non-integer quantities are rounded up
+to the next higher unit.
+
+   For bind mounts and without arguments, ‘df’ only outputs the
+statistics for that device with the shortest mount point name in the
+list of file systems (MTAB), i.e., it hides duplicate entries, unless
+the ‘-a’ option is specified.
+
+   With the same logic, ‘df’ elides a mount entry of a dummy pseudo
+device if there is another mount entry of a real block device for that
+mount point with the same device number, e.g.  the early-boot pseudo
+file system ‘rootfs’ is not shown per default when already the real root
+device has been mounted.
+
+   If an argument FILE resolves to a special file containing a mounted
+file system, ‘df’ shows the space available on that file system rather
+than on the file system containing the device node.  GNU ‘df’ does not
+attempt to determine the usage on unmounted file systems, because on
+most kinds of systems doing so requires extremely non-portable intimate
+knowledge of file system structures.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a’
+‘--all’
+     Include in the listing dummy, duplicate, or inaccessible file
+     systems, which are omitted by default.  Dummy file systems are
+     typically special purpose pseudo file systems such as ‘/proc’, with
+     no associated storage.  Duplicate file systems are local or remote
+     file systems that are mounted at separate locations in the local
+     file hierarchy, or bind mounted locations.  Inaccessible file
+     systems are those which are mounted but subsequently over-mounted
+     by another file system at that point, or otherwise inaccessible due
+     to permissions of the mount point etc.
+
+‘-B SIZE’
+‘--block-size=SIZE’
+     Scale sizes by SIZE before printing them (*note Block size::).  For
+     example, ‘-BG’ prints sizes in units of 1,073,741,824 bytes.
+
+‘-h’
+‘--human-readable’
+     Append a size letter to each size, such as ‘M’ for mebibytes.
+     Powers of 1024 are used, not 1000; ‘M’ stands for 1,048,576 bytes.
+     This option is equivalent to ‘--block-size=human-readable’.  Use
+     the ‘--si’ option if you prefer powers of 1000.
+
+‘-H’
+     Equivalent to ‘--si’.
+
+‘-i’
+‘--inodes’
+     List inode usage information instead of block usage.  An inode
+     (short for index node) contains information about a file such as
+     its owner, permissions, timestamps, and location on the file
+     system.
+
+‘-k’
+     Print sizes in 1024-byte blocks, overriding the default block size
+     (*note Block size::).  This option is equivalent to
+     ‘--block-size=1K’.
+
+‘-l’
+‘--local’
+     Limit the listing to local file systems.  By default, remote file
+     systems are also listed.
+
+‘--no-sync’
+     Do not invoke the ‘sync’ system call before getting any usage data.
+     This may make ‘df’ run significantly faster on systems with many
+     file systems, but on some systems (notably Solaris) the results may
+     be slightly out of date.  This is the default.
+
+‘--output’
+‘--output[=FIELD_LIST]’
+     Use the output format defined by FIELD_LIST, or print all fields if
+     FIELD_LIST is omitted.  In the latter case, the order of the
+     columns conforms to the order of the field descriptions below.
+
+     The use of the ‘--output’ together with each of the options ‘-i’,
+     ‘-P’, and ‘-T’ is mutually exclusive.
+
+     FIELD_LIST is a comma-separated list of columns to be included in
+     ‘df’’s output and therefore effectively controls the order of
+     output columns.  Each field can thus be used at the place of
+     choice, but yet must only be used once.
+
+     Valid field names in the FIELD_LIST are:
+     ‘source’
+          The source of the mount point, usually a device.
+     ‘fstype’
+          File system type.
+
+     ‘itotal’
+          Total number of inodes.
+     ‘iused’
+          Number of used inodes.
+     ‘iavail’
+          Number of available inodes.
+     ‘ipcent’
+          Percentage of IUSED divided by ITOTAL.
+
+     ‘size’
+          Total number of blocks.
+     ‘used’
+          Number of used blocks.
+     ‘avail’
+          Number of available blocks.
+     ‘pcent’
+          Percentage of USED divided by SIZE.
+
+     ‘file’
+          The file name if specified on the command line.
+     ‘target’
+          The mount point.
+
+     The fields for block and inodes statistics are affected by the
+     scaling options like ‘-h’ as usual.
+
+     The definition of the FIELD_LIST can even be split among several
+     ‘--output’ uses.
+
+          #!/bin/sh
+          # Print the TARGET (i.e., the mount point) along with their percentage
+          # statistic regarding the blocks and the inodes.
+          df --out=target --output=pcent,ipcent
+
+          # Print all available fields.
+          df --o
+
+‘-P’
+‘--portability’
+     Use the POSIX output format.  This is like the default format
+     except for the following:
+
+       1. The information about each file system is always printed on
+          exactly one line; a mount device is never put on a line by
+          itself.  This means that if the mount device name is more than
+          20 characters long (e.g., for some network mounts), the
+          columns are misaligned.
+
+       2. The labels in the header output line are changed to conform to
+          POSIX.
+
+       3. The default block size and output format are unaffected by the
+          ‘DF_BLOCK_SIZE’, ‘BLOCK_SIZE’ and ‘BLOCKSIZE’ environment
+          variables.  However, the default block size is still affected
+          by ‘POSIXLY_CORRECT’: it is 512 if ‘POSIXLY_CORRECT’ is set,
+          1024 otherwise.  *Note Block size::.
+
+‘--si’
+     Append an SI-style abbreviation to each size, such as ‘M’ for
+     megabytes.  Powers of 1000 are used, not 1024; ‘M’ stands for
+     1,000,000 bytes.  This option is equivalent to ‘--block-size=si’.
+     Use the ‘-h’ or ‘--human-readable’ option if you prefer powers of
+     1024.
+
+‘--sync’
+     Invoke the ‘sync’ system call before getting any usage data.  On
+     some systems (notably Solaris), doing this yields more up to date
+     results, but in general this option makes ‘df’ much slower,
+     especially when there are many or very busy file systems.
+
+‘--total’
+     Print a grand total of all arguments after all arguments have been
+     processed.  This can be used to find out the total size, usage and
+     available space of all listed devices.  If no arguments are
+     specified df will try harder to elide file systems insignificant to
+     the total available space, by suppressing duplicate remote file
+     systems.
+
+     For the grand total line, ‘df’ prints ‘"total"’ into the SOURCE
+     column, and ‘"-"’ into the TARGET column.  If there is no SOURCE
+     column (see ‘--output’), then ‘df’ prints ‘"total"’ into the TARGET
+     column, if present.
+
+‘-t FSTYPE’
+‘--type=FSTYPE’
+     Limit the listing to file systems of type FSTYPE.  Multiple file
+     system types can be specified by giving multiple ‘-t’ options.  By
+     default, nothing is omitted.
+
+‘-T’
+‘--print-type’
+     Print each file system’s type.  The types printed here are the same
+     ones you can include or exclude with ‘-t’ and ‘-x’.  The particular
+     types printed are whatever is supported by the system.  Here are
+     some of the common names (this list is certainly not exhaustive):
+
+     ‘nfs’
+          An NFS file system, i.e., one mounted over a network from
+          another machine.  This is the one type name which seems to be
+          used uniformly by all systems.
+
+     ‘ext2, ext3, ext4, xfs, btrfs...’
+          A file system on a locally-mounted device.  (The system might
+          even support more than one type here; GNU/Linux does.)
+
+     ‘iso9660, cdfs’
+          A file system on a CD or DVD drive.  HP-UX uses ‘cdfs’, most
+          other systems use ‘iso9660’.
+
+     ‘ntfs,fat’
+          File systems used by MS-Windows / MS-DOS.
+
+‘-x FSTYPE’
+‘--exclude-type=FSTYPE’
+     Limit the listing to file systems not of type FSTYPE.  Multiple
+     file system types can be eliminated by giving multiple ‘-x’
+     options.  By default, no file system types are omitted.
+
+‘-v’
+     Ignored; for compatibility with System V versions of ‘df’.
+
+   ‘df’ is installed only on systems that have usable mount tables, so
+portable scripts should not rely on its existence.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.  Failure includes the case where no output is
+generated, so you can inspect the exit status of a command like ‘df -t
+ext3 -t reiserfs DIR’ to test whether DIR is on a file system of type
+‘ext3’ or ‘reiserfs’.
+
+   Since the list of file systems (MTAB) is needed to determine the file
+system type, failure includes the cases when that list cannot be read
+and one or more of the options ‘-a’, ‘-l’, ‘-t’ or ‘-x’ is used together
+with a file name argument.
+
+
+File: coreutils.info,  Node: du invocation,  Next: stat invocation,  Prev: df invocation,  Up: File space usage
+
+14.2 ‘du’: Estimate file space usage
+====================================
+
+‘du’ reports the space needed to represent a set of files.  Synopsis:
+
+     du [OPTION]... [FILE]...
+
+   With no arguments, ‘du’ reports the space needed to represent the
+files at or under the current directory.  Normally the space is printed
+in units of 1024 bytes, but this can be overridden (*note Block size::).
+Non-integer quantities are rounded up to the next higher unit.
+
+   If two or more hard links point to the same file, only one of the
+hard links is counted.  The FILE argument order affects which links are
+counted, and changing the argument order may change the numbers and
+entries that ‘du’ outputs.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-0’
+‘--null’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+
+‘-a’
+‘--all’
+     Show counts for all files, not just directories.
+
+‘--apparent-size’
+     Print apparent sizes, rather than file system usage.  The apparent
+     size of a file is the number of bytes reported by ‘wc -c’ on
+     regular files, or more generally, ‘ls -l --block-size=1’ or ‘stat
+     --format=%s’.  For example, a file containing the word ‘zoo’ with
+     no newline would, of course, have an apparent size of 3.  Such a
+     small file may require anywhere from 0 to 16 KiB or more of file
+     system space, depending on the type and configuration of the file
+     system on which the file resides.  However, a sparse file created
+     with this command:
+
+          dd bs=1 seek=2GiB if=/dev/null of=big
+
+     has an apparent size of 2 GiB, yet on most modern file systems, it
+     actually uses almost no space.
+
+     Apparent sizes are meaningful only for regular files and symbolic
+     links.  Other file types do not contribute to apparent size.
+
+‘-B SIZE’
+‘--block-size=SIZE’
+     Scale sizes by SIZE before printing them (*note Block size::).  For
+     example, ‘-BG’ prints sizes in units of 1,073,741,824 bytes.
+
+‘-b’
+‘--bytes’
+     Equivalent to ‘--apparent-size --block-size=1’.
+
+‘-c’
+‘--total’
+     Print a grand total of all arguments after all arguments have been
+     processed.  This can be used to find out the total file system
+     usage of a given set of files or directories.
+
+‘-D’
+‘--dereference-args’
+     Dereference symbolic links that are command line arguments.  Does
+     not affect other symbolic links.  This is helpful for finding out
+     the file system usage of directories, such as ‘/usr/tmp’, which are
+     often symbolic links.
+
+‘-d DEPTH’
+‘--max-depth=DEPTH’
+     Show the total for each directory (and file if ‘--all’) that is at
+     most MAX_DEPTH levels down from the root of the hierarchy.  The
+     root is at level 0, so ‘du --max-depth=0’ is equivalent to ‘du -s’.
+
+‘--files0-from=FILE’
+     Disallow processing files named on the command line, and instead
+     process those named in file FILE; each name being terminated by a
+     zero byte (ASCII NUL). This is useful when the list of file names
+     is so long that it may exceed a command line length limitation.  In
+     such cases, running ‘du’ via ‘xargs’ is undesirable because it
+     splits the list into pieces and makes ‘du’ print with the ‘--total’
+     (‘-c’) option for each sublist rather than for the entire list.
+     One way to produce a list of ASCII NUL terminated file names is
+     with GNU ‘find’, using its ‘-print0’ predicate.  If FILE is ‘-’
+     then the ASCII NUL terminated file names are read from standard
+     input.
+
+‘-H’
+     Equivalent to ‘--dereference-args’ (‘-D’).
+
+‘-h’
+‘--human-readable’
+     Append a size letter to each size, such as ‘M’ for mebibytes.
+     Powers of 1024 are used, not 1000; ‘M’ stands for 1,048,576 bytes.
+     This option is equivalent to ‘--block-size=human-readable’.  Use
+     the ‘--si’ option if you prefer powers of 1000.
+
+‘--inodes’
+     List inode usage information instead of block usage.  This option
+     is useful for finding directories which contain many files, and
+     therefore eat up most of the inodes space of a file system (see
+     ‘df’, option ‘--inodes’).  It can well be combined with the options
+     ‘-a’, ‘-c’, ‘-h’, ‘-l’, ‘-s’, ‘-S’, ‘-t’ and ‘-x’; however, passing
+     other options regarding the block size, for example ‘-b’, ‘-m’ and
+     ‘--apparent-size’, is ignored.
+
+‘-k’
+     Print sizes in 1024-byte blocks, overriding the default block size
+     (*note Block size::).  This option is equivalent to
+     ‘--block-size=1K’.
+
+‘-L’
+‘--dereference’
+     Dereference symbolic links (show the file system space used by the
+     file or directory that the link points to instead of the space used
+     by the link).
+
+‘-l’
+‘--count-links’
+     Count the size of all files, even if they have appeared already (as
+     a hard link).
+
+‘-m’
+     Print sizes in 1,048,576-byte blocks, overriding the default block
+     size (*note Block size::).  This option is equivalent to
+     ‘--block-size=1M’.
+
+‘-P’
+‘--no-dereference’
+     For each symbolic link encountered by ‘du’, consider the file
+     system space used by the symbolic link itself.
+
+‘-S’
+‘--separate-dirs’
+     Normally, in the output of ‘du’ (when not using ‘--summarize’), the
+     size listed next to a directory name, D, represents the sum of
+     sizes of all entries beneath D as well as the size of D itself.
+     With ‘--separate-dirs’, the size reported for a directory name, D,
+     will exclude the size of any subdirectories.
+
+‘--si’
+     Append an SI-style abbreviation to each size, such as ‘M’ for
+     megabytes.  Powers of 1000 are used, not 1024; ‘M’ stands for
+     1,000,000 bytes.  This option is equivalent to ‘--block-size=si’.
+     Use the ‘-h’ or ‘--human-readable’ option if you prefer powers of
+     1024.
+
+‘-s’
+‘--summarize’
+     Display only a total for each argument.
+
+‘-t SIZE’
+‘--threshold=SIZE’
+     Exclude entries based on a given SIZE.  The SIZE refers to used
+     blocks in normal mode (*note Block size::), or inodes count in
+     conjunction with the ‘--inodes’ option.
+
+     If SIZE is positive, then ‘du’ will only print entries with a size
+     greater than or equal to that.
+
+     If SIZE is negative, then ‘du’ will only print entries with a size
+     smaller than or equal to that.
+
+     Although GNU ‘find’ can be used to find files of a certain size,
+     ‘du’’s ‘--threshold’ option can be used to also filter directories
+     based on a given size.
+
+     When combined with the ‘--apparent-size’ option, the ‘--threshold’
+     option elides entries based on apparent size.  When combined with
+     the ‘--inodes’ option, it elides entries based on inode counts.
+
+     Here’s how you would use ‘--threshold’ to find directories with a
+     size greater than or equal to 200 megabytes:
+
+          du --threshold=200MB
+
+     Here’s how you would use ‘--threshold’ to find directories and
+     files – note the ‘-a’ – with an apparent size smaller than or equal
+     to 500 bytes:
+
+          du -a -t -500 --apparent-size
+
+     Here’s how you would use ‘--threshold’ to find directories on the
+     root file system with more than 20000 inodes used in the directory
+     tree below:
+
+          du --inodes -x --threshold=20000 /
+
+‘--time’
+     Show the most recent modification timestamp (mtime) of any file in
+     the directory, or any of its subdirectories.  *Note File
+     timestamps::.
+
+‘--time=ctime’
+‘--time=status’
+‘--time=use’
+     Show the most recent status change timestamp (ctime) of any file in
+     the directory, or any of its subdirectories.  *Note File
+     timestamps::.
+
+‘--time=atime’
+‘--time=access’
+     Show the most recent access timestamp (atime) of any file in the
+     directory, or any of its subdirectories.  *Note File timestamps::.
+
+‘--time-style=STYLE’
+     List timestamps in style STYLE.  This option has an effect only if
+     the ‘--time’ option is also specified.  The STYLE should be one of
+     the following:
+
+     ‘+FORMAT’
+          List timestamps using FORMAT, where FORMAT is interpreted like
+          the format argument of ‘date’ (*note date invocation::).  For
+          example, ‘--time-style="+%Y-%m-%d %H:%M:%S"’ causes ‘du’ to
+          list timestamps like ‘2020-07-21 23:45:56’.  As with ‘date’,
+          FORMAT’s interpretation is affected by the ‘LC_TIME’ locale
+          category.
+
+     ‘full-iso’
+          List timestamps in full using ISO 8601-like date, time, and
+          time zone components with nanosecond precision, e.g.,
+          ‘2020-07-21 23:45:56.477817180 -0400’.  This style is
+          equivalent to ‘+%Y-%m-%d %H:%M:%S.%N %z’.
+
+     ‘long-iso’
+          List ISO 8601 date and time components with minute precision,
+          e.g., ‘2020-07-21 23:45’.  These timestamps are shorter than
+          ‘full-iso’ timestamps, and are usually good enough for
+          everyday work.  This style is equivalent to ‘+%Y-%m-%d %H:%M’.
+
+     ‘iso’
+          List ISO 8601 dates for timestamps, e.g., ‘2020-07-21’.  This
+          style is equivalent to ‘+%Y-%m-%d’.
+
+     You can specify the default value of the ‘--time-style’ option with
+     the environment variable ‘TIME_STYLE’; if ‘TIME_STYLE’ is not set
+     the default style is ‘long-iso’.  For compatibility with ‘ls’, if
+     ‘TIME_STYLE’ begins with ‘+’ and contains a newline, the newline
+     and any later characters are ignored; if ‘TIME_STYLE’ begins with
+     ‘posix-’ the ‘posix-’ is ignored; and if ‘TIME_STYLE’ is ‘locale’
+     it is ignored.
+
+‘-X FILE’
+‘--exclude-from=FILE’
+     Like ‘--exclude’, except take the patterns to exclude from FILE,
+     one per line.  If FILE is ‘-’, take the patterns from standard
+     input.
+
+‘--exclude=PATTERN’
+     When recursing, skip subdirectories or files matching PATTERN.  For
+     example, ‘du --exclude='*.o'’ excludes files whose names end in
+     ‘.o’.
+
+‘-x’
+‘--one-file-system’
+     Skip directories that are on different file systems from the one
+     that the argument being processed is on.
+
+   Since ‘du’ relies on information reported by the operating system,
+its output might not reflect the space consumed in the underlying
+devices.  For example;
+
+   • Operating systems normally do not report device space consumed by
+     duplicate or backup blocks, error correction bits, and so forth.
+     This causes ‘du’ to underestimate the device space actually used.
+
+   • In file systems that use copy-on-write, if two distinct files share
+     space the output of ‘du’ typically counts the space that would be
+     consumed if all files’ non-holes were rewritten, not the space
+     currently consumed.
+
+   • In file systems that use compression, the operating system might
+     report the uncompressed space.  (If it does report the compressed
+     space, that report might change after one merely overwrites
+     existing file data.)
+
+   • Networked file systems historically have had difficulty
+     communicating accurate file system information from server to
+     client.
+
+For these reasons ‘du’ might better be thought of as an estimate of the
+size of a ‘tar’ or other conventional backup for a set of files, rather
+than as a measure of space consumed in the underlying devices.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: stat invocation,  Next: sync invocation,  Prev: du invocation,  Up: File space usage
+
+14.3 ‘stat’: Report file or file system status
+==============================================
+
+‘stat’ displays information about the specified file(s).  Synopsis:
+
+     stat [OPTION]... [FILE]...
+
+   With no option, ‘stat’ reports all information about the given files.
+But it also can be used to report the information of the file systems
+the given files are located on.  If the files are links, ‘stat’ can also
+give information about the files the links point to.
+
+   Due to shell aliases and built-in ‘stat’ functions, using an
+unadorned ‘stat’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+stat ...’) to avoid interference from the shell.
+
+‘-L’
+‘--dereference’
+     Change how ‘stat’ treats symbolic links.  With this option, ‘stat’
+     acts on the file referenced by each symbolic link argument.
+     Without it, ‘stat’ acts on any symbolic link argument directly.
+
+‘-f’
+‘--file-system’
+     Report information about the file systems where the given files are
+     located instead of information about the files themselves.  This
+     option implies the ‘-L’ option.
+
+‘--cached=MODE’
+     Control how attributes are read from the file system; if supported
+     by the system.  This allows one to control the trade-off between
+     freshness and efficiency of attribute access, especially useful
+     with remote file systems.  MODE can be:
+
+     ‘always’
+          Always read the already cached attributes if available.
+
+     ‘never’
+          Always synchronize with the latest file system attributes.
+          This also mounts automounted files.
+
+     ‘default’
+          Leave the caching behavior to the underlying file system.
+
+‘-c’
+‘--format=FORMAT’
+     Use FORMAT rather than the default format.  FORMAT is automatically
+     newline-terminated, so running a command like the following with
+     two or more FILE operands produces a line of output for each
+     operand:
+          $ stat --format=%d:%i / /usr
+          2050:2
+          2057:2
+
+‘--printf=FORMAT’
+     Use FORMAT rather than the default format.  Like ‘--format’, but
+     interpret backslash escapes, and do not output a mandatory trailing
+     newline.  If you want a newline, include ‘\n’ in the FORMAT.
+     Here’s how you would use ‘--printf’ to print the device and inode
+     numbers of ‘/’ and ‘/usr’:
+          $ stat --printf='%d:%i\n' / /usr
+          2050:2
+          2057:2
+
+‘-t’
+‘--terse’
+     Print the information in terse form, suitable for parsing by other
+     programs.
+
+     The output of the following commands are identical and the
+     ‘--format’ also identifies the items printed (in fuller form) in
+     the default format.  Note the format string would include another
+     ‘%C’ at the end with an active SELinux security context.
+          $ stat --format="%n %s %b %f %u %g %D %i %h %t %T %X %Y %Z %W %o" ...
+          $ stat --terse ...
+
+     The same illustrating terse output in ‘--file-system’ mode:
+          $ stat -f --format="%n %i %l %t %s %S %b %f %a %c %d" ...
+          $ stat -f --terse ...
+
+   The valid FORMAT directives for files with ‘--format’ and ‘--printf’
+are:
+
+   • %a – Permission bits in octal (note ‘#’ and ‘0’ printf flags)
+   • %A – Permission bits in symbolic form (similar to ‘ls -ld’)
+   • %b – Number of blocks allocated (see ‘%B’)
+   • %B – The size in bytes of each block reported by ‘%b’
+   • %C – The SELinux security context of a file, if available
+   • %d – Device number in decimal (st_dev)
+   • %D – Device number in hex (st_dev)
+   • %Hd – Major device number in decimal
+   • %Ld – Minor device number in decimal
+   • %f – Raw mode in hex
+   • %F – File type
+   • %g – Group ID of owner
+   • %G – Group name of owner
+   • %h – Number of hard links
+   • %i – Inode number
+   • %m – Mount point (See note below)
+   • %n – File name
+   • %N – Quoted file name with dereference if symbolic link (see below)
+   • %o – Optimal I/O transfer size hint
+   • %s – Total size, in bytes
+   • %r – Device type in decimal (st_rdev)
+   • %R – Device type in hex (st_rdev)
+   • %Hr – Major device type in decimal (see below)
+   • %Lr – Minor device type in decimal (see below)
+   • %t – Major device type in hex (see below)
+   • %T – Minor device type in hex (see below)
+   • %u – User ID of owner
+   • %U – User name of owner
+   • %w – Time of file birth, or ‘-’ if unknown
+   • %W – Time of file birth as seconds since Epoch, or ‘0’
+   • %x – Time of last access
+   • %X – Time of last access as seconds since Epoch
+   • %y – Time of last data modification
+   • %Y – Time of last data modification as seconds since Epoch
+   • %z – Time of last status change
+   • %Z – Time of last status change as seconds since Epoch
+
+   The ‘%a’ format prints the octal mode, and so it is useful to control
+the zero padding of the output with the ‘#’ and ‘0’ printf flags.  For
+example to pad to at least 3 wide while making larger numbers
+unambiguously octal, you can use ‘%#03a’.
+
+   The ‘%N’ format can be set with the environment variable
+‘QUOTING_STYLE’.  If that environment variable is not set, the default
+value is ‘shell-escape-always’.  Valid quoting styles are:
+‘literal’
+     Output strings as-is; this is the same as the ‘--literal’ (‘-N’)
+     option.
+‘shell’
+     Quote strings for the shell if they contain shell metacharacters or
+     would cause ambiguous output.  The quoting is suitable for
+     POSIX-compatible shells like ‘bash’, but it does not always work
+     for incompatible shells like ‘csh’.
+‘shell-always’
+     Quote strings for the shell, even if they would normally not
+     require quoting.
+‘shell-escape’
+     Like ‘shell’, but also quoting non-printable characters using the
+     POSIX proposed ‘$''’ syntax suitable for most shells.
+‘shell-escape-always’
+     Like ‘shell-escape’, but quote strings even if they would normally
+     not require quoting.
+‘c’
+     Quote strings as for C character string literals, including the
+     surrounding double-quote characters; this is the same as the
+     ‘--quote-name’ (‘-Q’) option.
+‘escape’
+     Quote strings as for C character string literals, except omit the
+     surrounding double-quote characters; this is the same as the
+     ‘--escape’ (‘-b’) option.
+‘clocale’
+     Quote strings as for C character string literals, except use
+     surrounding quotation marks appropriate for the locale.
+‘locale’
+     Quote strings as for C character string literals, except use
+     surrounding quotation marks appropriate for the locale, and quote
+     'like this' instead of "like this" in the default C locale.  This
+     looks nicer on many displays.
+
+   The ‘r’, ‘R’, ‘%t’, and ‘%T’ formats operate on the st_rdev member of
+the stat(2) structure, i.e., the represented device rather than the
+containing device, and so are only defined for character and block
+special files.  On some systems or file types, st_rdev may be used to
+represent other quantities.
+
+   The ‘%W’, ‘%X’, ‘%Y’, and ‘%Z’ formats accept a precision preceded by
+a period to specify the number of digits to print after the decimal
+point.  For example, ‘%.3X’ outputs the access timestamp to millisecond
+precision.  If a period is given but no precision, ‘stat’ uses 9 digits,
+so ‘%.X’ is equivalent to ‘%.9X’.  When discarding excess precision,
+timestamps are truncated toward minus infinity.
+
+     zero pad:
+       $ stat -c '[%015Y]' /usr
+       [000001288929712]
+     space align:
+       $ stat -c '[%15Y]' /usr
+       [     1288929712]
+       $ stat -c '[%-15Y]' /usr
+       [1288929712     ]
+     precision:
+       $ stat -c '[%.3Y]' /usr
+       [1288929712.114]
+       $ stat -c '[%.Y]' /usr
+       [1288929712.114951834]
+
+   The mount point printed by ‘%m’ is similar to that output by ‘df’,
+except that:
+   • stat does not dereference symlinks by default (unless ‘-L’ is
+     specified)
+   • stat does not search for specified device nodes in the file system
+     list, instead operating on them directly
+   • stat outputs the alias for a bind mounted file, rather than the
+     initial mount point of its backing device.  One can recursively
+     call stat until there is no change in output, to get the current
+     base mount point
+
+   When listing file system information (‘--file-system’ (‘-f’)), you
+must use a different set of FORMAT directives:
+
+   • %a – Free blocks available to non-super-user
+   • %b – Total data blocks in file system
+   • %c – Total file nodes in file system
+   • %d – Free file nodes in file system
+   • %f – Free blocks in file system
+   • %i – File System ID in hex
+   • %l – Maximum length of file names
+   • %n – File name
+   • %s – Block size (for faster transfers)
+   • %S – Fundamental block size (for block counts)
+   • %t – Type in hex
+   • %T – Type in human readable form
+
+   Timestamps are listed according to the time zone rules specified by
+the ‘TZ’ environment variable, or by the system default rules if ‘TZ’ is
+not set.  *Note Specifying the Time Zone with ‘TZ’: (libc)TZ Variable.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: sync invocation,  Next: truncate invocation,  Prev: stat invocation,  Up: File space usage
+
+14.4 ‘sync’: Synchronize cached writes to persistent storage
+============================================================
+
+‘sync’ synchronizes in memory files or file systems to persistent
+storage.  Synopsis:
+
+     sync [OPTION] [FILE]...
+
+   ‘sync’ writes any data buffered in memory out to the storage device.
+This can include (but is not limited to) modified superblocks, modified
+inodes, and delayed reads and writes.  This must be implemented by the
+kernel; The ‘sync’ program does nothing but exercise the ‘sync’,
+‘syncfs’, ‘fsync’, and ‘fdatasync’ system calls.
+
+   The kernel keeps data in memory to avoid doing (relatively slow)
+device reads and writes.  This improves performance, but if the computer
+crashes, data may be lost or the file system corrupted as a result.  The
+‘sync’ command instructs the kernel to write data in memory to
+persistent storage.
+
+   If any argument is specified then only those files will be
+synchronized using the fsync(2) syscall by default.
+
+   If at least one file is specified, it is possible to change the
+synchronization method with the following options.  Also see *note
+Common options::.
+
+‘-d’
+‘--data’
+     Use fdatasync(2) to sync only the data for the file, and any
+     metadata required to maintain file system consistency.
+
+‘-f’
+‘--file-system’
+     Synchronize all the I/O waiting for the file systems that contain
+     the file, using the syscall syncfs(2).  Note you would usually
+     _not_ specify this option if passing a device node like ‘/dev/sda’
+     for example, as that would sync the containing file system rather
+     than the referenced one.  Note also that depending on the system,
+     passing individual device nodes or files may have different sync
+     characteristics than using no arguments.  I.e., arguments passed to
+     fsync(2) may provide greater guarantees through write barriers,
+     than a global sync(2) used when no arguments are provided.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: truncate invocation,  Prev: sync invocation,  Up: File space usage
+
+14.5 ‘truncate’: Shrink or extend the size of a file
+====================================================
+
+‘truncate’ shrinks or extends the size of each FILE to the specified
+size.  Synopsis:
+
+     truncate OPTION... FILE...
+
+   Any FILE that does not exist is created.
+
+   If a FILE is larger than the specified size, the extra data is lost.
+If a FILE is shorter, it is extended and the sparse extended part (or
+hole) reads as zero bytes.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-c’
+‘--no-create’
+     Do not create files that do not exist.
+
+‘-o’
+‘--io-blocks’
+     Treat SIZE as number of I/O blocks of the FILE rather than bytes.
+
+‘-r RFILE’
+‘--reference=RFILE’
+     Base the size of each FILE on the size of RFILE.
+
+‘-s SIZE’
+‘--size=SIZE’
+     Set or adjust the size of each FILE according to SIZE.  SIZE is in
+     bytes unless ‘--io-blocks’ is specified.  SIZE may be, or may be an
+     integer optionally followed by, one of the following multiplicative
+     suffixes:
+          ‘KB’ =>           1000 (KiloBytes)
+          ‘K’  =>           1024 (KibiBytes)
+          ‘MB’ =>      1000*1000 (MegaBytes)
+          ‘M’  =>      1024*1024 (MebiBytes)
+          ‘GB’ => 1000*1000*1000 (GigaBytes)
+          ‘G’  => 1024*1024*1024 (GibiBytes)
+     and so on for ‘T’, ‘P’, ‘E’, ‘Z’, ‘Y’, ‘R’, and ‘Q’.  Binary
+     prefixes can be used, too: ‘KiB’=‘K’, ‘MiB’=‘M’, and so on.
+
+     SIZE may also be prefixed by one of the following to adjust the
+     size of each FILE based on its current size:
+          ‘+’  => extend by
+          ‘-’  => reduce by
+          ‘<’  => at most
+          ‘>’  => at least
+          ‘/’  => round down to multiple of
+          ‘%’  => round up to multiple of
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Printing text,  Next: Conditions,  Prev: File space usage,  Up: Top
+
+15 Printing text
+****************
+
+This section describes commands that display text strings.
+
+* Menu:
+
+* echo invocation::             Print a line of text.
+* printf invocation::           Format and print data.
+* yes invocation::              Print a string until interrupted.
+
+
+File: coreutils.info,  Node: echo invocation,  Next: printf invocation,  Up: Printing text
+
+15.1 ‘echo’: Print a line of text
+=================================
+
+‘echo’ writes each given STRING to standard output, with a space between
+each and a newline after the last one.  Synopsis:
+
+     echo [OPTION]... [STRING]...
+
+   Due to shell aliases and built-in ‘echo’ functions, using an
+unadorned ‘echo’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+echo ...’) to avoid interference from the shell.
+
+   Due to historical and backwards compatibility reasons, certain bare
+option-like strings cannot be passed to ‘echo’ as non-option arguments.
+It is therefore not advisable to use ‘echo’ for printing unknown or
+variable arguments.  The ‘printf’ command is recommended as a more
+portable and flexible replacement for tasks historically performed by
+‘echo’.  *Note printf invocation::.
+
+   The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands, and the normally-special
+argument ‘--’ has no special meaning and is treated like any other
+STRING.
+
+‘-n’
+     Do not output the trailing newline.
+
+‘-e’
+     Enable interpretation of the following backslash-escaped characters
+     in each STRING:
+
+     ‘\a’
+          alert (bell)
+     ‘\b’
+          backspace
+     ‘\c’
+          produce no further output
+     ‘\e’
+          escape
+     ‘\f’
+          form feed
+     ‘\n’
+          newline
+     ‘\r’
+          carriage return
+     ‘\t’
+          horizontal tab
+     ‘\v’
+          vertical tab
+     ‘\\’
+          backslash
+     ‘\0NNN’
+          the eight-bit value that is the octal number NNN (zero to
+          three octal digits), if NNN is a nine-bit value, the ninth bit
+          is ignored
+     ‘\NNN’
+          the eight-bit value that is the octal number NNN (one to three
+          octal digits), if NNN is a nine-bit value, the ninth bit is
+          ignored
+     ‘\xHH’
+          the eight-bit value that is the hexadecimal number HH (one or
+          two hexadecimal digits)
+
+‘-E’
+     Disable interpretation of backslash escapes in each STRING.  This
+     is the default.  If ‘-e’ and ‘-E’ are both specified, the last one
+     given takes effect.
+
+   If the ‘POSIXLY_CORRECT’ environment variable is set, then when
+‘echo’’s first argument is not ‘-n’ it outputs option-like arguments
+instead of treating them as options.  For example, ‘echo -ne hello’
+outputs ‘-ne hello’ instead of plain ‘hello’.  Also backslash escapes
+are always enabled.  Note to echo the string ‘-n’, one of the characters
+can be escaped in either octal or hexadecimal representation.  For
+example, ‘echo -e '\x2dn'’.
+
+   POSIX does not require support for any options, and says that the
+behavior of ‘echo’ is implementation-defined if any STRING contains a
+backslash or if the first argument is ‘-n’.  Portable programs should
+use the ‘printf’ command instead.  *Note printf invocation::.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: printf invocation,  Next: yes invocation,  Prev: echo invocation,  Up: Printing text
+
+15.2 ‘printf’: Format and print data
+====================================
+
+‘printf’ does formatted printing of text.  Synopsis:
+
+     printf FORMAT [ARGUMENT]...
+
+   ‘printf’ prints the FORMAT string, interpreting ‘%’ directives and
+‘\’ escapes to format numeric and string arguments in a way that is
+mostly similar to the C ‘printf’ function.  *Note ‘printf’ format
+directives: (libc)Output Conversion Syntax, for details.  The
+differences are listed below.
+
+   Due to shell aliases and built-in ‘printf’ functions, using an
+unadorned ‘printf’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+printf ...’) to avoid interference from the shell.
+
+   • The FORMAT argument is reused as necessary to convert all the given
+     ARGUMENTs.  For example, the command ‘printf %s a b’ outputs ‘ab’.
+
+   • Missing ARGUMENTs are treated as null strings or as zeros,
+     depending on whether the context expects a string or a number.  For
+     example, the command ‘printf %sx%d’ prints ‘x0’.
+
+   • An additional escape, ‘\c’, causes ‘printf’ to produce no further
+     output.  For example, the command ‘printf 'A%sC\cD%sF' B E’ prints
+     ‘ABC’.
+
+   • The hexadecimal escape sequence ‘\xHH’ has at most two digits, as
+     opposed to C where it can have an unlimited number of digits.  For
+     example, the command ‘printf '\x07e'’ prints two bytes, whereas the
+     C statement ‘printf ("\x07e")’ prints just one.
+
+   • An additional directive ‘%b’, prints its argument string with ‘\’
+     escapes interpreted in the same way as in the FORMAT string, except
+     that octal escapes are of the form ‘\0OOO’ where OOO is 0 to 3
+     octal digits.  If ‘\OOO’ is nine-bit value, ignore the ninth bit.
+     If a precision is also given, it limits the number of bytes printed
+     from the converted string.
+
+   • An additional directive ‘%q’, prints its argument string in a
+     format that can be reused as input by most shells.  Non-printable
+     characters are escaped with the POSIX proposed ‘$''’ syntax, and
+     shell metacharacters are quoted appropriately.  This is an
+     equivalent format to ‘ls --quoting=shell-escape’ output.
+
+   • Numeric arguments must be single C constants, possibly with leading
+     ‘+’ or ‘-’.  For example, ‘printf %.4d -3’ outputs ‘-0003’.
+
+   • If the leading character of a numeric argument is ‘"’ or ‘'’ then
+     its value is the numeric value of the immediately following
+     character.  Any remaining characters are silently ignored if the
+     ‘POSIXLY_CORRECT’ environment variable is set; otherwise, a warning
+     is printed.  For example, ‘printf "%d" "'a"’ outputs ‘97’ on hosts
+     that use the ASCII character set, since ‘a’ has the numeric value
+     97 in ASCII.
+
+   A floating point argument is interpreted according to the
+‘LC_NUMERIC’ category of either the current or the C locale, and is
+printed according to the current locale.  For example, in a locale whose
+decimal point character is a comma, the command ‘printf '%g %g' 2,5 2.5’
+outputs ‘2,5 2,5’.  *Note Floating point::.
+
+   ‘printf’ interprets ‘\OOO’ in FORMAT as an octal number (if OOO is 1
+to 3 octal digits) specifying a byte to print, and ‘\xHH’ as a
+hexadecimal number (if HH is 1 to 2 hex digits) specifying a character
+to print.  Note however that when ‘\OOO’ specifies a number larger than
+255, ‘printf’ ignores the ninth bit.  For example, ‘printf '\400'’ is
+equivalent to ‘printf '\0'’.
+
+   ‘printf’ interprets two syntax forms for specifying Unicode (ISO/IEC
+10646) characters.  ‘\u’ for 16-bit Unicode characters, specified as
+four hexadecimal digits HHHH, and ‘\U’ for 32-bit Unicode characters,
+specified as eight hexadecimal digits HHHHHHHH.  ‘printf’ outputs the
+Unicode characters according to the ‘LC_CTYPE’ locale.  Unicode
+characters in the range U+D800...U+DFFF cannot be specified by this
+syntax.  This syntax fully supports the universal character subset
+introduced in ISO C 99.
+
+   The processing of ‘\u’ and ‘\U’ requires a full-featured ‘iconv’
+facility.  It is activated on systems with glibc 2.2 (or newer), or when
+‘libiconv’ is installed prior to this package.  Otherwise ‘\u’ and ‘\U’
+will print as-is.
+
+   Unicode character syntax is useful for writing strings in a locale
+independent way.  For example, a string containing the Euro currency
+symbol
+
+     $ env printf '\u20AC 14.95'
+
+will be output correctly in all locales supporting the Euro symbol
+(ISO-8859-15, UTF-8, and others).  Similarly, a Chinese string
+
+     $ env printf '\u4e2d\u6587'
+
+will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8,
+etc).
+
+   Note that in these examples, the ‘printf’ command has been invoked
+via ‘env’ to ensure that we run the program found via your shell’s
+search path, and not a shell alias or a built-in function.
+
+   For larger strings, you don’t need to look up the hexadecimal code
+values of each character one by one.  ASCII characters mixed with \u
+escape sequences is also known as the JAVA source file encoding.  You
+can use GNU recode 3.5c (or newer) to convert strings to this encoding.
+Here is how to convert a piece of text into a shell script which will
+output this text in a locale-independent way:
+
+     $ LC_CTYPE=zh_TW.big5 env printf \
+         '\u4e2d\u6587\n' > sample.txt
+     $ recode BIG5..JAVA < sample.txt \
+         | sed -e "s|^|env printf '|" -e "s|%|%%|g" -e "s|$|\\\\n'|" \
+         > sample.sh
+
+   The only options are a lone ‘--help’ or ‘--version’.  *Note Common
+options::.  Options must precede operands.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: yes invocation,  Prev: printf invocation,  Up: Printing text
+
+15.3 ‘yes’: Print a string until interrupted
+============================================
+
+‘yes’ prints the command line arguments, separated by spaces and
+followed by a newline, forever until it is killed.  If no arguments are
+given, it prints ‘y’ followed by a newline forever until killed.
+
+   Upon a write error, ‘yes’ exits with status ‘1’.
+
+   The only options are a lone ‘--help’ or ‘--version’.  To output an
+argument that begins with ‘-’, precede it with ‘--’, e.g., ‘yes --
+--help’.  *Note Common options::.
+
+
+File: coreutils.info,  Node: Conditions,  Next: Redirection,  Prev: Printing text,  Up: Top
+
+16 Conditions
+*************
+
+This section describes commands that are primarily useful for their exit
+status, rather than their output.  Thus, they are often used as the
+condition of shell ‘if’ statements, or as the last command in a
+pipeline.
+
+* Menu:
+
+* false invocation::            Do nothing, unsuccessfully.
+* true invocation::             Do nothing, successfully.
+* test invocation::             Check file types and compare values.
+* expr invocation::             Evaluate expressions.
+
+
+File: coreutils.info,  Node: false invocation,  Next: true invocation,  Up: Conditions
+
+16.1 ‘false’: Do nothing, unsuccessfully
+========================================
+
+‘false’ does nothing except return an exit status of 1, meaning
+“failure”.  It can be used as a place holder in shell scripts where an
+unsuccessful command is needed.  In most modern shells, ‘false’ is a
+built-in command, so when you use ‘false’ in a script, you’re probably
+using the built-in command, not the one documented here.
+
+   ‘false’ honors the ‘--help’ and ‘--version’ options.
+
+   This version of ‘false’ is implemented as a C program, and is thus
+more secure and faster than a shell script implementation, and may
+safely be used as a dummy shell for the purpose of disabling accounts.
+
+   Note that ‘false’ (unlike all other programs documented herein) exits
+unsuccessfully, even when invoked with ‘--help’ or ‘--version’.
+
+   Portable programs should not assume that the exit status of ‘false’
+is 1, as it is greater than 1 on some non-GNU hosts.
+
+
+File: coreutils.info,  Node: true invocation,  Next: test invocation,  Prev: false invocation,  Up: Conditions
+
+16.2 ‘true’: Do nothing, successfully
+=====================================
+
+‘true’ does nothing except return an exit status of 0, meaning
+“success”.  It can be used as a place holder in shell scripts where a
+successful command is needed, although the shell built-in command ‘:’
+(colon) may do the same thing faster.  In most modern shells, ‘true’ is
+a built-in command, so when you use ‘true’ in a script, you’re probably
+using the built-in command, not the one documented here.
+
+   ‘true’ honors the ‘--help’ and ‘--version’ options.
+
+   Note, however, that it is possible to cause ‘true’ to exit with
+nonzero status: with the ‘--help’ or ‘--version’ option, and with
+standard output already closed or redirected to a file that evokes an
+I/O error.  For example, using a Bourne-compatible shell:
+
+     $ ./true --version >&-
+     ./true: write error: Bad file number
+     $ ./true --version > /dev/full
+     ./true: write error: No space left on device
+
+   This version of ‘true’ is implemented as a C program, and is thus
+more secure and faster than a shell script implementation, and may
+safely be used as a dummy shell for the purpose of disabling accounts.
+
+
+File: coreutils.info,  Node: test invocation,  Next: expr invocation,  Prev: true invocation,  Up: Conditions
+
+16.3 ‘test’: Check file types and compare values
+================================================
+
+‘test’ returns a status of 0 (true) or 1 (false) depending on the
+evaluation of the conditional expression EXPR.  Each part of the
+expression must be a separate argument.
+
+   ‘test’ has file status checks, string operators, and numeric
+comparison operators.
+
+   ‘test’ has an alternate form that uses opening and closing square
+brackets instead a leading ‘test’.  For example, instead of ‘test -d /’,
+you can write ‘[ -d / ]’.  The square brackets must be separate
+arguments; for example, ‘[-d /]’ does not have the desired effect.
+Since ‘test EXPR’ and ‘[ EXPR ]’ have the same meaning, only the former
+form is discussed below.
+
+   Synopses:
+
+     test EXPRESSION
+     test
+     [ EXPRESSION ]
+     [ ]
+     [ OPTION
+
+   Due to shell aliases and built-in ‘test’ functions, using an
+unadorned ‘test’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+test ...’) to avoid interference from the shell.
+
+   If EXPRESSION is omitted, ‘test’ returns false.  If EXPRESSION is a
+single argument, ‘test’ returns false if the argument is null and true
+otherwise.  The argument can be any string, including strings like ‘-d’,
+‘-1’, ‘--’, ‘--help’, and ‘--version’ that most other programs would
+treat as options.  To get help and version information, invoke the
+commands ‘[ --help’ and ‘[ --version’, without the usual closing
+brackets.  *Note Common options::.
+
+   Exit status:
+
+     0 if the expression is true,
+     1 if the expression is false,
+     2 if an error occurred.
+
+* Menu:
+
+* File type tests::             ‘-[bcdfhLpSt]’
+* Access permission tests::     ‘-[gkruwxOG]’
+* File characteristic tests::   ‘-e -s -nt -ot -ef’
+* String tests::                ‘-z -n = == !=’
+* Numeric tests::               ‘-eq -ne -lt -le -gt -ge’
+* Connectives for test::        ‘! -a -o’
+
+
+File: coreutils.info,  Node: File type tests,  Next: Access permission tests,  Up: test invocation
+
+16.3.1 File type tests
+----------------------
+
+These options test for particular types of files.  (Everything’s a file,
+but not all files are the same!)
+
+‘-b FILE’
+     True if FILE exists and is a block special device.
+
+‘-c FILE’
+     True if FILE exists and is a character special device.
+
+‘-d FILE’
+     True if FILE exists and is a directory.
+
+‘-f FILE’
+     True if FILE exists and is a regular file.
+
+‘-h FILE’
+‘-L FILE’
+     True if FILE exists and is a symbolic link.  Unlike all other
+     file-related tests, this test does not dereference FILE if it is a
+     symbolic link.
+
+‘-p FILE’
+     True if FILE exists and is a named pipe.
+
+‘-S FILE’
+     True if FILE exists and is a socket.
+
+‘-t FD’
+     True if FD is a file descriptor that is associated with a terminal.
+
+
+File: coreutils.info,  Node: Access permission tests,  Next: File characteristic tests,  Prev: File type tests,  Up: test invocation
+
+16.3.2 Access permission tests
+------------------------------
+
+These options test for particular access permissions.
+
+‘-g FILE’
+     True if FILE exists and has its set-group-ID bit set.
+
+‘-k FILE’
+     True if FILE exists and has its “sticky” bit set.
+
+‘-r FILE’
+     True if FILE exists and the user has read access.
+
+‘-u FILE’
+     True if FILE exists and has its set-user-ID bit set.
+
+‘-w FILE’
+     True if FILE exists and the user has write access.
+
+‘-x FILE’
+     True if FILE exists and the user has execute access (or search
+     permission, if it is a directory).
+
+‘-O FILE’
+     True if FILE exists and is owned by the current effective user ID.
+
+‘-G FILE’
+     True if FILE exists and is owned by the current effective group ID.
+
+
+File: coreutils.info,  Node: File characteristic tests,  Next: String tests,  Prev: Access permission tests,  Up: test invocation
+
+16.3.3 File characteristic tests
+--------------------------------
+
+These options test other file characteristics.
+
+‘-e FILE’
+     True if FILE exists.
+
+‘-s FILE’
+     True if FILE exists and has a size greater than zero.
+
+‘FILE1 -nt FILE2’
+     True if FILE1 is newer (according to modification date) than FILE2,
+     or if FILE1 exists and FILE2 does not.
+
+‘FILE1 -ot FILE2’
+     True if FILE1 is older (according to modification date) than FILE2,
+     or if FILE2 exists and FILE1 does not.
+
+‘FILE1 -ef FILE2’
+     True if FILE1 and FILE2 have the same device and inode numbers,
+     i.e., if they are hard links to each other.
+
+‘-N FILE’
+     True if FILE exists and has been modified (mtime) since it was last
+     read (atime).
+
+
+File: coreutils.info,  Node: String tests,  Next: Numeric tests,  Prev: File characteristic tests,  Up: test invocation
+
+16.3.4 String tests
+-------------------
+
+These options test string characteristics.  You may need to quote STRING
+arguments for the shell.  For example:
+
+     test -n "$V"
+
+   The quotes here prevent the wrong arguments from being passed to
+‘test’ if ‘$V’ is empty or contains special characters.
+
+‘-z STRING’
+     True if the length of STRING is zero.
+
+‘-n STRING’
+‘STRING’
+     True if the length of STRING is nonzero.
+
+‘STRING1 = STRING2’
+     True if the strings are equal.
+
+‘STRING1 == STRING2’
+     True if the strings are equal (synonym for =).  Note this form is
+     not as portable to other shells and systems.
+
+‘STRING1 != STRING2’
+     True if the strings are not equal.
+
+
+File: coreutils.info,  Node: Numeric tests,  Next: Connectives for test,  Prev: String tests,  Up: test invocation
+
+16.3.5 Numeric tests
+--------------------
+
+Numeric relational operators.  The arguments must be entirely numeric
+(possibly negative), or the special expression ‘-l STRING’, which
+evaluates to the length of STRING.
+
+‘ARG1 -eq ARG2’
+‘ARG1 -ne ARG2’
+‘ARG1 -lt ARG2’
+‘ARG1 -le ARG2’
+‘ARG1 -gt ARG2’
+‘ARG1 -ge ARG2’
+     These arithmetic binary operators return true if ARG1 is equal,
+     not-equal, less-than, less-than-or-equal, greater-than, or
+     greater-than-or-equal than ARG2, respectively.
+
+   For example:
+
+     test -1 -gt -2 && echo yes
+     ⇒ yes
+     test -l abc -gt 1 && echo yes
+     ⇒ yes
+     test 0x100 -eq 1
+     error→ test: integer expression expected before -eq
+
+
+File: coreutils.info,  Node: Connectives for test,  Prev: Numeric tests,  Up: test invocation
+
+16.3.6 Connectives for ‘test’
+-----------------------------
+
+Note it’s preferred to use shell logical primitives rather than these
+logical connectives internal to ‘test’, because an expression may become
+ambiguous depending on the expansion of its parameters.
+
+   For example, this becomes ambiguous when ‘$1’ is set to ‘'!'’ and
+‘$2’ to the empty string ‘''’:
+
+     test "$1" -a "$2"
+
+   and should be written as:
+
+     test "$1" && test "$2"
+
+   Note the shell logical primitives also benefit from short circuit
+operation, which can be significant for file attribute tests.
+
+‘! EXPR’
+     True if EXPR is false.  ‘!’ has lower precedence than all parts of
+     EXPR.  Note ‘!’ needs to be specified to the left of a binary
+     expression, I.e., ‘'!' 1 -gt 2’ rather than ‘1 '!' -gt 2’.  Also
+     ‘!’ is often a shell special character and is best used quoted.
+
+‘EXPR1 -a EXPR2’
+     True if both EXPR1 and EXPR2 are true.  ‘-a’ is left associative,
+     and has a higher precedence than ‘-o’.
+
+‘EXPR1 -o EXPR2’
+     True if either EXPR1 or EXPR2 is true.  ‘-o’ is left associative.
+
+
+File: coreutils.info,  Node: expr invocation,  Prev: test invocation,  Up: Conditions
+
+16.4 ‘expr’: Evaluate expressions
+=================================
+
+‘expr’ evaluates an expression and writes the result on standard output.
+Each token of the expression must be a separate argument.
+
+   Operands are either integers or strings.  Integers consist of one or
+more decimal digits, with an optional leading ‘-’.  ‘expr’ converts
+anything appearing in an operand position to an integer or a string
+depending on the operation being applied to it.
+
+   Strings are not quoted for ‘expr’ itself, though you may need to
+quote them to protect characters with special meaning to the shell,
+e.g., spaces.  However, regardless of whether it is quoted, a string
+operand should not be a parenthesis or any of ‘expr’’s operators like
+‘+’, so you cannot safely pass an arbitrary string ‘$str’ to expr merely
+by quoting it to the shell.  One way to work around this is to use the
+GNU extension ‘+’, (e.g., ‘+ "$str" = foo’); a more portable way is to
+use ‘" $str"’ and to adjust the rest of the expression to take the
+leading space into account (e.g., ‘" $str" = " foo"’).
+
+   You should not pass a negative integer or a string with leading ‘-’
+as ‘expr’’s first argument, as it might be misinterpreted as an option;
+this can be avoided by parenthesization.  Also, portable scripts should
+not use a string operand that happens to take the form of an integer;
+this can be worked around by inserting leading spaces as mentioned
+above.
+
+   Operators may be given as infix symbols or prefix keywords.
+Parentheses may be used for grouping in the usual manner.  You must
+quote parentheses and many operators to avoid the shell evaluating them,
+however.
+
+   Because ‘expr’ uses multiple-precision arithmetic, it works with
+integers wider than those of machine registers.
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.  Options must precede operands.
+
+   Exit status:
+
+     0 if the expression is neither null nor 0,
+     1 if the expression is null or 0,
+     2 if the expression is invalid,
+     3 if an internal error occurred (e.g., arithmetic overflow).
+
+* Menu:
+
+* String expressions::          ‘+ : match substr index length’
+* Numeric expressions::         ‘+ - * / %’
+* Relations for expr::          ‘| & < <= = == != >= >’
+* Examples of expr::            Examples.
+
+
+File: coreutils.info,  Node: String expressions,  Next: Numeric expressions,  Up: expr invocation
+
+16.4.1 String expressions
+-------------------------
+
+‘expr’ supports pattern matching and other string operators.  These have
+higher precedence than both the numeric and relational operators (in the
+next sections).
+
+‘STRING : REGEX’
+     Perform pattern matching.  The arguments are converted to strings
+     and the second is considered to be a (basic, a la GNU ‘grep’)
+     regular expression, with a ‘^’ implicitly prepended.  The first
+     argument is then matched against this regular expression.
+
+     If REGEX does not use ‘\(’ and ‘\)’, the ‘:’ expression returns the
+     number of characters matched, or 0 if the match fails.
+
+     If REGEX uses ‘\(’ and ‘\)’, the ‘:’ expression returns the part of
+     STRING that matched the subexpression, or the null string if the
+     match failed or the subexpression did not contribute to the match.
+
+     Only the first ‘\( ... \)’ pair is relevant to the return value;
+     additional pairs are meaningful only for grouping the regular
+     expression operators.
+
+     In the regular expression, ‘\+’, ‘\?’, and ‘\|’ are operators which
+     respectively match one or more, zero or one, or separate
+     alternatives.  These operators are GNU extensions.  *Note Regular
+     Expressions: (grep)Regular Expressions, for details of regular
+     expression syntax.  Some examples are in *note Examples of expr::.
+
+‘match STRING REGEX’
+     An alternative way to do pattern matching.  This is the same as
+     ‘STRING : REGEX’.
+
+‘substr STRING POSITION LENGTH’
+     Returns the substring of STRING beginning at POSITION with length
+     at most LENGTH.  If either POSITION or LENGTH is negative, zero, or
+     non-numeric, returns the null string.
+
+‘index STRING CHARSET’
+     Returns the first position in STRING where the first character in
+     CHARSET was found.  If no character in CHARSET is found in STRING,
+     return 0.
+
+‘length STRING’
+     Returns the length of STRING.
+
+‘+ TOKEN’
+     Interpret TOKEN as a string, even if it is a keyword like MATCH or
+     an operator like ‘/’.  This makes it possible to test ‘expr length
+     + "$x"’ or ‘expr + "$x" : '.*/\(.\)'’ and have it do the right
+     thing even if the value of $X happens to be (for example) ‘/’ or
+     ‘index’.  This operator is a GNU extension.  Portable shell scripts
+     should use ‘" $token" : ' \(.*\)'’ instead of ‘+ "$token"’.
+
+   To make ‘expr’ interpret keywords as strings, you must use the
+‘quote’ operator.
+
+
+File: coreutils.info,  Node: Numeric expressions,  Next: Relations for expr,  Prev: String expressions,  Up: expr invocation
+
+16.4.2 Numeric expressions
+--------------------------
+
+‘expr’ supports the usual numeric operators, in order of increasing
+precedence.  These numeric operators have lower precedence than the
+string operators described in the previous section, and higher
+precedence than the connectives (next section).
+
+‘+ -’
+     Addition and subtraction.  Both arguments are converted to
+     integers; an error occurs if this cannot be done.
+
+‘* / %’
+     Multiplication, division, remainder.  Both arguments are converted
+     to integers; an error occurs if this cannot be done.
+
+
+File: coreutils.info,  Node: Relations for expr,  Next: Examples of expr,  Prev: Numeric expressions,  Up: expr invocation
+
+16.4.3 Relations for ‘expr’
+---------------------------
+
+‘expr’ supports the usual logical connectives and relations.  These have
+lower precedence than the string and numeric operators (previous
+sections).  Here is the list, lowest-precedence operator first.
+
+‘|’
+     Returns its first argument if that is neither null nor zero,
+     otherwise its second argument if it is neither null nor zero,
+     otherwise 0.  It does not evaluate its second argument if its first
+     argument is neither null nor zero.
+
+‘&’
+     Return its first argument if neither argument is null or zero,
+     otherwise 0.  It does not evaluate its second argument if its first
+     argument is null or zero.
+
+‘< <= = == != >= >’
+     Compare the arguments and return 1 if the relation is true, 0
+     otherwise.  ‘==’ is a synonym for ‘=’.  ‘expr’ first tries to
+     convert both arguments to integers and do a numeric comparison; if
+     either conversion fails, it does a lexicographic comparison using
+     the character collating sequence specified by the ‘LC_COLLATE’
+     locale.
+
+
+File: coreutils.info,  Node: Examples of expr,  Prev: Relations for expr,  Up: expr invocation
+
+16.4.4 Examples of using ‘expr’
+-------------------------------
+
+Here are a few examples, including quoting for shell metacharacters.
+
+   To add 1 to the shell variable ‘foo’, in Bourne-compatible shells:
+
+     foo=$(expr $foo + 1)
+
+   To print the non-directory part of the file name stored in ‘$fname’,
+which need not contain a ‘/’:
+
+     expr $fname : '.*/\(.*\)' '|' $fname
+
+   An example showing that ‘\+’ is an operator:
+
+     expr aaa : 'a\+'
+     ⇒ 3
+
+     expr abc : 'a\(.\)c'
+     ⇒ b
+     expr index abcdef cz
+     ⇒ 3
+     expr index index a
+     error→ expr: syntax error
+     expr index + index a
+     ⇒ 0
+
+
+File: coreutils.info,  Node: Redirection,  Next: File name manipulation,  Prev: Conditions,  Up: Top
+
+17 Redirection
+**************
+
+Unix shells commonly provide several forms of “redirection” – ways to
+change the input source or output destination of a command.  But one
+useful redirection is performed by a separate command, not by the shell;
+it’s described here.
+
+* Menu:
+
+* tee invocation::              Redirect output to multiple files or processes.
+
+
+File: coreutils.info,  Node: tee invocation,  Up: Redirection
+
+17.1 ‘tee’: Redirect output to multiple files or processes
+==========================================================
+
+The ‘tee’ command copies standard input to standard output and also to
+any files given as arguments.  This is useful when you want not only to
+send some data down a pipe, but also to save a copy.  Synopsis:
+
+     tee [OPTION]... [FILE]...
+
+   If a file being written to does not already exist, it is created.  If
+a file being written to already exists, the data it previously contained
+is overwritten unless the ‘-a’ option is used.
+
+   In previous versions of GNU Coreutils (5.3.0–8.23), a FILE of ‘-’
+caused ‘tee’ to send another copy of input to standard output.  However,
+as the interleaved output was not very useful, ‘tee’ now conforms to
+POSIX and treats ‘-’ as a file name.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a’
+‘--append’
+     Append standard input to the given files rather than overwriting
+     them.
+
+‘-i’
+‘--ignore-interrupts’
+     Ignore interrupt signals.
+
+‘-p’
+‘--output-error[=MODE]’
+     Adjust the behavior with errors on the outputs.  In summary ‘-p’
+     allows ‘tee’ to operate in a more appropriate manner with pipes,
+     and to continue to process data to any remaining outputs, if any
+     pipe outputs exit early.  The default operation when
+     ‘--output-error’ is _not_ specified is to exit immediately on error
+     writing to a pipe, and diagnose errors writing to a non-pipe.  The
+     long form ‘--output-error’ option supports selection between the
+     following MODEs:
+
+     ‘warn’
+          Warn on error opening or writing any output, including pipes.
+          Writing is continued to still open files/pipes.  Exit status
+          indicates failure if any output has an error.
+
+     ‘warn-nopipe’
+          This is the default MODE when not specified, or when the short
+          form ‘-p’ is used.  Warn on error opening or writing any
+          output, except pipes.  Writing is continued to still open
+          files/pipes.  Exit immediately if all remaining outputs become
+          broken pipes.  Exit status indicates failure if any non pipe
+          output had an error.
+
+     ‘exit’
+          Exit on error opening or writing any output, including pipes.
+
+     ‘exit-nopipe’
+          Exit on error opening or writing any output, except pipes.
+          Exit immediately if all remaining outputs become broken pipes.
+
+   The ‘tee’ command is useful when you happen to be transferring a
+large amount of data and also want to summarize that data without
+reading it a second time.  For example, when you are downloading a DVD
+image, you often want to verify its signature or checksum right away.
+The inefficient way to do it is simply:
+
+     wget https://example.com/some.iso && sha1sum some.iso
+
+   One problem with the above is that it makes you wait for the download
+to complete before starting the time-consuming SHA1 computation.
+Perhaps even more importantly, the above requires reading the DVD image
+a second time (the first was from the network).
+
+   The efficient way to do it is to interleave the download and SHA1
+computation.  Then, you’ll get the checksum for free, because the entire
+process parallelizes so well:
+
+     # slightly contrived, to demonstrate process substitution
+     wget -O - https://example.com/dvd.iso \
+       | tee >(sha1sum > dvd.sha1) > dvd.iso
+
+   That makes ‘tee’ write not just to the expected output file, but also
+to a pipe running ‘sha1sum’ and saving the final checksum in a file
+named ‘dvd.sha1’.
+
+   Note, however, that this example relies on a feature of modern shells
+called “process substitution” (the ‘>(command)’ syntax, above; *Note
+Process Substitution: (bash)Process Substitution.), so it works with
+‘zsh’, ‘bash’, and ‘ksh’, but not with ‘/bin/sh’.  So if you write code
+like this in a shell script, be sure to start the script with
+‘#!/bin/bash’.
+
+   Note also that if any of the process substitutions (or piped standard
+output) might exit early without consuming all the data, the ‘-p’ option
+is needed to allow ‘tee’ to continue to process the input to any
+remaining outputs.
+
+   Since the above example writes to one file and one process, a more
+conventional and portable use of ‘tee’ is even better:
+
+     wget -O - https://example.com/dvd.iso \
+       | tee dvd.iso | sha1sum > dvd.sha1
+
+   You can extend this example to make ‘tee’ write to two processes,
+computing MD5 and SHA1 checksums in parallel.  In this case, process
+substitution is required:
+
+     wget -O - https://example.com/dvd.iso \
+       | tee >(sha1sum > dvd.sha1) \
+             >(md5sum > dvd.md5) \
+       > dvd.iso
+
+   This technique is also useful when you want to make a _compressed_
+copy of the contents of a pipe.  Consider a tool to graphically
+summarize file system usage data from ‘du -ak’.  For a large hierarchy,
+‘du -ak’ can run for a long time, and can easily produce terabytes of
+data, so you won’t want to rerun the command unnecessarily.  Nor will
+you want to save the uncompressed output.
+
+   Doing it the inefficient way, you can’t even start the GUI until
+after you’ve compressed all of the ‘du’ output:
+
+     du -ak | gzip -9 > /tmp/du.gz
+     gzip -d /tmp/du.gz | checkspace -a
+
+   With ‘tee’ and process substitution, you start the GUI right away and
+eliminate the decompression completely:
+
+     du -ak | tee >(gzip -9 > /tmp/du.gz) | checkspace -a
+
+   Finally, if you regularly create more than one type of compressed
+tarball at once, for example when ‘make dist’ creates both
+‘gzip’-compressed and ‘bzip2’-compressed tarballs, there may be a better
+way.  Typical ‘automake’-generated ‘Makefile’ rules create the two
+compressed tar archives with commands in sequence, like this (slightly
+simplified):
+
+     tardir=your-pkg-M.N
+     tar chof - "$tardir" | gzip  -9 -c > your-pkg-M.N.tar.gz
+     tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2
+
+   However, if the hierarchy you are archiving and compressing is larger
+than a couple megabytes, and especially if you are using a
+multi-processor system with plenty of memory, then you can do much
+better by reading the directory contents only once and running the
+compression programs in parallel:
+
+     tardir=your-pkg-M.N
+     tar chof - "$tardir" \
+       | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \
+       | bzip2 -9 -c > your-pkg-M.N.tar.bz2
+
+   If you want to further process the output from process substitutions,
+and those processes write atomically (i.e., write less than the system’s
+PIPE_BUF size at a time), that’s possible with a construct like:
+
+     tardir=your-pkg-M.N
+     tar chof - "$tardir" \
+       | tee >(md5sum --tag) > >(sha256sum --tag) \
+       | sort | gpg --clearsign > your-pkg-M.N.tar.sig
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: File name manipulation,  Next: Working context,  Prev: Redirection,  Up: Top
+
+18 File name manipulation
+*************************
+
+This section describes commands that manipulate file names.
+
+* Menu:
+
+* basename invocation::         Strip directory and suffix from a file name.
+* dirname invocation::          Strip last file name component.
+* pathchk invocation::          Check file name validity and portability.
+* mktemp invocation::           Create temporary file or directory.
+* realpath invocation::         Print resolved file names.
+
+
+File: coreutils.info,  Node: basename invocation,  Next: dirname invocation,  Up: File name manipulation
+
+18.1 ‘basename’: Strip directory and suffix from a file name
+============================================================
+
+‘basename’ removes any leading directory components from NAME.
+Synopsis:
+
+     basename NAME [SUFFIX]
+     basename OPTION... NAME...
+
+   If SUFFIX is specified and is identical to the end of NAME, it is
+removed from NAME as well.  Note that since trailing slashes are removed
+prior to suffix matching, SUFFIX will do nothing if it contains slashes.
+‘basename’ prints the result on standard output.
+
+   Together, ‘basename’ and ‘dirname’ are designed such that if ‘ls
+"$name"’ succeeds, then the command sequence ‘cd "$(dirname "$name")";
+ls "$(basename "$name")"’ will, too.  This works for everything except
+file names containing a trailing newline.
+
+   POSIX allows the implementation to define the results if NAME is
+empty or ‘//’.  In the former case, GNU ‘basename’ returns the empty
+string.  In the latter case, the result is ‘//’ on platforms where // is
+distinct from /, and ‘/’ on platforms where there is no difference.
+
+   The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands.
+
+‘-a’
+‘--multiple’
+     Support more than one argument.  Treat every argument as a NAME.
+     With this, an optional SUFFIX must be specified using the ‘-s’
+     option.
+
+‘-s SUFFIX’
+‘--suffix=SUFFIX’
+     Remove a trailing SUFFIX.  This option implies the ‘-a’ option.
+
+‘-z’
+‘--zero’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Examples:
+
+     # Output "sort".
+     basename /usr/bin/sort
+
+     # Output "stdio".
+     basename include/stdio.h .h
+
+     # Output "stdio".
+     basename -s .h include/stdio.h
+
+     # Output "stdio" followed by "stdlib"
+     basename -a -s .h include/stdio.h include/stdlib.h
+
+
+File: coreutils.info,  Node: dirname invocation,  Next: pathchk invocation,  Prev: basename invocation,  Up: File name manipulation
+
+18.2 ‘dirname’: Strip last file name component
+==============================================
+
+‘dirname’ prints all but the final slash-delimited component of each
+NAME.  Slashes on either side of the final component are also removed.
+If the string contains no slash, ‘dirname’ prints ‘.’ (meaning the
+current directory).  Synopsis:
+
+     dirname [OPTION] NAME...
+
+   NAME need not be a file name, but if it is, this operation
+effectively lists the directory that contains the final component,
+including the case when the final component is itself a directory.
+
+   Together, ‘basename’ and ‘dirname’ are designed such that if ‘ls
+"$name"’ succeeds, then the command sequence ‘cd "$(dirname "$name")";
+ls "$(basename "$name")"’ will, too.  This works for everything except
+file names containing a trailing newline.
+
+   POSIX allows the implementation to define the results if NAME is
+‘//’.  With GNU ‘dirname’, the result is ‘//’ on platforms where // is
+distinct from /, and ‘/’ on platforms where there is no difference.
+
+   The program accepts the following option.  Also see *note Common
+options::.
+
+‘-z’
+‘--zero’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   Examples:
+
+     # Output "/usr/bin".
+     dirname /usr/bin/sort
+     dirname /usr/bin//.//
+
+     # Output "dir1" followed by "dir2"
+     dirname dir1/str dir2/str
+
+     # Output ".".
+     dirname stdio.h
+
+
+File: coreutils.info,  Node: pathchk invocation,  Next: mktemp invocation,  Prev: dirname invocation,  Up: File name manipulation
+
+18.3 ‘pathchk’: Check file name validity and portability
+========================================================
+
+‘pathchk’ checks validity and portability of file names.  Synopsis:
+
+     pathchk [OPTION]... NAME...
+
+   For each NAME, ‘pathchk’ prints an error message if any of these
+conditions is true:
+
+  1. One of the existing directories in NAME does not have search
+     (execute) permission,
+  2. The length of NAME is larger than the maximum supported by the
+     operating system.
+  3. The length of one component of NAME is longer than its file
+     system’s maximum.
+
+   A nonexistent NAME is not an error, so long as a file with that name
+could be created under the above conditions.
+
+   The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands.
+
+‘-p’
+     Instead of performing checks based on the underlying file system,
+     print an error message if any of these conditions is true:
+
+       1. A file name is empty.
+
+       2. A file name contains a character outside the POSIX portable
+          file name character set, namely, the ASCII letters and digits,
+          ‘.’, ‘_’, ‘-’, and ‘/’.
+
+       3. The length of a file name or one of its components exceeds the
+          POSIX minimum limits for portability.
+
+‘-P’
+     Print an error message if a file name is empty, or if it contains a
+     component that begins with ‘-’.
+
+‘--portability’
+     Print an error message if a file name is not portable to all POSIX
+     hosts.  This option is equivalent to ‘-p -P’.
+
+   Exit status:
+
+     0 if all specified file names passed all checks,
+     1 otherwise.
+
+
+File: coreutils.info,  Node: mktemp invocation,  Next: realpath invocation,  Prev: pathchk invocation,  Up: File name manipulation
+
+18.4 ‘mktemp’: Create temporary file or directory
+=================================================
+
+‘mktemp’ manages the creation of temporary files and directories.
+Synopsis:
+
+     mktemp [OPTION]... [TEMPLATE]
+
+   Safely create a temporary file or directory based on TEMPLATE, and
+print its name.  If given, TEMPLATE must include at least three
+consecutive ‘X’s in the last component.  If omitted, the template
+‘tmp.XXXXXXXXXX’ is used, and option ‘--tmpdir’ is implied.  The final
+run of ‘X’s in the TEMPLATE will be replaced by alpha-numeric
+characters; thus, on a case-sensitive file system, and with a TEMPLATE
+including a run of N instances of ‘X’, there are ‘62**N’ potential file
+names.
+
+   Older scripts used to create temporary files by simply joining the
+name of the program with the process id (‘$$’) as a suffix.  However,
+that naming scheme is easily predictable, and suffers from a race
+condition where the attacker can create an appropriately named symbolic
+link, such that when the script then opens a handle to what it thought
+was an unused file, it is instead modifying an existing file.  Using the
+same scheme to create a directory is slightly safer, since the ‘mkdir’
+will fail if the target already exists, but it is still inferior because
+it allows for denial of service attacks.  Therefore, modern scripts
+should use the ‘mktemp’ command to guarantee that the generated name
+will be unpredictable, and that knowledge of the temporary file name
+implies that the file was created by the current script and cannot be
+modified by other users.
+
+   When creating a file, the resulting file has read and write
+permissions for the current user, but no permissions for the group or
+others; these permissions are reduced if the current umask is more
+restrictive.
+
+   Here are some examples (although note that if you repeat them, you
+will most likely get different file names):
+
+   • Create a temporary file in the current directory.
+          $ mktemp file.XXXX
+          file.H47c
+
+   • Create a temporary file with a known suffix.
+          $ mktemp --suffix=.txt file-XXXX
+          file-H08W.txt
+          $ mktemp file-XXXX-XXXX.txt
+          file-XXXX-eI9L.txt
+
+   • Create a secure fifo relative to the user’s choice of ‘TMPDIR’, but
+     falling back to the current directory rather than ‘/tmp’.  Note
+     that ‘mktemp’ does not create fifos, but can create a secure
+     directory in which the fifo can live.  Exit the shell if the
+     directory or fifo could not be created.
+          $ dir=$(mktemp -p "${TMPDIR:-.}" -d dir-XXXX) || exit 1
+          $ fifo=$dir/fifo
+          $ mkfifo "$fifo" || { rmdir "$dir"; exit 1; }
+
+   • Create and use a temporary file if possible, but ignore failure.
+     The file will reside in the directory named by ‘TMPDIR’, if
+     specified, or else in ‘/tmp’.
+          $ file=$(mktemp -q) && {
+          >   # Safe to use $file only within this block.  Use quotes,
+          >   # since $TMPDIR, and thus $file, may contain whitespace.
+          >   echo ... > "$file"
+          >   rm "$file"
+          > }
+
+   • Act as a semi-random character generator (it is not fully random,
+     since it is impacted by the contents of the current directory).  To
+     avoid security holes, do not use the resulting names to create a
+     file.
+          $ mktemp -u XXX
+          Gb9
+          $ mktemp -u XXX
+          nzC
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-d’
+‘--directory’
+     Create a directory rather than a file.  The directory will have
+     read, write, and search permissions for the current user, but no
+     permissions for the group or others; these permissions are reduced
+     if the current umask is more restrictive.
+
+‘-q’
+‘--quiet’
+     Suppress diagnostics about failure to create a file or directory.
+     The exit status will still reflect whether a file was created.
+
+‘-u’
+‘--dry-run’
+     Generate a temporary name that does not name an existing file,
+     without changing the file system contents.  Using the output of
+     this command to create a new file is inherently unsafe, as there is
+     a window of time between generating the name and using it where
+     another process can create an object by the same name.
+
+‘-p DIR’
+‘--tmpdir[=DIR]’
+     Treat TEMPLATE relative to the directory DIR.  If DIR is not
+     specified (only possible with the long option ‘--tmpdir’) or is the
+     empty string, use the value of ‘TMPDIR’ if available, otherwise use
+     ‘/tmp’.  If this is specified, TEMPLATE must not be absolute.
+     However, TEMPLATE can still contain slashes, although intermediate
+     directories must already exist.
+
+‘--suffix=SUFFIX’
+     Append SUFFIX to the TEMPLATE.  SUFFIX must not contain slash.  If
+     ‘--suffix’ is specified, TEMPLATE must end in ‘X’; if it is not
+     specified, then an appropriate ‘--suffix’ is inferred by finding
+     the last ‘X’ in TEMPLATE.  This option exists for use with the
+     default TEMPLATE and for the creation of a SUFFIX that starts with
+     ‘X’.
+
+‘-t’
+     Treat TEMPLATE as a single file relative to the value of ‘TMPDIR’
+     if available, or to the directory specified by ‘-p’, otherwise to
+     ‘/tmp’.  TEMPLATE must not contain slashes.  This option is
+     deprecated; the use of ‘-p’ without ‘-t’ offers better defaults (by
+     favoring the command line over ‘TMPDIR’) and more flexibility (by
+     allowing intermediate directories).
+
+   Exit status:
+
+     0 if the file was created,
+     1 otherwise.
+
+
+File: coreutils.info,  Node: realpath invocation,  Prev: mktemp invocation,  Up: File name manipulation
+
+18.5 ‘realpath’: Print the resolved file name.
+==============================================
+
+‘realpath’ expands all symbolic links and resolves references to ‘/./’,
+‘/../’ and extra ‘/’ characters.  By default, all but the last component
+of the specified files must exist.  Synopsis:
+
+     realpath [OPTION]... FILE...
+
+   The file name canonicalization functionality overlaps with that of
+the ‘readlink’ command.  This is the preferred command for
+canonicalization as it’s a more suitable and standard name.  In addition
+this command supports relative file name processing functionality.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-e’
+‘--canonicalize-existing’
+     Ensure that all components of the specified file names exist.  If
+     any component is missing or unavailable, ‘realpath’ will output a
+     diagnostic unless the ‘-q’ option is specified, and exit with a
+     nonzero exit code.  A trailing slash requires that the name resolve
+     to a directory.
+
+‘-m’
+‘--canonicalize-missing’
+     If any component of a specified file name is missing or
+     unavailable, treat it as a directory.
+
+‘-L’
+‘--logical’
+     Symbolic links are resolved in the specified file names, but they
+     are resolved after any subsequent ‘..’ components are processed.
+
+‘-P’
+‘--physical’
+     Symbolic links are resolved in the specified file names, and they
+     are resolved before any subsequent ‘..’ components are processed.
+     This is the default mode of operation.
+
+‘-q’
+‘--quiet’
+     Suppress diagnostic messages for specified file names.
+
+‘--relative-to=DIR’
+     Print the resolved file names relative to the specified directory.
+     Note this option honors the ‘-m’ and ‘-e’ options pertaining to
+     file existence.
+
+‘--relative-base=DIR’
+     Print the resolved file names as relative _if_ the files are
+     descendants of DIR.  Otherwise, print the resolved file names as
+     absolute.  Note this option honors the ‘-m’ and ‘-e’ options
+     pertaining to file existence.  For details about combining
+     ‘--relative-to’ and ‘--relative-base’, *note Realpath usage
+     examples::.
+
+‘-s’
+‘--strip’
+‘--no-symlinks’
+     Do not resolve symbolic links.  Only resolve references to ‘/./’,
+     ‘/../’ and remove extra ‘/’ characters.  When combined with the
+     ‘-m’ option, realpath operates only on the file name, and does not
+     touch any actual file.
+
+‘-z’
+‘--zero’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+
+   Exit status:
+
+     0 if all file names were printed without issue.
+     1 otherwise.
+
+* Menu:
+
+* Realpath usage examples::              Realpath usage examples.
+
+
+File: coreutils.info,  Node: Realpath usage examples,  Up: realpath invocation
+
+18.5.1 Realpath usage examples
+------------------------------
+
+By default, ‘realpath’ prints the absolute file name of given files
+(symlinks are resolved, ‘words’ is resolved to ‘american-english’):
+
+     cd /home/user
+     realpath /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+     ⇒ /usr/bin/sort
+     ⇒ /tmp/foo
+     ⇒ /usr/share/dict/american-english
+     ⇒ /home/user/1.txt
+
+   With ‘--relative-to’, file names are printed relative to the given
+directory:
+
+     realpath --relative-to=/usr/bin \
+              /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+     ⇒ sort
+     ⇒ ../../tmp/foo
+     ⇒ ../share/dict/american-english
+     ⇒ ../../home/user/1.txt
+
+   With ‘--relative-base’, relative file names are printed _if_ the
+resolved file name is below the given base directory.  For files outside
+the base directory absolute file names are printed:
+
+     realpath --relative-base=/usr \
+              /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+     ⇒ bin/sort
+     ⇒ /tmp/foo
+     ⇒ share/dict/american-english
+     ⇒ /home/user/1.txt
+
+   When both ‘--relative-to=DIR1’ and ‘--relative-base=DIR2’ are used,
+file names are printed relative to DIR1 _if_ they are located below
+DIR2.  If the files are not below DIR2, they are printed as absolute
+file names:
+
+     realpath --relative-to=/usr/bin --relative-base=/usr \
+              /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+     ⇒ sort
+     ⇒ /tmp/foo
+     ⇒ ../share/dict/american-english
+     ⇒ /home/user/1.txt
+
+   When both ‘--relative-to=DIR1’ and ‘--relative-base=DIR2’ are used,
+DIR1 _must_ be a subdirectory of DIR2.  Otherwise, ‘realpath’ prints
+absolutes file names.
+
+
+File: coreutils.info,  Node: Working context,  Next: User information,  Prev: File name manipulation,  Up: Top
+
+19 Working context
+******************
+
+This section describes commands that display or alter the context in
+which you are working: the current directory, the terminal settings, and
+so forth.  See also the user-related commands in the next section.
+
+* Menu:
+
+* pwd invocation::              Print working directory.
+* stty invocation::             Print or change terminal characteristics.
+* printenv invocation::         Print environment variables.
+* tty invocation::              Print file name of terminal on standard input.
+
+
+File: coreutils.info,  Node: pwd invocation,  Next: stty invocation,  Up: Working context
+
+19.1 ‘pwd’: Print working directory
+===================================
+
+‘pwd’ prints the name of the current directory.  Synopsis:
+
+     pwd [OPTION]...
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-L’
+‘--logical’
+     If the contents of the environment variable ‘PWD’ provide an
+     absolute name of the current directory with no ‘.’ or ‘..’
+     components, but possibly with symbolic links, then output those
+     contents.  Otherwise, fall back to default ‘-P’ handling.
+
+‘-P’
+‘--physical’
+     Print a fully resolved name for the current directory.  That is,
+     all components of the printed name will be actual directory names –
+     none will be symbolic links.
+
+   If ‘-L’ and ‘-P’ are both given, the last one takes precedence.  If
+neither option is given, then this implementation uses ‘-P’ as the
+default unless the ‘POSIXLY_CORRECT’ environment variable is set.
+
+   Due to shell aliases and built-in ‘pwd’ functions, using an unadorned
+‘pwd’ interactively or in a script may get you different functionality
+than that described here.  Invoke it via ‘env’ (i.e., ‘env pwd ...’) to
+avoid interference from the shell.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: stty invocation,  Next: printenv invocation,  Prev: pwd invocation,  Up: Working context
+
+19.2 ‘stty’: Print or change terminal characteristics
+=====================================================
+
+‘stty’ prints or changes terminal characteristics, such as baud rate.
+Synopses:
+
+     stty [OPTION] [SETTING]...
+     stty [OPTION]
+
+   If given no line settings, ‘stty’ prints the baud rate, line
+discipline number (on systems that support it), and line settings that
+have been changed from the values set by ‘stty sane’.  By default, mode
+reading and setting are performed on the tty line connected to standard
+input, although this can be modified by the ‘--file’ option.
+
+   ‘stty’ accepts many non-option arguments that change aspects of the
+terminal line operation, as described below.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a’
+‘--all’
+     Print all current settings in human-readable form.  This option may
+     not be used in combination with any line settings.
+
+‘-F DEVICE’
+‘--file=DEVICE’
+     Set the line opened by the file name specified in DEVICE instead of
+     the tty line connected to standard input.  This option is necessary
+     because opening a POSIX tty requires use of the ‘O_NONDELAY’ flag
+     to prevent a POSIX tty from blocking until the carrier detect line
+     is high if the ‘clocal’ flag is not set.  Hence, it is not always
+     possible to allow the shell to open the device in the traditional
+     manner.
+
+‘-g’
+‘--save’
+     Print all current settings in a form that can be used as an
+     argument to another ‘stty’ command to restore the current settings.
+     This option may not be used in combination with any line settings.
+
+   Many settings can be turned off by preceding them with a ‘-’.  Such
+arguments are marked below with “May be negated” in their description.
+The descriptions themselves refer to the positive case, that is, when
+_not_ negated (unless stated otherwise, of course).
+
+   Some settings are not available on all POSIX systems, since they use
+extensions.  Such arguments are marked below with “Non-POSIX” in their
+description.  On non-POSIX systems, those or other settings also may not
+be available, but it’s not feasible to document all the variations: just
+try it and see.
+
+   ‘stty’ is installed only on platforms with the POSIX terminal
+interface, so portable scripts should not rely on its existence on
+non-POSIX platforms.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+* Menu:
+
+* Control::                     Control settings
+* Input::                       Input settings
+* Output::                      Output settings
+* Local::                       Local settings
+* Combination::                 Combination settings
+* Characters::                  Special characters
+* Special::                     Special settings
+
+
+File: coreutils.info,  Node: Control,  Next: Input,  Up: stty invocation
+
+19.2.1 Control settings
+-----------------------
+
+Control settings:
+
+‘parenb’
+     Generate parity bit in output and expect parity bit in input.  May
+     be negated.
+
+‘parodd’
+     Set odd parity (even if negated).  May be negated.
+
+‘cmspar’
+     Use "stick" (mark/space) parity.  If parodd is set, the parity bit
+     is always 1; if parodd is not set, the parity bit is always zero.
+     Non-POSIX.  May be negated.
+
+‘cs5’
+‘cs6’
+‘cs7’
+‘cs8’
+     Set character size to 5, 6, 7, or 8 bits.
+
+‘hup’
+‘hupcl’
+     Send a hangup signal when the last process closes the tty.  May be
+     negated.
+
+‘cstopb’
+     Use two stop bits per character (one if negated).  May be negated.
+
+‘cread’
+     Allow input to be received.  May be negated.
+
+‘clocal’
+     Disable modem control signals.  May be negated.
+
+‘crtscts’
+     Enable RTS/CTS flow control.  Non-POSIX.  May be negated.
+
+‘cdtrdsr’
+     Enable DTR/DSR flow control.  Non-POSIX.  May be negated.
+
+
+File: coreutils.info,  Node: Input,  Next: Output,  Prev: Control,  Up: stty invocation
+
+19.2.2 Input settings
+---------------------
+
+These settings control operations on data received from the terminal.
+
+‘ignbrk’
+     Ignore break characters.  May be negated.
+
+‘brkint’
+     Make breaks cause an interrupt signal.  May be negated.
+
+‘ignpar’
+     Ignore characters with parity errors.  May be negated.
+
+‘parmrk’
+     Mark parity errors (with a 255-0-character sequence).  May be
+     negated.
+
+‘inpck’
+     Enable input parity checking.  May be negated.
+
+‘istrip’
+     Clear high (8th) bit of input characters.  May be negated.
+
+‘inlcr’
+     Translate newline to carriage return.  May be negated.
+
+‘igncr’
+     Ignore carriage return.  May be negated.
+
+‘icrnl’
+     Translate carriage return to newline.  May be negated.
+
+‘iutf8’
+     Assume input characters are UTF-8 encoded.  May be negated.
+
+‘ixon’
+     Enable XON/XOFF flow control (that is, ‘Ctrl-S’/‘Ctrl-Q’).  May be
+     negated.
+
+‘ixoff’
+‘tandem’
+     Enable sending of ‘stop’ character when the system input buffer is
+     almost full, and ‘start’ character when it becomes almost empty
+     again.  May be negated.
+
+‘iuclc’
+     Translate uppercase characters to lowercase.  Non-POSIX.  May be
+     negated.  Note ilcuc is not implemented, as one would not be able
+     to issue almost any (lowercase) Unix command, after invoking it.
+
+‘ixany’
+     Allow any character to restart output (only the start character if
+     negated).  Non-POSIX.  May be negated.
+
+‘imaxbel’
+     Enable beeping and not flushing input buffer if a character arrives
+     when the input buffer is full.  Non-POSIX.  May be negated.
+
+
+File: coreutils.info,  Node: Output,  Next: Local,  Prev: Input,  Up: stty invocation
+
+19.2.3 Output settings
+----------------------
+
+These settings control operations on data sent to the terminal.
+
+‘opost’
+     Postprocess output.  May be negated.
+
+‘olcuc’
+     Translate lowercase characters to uppercase.  Non-POSIX.  May be
+     negated.  (Note ouclc is not currently implemented.)
+
+‘ocrnl’
+     Translate carriage return to newline.  Non-POSIX.  May be negated.
+
+‘onlcr’
+     Translate newline to carriage return-newline.  Non-POSIX.  May be
+     negated.
+
+‘onocr’
+     Do not print carriage returns in the first column.  Non-POSIX.  May
+     be negated.
+
+‘onlret’
+     Newline performs a carriage return.  Non-POSIX.  May be negated.
+
+‘ofill’
+     Use fill (padding) characters instead of timing for delays.
+     Non-POSIX.  May be negated.
+
+‘ofdel’
+     Use ASCII DEL characters for fill instead of ASCII NUL characters.
+     Non-POSIX.  May be negated.
+
+‘nl1’
+‘nl0’
+     Newline delay style.  Non-POSIX.
+
+‘cr3’
+‘cr2’
+‘cr1’
+‘cr0’
+     Carriage return delay style.  Non-POSIX.
+
+‘tab3’
+‘tab2’
+‘tab1’
+‘tab0’
+     Horizontal tab delay style.  Non-POSIX.
+
+‘bs1’
+‘bs0’
+     Backspace delay style.  Non-POSIX.
+
+‘vt1’
+‘vt0’
+     Vertical tab delay style.  Non-POSIX.
+
+‘ff1’
+‘ff0’
+     Form feed delay style.  Non-POSIX.
+
+
+File: coreutils.info,  Node: Local,  Next: Combination,  Prev: Output,  Up: stty invocation
+
+19.2.4 Local settings
+---------------------
+
+‘isig’
+     Enable ‘interrupt’, ‘quit’, and ‘suspend’ special characters.  May
+     be negated.
+
+‘icanon’
+     Enable ‘erase’, ‘kill’, ‘werase’, and ‘rprnt’ special characters.
+     May be negated.
+
+‘iexten’
+     Enable non-POSIX special characters.  May be negated.
+
+‘echo’
+     Echo input characters.  May be negated.
+
+‘echoe’
+‘crterase’
+     Echo ‘erase’ characters as backspace-space-backspace.  May be
+     negated.
+
+‘echok’
+     Echo a newline after a ‘kill’ character.  May be negated.
+
+‘echonl’
+     Echo newline even if not echoing other characters.  May be negated.
+
+‘noflsh’
+     Disable flushing after ‘interrupt’ and ‘quit’ special characters.
+     May be negated.
+
+‘xcase’
+     Enable input and output of uppercase characters by preceding their
+     lowercase equivalents with ‘\’, when ‘icanon’ is set.  Non-POSIX.
+     May be negated.
+
+‘tostop’
+     Stop background jobs that try to write to the terminal.  Non-POSIX.
+     May be negated.
+
+‘echoprt’
+‘prterase’
+     Echo erased characters backward, between ‘\’ and ‘/’.  Non-POSIX.
+     May be negated.
+
+‘echoctl’
+‘ctlecho’
+     Echo control characters in hat notation (‘^C’) instead of
+     literally.  Non-POSIX.  May be negated.
+
+‘echoke’
+‘crtkill’
+     Echo the ‘kill’ special character by erasing each character on the
+     line as indicated by the ‘echoprt’ and ‘echoe’ settings, instead of
+     by the ‘echoctl’ and ‘echok’ settings.  Non-POSIX.  May be negated.
+
+‘extproc’
+     Enable ‘LINEMODE’, which is used to avoid echoing each character
+     over high latency links.  See also Internet RFC 1116
+     (https://tools.ietf.org/search/rfc1116).  Non-POSIX.  May be
+     negated.
+
+‘flusho’
+     Discard output.  Note this setting is currently ignored on
+     GNU/Linux systems.  Non-POSIX.  May be negated.
+
+
+File: coreutils.info,  Node: Combination,  Next: Characters,  Prev: Local,  Up: stty invocation
+
+19.2.5 Combination settings
+---------------------------
+
+Combination settings:
+
+‘evenp’
+‘parity’
+     Same as ‘parenb -parodd cs7’.  May be negated.  If negated, same as
+     ‘-parenb cs8’.
+
+‘oddp’
+     Same as ‘parenb parodd cs7’.  May be negated.  If negated, same as
+     ‘-parenb cs8’.
+
+‘nl’
+     Same as ‘-icrnl -onlcr’.  May be negated.  If negated, same as
+     ‘icrnl -inlcr -igncr onlcr -ocrnl -onlret’.
+
+‘ek’
+     Reset the ‘erase’ and ‘kill’ special characters to their default
+     values.
+
+‘sane’
+     Same as:
+
+          cread -ignbrk brkint -inlcr -igncr icrnl
+          icanon iexten echo echoe echok -echonl -noflsh
+          -ixoff -iutf8 -iuclc -ixany imaxbel -xcase -olcuc -ocrnl
+          opost -ofill onlcr -onocr -onlret nl0 cr0 tab0 bs0 vt0 ff0
+          isig -tostop -ofdel -echoprt echoctl echoke -extproc
+
+     and also sets all special characters to their default values.
+
+‘cooked’
+     Same as ‘brkint ignpar istrip icrnl ixon opost isig icanon’, plus
+     sets the ‘eof’ and ‘eol’ characters to their default values if they
+     are the same as the ‘min’ and ‘time’ characters.  May be negated.
+     If negated, same as ‘raw’.
+
+‘raw’
+     Same as:
+
+          -ignbrk -brkint -ignpar -parmrk -inpck -istrip
+          -inlcr -igncr -icrnl -ixon -ixoff -icanon -opost
+          -isig -iuclc -ixany -imaxbel -xcase min 1 time 0
+
+     May be negated.  If negated, same as ‘cooked’.
+
+‘cbreak’
+     Same as ‘-icanon’.  May be negated.  If negated, same as ‘icanon’.
+
+‘pass8’
+     Same as ‘-parenb -istrip cs8’.  May be negated.  If negated, same
+     as ‘parenb istrip cs7’.
+
+‘litout’
+     Same as ‘-parenb -istrip -opost cs8’.  May be negated.  If negated,
+     same as ‘parenb istrip opost cs7’.
+
+‘decctlq’
+     Same as ‘-ixany’.  Non-POSIX.  May be negated.
+
+‘tabs’
+     Same as ‘tab0’.  Non-POSIX.  May be negated.  If negated, same as
+     ‘tab3’.
+
+‘lcase’
+‘LCASE’
+     Same as ‘xcase iuclc olcuc’.  Non-POSIX.  May be negated.  (Used
+     for terminals with uppercase characters only.)
+
+‘crt’
+     Same as ‘echoe echoctl echoke’.
+
+‘dec’
+     Same as ‘echoe echoctl echoke -ixany intr ^C erase ^? kill C-u’.
+
+
+File: coreutils.info,  Node: Characters,  Next: Special,  Prev: Combination,  Up: stty invocation
+
+19.2.6 Special characters
+-------------------------
+
+The special characters’ default values vary from system to system.  They
+are set with the syntax ‘name value’, where the names are listed below
+and the value can be given either literally, in hat notation (‘^C’), or
+as an integer which may start with ‘0x’ to indicate hexadecimal, ‘0’ to
+indicate octal, or any other digit to indicate decimal.
+
+   For GNU stty, giving a value of ‘^-’ or ‘undef’ disables that special
+character.  (This is incompatible with Ultrix ‘stty’, which uses a value
+of ‘u’ to disable a special character.  GNU ‘stty’ treats a value ‘u’
+like any other, namely to set that special character to <U>.)
+
+‘intr’
+     Send an interrupt signal.
+
+‘quit’
+     Send a quit signal.
+
+‘erase’
+     Erase the last character typed.
+
+‘kill’
+     Erase the current line.
+
+‘eof’
+     Send an end of file (terminate the input).
+
+‘eol’
+     End the line.
+
+‘eol2’
+     Alternate character to end the line.  Non-POSIX.
+
+‘discard’
+     Alternate character to toggle discarding of output.  Non-POSIX.
+
+‘swtch’
+     Switch to a different shell layer.  Non-POSIX.
+
+‘status’
+     Send an info signal.  Not currently supported on GNU/Linux.
+     Non-POSIX.
+
+‘start’
+     Restart the output after stopping it.
+
+‘stop’
+     Stop the output.
+
+‘susp’
+     Send a terminal stop signal.
+
+‘dsusp’
+     Send a terminal stop signal after flushing the input.  Non-POSIX.
+
+‘rprnt’
+     Redraw the current line.  Non-POSIX.
+
+‘werase’
+     Erase the last word typed.  Non-POSIX.
+
+‘lnext’
+     Enter the next character typed literally, even if it is a special
+     character.  Non-POSIX.
+
+
+File: coreutils.info,  Node: Special,  Prev: Characters,  Up: stty invocation
+
+19.2.7 Special settings
+-----------------------
+
+‘min N’
+     Set the minimum number of characters that will satisfy a read until
+     the time value has expired, when ‘-icanon’ is set.
+
+‘time N’
+     Set the number of tenths of a second before reads time out if the
+     minimum number of characters have not been read, when ‘-icanon’ is
+     set.
+
+‘ispeed N’
+     Set the input speed to N.
+
+‘ospeed N’
+     Set the output speed to N.
+
+‘rows N’
+     Tell the tty kernel driver that the terminal has N rows.
+     Non-POSIX.
+
+‘cols N’
+‘columns N’
+     Tell the kernel that the terminal has N columns.  Non-POSIX.
+
+‘drain’
+     Apply settings after first waiting for pending output to be
+     transmitted.  This is enabled by default for GNU ‘stty’.  Note this
+     is treated as an option rather than a line setting, and will follow
+     the option processing rules described in the summary above.  It is
+     useful to disable this option in cases where the system may be in a
+     state where serial transmission is not possible.  For example, if
+     the system has received the ‘DC3’ character with ‘ixon’ (software
+     flow control) enabled, then ‘stty’ would block without ‘-drain’
+     being specified.  May be negated.  Non-POSIX.
+
+‘size’
+     Print the number of rows and columns that the kernel thinks the
+     terminal has.  (Systems that don’t support rows and columns in the
+     kernel typically use the environment variables ‘LINES’ and
+     ‘COLUMNS’ instead; however, GNU ‘stty’ does not know anything about
+     them.)  Non-POSIX.
+
+‘line N’
+     Use line discipline N.  Non-POSIX.
+
+‘speed’
+     Print the terminal speed.
+
+‘N’
+     Set the input and output speeds to N.  N can be one of: 0 50 75 110
+     134 134.5 150 200 300 600 1200 1800 2400 4800 9600 19200 38400
+     ‘exta’ ‘extb’.  ‘exta’ is the same as 19200; ‘extb’ is the same as
+     38400.  Many systems, including GNU/Linux, support higher speeds.
+     The ‘stty’ command includes support for speeds of 57600, 115200,
+     230400, 460800, 500000, 576000, 921600, 1000000, 1152000, 1500000,
+     2000000, 2500000, 3000000, 3500000, or 4000000 where the system
+     supports these.  0 hangs up the line if ‘-clocal’ is set.
+
+
+File: coreutils.info,  Node: printenv invocation,  Next: tty invocation,  Prev: stty invocation,  Up: Working context
+
+19.3 ‘printenv’: Print all or some environment variables
+========================================================
+
+‘printenv’ prints environment variable values.  Synopsis:
+
+     printenv [OPTION] [VARIABLE]...
+
+   If no VARIABLEs are specified, ‘printenv’ prints the value of every
+environment variable.  Otherwise, it prints the value of each VARIABLE
+that is set, and nothing for those that are not set.
+
+   The program accepts the following option.  Also see *note Common
+options::.
+
+‘-0’
+‘--null’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+
+   Exit status:
+
+     0 if all variables specified were found
+     1 if at least one specified variable was not found
+     2 if a write error occurred
+
+
+File: coreutils.info,  Node: tty invocation,  Prev: printenv invocation,  Up: Working context
+
+19.4 ‘tty’: Print file name of terminal on standard input
+=========================================================
+
+‘tty’ prints the file name of the terminal connected to its standard
+input.  It prints ‘not a tty’ if standard input is not a terminal.
+Synopsis:
+
+     tty [OPTION]...
+
+   The program accepts the following option.  Also see *note Common
+options::.
+
+‘-s’
+‘--silent’
+‘--quiet’
+     Print nothing; only return an exit status.
+
+   Exit status:
+
+     0 if standard input is a terminal
+     1 if standard input is a non-terminal file
+     2 if given incorrect arguments
+     3 if a write error occurs
+
+
+File: coreutils.info,  Node: User information,  Next: System context,  Prev: Working context,  Up: Top
+
+20 User information
+*******************
+
+This section describes commands that print user-related information:
+logins, groups, and so forth.
+
+* Menu:
+
+* id invocation::               Print user identity.
+* logname invocation::          Print current login name.
+* whoami invocation::           Print effective user ID.
+* groups invocation::           Print group names a user is in.
+* users invocation::            Print login names of users currently logged in.
+* who invocation::              Print who is currently logged in.
+
+
+File: coreutils.info,  Node: id invocation,  Next: logname invocation,  Up: User information
+
+20.1 ‘id’: Print user identity
+==============================
+
+‘id’ prints information about the given user, or the process running it
+if no user is specified.  Synopsis:
+
+     id [OPTION]... [USER]...
+
+   USER can be either a user ID or a name, with name look-up taking
+precedence unless the ID is specified with a leading ‘+’.  *Note
+Disambiguating names and IDs::.
+
+   By default, it prints the real user ID, real group ID, effective user
+ID if different from the real user ID, effective group ID if different
+from the real group ID, and supplemental group IDs.  In addition, if
+SELinux is enabled and the ‘POSIXLY_CORRECT’ environment variable is not
+set, then print ‘context=C’, where C is the security context.
+
+   Each of these numeric values is preceded by an identifying string and
+followed by the corresponding user or group name in parentheses.
+
+   The options cause ‘id’ to print only part of the above information.
+Also see *note Common options::.
+
+‘-g’
+‘--group’
+     Print only the group ID.
+
+‘-G’
+‘--groups’
+     Print only the group ID and the supplementary groups.
+
+‘-n’
+‘--name’
+     Print the user or group name instead of the ID number.  Requires
+     ‘-u’, ‘-g’, or ‘-G’.
+
+‘-r’
+‘--real’
+     Print the real, instead of effective, user or group ID.  Requires
+     ‘-u’, ‘-g’, or ‘-G’.
+
+‘-u’
+‘--user’
+     Print only the user ID.
+
+‘-Z’
+‘--context’
+     Print only the security context of the process, which is generally
+     the user’s security context inherited from the parent process.  If
+     neither SELinux or SMACK is enabled then print a warning and set
+     the exit status to 1.
+
+‘-z’
+‘--zero’
+     Delimit output items with ASCII NUL characters.  This option is not
+     permitted when using the default format.  When multiple users are
+     specified, and the ‘--groups’ option is also in effect, groups are
+     delimited with a single NUL character, while users are delimited
+     with two NUL characters.
+
+     Example:
+          $ id -Gn --zero
+          users <NUL> devs <NUL>
+
+   Primary and supplementary groups for a process are normally inherited
+from its parent and are usually unchanged since login.  This means that
+if you change the group database after logging in, ‘id’ will not reflect
+your changes within your existing login session.  Running ‘id’ with a
+user argument causes the user and group database to be consulted afresh,
+and so will give a different result.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: logname invocation,  Next: whoami invocation,  Prev: id invocation,  Up: User information
+
+20.2 ‘logname’: Print current login name
+========================================
+
+‘logname’ prints the calling user’s name, as found in a
+system-maintained file (often ‘/var/run/utmp’ or ‘/etc/utmp’), and exits
+with a status of 0.  If there is no entry for the calling process,
+‘logname’ prints an error message and exits with a status of 1.
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: whoami invocation,  Next: groups invocation,  Prev: logname invocation,  Up: User information
+
+20.3 ‘whoami’: Print effective user name
+========================================
+
+‘whoami’ prints the user name associated with the current effective user
+ID.  It is equivalent to the command ‘id -un’.
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: groups invocation,  Next: users invocation,  Prev: whoami invocation,  Up: User information
+
+20.4 ‘groups’: Print group names a user is in
+=============================================
+
+‘groups’ prints the names of the primary and any supplementary groups
+for each given USERNAME, or the current process if no names are given.
+If more than one name is given, the name of each user is printed before
+the list of that user’s groups and the user name is separated from the
+group list by a colon.  Synopsis:
+
+     groups [USERNAME]...
+
+   The group lists are equivalent to the output of the command ‘id -Gn’.
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   Primary and supplementary groups for a process are normally inherited
+from its parent and are usually unchanged since login.  This means that
+if you change the group database after logging in, ‘groups’ will not
+reflect your changes within your existing login session.  Running
+‘groups’ with a list of users causes the user and group database to be
+consulted afresh, and so will give a different result.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: users invocation,  Next: who invocation,  Prev: groups invocation,  Up: User information
+
+20.5 ‘users’: Print login names of users currently logged in
+============================================================
+
+‘users’ prints on a single line a blank-separated list of user names of
+users currently logged in to the current host.  Each user name
+corresponds to a login session, so if a user has more than one login
+session, that user’s name will appear the same number of times in the
+output.  Synopsis:
+
+     users [FILE]
+
+   With no FILE argument, ‘users’ extracts its information from a
+system-maintained file (often ‘/var/run/utmp’ or ‘/etc/utmp’).  If a
+file argument is given, ‘users’ uses that file instead.  A common choice
+is ‘/var/log/wtmp’.
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   The ‘users’ command is installed only on platforms with the POSIX
+‘<utmpx.h>’ include file or equivalent, so portable scripts should not
+rely on its existence on non-POSIX platforms.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: who invocation,  Prev: users invocation,  Up: User information
+
+20.6 ‘who’: Print who is currently logged in
+============================================
+
+‘who’ prints information about users who are currently logged on.
+Synopsis:
+
+     who [OPTION] [FILE] [am i]
+
+   If given no non-option arguments, ‘who’ prints the following
+information for each user currently logged on: login name, terminal
+line, login time, and remote hostname or X display.
+
+   If given one non-option argument, ‘who’ uses that instead of a
+default system-maintained file (often ‘/var/run/utmp’ or ‘/etc/utmp’) as
+the name of the file containing the record of users logged on.
+‘/var/log/wtmp’ is commonly given as an argument to ‘who’ to look at who
+has previously logged on.
+
+   If given two non-option arguments, ‘who’ prints only the entry for
+the user running it (determined from its standard input), preceded by
+the hostname.  Traditionally, the two arguments given are ‘am i’, as in
+‘who am i’.
+
+   Timestamps are listed according to the time zone rules specified by
+the ‘TZ’ environment variable, or by the system default rules if ‘TZ’ is
+not set.  *Note Specifying the Time Zone with ‘TZ’: (libc)TZ Variable.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a’
+‘--all’
+     Same as ‘-b -d --login -p -r -t -T -u’.
+
+‘-b’
+‘--boot’
+     Print the date and time of last system boot.
+
+‘-d’
+‘--dead’
+     Print information corresponding to dead processes.
+
+‘-H’
+‘--heading’
+     Print a line of column headings.
+
+‘-l’
+‘--login’
+     List only the entries that correspond to processes via which the
+     system is waiting for a user to login.  The user name is always
+     ‘LOGIN’.
+
+‘--lookup’
+     Attempt to canonicalize hostnames found in utmp through a DNS
+     lookup.  This is not the default because it can cause significant
+     delays on systems with automatic dial-up internet access.
+
+‘-m’
+     Same as ‘who am i’.
+
+‘-p’
+‘--process’
+     List active processes spawned by init.
+
+‘-q’
+‘--count’
+     Print only the login names and the number of users logged on.
+     Overrides all other options.
+
+‘-r’
+‘--runlevel’
+     Print the current (and maybe previous) run-level of the init
+     process.
+
+‘-s’
+     Ignored; for compatibility with other versions of ‘who’.
+
+‘-t’
+‘--time’
+     Print last system clock change.
+
+‘-u’
+     After the login time, print the number of hours and minutes that
+     the user has been idle.  ‘.’ means the user was active in the last
+     minute.  ‘old’ means the user has been idle for more than 24 hours.
+
+‘-w’
+‘-T’
+‘--mesg’
+‘--message’
+‘--writable’
+     After each login name print a character indicating the user’s
+     message status:
+
+          ‘+’ allowing ‘write’ messages
+          ‘-’ disallowing ‘write’ messages
+          ‘?’ cannot find terminal device
+
+   The ‘who’ command is installed only on platforms with the POSIX
+‘<utmpx.h>’ include file or equivalent, so portable scripts should not
+rely on its existence on non-POSIX platforms.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: System context,  Next: SELinux context,  Prev: User information,  Up: Top
+
+21 System context
+*****************
+
+This section describes commands that print or change system-wide
+information.
+
+* Menu:
+
+* date invocation::             Print or set system date and time.
+* arch invocation::             Print machine hardware name.
+* nproc invocation::            Print the number of processors.
+* uname invocation::            Print system information.
+* hostname invocation::         Print or set system name.
+* hostid invocation::           Print numeric host identifier.
+* uptime invocation::           Print system uptime and load.
+
+
+File: coreutils.info,  Node: date invocation,  Next: arch invocation,  Up: System context
+
+21.1 ‘date’: Print or set system date and time
+==============================================
+
+Synopses:
+
+     date [OPTION]... [+FORMAT]
+     date [-u|--utc|--universal] [ MMDDhhmm[[CC]YY][.ss] ]
+
+   The ‘date’ command displays the date and time.  With the ‘--set’
+(‘-s’) option, or with ‘MMDDhhmm[[CC]YY][.ss]’, it sets the date and
+time.
+
+   Invoking ‘date’ with no FORMAT argument is equivalent to invoking it
+with a default format that depends on the ‘LC_TIME’ locale category.  In
+the default C locale, this format is ‘'+%a %b %e %H:%M:%S %Z %Y'’, so
+the output looks like ‘Thu Jul  9 17:00:00 EDT 2020’.
+
+   Normally, ‘date’ uses the time zone rules indicated by the ‘TZ’
+environment variable, or the system default rules if ‘TZ’ is not set.
+*Note Specifying the Time Zone with ‘TZ’: (libc)TZ Variable.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+* Menu:
+
+* Date format specifiers::         Used in ‘date '+...'’
+* Setting the time::               Changing the system clock.
+* Options for date::               Instead of the current time.
+* Date input formats::             Specifying date strings.
+* Examples of date::               Examples.
+
+
+File: coreutils.info,  Node: Date format specifiers,  Next: Setting the time,  Up: date invocation
+
+21.1.1 Specifying the format of ‘date’ output
+---------------------------------------------
+
+If given an argument that starts with a ‘+’, ‘date’ prints the current
+date and time (or the date and time specified by the ‘--date’ option,
+see below) in the format defined by that argument, which is similar to
+that of the ‘strftime’ function.  Except for conversion specifiers,
+which start with ‘%’, characters in the format string are printed
+unchanged.  The conversion specifiers are described below.
+
+* Menu:
+
+* Time conversion specifiers::     %[HIklMNpPrRsSTXzZ]
+* Date conversion specifiers::     %[aAbBcCdDeFgGhjmuUVwWxyY]
+* Literal conversion specifiers::  %[%nt]
+* Padding and other flags::        Pad with zeros, spaces, etc.
+
+
+File: coreutils.info,  Node: Time conversion specifiers,  Next: Date conversion specifiers,  Up: Date format specifiers
+
+21.1.1.1 Time conversion specifiers
+...................................
+
+‘date’ conversion specifiers related to times.
+
+‘%H’
+     hour (‘00’...‘23’)
+‘%I’
+     hour (‘01’...‘12’)
+‘%k’
+     hour, space padded (‘ 0’...‘23’); equivalent to ‘%_H’.  This is a
+     GNU extension.
+‘%l’
+     hour, space padded (‘ 1’...‘12’); equivalent to ‘%_I’.  This is a
+     GNU extension.
+‘%M’
+     minute (‘00’...‘59’)
+‘%N’
+     nanoseconds (‘000000000’...‘999999999’).  This is a GNU extension.
+‘%p’
+     locale’s equivalent of either ‘AM’ or ‘PM’; blank in many locales.
+     Noon is treated as ‘PM’ and midnight as ‘AM’.
+‘%P’
+     like ‘%p’, except lower case.  This is a GNU extension.
+‘%r’
+     locale’s 12-hour clock time (e.g., ‘11:11:04 PM’)
+‘%R’
+     24-hour hour and minute.  Same as ‘%H:%M’.
+‘%s’
+     seconds since the Epoch, i.e., since 1970-01-01 00:00 UTC.  Leap
+     seconds are not counted unless leap second support is available.
+     *Note %s-examples::, for examples.  This is a GNU extension.
+‘%S’
+     second (‘00’...‘60’).  This may be ‘60’ if leap seconds are
+     supported.
+‘%T’
+     24-hour hour, minute, and second.  Same as ‘%H:%M:%S’.
+‘%X’
+     locale’s time representation (e.g., ‘23:13:48’)
+‘%z’
+     Four-digit numeric time zone, e.g., ‘-0600’ or ‘+0530’, or ‘-0000’
+     if no time zone is determinable.  This value reflects the numeric
+     time zone appropriate for the current time, using the time zone
+     rules specified by the ‘TZ’ environment variable.  A time zone is
+     not determinable if its numeric offset is zero and its abbreviation
+     begins with ‘-’.  The time (and optionally, the time zone rules)
+     can be overridden by the ‘--date’ option.
+‘%:z’
+     Numeric time zone with ‘:’, e.g., ‘-06:00’ or ‘+05:30’), or
+     ‘-00:00’ if no time zone is determinable.  This is a GNU extension.
+‘%::z’
+     Numeric time zone to the nearest second with ‘:’ (e.g., ‘-06:00:00’
+     or ‘+05:30:00’), or ‘-00:00:00’ if no time zone is determinable.
+     This is a GNU extension.
+‘%:::z’
+     Numeric time zone with ‘:’ using the minimum necessary precision
+     (e.g., ‘-06’, ‘+05:30’, or ‘-04:56:02’), or ‘-00’ if no time zone
+     is determinable.  This is a GNU extension.
+‘%Z’
+     alphabetic time zone abbreviation (e.g., ‘EDT’), or nothing if no
+     time zone is determinable.  See ‘%z’ for how it is determined.
+
+
+File: coreutils.info,  Node: Date conversion specifiers,  Next: Literal conversion specifiers,  Prev: Time conversion specifiers,  Up: Date format specifiers
+
+21.1.1.2 Date conversion specifiers
+...................................
+
+‘date’ conversion specifiers related to dates.
+
+‘%a’
+     locale’s abbreviated weekday name (e.g., ‘Sun’)
+‘%A’
+     locale’s full weekday name, variable length (e.g., ‘Sunday’)
+‘%b’
+     locale’s abbreviated month name (e.g., ‘Jan’)
+‘%B’
+     locale’s full month name, variable length (e.g., ‘January’)
+‘%c’
+     locale’s date and time (e.g., ‘Thu Mar  3 23:05:25 2020’)
+‘%C’
+     century.  This is like ‘%Y’, except the last two digits are
+     omitted.  For example, it is ‘20’ if ‘%Y’ is ‘2019’, and is ‘-0’ if
+     ‘%Y’ is ‘-001’.  It is normally at least two characters, but it may
+     be more.
+‘%d’
+     day of month (e.g., ‘01’)
+‘%D’
+     date; same as ‘%m/%d/%y’
+‘%e’
+     day of month, space padded; same as ‘%_d’
+‘%F’
+     full date in ISO 8601 format; like ‘%+4Y-%m-%d’ except that any
+     flags or field width override the ‘+’ and (after subtracting 6) the
+     ‘4’.  This is a good choice for a date format, as it is standard
+     and is easy to sort in the usual case where years are in the range
+     0000...9999.
+‘%g’
+     year corresponding to the ISO week number, but without the century
+     (range ‘00’ through ‘99’).  This has the same format and value as
+     ‘%y’, except that if the ISO week number (see ‘%V’) belongs to the
+     previous or next year, that year is used instead.
+‘%G’
+     year corresponding to the ISO week number.  This has the same
+     format and value as ‘%Y’, except that if the ISO week number (see
+     ‘%V’) belongs to the previous or next year, that year is used
+     instead.  It is normally useful only if ‘%V’ is also used; for
+     example, the format ‘%G-%m-%d’ is probably a mistake, since it
+     combines the ISO week number year with the conventional month and
+     day.
+‘%h’
+     same as ‘%b’
+‘%j’
+     day of year (‘001’...‘366’)
+‘%m’
+     month (‘01’...‘12’)
+‘%q’
+     quarter of year (‘1’...‘4’)
+‘%u’
+     day of week (‘1’...‘7’) with ‘1’ corresponding to Monday
+‘%U’
+     week number of year, with Sunday as the first day of the week
+     (‘00’...‘53’).  Days in a new year preceding the first Sunday are
+     in week zero.
+‘%V’
+     ISO week number, that is, the week number of year, with Monday as
+     the first day of the week (‘01’...‘53’).  If the week containing
+     January 1 has four or more days in the new year, then it is
+     considered week 1; otherwise, it is week 53 of the previous year,
+     and the next week is week 1.  (See the ISO 8601 standard.)
+‘%w’
+     day of week (‘0’...‘6’) with 0 corresponding to Sunday
+‘%W’
+     week number of year, with Monday as first day of week
+     (‘00’...‘53’).  Days in a new year preceding the first Monday are
+     in week zero.
+‘%x’
+     locale’s date representation (e.g., ‘12/31/99’)
+‘%y’
+     last two digits of year (‘00’...‘99’)
+‘%Y’
+     year.  This is normally at least four characters, but it may be
+     more.  Year ‘0000’ precedes year ‘0001’, and year ‘-001’ precedes
+     year ‘0000’.
+
+
+File: coreutils.info,  Node: Literal conversion specifiers,  Next: Padding and other flags,  Prev: Date conversion specifiers,  Up: Date format specifiers
+
+21.1.1.3 Literal conversion specifiers
+......................................
+
+‘date’ conversion specifiers that produce literal strings.
+
+‘%%’
+     a literal %
+‘%n’
+     a newline
+‘%t’
+     a horizontal tab
+
+
+File: coreutils.info,  Node: Padding and other flags,  Prev: Literal conversion specifiers,  Up: Date format specifiers
+
+21.1.1.4 Padding and other flags
+................................
+
+Unless otherwise specified, ‘date’ normally pads numeric fields with
+zeros, so that, for example, numeric months are always output as two
+digits.  Most numeric fields are padded on the left.  However,
+nanoseconds are padded on the right since they are commonly used after
+decimal points in formats like ‘%s.%-N’.  Also, seconds since the Epoch
+are not padded since there is no natural width for them.
+
+   The following optional flags can appear after the ‘%’:
+
+‘-’
+     (hyphen) Do not pad the field; useful if the output is intended for
+     human consumption.  This is a GNU extension.  As a special case,
+     ‘%-N’ outputs only enough trailing digits to not lose information,
+     assuming that the timestamp’s resolution is the same as the current
+     hardware clock.  For example, if the hardware clock resolution is 1
+     microsecond, ‘%s.%-N’ outputs something like ‘1640890100.395710’.
+
+‘_’
+     (underscore) Pad with spaces; useful if you need a fixed number of
+     characters in the output, but zeros are too distracting.  This is a
+     GNU extension.
+‘0’
+     (zero) Pad with zeros even if the conversion specifier would
+     normally pad with spaces.
+‘+’
+     Pad with zeros, like ‘0’.  In addition, precede any year number
+     with ‘+’ if it exceeds 9999 or if its field width exceeds 4;
+     similarly, precede any century number with ‘+’ if it exceeds 99 or
+     if its field width exceeds 2.  This supports ISO 8601 formats for
+     dates far in the future; for example, the command ‘date
+     --date=12019-02-25 +%+13F’ outputs the string ‘+012019-02-25’.
+‘^’
+     Use upper case characters if possible.  This is a GNU extension.
+‘#’
+     Use opposite case characters if possible.  A field that is normally
+     upper case becomes lower case, and vice versa.  This is a GNU
+     extension.
+
+Here are some examples of padding:
+
+     date +%d/%m -d "Feb 1"
+     ⇒ 01/02
+     date +%-d/%-m -d "Feb 1"
+     ⇒ 1/2
+     date +%_d/%_m -d "Feb 1"
+     ⇒  1/ 2
+
+   You can optionally specify the field width (after any flag, if
+present) as a decimal number.  If the natural size of the output of the
+field has less than the specified number of characters, the result is
+normally written right adjusted and padded to the given size.  For
+example, ‘%9B’ prints the right adjusted month name in a field of width
+9.  Nanoseconds are left adjusted, and are truncated or padded to the
+field width.
+
+   An optional modifier can follow the optional flag and width
+specification.  The modifiers are:
+
+‘E’
+     Use the locale’s alternate representation for date and time.  This
+     modifier applies to the ‘%c’, ‘%C’, ‘%x’, ‘%X’, ‘%y’ and ‘%Y’
+     conversion specifiers.  In a Japanese locale, for example, ‘%Ex’
+     might yield a date format based on the Japanese Emperors’ reigns.
+
+‘O’
+     Use the locale’s alternate numeric symbols for numbers.  This
+     modifier applies only to numeric conversion specifiers.
+
+   If the format supports the modifier but no alternate representation
+is available, it is ignored.
+
+   POSIX specifies the behavior of flags and field widths only for ‘%C’,
+‘%F’, ‘%G’, and ‘%Y’ (all without modifiers), and requires a flag to be
+present if and only if a field width is also present.  Other
+combinations of flags, field widths and modifiers are GNU extensions.
+
+
+File: coreutils.info,  Node: Setting the time,  Next: Options for date,  Prev: Date format specifiers,  Up: date invocation
+
+21.1.2 Setting the time
+-----------------------
+
+You must have appropriate privileges to set the system clock.  For
+changes to persist across a reboot, the hardware clock may need to be
+updated from the system clock, which might not happen automatically on
+your system.
+
+   To set the clock, you can use the ‘--set’ (‘-s’) option (*note
+Options for date::).  To set the clock without using GNU extensions, you
+can give ‘date’ an argument of the form ‘MMDDhhmm[[CC]YY][.ss]’ where
+each two-letter component stands for two digits with the following
+meanings:
+
+MM
+     month
+DD
+     day within month
+HH
+     hour
+MM
+     minute
+CC
+     first two digits of year (optional)
+YY
+     last two digits of year (optional)
+SS
+     second (optional)
+
+   Note, the ‘--date’ and ‘--set’ options may not be used with an
+argument in the above format.  The ‘--universal’ option may be used with
+such an argument to indicate that the specified date and time are
+relative to Universal Time rather than to the local time zone.
+
+
+File: coreutils.info,  Node: Options for date,  Next: Examples of date,  Prev: Setting the time,  Up: date invocation
+
+21.1.3 Options for ‘date’
+-------------------------
+
+The program accepts the following options.  Also see *note Common
+options::.  Except for ‘-u’, these options are all GNU extensions to
+POSIX.
+
+   All options that specify the date to display are mutually exclusive.
+I.e.: ‘--date’, ‘--file’, ‘--reference’, ‘--resolution’.
+
+‘-d DATESTR’
+‘--date=DATESTR’
+     Display the date and time specified in DATESTR instead of the
+     current date and time.  DATESTR can be in almost any common format.
+     It can contain month names, time zones, ‘am’ and ‘pm’, ‘yesterday’,
+     etc.  For example, ‘--date="2020-07-21 14:19:13.489392193 +0530"’
+     specifies the instant of time that is 489,392,193 nanoseconds after
+     July 21, 2020 at 2:19:13 PM in a time zone that is 5 hours and 30
+     minutes east of UTC.
+     Note: input currently must be in locale independent format.  E.g.,
+     the LC_TIME=C below is needed to print back the correct date in
+     many locales:
+          date -d "$(LC_TIME=C date)"
+     *Note Date input formats::.
+
+‘--debug’
+     Annotate the parsed date, display the effective time zone, and warn
+     about potential misuse.
+
+‘-f DATEFILE’
+‘--file=DATEFILE’
+     Parse each line in DATEFILE as with ‘-d’ and display the resulting
+     date and time.  If DATEFILE is ‘-’, use standard input.  This is
+     useful when you have many dates to process, because the system
+     overhead of starting up the ‘date’ executable many times can be
+     considerable.
+
+‘-I[TIMESPEC]’
+‘--iso-8601[=TIMESPEC]’
+     Display the date using an ISO 8601 format, ‘%Y-%m-%d’.
+
+     The argument TIMESPEC specifies the number of additional terms of
+     the time to include.  It can be one of the following:
+     ‘auto’
+          Print just the date.  This is the default if TIMESPEC is
+          omitted.  This is like the format ‘%Y-%m-%d’.
+
+     ‘hours’
+          Also print hours and time zone.  This is like the format
+          ‘%Y-%m-%dT%H%:z’.
+
+     ‘minutes’
+          Also print minutes.  This is like the format
+          ‘%Y-%m-%dT%H:%M%:z’.
+
+     ‘seconds’
+          Also print seconds.  This is like the format
+          ‘%Y-%m-%dT%H:%M:%S%:z’.
+
+     ‘ns’
+          Also print nanoseconds.  This is like the format
+          ‘%Y-%m-%dT%H:%M:%S,%N%:z’.
+
+     This format is always suitable as input for the ‘--date’ (‘-d’) and
+     ‘--file’ (‘-f’) options, regardless of the current locale.
+
+‘-r FILE’
+‘--reference=FILE’
+     Display the date and time of the last modification of FILE, instead
+     of the current date and time.
+
+‘--resolution’
+     Display the timestamp resolution instead of the time.  Current
+     clock timestamps that are output by ‘date’ are integer multiples of
+     the timestamp resolution.  With this option, the format defaults to
+     ‘%s.%N’.  For example, if the clock resolution is 1 millisecond,
+     the output is:
+
+          0.001000000
+
+‘-R’
+‘--rfc-email’
+     Display the date and time using the format ‘%a, %d %b %Y %H:%M:%S
+     %z’, evaluated in the C locale so abbreviations are always in
+     English.  For example:
+
+          Mon, 09 Jul 2020 17:00:00 -0400
+
+     This format conforms to Internet RFCs 5322
+     (https://tools.ietf.org/search/rfc5322), 2822
+     (https://tools.ietf.org/search/rfc2822) and 822
+     (https://tools.ietf.org/search/rfc822), the current and previous
+     standards for Internet email.  For compatibility with older
+     versions of ‘date’, ‘--rfc-2822’ and ‘--rfc-822’ are aliases for
+     ‘--rfc-email’.
+
+‘--rfc-3339=TIMESPEC’
+     Display the date using a format specified by Internet RFC 3339
+     (https://tools.ietf.org/search/rfc3339).  This is like
+     ‘--iso-8601’, except that a space rather than a ‘T’ separates dates
+     from times, and a period rather than a comma separates seconds from
+     subseconds.  This format is always suitable as input for the
+     ‘--date’ (‘-d’) and ‘--file’ (‘-f’) options, regardless of the
+     current locale.
+
+     The argument TIMESPEC specifies how much of the time to include.
+     It can be one of the following:
+
+     ‘date’
+          Print just the full-date, e.g., ‘2020-07-21’.  This is like
+          the format ‘%Y-%m-%d’.
+
+     ‘seconds’
+          Print the full-date and full-time separated by a space, e.g.,
+          ‘2020-07-21 04:30:37+05:30’.  The output ends with a numeric
+          time-offset; here the ‘+05:30’ means that local time is five
+          hours and thirty minutes east of UTC.  This is like the format
+          ‘%Y-%m-%d %H:%M:%S%:z’.
+
+     ‘ns’
+          Like ‘seconds’, but also print nanoseconds, e.g., ‘2020-07-21
+          04:30:37.998458565+05:30’.  This is like the format ‘%Y-%m-%d
+          %H:%M:%S.%N%:z’.
+
+‘-s DATESTR’
+‘--set=DATESTR’
+     Set the date and time to DATESTR.  See ‘-d’ above.  See also *note
+     Setting the time::.
+
+‘-u’
+‘--utc’
+‘--universal’
+     Use Universal Time by operating as if the ‘TZ’ environment variable
+     were set to the string ‘UTC0’.  UTC stands for Coordinated
+     Universal Time, established in 1960.  Universal Time is often
+     called “Greenwich Mean Time” (GMT) for historical reasons.
+     Typically, systems ignore leap seconds and thus implement an
+     approximation to UTC rather than true UTC.
+
+
+File: coreutils.info,  Node: Examples of date,  Prev: Options for date,  Up: date invocation
+
+21.1.4 Examples of ‘date’
+-------------------------
+
+Here are a few examples.  Also see the documentation for the ‘-d’ option
+in the previous section.
+
+   • To print the date of the day before yesterday:
+
+          date --date='2 days ago'
+
+   • To print the date of the day three months and one day hence:
+
+          date --date='3 months 1 day'
+
+   • To print the day of year of Christmas in the current year:
+
+          date --date='25 Dec' +%j
+
+   • To print the current full month name and the day of the month:
+
+          date '+%B %d'
+
+     But this may not be what you want because for the first nine days
+     of the month, the ‘%d’ expands to a zero-padded two-digit field,
+     for example ‘date -d 1may '+%B %d'’ will print ‘May 01’.
+
+   • To print a date without the leading zero for one-digit days of the
+     month, you can use the (GNU extension) ‘-’ flag to suppress the
+     padding altogether:
+
+          date -d 1may '+%B %-d'
+
+   • To print the current date and time in the format required by many
+     non-GNU versions of ‘date’ when setting the system clock:
+
+          date +%m%d%H%M%Y.%S
+
+   • To set the system clock forward by two minutes:
+
+          date --set='+2 minutes'
+
+   • To print the date in Internet RFC 5322 format, use ‘date
+     --rfc-email’.  Here is some example output:
+
+          Tue, 09 Jul 2020 19:00:37 -0400
+
+   • To convert a date string to the number of seconds since the Epoch
+     (which is 1970-01-01 00:00 UTC), use the ‘--date’ option with the
+     ‘%s’ format.  That can be useful in sorting and/or graphing and/or
+     comparing data by date.  The following command outputs the number
+     of the seconds since the Epoch for the time two minutes after the
+     Epoch:
+
+          date --date='1970-01-01 00:02:00 +0000' +%s
+          120
+
+     To convert a date string from one time zone FROM to another TO,
+     specify ‘TZ="FROM"’ in the environment and ‘TZ="TO"’ in the
+     ‘--date’ option.  *Note Specifying time zone rules::.  For example:
+
+          TZ="Asia/Tokyo" date --date='TZ="America/New_York" 2023-05-07 12:23'
+          Mon May  8 01:23:00 JST 2023
+
+     If you do not specify time zone information in the date string,
+     ‘date’ uses your computer’s idea of the time zone when interpreting
+     the string.  For example, if your computer’s time zone is that of
+     Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000
+     seconds) behind UTC:
+
+          # local time zone used
+          date --date='1970-01-01 00:02:00' +%s
+          18120
+
+   • If you’re sorting or graphing dated data, your raw date values may
+     be represented as seconds since the Epoch.  But few people can look
+     at the date ‘1577836800’ and casually note “Oh, that’s the first
+     second of the year 2020 in Greenwich, England.”
+
+          date --date='2020-01-01 UTC' +%s
+          1577836800
+
+     An alternative is to use the ‘--utc’ (‘-u’) option.  Then you may
+     omit ‘UTC’ from the date string.  Although this produces the same
+     result for ‘%s’ and many other format sequences, with a time zone
+     offset different from zero, it would give a different result for
+     zone-dependent formats like ‘%z’.
+
+          date -u --date=2020-07-21 +%s
+          1595289600
+
+     To convert such an unwieldy number of seconds back to a more
+     readable form, use a command like this:
+
+          date -d @1595289600 +"%F %T %z"
+          2020-07-20 20:00:00 -0400
+
+     Often it is better to output UTC-relative date and time:
+
+          date -u -d @1595289600 +"%F %T %z"
+          2020-07-21 00:00:00 +0000
+
+   • Typically the seconds count omits leap seconds, but some systems
+     are exceptions.  Because leap seconds are not predictable, the
+     mapping between the seconds count and a future timestamp is not
+     reliable on the atypical systems that include leap seconds in their
+     counts.
+
+     Here is how the two kinds of systems handle the leap second at the
+     end of the year 2016:
+
+          # Typical systems ignore leap seconds:
+          date --date='2016-12-31 23:59:59 +0000' +%s
+          1483228799
+          date --date='2016-12-31 23:59:60 +0000' +%s
+          date: invalid date '2016-12-31 23:59:60 +0000'
+          date --date='2017-01-01 00:00:00 +0000' +%s
+          1483228800
+
+          # Atypical systems count leap seconds:
+          date --date='2016-12-31 23:59:59 +0000' +%s
+          1483228825
+          date --date='2016-12-31 23:59:60 +0000' +%s
+          1483228826
+          date --date='2017-01-01 00:00:00 +0000' +%s
+          1483228827
+
+
+File: coreutils.info,  Node: arch invocation,  Next: nproc invocation,  Prev: date invocation,  Up: System context
+
+21.2 ‘arch’: Print machine hardware name
+========================================
+
+‘arch’ prints the machine hardware name, and is equivalent to ‘uname
+-m’.  Synopsis:
+
+     arch [OPTION]
+
+   The program accepts the *note Common options:: only.
+
+   ‘arch’ is not installed by default, so portable scripts should not
+rely on its existence.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: nproc invocation,  Next: uname invocation,  Prev: arch invocation,  Up: System context
+
+21.3 ‘nproc’: Print the number of available processors
+======================================================
+
+Print the number of processing units available to the current process,
+which may be less than the number of online processors.  If this
+information is not accessible, then print the number of processors
+installed.  If the ‘OMP_NUM_THREADS’ or ‘OMP_THREAD_LIMIT’ environment
+variables are set, then they will determine the minimum and maximum
+returned value respectively.  The result is guaranteed to be greater
+than zero.  Synopsis:
+
+     nproc [OPTION]
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘--all’
+     Print the number of installed processors on the system, which may
+     be greater than the number online or available to the current
+     process.  The ‘OMP_NUM_THREADS’ or ‘OMP_THREAD_LIMIT’ environment
+     variables are not honored in this case.
+
+‘--ignore=NUMBER’
+     If possible, exclude this NUMBER of processing units.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: uname invocation,  Next: hostname invocation,  Prev: nproc invocation,  Up: System context
+
+21.4 ‘uname’: Print system information
+======================================
+
+‘uname’ prints information about the machine and operating system it is
+run on.  If no options are given, ‘uname’ acts as if the ‘-s’ option
+were given.  Synopsis:
+
+     uname [OPTION]...
+
+   If multiple options or ‘-a’ are given, the selected information is
+printed in this order:
+
+     KERNEL-NAME NODENAME KERNEL-RELEASE KERNEL-VERSION
+     MACHINE PROCESSOR HARDWARE-PLATFORM OPERATING-SYSTEM
+
+   The information may contain internal spaces, so such output cannot be
+parsed reliably.  In the following example, KERNEL-VERSION is ‘#1 SMP
+Fri Jul 17 17:18:38 UTC 2020’:
+
+     uname -a
+     ⇒ Linux dumdum.example.org 5.9.16-200.fc33.x86_64 #1 SMP Mon Dec 21 14:08:22 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-a’
+‘--all’
+     Print all of the below information, except omit the processor type
+     and the hardware platform name if they are unknown.
+
+‘-i’
+‘--hardware-platform’
+     Print the hardware platform name (sometimes called the hardware
+     implementation).  Print ‘unknown’ if this information is not
+     available.  Note this is non-portable (even across GNU/Linux
+     distributions).
+
+‘-m’
+‘--machine’
+     Print the machine hardware name (sometimes called the hardware
+     class or hardware type).
+
+‘-n’
+‘--nodename’
+     Print the network node hostname.
+
+‘-p’
+‘--processor’
+     Print the processor type (sometimes called the instruction set
+     architecture or ISA). Print ‘unknown’ if this information is not
+     available.  Note this is non-portable (even across GNU/Linux
+     distributions).
+
+‘-o’
+‘--operating-system’
+     Print the name of the operating system.
+
+‘-r’
+‘--kernel-release’
+     Print the kernel release.
+
+‘-s’
+‘--kernel-name’
+     Print the kernel name.  POSIX 1003.1-2001 (*note Standards
+     conformance::) calls this “the implementation of the operating
+     system”, because the POSIX specification itself has no notion of
+     “kernel”.  The kernel name might be the same as the operating
+     system name printed by the ‘-o’ or ‘--operating-system’ option, but
+     it might differ.  Some operating systems (e.g., FreeBSD, HP-UX)
+     have the same name as their underlying kernels; others (e.g.,
+     GNU/Linux, Solaris) do not.
+
+‘-v’
+‘--kernel-version’
+     Print the kernel version.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: hostname invocation,  Next: hostid invocation,  Prev: uname invocation,  Up: System context
+
+21.5 ‘hostname’: Print or set system name
+=========================================
+
+With no arguments, ‘hostname’ prints the name of the current host
+system.  With one argument, it sets the current host name to the
+specified string.  You must have appropriate privileges to set the host
+name.  Synopsis:
+
+     hostname [NAME]
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   ‘hostname’ is not installed by default, and other packages also
+supply a ‘hostname’ command, so portable scripts should not rely on its
+existence or on the exact behavior documented above.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: hostid invocation,  Next: uptime invocation,  Prev: hostname invocation,  Up: System context
+
+21.6 ‘hostid’: Print numeric host identifier
+============================================
+
+‘hostid’ prints the numeric identifier of the current host in
+hexadecimal.  This command accepts no arguments.  The only options are
+‘--help’ and ‘--version’.  *Note Common options::.
+
+   For example, here’s what it prints on one system I use:
+
+     $ hostid
+     1bac013d
+
+   On that system, the 32-bit quantity happens to be closely related to
+the system’s Internet address, but that isn’t always the case.
+
+   ‘hostid’ is installed only on systems that have the ‘gethostid’
+function, so portable scripts should not rely on its existence.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: uptime invocation,  Prev: hostid invocation,  Up: System context
+
+21.7 ‘uptime’: Print system uptime and load
+===========================================
+
+‘uptime’ prints the current time, the system’s uptime, the number of
+logged-in users and the current load average.
+
+   If an argument is specified, it is used as the file to be read to
+discover how many users are logged in.  If no argument is specified, a
+system default is used (‘uptime --help’ indicates the default setting).
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   For example, here’s what it prints right now on one system I use:
+
+     $ uptime
+      14:07  up   3:35,  3 users,  load average: 1.39, 1.15, 1.04
+
+   The precise method of calculation of load average varies somewhat
+between systems.  Some systems calculate it as the average number of
+runnable processes over the last 1, 5 and 15 minutes, but some systems
+also include processes in the uninterruptible sleep state (that is,
+those processes which are waiting for device I/O). The Linux kernel
+includes uninterruptible processes.
+
+   ‘uptime’ is installed only on platforms with infrastructure for
+obtaining the boot time, and other packages also supply an ‘uptime’
+command, so portable scripts should not rely on its existence or on the
+exact behavior documented above.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: SELinux context,  Next: Modified command invocation,  Prev: System context,  Up: Top
+
+22 SELinux context
+******************
+
+This section describes commands for operations with SELinux contexts.
+
+* Menu:
+
+* chcon invocation::            Change SELinux context of file
+* runcon invocation::           Run a command in specified SELinux context
+
+
+File: coreutils.info,  Node: chcon invocation,  Next: runcon invocation,  Up: SELinux context
+
+22.1 ‘chcon’: Change SELinux context of file
+============================================
+
+‘chcon’ changes the SELinux security context of the selected files.
+Synopses:
+
+     chcon [OPTION]... CONTEXT FILE...
+     chcon [OPTION]... [-u USER] [-r ROLE] [-l RANGE] [-t TYPE] FILE...
+     chcon [OPTION]... --reference=RFILE FILE...
+
+   Change the SELinux security context of each FILE to CONTEXT.  With
+‘--reference’, change the security context of each FILE to that of
+RFILE.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘--dereference’
+     Do not affect symbolic links but what they refer to; this is the
+     default.
+
+‘-h’
+‘--no-dereference’
+     Affect the symbolic links themselves instead of any referenced
+     file.
+
+‘--reference=RFILE’
+     Use RFILE’s security context rather than specifying a CONTEXT
+     value.
+
+‘-R’
+‘--recursive’
+     Operate on files and directories recursively.
+
+‘--preserve-root’
+     Refuse to operate recursively on the root directory, ‘/’, when used
+     together with the ‘--recursive’ option.  *Note Treating /
+     specially::.
+
+‘--no-preserve-root’
+     Do not treat the root directory, ‘/’, specially when operating
+     recursively; this is the default.  *Note Treating / specially::.
+
+‘-H’
+     If ‘--recursive’ (‘-R’) is specified and a command line argument is
+     a symbolic link to a directory, traverse it.  *Note Traversing
+     symlinks::.
+
+‘-L’
+     In a recursive traversal, traverse every symbolic link to a
+     directory that is encountered.  *Note Traversing symlinks::.
+
+‘-P’
+     Do not traverse any symbolic links.  This is the default if none of
+     ‘-H’, ‘-L’, or ‘-P’ is specified.  *Note Traversing symlinks::.
+
+‘-v’
+‘--verbose’
+     Output a diagnostic for every file processed.
+
+‘-u USER’
+‘--user=USER’
+     Set user USER in the target security context.
+
+‘-r ROLE’
+‘--role=ROLE’
+     Set role ROLE in the target security context.
+
+‘-t TYPE’
+‘--type=TYPE’
+     Set type TYPE in the target security context.
+
+‘-l RANGE’
+‘--range=RANGE’
+     Set range RANGE in the target security context.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: runcon invocation,  Prev: chcon invocation,  Up: SELinux context
+
+22.2 ‘runcon’: Run a command in specified SELinux context
+=========================================================
+
+‘runcon’ runs file in specified SELinux security context.
+
+   Synopses:
+     runcon CONTEXT COMMAND [ARGS]
+     runcon [ -c ] [-u USER] [-r ROLE] [-t TYPE] [-l RANGE] COMMAND [ARGS]
+
+   Run COMMAND with completely-specified CONTEXT, or with current or
+transitioned security context modified by one or more of LEVEL, ROLE,
+TYPE and USER.
+
+   If none of ‘-c’, ‘-t’, ‘-u’, ‘-r’, or ‘-l’ is specified, the first
+argument is used as the complete context.  Any additional arguments
+after COMMAND are interpreted as arguments to the command.
+
+   With neither CONTEXT nor COMMAND, print the current security context.
+
+   Note also the ‘setpriv’ command which can be used to set the
+NO_NEW_PRIVS bit using ‘setpriv --no-new-privs runcon ...’, thus
+disallowing usage of a security context with more privileges than the
+process would normally have.
+
+   ‘runcon’ accepts the following options.  Also see *note Common
+options::.
+
+‘-c’
+‘--compute’
+     Compute process transition context before modifying.
+
+‘-u USER’
+‘--user=USER’
+     Set user USER in the target security context.
+
+‘-r ROLE’
+‘--role=ROLE’
+     Set role ROLE in the target security context.
+
+‘-t TYPE’
+‘--type=TYPE’
+     Set type TYPE in the target security context.
+
+‘-l RANGE’
+‘--range=RANGE’
+     Set range RANGE in the target security context.
+
+   Exit status:
+
+     125 if ‘runcon’ itself fails
+     126 if COMMAND is found but cannot be invoked
+     127 if COMMAND cannot be found
+     the exit status of COMMAND otherwise
+
+
+File: coreutils.info,  Node: Modified command invocation,  Next: Process control,  Prev: SELinux context,  Up: Top
+
+23 Modified command invocation
+******************************
+
+This section describes commands that run other commands in some context
+different than the current one: a modified environment, as a different
+user, etc.
+
+* Menu:
+
+* chroot invocation::           Modify the root directory.
+* env invocation::              Modify environment variables.
+* nice invocation::             Modify niceness.
+* nohup invocation::            Immunize to hangups.
+* stdbuf invocation::           Modify buffering of standard streams.
+* timeout invocation::          Run with time limit.
+
+
+File: coreutils.info,  Node: chroot invocation,  Next: env invocation,  Up: Modified command invocation
+
+23.1 ‘chroot’: Run a command with a different root directory
+============================================================
+
+‘chroot’ runs a command with a specified root directory.  On many
+systems, only the super-user can do this.(1).  Synopses:
+
+     chroot OPTION NEWROOT [COMMAND [ARGS]...]
+     chroot OPTION
+
+   Ordinarily, file names are looked up starting at the root of the
+directory structure, i.e., ‘/’.  ‘chroot’ changes the root to the
+directory NEWROOT (which must exist), then changes the working directory
+to ‘/’, and finally runs COMMAND with optional ARGS.  If COMMAND is not
+specified, the default is the value of the ‘SHELL’ environment variable
+or ‘/bin/sh’ if not set, invoked with the ‘-i’ option.  COMMAND must not
+be a special built-in utility (*note Special built-in utilities::).
+
+   The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands.
+
+‘--groups=GROUPS’
+     Use this option to override the supplementary GROUPS to be used by
+     the new process.  The items in the list (names or numeric IDs) must
+     be separated by commas.  Use ‘--groups=''’ to disable the
+     supplementary group look-up implicit in the ‘--userspec’ option.
+
+‘--userspec=USER[:GROUP]’
+     By default, COMMAND is run with the same credentials as the
+     invoking process.  Use this option to run it as a different USER
+     and/or with a different primary GROUP.  If a USER is specified then
+     the supplementary groups are set according to the system defined
+     list for that user, unless overridden with the ‘--groups’ option.
+
+‘--skip-chdir’
+     Use this option to not change the working directory to ‘/’ after
+     changing the root directory to NEWROOT, i.e., inside the chroot.
+     This option is only permitted when NEWROOT is the old ‘/’
+     directory, and therefore is mostly useful together with the
+     ‘--groups’ and ‘--userspec’ options to retain the previous working
+     directory.
+
+   The user and group name look-up performed by the ‘--userspec’ and
+‘--groups’ options, is done both outside and inside the chroot, with
+successful look-ups inside the chroot taking precedence.  If the
+specified user or group items are intended to represent a numeric ID,
+then a name to ID resolving step is avoided by specifying a leading ‘+’.
+*Note Disambiguating names and IDs::.
+
+   Here are a few tips to help avoid common problems in using chroot.
+To start with a simple example, make COMMAND refer to a statically
+linked binary.  If you were to use a dynamically linked executable, then
+you’d have to arrange to have the shared libraries in the right place
+under your new root directory.
+
+   For example, if you create a statically linked ‘ls’ executable, and
+put it in ‘/tmp/empty’, you can run this command as root:
+
+     $ chroot /tmp/empty /ls -Rl /
+
+   Then you’ll see output like this:
+
+     /:
+     total 1023
+     -rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls
+
+   If you want to use a dynamically linked executable, say ‘bash’, then
+first run ‘ldd bash’ to see what shared objects it needs.  Then, in
+addition to copying the actual binary, also copy the listed files to the
+required positions under your intended new root directory.  Finally, if
+the executable requires any other files (e.g., data, state, device
+files), copy them into place, too.
+
+   ‘chroot’ is installed only on systems that have the ‘chroot’
+function, so portable scripts should not rely on its existence.
+
+   Exit status:
+
+     125 if ‘chroot’ itself fails
+     126 if COMMAND is found but cannot be invoked
+     127 if COMMAND cannot be found
+     the exit status of COMMAND otherwise
+
+   ---------- Footnotes ----------
+
+   (1) However, some systems (e.g., FreeBSD) can be configured to allow
+certain regular users to use the ‘chroot’ system call, and hence to run
+this program.  Also, on Cygwin, anyone can run the ‘chroot’ command,
+because the underlying function is non-privileged due to lack of support
+in MS-Windows.  Furthermore, the ‘chroot’ command avoids the ‘chroot’
+system call when NEWROOT is identical to the old ‘/’ directory for
+consistency with systems where this is allowed for non-privileged users.
+
+
+File: coreutils.info,  Node: env invocation,  Next: nice invocation,  Prev: chroot invocation,  Up: Modified command invocation
+
+23.2 ‘env’: Run a command in a modified environment
+===================================================
+
+‘env’ runs a command with a modified environment.  Synopses:
+
+     env [OPTION]... [NAME=VALUE]... [COMMAND [ARGS]...]
+     env -[v]S'[OPTION]... [NAME=VALUE]... [COMMAND [ARGS]...]'
+     env
+
+   ‘env’ is commonly used on first line of scripts (shebang line):
+     #!/usr/bin/env COMMAND
+     #!/usr/bin/env -[v]S[OPTION]... [NAME=VALUE]... COMMAND [ARGS]...
+
+   Operands of the form ‘VARIABLE=VALUE’ set the environment variable
+VARIABLE to value VALUE.  VALUE may be empty (‘VARIABLE=’).  Setting a
+variable to an empty value is different from unsetting it.  These
+operands are evaluated left-to-right, so if two operands mention the
+same variable the earlier is ignored.
+
+   Environment variable names can be empty, and can contain any
+characters other than ‘=’ and ASCII NUL. However, it is wise to limit
+yourself to names that consist solely of underscores, digits, and ASCII
+letters, and that begin with a non-digit, as applications like the shell
+do not work well with other names.
+
+   The first operand that does not contain the character ‘=’ specifies
+the program to invoke; it is searched for according to the ‘PATH’
+environment variable.  Any remaining arguments are passed as arguments
+to that program.  The program should not be a special built-in utility
+(*note Special built-in utilities::).
+
+   Modifications to ‘PATH’ take effect prior to searching for COMMAND.
+Use caution when reducing ‘PATH’; behavior is not portable when ‘PATH’
+is undefined or omits key directories such as ‘/bin’.
+
+   In the rare case that a utility contains a ‘=’ in the name, the only
+way to disambiguate it from a variable assignment is to use an
+intermediate command for COMMAND, and pass the problematic program name
+via ARGS.  For example, if ‘./prog=’ is an executable in the current
+‘PATH’:
+
+     env prog= true # runs 'true', with prog= in environment
+     env ./prog= true # runs 'true', with ./prog= in environment
+     env -- prog= true # runs 'true', with prog= in environment
+     env sh -c '\prog= true' # runs 'prog=' with argument 'true'
+     env sh -c 'exec "$@"' sh prog= true # also runs 'prog='
+
+   If no command name is specified following the environment
+specifications, the resulting environment is printed.  This is like
+specifying the ‘printenv’ program.
+
+   For some examples, suppose the environment passed to ‘env’ contains
+‘LOGNAME=rms’, ‘EDITOR=emacs’, and ‘PATH=.:/gnubin:/hacks’:
+
+   • Output the current environment.
+          $ env | LC_ALL=C sort
+          EDITOR=emacs
+          LOGNAME=rms
+          PATH=.:/gnubin:/hacks
+
+   • Run ‘foo’ with a reduced environment, preserving only the original
+     ‘PATH’ to avoid problems in locating ‘foo’.
+          env - PATH="$PATH" foo
+
+   • Run ‘foo’ with the environment containing ‘LOGNAME=rms’,
+     ‘EDITOR=emacs’, and ‘PATH=.:/gnubin:/hacks’, and guarantees that
+     ‘foo’ was found in the file system rather than as a shell built-in.
+          env foo
+
+   • Run ‘nemacs’ with the environment containing ‘LOGNAME=foo’,
+     ‘EDITOR=emacs’, ‘PATH=.:/gnubin:/hacks’, and ‘DISPLAY=gnu:0’.
+          env DISPLAY=gnu:0 LOGNAME=foo nemacs
+
+   • Attempt to run the program ‘/energy/--’ (as that is the only
+     possible path search result); if the command exists, the
+     environment will contain ‘LOGNAME=rms’ and ‘PATH=/energy’, and the
+     arguments will be ‘e=mc2’, ‘bar’, and ‘baz’.
+          env -u EDITOR PATH=/energy -- e=mc2 bar baz
+
+23.2.1 General options
+----------------------
+
+The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands.
+
+‘-0’
+‘--null’
+     Output a zero byte (ASCII NUL) at the end of each line, rather than
+     a newline.  This option enables other programs to parse the output
+     even when that output would contain data with embedded newlines.
+
+‘-u NAME’
+‘--unset=NAME’
+     Remove variable NAME from the environment, if it was in the
+     environment.
+
+‘-’
+‘-i’
+‘--ignore-environment’
+     Start with an empty environment, ignoring the inherited
+     environment.
+
+‘-C DIR’
+‘--chdir=DIR’
+     Change the working directory to DIR before invoking COMMAND.  This
+     differs from the shell built-in ‘cd’ in that it starts COMMAND as a
+     subprocess rather than altering the shell’s own working directory;
+     this allows it to be chained with other commands that run commands
+     in a different context.  For example:
+
+          # Run 'true' with /chroot as its root directory and /srv as its working
+          # directory.
+          chroot /chroot env --chdir=/srv true
+          # Run 'true' with /build as its working directory, FOO=bar in its
+          # environment, and a time limit of five seconds.
+          env --chdir=/build FOO=bar timeout 5 true
+
+‘--default-signal[=SIG]’
+     Unblock and reset signal SIG to its default signal handler.
+     Without SIG all known signals are unblocked and reset to their
+     defaults.  Multiple signals can be comma-separated.  An empty SIG
+     argument is a no-op.  The following command runs ‘seq’ with SIGINT
+     and SIGPIPE set to their default (which is to terminate the
+     program):
+
+          env --default-signal=PIPE,INT seq 1000 | head -n1
+
+     In the following example, we see how this is not possible to do
+     with traditional shells.  Here the first trap command sets SIGPIPE
+     to ignore.  The second trap command ostensibly sets it back to its
+     default, but POSIX mandates that the shell must not change
+     inherited state of the signal – so it is a no-op.
+
+          trap '' PIPE && sh -c 'trap - PIPE ; seq inf | head -n1'
+
+     Using ‘--default-signal=PIPE’ we can ensure the signal handling is
+     set to its default behavior:
+
+          trap '' PIPE && sh -c 'env --default-signal=PIPE seq inf | head -n1'
+
+‘--ignore-signal[=SIG]’
+     Ignore signal SIG when running a program.  Without SIG all known
+     signals are set to ignore.  Multiple signals can be
+     comma-separated.  An empty SIG argument is a no-op.  The following
+     command runs ‘seq’ with SIGINT set to be ignored – pressing
+     ‘Ctrl-C’ will not terminate it:
+
+          env --ignore-signal=INT seq inf > /dev/null
+
+     ‘SIGCHLD’ is special, in that ‘--ignore-signal=CHLD’ might have no
+     effect (POSIX says it’s unspecified).
+
+     Most operating systems do not allow ignoring ‘SIGKILL’, ‘SIGSTOP’
+     (and possibly other signals).  Attempting to ignore these signals
+     will fail.
+
+     Multiple (and contradictory) ‘--default-signal=SIG’ and
+     ‘--ignore-signal=SIG’ options are processed left-to-right, with the
+     latter taking precedence.  In the following example, ‘SIGPIPE’ is
+     set to default while ‘SIGINT’ is ignored:
+
+          env --default-signal=INT,PIPE --ignore-signal=INT
+
+‘--block-signal[=SIG]’
+     Block signal(s) SIG from being delivered.  Without SIG all known
+     signals are set to blocked.  Multiple signals can be
+     comma-separated.  An empty SIG argument is a no-op.
+
+‘--list-signal-handling’
+     List blocked or ignored signals to standard error, before executing
+     a command.
+
+‘-v’
+‘--debug’
+     Show verbose information for each processing step.
+
+          $ env -v -uTERM A=B uname -s
+          unset:    TERM
+          setenv:   A=B
+          executing: uname
+             arg[0]= 'uname'
+             arg[1]= '-s'
+          Linux
+
+     When combined with ‘-S’ it is recommended to list ‘-v’ first, e.g.
+     ‘env -vS'string'’.
+
+‘-S STRING’
+‘--split-string=STRING’
+     process and split STRING into separate arguments used to pass
+     multiple arguments on shebang lines.  ‘env’ supports FreeBSD’s
+     syntax of several escape sequences and environment variable
+     expansions.  See below for details and examples.
+
+   Exit status:
+
+     0   if no COMMAND is specified and the environment is output
+     125 if ‘env’ itself fails
+     126 if COMMAND is found but cannot be invoked
+     127 if COMMAND cannot be found
+     the exit status of COMMAND otherwise
+
+23.2.2 ‘-S’/‘--split-string’ usage in scripts
+---------------------------------------------
+
+The ‘-S’/‘--split-string’ option enables use of multiple arguments on
+the first line of scripts (the shebang line, ‘#!’).
+
+   When a script’s interpreter is in a known location, scripts typically
+contain the absolute file name in their first line:
+
+Shell script:         #!/bin/sh
+                      echo hello
+                 
+Perl script:          #!/usr/bin/perl
+                      print "hello\n";
+                 
+Python script:        #!/usr/bin/python3
+                      print("hello")
+                 
+
+   When a script’s interpreter is in a non-standard location in the
+‘PATH’ environment variable, it is recommended to use ‘env’ on the first
+line of the script to find the executable and run it:
+
+Shell script:         #!/usr/bin/env bash
+                      echo hello
+                 
+Perl script:          #!/usr/bin/env perl
+                      print "hello\n";
+                 
+Python script:        #!/usr/bin/env python3
+                      print("hello")
+                 
+
+   Most operating systems (e.g.  GNU/Linux, BSDs) treat all text after
+the first space as a single argument.  When using ‘env’ in a script it
+is thus not possible to specify multiple arguments.
+
+   In the following example:
+     #!/usr/bin/env perl -T -w
+     print "hello\n";
+
+   The operating system treats ‘perl -T -w’ as one argument (the
+program’s name), and executing the script fails with:
+
+     /usr/bin/env: 'perl -T -w': No such file or directory
+
+   The ‘-S’ option instructs ‘env’ to split the single string into
+multiple arguments.  The following example works as expected:
+
+     $ cat hello.pl
+     #!/usr/bin/env -S perl -T -w
+     print "hello\n";
+
+     $ chmod a+x hello.pl
+     $ ./hello.pl
+     hello
+
+   And is equivalent to running ‘perl -T -w hello.pl’ on the command
+line prompt.
+
+Testing and troubleshooting
+...........................
+
+To test ‘env -S’ on the command line, use single quotes for the ‘-S’
+string to emulate a single parameter.  Single quotes are not needed when
+using ‘env -S’ in a shebang line on the first line of a script (the
+operating system already treats it as one argument).
+
+   The following command is equivalent to the ‘hello.pl’ script above:
+
+     $ env -S'perl -T -w' hello.pl
+
+   To troubleshoot ‘-S’ usage add the ‘-v’ as the first argument (before
+‘-S’).
+
+   Using ‘-vS’ on a shebang line in a script:
+
+     $ cat hello-debug.pl
+     #!/usr/bin/env -vS perl -T -w
+     print "hello\n";
+
+     $ chmod a+x hello-debug.pl
+     $ ./hello-debug.pl
+     split -S:  'perl -T -w'
+      into:    'perl'
+          &    '-T'
+          &    '-w'
+     executing: perl
+        arg[0]= 'perl'
+        arg[1]= '-T'
+        arg[2]= '-w'
+        arg[3]= './hello-debug.pl'
+     hello
+
+   Using ‘-vS’ on the command line prompt (adding single quotes):
+
+     $ env -vS'perl -T -w' hello-debug.pl
+     split -S:  'perl -T -w'
+      into:    'perl'
+          &    '-T'
+          &    '-w'
+     executing: perl
+        arg[0]= 'perl'
+        arg[1]= '-T'
+        arg[2]= '-w'
+        arg[3]= 'hello-debug.pl'
+     hello
+
+23.2.3 ‘-S’/‘--split-string’ syntax
+-----------------------------------
+
+Splitting arguments by whitespace
+.................................
+
+Running ‘env -Sstring’ splits the STRING into arguments based on
+unquoted spaces or tab characters.  (Newlines, carriage returns,
+vertical tabs and form feeds are treated like spaces and tabs.)
+
+   In the following contrived example the ‘awk’ variable ‘OFS’ will be
+‘<space>xyz<space>’ as these spaces are inside double quotes.  The other
+space characters are used as argument separators:
+
+     $ cat one.awk
+     #!/usr/bin/env -S awk -v OFS=" xyz " -f
+     BEGIN {print 1,2,3}
+
+     $ chmod a+x one.awk
+     $ ./one.awk
+     1 xyz 2 xyz 3
+
+   When using ‘-S’ on the command line prompt, remember to add single
+quotes around the entire string:
+
+     $ env -S'awk -v OFS=" xyz " -f' one.awk
+     1 xyz 2 xyz 3
+
+Escape sequences
+................
+
+‘env’ supports several escape sequences.  These sequences are processed
+when unquoted or inside double quotes (unless otherwise noted).  Single
+quotes disable escape sequences except ‘\'’ and ‘\\’.
+
+‘\c’    Ignore the remaining characters in the string.  Cannot be used
+        inside double quotes.
+        
+‘\f’    form-feed character (ASCII 0x0C)
+        
+‘\n’    new-line character (ASCII 0x0A)
+        
+‘\r’    carriage-return character (ASCII 0x0D)
+        
+‘\t’    tab character (ASCII 0x09)
+        
+‘\v’    vertical tab character (ASCII 0x0B)
+        
+‘\#’    A hash ‘#’ character.  Used when a ‘#’ character is needed as
+        the first character of an argument (see ’comments’ section
+        below).
+        
+‘\$’    A dollar-sign character ‘$’.  Unescaped ‘$’ characters are used
+        to expand environment variables (see ’variables’ section
+        below).
+        
+‘\_’    Inside double-quotes, replaced with a single space character.
+        Outside quotes, treated as an argument separator.  ‘\_’ can be
+        used to avoid space characters in a shebang line (see examples
+        below).
+        
+‘\"’    A double-quote character.
+        
+‘\'’    A single-quote character.  This escape sequence works inside
+        single-quoted strings.
+        
+‘\\’    A backslash character.  This escape sequence works inside
+        single-quoted strings.
+        
+
+   The following ‘awk’ script will use tab character as input and output
+field separator (instead of spaces and tabs):
+
+     $ cat tabs.awk
+     #!/usr/bin/env -S awk -v FS="\t" -v OFS="\t" -f
+     ...
+
+Comments
+........
+
+The escape sequence ‘\c’ (used outside single/double quotes) causes
+‘env’ to ignore the rest of the string.
+
+   The ‘#’ character causes ‘env’ to ignore the rest of the string when
+it appears as the first character of an argument.  Use ‘\#’ to reverse
+this behavior.
+
+     $ env -S'printf %s\n A B C'
+     A
+     B
+     C
+
+     $ env -S'printf %s\n A# B C'
+     A#
+     B
+     C
+
+     $ env -S'printf %s\n A #B C'
+     A
+
+     $ env -S'printf %s\n A \#B C'
+     A
+     #B
+     C
+
+     $ env -S'printf %s\n A\cB C'
+     A
+
+   NOTE: The above examples use single quotes as they are executed on
+the command-line.
+
+Environment variable expansion
+..............................
+
+The pattern ‘${VARNAME}’ is used to substitute a value from the
+environment variable.  The pattern must include the curly braces
+(‘{’,‘}’).  Without them ‘env’ will reject the string.  Special shell
+variables (such as ‘$@’, ‘$*’, ‘$$’) are not supported.
+
+   If the environment variable is empty or not set, the pattern will be
+replaced by an empty string.  The value of ‘${VARNAME}’ will be that of
+the executed ‘env’, before any modifications using
+‘-i’/‘--ignore-environment’/‘-u’/‘--unset’ or setting new values using
+‘VAR=VALUE’.
+
+   The following python script prepends ‘/opt/custom/modules’ to the
+python module search path environment variable (‘PYTHONPATH’):
+
+     $ cat custom.py
+     #!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:${PYTHONPATH} python
+     print "hello"
+     ...
+
+   The expansion of ‘${PYTHONPATH}’ is performed by ‘env’, not by a
+shell.  If the curly braces are omitted, ‘env’ will fail:
+
+     $ cat custom.py
+     #!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$PYTHONPATH python
+     print "hello"
+     ...
+
+     $ chmod a+x custom.py
+     $ custom.py
+     /usr/bin/env: only ${VARNAME} expansion is supported, error at: $PYTHONPATH python
+
+   Environment variable expansion happens before clearing the
+environment (with ‘-i’) or unsetting specific variables (with ‘-u’):
+
+     $ env -S'-i OLDUSER=${USER} env'
+     OLDUSER=gordon
+
+   Use ‘-v’ to diagnose the operations step-by-step:
+
+     $ env -vS'-i OLDUSER=${USER} env'
+     expanding ${USER} into 'gordon'
+     split -S:  '-i OLDUSER=${USER} env'
+      into:    '-i'
+          &    'OLDUSER=gordon'
+          &    'env'
+     cleaning environ
+     setenv:   OLDUSER=gordon
+     executing: env
+        arg[0]= 'env'
+     OLDUSER=gordon
+
+
+File: coreutils.info,  Node: nice invocation,  Next: nohup invocation,  Prev: env invocation,  Up: Modified command invocation
+
+23.3 ‘nice’: Run a command with modified niceness
+=================================================
+
+‘nice’ prints a process’s “niceness”, or runs a command with modified
+niceness.  “niceness” affects how favorably the process is scheduled in
+the system.  Synopsis:
+
+     nice [OPTION]... [COMMAND [ARG]...]
+
+   If no arguments are given, ‘nice’ prints the current niceness.
+Otherwise, ‘nice’ runs the given COMMAND with its niceness adjusted.  By
+default, its niceness is incremented by 10.
+
+   Niceness values range at least from −20 (process has high priority
+and gets more resources, thus slowing down other processes) through 19
+(process has lower priority and runs slowly itself, but has less impact
+on the speed of other running processes).  Some systems may have a wider
+range of niceness values; conversely, other systems may enforce more
+restrictive limits.  An attempt to set the niceness outside the
+supported range is treated as an attempt to use the minimum or maximum
+supported value.
+
+   A niceness should not be confused with a scheduling priority, which
+lets applications determine the order in which threads are scheduled to
+run.  Unlike a priority, a niceness is merely advice to the scheduler,
+which the scheduler is free to ignore.  Also, as a point of terminology,
+POSIX defines the behavior of ‘nice’ in terms of a “nice value”, which
+is the non-negative difference between a niceness and the minimum
+niceness.  Though ‘nice’ conforms to POSIX, its documentation and
+diagnostics use the term “niceness” for compatibility with historical
+practice.
+
+   COMMAND must not be a special built-in utility (*note Special
+built-in utilities::).
+
+   Due to shell aliases and built-in ‘nice’ functions, using an
+unadorned ‘nice’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+nice ...’) to avoid interference from the shell.
+
+   Note to change the “niceness” of an existing process, one needs to
+use the ‘renice’ command.
+
+   The program accepts the following option.  Also see *note Common
+options::.  Options must precede operands.
+
+‘-n ADJUSTMENT’
+‘--adjustment=ADJUSTMENT’
+     Add ADJUSTMENT instead of 10 to the command’s niceness.  If
+     ADJUSTMENT is negative and you lack appropriate privileges, ‘nice’
+     issues a warning but otherwise acts as if you specified a zero
+     adjustment.
+
+     For compatibility ‘nice’ also supports an obsolete option syntax
+     ‘-ADJUSTMENT’.  New scripts should use ‘-n ADJUSTMENT’ instead.
+
+   ‘nice’ is installed only on systems that have the POSIX ‘setpriority’
+function, so portable scripts should not rely on its existence on
+non-POSIX platforms.
+
+   Exit status:
+
+     0   if no COMMAND is specified and the niceness is output
+     125 if ‘nice’ itself fails
+     126 if COMMAND is found but cannot be invoked
+     127 if COMMAND cannot be found
+     the exit status of COMMAND otherwise
+
+   It is sometimes useful to run a non-interactive program with reduced
+niceness.
+
+     $ nice factor 4611686018427387903
+
+   Since ‘nice’ prints the current niceness, you can invoke it through
+itself to demonstrate how it works.
+
+   The default behavior is to increase the niceness by ‘10’:
+
+     $ nice
+     0
+     $ nice nice
+     10
+     $ nice -n 10 nice
+     10
+
+   The ADJUSTMENT is relative to the current niceness.  In the next
+example, the first ‘nice’ invocation runs the second one with niceness
+10, and it in turn runs the final one with a niceness that is 3 more:
+
+     $ nice nice -n 3 nice
+     13
+
+   Specifying a niceness larger than the supported range is the same as
+specifying the maximum supported value:
+
+     $ nice -n 10000000000 nice
+     19
+
+   Only a privileged user may run a process with lower niceness:
+
+     $ nice -n -1 nice
+     nice: cannot set niceness: Permission denied
+     0
+     $ sudo nice -n -1 nice
+     -1
+
+
+File: coreutils.info,  Node: nohup invocation,  Next: stdbuf invocation,  Prev: nice invocation,  Up: Modified command invocation
+
+23.4 ‘nohup’: Run a command immune to hangups
+=============================================
+
+‘nohup’ runs the given COMMAND with hangup signals ignored, so that the
+command can continue running in the background after you log out.
+Synopsis:
+
+     nohup COMMAND [ARG]...
+
+   If standard input is a terminal, redirect it so that terminal
+sessions do not mistakenly consider the terminal to be used by the
+command.  Make the substitute file descriptor unreadable, so that
+commands that mistakenly attempt to read from standard input can report
+an error.  This redirection is a GNU extension; programs intended to be
+portable to non-GNU hosts can use ‘nohup COMMAND [ARG]... 0>/dev/null’
+instead.
+
+   If standard output is a terminal, the command’s standard output is
+appended to the file ‘nohup.out’; if that cannot be written to, it is
+appended to the file ‘$HOME/nohup.out’; and if that cannot be written
+to, the command is not run.  Any ‘nohup.out’ or ‘$HOME/nohup.out’ file
+created by ‘nohup’ is made readable and writable only to the user,
+regardless of the current umask settings.
+
+   If standard error is a terminal, it is normally redirected to the
+same file descriptor as the (possibly-redirected) standard output.
+However, if standard output is closed, standard error terminal output is
+instead appended to the file ‘nohup.out’ or ‘$HOME/nohup.out’ as above.
+
+   To capture the command’s output to a file other than ‘nohup.out’ you
+can redirect it.  For example, to capture the output of ‘make’:
+
+     nohup make > make.log
+
+   ‘nohup’ does not automatically put the command it runs in the
+background; you must do that explicitly, by ending the command line with
+an ‘&’.  Also, ‘nohup’ does not alter the niceness of COMMAND; use
+‘nice’ for that, e.g., ‘nohup nice COMMAND’.
+
+   COMMAND must not be a special built-in utility (*note Special
+built-in utilities::).
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.  Options must precede operands.
+
+   Exit status:
+
+     125 if ‘nohup’ itself fails, and ‘POSIXLY_CORRECT’ is not set
+     126 if COMMAND is found but cannot be invoked
+     127 if COMMAND cannot be found
+     the exit status of COMMAND otherwise
+
+   If ‘POSIXLY_CORRECT’ is set, internal failures give status 127
+instead of 125.
+
+
+File: coreutils.info,  Node: stdbuf invocation,  Next: timeout invocation,  Prev: nohup invocation,  Up: Modified command invocation
+
+23.5 ‘stdbuf’: Run a command with modified I/O stream buffering
+===============================================================
+
+‘stdbuf’ allows one to modify the buffering operations of the three
+standard I/O streams associated with a program.  Synopsis:
+
+     stdbuf OPTION... COMMAND
+
+   COMMAND must start with the name of a program that
+  1. uses the ISO C ‘FILE’ streams for input/output (note the programs
+     ‘dd’ and ‘cat’ don’t do that),
+
+  2. does not adjust the buffering of its standard streams (note the
+     program ‘tee’ is not in this category).
+
+   Any additional ARGs are passed as additional arguments to the
+COMMAND.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-i MODE’
+‘--input=MODE’
+     Adjust the standard input stream buffering.
+
+‘-o MODE’
+‘--output=MODE’
+     Adjust the standard output stream buffering.
+
+‘-e MODE’
+‘--error=MODE’
+     Adjust the standard error stream buffering.
+
+   The MODE can be specified as follows:
+
+‘L’
+     Set the stream to line buffered mode.  In this mode data is
+     coalesced until a newline is output or input is read from any
+     stream attached to a terminal device.  This option is invalid with
+     standard input.
+
+‘0’
+     Disable buffering of the selected stream.  In this mode, data is
+     output immediately and only the amount of data requested is read
+     from input.  Note the difference in function for input and output.
+     Disabling buffering for input will not influence the responsiveness
+     or blocking behavior of the stream input functions.  For example
+     ‘fread’ will still block until ‘EOF’ or error, even if the
+     underlying ‘read’ returns less data than requested.
+
+‘SIZE’
+     Specify the size of the buffer to use in fully buffered mode.  SIZE
+     may be, or may be an integer optionally followed by, one of the
+     following multiplicative suffixes:
+          ‘KB’ =>           1000 (KiloBytes)
+          ‘K’  =>           1024 (KibiBytes)
+          ‘MB’ =>      1000*1000 (MegaBytes)
+          ‘M’  =>      1024*1024 (MebiBytes)
+          ‘GB’ => 1000*1000*1000 (GigaBytes)
+          ‘G’  => 1024*1024*1024 (GibiBytes)
+     and so on for ‘T’, ‘P’, ‘E’, ‘Z’, ‘Y’, ‘R’, and ‘Q’.  Binary
+     prefixes can be used, too: ‘KiB’=‘K’, ‘MiB’=‘M’, and so on.
+
+   ‘stdbuf’ is installed only on platforms that use the Executable and
+Linkable Format (ELF) and support the ‘constructor’ attribute, so
+portable scripts should not rely on its existence.
+
+   Exit status:
+
+     125 if ‘stdbuf’ itself fails
+     126 if COMMAND is found but cannot be invoked
+     127 if COMMAND cannot be found
+     the exit status of COMMAND otherwise
+
+
+File: coreutils.info,  Node: timeout invocation,  Prev: stdbuf invocation,  Up: Modified command invocation
+
+23.6 ‘timeout’: Run a command with a time limit
+===============================================
+
+‘timeout’ runs the given COMMAND and kills it if it is still running
+after the specified time interval.  Synopsis:
+
+     timeout [OPTION] DURATION COMMAND [ARG]...
+
+   COMMAND must not be a special built-in utility (*note Special
+built-in utilities::).
+
+   The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands.
+
+‘--preserve-status’
+     Return the exit status of the managed COMMAND on timeout, rather
+     than a specific exit status indicating a timeout.  This is useful
+     if the managed COMMAND supports running for an indeterminate amount
+     of time.
+
+‘--foreground’
+     Don’t create a separate background program group, so that the
+     managed COMMAND can use the foreground TTY normally.  This is
+     needed to support two situations when timing out commands, when not
+     invoking ‘timeout’ from an interactive shell.
+       1. COMMAND is interactive and needs to read from the terminal for
+          example
+       2. the user wants to support sending signals directly to COMMAND
+          from the terminal (like Ctrl-C for example)
+
+     Note in this mode of operation, any children of COMMAND will not be
+     timed out.  Also SIGCONT will not be sent to COMMAND, as it’s
+     generally not needed with foreground processes, and can cause
+     intermittent signal delivery issues with programs that are monitors
+     themselves (like GDB for example).
+
+‘-k DURATION’
+‘--kill-after=DURATION’
+     Ensure the monitored COMMAND is killed by also sending a ‘KILL’
+     signal.
+
+     The specified DURATION starts from the point in time when ‘timeout’
+     sends the initial signal to COMMAND, i.e., not from the beginning
+     when the COMMAND is started.
+
+     This option has no effect if either the main DURATION of the
+     ‘timeout’ command, or the DURATION specified to this option, is 0.
+
+     This option may be useful if the selected signal did not kill the
+     COMMAND, either because the signal was blocked or ignored, or if
+     the COMMAND takes too long (e.g.  for cleanup work) to terminate
+     itself within a certain amount of time.
+
+‘-s SIGNAL’
+‘--signal=SIGNAL’
+     Send this SIGNAL to COMMAND on timeout, rather than the default
+     ‘TERM’ signal.  SIGNAL may be a name like ‘HUP’ or a number.  *Note
+     Signal specifications::.
+
+‘-v’
+‘--verbose’
+     Diagnose to standard error, any signal sent upon timeout.
+
+   DURATION is a floating point number in either the current or the C
+locale (*note Floating point::) followed by an optional unit:
+     ‘s’ for seconds (the default)
+     ‘m’ for minutes
+     ‘h’ for hours
+     ‘d’ for days
+   A duration of 0 disables the associated timeout.  Note that the
+actual timeout duration is dependent on system conditions, which should
+be especially considered when specifying sub-second timeouts.
+
+   Exit status:
+
+     124 if COMMAND times out, and ‘--preserve-status’ is not specified
+     125 if ‘timeout’ itself fails
+     126 if COMMAND is found but cannot be invoked
+     127 if COMMAND cannot be found
+     137 if COMMAND or ‘timeout’ is sent the KILL(9) signal (128+9)
+     the exit status of COMMAND otherwise
+
+   In the case of the ‘KILL(9)’ signal, ‘timeout’ returns with exit
+status 137, regardless of whether that signal is sent to COMMAND or to
+‘timeout’ itself, i.e., these cases cannot be distinguished.  In the
+latter case, the COMMAND process may still be alive after ‘timeout’ has
+forcefully been terminated.
+
+   Examples:
+
+     # Send the default TERM signal after 20s to a short-living 'sleep 1'.
+     # As that terminates long before the given duration, 'timeout' returns
+     # with the same exit status as the command, 0 in this case.
+     timeout 20 sleep 1
+
+     # Send the INT signal after 5s to the 'sleep' command.  Returns after
+     # 5 seconds with exit status 124 to indicate the sending of the signal.
+     timeout -s INT 5 sleep 20
+
+     # Likewise, but the command ignoring the INT signal due to being started
+     # via 'env --ignore-signal'.  Thus, 'sleep' terminates regularly after
+     # the full 20 seconds, still 'timeout' returns with exit status 124.
+     timeout -s INT 5s env --ignore-signal=INT sleep 20
+
+     # Likewise, but sending the KILL signal 3 seconds after the initial
+     # INT signal.  Hence, 'sleep' is forcefully terminated after about
+     # 8 seconds (5+3), and 'timeout' returns with an exit status of 137.
+     timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20
+
+
+File: coreutils.info,  Node: Process control,  Next: Delaying,  Prev: Modified command invocation,  Up: Top
+
+24 Process control
+******************
+
+* Menu:
+
+* kill invocation::             Sending a signal to processes.
+
+
+File: coreutils.info,  Node: kill invocation,  Up: Process control
+
+24.1 ‘kill’: Send a signal to processes
+=======================================
+
+The ‘kill’ command sends a signal to processes, causing them to
+terminate or otherwise act upon receiving the signal in some way.
+Alternatively, it lists information about signals.  Synopses:
+
+     kill [-s SIGNAL | --signal SIGNAL | -SIGNAL] PID...
+     kill [-l | --list | -t | --table] [SIGNAL]...
+
+   Due to shell aliases and built-in ‘kill’ functions, using an
+unadorned ‘kill’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+kill ...’) to avoid interference from the shell.
+
+   The first form of the ‘kill’ command sends a signal to all PID
+arguments.  The default signal to send if none is specified is ‘TERM’.
+The special signal number ‘0’ does not denote a valid signal, but can be
+used to test whether the PID arguments specify processes to which a
+signal could be sent.
+
+   If PID is positive, the signal is sent to the process with the
+process ID PID.  If PID is zero, the signal is sent to all processes in
+the process group of the current process.  If PID is −1, the signal is
+sent to all processes for which the user has permission to send a
+signal.  If PID is less than −1, the signal is sent to all processes in
+the process group that equals the absolute value of PID.
+
+   If PID is not positive, a system-dependent set of system processes is
+excluded from the list of processes to which the signal is sent.
+
+   If a negative PID argument is desired as the first one, it should be
+preceded by ‘--’.  However, as a common extension to POSIX, ‘--’ is not
+required with ‘kill -SIGNAL -PID’.  The following commands are
+equivalent:
+
+     kill -15 -1
+     kill -TERM -1
+     kill -s TERM -- -1
+     kill -- -1
+
+   The first form of the ‘kill’ command succeeds if every PID argument
+specifies at least one process that the signal was sent to.
+
+   The second form of the ‘kill’ command lists signal information.
+Either the ‘-l’ or ‘--list’ option, or the ‘-t’ or ‘--table’ option must
+be specified.  Without any SIGNAL argument, all supported signals are
+listed.  The output of ‘-l’ or ‘--list’ is a list of the signal names,
+one per line; if SIGNAL is already a name, the signal number is printed
+instead.  The output of ‘-t’ or ‘--table’ is a table of signal numbers,
+names, and descriptions.  This form of the ‘kill’ command succeeds if
+all SIGNAL arguments are valid and if there is no output error.
+
+   The ‘kill’ command also supports the ‘--help’ and ‘--version’
+options.  *Note Common options::.
+
+   A SIGNAL may be a signal name like ‘HUP’, or a signal number like
+‘1’, or an exit status of a process terminated by the signal.  A signal
+name can be given in canonical form or prefixed by ‘SIG’.  The case of
+the letters is ignored, except for the ‘-SIGNAL’ option which must use
+upper case to avoid ambiguity with lower case option letters.  *Note
+Signal specifications::, for a list of supported signal names and
+numbers.
+
+
+File: coreutils.info,  Node: Delaying,  Next: Numeric operations,  Prev: Process control,  Up: Top
+
+25 Delaying
+***********
+
+* Menu:
+
+* sleep invocation::            Delay for a specified time.
+
+
+File: coreutils.info,  Node: sleep invocation,  Up: Delaying
+
+25.1 ‘sleep’: Delay for a specified time
+========================================
+
+‘sleep’ pauses for an amount of time specified by the sum of the values
+of the command line arguments.  Synopsis:
+
+     sleep NUMBER[smhd]...
+
+   Each argument is a non-negative number followed by an optional unit;
+the default is seconds.  The units are:
+
+‘s’
+     seconds
+‘m’
+     minutes
+‘h’
+     hours
+‘d’
+     days
+
+   Although portable POSIX scripts must give ‘sleep’ a single
+non-negative integer argument without a suffix, GNU ‘sleep’ also accepts
+two or more arguments, unit suffixes, and floating-point numbers in
+either the current or the C locale.  *Note Floating point::.
+
+   For instance, the following could be used to ‘sleep’ for 1 second,
+234 milli-, 567 micro- and 890 nanoseconds:
+
+     sleep 1234e-3 567.89e-6
+
+   Also one could sleep indefinitely like:
+
+     sleep inf
+
+   The only options are ‘--help’ and ‘--version’.  *Note Common
+options::.
+
+   Due to shell aliases and built-in ‘sleep’ functions, using an
+unadorned ‘sleep’ interactively or in a script may get you different
+functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
+sleep ...’) to avoid interference from the shell.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: Numeric operations,  Next: File permissions,  Prev: Delaying,  Up: Top
+
+26 Numeric operations
+*********************
+
+These programs do numerically-related operations.
+
+* Menu:
+
+* factor invocation::              Show factors of numbers.
+* numfmt invocation::              Reformat numbers.
+* seq invocation::                 Print sequences of numbers.
+
+
+File: coreutils.info,  Node: factor invocation,  Next: numfmt invocation,  Up: Numeric operations
+
+26.1 ‘factor’: Print prime factors
+==================================
+
+‘factor’ prints prime factors.  Synopsis:
+
+     factor [OPTION]... [NUMBER]...
+
+   If no NUMBER is specified on the command line, ‘factor’ reads numbers
+from standard input, delimited by newlines, tabs, or spaces.
+
+   The program accepts the following options.  Also see *note Common
+options::.
+
+‘-h’
+‘--exponents’
+     print factors in the form p^e, rather than repeating the prime ‘p’,
+     ‘e’ times.  If the exponent ‘e’ is 1, then it is omitted.
+
+          $ factor --exponents 3000
+          3000: 2^3 3 5^3
+
+   If the number to be factored is small (less than 2^{127} on typical
+machines), ‘factor’ uses a faster algorithm.  For example, on a
+circa-2017 Intel Xeon Silver 4116, factoring the product of the eighth
+and ninth Mersenne primes (approximately 2^{92}) takes about 4 ms of CPU
+time:
+
+     $ M8=$(echo 2^31-1 | bc)
+     $ M9=$(echo 2^61-1 | bc)
+     $ n=$(echo "$M8 * $M9" | bc)
+     $ bash -c "time factor $n"
+     4951760154835678088235319297: 2147483647 2305843009213693951
+
+     real	0m0.004s
+     user	0m0.004s
+     sys	0m0.000s
+
+   For larger numbers, ‘factor’ uses a slower algorithm.  On the same
+platform, factoring the eighth Fermat number 2^{256} + 1 takes about 14
+seconds, and the slower algorithm would have taken about 750 ms to
+factor 2^{127} - 3 instead of the 50 ms needed by the faster algorithm.
+
+   Factoring large numbers is, in general, hard.  The Pollard-Brent rho
+algorithm used by ‘factor’ is particularly effective for numbers with
+relatively small factors.  If you wish to factor large numbers which do
+not have small factors (for example, numbers which are the product of
+two large primes), other methods are far better.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: numfmt invocation,  Next: seq invocation,  Prev: factor invocation,  Up: Numeric operations
+
+26.2 ‘numfmt’: Reformat numbers
+===============================
+
+‘numfmt’ reads numbers in various representations and reformats them as
+requested.  The most common usage is converting numbers to/from _human_
+representation (e.g.  ‘4G’ ↦ ‘4,000,000,000’).
+
+     numfmt [OPTION]... [NUMBER]
+
+   ‘numfmt’ converts each NUMBER on the command-line according to the
+specified options (see below).  If no NUMBERs are given, it reads
+numbers from standard input.  ‘numfmt’ can optionally extract numbers
+from specific columns, maintaining proper line padding and alignment.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+   See ‘--invalid’ for additional information regarding exit status.
+
+26.2.1 General options
+----------------------
+
+The program accepts the following options.  Also see *note Common
+options::.
+
+‘--debug’
+     Print (to standard error) warning messages about possible erroneous
+     usage.
+
+‘-d D’
+‘--delimiter=D’
+     Use the character D as input field separator (default: whitespace).
+     _Note_: Using non-default delimiter turns off automatic padding.
+
+‘--field=FIELDS’
+     Convert the number in input field FIELDS (default: 1).  FIELDS
+     supports ‘cut’ style field ranges:
+
+          N    N'th field, counted from 1
+          N-   from N'th field, to end of line
+          N-M  from N'th to M'th field (inclusive)
+          -M   from first to M'th field (inclusive)
+          -    all fields
+
+‘--format=FORMAT’
+     Use printf-style floating FORMAT string.  The FORMAT string must
+     contain one ‘%f’ directive, optionally with ‘'’, ‘-’, ‘0’, width or
+     precision modifiers.  The ‘'’ modifier will enable ‘--grouping’,
+     the ‘-’ modifier will enable left-aligned ‘--padding’ and the width
+     modifier will enable right-aligned ‘--padding’.  The ‘0’ width
+     modifier (without the ‘-’ modifier) will generate leading zeros on
+     the number, up to the specified width.  A precision specification
+     like ‘%.1f’ will override the precision determined from the input
+     data or set due to ‘--to’ option auto scaling.
+
+‘--from=UNIT’
+     Auto-scales input numbers according to UNIT.  See UNITS below.  The
+     default is no scaling, meaning suffixes (e.g.  ‘M’, ‘G’) will
+     trigger an error.
+
+‘--from-unit=N’
+     Specify the input unit size (instead of the default 1).  Use this
+     option when the input numbers represent other units (e.g.  if the
+     input number ‘10’ represents 10 units of 512 bytes, use
+     ‘--from-unit=512’).  Suffixes are handled as with ‘--from=auto’.
+
+‘--grouping’
+     Group digits in output numbers according to the current locale’s
+     grouping rules (e.g _Thousands Separator_ character, commonly ‘.’
+     (dot) or ‘,’ comma).  This option has no effect in ‘POSIX/C’
+     locale.
+
+‘--header[=N]’
+     Print the first N (default: 1) lines without any conversion.
+
+‘--invalid=MODE’
+     The default action on input errors is to exit immediately with
+     status code 2.  ‘--invalid=‘abort’’ explicitly specifies this
+     default mode.  With a MODE of ‘fail’, print a warning for _each_
+     conversion error, and exit with status 2.  With a MODE of ‘warn’,
+     exit with status 0, even in the presence of conversion errors, and
+     with a MODE of ‘ignore’ do not even print diagnostics.
+
+‘--padding=N’
+     Pad the output numbers to N characters, by adding spaces.  If N is
+     a positive number, numbers will be right-aligned.  If N is a
+     negative number, numbers will be left-aligned.  By default, numbers
+     are automatically aligned based on the input line’s width (only
+     with the default delimiter).
+
+‘--round=METHOD’
+     When converting number representations, round the number according
+     to METHOD, which can be ‘up’, ‘down’, ‘from-zero’ (the default),
+     ‘towards-zero’, ‘nearest’.
+
+‘--suffix=SUFFIX’
+     Add ‘SUFFIX’ to the output numbers, and accept optional ‘SUFFIX’ in
+     input numbers.
+
+‘--to=UNIT’
+     Auto-scales output numbers according to UNIT.  See _Units_ below.
+     The default is no scaling, meaning all the digits of the number are
+     printed.
+
+‘--to-unit=N’
+     Specify the output unit size (instead of the default 1).  Use this
+     option when the output numbers represent other units (e.g.  to
+     represent ‘4,000,000’ bytes in blocks of 1KB, use ‘--to=si
+     --to-unit=1000’).  Suffixes are handled as with ‘--from=auto’.
+
+‘-z’
+‘--zero-terminated’
+     Delimit items with a zero byte rather than a newline (ASCII LF).
+     I.e., treat input as items separated by ASCII NUL and terminate
+     output items with ASCII NUL. This option can be useful in
+     conjunction with ‘perl -0’ or ‘find -print0’ and ‘xargs -0’ which
+     do the same in order to reliably handle arbitrary file names (even
+     those containing blanks or other special characters).  Note with
+     ‘-z’ the newline character is treated as a field separator.
+
+26.2.2 Possible UNITs:
+----------------------
+
+The following are the possible UNIT options with ‘--from=UNITS’ and
+‘--to=UNITS’:
+
+NONE
+     No scaling is performed.  For input numbers, no suffixes are
+     accepted, and any trailing characters following the number will
+     trigger an error.  For output numbers, all digits of the numbers
+     will be printed.
+
+SI
+     Auto-scale numbers according to the _International System of Units
+     (SI)_ standard.  For input numbers, accept one of the following
+     suffixes.  For output numbers, values larger than 1000 will be
+     rounded, and printed with one of the following suffixes:
+
+          ‘K’  =>  1000^1 = 10^3 (Kilo)
+          ‘M’  =>  1000^2 = 10^6 (Mega)
+          ‘G’  =>  1000^3 = 10^9 (Giga)
+          ‘T’  =>  1000^4 = 10^{12} (Tera)
+          ‘P’  =>  1000^5 = 10^{15} (Peta)
+          ‘E’  =>  1000^6 = 10^{18} (Exa)
+          ‘Z’  =>  1000^7 = 10^{21} (Zetta)
+          ‘Y’  =>  1000^8 = 10^{24} (Yotta)
+          ‘R’  =>  1000^9 = 10^{27} (Ronna)
+          ‘Q’  =>  1000^{10} = 10^{30} (Quetta)
+
+IEC
+     Auto-scale numbers according to the _International Electrotechnical
+     Commission (IEC)_ standard.  For input numbers, accept one of the
+     following suffixes.  For output numbers, values larger than 1024
+     will be rounded, and printed with one of the following suffixes:
+
+          ‘K’  =>  1024^1 = 2^{10} (Kibi)
+          ‘M’  =>  1024^2 = 2^{20} (Mebi)
+          ‘G’  =>  1024^3 = 2^{30} (Gibi)
+          ‘T’  =>  1024^4 = 2^{40} (Tebi)
+          ‘P’  =>  1024^5 = 2^{50} (Pebi)
+          ‘E’  =>  1024^6 = 2^{60} (Exbi)
+          ‘Z’  =>  1024^7 = 2^{70} (Zebi)
+          ‘Y’  =>  1024^8 = 2^{80} (Yobi)
+          ‘R’  =>  1024^9 = 2^{90} (Robi)
+          ‘Q’  =>  1024^{10} = 2^{100} (Quebi)
+
+     The ‘iec’ option uses a single letter suffix (e.g.  ‘G’), which is
+     not fully standard, as the _iec_ standard recommends a two-letter
+     symbol (e.g ‘Gi’) – but in practice, this method is common.
+     Compare with the ‘iec-i’ option.
+
+IEC-I
+     Auto-scale numbers according to the _International Electrotechnical
+     Commission (IEC)_ standard.  For input numbers, accept one of the
+     following suffixes.  For output numbers, values larger than 1024
+     will be rounded, and printed with one of the following suffixes:
+
+          ‘Ki’  =>  1024^1 = 2^{10} (Kibi)
+          ‘Mi’  =>  1024^2 = 2^{20} (Mebi)
+          ‘Gi’  =>  1024^3 = 2^{30} (Gibi)
+          ‘Ti’  =>  1024^4 = 2^{40} (Tebi)
+          ‘Pi’  =>  1024^5 = 2^{50} (Pebi)
+          ‘Ei’  =>  1024^6 = 2^{60} (Exbi)
+          ‘Zi’  =>  1024^7 = 2^{70} (Zebi)
+          ‘Yi’  =>  1024^8 = 2^{80} (Yobi)
+          ‘Ri’  =>  1024^9 = 2^{90} (Robi)
+          ‘Qi’  =>  1024^{10} = 2^{100} (Quebi)
+
+     The ‘iec-i’ option uses a two-letter suffix symbol (e.g.  ‘Gi’), as
+     the _iec_ standard recommends, but this is not always common in
+     practice.  Compare with the ‘iec’ option.
+
+AUTO
+     ‘auto’ can only be used with ‘--from’.  With this method, numbers
+     with single-letter suffixes like ‘K’ suffixes are interpreted as
+     _SI_ values, and numbers with two-letter suffixes like ‘Ki’ are
+     interpreted as _IEC_ values.
+
+26.2.3 Examples of using ‘numfmt’
+---------------------------------
+
+Converting a single number from/to _human_ representation:
+     $ numfmt --to=si 500000
+     500K
+
+     $ numfmt --to=iec 500000
+     489K
+
+     $ numfmt --to=iec-i 500000
+     489Ki
+
+     $ numfmt --from=si 1M
+     1000000
+
+     $ numfmt --from=iec 1M
+     1048576
+
+     # with '--from=auto', M=Mega, Mi=Mebi
+     $ numfmt --from=auto 1M
+     1000000
+     $ numfmt --from=auto 1Mi
+     1048576
+
+   Converting from ‘SI’ to ‘IEC’ scales (e.g.  when a drive’s capacity
+is advertised as ‘1TB’, while checking the drive’s capacity gives lower
+values):
+
+     $ numfmt --from=si --to=iec 1T
+     932G
+
+   With both input and output scales specified, the largest defined
+prefixes are supported:
+
+     $ numfmt --from=si --to=iec-i 2000R
+     1.6Qi
+
+   Converting a single field from an input file / piped input (these
+contrived examples are for demonstration purposes only, as both ‘ls’ and
+‘df’ support the ‘--human-readable’ option to output sizes in
+human-readable format):
+
+     # Third field (file size) will be shown in SI representation
+     $ ls -log | numfmt --field 3 --header --to=si | head -n4
+     -rw-r--r--  1     94K Aug 23  2011 ABOUT-NLS
+     -rw-r--r--  1    3.7K Jan  7 16:15 AUTHORS
+     -rw-r--r--  1     36K Jun  1  2011 COPYING
+     -rw-r--r--  1       0 Jan  7 15:15 ChangeLog
+
+     # Second field (size) will be shown in IEC representation
+     $ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
+     File system   1B-blocks        Used  Available Use% Mounted on
+     rootfs             132G   104741408   26554036  80% /
+     tmpfs              794M        7580     804960   1% /run/shm
+     /dev/sdb1          694G   651424756   46074696  94% /home
+
+   Output can be tweaked using ‘--padding’ or ‘--format’:
+
+     # Pad to 10 characters, right-aligned
+     $ du -s * | numfmt --to=si --padding=10
+           2.5K config.log
+            108 config.status
+           1.7K configure
+             20 configure.ac
+
+     # Pad to 10 characters, left-aligned
+     $ du -s * | numfmt --to=si --padding=-10
+     2.5K       config.log
+     108        config.status
+     1.7K       configure
+     20         configure.ac
+
+     # Pad to 10 characters, left-aligned, using 'format'
+     $ du -s * | numfmt --to=si --format="%10f"
+           2.5K config.log
+            108 config.status
+           1.7K configure
+             20 configure.ac
+
+     # Pad to 10 characters, left-aligned, using 'format'
+     $ du -s * | numfmt --to=si --padding="%-10f"
+     2.5K       config.log
+     108        config.status
+     1.7K       configure
+     20         configure.ac
+
+   With locales that support grouping digits, using ‘--grouping’ or
+‘--format’ enables grouping.  In ‘POSIX’ locale, grouping is silently
+ignored:
+
+     $ LC_ALL=C numfmt --from=iec --grouping 2G
+     2147483648
+
+     $ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
+     2,147,483,648
+
+     $ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
+     2,14,74,83,648
+
+     $ LC_ALL=C numfmt --from=iec --format="==%'15f==" 2G
+     ==     2147483648==
+
+     $ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'15f==" 2G
+     ==  2,147,483,648==
+
+     $ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'-15f==" 2G
+     ==2,147,483,648  ==
+
+     $ LC_ALL=ta_IN numfmt --from=iec --format="==%'15f==" 2G
+     == 2,14,74,83,648==
+
+
+File: coreutils.info,  Node: seq invocation,  Prev: numfmt invocation,  Up: Numeric operations
+
+26.3 ‘seq’: Print numeric sequences
+===================================
+
+‘seq’ prints a sequence of numbers to standard output.  Synopses:
+
+     seq [OPTION]... LAST
+     seq [OPTION]... FIRST LAST
+     seq [OPTION]... FIRST INCREMENT LAST
+
+   ‘seq’ prints the numbers from FIRST to LAST by INCREMENT.  By
+default, each number is printed on a separate line.  When INCREMENT is
+not specified, it defaults to ‘1’, even when FIRST is larger than LAST.
+FIRST also defaults to ‘1’.  So ‘seq 1’ prints ‘1’, but ‘seq 0’ and ‘seq
+10 5’ produce no output.  The sequence of numbers ends when the sum of
+the current number and INCREMENT would become greater than LAST, so ‘seq
+1 10 10’ only produces ‘1’.  INCREMENT must not be ‘0’; use the tool
+‘yes’ to get repeated output of a constant number.  FIRST, INCREMENT and
+LAST must not be ‘NaN’, but ‘inf’ is supported.  Floating-point numbers
+may be specified in either the current or the C locale.  *Note Floating
+point::.
+
+   The program accepts the following options.  Also see *note Common
+options::.  Options must precede operands.
+
+‘-f FORMAT’
+‘--format=FORMAT’
+     Print all numbers using FORMAT.  FORMAT must contain exactly one of
+     the ‘printf’-style floating point conversion specifications ‘%a’,
+     ‘%e’, ‘%f’, ‘%g’, ‘%A’, ‘%E’, ‘%F’, ‘%G’.  The ‘%’ may be followed
+     by zero or more flags taken from the set ‘-+#0 '’, then an optional
+     width containing one or more digits, then an optional precision
+     consisting of a ‘.’ followed by zero or more digits.  FORMAT may
+     also contain any number of ‘%%’ conversion specifications.  All
+     conversion specifications have the same meaning as with ‘printf’.
+
+     The default format is derived from FIRST, STEP, and LAST.  If these
+     all use a fixed point decimal representation, the default format is
+     ‘%.Pf’, where P is the minimum precision that can represent the
+     output numbers exactly.  Otherwise, the default format is ‘%g’.
+
+‘-s STRING’
+‘--separator=STRING’
+     Separate numbers with STRING; default is a newline.  The output
+     always terminates with a newline.
+
+‘-w’
+‘--equal-width’
+     Print all numbers with the same width, by padding with leading
+     zeros.  FIRST, STEP, and LAST should all use a fixed point decimal
+     representation.  (To have other kinds of padding, use ‘--format’).
+
+   You can get finer-grained control over output with ‘-f’:
+
+     $ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6
+     (-9.00E+05)
+     ( 2.00E+05)
+     ( 1.30E+06)
+
+   If you want hexadecimal integer output, you can use ‘printf’ to
+perform the conversion:
+
+     $ printf '%x\n' $(seq 1048575 1024 1050623)
+     fffff
+     1003ff
+     1007ff
+
+   For very long lists of numbers, use xargs to avoid system limitations
+on the length of an argument list:
+
+     $ seq 1000000 | xargs printf '%x\n' | tail -n 3
+     f423e
+     f423f
+     f4240
+
+   To generate octal output, use the printf ‘%o’ format instead of ‘%x’.
+
+   On most systems, seq can produce whole-number output for values up to
+at least 2^{53}.  Larger integers are approximated.  The details differ
+depending on your floating-point implementation.  *Note Floating
+point::.  A common case is that ‘seq’ works with integers through
+2^{64}, and larger integers may not be numerically correct:
+
+     $ seq 50000000000000000000 2 50000000000000000004
+     50000000000000000000
+     50000000000000000000
+     50000000000000000004
+
+   However, note that when limited to non-negative whole numbers, an
+increment of less than 200, and no format-specifying option, seq can
+print arbitrarily large numbers.  Therefore ‘seq inf’ can be used to
+generate an infinite sequence of numbers.
+
+   Be careful when using ‘seq’ with outlandish values: otherwise you may
+see surprising results, as ‘seq’ uses floating point internally.  For
+example, on the x86 platform, where the internal representation uses a
+64-bit fraction, the command:
+
+     seq 1 0.0000000000000000001 1.0000000000000000009
+
+   outputs 1.0000000000000000007 twice and skips 1.0000000000000000008.
+
+   An exit status of zero indicates success, and a nonzero value
+indicates failure.
+
+
+File: coreutils.info,  Node: File permissions,  Next: File timestamps,  Prev: Numeric operations,  Up: Top
+
+27 File permissions
+*******************
+
+Each file has a set of “file mode bits” that control the kinds of access
+that users have to that file.  They can be represented either in
+symbolic form or as an octal number.
+
+* Menu:
+
+* Mode Structure::              Structure of file mode bits.
+* Symbolic Modes::              Mnemonic representation of file mode bits.
+* Numeric Modes::               File mode bits as octal numbers.
+* Operator Numeric Modes::      ANDing, ORing, and setting modes octally.
+* Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories.
+
+
+File: coreutils.info,  Node: Mode Structure,  Next: Symbolic Modes,  Up: File permissions
+
+27.1 Structure of File Mode Bits
+================================
+
+The file mode bits have two parts: the “file permission bits”, which
+control ordinary access to the file, and “special mode bits”, which
+affect only some files.
+
+   There are three kinds of permissions that a user can have for a file:
+
+  1. permission to read the file.  For directories, this means
+     permission to list the contents of the directory.
+  2. permission to write to (change) the file.  For directories, this
+     means permission to create and remove files in the directory.
+  3. permission to execute the file (run it as a program).  For
+     directories, this means permission to access files in the
+     directory.
+
+   There are three categories of users who may have different
+permissions to perform any of the above operations on a file:
+
+  1. the file’s owner;
+  2. other users who are in the file’s group;
+  3. everyone else.
+
+   Files are given an owner and group when they are created.  Usually
+the owner is the current user and the group is the group of the
+directory the file is in, but this varies with the operating system, the
+file system the file is created on, and the way the file is created.
+You can change the owner and group of a file by using the ‘chown’ and
+‘chgrp’ commands.
+
+   In addition to the three sets of three permissions listed above, the
+file mode bits have three special components, which affect only
+executable files (programs) and, on most systems, directories:
+
+The “set-user-ID bit” (“setuid bit”).
+     On execution, set the process’s effective user ID to that of the
+     file.  For directories on a few systems, give files created in the
+     directory the same owner as the directory, no matter who creates
+     them, and set the set-user-ID bit of newly-created subdirectories.
+
+The “set-group-ID bit” (“setgid bit”).
+     On execution, set the process’s effective group ID to that of the
+     file.  For directories on most systems, give files created in the
+     directory the same group as the directory, no matter what group the
+     user who creates them is in, and set the set-group-ID bit of
+     newly-created subdirectories.
+
+The “restricted deletion flag” or “sticky bit”.
+     Prevent unprivileged users from removing or renaming a file in a
+     directory unless they own the file or the directory; this is
+     commonly found on world-writable directories like ‘/tmp’.  For
+     regular files on some older systems, save the program’s text image
+     on the swap device so it will load more quickly when run, so that
+     the image is “sticky”.
+
+   In addition to the file mode bits listed above, there may be file
+attributes specific to the file system, e.g., access control lists
+(ACLs), whether a file is compressed, whether a file can be modified
+(immutability), and whether a file can be dumped.  These are usually set
+using programs specific to the file system.  For example:
+
+ext2
+     On GNU and GNU/Linux the file attributes specific to the ext2 file
+     system are set using ‘chattr’.
+
+FFS
+     On FreeBSD the file flags specific to the FFS file system are set
+     using ‘chflags’.
+
+   Even if a file’s mode bits allow an operation on that file, that
+operation may still fail, because:
+
+   • the file-system-specific attributes or flags do not permit it; or
+
+   • the file system is mounted as read-only.
+
+   For example, if the immutable attribute is set on a file, it cannot
+be modified, regardless of the fact that you may have just run ‘chmod
+a+w FILE’.
+
+
+File: coreutils.info,  Node: Symbolic Modes,  Next: Numeric Modes,  Prev: Mode Structure,  Up: File permissions
+
+27.2 Symbolic Modes
+===================
+
+“Symbolic modes” represent changes to files’ mode bits as operations on
+single-character symbols.  They allow you to modify either all or
+selected parts of files’ mode bits, optionally based on their previous
+values, and perhaps on the current ‘umask’ as well (*note Umask and
+Protection::).
+
+   The format of symbolic modes is:
+
+     [ugoa...][-+=]PERMS...[,...]
+
+where PERMS is either zero or more letters from the set ‘rwxXst’, or a
+single letter from the set ‘ugo’.
+
+   The following sections describe the operators and other details of
+symbolic modes.
+
+* Menu:
+
+* Setting Permissions::          Basic operations on permissions.
+* Copying Permissions::          Copying existing permissions.
+* Changing Special Mode Bits::   Special mode bits.
+* Conditional Executability::    Conditionally affecting executability.
+* Multiple Changes::             Making multiple changes.
+* Umask and Protection::              The effect of the umask.
+
+
+File: coreutils.info,  Node: Setting Permissions,  Next: Copying Permissions,  Up: Symbolic Modes
+
+27.2.1 Setting Permissions
+--------------------------
+
+The basic symbolic operations on a file’s permissions are adding,
+removing, and setting the permission that certain users have to read,
+write, and execute or search the file.  These operations have the
+following format:
+
+     USERS OPERATION PERMISSIONS
+
+The spaces between the three parts above are shown for readability only;
+symbolic modes cannot contain spaces.
+
+   The USERS part tells which users’ access to the file is changed.  It
+consists of one or more of the following letters (or it can be empty;
+*note Umask and Protection::, for a description of what happens then).
+When more than one of these letters is given, the order that they are in
+does not matter.
+
+‘u’
+     the user who owns the file;
+‘g’
+     other users who are in the file’s group;
+‘o’
+     all other users;
+‘a’
+     all users; the same as ‘ugo’.
+
+   The OPERATION part tells how to change the affected users’ access to
+the file, and is one of the following symbols:
+
+‘+’
+     to add the PERMISSIONS to whatever permissions the USERS already
+     have for the file;
+‘-’
+     to remove the PERMISSIONS from whatever permissions the USERS
+     already have for the file;
+‘=’
+     to make the PERMISSIONS the only permissions that the USERS have
+     for the file.
+
+   The PERMISSIONS part tells what kind of access to the file should be
+changed; it is normally zero or more of the following letters.  As with
+the USERS part, the order does not matter when more than one letter is
+given.  Omitting the PERMISSIONS part is useful only with the ‘=’
+operation, where it gives the specified USERS no access at all to the
+file.
+
+‘r’
+     the permission the USERS have to read the file;
+‘w’
+     the permission the USERS have to write to the file;
+‘x’
+     the permission the USERS have to execute the file, or search it if
+     it is a directory.
+
+   For example, to give everyone permission to read and write a regular
+file, but not to execute it, use:
+
+     a=rw
+
+   To remove write permission for all users other than the file’s owner,
+use:
+
+     go-w
+
+The above command does not affect the access that the owner of the file
+has to it, nor does it affect whether other users can read or execute
+the file.
+
+   To give everyone except a file’s owner no permission to do anything
+with that file, use the mode below.  Other users could still remove the
+file, if they have write permission on the directory it is in.
+
+     go=
+
+Another way to specify the same thing is:
+
+     og-rwx
+
+
+File: coreutils.info,  Node: Copying Permissions,  Next: Changing Special Mode Bits,  Prev: Setting Permissions,  Up: Symbolic Modes
+
+27.2.2 Copying Existing Permissions
+-----------------------------------
+
+You can base a file’s permissions on its existing permissions.  To do
+this, instead of using a series of ‘r’, ‘w’, or ‘x’ letters after the
+operator, you use the letter ‘u’, ‘g’, or ‘o’.  For example, the mode
+
+     o+g
+
+adds the permissions for users who are in a file’s group to the
+permissions that other users have for the file.  Thus, if the file
+started out as mode 664 (‘rw-rw-r--’), the above mode would change it to
+mode 666 (‘rw-rw-rw-’).  If the file had started out as mode 741
+(‘rwxr----x’), the above mode would change it to mode 745 (‘rwxr--r-x’).
+The ‘-’ and ‘=’ operations work analogously.
+
+
+File: coreutils.info,  Node: Changing Special Mode Bits,  Next: Conditional Executability,  Prev: Copying Permissions,  Up: Symbolic Modes
+
+27.2.3 Changing Special Mode Bits
+---------------------------------
+
+In addition to changing a file’s read, write, and execute/search
+permissions, you can change its special mode bits.  *Note Mode
+Structure::, for a summary of these special mode bits.
+
+   To change the file mode bits to set the user ID on execution, use ‘u’
+in the USERS part of the symbolic mode and ‘s’ in the PERMISSIONS part.
+
+   To change the file mode bits to set the group ID on execution, use
+‘g’ in the USERS part of the symbolic mode and ‘s’ in the PERMISSIONS
+part.
+
+   To set both user and group ID on execution, omit the USERS part of
+the symbolic mode (or use ‘a’) and use ‘s’ in the PERMISSIONS part.
+
+   To change the file mode bits to set the restricted deletion flag or
+sticky bit, omit the USERS part of the symbolic mode (or use ‘a’) and
+use ‘t’ in the PERMISSIONS part.
+
+   For example, to set the set-user-ID mode bit of a program, you can
+use the mode:
+
+     u+s
+
+   To remove both set-user-ID and set-group-ID mode bits from it, you
+can use the mode:
+
+     a-s
+
+   To set the restricted deletion flag or sticky bit, you can use the
+mode:
+
+     +t
+
+   The combination ‘o+s’ has no effect.  On GNU systems the combinations
+‘u+t’ and ‘g+t’ have no effect, and ‘o+t’ acts like plain ‘+t’.
+
+   The ‘=’ operator is not very useful with special mode bits.  For
+example, the mode:
+
+     o=t
+
+does set the restricted deletion flag or sticky bit, but it also removes
+all read, write, and execute/search permissions that users not in the
+file’s group might have had for it.
+
+   *Note Directory Setuid and Setgid::, for additional rules concerning
+set-user-ID and set-group-ID bits and directories.
+
+
+File: coreutils.info,  Node: Conditional Executability,  Next: Multiple Changes,  Prev: Changing Special Mode Bits,  Up: Symbolic Modes
+
+27.2.4 Conditional Executability
+--------------------------------
+
+There is one more special type of symbolic permission: if you use ‘X’
+instead of ‘x’, execute/search permission is affected only if the file
+is a directory or already had execute permission.
+
+   For example, this mode:
+
+     a+X
+
+gives all users permission to search directories, or to execute files if
+anyone could execute them before.
+
+
+File: coreutils.info,  Node: Multiple Changes,  Next: Umask and Protection,  Prev: Conditional Executability,  Up: Symbolic Modes
+
+27.2.5 Making Multiple Changes
+------------------------------
+
+The format of symbolic modes is actually more complex than described
+above (*note Setting Permissions::).  It provides two ways to make
+multiple changes to files’ mode bits.
+
+   The first way is to specify multiple OPERATION and PERMISSIONS parts
+after a USERS part in the symbolic mode.
+
+   For example, the mode:
+
+     og+rX-w
+
+gives users other than the owner of the file read permission and, if it
+is a directory or if someone already had execute permission to it, gives
+them execute/search permission; and it also denies them write permission
+to the file.  It does not affect the permission that the owner of the
+file has for it.  The above mode is equivalent to the two modes:
+
+     og+rX
+     og-w
+
+   The second way to make multiple changes is to specify more than one
+simple symbolic mode, separated by commas.  For example, the mode:
+
+     a+r,go-w
+
+gives everyone permission to read the file and removes write permission
+on it for all users except its owner.  Another example:
+
+     u=rwx,g=rx,o=
+
+sets all of the permission bits for the file explicitly.  (It gives
+users who are not in the file’s group no permission at all for it.)
+
+   The two methods can be combined.  The mode:
+
+     a+r,g+x-w
+
+gives all users permission to read the file, and gives users who are in
+the file’s group permission to execute/search it as well, but not
+permission to write to it.  The above mode could be written in several
+different ways; another is:
+
+     u+r,g+rx,o+r,g-w
+
+
+File: coreutils.info,  Node: Umask and Protection,  Prev: Multiple Changes,  Up: Symbolic Modes
+
+27.2.6 The Umask and Protection
+-------------------------------
+
+If the USERS part of a symbolic mode is omitted, it defaults to ‘a’
+(affect all users), except that any permissions that are _set_ in the
+system variable ‘umask’ are _not affected_.  The value of ‘umask’ can be
+set using the ‘umask’ command.  Its default value varies from system to
+system.
+
+   Omitting the USERS part of a symbolic mode is generally not useful
+with operations other than ‘+’.  It is useful with ‘+’ because it allows
+you to use ‘umask’ as an easily customizable protection against giving
+away more permission to files than you intended to.
+
+   As an example, if ‘umask’ has the value 2, which removes write
+permission for users who are not in the file’s group, then the mode:
+
+     +w
+
+adds permission to write to the file to its owner and to other users who
+are in the file’s group, but _not_ to other users.  In contrast, the
+mode:
+
+     a+w
+
+ignores ‘umask’, and _does_ give write permission for the file to all
+users.
+
+
+File: coreutils.info,  Node: Numeric Modes,  Next: Operator Numeric Modes,  Prev: Symbolic Modes,  Up: File permissions
+
+27.3 Numeric Modes
+==================
+
+As an alternative to giving a symbolic mode, you can give an octal (base
+8) number that represents the mode.
+
+   The permissions granted to the user, to other users in the file’s
+group, and to other users not in the file’s group each require three
+bits: one bit for read, one for write, and one for execute/search
+permission.  These three bits are represented as one octal digit; for
+example, if all three are present, the resulting 111 (in binary) is
+represented as the digit 7 (in octal).  The three special mode bits also
+require one bit each, and they are as a group represented as another
+octal digit.  Here is how the bits are arranged, starting with the
+highest valued bit:
+
+     Value in  Corresponding
+     Mode      Mode Bit
+
+               Special mode bits:
+     4000      Set user ID
+     2000      Set group ID
+     1000      Restricted deletion flag or sticky bit
+
+               The file's owner:
+      400      Read
+      200      Write
+      100      Execute/search
+
+               Other users in the file's group:
+       40      Read
+       20      Write
+       10      Execute/search
+
+               Other users not in the file's group:
+        4      Read
+        2      Write
+        1      Execute/search
+
+   For example, numeric mode ‘4751’ corresponds to symbolic mode
+‘u=srwx,g=rx,o=x’, and numeric mode ‘664’ corresponds to symbolic mode
+‘ug=rw,o=r’.  Numeric mode ‘0’ corresponds to symbolic mode ‘a=’.
+
+   A numeric mode is usually shorter than the corresponding symbolic
+mode, but it is limited in that normally it cannot take into account the
+previous file mode bits; it can only set them absolutely.  The
+set-user-ID and set-group-ID bits of directories are an exception to
+this general limitation.  *Note Directory Setuid and Setgid::.  Also,
+operator numeric modes can take previous file mode bits into account.
+*Note Operator Numeric Modes::.
+
+   Numeric modes are always interpreted in octal; you do not have to add
+a leading ‘0’, as you do in C.  Mode ‘0055’ is the same as mode ‘55’.
+However, modes of five digits or more, such as ‘00055’, are sometimes
+special (*note Directory Setuid and Setgid::).
+
+
+File: coreutils.info,  Node: Operator Numeric Modes,  Next: Directory Setuid and Setgid,  Prev: Numeric Modes,  Up: File permissions
+
+27.4 Operator Numeric Modes
+===========================
+
+An operator numeric mode is a numeric mode that is prefixed by a ‘-’,
+‘+’, or ‘=’ operator, which has the same interpretation as in symbolic
+modes.  For example, ‘+440’ enables read permission for the file’s owner
+and group, ‘-1’ disables execute permission for other users, and ‘=600’
+clears all permissions except for enabling read-write permissions for
+the file’s owner.  Operator numeric modes can be combined with symbolic
+modes by separating them with a comma; for example, ‘=0,u+r’ clears all
+permissions except for enabling read permission for the file’s owner.
+
+   The commands ‘chmod =755 DIR’ and ‘chmod 755 DIR’ differ in that the
+former clears the directory DIR’s setuid and setgid bits, whereas the
+latter preserves them.  *Note Directory Setuid and Setgid::.
+
+   Operator numeric modes are a GNU extension.
+
+
+File: coreutils.info,  Node: Directory Setuid and Setgid,  Prev: Operator Numeric Modes,  Up: File permissions
+
+27.5 Directories and the Set-User-ID and Set-Group-ID Bits
+==========================================================
+
+On most systems, if a directory’s set-group-ID bit is set, newly created
+subfiles inherit the same group as the directory, and newly created
+subdirectories inherit the set-group-ID bit of the parent directory.  On
+a few systems, a directory’s set-user-ID bit has a similar effect on the
+ownership of new subfiles and the set-user-ID bits of new
+subdirectories.  These mechanisms let users share files more easily, by
+lessening the need to use ‘chmod’ or ‘chown’ to share new files.
+
+   These convenience mechanisms rely on the set-user-ID and set-group-ID
+bits of directories.  If commands like ‘chmod’ and ‘mkdir’ routinely
+cleared these bits on directories, the mechanisms would be less
+convenient and it would be harder to share files.  Therefore, a command
+like ‘chmod’ does not affect the set-user-ID or set-group-ID bits of a
+directory unless the user specifically mentions them in a symbolic mode,
+or uses an operator numeric mode such as ‘=755’, or sets them in a
+numeric mode, or clears them in a numeric mode that has five or more
+octal digits.  For example, on systems that support set-group-ID
+inheritance:
+
+     # These commands leave the set-user-ID and
+     # set-group-ID bits of the subdirectories alone,
+     # so that they retain their default values.
+     mkdir A B C
+     chmod 755 A
+     chmod 0755 B
+     chmod u=rwx,go=rx C
+     mkdir -m 755 D
+     mkdir -m 0755 E
+     mkdir -m u=rwx,go=rx F
+
+   If you want to try to set these bits, you must mention them
+explicitly in the symbolic or numeric modes, e.g.:
+
+     # These commands try to set the set-user-ID
+     # and set-group-ID bits of the subdirectories.
+     mkdir G
+     chmod 6755 G
+     chmod +6000 G
+     chmod u=rwx,go=rx,a+s G
+     mkdir -m 6755 H
+     mkdir -m +6000 I
+     mkdir -m u=rwx,go=rx,a+s J
+
+   If you want to try to clear these bits, you must mention them
+explicitly in a symbolic mode, or use an operator numeric mode, or
+specify a numeric mode with five or more octal digits, e.g.:
+
+     # These commands try to clear the set-user-ID
+     # and set-group-ID bits of the directory D.
+     chmod a-s D
+     chmod -6000 D
+     chmod =755 D
+     chmod 00755 D
+
+   This behavior is a GNU extension.  Portable scripts should not rely
+on requests to set or clear these bits on directories, as POSIX allows
+implementations to ignore these requests.  The GNU behavior with numeric
+modes of four or fewer digits is intended for scripts portable to
+systems that preserve these bits; the behavior with numeric modes of
+five or more digits is for scripts portable to systems that do not
+preserve the bits.
+
+
+File: coreutils.info,  Node: File timestamps,  Next: Date input formats,  Prev: File permissions,  Up: Top
+
+28 File timestamps
+******************
+
+Standard POSIX files have three timestamps: the access timestamp (atime)
+of the last read, the modification timestamp (mtime) of the last write,
+and the status change timestamp (ctime) of the last change to the file’s
+meta-information.  Some file systems support a fourth time: the birth
+timestamp (birthtime) of when the file was created; by definition,
+birthtime never changes.
+
+   One common example of a ctime change is when the permissions of a
+file change.  Changing the permissions doesn’t access the file, so atime
+doesn’t change, nor does it modify the file, so the mtime doesn’t
+change.  Yet, something about the file itself has changed, and this must
+be noted somewhere.  This is the job of the ctime field.  This is
+necessary, so that, for example, a backup program can make a fresh copy
+of the file, including the new permissions value.  Another operation
+that modifies a file’s ctime without affecting the others is renaming.
+
+   Naively, a file’s atime, mtime, and ctime are set to the current time
+whenever you read, write, or change the attributes of the file
+respectively, and searching a directory counts as reading it.  A file’s
+atime and mtime can also be set directly, via the ‘touch’ command (*note
+touch invocation::).  In practice, though, timestamps are not updated
+quite that way.
+
+   For efficiency reasons, many systems are lazy about updating atimes:
+when a program accesses a file, they may delay updating the file’s
+atime, or may not update the file’s atime if the file has been accessed
+recently, or may not update the atime at all.  Similar laziness, though
+typically not quite so extreme, applies to mtimes and ctimes.
+
+   Some systems emulate timestamps instead of supporting them directly,
+and these emulations may disagree with the naive interpretation.  For
+example, a system may fake an atime or ctime by using the mtime.
+
+   The determination of what time is “current” depends on the platform.
+Platforms with network file systems often use different clocks for the
+operating system and for file systems; because updates typically uses
+file systems’ clocks by default, clock skew can cause the resulting file
+timestamps to appear to be in a program’s “future” or “past”.
+
+   When the system updates a file timestamp to a desired time T (which
+is either the current time, or a time specified via the ‘touch’
+command), there are several reasons the file’s timestamp may be set to a
+value that differs from T.  First, T may have a higher resolution than
+supported.  Second, a file system may use different resolutions for
+different types of times.  Third, file timestamps may use a different
+resolution than operating system timestamps.  Fourth, the operating
+system primitives used to update timestamps may employ yet a different
+resolution.  For example, in theory a file system might use
+10-microsecond resolution for access timestamp and 100-nanosecond
+resolution for modification timestamp, and the operating system might
+use nanosecond resolution for the current time and microsecond
+resolution for the primitive that ‘touch’ uses to set a file’s timestamp
+to an arbitrary value.
+
+
+File: coreutils.info,  Node: Date input formats,  Next: Version sort ordering,  Prev: File timestamps,  Up: Top
+
+29 Date input formats
+*********************
+
+First, a quote:
+
+     Our units of temporal measurement, from seconds on up to months,
+     are so complicated, asymmetrical and disjunctive so as to make
+     coherent mental reckoning in time all but impossible.  Indeed, had
+     some tyrannical god contrived to enslave our minds to time, to make
+     it all but impossible for us to escape subjection to sodden
+     routines and unpleasant surprises, he could hardly have done better
+     than handing down our present system.  It is like a set of
+     trapezoidal building blocks, with no vertical or horizontal
+     surfaces, like a language in which the simplest thought demands
+     ornate constructions, useless particles and lengthy
+     circumlocutions.  Unlike the more successful patterns of language
+     and science, which enable us to face experience boldly or at least
+     level-headedly, our system of temporal calculation silently and
+     persistently encourages our terror of time.
+
+     ... It is as though architects had to measure length in feet, width
+     in meters and height in ells; as though basic instruction manuals
+     demanded a knowledge of five different languages.  It is no wonder
+     then that we often look into our own immediate past or future, last
+     Tuesday or a week from Sunday, with feelings of helpless confusion.
+     ...
+
+     —Robert Grudin, ‘Time and the Art of Living’.
+
+   This section describes the textual date representations that GNU
+programs accept.  These are the strings you, as a user, can supply as
+arguments to the various programs.  The C interface (via the
+‘parse_datetime’ function) is not described here.
+
+* Menu:
+
+* General date syntax::          Common rules
+* Calendar date items::          ‘14 Nov 2022’
+* Time of day items::            ‘9:02pm’
+* Time zone items::              ‘UTC’, ‘-0700’, ‘+0900’, ...
+* Combined date and time of day items:: ‘2022-11-14T21:02:42,000000-0500’
+* Day of week items::            ‘Monday’ and others
+* Relative items in date strings:: ‘next tuesday, 2 years ago’
+* Pure numbers in date strings:: ‘20221114’, ‘2102’
+* Seconds since the Epoch::      ‘@1668477762’
+* Specifying time zone rules::   ‘TZ="America/New_York"’, ‘TZ="UTC0"’
+* Authors of parse_datetime::    Bellovin, Eggert, Salz, Berets, et al.
+
+
+File: coreutils.info,  Node: General date syntax,  Next: Calendar date items,  Up: Date input formats
+
+29.1 General date syntax
+========================
+
+A “date” is a string, possibly empty, containing many items separated by
+whitespace.  The whitespace may be omitted when no ambiguity arises.
+The empty string means the beginning of today (i.e., midnight).  Order
+of the items is immaterial.  A date string may contain many flavors of
+items:
+
+   • calendar date items
+   • time of day items
+   • time zone items
+   • combined date and time of day items
+   • day of the week items
+   • relative items
+   • pure numbers.
+
+We describe each of these item types in turn, below.
+
+   A few ordinal numbers may be written out in words in some contexts.
+This is most useful for specifying day of the week items or relative
+items (see below).  Among the most commonly used ordinal numbers, the
+word ‘last’ stands for -1, ‘this’ stands for 0, and ‘first’ and ‘next’
+both stand for 1.  Because the word ‘second’ stands for the unit of time
+there is no way to write the ordinal number 2, but for convenience
+‘third’ stands for 3, ‘fourth’ for 4, ‘fifth’ for 5, ‘sixth’ for 6,
+‘seventh’ for 7, ‘eighth’ for 8, ‘ninth’ for 9, ‘tenth’ for 10,
+‘eleventh’ for 11 and ‘twelfth’ for 12.
+
+   When a month is written this way, it is still considered to be
+written numerically, instead of being “spelled in full”; this changes
+the allowed strings.
+
+   In the current implementation, only English is supported for words
+and abbreviations like ‘AM’, ‘DST’, ‘EST’, ‘first’, ‘January’, ‘Sunday’,
+‘tomorrow’, and ‘year’.
+
+   The output of the ‘date’ command is not always acceptable as a date
+string, not only because of the language problem, but also because there
+is no standard meaning for time zone items like ‘IST’.  When using
+‘date’ to generate a date string intended to be parsed later, specify a
+date format that is independent of language and that does not use time
+zone items other than ‘UTC’ and ‘Z’.  Here are some ways to do this:
+
+     $ LC_ALL=C TZ=UTC0 date
+     Tue Nov 15 02:02:42 UTC 2022
+     $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+     2022-11-15 02:02:42Z
+     $ date --rfc-3339=ns  # --rfc-3339 is a GNU extension.
+     2022-11-14 21:02:42.000000000-05:00
+     $ date --rfc-email  # a GNU extension
+     Mon, 14 Nov 2022 21:02:42 -0500
+     $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
+     2022-11-14 21:02:42 -0500
+     $ date +'@%s.%N'  # %s and %N are GNU extensions.
+     @1668477762.692722128
+
+   Alphabetic case is completely ignored in dates.  Comments may be
+introduced between round parentheses, as long as included parentheses
+are properly nested.  Hyphens not followed by a digit are currently
+ignored.  Leading zeros on numbers are ignored.
+
+   Invalid dates like ‘2022-02-29’ or times like ‘24:00’ are rejected.
+In the typical case of a host that does not support leap seconds, a time
+like ‘23:59:60’ is rejected even if it corresponds to a valid leap
+second.
+
+
+File: coreutils.info,  Node: Calendar date items,  Next: Time of day items,  Prev: General date syntax,  Up: Date input formats
+
+29.2 Calendar date items
+========================
+
+A “calendar date item” specifies a day of the year.  It is specified
+differently, depending on whether the month is specified numerically or
+literally.  All these strings specify the same calendar date:
+
+     2022-11-14     # ISO 8601.
+     22-11-14       # Assume 19xx for 69 through 99,
+                    # 20xx for 00 through 68 (not recommended).
+     11/14/2022     # Common U.S. writing.
+     14 November 2022
+     14 Nov 2022    # Three-letter abbreviations always allowed.
+     November 14, 2022
+     14-nov-2022
+     14nov2022
+
+   The year can also be omitted.  In this case, the last specified year
+is used, or the current year if none.  For example:
+
+     11/14
+     nov 14
+
+   Here are the rules.
+
+   For numeric months, the ISO 8601 format ‘YEAR-MONTH-DAY’ is allowed,
+where YEAR is any positive number, MONTH is a number between 01 and 12,
+and DAY is a number between 01 and 31.  A leading zero must be present
+if a number is less than ten.  If YEAR is 68 or smaller, then 2000 is
+added to it; otherwise, if YEAR is less than 100, then 1900 is added to
+it.  The construct ‘MONTH/DAY/YEAR’, popular in the United States, is
+accepted.  Also ‘MONTH/DAY’, omitting the year.
+
+   Literal months may be spelled out in full: ‘January’, ‘February’,
+‘March’, ‘April’, ‘May’, ‘June’, ‘July’, ‘August’, ‘September’,
+‘October’, ‘November’ or ‘December’.  Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write ‘Sept’ instead of ‘September’.
+
+   When months are written literally, the calendar date may be given as
+any of the following:
+
+     DAY MONTH YEAR
+     DAY MONTH
+     MONTH DAY YEAR
+     DAY-MONTH-YEAR
+
+   Or, omitting the year:
+
+     MONTH DAY
+
+
+File: coreutils.info,  Node: Time of day items,  Next: Time zone items,  Prev: Calendar date items,  Up: Date input formats
+
+29.3 Time of day items
+======================
+
+A “time of day item” in date strings specifies the time on a given day.
+Here are some examples, all of which represent the same time:
+
+     20:02:00.000000
+     20:02
+     8:02pm
+     20:02-0500      # In EST (U.S. Eastern Standard Time).
+
+   More generally, the time of day may be given as ‘HOUR:MINUTE:SECOND’,
+where HOUR is a number between 0 and 23, MINUTE is a number between 0
+and 59, and SECOND is a number between 0 and 59 possibly followed by ‘.’
+or ‘,’ and a fraction containing one or more digits.  Alternatively,
+‘:SECOND’ can be omitted, in which case it is taken to be zero.  On the
+rare hosts that support leap seconds, SECOND may be 60.
+
+   If the time is followed by ‘am’ or ‘pm’ (or ‘a.m.’ or ‘p.m.’), HOUR
+is restricted to run from 1 to 12, and ‘:MINUTE’ may be omitted (taken
+to be zero).  ‘am’ indicates the first half of the day, ‘pm’ indicates
+the second half of the day.  In this notation, 12 is the predecessor of
+1: midnight is ‘12am’ while noon is ‘12pm’.  (This is the zero-oriented
+interpretation of ‘12am’ and ‘12pm’, as opposed to the old tradition
+derived from Latin which uses ‘12m’ for noon and ‘12pm’ for midnight.)
+
+   The time may alternatively be followed by a time zone correction,
+expressed as ‘SHHMM’, where S is ‘+’ or ‘-’, HH is a number of zone
+hours and MM is a number of zone minutes.  The zone minutes term, MM,
+may be omitted, in which case the one- or two-digit correction is
+interpreted as a number of hours.  You can also separate HH from MM with
+a colon.  When a time zone correction is given this way, it forces
+interpretation of the time relative to Coordinated Universal Time (UTC),
+overriding any previous specification for the time zone or the local
+time zone.  For example, ‘+0530’ and ‘+05:30’ both stand for the time
+zone 5.5 hours ahead of UTC (e.g., India).  This is the best way to
+specify a time zone correction by fractional parts of an hour.  The
+maximum zone correction is 24 hours.
+
+   Either ‘am’/‘pm’ or a time zone correction may be specified, but not
+both.
+
+
+File: coreutils.info,  Node: Time zone items,  Next: Combined date and time of day items,  Prev: Time of day items,  Up: Date input formats
+
+29.4 Time zone items
+====================
+
+A “time zone item” specifies an international time zone, indicated by a
+small set of letters, e.g., ‘UTC’ or ‘Z’ for Coordinated Universal Time.
+Any included periods are ignored.  By following a non-daylight-saving
+time zone by the string ‘DST’ in a separate word (that is, separated by
+some white space), the corresponding daylight saving time zone may be
+specified.  Alternatively, a non-daylight-saving time zone can be
+followed by a time zone correction, to add the two values.  This is
+normally done only for ‘UTC’; for example, ‘UTC+05:30’ is equivalent to
+‘+05:30’.
+
+   Time zone items other than ‘UTC’ and ‘Z’ are obsolescent and are not
+recommended, because they are ambiguous; for example, ‘EST’ has a
+different meaning in Australia than in the United States, and ‘A’ has
+different meaning as a military time zone than as an obsolete RFC 822
+time zone.  Instead, it’s better to use unambiguous numeric time zone
+corrections like ‘-0500’, as described in the previous section.
+
+   If neither a time zone item nor a time zone correction is supplied,
+timestamps are interpreted using the rules of the default time zone
+(*note Specifying time zone rules::).
+
+
+File: coreutils.info,  Node: Combined date and time of day items,  Next: Day of week items,  Prev: Time zone items,  Up: Date input formats
+
+29.5 Combined date and time of day items
+========================================
+
+The ISO 8601 date and time of day extended format consists of an ISO
+8601 date, a ‘T’ character separator, and an ISO 8601 time of day.  This
+format is also recognized if the ‘T’ is replaced by a space.
+
+   In this format, the time of day should use 24-hour notation.
+Fractional seconds are allowed, with either comma or period preceding
+the fraction.  ISO 8601 fractional minutes and hours are not supported.
+Typically, hosts support nanosecond timestamp resolution; excess
+precision is silently discarded.
+
+   Here are some examples:
+
+     2022-09-24T20:02:00.052-05:00
+     2022-12-31T23:59:59,999999999+11:00
+     1970-01-01 00:00Z
+
+
+File: coreutils.info,  Node: Day of week items,  Next: Relative items in date strings,  Prev: Combined date and time of day items,  Up: Date input formats
+
+29.6 Day of week items
+======================
+
+The explicit mention of a day of the week will forward the date (only if
+necessary) to reach that day of the week in the future.
+
+   Days of the week may be spelled out in full: ‘Sunday’, ‘Monday’,
+‘Tuesday’, ‘Wednesday’, ‘Thursday’, ‘Friday’ or ‘Saturday’.  Days may be
+abbreviated to their first three letters, optionally followed by a
+period.  The special abbreviations ‘Tues’ for ‘Tuesday’, ‘Wednes’ for
+‘Wednesday’ and ‘Thur’ or ‘Thurs’ for ‘Thursday’ are also allowed.
+
+   A number may precede a day of the week item to move forward
+supplementary weeks.  It is best used in expression like ‘third monday’.
+In this context, ‘last DAY’ or ‘next DAY’ is also acceptable; they move
+one week before or after the day that DAY by itself would represent.
+
+   A comma following a day of the week item is ignored.
+
+
+File: coreutils.info,  Node: Relative items in date strings,  Next: Pure numbers in date strings,  Prev: Day of week items,  Up: Date input formats
+
+29.7 Relative items in date strings
+===================================
+
+“Relative items” adjust a date (or the current date if none) forward or
+backward.  The effects of relative items accumulate.  Here are some
+examples:
+
+     1 year
+     1 year ago
+     3 years
+     2 days
+
+   The unit of time displacement may be selected by the string ‘year’ or
+‘month’ for moving by whole years or months.  These are fuzzy units, as
+years and months are not all of equal duration.  More precise units are
+‘fortnight’ which is worth 14 days, ‘week’ worth 7 days, ‘day’ worth 24
+hours, ‘hour’ worth 60 minutes, ‘minute’ or ‘min’ worth 60 seconds, and
+‘second’ or ‘sec’ worth one second.  An ‘s’ suffix on these units is
+accepted and ignored.
+
+   The unit of time may be preceded by a multiplier, given as an
+optionally signed number.  Unsigned numbers are taken as positively
+signed.  No number at all implies 1 for a multiplier.  Following a
+relative item by the string ‘ago’ is equivalent to preceding the unit by
+a multiplier with value -1.
+
+   The string ‘tomorrow’ is worth one day in the future (equivalent to
+‘day’), the string ‘yesterday’ is worth one day in the past (equivalent
+to ‘day ago’).
+
+   The strings ‘now’ or ‘today’ are relative items corresponding to
+zero-valued time displacement, these strings come from the fact a
+zero-valued time displacement represents the current time when not
+otherwise changed by previous items.  They may be used to stress other
+items, like in ‘12:00 today’.  The string ‘this’ also has the meaning of
+a zero-valued time displacement, but is preferred in date strings like
+‘this thursday’.
+
+   When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time, the
+resulting date and time are adjusted accordingly.
+
+   The fuzz in units can cause problems with relative items.  For
+example, ‘2022-12-31 -1 month’ might evaluate to 2022-12-01, because
+2022-11-31 is an invalid date.  To determine the previous month more
+reliably, you can ask for the month before the 15th of the current
+month.  For example:
+
+     $ date -R
+     Thu, 31 Dec 2022 13:02:39 -0400
+     $ date --date='-1 month' +'Last month was %B?'
+     Last month was December?
+     $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+     Last month was November!
+
+   Also, take care when manipulating dates around clock changes such as
+daylight saving leaps.  In a few cases these have added or subtracted as
+much as 24 hours from the clock, so it is often wise to adopt universal
+time by setting the ‘TZ’ environment variable to ‘UTC0’ before embarking
+on calendrical calculations.
+
+
+File: coreutils.info,  Node: Pure numbers in date strings,  Next: Seconds since the Epoch,  Prev: Relative items in date strings,  Up: Date input formats
+
+29.8 Pure numbers in date strings
+=================================
+
+The precise interpretation of a pure decimal number depends on the
+context in the date string.
+
+   If the decimal number is of the form YYYYMMDD and no other calendar
+date item (*note Calendar date items::) appears before it in the date
+string, then YYYY is read as the year, MM as the month number and DD as
+the day of the month, for the specified calendar date.
+
+   If the decimal number is of the form HHMM and no other time of day
+item appears before it in the date string, then HH is read as the hour
+of the day and MM as the minute of the hour, for the specified time of
+day.  MM can also be omitted.
+
+   If both a calendar date and a time of day appear to the left of a
+number in the date string, but no relative item, then the number
+overrides the year.
+
+
+File: coreutils.info,  Node: Seconds since the Epoch,  Next: Specifying time zone rules,  Prev: Pure numbers in date strings,  Up: Date input formats
+
+29.9 Seconds since the Epoch
+============================
+
+If you precede a number with ‘@’, it represents an internal timestamp as
+a count of seconds.  The number can contain an internal decimal point
+(either ‘.’ or ‘,’); any excess precision not supported by the internal
+representation is truncated toward minus infinity.  Such a number cannot
+be combined with any other date item, as it specifies a complete
+timestamp.
+
+   Internally, computer times are represented as a count of seconds
+since an Epoch—a well-defined point of time.  On GNU and POSIX systems,
+the Epoch is 1970-01-01 00:00:00 UTC, so ‘@0’ represents this time, ‘@1’
+represents 1970-01-01 00:00:01 UTC, and so forth.  GNU and most other
+POSIX-compliant systems support such times as an extension to POSIX,
+using negative counts, so that ‘@-1’ represents 1969-12-31 23:59:59 UTC.
+
+   Most modern systems count seconds with 64-bit two’s-complement
+integers of seconds with nanosecond subcounts, which is a range that
+includes the known lifetime of the universe with nanosecond resolution.
+Some obsolescent systems count seconds with 32-bit two’s-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 UTC.  A few systems sport other time ranges.
+
+   On most hosts, these counts ignore the presence of leap seconds.  For
+example, on most hosts ‘@1483228799’ represents 2016-12-31 23:59:59 UTC,
+‘@1483228800’ represents 2017-01-01 00:00:00 UTC, and there is no way to
+represent the intervening leap second 2016-12-31 23:59:60 UTC.
+
+
+File: coreutils.info,  Node: Specifying time zone rules,  Next: Authors of parse_datetime,  Prev: Seconds since the Epoch,  Up: Date input formats
+
+29.10 Specifying time zone rules
+================================
+
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the ‘TZ’ environment variable, or
+by a system default if ‘TZ’ is not set.  To specify a different set of
+default time zone rules that apply just to one date, start the date with
+a string of the form ‘TZ="RULE"’.  The two quote characters (‘"’) must
+be present in the date, and any quotes or backslashes within RULE must
+be escaped by a backslash.
+
+   For example, with the GNU ‘date’ command you can answer the question
+“What time is it in New York when a Paris clock shows 6:30am on October
+31, 2022?” by using a date beginning with ‘TZ="Europe/Paris"’ as shown
+in the following shell transcript:
+
+     $ export TZ="America/New_York"
+     $ date --date='TZ="Europe/Paris" 2022-10-31 06:30'
+     Mon Oct 31 01:30:00 EDT 2022
+
+   In this example, the ‘--date’ operand begins with its own ‘TZ’
+setting, so the rest of that operand is processed according to
+‘Europe/Paris’ rules, treating the string ‘2022-11-14 06:30’ as if it
+were in Paris.  However, since the output of the ‘date’ command is
+processed according to the overall time zone rules, it uses New York
+time.  (Paris was normally six hours ahead of New York in 2022, but this
+example refers to a brief Halloween period when the gap was five hours.)
+
+   A ‘TZ’ value is a rule that typically names a location in the ‘tz’
+database (https://www.iana.org/time-zones).  A recent catalog of
+location names appears in the TWiki Date and Time Gateway
+(https://twiki.org/cgi-bin/xtra/tzdatepick.html).  A few non-GNU hosts
+require a colon before a location name in a ‘TZ’ setting, e.g.,
+‘TZ=":America/New_York"’.
+
+   The ‘tz’ database includes a wide variety of locations ranging from
+‘Africa/Abidjan’ to ‘Pacific/Tongatapu’, but if you are at sea and have
+your own private time zone, or if you are using a non-GNU host that does
+not support the ‘tz’ database, you may need to use a POSIX rule instead.
+The previously-mentioned POSIX rule ‘UTC0’ says that the time zone
+abbreviation is ‘UTC’, the zone is zero hours away from Greenwich, and
+there is no daylight saving time.  POSIX rules can also specify nonzero
+Greenwich offsets.  For example, the following shell transcript answers
+the question “What time is it five and a half hours east of Greenwich
+when a clock seven hours west of Greenwich shows 9:50pm on July 12,
+2022?”
+
+     $ TZ="<+0530>-5:30" date --date='TZ="<-07>+7" 2022-07-12 21:50'
+     Wed Jul 13 10:20:00 +0530 2022
+
+This example uses the somewhat-confusing POSIX convention for rules.
+‘TZ="<-07>+7"’ says that the time zone abbreviation is ‘-07’ and the
+time zone is 7 hours west of Greenwich, and ‘TZ="<+0530>-5:30"’ says
+that the time zone abbreviation is ‘+0530’ and the time zone is 5 hours
+30 minutes east of Greenwich.  (One should never use a setting like
+‘TZ="UTC-5"’, since this would incorrectly imply that local time is five
+hours east of Greenwich and the time zone is called “UTC”.)  Although
+trickier POSIX ‘TZ’ settings like ‘TZ="<-05>+5<-04>,M3.2.0/2,M11.1.0/2"’
+can specify some daylight saving regimes, location-based settings like
+‘TZ="America/New_York"’ are typically simpler and more accurate
+historically.  *Note Specifying the Time Zone with ‘TZ’: (libc)TZ
+Variable.
+
+
+File: coreutils.info,  Node: Authors of parse_datetime,  Prev: Specifying time zone rules,  Up: Date input formats
+
+29.11 Authors of ‘parse_datetime’
+=================================
+
+‘parse_datetime’ started life as ‘getdate’, as originally implemented by
+Steven M. Bellovin (<smb@research.att.com>) while at the University of
+North Carolina at Chapel Hill.  The code was later tweaked by a couple
+of people on Usenet, then completely overhauled by Rich $alz
+(<rsalz@bbn.com>) and Jim Berets (<jberets@bbn.com>) in August, 1990.
+Various revisions for the GNU system were made by David MacKenzie, Jim
+Meyering, Paul Eggert and others, including renaming it to ‘get_date’ to
+avoid a conflict with the alternative Posix function ‘getdate’, and a
+later rename to ‘parse_datetime’.  The Posix function ‘getdate’ can
+parse more locale-specific dates using ‘strptime’, but relies on an
+environment variable and external file, and lacks the thread-safety of
+‘parse_datetime’.
+
+   This chapter was originally produced by François Pinard
+(<pinard@iro.umontreal.ca>) from the ‘parse_datetime.y’ source code, and
+then edited by K. Berry (<kb@cs.umb.edu>).
+
+
+File: coreutils.info,  Node: Version sort ordering,  Next: Opening the software toolbox,  Prev: Date input formats,  Up: Top
+
+30 Version sort ordering
+************************
+
+* Menu:
+
+* Version sort overview::
+* Version sort implementation::
+* Differences from Debian version sort::
+* Advanced version sort topics::
+
+
+File: coreutils.info,  Node: Version sort overview,  Next: Version sort implementation,  Up: Version sort ordering
+
+30.1 Version sort overview
+==========================
+
+“Version sort” puts items such as file names and lines of text in an
+order that feels natural to people, when the text contains a mixture of
+letters and digits.
+
+   Lexicographic sorting usually does not produce the order that one
+expects because comparisons are made on a character-by-character basis.
+
+   Compare the sorting of the following items:
+
+     Lexicographic sort:          Version Sort:
+
+     a1                           a1
+     a120                         a2
+     a13                          a13
+     a2                           a120
+
+   Version sort functionality in GNU Coreutils is available in the ‘ls
+-v’, ‘ls --sort=version’, ‘sort -V’, and ‘sort --version-sort’ commands.
+
+* Menu:
+
+* Using version sort in GNU Coreutils::
+* Version sort and natural sort::
+* Variations in version sort order::
+
+
+File: coreutils.info,  Node: Using version sort in GNU Coreutils,  Next: Version sort and natural sort,  Up: Version sort overview
+
+30.1.1 Using version sort in GNU Coreutils
+------------------------------------------
+
+Two GNU Coreutils programs use version sort: ‘ls’ and ‘sort’.
+
+   To list files in version sort order, use ‘ls’ with the ‘-v’ or
+‘--sort=version’ option:
+
+     default sort:              version sort:
+
+     $ ls -1                    $ ls -1 -v
+     a1                         a1
+     a100                       a1.4
+     a1.13                      a1.13
+     a1.4                       a1.40
+     a1.40                      a2
+     a2                         a100
+
+   To sort text files in version sort order, use ‘sort’ with the ‘-V’ or
+‘--version-sort’ option:
+
+     $ cat input
+     b3
+     b11
+     b1
+     b20
+
+
+     lexicographic order:       version sort order:
+
+     $ sort input               $ sort -V input
+     b1                         b1
+     b11                        b3
+     b20                        b11
+     b3                         b20
+
+   To sort a specific field in a file, use ‘-k/--key’ with ‘V’ type
+sorting, which is often combined with ‘b’ to ignore leading blanks in
+the field:
+
+     $ cat input2
+     100   b3   apples
+     2000  b11  oranges
+     3000  b1   potatoes
+     4000  b20  bananas
+     $ sort -k 2bV,2 input2
+     3000  b1   potatoes
+     100   b3   apples
+     2000  b11  oranges
+     4000  b20  bananas
+
+
+File: coreutils.info,  Node: Version sort and natural sort,  Next: Variations in version sort order,  Prev: Using version sort in GNU Coreutils,  Up: Version sort overview
+
+30.1.2 Version sort and natural sort
+------------------------------------
+
+In GNU Coreutils, the name “version sort” was chosen because it is based
+on Debian GNU/Linux’s algorithm of sorting packages’ versions.
+
+   Its goal is to answer questions like “Which package is newer,
+‘firefox-60.7.2’ or ‘firefox-60.12.3’?”
+
+   In Coreutils this algorithm was slightly modified to work on more
+general input such as textual strings and file names (see *note
+Differences from Debian version sort::).
+
+   In other contexts, such as other programs and other programming
+languages, a similar sorting functionality is called natural sort
+(https://en.wikipedia.org/wiki/Natural_sort_order).
+
+
+File: coreutils.info,  Node: Variations in version sort order,  Prev: Version sort and natural sort,  Up: Version sort overview
+
+30.1.3 Variations in version sort order
+---------------------------------------
+
+Currently there is no standard for version sort.
+
+   That is: there is no one correct way or universally agreed-upon way
+to order items.  Each program and each programming language can decide
+its own ordering algorithm and call it “version sort”, “natural sort”,
+or other names.
+
+   See *note Other version/natural sort implementations:: for many
+examples of differing sorting possibilities, each with its own rules and
+variations.
+
+   If you find a bug in the Coreutils implementation of version-sort,
+please report it.  *Note Reporting version sort bugs::.
+
+
+File: coreutils.info,  Node: Version sort implementation,  Next: Differences from Debian version sort,  Prev: Version sort overview,  Up: Version sort ordering
+
+30.2 Version sort implementation
+================================
+
+GNU Coreutils version sort is based on the “upstream version” part of
+Debian’s versioning scheme
+(https://www.debian.org/doc/debian-policy/ch-controlfields.html#version).
+
+   This section describes the GNU Coreutils sort ordering rules.
+
+   The next section (*note Differences from Debian version sort::)
+describes some differences between GNU Coreutils and Debian version
+sort.
+
+* Menu:
+
+* Version-sort ordering rules::
+* Version sort is not the same as numeric sort::
+* Version sort punctuation::
+* Punctuation vs letters::
+* The tilde ~::
+* Version sort ignores locale::
+
+
+File: coreutils.info,  Node: Version-sort ordering rules,  Next: Version sort is not the same as numeric sort,  Up: Version sort implementation
+
+30.2.1 Version-sort ordering rules
+----------------------------------
+
+The version sort ordering rules are:
+
+  1. The strings are compared from left to right.
+
+  2. First the initial part of each string consisting entirely of
+     non-digit bytes is determined.
+
+       A. These two parts (either of which may be empty) are compared
+          lexically.  If a difference is found it is returned.
+
+       B. The lexical comparison is a lexicographic comparison of byte
+          strings, except that:
+
+            a. ASCII letters sort before other bytes.
+            b. A tilde sorts before anything, even an empty string.
+
+  3. Then the initial part of the remainder of each string that contains
+     all the leading digits is determined.  The numerical values
+     represented by these two parts are compared, and any difference
+     found is returned as the result of the comparison.
+
+       A. For these purposes an empty string (which can only occur at
+          the end of one or both version strings being compared) counts
+          as zero.
+
+       B. Because the numerical value is used, non-identical strings can
+          compare equal.  For example, ‘123’ compares equal to ‘00123’,
+          and the empty string compares equal to ‘0’.
+
+  4. These two steps (comparing and removing initial non-digit strings
+     and initial digit strings) are repeated until a difference is found
+     or both strings are exhausted.
+
+   Consider the version-sort comparison of two file names: ‘foo07.7z’
+and ‘foo7a.7z’.  The two strings will be broken down to the following
+parts, and the parts compared respectively from each string:
+
+     foo  vs  foo   (rule 2, non-digits)
+     07   vs  7     (rule 3, digits)
+     .    vs  a.    (rule 2)
+     7    vs  7     (rule 3)
+     z    vs  z     (rule 2)
+
+   Comparison flow based on above algorithm:
+
+  1. The first parts (‘foo’) are identical.
+
+  2. The second parts (‘07’ and ‘7’) are compared numerically, and
+     compare equal.
+
+  3. The third parts (‘.’ vs ‘a.’) are compared lexically by ASCII value
+     (rule 2.B).
+
+  4. The first byte of the first string (‘.’) is compared to the first
+     byte of the second string (‘a’).
+
+  5. Rule 2.B.a says letters sorts before non-letters.  Hence, ‘a’ comes
+     before ‘.’.
+
+  6. The returned result is that ‘foo7a.7z’ comes before ‘foo07.7z’.
+
+   Result when using sort:
+
+     $ cat input3
+     foo07.7z
+     foo7a.7z
+     $ sort -V input3
+     foo7a.7z
+     foo07.7z
+
+   See *note Differences from Debian version sort:: for additional rules
+that extend the Debian algorithm in Coreutils.
+
+
+File: coreutils.info,  Node: Version sort is not the same as numeric sort,  Next: Version sort punctuation,  Prev: Version-sort ordering rules,  Up: Version sort implementation
+
+30.2.2 Version sort is not the same as numeric sort
+---------------------------------------------------
+
+Consider the following text file:
+
+     $ cat input4
+     8.10
+     8.5
+     8.1
+     8.01
+     8.010
+     8.100
+     8.49
+
+     Numerical Sort:                   Version Sort:
+
+     $ sort -n input4                  $ sort -V input4
+     8.01                              8.01
+     8.010                             8.1
+     8.1                               8.5
+     8.10                              8.010
+     8.100                             8.10
+     8.49                              8.49
+     8.5                               8.100
+
+   Numeric sort (‘sort -n’) treats the entire string as a single numeric
+value, and compares it to other values.  For example, ‘8.1’, ‘8.10’ and
+‘8.100’ are numerically equivalent, and are ordered together.
+Similarly, ‘8.49’ is numerically less than ‘8.5’, and appears before
+first.
+
+   Version sort (‘sort -V’) first breaks down the string into digit and
+non-digit parts, and only then compares each part (see annotated example
+in *note Version-sort ordering rules::).
+
+   Comparing the string ‘8.1’ to ‘8.01’, first the ‘8’s are compared
+(and are identical), then the dots (‘.’) are compared and are identical,
+and lastly the remaining digits are compared numerically (‘1’ and ‘01’)
+– which are numerically equal.  Hence, ‘8.01’ and ‘8.1’ are grouped
+together.
+
+   Similarly, comparing ‘8.5’ to ‘8.49’ – the ‘8’ and ‘.’ parts are
+identical, then the numeric values ‘5’ and ‘49’ are compared.  The
+resulting ‘5’ appears before ‘49’.
+
+   This sorting order (where ‘8.5’ comes before ‘8.49’) is common when
+assigning versions to computer programs (while perhaps not intuitive or
+“natural” for people).
+
+
+File: coreutils.info,  Node: Version sort punctuation,  Next: Punctuation vs letters,  Prev: Version sort is not the same as numeric sort,  Up: Version sort implementation
+
+30.2.3 Version sort punctuation
+-------------------------------
+
+Punctuation is sorted by ASCII order (rule 2.B).
+
+     $ touch 1.0.5_src.tar.gz 1.0_src.tar.gz
+     $ ls -v -1
+     1.0.5_src.tar.gz
+     1.0_src.tar.gz
+
+   Why is ‘1.0.5_src.tar.gz’ listed before ‘1.0_src.tar.gz’?
+
+   Based on the version-sort ordering rules, the strings are broken down
+into the following parts:
+
+               1   vs  1               (rule 3, all digits)
+               .   vs  .               (rule 2, all non-digits)
+               0   vs  0               (rule 3)
+               .   vs  _src.tar.gz     (rule 2)
+               5   vs  empty string    (no more bytes in the file name)
+     _src.tar.gz   vs  empty string
+
+   The fourth parts (‘.’ and ‘_src.tar.gz’) are compared lexically by
+ASCII order.  The ‘.’ (ASCII value 46) is less than ‘_’ (ASCII value 95)
+– and should be listed before it.
+
+   Hence, ‘1.0.5_src.tar.gz’ is listed first.
+
+   If a different byte appears instead of the underscore (for example,
+percent sign ‘%’ ASCII value 37, which is less than dot’s ASCII value of
+46), that file will be listed first:
+
+     $ touch   1.0.5_src.tar.gz     1.0%zzzzz.gz
+     1.0%zzzzz.gz
+     1.0.5_src.tar.gz
+
+   The same reasoning applies to the following example, as ‘.’ with
+ASCII value 46 is less than ‘/’ with ASCII value 47:
+
+     $ cat input5
+     3.0/
+     3.0.5
+     $ sort -V input5
+     3.0.5
+     3.0/
+
+
+File: coreutils.info,  Node: Punctuation vs letters,  Next: The tilde ~,  Prev: Version sort punctuation,  Up: Version sort implementation
+
+30.2.4 Punctuation vs letters
+-----------------------------
+
+Rule 2.B.a says letters sort before non-letters (after breaking down a
+string to digit and non-digit parts).
+
+     $ cat input6
+     a%
+     az
+     $ sort -V input6
+     az
+     a%
+
+   The input strings consist entirely of non-digits, and based on the
+above algorithm have only one part, all non-digits (‘a%’ vs ‘az’).
+
+   Each part is then compared lexically, byte-by-byte; ‘a’ compares
+identically in both strings.
+
+   Rule 2.B.a says a letter like ‘z’ sorts before a non-letter like ‘%’
+– hence ‘az’ appears first (despite ‘z’ having ASCII value of 122, much
+larger than ‘%’ with ASCII value 37).
+
+
+File: coreutils.info,  Node: The tilde ~,  Next: Version sort ignores locale,  Prev: Punctuation vs letters,  Up: Version sort implementation
+
+30.2.5 The tilde ‘~’
+--------------------
+
+Rule 2.B.b says the tilde ‘~’ (ASCII 126) sorts before other bytes, and
+before an empty string.
+
+     $ cat input7
+     1
+     1%
+     1.2
+     1~
+     ~
+     $ sort -V input7
+     ~
+     1~
+     1
+     1%
+     1.2
+
+   The sorting algorithm starts by breaking down the string into
+non-digit (rule 2) and digit parts (rule 3).
+
+   In the above input file, only the last line in the input file starts
+with a non-digit (‘~’).  This is the first part.  All other lines in the
+input file start with a digit – their first non-digit part is empty.
+
+   Based on rule 2.B.b, tilde ‘~’ sorts before other bytes and before
+the empty string – hence it comes before all other strings, and is
+listed first in the sorted output.
+
+   The remaining lines (‘1’, ‘1%’, ‘1.2’, ‘1~’) follow similar logic:
+The digit part is extracted (1 for all strings) and compares equal.  The
+following extracted parts for the remaining input lines are: empty part,
+‘%’, ‘.’, ‘~’.
+
+   Tilde sorts before all others, hence the line ‘1~’ appears next.
+
+   The remaining lines (‘1’, ‘1%’, ‘1.2’) are sorted based on previously
+explained rules.
+
+
+File: coreutils.info,  Node: Version sort ignores locale,  Prev: The tilde ~,  Up: Version sort implementation
+
+30.2.6 Version sort ignores locale
+----------------------------------
+
+In version sort, Unicode characters are compared byte-by-byte according
+to their binary representation, ignoring their Unicode value or the
+current locale.
+
+   Most commonly, Unicode characters are encoded as UTF-8 bytes; for
+example, GREEK SMALL LETTER ALPHA (U+03B1, ‘α’) is encoded as the UTF-8
+sequence ‘0xCE 0xB1’).  The encoding is compared byte-by-byte, e.g.,
+first ‘0xCE’ (decimal value 206) then ‘0xB1’ (decimal value 177).
+
+     $ touch aa az "a%" "aα"
+     $ ls -1 -v
+     aa
+     az
+     a%
+     aα
+
+   Ignoring the first letter (‘a’) which is identical in all strings,
+the compared values are:
+
+   ‘a’ and ‘z’ are letters, and sort before all other non-digits.
+
+   Then, percent sign ‘%’ (ASCII value 37) is compared to the first byte
+of the UTF-8 sequence of ‘α’, which is 0xCE or 206).  The value 37 is
+smaller, hence ‘a%’ is listed before ‘aα’.
+
+
+File: coreutils.info,  Node: Differences from Debian version sort,  Next: Advanced version sort topics,  Prev: Version sort implementation,  Up: Version sort ordering
+
+30.3 Differences from Debian version sort
+=========================================
+
+GNU Coreutils version sort differs slightly from the official Debian
+algorithm, in order to accommodate more general usage and file name
+listing.
+
+* Menu:
+
+* Hyphen-minus and colon::
+* Special priority in GNU Coreutils version sort::
+* Special handling of file extensions::
+* Comparing two strings using Debian's algorithm::
+
+
+File: coreutils.info,  Node: Hyphen-minus and colon,  Next: Special priority in GNU Coreutils version sort,  Up: Differences from Debian version sort
+
+30.3.1 Hyphen-minus ‘-’ and colon ‘:’
+-------------------------------------
+
+In Debian’s version string syntax the version consists of three parts:
+     [epoch:]upstream_version[-debian_revision]
+   The ‘epoch’ and ‘debian_revision’ parts are optional.
+
+   Example of such version strings:
+
+     60.7.2esr-1~deb9u1
+     52.9.0esr-1~deb9u1
+     1:2.3.4-1+b2
+     327-2
+     1:1.0.13-3
+     2:1.19.2-1+deb9u5
+
+   If the ‘debian_revision part’ is not present, hyphens ‘-’ are not
+allowed.  If epoch is not present, colons ‘:’ are not allowed.
+
+   If these parts are present, hyphen and/or colons can appear only once
+in valid Debian version strings.
+
+   In GNU Coreutils, such restrictions are not reasonable (a file name
+can have many hyphens, a line of text can have many colons).
+
+   As a result, in GNU Coreutils hyphens and colons are treated exactly
+like all other punctuation, i.e., they are sorted after letters.  *Note
+Version sort punctuation::.
+
+   In Debian, these characters are treated differently than in
+Coreutils: a version string with hyphen will sort before similar strings
+without hyphens.
+
+   Compare:
+
+     $ touch 1ab-cd 1abb
+     $ ls -v -1
+     1abb
+     1ab-cd
+     $ if dpkg --compare-versions 1abb lt 1ab-cd
+     > then echo sorted
+     > else echo out of order
+     > fi
+     out of order
+
+   For further details, see *note Comparing two strings using Debian's
+algorithm:: and GNU Bug 35939 (https://bugs.gnu.org/35939).
+
+
+File: coreutils.info,  Node: Special priority in GNU Coreutils version sort,  Next: Special handling of file extensions,  Prev: Hyphen-minus and colon,  Up: Differences from Debian version sort
+
+30.3.2 Special priority in GNU Coreutils version sort
+-----------------------------------------------------
+
+In GNU Coreutils version sort, the following items have special priority
+and sort before all other strings (listed in order):
+
+  1. The empty string
+
+  2. The string ‘.’ (a single dot, ASCII 46)
+
+  3. The string ‘..’ (two dots)
+
+  4. Strings starting with dot (‘.’) sort before strings starting with
+     any other byte.
+
+   Example:
+
+     $ printf '%s\n' a "" b "." c  ".."  ".d20" ".d3"  | sort -V
+     .
+     ..
+     .d3
+     .d20
+     a
+     b
+     c
+
+   These priorities make perfect sense for ‘ls -v’: The special files
+dot ‘.’ and dot-dot ‘..’ will be listed first, followed by any hidden
+files (files starting with a dot), followed by non-hidden files.
+
+   For ‘sort -V’ these priorities might seem arbitrary.  However,
+because the sorting code is shared between the ‘ls’ and ‘sort’ program,
+the ordering rules are the same.
+
+
+File: coreutils.info,  Node: Special handling of file extensions,  Next: Comparing two strings using Debian's algorithm,  Prev: Special priority in GNU Coreutils version sort,  Up: Differences from Debian version sort
+
+30.3.3 Special handling of file extensions
+------------------------------------------
+
+GNU Coreutils version sort implements specialized handling of strings
+that look like file names with extensions.  This enables slightly more
+natural ordering of file names.
+
+   The following additional rules apply when comparing two strings where
+both begin with non-‘.’.  They also apply when comparing two strings
+where both begin with ‘.’ but neither is ‘.’ or ‘..’.
+
+  1. A suffix (i.e., a file extension) is defined as: a dot, followed by
+     an ASCII letter or tilde, followed by zero or more ASCII letters,
+     digits, or tildes; all repeated zero or more times, and ending at
+     string end.  This is equivalent to matching the extended regular
+     expression ‘(\.[A-Za-z~][A-Za-z0-9~]*)*$’ in the C locale.  The
+     longest such match is used, except that a suffix is not allowed to
+     match an entire nonempty string.
+
+  2. The suffixes are temporarily removed, and the strings are compared
+     without them, using version sort (see *note Version-sort ordering
+     rules::) without special priority (see *note Special priority in
+     GNU Coreutils version sort::).
+
+  3. If the suffix-less strings do not compare equal, this comparison
+     result is used and the suffixes are effectively ignored.
+
+  4. If the suffix-less strings compare equal, the suffixes are restored
+     and the entire strings are compared using version sort.
+
+   Examples for rule 1:
+
+   • ‘hello-8.txt’: the suffix is ‘.txt’
+
+   • ‘hello-8.2.txt’: the suffix is ‘.txt’ (‘.2’ is not included because
+     the dot is not followed by a letter)
+
+   • ‘hello-8.0.12.tar.gz’: the suffix is ‘.tar.gz’ (‘.0.12’ is not
+     included)
+
+   • ‘hello-8.2’: no suffix (suffix is an empty string)
+
+   • ‘hello.foobar65’: the suffix is ‘.foobar65’
+
+   • ‘gcc-c++-10.8.12-0.7rc2.fc9.tar.bz2’: the suffix is ‘.fc9.tar.bz2’
+     (‘.7rc2’ is not included as it begins with a digit)
+
+   • ‘.autom4te.cfg’: the suffix is the entire string.
+
+   Examples for rule 2:
+
+   • Comparing ‘hello-8.txt’ to ‘hello-8.2.12.txt’, the ‘.txt’ suffix is
+     temporarily removed from both strings.
+
+   • Comparing ‘foo-10.3.tar.gz’ to ‘foo-10.tar.xz’, the suffixes
+     ‘.tar.gz’ and ‘.tar.xz’ are temporarily removed from the strings.
+
+   Example for rule 3:
+
+   • Comparing ‘hello.foobar65’ to ‘hello.foobar4’, the suffixes
+     (‘.foobar65’ and ‘.foobar4’) are temporarily removed.  The
+     remaining strings are identical (‘hello’).  The suffixes are then
+     restored, and the entire strings are compared (‘hello.foobar4’
+     comes first).
+
+   Examples for rule 4:
+
+   • When comparing the strings ‘hello-8.2.txt’ and ‘hello-8.10.txt’,
+     the suffixes (‘.txt’) are temporarily removed.  The remaining
+     strings (‘hello-8.2’ and ‘hello-8.10’) are compared as previously
+     described (‘hello-8.2’ comes first).  (In this case the suffix
+     removal algorithm does not have a noticeable effect on the
+     resulting order.)
+
+   How does the suffix-removal algorithm effect ordering results?
+
+   Consider the comparison of hello-8.txt and hello-8.2.txt.
+
+   Without the suffix-removal algorithm, the strings will be broken down
+to the following parts:
+
+     hello-  vs  hello-  (rule 2, all non-digits)
+     8       vs  8       (rule 3, all digits)
+     .txt    vs  .       (rule 2)
+     empty   vs  2
+     empty   vs  .txt
+
+   The comparison of the third parts (‘.’ vs ‘.txt’) will determine that
+the shorter string comes first – resulting in ‘hello-8.2.txt’ appearing
+first.
+
+   Indeed this is the order in which Debian’s ‘dpkg’ compares the
+strings.
+
+   A more natural result is that ‘hello-8.txt’ should come before
+‘hello-8.2.txt’, and this is where the suffix-removal comes into play:
+
+   The suffixes (‘.txt’) are removed, and the remaining strings are
+broken down into the following parts:
+
+     hello-  vs  hello-  (rule 2, all non-digits)
+     8       vs  8       (rule 3, all digits)
+     empty   vs  .       (rule 2)
+     empty   vs  2
+
+   As empty strings sort before non-empty strings, the result is
+‘hello-8’ being first.
+
+   A real-world example would be listing files such as:
+‘gcc_10.fc9.tar.gz’ and ‘gcc_10.8.12.7rc2.fc9.tar.bz2’: Debian’s
+algorithm would list ‘gcc_10.8.12.7rc2.fc9.tar.bz2’ first, while ‘ls -v’
+will list ‘gcc_10.fc9.tar.gz’ first.
+
+   These priorities make sense for ‘ls -v’: Versioned files will be
+listed in a more natural order.
+
+   For ‘sort -V’ these priorities might seem arbitrary.  However,
+because the sorting code is shared between the ‘ls’ and ‘sort’ program,
+the ordering rules are the same.
+
+
+File: coreutils.info,  Node: Comparing two strings using Debian's algorithm,  Prev: Special handling of file extensions,  Up: Differences from Debian version sort
+
+30.3.4 Comparing two strings using Debian’s algorithm
+-----------------------------------------------------
+
+The Debian program ‘dpkg’ (available on all Debian and Ubuntu
+installations) can compare two strings using the ‘--compare-versions’
+option.
+
+   To use it, create a helper shell function (simply copy & paste the
+following snippet to your shell command-prompt):
+
+     compver() {
+       if dpkg --compare-versions "$1" lt "$2"
+       then printf '%s\n' "$1" "$2"
+       else printf '%s\n' "$2" "$1"
+       fi
+     }
+
+   Then compare two strings by calling ‘compver’:
+
+     $ compver 8.49 8.5
+     8.5
+     8.49
+
+   Note that ‘dpkg’ will warn if the strings have invalid syntax:
+
+     $ compver "foo07.7z" "foo7a.7z"
+     dpkg: warning: version 'foo07.7z' has bad syntax:
+                    version number does not start with digit
+     dpkg: warning: version 'foo7a.7z' has bad syntax:
+                    version number does not start with digit
+     foo7a.7z
+     foo07.7z
+     $ compver "3.0/" "3.0.5"
+     dpkg: warning: version '3.0/' has bad syntax:
+                    invalid character in version number
+     3.0.5
+     3.0/
+
+   To illustrate the different handling of hyphens between Debian and
+Coreutils algorithms (see *note Hyphen-minus and colon::):
+
+     $ compver abb ab-cd 2>/dev/null     $ printf 'abb\nab-cd\n' | sort -V
+     ab-cd                               abb
+     abb                                 ab-cd
+
+   To illustrate the different handling of file extension: (see *note
+Special handling of file extensions::):
+
+     $ compver hello-8.txt hello-8.2.txt 2>/dev/null
+     hello-8.2.txt
+     hello-8.txt
+     $ printf '%s\n' hello-8.txt hello-8.2.txt | sort -V
+     hello-8.txt
+     hello-8.2.txt
+
+
+File: coreutils.info,  Node: Advanced version sort topics,  Prev: Differences from Debian version sort,  Up: Version sort ordering
+
+30.4 Advanced Topics
+====================
+
+* Menu:
+
+* Reporting version sort bugs::
+* Other version/natural sort implementations::
+* Related source code::
+
+
+File: coreutils.info,  Node: Reporting version sort bugs,  Next: Other version/natural sort implementations,  Up: Advanced version sort topics
+
+30.4.1 Reporting version sort bugs
+----------------------------------
+
+If you suspect a bug in GNU Coreutils version sort (i.e., in the output
+of ‘ls -v’ or ‘sort -V’), please first check the following:
+
+  1. Is the result consistent with Debian’s own ordering (using ‘dpkg’,
+     see *note Comparing two strings using Debian's algorithm::)?  If it
+     is, then this is not a bug – please do not report it.
+
+  2. If the result differs from Debian’s, is it explained by one of the
+     sections in *note Differences from Debian version sort::?  If it
+     is, then this is not a bug – please do not report it.
+
+  3. If you have a question about specific ordering which is not
+     explained here, please write to <coreutils@gnu.org>, and provide a
+     concise example that will help us diagnose the issue.
+
+  4. If you still suspect a bug which is not explained by the above,
+     please write to <bug-coreutils@gnu.org> with a concrete example of
+     the suspected incorrect output, with details on why you think it is
+     incorrect.
+
+
+File: coreutils.info,  Node: Other version/natural sort implementations,  Next: Related source code,  Prev: Reporting version sort bugs,  Up: Advanced version sort topics
+
+30.4.2 Other version/natural sort implementations
+-------------------------------------------------
+
+As previously mentioned, there are multiple variations on
+version/natural sort, each with its own rules.  Some examples are:
+
+   • Natural Sorting variants in Rosetta Code
+     (https://rosettacode.org/wiki/Natural_sorting).
+
+   • Python’s natsort package (https://pypi.org/project/natsort/)
+     (includes detailed description of their sorting rules: natsort –
+     how it works
+     (https://natsort.readthedocs.io/en/master/howitworks.html)).
+
+   • Ruby’s version_sorter (https://github.com/github/version_sorter).
+
+   • Perl has multiple packages for natural and version sorts (each
+     likely with its own rules and nuances): Sort::Naturally
+     (https://metacpan.org/pod/Sort::Naturally), Sort::Versions
+     (https://metacpan.org/pod/Sort::Versions), CPAN::Version
+     (https://metacpan.org/pod/CPAN::Version).
+
+   • PHP has a built-in function natsort
+     (https://www.php.net/manual/en/function.natsort.php).
+
+   • NodeJS’s natural-sort package
+     (https://www.npmjs.com/package/natural-sort).
+
+   • In zsh, the glob modifier
+     (http://zsh.sourceforge.net/Doc/Release/Expansion.html#Glob-Qualifiers)
+     ‘*(n)’ will expand to files in natural sort order.
+
+   • When writing C programs, the GNU libc library (‘glibc’) provides
+     the strverscmp(3)
+     (https://man7.org/linux/man-pages/man3/strverscmp.3.html) function
+     to compare two strings, and versionsort(3)
+     (https://man7.org/linux/man-pages/man3/versionsort.3.html) function
+     to compare two directory entries (despite the names, they are not
+     identical to GNU Coreutils version sort ordering).
+
+   • Using Debian’s sorting algorithm in:
+
+        • python: Stack Overflow Example #4957741
+          (https://stackoverflow.com/a/4957741).
+
+        • NodeJS: deb-version-compare
+          (https://www.npmjs.com/package/deb-version-compare).
+
+
+File: coreutils.info,  Node: Related source code,  Prev: Other version/natural sort implementations,  Up: Advanced version sort topics
+
+30.4.3 Related source code
+--------------------------
+
+   • Debian’s code which splits a version string into
+     ‘epoch/upstream_version/debian_revision’ parts:
+     parsehelp.c:parseversion()
+     (https://git.dpkg.org/cgit/dpkg/dpkg.git/tree/lib/dpkg/parsehelp.c#n191).
+
+   • Debian’s code which performs the ‘upstream_version’ comparison:
+     version.c
+     (https://git.dpkg.org/cgit/dpkg/dpkg.git/tree/lib/dpkg/version.c#n140).
+
+   • Gnulib code (used by GNU Coreutils) which performs the version
+     comparison: filevercmp.c
+     (https://git.savannah.gnu.org/cgit/gnulib.git/tree/lib/filevercmp.c).
+
+
+File: coreutils.info,  Node: Opening the software toolbox,  Next: GNU Free Documentation License,  Prev: Version sort ordering,  Up: Top
+
+31 Opening the Software Toolbox
+*******************************
+
+An earlier version of this chapter appeared in the ‘What’s GNU?’  column
+of the June 1994 ‘Linux Journal’
+(https://www.linuxjournal.com/article.php?sid=2762).  It was written by
+Arnold Robbins.
+
+* Menu:
+
+* Toolbox introduction::        Toolbox introduction
+* I/O redirection::             I/O redirection
+* The who command::             The ‘who’ command
+* The cut command::             The ‘cut’ command
+* The sort command::            The ‘sort’ command
+* The uniq command::            The ‘uniq’ command
+* Putting the tools together::  Putting the tools together
+
+
+File: coreutils.info,  Node: Toolbox introduction,  Next: I/O redirection,  Up: Opening the software toolbox
+
+Toolbox Introduction
+====================
+
+This month’s column is only peripherally related to the GNU Project, in
+that it describes a number of the GNU tools on your GNU/Linux system and
+how they might be used.  What it’s really about is the “Software Tools”
+philosophy of program development and usage.
+
+   The software tools philosophy was an important and integral concept
+in the initial design and development of Unix (of which GNU/Linux and
+GNU are essentially clones).  Unfortunately, in the modern day press of
+Internetworking and flashy GUIs, it seems to have fallen by the wayside.
+This is a shame, since it provides a powerful mental model for solving
+many kinds of problems.
+
+   Many people carry a Swiss Army knife around in their pants pockets
+(or purse).  A Swiss Army knife is a handy tool to have: it has several
+knife blades, a screwdriver, tweezers, toothpick, nail file, corkscrew,
+and perhaps a number of other things on it.  For the everyday, small
+miscellaneous jobs where you need a simple, general purpose tool, it’s
+just the thing.
+
+   On the other hand, an experienced carpenter doesn’t build a house
+using a Swiss Army knife.  Instead, he has a toolbox chock full of
+specialized tools – a saw, a hammer, a screwdriver, a plane, and so on.
+And he knows exactly when and where to use each tool; you won’t catch
+him hammering nails with the handle of his screwdriver.
+
+   The Unix developers at Bell Labs were all professional programmers
+and trained computer scientists.  They had found that while a
+one-size-fits-all program might appeal to a user because there’s only
+one program to use, in practice such programs are
+
+  a. difficult to write,
+
+  b. difficult to maintain and debug, and
+
+  c. difficult to extend to meet new situations.
+
+   Instead, they felt that programs should be specialized tools.  In
+short, each program “should do one thing well.” No more and no less.
+Such programs are simpler to design, write, and get right – they only do
+one thing.
+
+   Furthermore, they found that with the right machinery for hooking
+programs together, that the whole was greater than the sum of the parts.
+By combining several special purpose programs, you could accomplish a
+specific task that none of the programs was designed for, and accomplish
+it much more quickly and easily than if you had to write a special
+purpose program.  We will see some (classic) examples of this further on
+in the column.  (An important additional point was that, if necessary,
+take a detour and build any software tools you may need first, if you
+don’t already have something appropriate in the toolbox.)
+
+
+File: coreutils.info,  Node: I/O redirection,  Next: The who command,  Prev: Toolbox introduction,  Up: Opening the software toolbox
+
+I/O Redirection
+===============
+
+Hopefully, you are familiar with the basics of I/O redirection in the
+shell, in particular the concepts of “standard input,” “standard
+output,” and “standard error”.  Briefly, “standard input” is a data
+source, where data comes from.  A program should not need to either know
+or care if the data source is a regular file, a keyboard, a magnetic
+tape, or even a punched card reader.  Similarly, “standard output” is a
+data sink, where data goes to.  The program should neither know nor care
+where this might be.  Programs that only read their standard input, do
+something to the data, and then send it on, are called “filters”, by
+analogy to filters in a water pipeline.
+
+   With the Unix shell, it’s very easy to set up data pipelines:
+
+     program_to_create_data | filter1 | ... | filterN > final.pretty.data
+
+   We start out by creating the raw data; each filter applies some
+successive transformation to the data, until by the time it comes out of
+the pipeline, it is in the desired form.
+
+   This is fine and good for standard input and standard output.  Where
+does the standard error come in to play?  Well, think about ‘filter1’ in
+the pipeline above.  What happens if it encounters an error in the data
+it sees?  If it writes an error message to standard output, it will just
+disappear down the pipeline into ‘filter2’’s input, and the user will
+probably never see it.  So programs need a place where they can send
+error messages so that the user will notice them.  This is standard
+error, and it is usually connected to your console or window, even if
+you have redirected standard output of your program away from your
+screen.
+
+   For filter programs to work together, the format of the data has to
+be agreed upon.  The most straightforward and easiest format to use is
+simply lines of text.  Unix data files are generally just streams of
+bytes, with lines delimited by the ASCII LF (Line Feed) character,
+conventionally called a “newline” in the Unix literature.  (This is
+‘'\n'’ if you’re a C programmer.)  This is the format used by all the
+traditional filtering programs.  (Many earlier operating systems had
+elaborate facilities and special purpose programs for managing binary
+data.  Unix has always shied away from such things, under the philosophy
+that it’s easiest to simply be able to view and edit your data with a
+text editor.)
+
+   OK, enough introduction.  Let’s take a look at some of the tools, and
+then we’ll see how to hook them together in interesting ways.  In the
+following discussion, we will only present those command line options
+that interest us.  As you should always do, double check your system
+documentation for the full story.
+
+
+File: coreutils.info,  Node: The who command,  Next: The cut command,  Prev: I/O redirection,  Up: Opening the software toolbox
+
+The ‘who’ Command
+=================
+
+The first program is the ‘who’ command.  By itself, it generates a list
+of the users who are currently logged in.  Although I’m writing this on
+a single-user system, we’ll pretend that several people are logged in:
+
+     $ who
+     ⊣ arnold   console Jan 22 19:57
+     ⊣ miriam   ttyp0   Jan 23 14:19(:0.0)
+     ⊣ bill     ttyp1   Jan 21 09:32(:0.0)
+     ⊣ arnold   ttyp2   Jan 23 20:48(:0.0)
+
+   Here, the ‘$’ is the usual shell prompt, at which I typed ‘who’.
+There are three people logged in, and I am logged in twice.  On
+traditional Unix systems, user names are never more than eight
+characters long.  This little bit of trivia will be useful later.  The
+output of ‘who’ is nice, but the data is not all that exciting.
+
+
+File: coreutils.info,  Node: The cut command,  Next: The sort command,  Prev: The who command,  Up: Opening the software toolbox
+
+The ‘cut’ Command
+=================
+
+The next program we’ll look at is the ‘cut’ command.  This program cuts
+out columns or fields of input data.  For example, we can tell it to
+print just the login name and full name from the ‘/etc/passwd’ file.
+The ‘/etc/passwd’ file has seven fields, separated by colons:
+
+     arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash
+
+   To get the first and fifth fields, we would use ‘cut’ like this:
+
+     $ cut -d: -f1,5 /etc/passwd
+     ⊣ root:Operator
+     ...
+     ⊣ arnold:Arnold D. Robbins
+     ⊣ miriam:Miriam A. Robbins
+     ...
+
+   With the ‘-c’ option, ‘cut’ will cut out specific characters (i.e.,
+columns) in the input lines.  This is useful for input data that has
+fixed width fields, and does not have a field separator.  For example,
+list the Monday dates for the current month:
+
+     $ cal | cut -c 3-5
+     ⊣Mo
+     ⊣
+     ⊣  6
+     ⊣ 13
+     ⊣ 20
+     ⊣ 27
+
+
+File: coreutils.info,  Node: The sort command,  Next: The uniq command,  Prev: The cut command,  Up: Opening the software toolbox
+
+The ‘sort’ Command
+==================
+
+Next we’ll look at the ‘sort’ command.  This is one of the most powerful
+commands on a Unix-style system; one that you will often find yourself
+using when setting up fancy data plumbing.
+
+   The ‘sort’ command reads and sorts each file named on the command
+line.  It then merges the sorted data and writes it to standard output.
+It will read standard input if no files are given on the command line
+(thus making it into a filter).  The sort is based on the character
+collating sequence or based on user-supplied ordering criteria.
+
+
+File: coreutils.info,  Node: The uniq command,  Next: Putting the tools together,  Prev: The sort command,  Up: Opening the software toolbox
+
+The ‘uniq’ Command
+==================
+
+Finally (at least for now), we’ll look at the ‘uniq’ program.  When
+sorting data, you will often end up with duplicate lines, lines that are
+identical.  Usually, all you need is one instance of each line.  This is
+where ‘uniq’ comes in.  The ‘uniq’ program reads its standard input.  It
+prints only one copy of each repeated line.  It does have several
+options.  Later on, we’ll use the ‘-c’ option, which prints each unique
+line, preceded by a count of the number of times that line occurred in
+the input.
+
+
+File: coreutils.info,  Node: Putting the tools together,  Prev: The uniq command,  Up: Opening the software toolbox
+
+Putting the Tools Together
+==========================
+
+Now, let’s suppose this is a large ISP server system with dozens of
+users logged in.  The management wants the system administrator to write
+a program that will generate a sorted list of logged in users.
+Furthermore, even if a user is logged in multiple times, his or her name
+should only show up in the output once.
+
+   The administrator could sit down with the system documentation and
+write a C program that did this.  It would take perhaps a couple of
+hundred lines of code and about two hours to write it, test it, and
+debug it.  However, knowing the software toolbox, the administrator can
+instead start out by generating just a list of logged on users:
+
+     $ who | cut -c1-8
+     ⊣ arnold
+     ⊣ miriam
+     ⊣ bill
+     ⊣ arnold
+
+   Next, sort the list:
+
+     $ who | cut -c1-8 | sort
+     ⊣ arnold
+     ⊣ arnold
+     ⊣ bill
+     ⊣ miriam
+
+   Finally, run the sorted list through ‘uniq’, to weed out duplicates:
+
+     $ who | cut -c1-8 | sort | uniq
+     ⊣ arnold
+     ⊣ bill
+     ⊣ miriam
+
+   The ‘sort’ command actually has a ‘-u’ option that does what ‘uniq’
+does.  However, ‘uniq’ has other uses for which one cannot substitute
+‘sort -u’.
+
+   The administrator puts this pipeline into a shell script, and makes
+it available for all the users on the system (‘#’ is the system
+administrator, or ‘root’, prompt):
+
+     # cat > /usr/local/bin/listusers
+     who | cut -c1-8 | sort | uniq
+     ^D
+     # chmod +x /usr/local/bin/listusers
+
+   There are four major points to note here.  First, with just four
+programs, on one command line, the administrator was able to save about
+two hours worth of work.  Furthermore, the shell pipeline is just about
+as efficient as the C program would be, and it is much more efficient in
+terms of programmer time.  People time is much more expensive than
+computer time, and in our modern “there’s never enough time to do
+everything” society, saving two hours of programmer time is no mean
+feat.
+
+   Second, it is also important to emphasize that with the _combination_
+of the tools, it is possible to do a special purpose job never imagined
+by the authors of the individual programs.
+
+   Third, it is also valuable to build up your pipeline in stages, as we
+did here.  This allows you to view the data at each stage in the
+pipeline, which helps you acquire the confidence that you are indeed
+using these tools correctly.
+
+   Finally, by bundling the pipeline in a shell script, other users can
+use your command, without having to remember the fancy plumbing you set
+up for them.  In terms of how you run them, shell scripts and compiled
+programs are indistinguishable.
+
+   After the previous warm-up exercise, we’ll look at two additional,
+more complicated pipelines.  For them, we need to introduce two more
+tools.
+
+   The first is the ‘tr’ command, which stands for “transliterate.” The
+‘tr’ command works on a character-by-character basis, changing
+characters.  Normally it is used for things like mapping upper case to
+lower case:
+
+     $ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]'
+     ⊣ this example has mixed case!
+
+   There are several options of interest:
+
+‘-c’
+     work on the complement of the listed characters, i.e., operations
+     apply to characters not in the given set
+
+‘-d’
+     delete characters in the first set from the output
+
+‘-s’
+     squeeze repeated characters in the output into just one character.
+
+   We will be using all three options in a moment.
+
+   The other command we’ll look at is ‘comm’.  The ‘comm’ command takes
+two sorted input files as input data, and prints out the files’ lines in
+three columns.  The output columns are the data lines unique to the
+first file, the data lines unique to the second file, and the data lines
+that are common to both.  The ‘-1’, ‘-2’, and ‘-3’ command line options
+_omit_ the respective columns.  (This is non-intuitive and takes a
+little getting used to.)  For example:
+
+     $ cat f1
+     ⊣ 11111
+     ⊣ 22222
+     ⊣ 33333
+     ⊣ 44444
+     $ cat f2
+     ⊣ 00000
+     ⊣ 22222
+     ⊣ 33333
+     ⊣ 55555
+     $ comm f1 f2
+     ⊣         00000
+     ⊣ 11111
+     ⊣                 22222
+     ⊣                 33333
+     ⊣ 44444
+     ⊣         55555
+
+   The file name ‘-’ tells ‘comm’ to read standard input instead of a
+regular file.
+
+   Now we’re ready to build a fancy pipeline.  The first application is
+a word frequency counter.  This helps an author determine if he or she
+is over-using certain words.
+
+   The first step is to change the case of all the letters in our input
+file to one case.  “The” and “the” are the same word when doing
+counting.
+
+     $ tr '[:upper:]' '[:lower:]' < whats.gnu | ...
+
+   The next step is to get rid of punctuation.  Quoted words and
+unquoted words should be treated identically; it’s easiest to just get
+the punctuation out of the way.
+
+     $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ...
+
+   The second ‘tr’ command operates on the complement of the listed
+characters, which are all the letters, the digits, the underscore, and
+the blank.  The ‘\n’ represents the newline character; it has to be left
+alone.  (The ASCII tab character should also be included for good
+measure in a production script.)
+
+   At this point, we have data consisting of words separated by blank
+space.  The words only contain alphanumeric characters (and the
+underscore).  The next step is break the data apart so that we have one
+word per line.  This makes the counting operation much easier, as we
+will see shortly.
+
+     $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+     > tr -s ' ' '\n' | ...
+
+   This command turns blanks into newlines.  The ‘-s’ option squeezes
+multiple newline characters in the output into just one, removing blank
+lines.  (The ‘>’ is the shell’s “secondary prompt.” This is what the
+shell prints when it notices you haven’t finished typing in all of a
+command.)
+
+   We now have data consisting of one word per line, no punctuation, all
+one case.  We’re ready to count each word:
+
+     $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+     > tr -s ' ' '\n' | sort | uniq -c | ...
+
+   At this point, the data might look something like this:
+
+          60 a
+           2 able
+           6 about
+           1 above
+           2 accomplish
+           1 acquire
+           1 actually
+           2 additional
+
+   The output is sorted by word, not by count!  What we want is the most
+frequently used words first.  Fortunately, this is easy to accomplish,
+with the help of two more ‘sort’ options:
+
+‘-n’
+     do a numeric sort, not a textual one
+
+‘-r’
+     reverse the order of the sort
+
+   The final pipeline looks like this:
+
+     $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+     > tr -s ' ' '\n' | sort | uniq -c | sort -n -r
+     ⊣    156 the
+     ⊣     60 a
+     ⊣     58 to
+     ⊣     51 of
+     ⊣     51 and
+     ...
+
+   Whew!  That’s a lot to digest.  Yet, the same principles apply.  With
+six commands, on two lines (really one long one split for convenience),
+we’ve created a program that does something interesting and useful, in
+much less time than we could have written a C program to do the same
+thing.
+
+   A minor modification to the above pipeline can give us a simple
+spelling checker!  To determine if you’ve spelled a word correctly, all
+you have to do is look it up in a dictionary.  If it is not there, then
+chances are that your spelling is incorrect.  So, we need a dictionary.
+The conventional location for a dictionary is ‘/usr/share/dict/words’.
+
+   Now, how to compare our file with the dictionary?  As before, we
+generate a sorted list of words, one per line:
+
+     $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+     > tr -s ' ' '\n' | sort -u | ...
+
+   Now, all we need is a list of words that are _not_ in the dictionary.
+Here is where the ‘comm’ command comes in.  Unfortunately ‘comm’
+operates on sorted input and ‘/usr/share/dict/words’ is not sorted the
+way that ‘sort’ and ‘comm’ normally use, so we first create a
+properly-sorted copy of the dictionary and then run a pipeline that uses
+the copy.
+
+     $ sort /usr/share/dict/words > sorted-words
+     $ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+     > tr -s ' ' '\n' | sort -u |
+     > comm -23 - sorted-words
+
+   The ‘-2’ and ‘-3’ options eliminate lines that are only in the
+dictionary (the second file), and lines that are in both files.  Lines
+only in the first file (standard input, our stream of words), are words
+that are not in the dictionary.  These are likely candidates for
+spelling errors.  This pipeline was the first cut at a production
+spelling checker on Unix.
+
+   There are some other tools that deserve brief mention.
+
+‘grep’
+     search files for text that matches a regular expression
+
+‘wc’
+     count lines, words, characters
+
+‘tee’
+     a T-fitting for data pipes, copies data to files and to standard
+     output
+
+‘sed’
+     the stream editor, an advanced tool
+
+‘awk’
+     a data manipulation language, another advanced tool
+
+   The software tools philosophy also espoused the following bit of
+advice: “Let someone else do the hard part.” This means, take something
+that gives you most of what you need, and then massage it the rest of
+the way until it’s in the form that you want.
+
+   To summarize:
+
+  1. Each program should do one thing well.  No more, no less.
+
+  2. Combining programs with appropriate plumbing leads to results where
+     the whole is greater than the sum of the parts.  It also leads to
+     novel uses of programs that the authors might never have imagined.
+
+  3. Programs should never print extraneous header or trailer data,
+     since these could get sent on down a pipeline.  (A point we didn’t
+     mention earlier.)
+
+  4. Let someone else do the hard part.
+
+  5. Know your toolbox!  Use each program appropriately.  If you don’t
+     have an appropriate tool, build one.
+
+   All the programs discussed are available as described in GNU core
+utilities (https://www.gnu.org/software/coreutils/coreutils.html).
+
+   None of what I have presented in this column is new.  The Software
+Tools philosophy was first introduced in the book ‘Software Tools’, by
+Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X).
+This book showed how to write and use software tools.  It was written in
+1976, using a preprocessor for FORTRAN named ‘ratfor’ (RATional
+FORtran).  At the time, C was not as ubiquitous as it is now; FORTRAN
+was.  The last chapter presented a ‘ratfor’ to FORTRAN processor,
+written in ‘ratfor’.  ‘ratfor’ looks an awful lot like C; if you know C,
+you won’t have any problem following the code.
+
+   In 1981, the book was updated and made available as ‘Software Tools
+in Pascal’ (Addison-Wesley, ISBN 0-201-10342-7).  Both books are still
+in print and are well worth reading if you’re a programmer.  They
+certainly made a major change in how I view programming.
+
+   The programs in both books are available from Brian Kernighan’s home
+page (https://www.cs.princeton.edu/~bwk/).  For a number of years, there
+was an active Software Tools Users Group, whose members had ported the
+original ‘ratfor’ programs to essentially every computer system with a
+FORTRAN compiler.  The popularity of the group waned in the middle 1980s
+as Unix began to spread beyond universities.
+
+   With the current proliferation of GNU code and other clones of Unix
+programs, these programs now receive little attention; modern C versions
+are much more efficient and do more than these programs do.
+Nevertheless, as exposition of good programming style, and evangelism
+for a still-valuable philosophy, these books are unparalleled, and I
+recommend them highly.
+
+   Acknowledgment: I would like to express my gratitude to Brian
+Kernighan of Bell Labs, the original Software Toolsmith, for reviewing
+this column.
+
+
+File: coreutils.info,  Node: GNU Free Documentation License,  Next: Concept index,  Prev: Opening the software toolbox,  Up: Top
+
+Appendix A GNU Free Documentation License
+*****************************************
+
+                     Version 1.3, 3 November 2008
+
+     Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+     <https://fsf.org/>
+
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+  0. PREAMBLE
+
+     The purpose of this License is to make a manual, textbook, or other
+     functional and useful document “free” in the sense of freedom: to
+     assure everyone the effective freedom to copy and redistribute it,
+     with or without modifying it, either commercially or
+     noncommercially.  Secondarily, this License preserves for the
+     author and publisher a way to get credit for their work, while not
+     being considered responsible for modifications made by others.
+
+     This License is a kind of “copyleft”, which means that derivative
+     works of the document must themselves be free in the same sense.
+     It complements the GNU General Public License, which is a copyleft
+     license designed for free software.
+
+     We have designed this License in order to use it for manuals for
+     free software, because free software needs free documentation: a
+     free program should come with manuals providing the same freedoms
+     that the software does.  But this License is not limited to
+     software manuals; it can be used for any textual work, regardless
+     of subject matter or whether it is published as a printed book.  We
+     recommend this License principally for works whose purpose is
+     instruction or reference.
+
+  1. APPLICABILITY AND DEFINITIONS
+
+     This License applies to any manual or other work, in any medium,
+     that contains a notice placed by the copyright holder saying it can
+     be distributed under the terms of this License.  Such a notice
+     grants a world-wide, royalty-free license, unlimited in duration,
+     to use that work under the conditions stated herein.  The
+     “Document”, below, refers to any such manual or work.  Any member
+     of the public is a licensee, and is addressed as “you”.  You accept
+     the license if you copy, modify or distribute the work in a way
+     requiring permission under copyright law.
+
+     A “Modified Version” of the Document means any work containing the
+     Document or a portion of it, either copied verbatim, or with
+     modifications and/or translated into another language.
+
+     A “Secondary Section” is a named appendix or a front-matter section
+     of the Document that deals exclusively with the relationship of the
+     publishers or authors of the Document to the Document’s overall
+     subject (or to related matters) and contains nothing that could
+     fall directly within that overall subject.  (Thus, if the Document
+     is in part a textbook of mathematics, a Secondary Section may not
+     explain any mathematics.)  The relationship could be a matter of
+     historical connection with the subject or with related matters, or
+     of legal, commercial, philosophical, ethical or political position
+     regarding them.
+
+     The “Invariant Sections” are certain Secondary Sections whose
+     titles are designated, as being those of Invariant Sections, in the
+     notice that says that the Document is released under this License.
+     If a section does not fit the above definition of Secondary then it
+     is not allowed to be designated as Invariant.  The Document may
+     contain zero Invariant Sections.  If the Document does not identify
+     any Invariant Sections then there are none.
+
+     The “Cover Texts” are certain short passages of text that are
+     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+     that says that the Document is released under this License.  A
+     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+     be at most 25 words.
+
+     A “Transparent” copy of the Document means a machine-readable copy,
+     represented in a format whose specification is available to the
+     general public, that is suitable for revising the document
+     straightforwardly with generic text editors or (for images composed
+     of pixels) generic paint programs or (for drawings) some widely
+     available drawing editor, and that is suitable for input to text
+     formatters or for automatic translation to a variety of formats
+     suitable for input to text formatters.  A copy made in an otherwise
+     Transparent file format whose markup, or absence of markup, has
+     been arranged to thwart or discourage subsequent modification by
+     readers is not Transparent.  An image format is not Transparent if
+     used for any substantial amount of text.  A copy that is not
+     “Transparent” is called “Opaque”.
+
+     Examples of suitable formats for Transparent copies include plain
+     ASCII without markup, Texinfo input format, LaTeX input format,
+     SGML or XML using a publicly available DTD, and standard-conforming
+     simple HTML, PostScript or PDF designed for human modification.
+     Examples of transparent image formats include PNG, XCF and JPG.
+     Opaque formats include proprietary formats that can be read and
+     edited only by proprietary word processors, SGML or XML for which
+     the DTD and/or processing tools are not generally available, and
+     the machine-generated HTML, PostScript or PDF produced by some word
+     processors for output purposes only.
+
+     The “Title Page” means, for a printed book, the title page itself,
+     plus such following pages as are needed to hold, legibly, the
+     material this License requires to appear in the title page.  For
+     works in formats which do not have any title page as such, “Title
+     Page” means the text near the most prominent appearance of the
+     work’s title, preceding the beginning of the body of the text.
+
+     The “publisher” means any person or entity that distributes copies
+     of the Document to the public.
+
+     A section “Entitled XYZ” means a named subunit of the Document
+     whose title either is precisely XYZ or contains XYZ in parentheses
+     following text that translates XYZ in another language.  (Here XYZ
+     stands for a specific section name mentioned below, such as
+     “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.)
+     To “Preserve the Title” of such a section when you modify the
+     Document means that it remains a section “Entitled XYZ” according
+     to this definition.
+
+     The Document may include Warranty Disclaimers next to the notice
+     which states that this License applies to the Document.  These
+     Warranty Disclaimers are considered to be included by reference in
+     this License, but only as regards disclaiming warranties: any other
+     implication that these Warranty Disclaimers may have is void and
+     has no effect on the meaning of this License.
+
+  2. VERBATIM COPYING
+
+     You may copy and distribute the Document in any medium, either
+     commercially or noncommercially, provided that this License, the
+     copyright notices, and the license notice saying this License
+     applies to the Document are reproduced in all copies, and that you
+     add no other conditions whatsoever to those of this License.  You
+     may not use technical measures to obstruct or control the reading
+     or further copying of the copies you make or distribute.  However,
+     you may accept compensation in exchange for copies.  If you
+     distribute a large enough number of copies you must also follow the
+     conditions in section 3.
+
+     You may also lend copies, under the same conditions stated above,
+     and you may publicly display copies.
+
+  3. COPYING IN QUANTITY
+
+     If you publish printed copies (or copies in media that commonly
+     have printed covers) of the Document, numbering more than 100, and
+     the Document’s license notice requires Cover Texts, you must
+     enclose the copies in covers that carry, clearly and legibly, all
+     these Cover Texts: Front-Cover Texts on the front cover, and
+     Back-Cover Texts on the back cover.  Both covers must also clearly
+     and legibly identify you as the publisher of these copies.  The
+     front cover must present the full title with all words of the title
+     equally prominent and visible.  You may add other material on the
+     covers in addition.  Copying with changes limited to the covers, as
+     long as they preserve the title of the Document and satisfy these
+     conditions, can be treated as verbatim copying in other respects.
+
+     If the required texts for either cover are too voluminous to fit
+     legibly, you should put the first ones listed (as many as fit
+     reasonably) on the actual cover, and continue the rest onto
+     adjacent pages.
+
+     If you publish or distribute Opaque copies of the Document
+     numbering more than 100, you must either include a machine-readable
+     Transparent copy along with each Opaque copy, or state in or with
+     each Opaque copy a computer-network location from which the general
+     network-using public has access to download using public-standard
+     network protocols a complete Transparent copy of the Document, free
+     of added material.  If you use the latter option, you must take
+     reasonably prudent steps, when you begin distribution of Opaque
+     copies in quantity, to ensure that this Transparent copy will
+     remain thus accessible at the stated location until at least one
+     year after the last time you distribute an Opaque copy (directly or
+     through your agents or retailers) of that edition to the public.
+
+     It is requested, but not required, that you contact the authors of
+     the Document well before redistributing any large number of copies,
+     to give them a chance to provide you with an updated version of the
+     Document.
+
+  4. MODIFICATIONS
+
+     You may copy and distribute a Modified Version of the Document
+     under the conditions of sections 2 and 3 above, provided that you
+     release the Modified Version under precisely this License, with the
+     Modified Version filling the role of the Document, thus licensing
+     distribution and modification of the Modified Version to whoever
+     possesses a copy of it.  In addition, you must do these things in
+     the Modified Version:
+
+       A. Use in the Title Page (and on the covers, if any) a title
+          distinct from that of the Document, and from those of previous
+          versions (which should, if there were any, be listed in the
+          History section of the Document).  You may use the same title
+          as a previous version if the original publisher of that
+          version gives permission.
+
+       B. List on the Title Page, as authors, one or more persons or
+          entities responsible for authorship of the modifications in
+          the Modified Version, together with at least five of the
+          principal authors of the Document (all of its principal
+          authors, if it has fewer than five), unless they release you
+          from this requirement.
+
+       C. State on the Title page the name of the publisher of the
+          Modified Version, as the publisher.
+
+       D. Preserve all the copyright notices of the Document.
+
+       E. Add an appropriate copyright notice for your modifications
+          adjacent to the other copyright notices.
+
+       F. Include, immediately after the copyright notices, a license
+          notice giving the public permission to use the Modified
+          Version under the terms of this License, in the form shown in
+          the Addendum below.
+
+       G. Preserve in that license notice the full lists of Invariant
+          Sections and required Cover Texts given in the Document’s
+          license notice.
+
+       H. Include an unaltered copy of this License.
+
+       I. Preserve the section Entitled “History”, Preserve its Title,
+          and add to it an item stating at least the title, year, new
+          authors, and publisher of the Modified Version as given on the
+          Title Page.  If there is no section Entitled “History” in the
+          Document, create one stating the title, year, authors, and
+          publisher of the Document as given on its Title Page, then add
+          an item describing the Modified Version as stated in the
+          previous sentence.
+
+       J. Preserve the network location, if any, given in the Document
+          for public access to a Transparent copy of the Document, and
+          likewise the network locations given in the Document for
+          previous versions it was based on.  These may be placed in the
+          “History” section.  You may omit a network location for a work
+          that was published at least four years before the Document
+          itself, or if the original publisher of the version it refers
+          to gives permission.
+
+       K. For any section Entitled “Acknowledgements” or “Dedications”,
+          Preserve the Title of the section, and preserve in the section
+          all the substance and tone of each of the contributor
+          acknowledgements and/or dedications given therein.
+
+       L. Preserve all the Invariant Sections of the Document, unaltered
+          in their text and in their titles.  Section numbers or the
+          equivalent are not considered part of the section titles.
+
+       M. Delete any section Entitled “Endorsements”.  Such a section
+          may not be included in the Modified Version.
+
+       N. Do not retitle any existing section to be Entitled
+          “Endorsements” or to conflict in title with any Invariant
+          Section.
+
+       O. Preserve any Warranty Disclaimers.
+
+     If the Modified Version includes new front-matter sections or
+     appendices that qualify as Secondary Sections and contain no
+     material copied from the Document, you may at your option designate
+     some or all of these sections as invariant.  To do this, add their
+     titles to the list of Invariant Sections in the Modified Version’s
+     license notice.  These titles must be distinct from any other
+     section titles.
+
+     You may add a section Entitled “Endorsements”, provided it contains
+     nothing but endorsements of your Modified Version by various
+     parties—for example, statements of peer review or that the text has
+     been approved by an organization as the authoritative definition of
+     a standard.
+
+     You may add a passage of up to five words as a Front-Cover Text,
+     and a passage of up to 25 words as a Back-Cover Text, to the end of
+     the list of Cover Texts in the Modified Version.  Only one passage
+     of Front-Cover Text and one of Back-Cover Text may be added by (or
+     through arrangements made by) any one entity.  If the Document
+     already includes a cover text for the same cover, previously added
+     by you or by arrangement made by the same entity you are acting on
+     behalf of, you may not add another; but you may replace the old
+     one, on explicit permission from the previous publisher that added
+     the old one.
+
+     The author(s) and publisher(s) of the Document do not by this
+     License give permission to use their names for publicity for or to
+     assert or imply endorsement of any Modified Version.
+
+  5. COMBINING DOCUMENTS
+
+     You may combine the Document with other documents released under
+     this License, under the terms defined in section 4 above for
+     modified versions, provided that you include in the combination all
+     of the Invariant Sections of all of the original documents,
+     unmodified, and list them all as Invariant Sections of your
+     combined work in its license notice, and that you preserve all
+     their Warranty Disclaimers.
+
+     The combined work need only contain one copy of this License, and
+     multiple identical Invariant Sections may be replaced with a single
+     copy.  If there are multiple Invariant Sections with the same name
+     but different contents, make the title of each such section unique
+     by adding at the end of it, in parentheses, the name of the
+     original author or publisher of that section if known, or else a
+     unique number.  Make the same adjustment to the section titles in
+     the list of Invariant Sections in the license notice of the
+     combined work.
+
+     In the combination, you must combine any sections Entitled
+     “History” in the various original documents, forming one section
+     Entitled “History”; likewise combine any sections Entitled
+     “Acknowledgements”, and any sections Entitled “Dedications”.  You
+     must delete all sections Entitled “Endorsements.”
+
+  6. COLLECTIONS OF DOCUMENTS
+
+     You may make a collection consisting of the Document and other
+     documents released under this License, and replace the individual
+     copies of this License in the various documents with a single copy
+     that is included in the collection, provided that you follow the
+     rules of this License for verbatim copying of each of the documents
+     in all other respects.
+
+     You may extract a single document from such a collection, and
+     distribute it individually under this License, provided you insert
+     a copy of this License into the extracted document, and follow this
+     License in all other respects regarding verbatim copying of that
+     document.
+
+  7. AGGREGATION WITH INDEPENDENT WORKS
+
+     A compilation of the Document or its derivatives with other
+     separate and independent documents or works, in or on a volume of a
+     storage or distribution medium, is called an “aggregate” if the
+     copyright resulting from the compilation is not used to limit the
+     legal rights of the compilation’s users beyond what the individual
+     works permit.  When the Document is included in an aggregate, this
+     License does not apply to the other works in the aggregate which
+     are not themselves derivative works of the Document.
+
+     If the Cover Text requirement of section 3 is applicable to these
+     copies of the Document, then if the Document is less than one half
+     of the entire aggregate, the Document’s Cover Texts may be placed
+     on covers that bracket the Document within the aggregate, or the
+     electronic equivalent of covers if the Document is in electronic
+     form.  Otherwise they must appear on printed covers that bracket
+     the whole aggregate.
+
+  8. TRANSLATION
+
+     Translation is considered a kind of modification, so you may
+     distribute translations of the Document under the terms of section
+     4.  Replacing Invariant Sections with translations requires special
+     permission from their copyright holders, but you may include
+     translations of some or all Invariant Sections in addition to the
+     original versions of these Invariant Sections.  You may include a
+     translation of this License, and all the license notices in the
+     Document, and any Warranty Disclaimers, provided that you also
+     include the original English version of this License and the
+     original versions of those notices and disclaimers.  In case of a
+     disagreement between the translation and the original version of
+     this License or a notice or disclaimer, the original version will
+     prevail.
+
+     If a section in the Document is Entitled “Acknowledgements”,
+     “Dedications”, or “History”, the requirement (section 4) to
+     Preserve its Title (section 1) will typically require changing the
+     actual title.
+
+  9. TERMINATION
+
+     You may not copy, modify, sublicense, or distribute the Document
+     except as expressly provided under this License.  Any attempt
+     otherwise to copy, modify, sublicense, or distribute it is void,
+     and will automatically terminate your rights under this License.
+
+     However, if you cease all violation of this License, then your
+     license from a particular copyright holder is reinstated (a)
+     provisionally, unless and until the copyright holder explicitly and
+     finally terminates your license, and (b) permanently, if the
+     copyright holder fails to notify you of the violation by some
+     reasonable means prior to 60 days after the cessation.
+
+     Moreover, your license from a particular copyright holder is
+     reinstated permanently if the copyright holder notifies you of the
+     violation by some reasonable means, this is the first time you have
+     received notice of violation of this License (for any work) from
+     that copyright holder, and you cure the violation prior to 30 days
+     after your receipt of the notice.
+
+     Termination of your rights under this section does not terminate
+     the licenses of parties who have received copies or rights from you
+     under this License.  If your rights have been terminated and not
+     permanently reinstated, receipt of a copy of some or all of the
+     same material does not give you any rights to use it.
+
+  10. FUTURE REVISIONS OF THIS LICENSE
+
+     The Free Software Foundation may publish new, revised versions of
+     the GNU Free Documentation License from time to time.  Such new
+     versions will be similar in spirit to the present version, but may
+     differ in detail to address new problems or concerns.  See
+     <https://www.gnu.org/licenses/>.
+
+     Each version of the License is given a distinguishing version
+     number.  If the Document specifies that a particular numbered
+     version of this License “or any later version” applies to it, you
+     have the option of following the terms and conditions either of
+     that specified version or of any later version that has been
+     published (not as a draft) by the Free Software Foundation.  If the
+     Document does not specify a version number of this License, you may
+     choose any version ever published (not as a draft) by the Free
+     Software Foundation.  If the Document specifies that a proxy can
+     decide which future versions of this License can be used, that
+     proxy’s public statement of acceptance of a version permanently
+     authorizes you to choose that version for the Document.
+
+  11. RELICENSING
+
+     “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
+     World Wide Web server that publishes copyrightable works and also
+     provides prominent facilities for anybody to edit those works.  A
+     public wiki that anybody can edit is an example of such a server.
+     A “Massive Multiauthor Collaboration” (or “MMC”) contained in the
+     site means any set of copyrightable works thus published on the MMC
+     site.
+
+     “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
+     license published by Creative Commons Corporation, a not-for-profit
+     corporation with a principal place of business in San Francisco,
+     California, as well as future copyleft versions of that license
+     published by that same organization.
+
+     “Incorporate” means to publish or republish a Document, in whole or
+     in part, as part of another Document.
+
+     An MMC is “eligible for relicensing” if it is licensed under this
+     License, and if all works that were first published under this
+     License somewhere other than this MMC, and subsequently
+     incorporated in whole or in part into the MMC, (1) had no cover
+     texts or invariant sections, and (2) were thus incorporated prior
+     to November 1, 2008.
+
+     The operator of an MMC Site may republish an MMC contained in the
+     site under CC-BY-SA on the same site at any time before August 1,
+     2009, provided the MMC is eligible for relicensing.
+
+ADDENDUM: How to use this License for your documents
+====================================================
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+       Copyright (C)  YEAR  YOUR NAME.
+       Permission is granted to copy, distribute and/or modify this document
+       under the terms of the GNU Free Documentation License, Version 1.3
+       or any later version published by the Free Software Foundation;
+       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+       Texts.  A copy of the license is included in the section entitled ``GNU
+       Free Documentation License''.
+
+   If you have Invariant Sections, Front-Cover Texts and Back-Cover
+Texts, replace the “with...Texts.” line with this:
+
+         with the Invariant Sections being LIST THEIR TITLES, with
+         the Front-Cover Texts being LIST, and with the Back-Cover Texts
+         being LIST.
+
+   If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+   If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of free
+software license, such as the GNU General Public License, to permit
+their use in free software.
+
+
+File: coreutils.info,  Node: Concept index,  Prev: GNU Free Documentation License,  Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* !:                                     Connectives for test.
+                                                              (line  23)
+* !=:                                    String tests.        (line  29)
+* %:                                     Numeric expressions. (line  16)
+* %b:                                    printf invocation.   (line  37)
+* %q:                                    printf invocation.   (line  44)
+* &:                                     Relations for expr.  (line  17)
+* *:                                     Numeric expressions. (line  16)
+* +:                                     String expressions.  (line  51)
+* + <1>:                                 Numeric expressions. (line  12)
+* +PAGE_RANGE:                           pr invocation.       (line  39)
+* -:                                     Numeric expressions. (line  12)
+* - <1>:                                 env invocation.      (line 102)
+* - and Unix rm:                         rm invocation.       (line 114)
+* -, removing files beginning with:      rm invocation.       (line 102)
+* --:                                    Common options.      (line  43)
+* --across:                              pr invocation.       (line  62)
+* --additional-suffix:                   split invocation.    (line 139)
+* --address-radix:                       od invocation.       (line  36)
+* --adjustment:                          nice invocation.     (line  51)
+* --algorithm:                           cksum general options.
+                                                              (line   5)
+* --all:                                 unexpand invocation. (line  51)
+* --all <1>:                             Which files are listed.
+                                                              (line  13)
+* --all <2>:                             df invocation.       (line  42)
+* --all <3>:                             du invocation.       (line  31)
+* --all <4>:                             stty invocation.     (line  26)
+* --all <5>:                             who invocation.      (line  35)
+* --all <6>:                             nproc invocation.    (line  20)
+* --all <7>:                             uname invocation.    (line  30)
+* --all-repeated:                        uniq invocation.     (line  70)
+* --almost-all:                          Which files are listed.
+                                                              (line  17)
+* --apparent-size:                       du invocation.       (line  34)
+* --append:                              tee invocation.      (line  26)
+* --archive:                             cp invocation.       (line  63)
+* --attributes-only:                     cp invocation.       (line  72)
+* --author:                              What information is listed.
+                                                              (line  10)
+* --auto-reference:                      Output formatting in ptx.
+                                                              (line  45)
+* --backup:                              Backup options.      (line  13)
+* --backup <1>:                          cp invocation.       (line  79)
+* --backup <2>:                          install invocation.  (line  41)
+* --backup <3>:                          mv invocation.       (line  56)
+* --backup <4>:                          ln invocation.       (line  82)
+* --base16:                              basenc invocation.   (line  49)
+* --base2lsbf:                           basenc invocation.   (line  55)
+* --base2msbf:                           basenc invocation.   (line  59)
+* --base32:                              basenc invocation.   (line  35)
+* --base32hex:                           basenc invocation.   (line  42)
+* --base64:                              basenc invocation.   (line  23)
+* --base64 <1>:                          cksum general options.
+                                                              (line  23)
+* --base64url:                           basenc invocation.   (line  29)
+* --batch-size:                          sort invocation.     (line 268)
+* --before:                              tac invocation.      (line  21)
+* --binary:                              cksum common options.
+                                                              (line   5)
+* --block-size:                          Block size.          (line 131)
+* --block-size <1>:                      df invocation.       (line  54)
+* --block-size <2>:                      du invocation.       (line  54)
+* --block-size=SIZE:                     Block size.          (line  12)
+* --body-numbering:                      nl invocation.       (line  45)
+* --boot:                                who invocation.      (line  39)
+* --bourne-shell:                        dircolors invocation.
+                                                              (line  34)
+* --break-file:                          Input processing in ptx.
+                                                              (line   8)
+* --buffer-size:                         sort invocation.     (line 322)
+* --bytes:                               fold invocation.     (line  23)
+* --bytes <1>:                           head invocation.     (line  24)
+* --bytes <2>:                           tail invocation.     (line  39)
+* --bytes <3>:                           split invocation.    (line  41)
+* --bytes <4>:                           wc invocation.       (line  46)
+* --bytes <5>:                           cut invocation.      (line  26)
+* --bytes <6>:                           du invocation.       (line  59)
+* --c-shell:                             dircolors invocation.
+                                                              (line  40)
+* --cached=MODE:                         stat invocation.     (line  33)
+* --canonicalize:                        readlink invocation. (line  31)
+* --canonicalize-existing:               readlink invocation. (line  38)
+* --canonicalize-existing <1>:           realpath invocation. (line  22)
+* --canonicalize-missing:                readlink invocation. (line  45)
+* --canonicalize-missing <1>:            realpath invocation. (line  30)
+* --changes:                             chown invocation.    (line  74)
+* --changes <1>:                         chgrp invocation.    (line  24)
+* --changes <2>:                         chmod invocation.    (line  43)
+* --characters:                          cut invocation.      (line  34)
+* --chars:                               wc invocation.       (line  50)
+* --chdir:                               env invocation.      (line 107)
+* --check:                               sort invocation.     (line  39)
+* --check <1>:                           sort invocation.     (line  47)
+* --check-chars:                         uniq invocation.     (line 134)
+* --classify:                            General output formatting.
+                                                              (line  52)
+* --color:                               General output formatting.
+                                                              (line  28)
+* --columns:                             pr invocation.       (line  49)
+* --compare:                             install invocation.  (line  46)
+* --complement:                          cut invocation.      (line  86)
+* --complement <1>:                      tr invocation.       (line  31)
+* --compute:                             runcon invocation.   (line  32)
+* --context:                             What information is listed.
+                                                              (line 259)
+* --context <1>:                         cp invocation.       (line 417)
+* --context <2>:                         install invocation.  (line 143)
+* --context <3>:                         mv invocation.       (line 144)
+* --context <4>:                         mkdir invocation.    (line  59)
+* --context <5>:                         mkfifo invocation.   (line  28)
+* --context <6>:                         mknod invocation.    (line  53)
+* --context <7>:                         id invocation.       (line  51)
+* --count:                               uniq invocation.     (line  56)
+* --count <1>:                           who invocation.      (line  69)
+* --count-links:                         du invocation.       (line 125)
+* --crown-margin:                        fmt invocation.      (line  34)
+* --csh:                                 dircolors invocation.
+                                                              (line  40)
+* --data:                                sync invocation.     (line  32)
+* --date:                                touch invocation.    (line  56)
+* --date <1>:                            Options for date.    (line  15)
+* --dead:                                who invocation.      (line  43)
+* --debug:                               cksum general options.
+                                                              (line  34)
+* --debug <1>:                           cp invocation.       (line 114)
+* --debug <2>:                           install invocation.  (line  72)
+* --debug <3>:                           mv invocation.       (line  60)
+* --debug <4>:                           Options for date.    (line  29)
+* --debug <5>:                           env invocation.      (line 177)
+* --debug <6>:                           numfmt invocation.   (line  29)
+* --decode:                              base64 invocation.   (line  33)
+* --delete:                              tr invocation.       (line  38)
+* --delimiter:                           cut invocation.      (line  66)
+* --delimiter <1>:                       numfmt invocation.   (line  34)
+* --delimiters:                          paste invocation.    (line  61)
+* --dereference:                         Which files are listed.
+                                                              (line  84)
+* --dereference <1>:                     cp invocation.       (line 153)
+* --dereference <2>:                     chown invocation.    (line 107)
+* --dereference <3>:                     chgrp invocation.    (line  34)
+* --dereference <4>:                     du invocation.       (line 119)
+* --dereference <5>:                     stat invocation.     (line  22)
+* --dereference <6>:                     chcon invocation.    (line  21)
+* --dereference-args:                    du invocation.       (line  69)
+* --dereference-command-line:            Which files are listed.
+                                                              (line  36)
+* --dereference-command-line-symlink-to-dir: Which files are listed.
+                                                              (line  41)
+* --dictionary-order:                    sort invocation.     (line  87)
+* --digits:                              csplit invocation.   (line  82)
+* --dir:                                 rm invocation.       (line  35)
+* --directory:                           Which files are listed.
+                                                              (line  28)
+* --directory <1>:                       install invocation.  (line  67)
+* --directory <2>:                       ln invocation.       (line  88)
+* --directory <3>:                       mktemp invocation.   (line  85)
+* --dired:                               What information is listed.
+                                                              (line  16)
+* --double-space:                        pr invocation.       (line  74)
+* --dry-run:                             mktemp invocation.   (line  97)
+* --echo:                                shuf invocation.     (line  19)
+* --elide-empty-files:                   split invocation.    (line 144)
+* --elide-empty-files <1>:               csplit invocation.   (line  96)
+* --endian:                              od invocation.       (line  51)
+* --equal-width:                         seq invocation.      (line  50)
+* --error:                               stdbuf invocation.   (line  34)
+* --escape:                              Formatting the file names.
+                                                              (line  11)
+* --exact:                               shred invocation.    (line 164)
+* --exclude-from=FILE:                   du invocation.       (line 250)
+* --exclude-type:                        df invocation.       (line 224)
+* --exclude=PATTERN:                     du invocation.       (line 255)
+* --expand-tabs:                         pr invocation.       (line  98)
+* --exponents:                           factor invocation.   (line  18)
+* --field:                               numfmt invocation.   (line  38)
+* --field-separator:                     sort invocation.     (line 338)
+* --fields:                              cut invocation.      (line  43)
+* --file:                                stty invocation.     (line  31)
+* --file <1>:                            Options for date.    (line  34)
+* --file-system:                         stat invocation.     (line  28)
+* --file-system <1>:                     sync invocation.     (line  37)
+* --file-type:                           General output formatting.
+                                                              (line  68)
+* --files0-from=FILE:                    wc invocation.       (line  84)
+* --files0-from=FILE <1>:                sort invocation.     (line 224)
+* --files0-from=FILE <2>:                du invocation.       (line  81)
+* --filter:                              split invocation.    (line  63)
+* --first-line-number:                   pr invocation.       (line 174)
+* --flag-truncation:                     Output formatting in ptx.
+                                                              (line  71)
+* --follow:                              tail invocation.     (line  57)
+* --footer-numbering:                    nl invocation.       (line  72)
+* --force:                               cp invocation.       (line 119)
+* --force <1>:                           mv invocation.       (line  65)
+* --force <2>:                           rm invocation.       (line  39)
+* --force <3>:                           shred invocation.    (line 123)
+* --force <4>:                           ln invocation.       (line  94)
+* --foreground:                          timeout invocation.  (line  24)
+* --form-feed:                           pr invocation.       (line 106)
+* --format:                              od invocation.       (line  90)
+* --format <1>:                          What information is listed.
+                                                              (line 133)
+* --format <2>:                          General output formatting.
+                                                              (line   9)
+* --format <3>:                          General output formatting.
+                                                              (line  21)
+* --format <4>:                          General output formatting.
+                                                              (line 114)
+* --format <5>:                          General output formatting.
+                                                              (line 125)
+* --format <6>:                          numfmt invocation.   (line  48)
+* --format <7>:                          seq invocation.      (line  29)
+* --format=FORMAT:                       stat invocation.     (line  50)
+* --format=roff:                         Output formatting in ptx.
+                                                              (line 100)
+* --format=tex:                          Output formatting in ptx.
+                                                              (line 118)
+* --from:                                chown invocation.    (line  84)
+* --from <1>:                            numfmt invocation.   (line  59)
+* --from-unit:                           numfmt invocation.   (line  64)
+* --full-time:                           What information is listed.
+                                                              (line 103)
+* --gap-size:                            Output formatting in ptx.
+                                                              (line  26)
+* --general-numeric-sort:                sort invocation.     (line 105)
+* --goal:                                fmt invocation.      (line  64)
+* --group:                               uniq invocation.     (line 101)
+* --group <1>:                           install invocation.  (line  77)
+* --group <2>:                           id invocation.       (line  29)
+* --group-directories-first:             Which files are listed.
+                                                              (line  50)
+* --grouping:                            numfmt invocation.   (line  70)
+* --groups:                              id invocation.       (line  33)
+* --groups <1>:                          chroot invocation.   (line  24)
+* --hardware-platform:                   uname invocation.    (line  35)
+* --head-count:                          shuf invocation.     (line  31)
+* --header:                              pr invocation.       (line 111)
+* --header <1>:                          General options in join.
+                                                              (line  25)
+* --header <2>:                          numfmt invocation.   (line  76)
+* --header-numbering:                    nl invocation.       (line  76)
+* --header=N:                            numfmt invocation.   (line  76)
+* --heading:                             who invocation.      (line  47)
+* --help:                                Common options.      (line  36)
+* --hex-suffixes:                        split invocation.    (line 135)
+* --hide-control-chars:                  Formatting the file names.
+                                                              (line  23)
+* --hide=PATTERN:                        Which files are listed.
+                                                              (line  58)
+* --human-numeric-sort:                  sort invocation.     (line 132)
+* --human-readable:                      Block size.          (line 131)
+* --human-readable <1>:                  What information is listed.
+                                                              (line 118)
+* --human-readable <2>:                  df invocation.       (line  59)
+* --human-readable <3>:                  du invocation.       (line  98)
+* --hyperlink:                           General output formatting.
+                                                              (line  73)
+* --ignore:                              nproc invocation.    (line  26)
+* --ignore-backups:                      Which files are listed.
+                                                              (line  23)
+* --ignore-case:                         sort invocation.     (line  94)
+* --ignore-case <1>:                     uniq invocation.     (line  60)
+* --ignore-case <2>:                     Charset selection in ptx.
+                                                              (line  20)
+* --ignore-case <3>:                     General options in join.
+                                                              (line  35)
+* --ignore-environment:                  env invocation.      (line 102)
+* --ignore-fail-on-non-empty:            rmdir invocation.    (line  17)
+* --ignore-file:                         Input processing in ptx.
+                                                              (line  26)
+* --ignore-garbage:                      base64 invocation.   (line  39)
+* --ignore-interrupts:                   tee invocation.      (line  31)
+* --ignore-leading-blanks:               sort invocation.     (line  79)
+* --ignore-missing:                      cksum common options.
+                                                              (line  54)
+* --ignore-nonprinting:                  sort invocation.     (line 149)
+* --ignore=PATTERN:                      Which files are listed.
+                                                              (line  70)
+* --indent:                              pr invocation.       (line 180)
+* --indicator-style:                     General output formatting.
+                                                              (line  52)
+* --indicator-style <1>:                 General output formatting.
+                                                              (line  68)
+* --indicator-style <2>:                 General output formatting.
+                                                              (line  82)
+* --indicator-style <3>:                 General output formatting.
+                                                              (line 120)
+* --initial:                             expand invocation.   (line  46)
+* --inode:                               What information is listed.
+                                                              (line 125)
+* --inodes:                              df invocation.       (line  69)
+* --inodes <1>:                          du invocation.       (line 104)
+* --input:                               stdbuf invocation.   (line  26)
+* --input-range:                         shuf invocation.     (line  23)
+* --interactive:                         cp invocation.       (line 143)
+* --interactive <1>:                     mv invocation.       (line  71)
+* --interactive <2>:                     rm invocation.       (line  55)
+* --interactive <3>:                     ln invocation.       (line  98)
+* --invalid:                             numfmt invocation.   (line  79)
+* --io-blocks:                           truncate invocation. (line  26)
+* --iso-8601[=TIMESPEC]:                 Options for date.    (line  42)
+* --iterations=NUMBER:                   shred invocation.    (line 127)
+* --join-blank-lines:                    nl invocation.       (line  85)
+* --join-lines:                          pr invocation.       (line 124)
+* --keep-files:                          csplit invocation.   (line  87)
+* --kernel-name:                         uname invocation.    (line  66)
+* --kernel-release:                      uname invocation.    (line  62)
+* --kernel-version:                      uname invocation.    (line  77)
+* --key:                                 sort invocation.     (line 237)
+* --kibibytes:                           General output formatting.
+                                                              (line 101)
+* --kill-after:                          timeout invocation.  (line  41)
+* --length:                              pr invocation.       (line 133)
+* --length <1>:                          cksum general options.
+                                                              (line  39)
+* --length <2>:                          b2sum invocation.    (line  24)
+* --line-bytes:                          split invocation.    (line  56)
+* --line-increment:                      nl invocation.       (line  80)
+* --lines:                               head invocation.     (line  40)
+* --lines <1>:                           tail invocation.     (line 126)
+* --lines <2>:                           split invocation.    (line  33)
+* --lines <3>:                           wc invocation.       (line  60)
+* --link:                                cp invocation.       (line 149)
+* --literal:                             Formatting the file names.
+                                                              (line  17)
+* --local:                               df invocation.       (line  81)
+* --logical:                             ln invocation.       (line 103)
+* --logical <1>:                         realpath invocation. (line  35)
+* --logical <2>:                         pwd invocation.      (line  15)
+* --login:                               who invocation.      (line  51)
+* --lookup:                              who invocation.      (line  56)
+* --machine:                             uname invocation.    (line  42)
+* --macro-name:                          Output formatting in ptx.
+                                                              (line  94)
+* --max-depth=DEPTH:                     du invocation.       (line  76)
+* --max-line-length:                     wc invocation.       (line  66)
+* --max-unchanged-stats:                 tail invocation.     (line 114)
+* --merge:                               pr invocation.       (line 140)
+* --merge <1>:                           sort invocation.     (line  53)
+* --mesg:                                who invocation.      (line  94)
+* --message:                             who invocation.      (line  94)
+* --mode:                                install invocation.  (line  83)
+* --mode <1>:                            mkdir invocation.    (line  19)
+* --mode <2>:                            mkfifo invocation.   (line  21)
+* --mode <3>:                            mknod invocation.    (line  47)
+* --month-sort:                          sort invocation.     (line 156)
+* --multiple:                            basename invocation. (line  32)
+* --name:                                id invocation.       (line  37)
+* --no-clobber:                          cp invocation.       (line 160)
+* --no-clobber <1>:                      mv invocation.       (line  78)
+* --no-copy:                             mv invocation.       (line  85)
+* --no-create:                           touch invocation.    (line  52)
+* --no-create <1>:                       truncate invocation. (line  22)
+* --no-dereference:                      cp invocation.       (line 166)
+* --no-dereference <1>:                  ln invocation.       (line 109)
+* --no-dereference <2>:                  chown invocation.    (line 119)
+* --no-dereference <3>:                  chgrp invocation.    (line  46)
+* --no-dereference <4>:                  touch invocation.    (line  70)
+* --no-dereference <5>:                  du invocation.       (line 135)
+* --no-dereference <6>:                  chcon invocation.    (line  26)
+* --no-file-warnings:                    pr invocation.       (line 187)
+* --no-group:                            What information is listed.
+                                                              (line 112)
+* --no-newline:                          readlink invocation. (line  50)
+* --no-preserve-root:                    rm invocation.       (line  89)
+* --no-preserve-root <1>:                chown invocation.    (line 132)
+* --no-preserve-root <2>:                chgrp invocation.    (line  59)
+* --no-preserve-root <3>:                chmod invocation.    (line  58)
+* --no-preserve-root <4>:                chcon invocation.    (line  43)
+* --no-renumber:                         nl invocation.       (line 104)
+* --no-symlinks:                         realpath invocation. (line  64)
+* --no-sync:                             df invocation.       (line  85)
+* --no-target-directory:                 Target directory.    (line  15)
+* --no-target-directory <1>:             cp invocation.       (line 367)
+* --no-target-directory <2>:             install invocation.  (line 134)
+* --no-target-directory <3>:             mv invocation.       (line 139)
+* --no-target-directory <4>:             ln invocation.       (line 177)
+* --nodename:                            uname invocation.    (line  47)
+* --null:                                du invocation.       (line  25)
+* --null <1>:                            printenv invocation. (line  19)
+* --null <2>:                            env invocation.      (line  90)
+* --number:                              cat invocation.      (line  32)
+* --number <1>:                          split invocation.    (line  79)
+* --number-format:                       nl invocation.       (line  93)
+* --number-lines:                        pr invocation.       (line 153)
+* --number-nonblank:                     cat invocation.      (line  20)
+* --number-separator:                    nl invocation.       (line 108)
+* --number-width:                        nl invocation.       (line 118)
+* --numeric-sort:                        sort invocation.     (line 166)
+* --numeric-suffixes:                    split invocation.    (line 121)
+* --numeric-uid-gid:                     What information is listed.
+                                                              (line 227)
+* --omit-header:                         pr invocation.       (line 210)
+* --omit-pagination:                     pr invocation.       (line 220)
+* --one-file-system:                     cp invocation.       (line 411)
+* --one-file-system <1>:                 rm invocation.       (line  66)
+* --one-file-system <2>:                 du invocation.       (line 261)
+* --only-delimited:                      cut invocation.      (line  74)
+* --only-file:                           Input processing in ptx.
+                                                              (line  35)
+* --operating-system:                    uname invocation.    (line  58)
+* --output:                              sort invocation.     (line 294)
+* --output <1>:                          shuf invocation.     (line  36)
+* --output <2>:                          df invocation.       (line  92)
+* --output <3>:                          stdbuf invocation.   (line  30)
+* --output-delimiter:                    cut invocation.      (line  79)
+* --output-duplicates:                   od invocation.       (line 150)
+* --output-error:                        tee invocation.      (line  35)
+* --output-tabs:                         pr invocation.       (line 117)
+* --owner:                               install invocation.  (line  95)
+* --padding:                             numfmt invocation.   (line  87)
+* --pages=PAGE_RANGE:                    pr invocation.       (line  39)
+* --page_width:                          pr invocation.       (line 239)
+* --parallel:                            sort invocation.     (line 366)
+* --parents:                             cp invocation.       (line 249)
+* --parents <1>:                         mkdir invocation.    (line  36)
+* --parents <2>:                         rmdir invocation.    (line  21)
+* --physical:                            ln invocation.       (line 128)
+* --physical <1>:                        realpath invocation. (line  40)
+* --physical <2>:                        pwd invocation.      (line  22)
+* --pid:                                 tail invocation.     (line 133)
+* --portability:                         df invocation.       (line 149)
+* --portability <1>:                     pathchk invocation.  (line  44)
+* --prefix:                              csplit invocation.   (line  64)
+* --preserve:                            cp invocation.       (line 173)
+* --preserve-context:                    install invocation.  (line 100)
+* --preserve-root:                       rm invocation.       (line  82)
+* --preserve-root <1>:                   chown invocation.    (line 127)
+* --preserve-root <2>:                   chgrp invocation.    (line  54)
+* --preserve-root <3>:                   chmod invocation.    (line  53)
+* --preserve-root <4>:                   chcon invocation.    (line  38)
+* --preserve-status:                     timeout invocation.  (line  18)
+* --preserve-timestamps:                 install invocation.  (line 107)
+* --print-database:                      dircolors invocation.
+                                                              (line  45)
+* --print-ls-colors:                     dircolors invocation.
+                                                              (line  50)
+* --print-type:                          df invocation.       (line 201)
+* --printf=FORMAT:                       stat invocation.     (line  59)
+* --process:                             who invocation.      (line  65)
+* --processor:                           uname invocation.    (line  51)
+* --quiet:                               head invocation.     (line  47)
+* --quiet <1>:                           tail invocation.     (line 155)
+* --quiet <2>:                           csplit invocation.   (line 107)
+* --quiet <3>:                           cksum common options.
+                                                              (line  60)
+* --quiet <4>:                           readlink invocation. (line  57)
+* --quiet <5>:                           chown invocation.    (line  80)
+* --quiet <6>:                           chgrp invocation.    (line  30)
+* --quiet <7>:                           chmod invocation.    (line  49)
+* --quiet <8>:                           mktemp invocation.   (line  92)
+* --quiet <9>:                           realpath invocation. (line  46)
+* --quiet <10>:                          tty invocation.      (line  18)
+* --quote-name:                          Formatting the file names.
+                                                              (line  30)
+* --quoting-style:                       Formatting the file names.
+                                                              (line  11)
+* --quoting-style <1>:                   Formatting the file names.
+                                                              (line  17)
+* --quoting-style <2>:                   Formatting the file names.
+                                                              (line  30)
+* --quoting-style <3>:                   Formatting the file names.
+                                                              (line  34)
+* --random-sort:                         sort invocation.     (line 195)
+* --random-source:                       sort invocation.     (line 310)
+* --random-source <1>:                   shuf invocation.     (line  42)
+* --random-source <2>:                   shred invocation.    (line 133)
+* --range:                               chcon invocation.    (line  77)
+* --range <1>:                           runcon invocation.   (line  48)
+* --raw:                                 cksum general options.
+                                                              (line  45)
+* --read-bytes:                          od invocation.       (line  76)
+* --real:                                id invocation.       (line  42)
+* --recursive:                           Which files are listed.
+                                                              (line  91)
+* --recursive <1>:                       cp invocation.       (line 262)
+* --recursive <2>:                       rm invocation.       (line  96)
+* --recursive <3>:                       chown invocation.    (line 151)
+* --recursive <4>:                       chgrp invocation.    (line  77)
+* --recursive <5>:                       chmod invocation.    (line  73)
+* --recursive <6>:                       chcon invocation.    (line  35)
+* --reference:                           chown invocation.    (line 136)
+* --reference <1>:                       chgrp invocation.    (line  63)
+* --reference <2>:                       chmod invocation.    (line  66)
+* --reference <3>:                       touch invocation.    (line  89)
+* --reference <4>:                       truncate invocation. (line  30)
+* --reference <5>:                       Options for date.    (line  71)
+* --reference <6>:                       chcon invocation.    (line  30)
+* --references:                          Input processing in ptx.
+                                                              (line  48)
+* --reflink[=WHEN]:                      cp invocation.       (line 275)
+* --regex:                               tac invocation.      (line  26)
+* --relative:                            ln invocation.       (line 137)
+* --relative-base:                       realpath invocation. (line  54)
+* --relative-base <1>:                   Realpath usage examples.
+                                                              (line   6)
+* --relative-to:                         realpath invocation. (line  49)
+* --relative-to <1>:                     Realpath usage examples.
+                                                              (line   6)
+* --remove:                              shred invocation.    (line 144)
+* --remove-destination:                  cp invocation.       (line 302)
+* --remove=unlink:                       shred invocation.    (line 144)
+* --remove=wipe:                         shred invocation.    (line 144)
+* --remove=wipesync:                     shred invocation.    (line 144)
+* --repeat:                              shuf invocation.     (line  47)
+* --repeated:                            uniq invocation.     (line  64)
+* --resolution:                          Options for date.    (line  75)
+* --retry:                               tail invocation.     (line 158)
+* --reverse:                             sort invocation.     (line 189)
+* --reverse <1>:                         Sorting the output.  (line  25)
+* --rfc-2822:                            Options for date.    (line  91)
+* --rfc-3339=TIMESPEC:                   Options for date.    (line 100)
+* --rfc-822:                             Options for date.    (line  91)
+* --rfc-email:                           Options for date.    (line  85)
+* --right-side-refs:                     Output formatting in ptx.
+                                                              (line  56)
+* --role:                                chcon invocation.    (line  69)
+* --role <1>:                            runcon invocation.   (line  40)
+* --round:                               numfmt invocation.   (line  94)
+* --round=down:                          numfmt invocation.   (line  94)
+* --round=from-zero:                     numfmt invocation.   (line  94)
+* --round=nearest:                       numfmt invocation.   (line  94)
+* --round=towards-zero:                  numfmt invocation.   (line  94)
+* --round=up:                            numfmt invocation.   (line  94)
+* --runlevel:                            who invocation.      (line  74)
+* --save:                                stty invocation.     (line  41)
+* --section-delimiter:                   nl invocation.       (line  63)
+* --sentence-regexp:                     Input processing in ptx.
+                                                              (line  65)
+* --sep-string:                          pr invocation.       (line 201)
+* --separate-dirs:                       du invocation.       (line 140)
+* --separator:                           tac invocation.      (line  30)
+* --separator <1>:                       pr invocation.       (line 192)
+* --separator <2>:                       split invocation.    (line 152)
+* --separator <3>:                       seq invocation.      (line  45)
+* --serial:                              paste invocation.    (line  52)
+* --set:                                 Options for date.    (line 129)
+* --sh:                                  dircolors invocation.
+                                                              (line  34)
+* --show-all:                            cat invocation.      (line  16)
+* --show-control-chars:                  pr invocation.       (line  68)
+* --show-control-chars <1>:              Formatting the file names.
+                                                              (line  78)
+* --show-ends:                           cat invocation.      (line  27)
+* --show-nonprinting:                    cat invocation.      (line  52)
+* --show-nonprinting <1>:                pr invocation.       (line 225)
+* --show-tabs:                           cat invocation.      (line  45)
+* --si:                                  Block size.          (line 131)
+* --si <1>:                              What information is listed.
+                                                              (line 251)
+* --si <2>:                              df invocation.       (line 168)
+* --si <3>:                              du invocation.       (line 147)
+* --signal:                              timeout invocation.  (line  58)
+* --silent:                              head invocation.     (line  47)
+* --silent <1>:                          tail invocation.     (line 155)
+* --silent <2>:                          csplit invocation.   (line 107)
+* --silent <3>:                          readlink invocation. (line  57)
+* --silent <4>:                          chown invocation.    (line  80)
+* --silent <5>:                          chgrp invocation.    (line  30)
+* --silent <6>:                          chmod invocation.    (line  49)
+* --silent <7>:                          tty invocation.      (line  18)
+* --size:                                What information is listed.
+                                                              (line 236)
+* --size <1>:                            truncate invocation. (line  34)
+* --size=BYTES:                          shred invocation.    (line 138)
+* --skip-bytes:                          od invocation.       (line  59)
+* --skip-chars:                          uniq invocation.     (line  42)
+* --skip-chdir:                          chroot invocation.   (line  37)
+* --skip-fields:                         uniq invocation.     (line  31)
+* --sleep-interval:                      tail invocation.     (line 175)
+* --sort:                                sort invocation.     (line 105)
+* --sort <1>:                            sort invocation.     (line 132)
+* --sort <2>:                            sort invocation.     (line 156)
+* --sort <3>:                            sort invocation.     (line 166)
+* --sort <4>:                            sort invocation.     (line 195)
+* --sort <5>:                            Sorting the output.  (line  32)
+* --sort <6>:                            Sorting the output.  (line  36)
+* --sort <7>:                            Sorting the output.  (line  64)
+* --sort <8>:                            Sorting the output.  (line  71)
+* --sort <9>:                            Sorting the output.  (line  77)
+* --sort <10>:                           Sorting the output.  (line  83)
+* --spaces:                              fold invocation.     (line  29)
+* --sparse=WHEN:                         cp invocation.       (line 306)
+* --split-only:                          fmt invocation.      (line  47)
+* --split-string:                        env invocation.      (line 192)
+* --squeeze-blank:                       cat invocation.      (line  37)
+* --squeeze-repeats:                     tr invocation.       (line  42)
+* --stable:                              sort invocation.     (line 315)
+* --starting-line-number:                nl invocation.       (line 113)
+* --status:                              cksum common options.
+                                                              (line  68)
+* --strict:                              cksum common options.
+                                                              (line 104)
+* --strings:                             od invocation.       (line  81)
+* --strip:                               install invocation.  (line 117)
+* --strip <1>:                           realpath invocation. (line  64)
+* --strip-program:                       install invocation.  (line 120)
+* --strip-trailing-slashes:              cp invocation.       (line 345)
+* --strip-trailing-slashes <1>:          mv invocation.       (line 125)
+* --suffix:                              Backup options.      (line  49)
+* --suffix <1>:                          cp invocation.       (line 358)
+* --suffix <2>:                          install invocation.  (line 124)
+* --suffix <3>:                          mv invocation.       (line 130)
+* --suffix <4>:                          ln invocation.       (line 168)
+* --suffix <5>:                          basename invocation. (line  38)
+* --suffix <6>:                          mktemp invocation.   (line 113)
+* --suffix <7>:                          numfmt invocation.   (line  99)
+* --suffix-format:                       csplit invocation.   (line  68)
+* --suffix-length:                       split invocation.    (line 113)
+* --summarize:                           du invocation.       (line 155)
+* --suppress-matched:                    csplit invocation.   (line  90)
+* --symbolic:                            ln invocation.       (line 162)
+* --symbolic-link:                       cp invocation.       (line 350)
+* --sync:                                df invocation.       (line 175)
+* --sysv:                                sum invocation.      (line  29)
+* --tabs:                                expand invocation.   (line  22)
+* --tabs <1>:                            unexpand invocation. (line  24)
+* --tabsize:                             General output formatting.
+                                                              (line 129)
+* --tag:                                 cksum common options.
+                                                              (line  77)
+* --tagged-paragraph:                    fmt invocation.      (line  40)
+* --target-directory:                    Target directory.    (line  31)
+* --target-directory <1>:                cp invocation.       (line 363)
+* --target-directory <2>:                install invocation.  (line 129)
+* --target-directory <3>:                mv invocation.       (line 135)
+* --target-directory <4>:                ln invocation.       (line 173)
+* --temporary-directory:                 sort invocation.     (line 358)
+* --terse:                               stat invocation.     (line  70)
+* --text:                                cksum common options.
+                                                              (line  89)
+* --threshold:                           du invocation.       (line 159)
+* --time:                                Sorting the output.  (line  13)
+* --time <1>:                            Sorting the output.  (line  44)
+* --time <2>:                            Sorting the output.  (line  50)
+* --time <3>:                            Sorting the output.  (line  57)
+* --time <4>:                            touch invocation.    (line  48)
+* --time <5>:                            touch invocation.    (line  85)
+* --time <6>:                            du invocation.       (line 195)
+* --time <7>:                            du invocation.       (line 202)
+* --time <8>:                            du invocation.       (line 208)
+* --time <9>:                            who invocation.      (line  82)
+* --time-style:                          Formatting file timestamps.
+                                                              (line  24)
+* --time-style <1>:                      du invocation.       (line 212)
+* --tmpdir:                              mktemp invocation.   (line 105)
+* --to:                                  numfmt invocation.   (line 103)
+* --to-unit:                             numfmt invocation.   (line 108)
+* --total:                               df invocation.       (line 181)
+* --total <1>:                           du invocation.       (line  63)
+* --total=WHEN:                          wc invocation.       (line  71)
+* --traditional:                         od invocation.       (line 200)
+* --truncate-set1:                       tr invocation.       (line  47)
+* --type:                                df invocation.       (line 195)
+* --type <1>:                            chcon invocation.    (line  73)
+* --type <2>:                            runcon invocation.   (line  44)
+* --unbuffered:                          split invocation.    (line 159)
+* --uniform-spacing:                     fmt invocation.      (line  53)
+* --unique:                              sort invocation.     (line 374)
+* --unique <1>:                          uniq invocation.     (line 128)
+* --universal:                           Options for date.    (line 135)
+* --unset:                               env invocation.      (line  96)
+* --untagged:                            cksum general options.
+                                                              (line  52)
+* --update:                              mv invocation.       (line  91)
+* --update[=WHICH]:                      cp invocation.       (line 372)
+* --user:                                id invocation.       (line  47)
+* --user <1>:                            chcon invocation.    (line  65)
+* --user <2>:                            runcon invocation.   (line  36)
+* --userspec:                            chroot invocation.   (line  30)
+* --utc:                                 Options for date.    (line 135)
+* --verbose:                             head invocation.     (line  51)
+* --verbose <1>:                         tail invocation.     (line 186)
+* --verbose <2>:                         split invocation.    (line 163)
+* --verbose <3>:                         cp invocation.       (line 407)
+* --verbose <4>:                         install invocation.  (line 139)
+* --verbose <5>:                         mv invocation.       (line 122)
+* --verbose <6>:                         rm invocation.       (line 100)
+* --verbose <7>:                         shred invocation.    (line 159)
+* --verbose <8>:                         ln invocation.       (line 182)
+* --verbose <9>:                         mkdir invocation.    (line  54)
+* --verbose <10>:                        readlink invocation. (line  61)
+* --verbose <11>:                        rmdir invocation.    (line  30)
+* --verbose <12>:                        chown invocation.    (line 143)
+* --verbose <13>:                        chgrp invocation.    (line  69)
+* --verbose <14>:                        chmod invocation.    (line  63)
+* --verbose <15>:                        chcon invocation.    (line  61)
+* --verbose <16>:                        timeout invocation.  (line  64)
+* --version:                             Common options.      (line  40)
+* --version-sort:                        sort invocation.     (line 183)
+* --warn:                                cksum common options.
+                                                              (line  99)
+* --width:                               od invocation.       (line 157)
+* --width <1>:                           fmt invocation.      (line  59)
+* --width <2>:                           pr invocation.       (line 229)
+* --width <3>:                           fold invocation.     (line  35)
+* --width <4>:                           Output formatting in ptx.
+                                                              (line  32)
+* --width <5>:                           General output formatting.
+                                                              (line 149)
+* --word-regexp:                         Input processing in ptx.
+                                                              (line 105)
+* --words:                               wc invocation.       (line  55)
+* --wrap:                                base64 invocation.   (line  25)
+* --writable:                            who invocation.      (line  94)
+* --z85:                                 basenc invocation.   (line  63)
+* --zero:                                cksum common options.
+                                                              (line 109)
+* --zero <1>:                            General output formatting.
+                                                              (line 157)
+* --zero <2>:                            shred invocation.    (line 175)
+* --zero <3>:                            readlink invocation. (line  65)
+* --zero <4>:                            basename invocation. (line  42)
+* --zero <5>:                            dirname invocation.  (line  31)
+* --zero <6>:                            realpath invocation. (line  71)
+* --zero <7>:                            id invocation.       (line  58)
+* --zero-terminated:                     head invocation.     (line  55)
+* --zero-terminated <1>:                 tail invocation.     (line 190)
+* --zero-terminated <2>:                 sort invocation.     (line 389)
+* --zero-terminated <3>:                 shuf invocation.     (line  55)
+* --zero-terminated <4>:                 uniq invocation.     (line 140)
+* --zero-terminated <5>:                 comm invocation.     (line  89)
+* --zero-terminated <6>:                 cut invocation.      (line  94)
+* --zero-terminated <7>:                 paste invocation.    (line  72)
+* --zero-terminated <8>:                 General options in join.
+                                                              (line  93)
+* --zero-terminated <9>:                 numfmt invocation.   (line 115)
+* -0:                                    du invocation.       (line  25)
+* -0 <1>:                                printenv invocation. (line  19)
+* -0 <2>:                                env invocation.      (line  90)
+* -1:                                    comm invocation.     (line  23)
+* -1 <1>:                                General options in join.
+                                                              (line  40)
+* -1 <2>:                                General output formatting.
+                                                              (line  16)
+* -2:                                    comm invocation.     (line  23)
+* -2 <1>:                                General options in join.
+                                                              (line  43)
+* -3:                                    comm invocation.     (line  23)
+* -A:                                    cat invocation.      (line  16)
+* -A <1>:                                od invocation.       (line  36)
+* -a:                                    od invocation.       (line 169)
+* -a <1>:                                pr invocation.       (line  62)
+* -a <2>:                                split invocation.    (line 113)
+* -a <3>:                                cksum general options.
+                                                              (line   5)
+* -A <2>:                                Output formatting in ptx.
+                                                              (line  45)
+* -a <4>:                                General options in join.
+                                                              (line  10)
+* -a <5>:                                unexpand invocation. (line  51)
+* -a <6>:                                Which files are listed.
+                                                              (line  13)
+* -A <3>:                                Which files are listed.
+                                                              (line  17)
+* -a <7>:                                cp invocation.       (line  63)
+* -a <8>:                                touch invocation.    (line  48)
+* -a <9>:                                df invocation.       (line  42)
+* -a <10>:                               du invocation.       (line  31)
+* -a <11>:                               Connectives for test.
+                                                              (line  29)
+* -a <12>:                               tee invocation.      (line  26)
+* -a <13>:                               basename invocation. (line  32)
+* -a <14>:                               stty invocation.     (line  26)
+* -a <15>:                               who invocation.      (line  35)
+* -a <16>:                               uname invocation.    (line  30)
+* -b:                                    Backup options.      (line  13)
+* -b <1>:                                cat invocation.      (line  20)
+* -b <2>:                                tac invocation.      (line  21)
+* -b <3>:                                nl invocation.       (line  45)
+* -b <4>:                                od invocation.       (line 172)
+* -b <5>:                                fold invocation.     (line  23)
+* -b <6>:                                split invocation.    (line  41)
+* -b <7>:                                csplit invocation.   (line  68)
+* -b <8>:                                cksum common options.
+                                                              (line   5)
+* -b <9>:                                sort invocation.     (line  79)
+* -b <10>:                               Input processing in ptx.
+                                                              (line   8)
+* -b <11>:                               cut invocation.      (line  26)
+* -B:                                    Which files are listed.
+                                                              (line  23)
+* -b <12>:                               Formatting the file names.
+                                                              (line  11)
+* -b <13>:                               dircolors invocation.
+                                                              (line  34)
+* -b <14>:                               cp invocation.       (line  79)
+* -b <15>:                               install invocation.  (line  41)
+* -b <16>:                               mv invocation.       (line  56)
+* -b <17>:                               ln invocation.       (line  82)
+* -B <1>:                                df invocation.       (line  54)
+* -B <2>:                                du invocation.       (line  54)
+* -b <18>:                               du invocation.       (line  59)
+* -b <19>:                               File type tests.     (line  10)
+* -b <20>:                               who invocation.      (line  39)
+* -c:                                    od invocation.       (line 175)
+* -c <1>:                                fmt invocation.      (line  34)
+* -c <2>:                                pr invocation.       (line  68)
+* -c <3>:                                head invocation.     (line  24)
+* -c <4>:                                tail invocation.     (line  39)
+* -C:                                    split invocation.    (line  56)
+* -c <5>:                                wc invocation.       (line  46)
+* -c <6>:                                sort invocation.     (line  39)
+* -c <7>:                                sort invocation.     (line  47)
+* -c <8>:                                shuf invocation.     (line  19)
+* -c <9>:                                uniq invocation.     (line  56)
+* -c <10>:                               cut invocation.      (line  34)
+* -c <11>:                               tr invocation.       (line  31)
+* -C <1>:                                tr invocation.       (line  31)
+* -c <12>:                               Sorting the output.  (line  13)
+* -C <2>:                                General output formatting.
+                                                              (line  21)
+* -c <13>:                               dircolors invocation.
+                                                              (line  40)
+* -C <3>:                                install invocation.  (line  46)
+* -c <14>:                               install invocation.  (line  57)
+* -c <15>:                               chown invocation.    (line  74)
+* -c <16>:                               chgrp invocation.    (line  24)
+* -c <17>:                               chmod invocation.    (line  43)
+* -c <18>:                               touch invocation.    (line  52)
+* -c <19>:                               du invocation.       (line  63)
+* -c <20>:                               stat invocation.     (line  50)
+* -c <21>:                               truncate invocation. (line  22)
+* -c <22>:                               File type tests.     (line  13)
+* -c <23>:                               runcon invocation.   (line  32)
+* -C <4>:                                env invocation.      (line 107)
+* -COLUMN:                               pr invocation.       (line  49)
+* -d:                                    nl invocation.       (line  63)
+* -d <1>:                                od invocation.       (line 179)
+* -d <2>:                                base64 invocation.   (line  33)
+* -d <3>:                                pr invocation.       (line  74)
+* -d <4>:                                split invocation.    (line 121)
+* -d <5>:                                sort invocation.     (line  87)
+* -d <6>:                                uniq invocation.     (line  64)
+* -D:                                    uniq invocation.     (line  70)
+* -d <7>:                                cut invocation.      (line  66)
+* -d <8>:                                paste invocation.    (line  61)
+* -d <9>:                                tr invocation.       (line  38)
+* -d <10>:                               Which files are listed.
+                                                              (line  28)
+* -D <1>:                                What information is listed.
+                                                              (line  16)
+* -d <11>:                               cp invocation.       (line 109)
+* -D <2>:                                install invocation.  (line  60)
+* -d <12>:                               install invocation.  (line  67)
+* -d <13>:                               rm invocation.       (line  35)
+* -d <14>:                               ln invocation.       (line  88)
+* -d <15>:                               touch invocation.    (line  56)
+* -D <3>:                                du invocation.       (line  69)
+* -d <16>:                               File type tests.     (line  16)
+* -d <17>:                               mktemp invocation.   (line  85)
+* -d <18>:                               who invocation.      (line  43)
+* -d <19>:                               Options for date.    (line  15)
+* -d <20>:                               numfmt invocation.   (line  34)
+* -d DEPTH:                              du invocation.       (line  76)
+* -e:                                    cat invocation.      (line  23)
+* -E:                                    cat invocation.      (line  27)
+* -e <1>:                                pr invocation.       (line  98)
+* -e <2>:                                split invocation.    (line 144)
+* -e <3>:                                General options in join.
+                                                              (line  21)
+* -e <4>:                                readlink invocation. (line  38)
+* -e <5>:                                echo invocation.     (line  32)
+* -E <1>:                                echo invocation.     (line  68)
+* -e <6>:                                File characteristic tests.
+                                                              (line   9)
+* -e <7>:                                realpath invocation. (line  22)
+* -e <8>:                                stdbuf invocation.   (line  34)
+* -ef:                                   File characteristic tests.
+                                                              (line  23)
+* -eq:                                   Numeric tests.       (line  16)
+* -f:                                    nl invocation.       (line  72)
+* -f <1>:                                od invocation.       (line 182)
+* -F:                                    pr invocation.       (line 106)
+* -f <2>:                                pr invocation.       (line 106)
+* -f <3>:                                tail invocation.     (line  57)
+* -F <1>:                                tail invocation.     (line 109)
+* -f <4>:                                csplit invocation.   (line  64)
+* -f <5>:                                sort invocation.     (line  94)
+* -f <6>:                                uniq invocation.     (line  31)
+* -f <7>:                                Charset selection in ptx.
+                                                              (line  20)
+* -F <2>:                                Output formatting in ptx.
+                                                              (line  71)
+* -f <8>:                                cut invocation.      (line  43)
+* -f <9>:                                Sorting the output.  (line  18)
+* -F <3>:                                General output formatting.
+                                                              (line  52)
+* -f <10>:                               cp invocation.       (line 119)
+* -f <11>:                               mv invocation.       (line  65)
+* -f <12>:                               rm invocation.       (line  39)
+* -f <13>:                               shred invocation.    (line 123)
+* -F <4>:                                ln invocation.       (line  88)
+* -f <14>:                               ln invocation.       (line  94)
+* -f <15>:                               readlink invocation. (line  31)
+* -f <16>:                               chown invocation.    (line  80)
+* -f <17>:                               chgrp invocation.    (line  30)
+* -f <18>:                               chmod invocation.    (line  49)
+* -f <19>:                               touch invocation.    (line  66)
+* -f <20>:                               stat invocation.     (line  28)
+* -f <21>:                               File type tests.     (line  19)
+* -F <5>:                                stty invocation.     (line  31)
+* -f <22>:                               Options for date.    (line  34)
+* -f <23>:                               seq invocation.      (line  29)
+* -g:                                    fmt invocation.      (line  64)
+* -g <1>:                                sort invocation.     (line 105)
+* -g <2>:                                Output formatting in ptx.
+                                                              (line  26)
+* -g <3>:                                What information is listed.
+                                                              (line 108)
+* -G:                                    What information is listed.
+                                                              (line 112)
+* -g <4>:                                install invocation.  (line  77)
+* -g <5>:                                Access permission tests.
+                                                              (line   9)
+* -G <1>:                                Access permission tests.
+                                                              (line  31)
+* -g <6>:                                stty invocation.     (line  41)
+* -g <7>:                                id invocation.       (line  29)
+* -G <2>:                                id invocation.       (line  33)
+* -ge:                                   Numeric tests.       (line  16)
+* -gt:                                   Numeric tests.       (line  16)
+* -h:                                    Block size.          (line 131)
+* -H:                                    Traversing symlinks. (line  18)
+* -h <1>:                                nl invocation.       (line  76)
+* -h <2>:                                pr invocation.       (line 111)
+* -h <3>:                                sort invocation.     (line 132)
+* -H <1>:                                Which files are listed.
+                                                              (line  36)
+* -h <4>:                                What information is listed.
+                                                              (line 118)
+* -H <2>:                                cp invocation.       (line 136)
+* -h <5>:                                chown invocation.    (line 119)
+* -H <3>:                                chown invocation.    (line 154)
+* -h <6>:                                chgrp invocation.    (line  46)
+* -H <4>:                                chgrp invocation.    (line  81)
+* -h <7>:                                touch invocation.    (line  70)
+* -h <8>:                                df invocation.       (line  59)
+* -H <5>:                                df invocation.       (line  65)
+* -H <6>:                                du invocation.       (line  94)
+* -h <9>:                                du invocation.       (line  98)
+* -h <10>:                               File type tests.     (line  23)
+* -H <7>:                                who invocation.      (line  47)
+* -h <11>:                               chcon invocation.    (line  26)
+* -H <8>:                                chcon invocation.    (line  47)
+* -h <12>:                               factor invocation.   (line  18)
+* -i:                                    nl invocation.       (line  80)
+* -i <1>:                                od invocation.       (line 185)
+* -i <2>:                                base64 invocation.   (line  39)
+* -i <3>:                                pr invocation.       (line 117)
+* -i <4>:                                sort invocation.     (line 149)
+* -i <5>:                                shuf invocation.     (line  23)
+* -i <6>:                                uniq invocation.     (line  60)
+* -i <7>:                                Input processing in ptx.
+                                                              (line  26)
+* -i <8>:                                General options in join.
+                                                              (line  35)
+* -i <9>:                                expand invocation.   (line  46)
+* -I:                                    Which files are listed.
+                                                              (line  70)
+* -i <10>:                               What information is listed.
+                                                              (line 125)
+* -i <11>:                               cp invocation.       (line 143)
+* -i <12>:                               mv invocation.       (line  71)
+* -i <13>:                               rm invocation.       (line  43)
+* -I <1>:                                rm invocation.       (line  49)
+* -i <14>:                               ln invocation.       (line  98)
+* -i <15>:                               df invocation.       (line  69)
+* -i <16>:                               tee invocation.      (line  31)
+* -i <17>:                               uname invocation.    (line  35)
+* -i <18>:                               env invocation.      (line 102)
+* -i <19>:                               stdbuf invocation.   (line  26)
+* -I[TIMESPEC]:                          Options for date.    (line  42)
+* -j:                                    od invocation.       (line  59)
+* -J:                                    pr invocation.       (line 124)
+* -k:                                    Block size.          (line 131)
+* -k <1>:                                csplit invocation.   (line  87)
+* -k <2>:                                sort invocation.     (line 237)
+* -k <3>:                                General output formatting.
+                                                              (line 101)
+* -k <4>:                                df invocation.       (line  75)
+* -k <5>:                                du invocation.       (line 113)
+* -k <6>:                                Access permission tests.
+                                                              (line  12)
+* -k <7>:                                timeout invocation.  (line  41)
+* -L:                                    Traversing symlinks. (line  22)
+* -l:                                    nl invocation.       (line  85)
+* -l <1>:                                od invocation.       (line 188)
+* -l <2>:                                pr invocation.       (line 133)
+* -l <3>:                                split invocation.    (line  33)
+* -l <4>:                                wc invocation.       (line  60)
+* -L <1>:                                wc invocation.       (line  66)
+* -l <5>:                                cksum general options.
+                                                              (line  39)
+* -l <6>:                                b2sum invocation.    (line  24)
+* -L <2>:                                Which files are listed.
+                                                              (line  84)
+* -l <7>:                                What information is listed.
+                                                              (line 133)
+* -l <8>:                                cp invocation.       (line 149)
+* -L <3>:                                cp invocation.       (line 153)
+* -L <4>:                                ln invocation.       (line 103)
+* -L <5>:                                chown invocation.    (line 159)
+* -L <6>:                                chgrp invocation.    (line  86)
+* -l <9>:                                df invocation.       (line  81)
+* -L <7>:                                du invocation.       (line 119)
+* -l <10>:                               du invocation.       (line 125)
+* -L <8>:                                stat invocation.     (line  22)
+* -L <9>:                                File type tests.     (line  23)
+* -L <10>:                               realpath invocation. (line  35)
+* -L <11>:                               pwd invocation.      (line  15)
+* -l <11>:                               who invocation.      (line  51)
+* -L <12>:                               chcon invocation.    (line  52)
+* -l <12>:                               chcon invocation.    (line  77)
+* -l <13>:                               runcon invocation.   (line  48)
+* -le:                                   Numeric tests.       (line  16)
+* -lt:                                   Numeric tests.       (line  16)
+* -m:                                    pr invocation.       (line 140)
+* -m <1>:                                wc invocation.       (line  50)
+* -m <2>:                                sort invocation.     (line  53)
+* -M:                                    sort invocation.     (line 156)
+* -M <1>:                                Output formatting in ptx.
+                                                              (line  94)
+* -m <3>:                                General output formatting.
+                                                              (line 114)
+* -m <4>:                                install invocation.  (line  83)
+* -m <5>:                                mkdir invocation.    (line  19)
+* -m <6>:                                mkfifo invocation.   (line  21)
+* -m <7>:                                mknod invocation.    (line  47)
+* -m <8>:                                readlink invocation. (line  45)
+* -m <9>:                                touch invocation.    (line  85)
+* -m <10>:                               du invocation.       (line 129)
+* -m <11>:                               realpath invocation. (line  30)
+* -m <12>:                               who invocation.      (line  61)
+* -m <13>:                               uname invocation.    (line  42)
+* -n:                                    cat invocation.      (line  32)
+* -n <1>:                                nl invocation.       (line  93)
+* -N:                                    od invocation.       (line  76)
+* -n <2>:                                pr invocation.       (line 153)
+* -N <1>:                                pr invocation.       (line 174)
+* -n <3>:                                head invocation.     (line  40)
+* -n <4>:                                tail invocation.     (line 126)
+* -n <5>:                                split invocation.    (line  79)
+* -n <6>:                                csplit invocation.   (line  82)
+* -n <7>:                                sort invocation.     (line 166)
+* -n <8>:                                shuf invocation.     (line  31)
+* -n <9>:                                cut invocation.      (line  70)
+* -n <10>:                               What information is listed.
+                                                              (line 227)
+* -N <2>:                                Formatting the file names.
+                                                              (line  17)
+* -n <11>:                               cp invocation.       (line 160)
+* -n <12>:                               mv invocation.       (line  78)
+* -n <13>:                               ln invocation.       (line 109)
+* -n <14>:                               readlink invocation. (line  50)
+* -n <15>:                               echo invocation.     (line  29)
+* -N <3>:                                File characteristic tests.
+                                                              (line  27)
+* -n <16>:                               String tests.        (line  19)
+* -n <17>:                               id invocation.       (line  37)
+* -n <18>:                               uname invocation.    (line  47)
+* -n <19>:                               nice invocation.     (line  51)
+* -n NUMBER:                             shred invocation.    (line 127)
+* -ne:                                   Numeric tests.       (line  16)
+* -nt:                                   File characteristic tests.
+                                                              (line  15)
+* -o:                                    od invocation.       (line 191)
+* -o <1>:                                pr invocation.       (line 180)
+* -o <2>:                                sort invocation.     (line 294)
+* -o <3>:                                shuf invocation.     (line  36)
+* -o <4>:                                Input processing in ptx.
+                                                              (line  35)
+* -O:                                    Output formatting in ptx.
+                                                              (line 100)
+* -o <5>:                                What information is listed.
+                                                              (line 231)
+* -o <6>:                                install invocation.  (line  95)
+* -o <7>:                                truncate invocation. (line  26)
+* -O <1>:                                Access permission tests.
+                                                              (line  28)
+* -o <8>:                                Connectives for test.
+                                                              (line  33)
+* -o <9>:                                uname invocation.    (line  58)
+* -o <10>:                               stdbuf invocation.   (line  30)
+* -ot:                                   File characteristic tests.
+                                                              (line  19)
+* -P:                                    Traversing symlinks. (line  26)
+* -p:                                    nl invocation.       (line 104)
+* -p <1>:                                General output formatting.
+                                                              (line 120)
+* -p <2>:                                dircolors invocation.
+                                                              (line  45)
+* -P <1>:                                cp invocation.       (line 166)
+* -p <3>:                                cp invocation.       (line 173)
+* -p <4>:                                install invocation.  (line 107)
+* -P <2>:                                ln invocation.       (line 128)
+* -p <5>:                                mkdir invocation.    (line  36)
+* -p <6>:                                rmdir invocation.    (line  21)
+* -P <3>:                                chown invocation.    (line 172)
+* -P <4>:                                chgrp invocation.    (line  99)
+* -P <5>:                                df invocation.       (line 149)
+* -P <6>:                                du invocation.       (line 135)
+* -p <7>:                                File type tests.     (line  28)
+* -p <8>:                                tee invocation.      (line  35)
+* -p <9>:                                pathchk invocation.  (line  27)
+* -P <7>:                                pathchk invocation.  (line  40)
+* -p <10>:                               mktemp invocation.   (line 105)
+* -P <8>:                                realpath invocation. (line  40)
+* -P <9>:                                pwd invocation.      (line  22)
+* -p <11>:                               who invocation.      (line  65)
+* -p <12>:                               uname invocation.    (line  51)
+* -P <10>:                               chcon invocation.    (line  56)
+* -q:                                    head invocation.     (line  47)
+* -q <1>:                                tail invocation.     (line 155)
+* -q <2>:                                csplit invocation.   (line 107)
+* -q <3>:                                Formatting the file names.
+                                                              (line  23)
+* -Q:                                    Formatting the file names.
+                                                              (line  30)
+* -q <4>:                                readlink invocation. (line  57)
+* -q <5>:                                mktemp invocation.   (line  92)
+* -q <6>:                                realpath invocation. (line  46)
+* -q <7>:                                who invocation.      (line  69)
+* -r:                                    tac invocation.      (line  26)
+* -r <1>:                                pr invocation.       (line 187)
+* -r <2>:                                sum invocation.      (line  23)
+* -r <3>:                                sort invocation.     (line 189)
+* -R:                                    sort invocation.     (line 195)
+* -r <4>:                                shuf invocation.     (line  47)
+* -r <5>:                                Input processing in ptx.
+                                                              (line  48)
+* -R <1>:                                Output formatting in ptx.
+                                                              (line  56)
+* -R <2>:                                Which files are listed.
+                                                              (line  91)
+* -r <6>:                                Sorting the output.  (line  25)
+* -R <3>:                                cp invocation.       (line 262)
+* -r <7>:                                cp invocation.       (line 262)
+* -r <8>:                                rm invocation.       (line  96)
+* -R <4>:                                rm invocation.       (line  96)
+* -r <9>:                                ln invocation.       (line 137)
+* -R <5>:                                chown invocation.    (line 151)
+* -R <6>:                                chgrp invocation.    (line  77)
+* -R <7>:                                chmod invocation.    (line  73)
+* -r <10>:                               touch invocation.    (line  89)
+* -r <11>:                               truncate invocation. (line  30)
+* -r <12>:                               Access permission tests.
+                                                              (line  15)
+* -r <13>:                               id invocation.       (line  42)
+* -r <14>:                               who invocation.      (line  74)
+* -r <15>:                               Options for date.    (line  71)
+* -R <8>:                                Options for date.    (line  85)
+* -r <16>:                               uname invocation.    (line  62)
+* -R <9>:                                chcon invocation.    (line  35)
+* -r <17>:                               chcon invocation.    (line  69)
+* -r <18>:                               runcon invocation.   (line  40)
+* -S:                                    Backup options.      (line  49)
+* -s:                                    cat invocation.      (line  37)
+* -s <1>:                                tac invocation.      (line  30)
+* -s <2>:                                nl invocation.       (line 108)
+* -S <1>:                                od invocation.       (line  81)
+* -s <3>:                                od invocation.       (line 194)
+* -s <4>:                                fmt invocation.      (line  47)
+* -s <5>:                                pr invocation.       (line 192)
+* -S <2>:                                pr invocation.       (line 201)
+* -s <6>:                                fold invocation.     (line  29)
+* -s <7>:                                tail invocation.     (line 175)
+* -s <8>:                                csplit invocation.   (line 107)
+* -s <9>:                                sum invocation.      (line  29)
+* -s <10>:                               sort invocation.     (line 315)
+* -S <3>:                                sort invocation.     (line 322)
+* -s <11>:                               uniq invocation.     (line  42)
+* -S <4>:                                Input processing in ptx.
+                                                              (line  65)
+* -s <12>:                               cut invocation.      (line  74)
+* -s <13>:                               paste invocation.    (line  52)
+* -s <14>:                               tr invocation.       (line  42)
+* -s <15>:                               What information is listed.
+                                                              (line 236)
+* -S <5>:                                Sorting the output.  (line  32)
+* -s <16>:                               cp invocation.       (line 350)
+* -S <6>:                                cp invocation.       (line 358)
+* -s <17>:                               install invocation.  (line 117)
+* -S <7>:                                install invocation.  (line 124)
+* -S <8>:                                mv invocation.       (line 130)
+* -s <18>:                               ln invocation.       (line 162)
+* -S <9>:                                ln invocation.       (line 168)
+* -s <19>:                               readlink invocation. (line  57)
+* -S <10>:                               du invocation.       (line 140)
+* -s <20>:                               du invocation.       (line 155)
+* -s <21>:                               truncate invocation. (line  34)
+* -S <11>:                               File type tests.     (line  31)
+* -s <22>:                               File characteristic tests.
+                                                              (line  12)
+* -s <23>:                               basename invocation. (line  38)
+* -s <24>:                               realpath invocation. (line  64)
+* -s <25>:                               tty invocation.      (line  18)
+* -s <26>:                               who invocation.      (line  78)
+* -s <27>:                               Options for date.    (line 129)
+* -s <28>:                               uname invocation.    (line  66)
+* -S <12>:                               env invocation.      (line 192)
+* -s <29>:                               timeout invocation.  (line  58)
+* -s <30>:                               seq invocation.      (line  45)
+* -s BYTES:                              shred invocation.    (line 138)
+* -S, env and single quotes:             env invocation.      (line 268)
+* -t:                                    cat invocation.      (line  41)
+* -T:                                    cat invocation.      (line  45)
+* -t <1>:                                od invocation.       (line  90)
+* -t <2>:                                fmt invocation.      (line  40)
+* -t <3>:                                pr invocation.       (line 210)
+* -T <1>:                                pr invocation.       (line 220)
+* -t <4>:                                split invocation.    (line 152)
+* -t <5>:                                cksum common options.
+                                                              (line  89)
+* -t <6>:                                sort invocation.     (line 338)
+* -T <2>:                                sort invocation.     (line 358)
+* -T <3>:                                Output formatting in ptx.
+                                                              (line 118)
+* -t <7>:                                tr invocation.       (line  47)
+* -t <8>:                                expand invocation.   (line  22)
+* -t <9>:                                unexpand invocation. (line  24)
+* -t <10>:                               Sorting the output.  (line  36)
+* -T <4>:                                General output formatting.
+                                                              (line 129)
+* -t <11>:                               cp invocation.       (line 363)
+* -T <5>:                                cp invocation.       (line 367)
+* -t <12>:                               install invocation.  (line 129)
+* -T <6>:                                install invocation.  (line 134)
+* -t <13>:                               mv invocation.       (line 135)
+* -T <7>:                                mv invocation.       (line 139)
+* -t <14>:                               ln invocation.       (line 173)
+* -T <8>:                                ln invocation.       (line 177)
+* -t <15>:                               df invocation.       (line 195)
+* -T <9>:                                df invocation.       (line 201)
+* -t <16>:                               du invocation.       (line 159)
+* -t <17>:                               stat invocation.     (line  70)
+* -t <18>:                               File type tests.     (line  34)
+* -t <19>:                               mktemp invocation.   (line 121)
+* -t <20>:                               who invocation.      (line  82)
+* -T <10>:                               who invocation.      (line  94)
+* -t <21>:                               chcon invocation.    (line  73)
+* -t <22>:                               runcon invocation.   (line  44)
+* -u:                                    cat invocation.      (line  48)
+* -u <1>:                                fmt invocation.      (line  53)
+* -u <2>:                                split invocation.    (line 159)
+* -u <3>:                                sort invocation.     (line 374)
+* -u <4>:                                uniq invocation.     (line 128)
+* -u <5>:                                Sorting the output.  (line  44)
+* -U:                                    Sorting the output.  (line  64)
+* -u <6>:                                cp invocation.       (line 372)
+* -u <7>:                                mv invocation.       (line  91)
+* -u <8>:                                shred invocation.    (line 144)
+* -u <9>:                                Access permission tests.
+                                                              (line  18)
+* -u <10>:                               mktemp invocation.   (line  97)
+* -u <11>:                               id invocation.       (line  47)
+* -u <12>:                               who invocation.      (line  85)
+* -u <13>:                               Options for date.    (line 135)
+* -u <14>:                               chcon invocation.    (line  65)
+* -u <15>:                               runcon invocation.   (line  36)
+* -u <16>:                               env invocation.      (line  96)
+* -v:                                    cat invocation.      (line  52)
+* -v <1>:                                nl invocation.       (line 113)
+* -v <2>:                                od invocation.       (line 150)
+* -v <3>:                                pr invocation.       (line 225)
+* -v <4>:                                head invocation.     (line  51)
+* -v <5>:                                tail invocation.     (line 186)
+* -V:                                    sort invocation.     (line 183)
+* -v <6>:                                Sorting the output.  (line  71)
+* -v <7>:                                cp invocation.       (line 407)
+* -v <8>:                                install invocation.  (line 139)
+* -v <9>:                                mv invocation.       (line 122)
+* -v <10>:                               rm invocation.       (line 100)
+* -v <11>:                               shred invocation.    (line 159)
+* -v <12>:                               ln invocation.       (line 182)
+* -v <13>:                               mkdir invocation.    (line  54)
+* -v <14>:                               readlink invocation. (line  61)
+* -v <15>:                               rmdir invocation.    (line  30)
+* -v <16>:                               chown invocation.    (line 143)
+* -v <17>:                               chgrp invocation.    (line  69)
+* -v <18>:                               chmod invocation.    (line  63)
+* -v <19>:                               uname invocation.    (line  77)
+* -v <20>:                               chcon invocation.    (line  61)
+* -v <21>:                               env invocation.      (line 177)
+* -v <22>:                               timeout invocation.  (line  64)
+* -w:                                    nl invocation.       (line 118)
+* -w <1>:                                od invocation.       (line 157)
+* -w <2>:                                base64 invocation.   (line  25)
+* -w <3>:                                fmt invocation.      (line  59)
+* -w <4>:                                pr invocation.       (line 229)
+* -W:                                    pr invocation.       (line 239)
+* -w <5>:                                fold invocation.     (line  35)
+* -w <6>:                                wc invocation.       (line  55)
+* -w <7>:                                cksum common options.
+                                                              (line  99)
+* -w <8>:                                uniq invocation.     (line 134)
+* -W <1>:                                Input processing in ptx.
+                                                              (line 105)
+* -w <9>:                                Output formatting in ptx.
+                                                              (line  32)
+* -w <10>:                               General output formatting.
+                                                              (line 149)
+* -w <11>:                               Access permission tests.
+                                                              (line  21)
+* -w <12>:                               who invocation.      (line  94)
+* -w <13>:                               seq invocation.      (line  50)
+* -WIDTH:                                fmt invocation.      (line  59)
+* -x:                                    od invocation.       (line 197)
+* -x <1>:                                split invocation.    (line 135)
+* -X:                                    Sorting the output.  (line  83)
+* -x <2>:                                General output formatting.
+                                                              (line 125)
+* -x <3>:                                cp invocation.       (line 411)
+* -x <4>:                                shred invocation.    (line 164)
+* -x <5>:                                df invocation.       (line 224)
+* -x <6>:                                du invocation.       (line 261)
+* -x <7>:                                Access permission tests.
+                                                              (line  24)
+* -X FILE:                               du invocation.       (line 250)
+* -z:                                    head invocation.     (line  55)
+* -z <1>:                                tail invocation.     (line 190)
+* -z <2>:                                csplit invocation.   (line  96)
+* -z <3>:                                cksum common options.
+                                                              (line 109)
+* -z <4>:                                sort invocation.     (line 389)
+* -z <5>:                                shuf invocation.     (line  55)
+* -z <6>:                                uniq invocation.     (line 140)
+* -z <7>:                                comm invocation.     (line  89)
+* -z <8>:                                cut invocation.      (line  94)
+* -z <9>:                                paste invocation.    (line  72)
+* -z <10>:                               General options in join.
+                                                              (line  93)
+* -Z:                                    What information is listed.
+                                                              (line 259)
+* -Z <1>:                                cp invocation.       (line 417)
+* -Z <2>:                                install invocation.  (line 143)
+* -Z <3>:                                mv invocation.       (line 144)
+* -z <11>:                               shred invocation.    (line 175)
+* -Z <4>:                                mkdir invocation.    (line  59)
+* -Z <5>:                                mkfifo invocation.   (line  28)
+* -Z <6>:                                mknod invocation.    (line  53)
+* -z <12>:                               readlink invocation. (line  65)
+* -z <13>:                               String tests.        (line  15)
+* -z <14>:                               basename invocation. (line  42)
+* -z <15>:                               dirname invocation.  (line  31)
+* -z <16>:                               realpath invocation. (line  71)
+* -Z <7>:                                id invocation.       (line  51)
+* -z <17>:                               id invocation.       (line  58)
+* -z <18>:                               numfmt invocation.   (line 115)
+* /:                                     Numeric expressions. (line  16)
+* 128-bit checksum:                      md5sum invocation.   (line   6)
+* 16-bit checksum:                       sum invocation.      (line   6)
+* 160-bit checksum:                      sha1sum invocation.  (line   6)
+* 224-bit checksum:                      sha2 utilities.      (line   6)
+* 256-bit checksum:                      sha2 utilities.      (line   6)
+* 32-bit checksum:                       cksum invocation.    (line   6)
+* 384-bit checksum:                      sha2 utilities.      (line   6)
+* 512-bit checksum:                      b2sum invocation.    (line   6)
+* 512-bit checksum <1>:                  sha2 utilities.      (line   6)
+* <:                                     Relations for expr.  (line  22)
+* <=:                                    Relations for expr.  (line  22)
+* =:                                     Relations for expr.  (line  22)
+* = <1>:                                 String tests.        (line  22)
+* ==:                                    Relations for expr.  (line  22)
+* == <1>:                                String tests.        (line  25)
+* >:                                     Relations for expr.  (line  22)
+* >=:                                    Relations for expr.  (line  22)
+* \( regexp operator:                    String expressions.  (line  23)
+* \+ regexp operator:                    String expressions.  (line  27)
+* \? regexp operator:                    String expressions.  (line  27)
+* \c:                                    printf invocation.   (line  28)
+* \OOO:                                  printf invocation.   (line  67)
+* \uhhhh:                                printf invocation.   (line  74)
+* \Uhhhhhhhh:                            printf invocation.   (line  74)
+* \xHH:                                  printf invocation.   (line  67)
+* \| regexp operator:                    String expressions.  (line  27)
+* _POSIX2_VERSION:                       Standards conformance.
+                                                              (line  20)
+* _POSIX2_VERSION <1>:                   tail invocation.     (line 205)
+* _POSIX2_VERSION <2>:                   sort invocation.     (line 421)
+* _POSIX2_VERSION <3>:                   uniq invocation.     (line  47)
+* _POSIX2_VERSION <4>:                   touch invocation.    (line 107)
+* |:                                     Relations for expr.  (line  11)
+* abbreviations for months:              Calendar date items. (line  36)
+* access control lists (ACLs):           cp invocation.       (line 178)
+* access control lists (ACLs) <1>:       cp invocation.       (line 220)
+* access permission tests:               Access permission tests.
+                                                              (line   6)
+* access permissions, changing:          chmod invocation.    (line   6)
+* access time, changing:                 touch invocation.    (line  48)
+* access timestamp:                      dd invocation.       (line 324)
+* access timestamp, printing or sorting files by: Sorting the output.
+                                                              (line  44)
+* access timestamp, show the most recent: du invocation.      (line 208)
+* across columns:                        pr invocation.       (line  62)
+* across, listing files:                 General output formatting.
+                                                              (line 125)
+* adding permissions:                    Setting Permissions. (line  35)
+* addition:                              Numeric expressions. (line  12)
+* ago in date strings:                   Relative items in date strings.
+                                                              (line  23)
+* all lines, grouping:                   uniq invocation.     (line 101)
+* all repeated lines, outputting:        uniq invocation.     (line  70)
+* alnum:                                 Character arrays.    (line 108)
+* alpha:                                 Character arrays.    (line 110)
+* alternate ebcdic, converting to:       dd invocation.       (line 149)
+* always classify option:                General output formatting.
+                                                              (line  59)
+* always color option:                   General output formatting.
+                                                              (line  32)
+* always hyperlink option:               General output formatting.
+                                                              (line  77)
+* always interactive option:             rm invocation.       (line  60)
+* always total option:                   wc invocation.       (line  76)
+* am i:                                  who invocation.      (line  21)
+* am in date strings:                    Time of day items.   (line  21)
+* and operator:                          Connectives for test.
+                                                              (line  29)
+* and operator <1>:                      Relations for expr.  (line  17)
+* append:                                dd invocation.       (line 253)
+* appending to the output file:          dd invocation.       (line 253)
+* appropriate privileges:                install invocation.  (line  95)
+* appropriate privileges <1>:            Setting the time.    (line   6)
+* appropriate privileges <2>:            hostname invocation. (line   6)
+* appropriate privileges <3>:            nice invocation.     (line   6)
+* arbitrary date strings, debugging:     Options for date.    (line  29)
+* arbitrary date strings, parsing:       Options for date.    (line  15)
+* arbitrary text, displaying:            echo invocation.     (line   6)
+* arch:                                  arch invocation.     (line   6)
+* arithmetic tests:                      Numeric tests.       (line   6)
+* arrays of characters in tr:            Character arrays.    (line   6)
+* ASCII dump of files:                   od invocation.       (line   6)
+* ascii, converting to:                  dd invocation.       (line 138)
+* atime:                                 File timestamps.     (line   6)
+* atime, changing:                       touch invocation.    (line  48)
+* atime, printing or sorting files by:   Sorting the output.  (line  44)
+* atime, show the most recent:           du invocation.       (line 208)
+* attribute caching:                     stat invocation.     (line  33)
+* attributes, file:                      Changing file attributes.
+                                                              (line   6)
+* authors of parse_datetime:             Authors of parse_datetime.
+                                                              (line   6)
+* auto classify option:                  General output formatting.
+                                                              (line  58)
+* auto color option:                     General output formatting.
+                                                              (line  31)
+* auto hyperlink option:                 General output formatting.
+                                                              (line  76)
+* auto total option:                     wc invocation.       (line  73)
+* b for block special file:              mknod invocation.    (line  31)
+* b2sum:                                 b2sum invocation.    (line   6)
+* background jobs, stopping at terminal write: Local.         (line  41)
+* backslash escapes:                     Character arrays.    (line  30)
+* backslash escapes <1>:                 echo invocation.     (line  32)
+* backslash escapes <2>:                 echo invocation.     (line  68)
+* backslash sequences for file names:    Formatting the file names.
+                                                              (line  11)
+* backup files, ignoring:                Which files are listed.
+                                                              (line  23)
+* backup options:                        Backup options.      (line   6)
+* backup suffix:                         Backup options.      (line  49)
+* backups, making:                       Backup options.      (line  13)
+* backups, making <1>:                   cp invocation.       (line  79)
+* backups, making <2>:                   install invocation.  (line  41)
+* backups, making <3>:                   mv invocation.       (line  56)
+* backups, making <4>:                   ln invocation.       (line  82)
+* backups, making only:                  cp invocation.       (line  51)
+* base32:                                base32 invocation.   (line   6)
+* base32 encoding:                       base32 invocation.   (line   6)
+* base32 encoding <1>:                   basenc invocation.   (line   6)
+* base64:                                base64 invocation.   (line   6)
+* base64 checksum encoding:              cksum general options.
+                                                              (line  23)
+* Base64 decoding:                       base64 invocation.   (line  33)
+* base64 encoding:                       base64 invocation.   (line   6)
+* basename:                              basename invocation. (line   6)
+* basenc:                                basenc invocation.   (line   6)
+* baud rate, setting:                    Special.             (line  54)
+* beeping at input buffer full:          Input.               (line  59)
+* beginning of time:                     Time conversion specifiers.
+                                                              (line  32)
+* beginning of time, for POSIX:          Seconds since the Epoch.
+                                                              (line  13)
+* Bellovin, Steven M.:                   Authors of parse_datetime.
+                                                              (line   6)
+* Berets, Jim:                           Authors of parse_datetime.
+                                                              (line   6)
+* Berry, K.:                             Introduction.        (line  29)
+* Berry, K. <1>:                         Authors of parse_datetime.
+                                                              (line  19)
+* binary:                                dd invocation.       (line 341)
+* binary I/O:                            dd invocation.       (line 341)
+* binary input files:                    cksum common options.
+                                                              (line   5)
+* bind mount:                            rm invocation.       (line  68)
+* bind mount <1>:                        stat invocation.     (line 199)
+* birth time, printing or sorting files by: Sorting the output.
+                                                              (line  57)
+* birthtime:                             File timestamps.     (line   6)
+* BLAKE2:                                b2sum invocation.    (line   6)
+* BLAKE2 hash length:                    cksum general options.
+                                                              (line  39)
+* BLAKE2 hash length <1>:                b2sum invocation.    (line  24)
+* blank:                                 Character arrays.    (line 112)
+* blank lines, numbering:                nl invocation.       (line  85)
+* blanks, ignoring leading:              sort invocation.     (line  79)
+* block (space-padding):                 dd invocation.       (line 159)
+* block size:                            Block size.          (line   6)
+* block size <1>:                        dd invocation.       (line  60)
+* block size of conversion:              dd invocation.       (line  67)
+* block size of input:                   dd invocation.       (line  52)
+* block size of output:                  dd invocation.       (line  56)
+* block special check:                   File type tests.     (line  10)
+* block special files:                   mknod invocation.    (line  11)
+* block special files, creating:         mknod invocation.    (line   6)
+* BLOCKSIZE:                             Block size.          (line  12)
+* BLOCK_SIZE:                            Block size.          (line  12)
+* body, numbering:                       nl invocation.       (line  17)
+* Bourne shell syntax for color setup:   dircolors invocation.
+                                                              (line  34)
+* breaks, cause interrupts:              Input.               (line  12)
+* breaks, ignoring:                      Input.               (line   9)
+* brkint:                                Input.               (line  12)
+* bs:                                    dd invocation.       (line  60)
+* BSD output:                            cksum common options.
+                                                              (line  77)
+* BSD sum:                               sum invocation.      (line  23)
+* BSD tail:                              tail invocation.     (line  26)
+* BSD touch compatibility:               touch invocation.    (line  66)
+* bsN:                                   Output.              (line  55)
+* btrfs file system type:                df invocation.       (line 212)
+* bugs, reporting:                       Introduction.        (line  12)
+* built-in shell commands, conflicts with: mknod invocation.  (line  20)
+* built-in shell commands, conflicts with <1>: stat invocation.
+                                                              (line  15)
+* built-in shell commands, conflicts with <2>: echo invocation.
+                                                              (line  11)
+* built-in shell commands, conflicts with <3>: printf invocation.
+                                                              (line  16)
+* built-in shell commands, conflicts with <4>: test invocation.
+                                                              (line  28)
+* built-in shell commands, conflicts with <5>: pwd invocation.
+                                                              (line  30)
+* built-in shell commands, conflicts with <6>: nice invocation.
+                                                              (line  38)
+* built-in shell commands, conflicts with <7>: kill invocation.
+                                                              (line  13)
+* built-in shell commands, conflicts with <8>: sleep invocation.
+                                                              (line  40)
+* byte count:                            wc invocation.       (line   6)
+* byte-swapping:                         od invocation.       (line  51)
+* byte-swapping <1>:                     dd invocation.       (line 195)
+* c for character special file:          mknod invocation.    (line  34)
+* C shell syntax for color setup:        dircolors invocation.
+                                                              (line  40)
+* C-s/C-q flow control:                  Input.               (line  40)
+* calendar date item:                    Calendar date items. (line   6)
+* calling combined multi-call program:   Multi-call invocation.
+                                                              (line   6)
+* canonical file name:                   readlink invocation. (line   6)
+* canonical file name <1>:               realpath invocation. (line   6)
+* canonicalize a file name:              readlink invocation. (line   6)
+* canonicalize a file name <1>:          realpath invocation. (line   6)
+* case folding:                          sort invocation.     (line  94)
+* case translation:                      Local.               (line  36)
+* case, ignored in dates:                General date syntax. (line  60)
+* cat:                                   cat invocation.      (line   6)
+* cbreak:                                Combination.         (line  52)
+* cbs:                                   dd invocation.       (line  67)
+* CD-ROM file system type:               df invocation.       (line 216)
+* cdfs file system type:                 df invocation.       (line 216)
+* cdtrdsr:                               Control.             (line  44)
+* change or print terminal settings:     stty invocation.     (line   6)
+* change SELinux context:                chcon invocation.    (line   6)
+* changed files, verbosely describing:   chgrp invocation.    (line  24)
+* changed owners, verbosely describing:  chown invocation.    (line  74)
+* changing access permissions:           chmod invocation.    (line   6)
+* changing file attributes:              Changing file attributes.
+                                                              (line   6)
+* changing file ownership:               chown invocation.    (line   6)
+* changing file timestamps:              touch invocation.    (line   6)
+* changing group ownership:              chown invocation.    (line   6)
+* changing group ownership <1>:          chgrp invocation.    (line   6)
+* changing security context:             chcon invocation.    (line   6)
+* changing special mode bits:            Changing Special Mode Bits.
+                                                              (line   6)
+* character classes:                     Character arrays.    (line  94)
+* character count:                       wc invocation.       (line   6)
+* character size:                        Control.             (line  24)
+* character special check:               File type tests.     (line  13)
+* character special files:               mknod invocation.    (line  11)
+* character special files, creating:     mknod invocation.    (line   6)
+* characters, special:                   Characters.          (line   6)
+* chcon:                                 chcon invocation.    (line   6)
+* check file types:                      test invocation.     (line   6)
+* checking whether a file is sorted:     sort invocation.     (line  39)
+* checking whether a file is sorted <1>: sort invocation.     (line  47)
+* checksum, 128-bit:                     md5sum invocation.   (line   6)
+* checksum, 16-bit:                      sum invocation.      (line   6)
+* checksum, 160-bit:                     sha1sum invocation.  (line   6)
+* checksum, 224-bit:                     sha2 utilities.      (line   6)
+* checksum, 256-bit:                     sha2 utilities.      (line   6)
+* checksum, 32-bit:                      cksum invocation.    (line   6)
+* checksum, 384-bit:                     sha2 utilities.      (line   6)
+* checksum, 512-bit:                     b2sum invocation.    (line   6)
+* checksum, 512-bit <1>:                 sha2 utilities.      (line   6)
+* chgrp:                                 chgrp invocation.    (line   6)
+* chmod:                                 chmod invocation.    (line   6)
+* chown:                                 chown invocation.    (line   6)
+* chroot:                                chroot invocation.   (line   6)
+* cio:                                   dd invocation.       (line 261)
+* cksum:                                 cksum invocation.    (line   6)
+* clocal:                                Control.             (line  38)
+* clock skew:                            Formatting file timestamps.
+                                                              (line  11)
+* clock skew <1>:                        File timestamps.     (line  39)
+* clone:                                 cp invocation.       (line 275)
+* cmspar:                                Control.             (line  16)
+* cntrl:                                 Character arrays.    (line 114)
+* color database, printing:              dircolors invocation.
+                                                              (line  45)
+* color setup:                           dircolors invocation.
+                                                              (line   6)
+* color, distinguishing file types with: General output formatting.
+                                                              (line  28)
+* cols:                                  Special.             (line  27)
+* column to wrap data after:             base64 invocation.   (line  25)
+* COLUMNS:                               General output formatting.
+                                                              (line 149)
+* COLUMNS <1>:                           Special.             (line  41)
+* columns:                               Special.             (line  27)
+* combination settings:                  Combination.         (line   6)
+* combined:                              Multi-call invocation.
+                                                              (line   6)
+* combined date and time of day item:    Combined date and time of day items.
+                                                              (line   6)
+* comm:                                  comm invocation.     (line   6)
+* command-line operands to shuffle:      shuf invocation.     (line  19)
+* commands for controlling processes:    Process control.     (line   6)
+* commands for delaying:                 Delaying.            (line   6)
+* commands for exit status:              Conditions.          (line   6)
+* commands for file name manipulation:   File name manipulation.
+                                                              (line   6)
+* commands for invoking other commands:  Modified command invocation.
+                                                              (line   6)
+* commands for printing text:            Printing text.       (line   6)
+* commands for printing the working context: Working context. (line   6)
+* commands for printing user information: User information.   (line   6)
+* commands for redirection:              Redirection.         (line   6)
+* commands for SELinux context:          SELinux context.     (line   6)
+* commands for system context:           System context.      (line   6)
+* commas, outputting between files:      General output formatting.
+                                                              (line 114)
+* comments, in dates:                    General date syntax. (line  60)
+* common field, joining on:              join invocation.     (line   6)
+* common lines:                          comm invocation.     (line  18)
+* common options:                        Common options.      (line   6)
+* compare values:                        test invocation.     (line   6)
+* comparing sorted files:                comm invocation.     (line   6)
+* comparison operators:                  Relations for expr.  (line  22)
+* compression and du:                    du invocation.       (line 277)
+* concatenate and write files:           cat invocation.      (line   6)
+* concurrent I/O:                        dd invocation.       (line 261)
+* conditional executability:             Conditional Executability.
+                                                              (line   6)
+* conditions:                            Conditions.          (line   6)
+* conflicts with shell built-ins:        mknod invocation.    (line  20)
+* conflicts with shell built-ins <1>:    stat invocation.     (line  15)
+* conflicts with shell built-ins <2>:    echo invocation.     (line  11)
+* conflicts with shell built-ins <3>:    printf invocation.   (line  16)
+* conflicts with shell built-ins <4>:    test invocation.     (line  28)
+* conflicts with shell built-ins <5>:    pwd invocation.      (line  30)
+* conflicts with shell built-ins <6>:    nice invocation.     (line  38)
+* conflicts with shell built-ins <7>:    kill invocation.     (line  13)
+* conflicts with shell built-ins <8>:    sleep invocation.    (line  40)
+* connectives, logical:                  Connectives for test.
+                                                              (line   6)
+* connectives, logical <1>:              Relations for expr.  (line   6)
+* constant parity:                       Control.             (line  16)
+* context splitting:                     csplit invocation.   (line   6)
+* context, system:                       System context.      (line   6)
+* control characters, using ^C:          Local.               (line  51)
+* control settings:                      Control.             (line   6)
+* controlling terminal:                  dd invocation.       (line 330)
+* conv:                                  dd invocation.       (line 132)
+* conversion block size:                 dd invocation.       (line  67)
+* conversion specifiers, date:           Date conversion specifiers.
+                                                              (line   6)
+* conversion specifiers, literal:        Literal conversion specifiers.
+                                                              (line   6)
+* conversion specifiers, time:           Time conversion specifiers.
+                                                              (line   6)
+* converting tabs to spaces:             expand invocation.   (line   6)
+* converting while copying a file:       dd invocation.       (line   6)
+* cooked:                                Combination.         (line  37)
+* Coordinated Universal Time:            Options for date.    (line 135)
+* copy on write:                         cp invocation.       (line 275)
+* copy-on-write and du:                  du invocation.       (line 272)
+* copying directories recursively:       cp invocation.       (line  96)
+* copying directories recursively <1>:   cp invocation.       (line 262)
+* copying existing permissions:          Copying Permissions. (line   6)
+* copying files:                         cat invocation.      (line   6)
+* copying files and directories:         cp invocation.       (line   6)
+* copying files and setting attributes:  install invocation.  (line   6)
+* core utilities:                        Top.                 (line  18)
+* count:                                 dd invocation.       (line  86)
+* COW:                                   cp invocation.       (line 275)
+* cp:                                    cp invocation.       (line   6)
+* crashes and corruption:                sync invocation.     (line  17)
+* CRC checksum:                          cksum invocation.    (line   6)
+* cread:                                 Control.             (line  35)
+* creating directories:                  mkdir invocation.    (line   6)
+* creating FIFOs (named pipes):          mkfifo invocation.   (line   6)
+* creating links (hard only):            link invocation.     (line   6)
+* creating links (hard or soft):         ln invocation.       (line   6)
+* creating output file, avoiding:        dd invocation.       (line 210)
+* creating output file, requiring:       dd invocation.       (line 206)
+* creation timestamp, printing or sorting files by: Sorting the output.
+                                                              (line  57)
+* crN:                                   Output.              (line  45)
+* crown margin:                          fmt invocation.      (line  34)
+* crt:                                   Combination.         (line  75)
+* crterase:                              Local.               (line  22)
+* crtkill:                               Local.               (line  56)
+* crtscts:                               Control.             (line  41)
+* csh syntax for color setup:            dircolors invocation.
+                                                              (line  40)
+* csN:                                   Control.             (line  24)
+* csplit:                                csplit invocation.   (line   6)
+* cstopb:                                Control.             (line  32)
+* ctime:                                 File timestamps.     (line   6)
+* ctime, printing or sorting by:         Sorting the output.  (line  13)
+* ctime, show the most recent:           du invocation.       (line 202)
+* ctlecho:                               Local.               (line  51)
+* current working directory, printing:   pwd invocation.      (line   6)
+* cut:                                   cut invocation.      (line   6)
+* cyclic redundancy check:               cksum invocation.    (line   6)
+* data modification time, printing or sorting files by: Sorting the output.
+                                                              (line  50)
+* data, erasing:                         shred invocation.    (line   6)
+* database for color setup, printing:    dircolors invocation.
+                                                              (line  45)
+* date:                                  date invocation.     (line   6)
+* date and time of day format, ISO 8601: Combined date and time of day items.
+                                                              (line   6)
+* date conversion specifiers:            Date conversion specifiers.
+                                                              (line   6)
+* date format, ISO 8601:                 Calendar date items. (line  28)
+* date input formats:                    Date input formats.  (line   6)
+* date options:                          Options for date.    (line   6)
+* date strings, debugging:               Options for date.    (line  29)
+* date strings, parsing:                 Options for date.    (line  15)
+* day in date strings:                   Relative items in date strings.
+                                                              (line  15)
+* day in date strings <1>:               Relative items in date strings.
+                                                              (line  29)
+* day of week item:                      Day of week items.   (line   6)
+* dd:                                    dd invocation.       (line   6)
+* ddrescue:                              dd invocation.       (line 397)
+* debugging date strings:                Options for date.    (line  29)
+* debugging, copying:                    cp invocation.       (line 114)
+* debugging, copying <1>:                install invocation.  (line  72)
+* debugging, copying <2>:                mv invocation.       (line  60)
+* debugging, env -S:                     env invocation.      (line 277)
+* dec:                                   Combination.         (line  78)
+* decctlq:                               Combination.         (line  63)
+* Decode base64 data:                    base64 invocation.   (line  33)
+* delay for a specified time:            sleep invocation.    (line   6)
+* delaying commands:                     Delaying.            (line   6)
+* deleting characters:                   Squeezing and deleting.
+                                                              (line   6)
+* dereferencing symbolic links:          ln invocation.       (line  42)
+* descriptor follow option:              tail invocation.     (line  57)
+* destination directory:                 Target directory.    (line  15)
+* destination directory <1>:             Target directory.    (line  31)
+* destination directory <2>:             cp invocation.       (line 363)
+* destination directory <3>:             cp invocation.       (line 367)
+* destination directory <4>:             install invocation.  (line 129)
+* destination directory <5>:             install invocation.  (line 134)
+* destination directory <6>:             mv invocation.       (line 135)
+* destination directory <7>:             mv invocation.       (line 139)
+* destination directory <8>:             ln invocation.       (line 173)
+* destination directory <9>:             ln invocation.       (line 177)
+* destinations, multiple output:         tee invocation.      (line   6)
+* device file:                           df invocation.       (line  30)
+* df:                                    df invocation.       (line   6)
+* DF_BLOCK_SIZE:                         Block size.          (line  12)
+* diagnostic:                            chcon invocation.    (line  61)
+* dictionary order:                      sort invocation.     (line  87)
+* differing lines:                       comm invocation.     (line  18)
+* digest:                                cksum invocation.    (line   6)
+* digest algorithm:                      cksum general options.
+                                                              (line   5)
+* digit:                                 Character arrays.    (line 116)
+* dir:                                   dir invocation.      (line   6)
+* dircolors:                             dircolors invocation.
+                                                              (line   6)
+* direct:                                dd invocation.       (line 267)
+* direct I/O:                            dd invocation.       (line 267)
+* directories, copying:                  cp invocation.       (line   6)
+* directories, copying recursively:      cp invocation.       (line  96)
+* directories, copying recursively <1>:  cp invocation.       (line 262)
+* directories, creating:                 mkdir invocation.    (line   6)
+* directories, creating with given attributes: install invocation.
+                                                              (line  67)
+* directories, removing:                 rm invocation.       (line  35)
+* directories, removing (recursively):   rm invocation.       (line  96)
+* directories, removing empty:           rmdir invocation.    (line   6)
+* directory:                             dd invocation.       (line 275)
+* directory check:                       File type tests.     (line  16)
+* directory components, printing:        dirname invocation.  (line   6)
+* directory deletion, ignoring failures: rmdir invocation.    (line  17)
+* directory deletion, reporting:         rmdir invocation.    (line  30)
+* directory I/O:                         dd invocation.       (line 275)
+* directory listing:                     ls invocation.       (line   6)
+* directory listing, brief:              dir invocation.      (line   6)
+* directory listing, recursive:          Which files are listed.
+                                                              (line  91)
+* directory listing, verbose:            vdir invocation.     (line   6)
+* directory order, listing by:           Sorting the output.  (line  18)
+* directory, creating temporary:         mktemp invocation.   (line   6)
+* directory, stripping from file names:  basename invocation. (line   6)
+* dired Emacs mode support:              What information is listed.
+                                                              (line  16)
+* dirname:                               dirname invocation.  (line   6)
+* disabling special characters:          Characters.          (line  12)
+* disambiguating group names and IDs:    Disambiguating names and IDs.
+                                                              (line   6)
+* discard:                               Characters.          (line  39)
+* discarding file cache:                 dd invocation.       (line 292)
+* disk device file:                      df invocation.       (line  30)
+* disk usage:                            File space usage.    (line   6)
+* disk usage by file system:             df invocation.       (line   6)
+* disk usage for files:                  du invocation.       (line   6)
+* displacement of dates:                 Relative items in date strings.
+                                                              (line   6)
+* displaying text:                       echo invocation.     (line   6)
+* displaying value of a symbolic link:   readlink invocation. (line   6)
+* division:                              Numeric expressions. (line  16)
+* do nothing, successfully:              true invocation.     (line   6)
+* do nothing, unsuccessfully:            false invocation.    (line   6)
+* DOS file system:                       df invocation.       (line 220)
+* double spacing:                        pr invocation.       (line  74)
+* down columns:                          pr invocation.       (line  49)
+* drain:                                 Special.             (line  30)
+* dsusp:                                 Characters.          (line  58)
+* dsync:                                 dd invocation.       (line 281)
+* DTR/DSR flow control:                  Control.             (line  44)
+* du:                                    du invocation.       (line   6)
+* DU_BLOCK_SIZE:                         Block size.          (line  12)
+* DVD file system type:                  df invocation.       (line 216)
+* ebcdic, converting to:                 dd invocation.       (line 144)
+* echo:                                  echo invocation.     (line   6)
+* echo <1>:                              Local.               (line  18)
+* echoctl:                               Local.               (line  51)
+* echoe:                                 Local.               (line  22)
+* echok:                                 Local.               (line  26)
+* echoke:                                Local.               (line  56)
+* echonl:                                Local.               (line  29)
+* echoprt:                               Local.               (line  46)
+* effective user and group IDs, printing: id invocation.      (line   6)
+* effective user name, printing:         whoami invocation.   (line   6)
+* Eggert, Paul:                          Authors of parse_datetime.
+                                                              (line   6)
+* eight-bit characters:                  Control.             (line  24)
+* eight-bit characters <1>:              Combination.         (line  55)
+* eight-bit input:                       Input.               (line  25)
+* ek:                                    Combination.         (line  22)
+* empty files, creating:                 touch invocation.    (line  11)
+* empty lines, numbering:                nl invocation.       (line  85)
+* endianness:                            od invocation.       (line  51)
+* entire files, output of:               Output of entire files.
+                                                              (line   6)
+* env:                                   env invocation.      (line   6)
+* env -S, and single quotes:             env invocation.      (line 268)
+* env -S, debugging:                     env invocation.      (line 277)
+* env in scripts:                        env invocation.      (line 192)
+* environment variables, printing:       printenv invocation. (line   6)
+* environment, printing:                 env invocation.      (line  50)
+* environment, running a program in a modified: env invocation.
+                                                              (line   6)
+* eof:                                   Characters.          (line  30)
+* eol:                                   Characters.          (line  33)
+* eol2:                                  Characters.          (line  36)
+* Epoch, for POSIX:                      Seconds since the Epoch.
+                                                              (line  13)
+* Epoch, seconds since:                  Time conversion specifiers.
+                                                              (line  32)
+* equal string check:                    String tests.        (line  22)
+* equal string check <1>:                String tests.        (line  25)
+* equivalence classes:                   Character arrays.    (line 133)
+* erase:                                 Characters.          (line  24)
+* erasing data:                          shred invocation.    (line   6)
+* error messages, omitting:              chown invocation.    (line  80)
+* error messages, omitting <1>:          chgrp invocation.    (line  30)
+* error messages, omitting <2>:          chmod invocation.    (line  49)
+* evaluation of expressions:             expr invocation.     (line   6)
+* even parity:                           Control.             (line  13)
+* evenp:                                 Combination.         (line   9)
+* exabyte, definition of:                Block size.          (line 106)
+* examples of date:                      Examples of date.    (line   6)
+* examples of expr:                      Examples of expr.    (line   6)
+* exbibyte, definition of:               Block size.          (line 109)
+* excl:                                  dd invocation.       (line 206)
+* excluding files from du:               du invocation.       (line 250)
+* excluding files from du <1>:           du invocation.       (line 255)
+* executable file check:                 Access permission tests.
+                                                              (line  24)
+* executables and file type, marking:    General output formatting.
+                                                              (line  52)
+* execute/search permission:             Mode Structure.      (line  16)
+* execute/search permission, symbolic:   Setting Permissions. (line  56)
+* existence-of-file check:               File characteristic tests.
+                                                              (line   9)
+* existing backup method:                Backup options.      (line  39)
+* exit status commands:                  Conditions.          (line   6)
+* exit status of chroot:                 chroot invocation.   (line  78)
+* exit status of env:                    env invocation.      (line 197)
+* exit status of expr:                   expr invocation.     (line  42)
+* exit status of false:                  false invocation.    (line   6)
+* exit status of ls:                     ls invocation.       (line  29)
+* exit status of mktemp:                 mktemp invocation.   (line 128)
+* exit status of nice:                   nice invocation.     (line  63)
+* exit status of nohup:                  nohup invocation.    (line  48)
+* exit status of pathchk:                pathchk invocation.  (line  47)
+* exit status of printenv:               printenv invocation. (line  23)
+* exit status of realpath:               realpath invocation. (line  75)
+* exit status of runcon:                 runcon invocation.   (line  50)
+* exit status of sort:                   sort invocation.     (line  58)
+* exit status of stdbuf:                 stdbuf invocation.   (line  70)
+* exit status of test:                   test invocation.     (line  41)
+* exit status of timeout:                timeout invocation.  (line  76)
+* exit status of true:                   true invocation.     (line   6)
+* exit status of tty:                    tty invocation.      (line  20)
+* expand:                                expand invocation.   (line   6)
+* expr:                                  expr invocation.     (line   6)
+* expression evaluation:                 test invocation.     (line   6)
+* expression evaluation <1>:             expr invocation.     (line   6)
+* expressions, numeric:                  Numeric expressions. (line   6)
+* expressions, string:                   String expressions.  (line   6)
+* ext2 file system type:                 df invocation.       (line 212)
+* ext3 file system type:                 df invocation.       (line 212)
+* ext4 file system type:                 df invocation.       (line 212)
+* extended attributes, xattr:            install invocation.  (line  34)
+* extended attributes, xattr <1>:        mv invocation.       (line  30)
+* extension, sorting files by:           Sorting the output.  (line  83)
+* extproc:                               Local.               (line  61)
+* factor:                                factor invocation.   (line   6)
+* failure exit status:                   false invocation.    (line   6)
+* false:                                 false invocation.    (line   6)
+* fat file system file:                  df invocation.       (line 220)
+* fdatasync:                             dd invocation.       (line 223)
+* ffN:                                   Output.              (line  63)
+* field separator character:             sort invocation.     (line 338)
+* fields, padding numeric:               Padding and other flags.
+                                                              (line   6)
+* FIFOs, creating:                       mkfifo invocation.   (line   6)
+* file attributes, changing:             Changing file attributes.
+                                                              (line   6)
+* file characteristic tests:             File characteristic tests.
+                                                              (line   6)
+* file contents, dumping unambiguously:  od invocation.       (line   6)
+* file information, preserving:          cp invocation.       (line 245)
+* file information, preserving, extended attributes, xattr: cp invocation.
+                                                              (line 173)
+* file mode bits, numeric:               Numeric Modes.       (line   6)
+* file name manipulation:                File name manipulation.
+                                                              (line   6)
+* file names, canonicalization:          realpath invocation. (line   6)
+* file names, checking validity and portability: pathchk invocation.
+                                                              (line   6)
+* file names, creating temporary:        mktemp invocation.   (line   6)
+* file names, stripping directory and suffix: basename invocation.
+                                                              (line   6)
+* file offset radix:                     od invocation.       (line  36)
+* file ownership, changing:              chown invocation.    (line   6)
+* file sizes:                            du invocation.       (line  54)
+* File space usage:                      File space usage.    (line   6)
+* file space usage:                      du invocation.       (line   6)
+* file status:                           stat invocation.     (line   6)
+* file system allocation:                What information is listed.
+                                                              (line 236)
+* file system sizes:                     df invocation.       (line  54)
+* file system space, retrieving current data more slowly: df invocation.
+                                                              (line 175)
+* file system space, retrieving old data more quickly: df invocation.
+                                                              (line  85)
+* file system status:                    stat invocation.     (line   6)
+* file system types, limiting output to certain: df invocation.
+                                                              (line  81)
+* file system types, limiting output to certain <1>: df invocation.
+                                                              (line 195)
+* file system types, printing:           df invocation.       (line 201)
+* file system usage:                     df invocation.       (line   6)
+* file systems:                          stat invocation.     (line  28)
+* file systems and hard links:           ln invocation.       (line   6)
+* file systems, omitting copying to different: cp invocation. (line 411)
+* file timestamp resolution:             File timestamps.     (line  45)
+* file timestamps, changing:             touch invocation.    (line   6)
+* file type and executables, marking:    General output formatting.
+                                                              (line  52)
+* file type tests:                       File type tests.     (line   6)
+* file type, marking:                    General output formatting.
+                                                              (line  68)
+* file type, marking <1>:                General output formatting.
+                                                              (line 120)
+* file types:                            Special file types.  (line   9)
+* file types, special:                   Special file types.  (line   6)
+* file utilities:                        Top.                 (line  18)
+* files beginning with -, removing:      rm invocation.       (line 102)
+* files, copying:                        cp invocation.       (line   6)
+* files, creating:                       truncate invocation. (line  11)
+* fingerprint, 128-bit:                  md5sum invocation.   (line   6)
+* fingerprint, 160-bit:                  sha1sum invocation.  (line   6)
+* fingerprint, 224-bit:                  sha2 utilities.      (line   6)
+* fingerprint, 256-bit:                  sha2 utilities.      (line   6)
+* fingerprint, 384-bit:                  sha2 utilities.      (line   6)
+* fingerprint, 512-bit:                  b2sum invocation.    (line   6)
+* fingerprint, 512-bit <1>:              sha2 utilities.      (line   6)
+* first in date strings:                 General date syntax. (line  22)
+* first part of files, outputting:       head invocation.     (line   6)
+* fixed-length records, converting to variable-length: dd invocation.
+                                                              (line  67)
+* floating point:                        Floating point.      (line   6)
+* flow control, hardware:                Control.             (line  41)
+* flow control, hardware <1>:            Control.             (line  44)
+* flow control, software:                Input.               (line  45)
+* flush:                                 Characters.          (line  39)
+* flushing, disabling:                   Local.               (line  32)
+* flusho:                                Local.               (line  67)
+* fmt:                                   fmt invocation.      (line   6)
+* fold:                                  fold invocation.     (line   6)
+* folding long input lines:              fold invocation.     (line   6)
+* footers, numbering:                    nl invocation.       (line  17)
+* force deletion:                        shred invocation.    (line 123)
+* formatting file contents:              Formatting file contents.
+                                                              (line   6)
+* formatting of numbers in seq:          seq invocation.      (line  29)
+* formatting times:                      pr invocation.       (line  78)
+* formatting times <1>:                  Date format specifiers.
+                                                              (line   6)
+* fortnight in date strings:             Relative items in date strings.
+                                                              (line  15)
+* fsync:                                 dd invocation.       (line 234)
+* fullblock:                             dd invocation.       (line 349)
+* general date syntax:                   General date syntax. (line   6)
+* general numeric sort:                  sort invocation.     (line 105)
+* gibibyte, definition of:               Block size.          (line  94)
+* gigabyte, definition of:               Block size.          (line  91)
+* giving away permissions:               Umask and Protection.
+                                                              (line  12)
+* GMT:                                   Options for date.    (line 135)
+* grand total of file system size, usage and available space: df invocation.
+                                                              (line 181)
+* grand total of file system space:      du invocation.       (line  63)
+* graph:                                 Character arrays.    (line 118)
+* Greenwich Mean Time:                   Options for date.    (line 135)
+* group IDs, disambiguating:             Disambiguating names and IDs.
+                                                              (line   6)
+* group names, disambiguating:           Disambiguating names and IDs.
+                                                              (line   6)
+* group owner, default:                  Mode Structure.      (line  27)
+* group ownership of installed files, setting: install invocation.
+                                                              (line  77)
+* group ownership, changing:             chown invocation.    (line   6)
+* group ownership, changing <1>:         chgrp invocation.    (line   6)
+* group, permissions for:                Setting Permissions. (line  25)
+* groups:                                groups invocation.   (line   6)
+* growing files:                         tail invocation.     (line  57)
+* hangups, immunity to:                  nohup invocation.    (line   6)
+* hard link check:                       File characteristic tests.
+                                                              (line  23)
+* hard link, defined:                    ln invocation.       (line  32)
+* hard links:                            dd invocation.       (line 338)
+* hard links to directories:             ln invocation.       (line  88)
+* hard links to symbolic links:          ln invocation.       (line 184)
+* hard links, counting in du:            du invocation.       (line 125)
+* hard links, creating:                  link invocation.     (line   6)
+* hard links, creating <1>:              ln invocation.       (line   6)
+* hard links, preserving:                cp invocation.       (line 109)
+* hardware class:                        uname invocation.    (line  42)
+* hardware flow control:                 Control.             (line  41)
+* hardware flow control <1>:             Control.             (line  44)
+* hardware platform:                     uname invocation.    (line  35)
+* hardware type:                         uname invocation.    (line  42)
+* hat notation for control characters:   Local.               (line  51)
+* head:                                  head invocation.     (line   6)
+* head of output:                        shuf invocation.     (line  31)
+* headers, numbering:                    nl invocation.       (line  17)
+* help, online:                          Common options.      (line  36)
+* hex dump of files:                     od invocation.       (line   6)
+* holes, copying files with:             cp invocation.       (line 306)
+* holes, creating files with:            truncate invocation. (line  13)
+* horizontal, listing files:             General output formatting.
+                                                              (line 125)
+* host processor type:                   uname invocation.    (line  51)
+* hostid:                                hostid invocation.   (line   6)
+* hostname:                              hostname invocation. (line   6)
+* hostname <1>:                          uname invocation.    (line  47)
+* hour in date strings:                  Relative items in date strings.
+                                                              (line  15)
+* human numeric sort:                    sort invocation.     (line 132)
+* human-readable output:                 Block size.          (line  42)
+* human-readable output <1>:             What information is listed.
+                                                              (line 118)
+* human-readable output <2>:             df invocation.       (line  59)
+* human-readable output <3>:             du invocation.       (line  98)
+* hup[cl]:                               Control.             (line  28)
+* hurd, author, printing:                What information is listed.
+                                                              (line  10)
+* hyperlink, linking to files:           General output formatting.
+                                                              (line  73)
+* ibs:                                   dd invocation.       (line  52)
+* icanon:                                Local.               (line  11)
+* icrnl:                                 Input.               (line  34)
+* id:                                    id invocation.       (line   6)
+* idle time:                             who invocation.      (line  85)
+* IEEE floating point:                   Floating point.      (line   6)
+* iexten:                                Local.               (line  15)
+* if:                                    dd invocation.       (line  45)
+* iflag:                                 dd invocation.       (line 243)
+* ignbrk:                                Input.               (line   9)
+* igncr:                                 Input.               (line  31)
+* ignore file systems:                   df invocation.       (line  42)
+* Ignore garbage in base64 stream:       base64 invocation.   (line  39)
+* ignoring case:                         sort invocation.     (line  94)
+* ignpar:                                Input.               (line  15)
+* imaxbel:                               Input.               (line  59)
+* immunity to hangups:                   nohup invocation.    (line   6)
+* implementation, hardware:              uname invocation.    (line  35)
+* indenting lines:                       pr invocation.       (line 180)
+* index:                                 String expressions.  (line  43)
+* information, about current users:      who invocation.      (line   6)
+* initial part of files, outputting:     head invocation.     (line   6)
+* initial tabs, converting:              expand invocation.   (line  46)
+* inlcr:                                 Input.               (line  28)
+* inode number, printing:                What information is listed.
+                                                              (line 125)
+* inode usage:                           df invocation.       (line  69)
+* inode usage, dereferencing in du:      du invocation.       (line 104)
+* inode, and hard links:                 ln invocation.       (line  32)
+* inodes, written buffered:              sync invocation.     (line  11)
+* inpck:                                 Input.               (line  22)
+* input block size:                      dd invocation.       (line  52)
+* input encoding, UTF-8:                 Input.               (line  37)
+* input range to shuffle:                shuf invocation.     (line  23)
+* input settings:                        Input.               (line   6)
+* input tabs:                            pr invocation.       (line  98)
+* install:                               install invocation.  (line   6)
+* intr:                                  Characters.          (line  18)
+* invocation of commands, modified:      Modified command invocation.
+                                                              (line   6)
+* iseek:                                 dd invocation.       (line  73)
+* isig:                                  Local.               (line   7)
+* ISO 8601 date and time of day format:  Combined date and time of day items.
+                                                              (line   6)
+* ISO 8601 date format:                  Calendar date items. (line  28)
+* ISO/IEC 10646:                         printf invocation.   (line  74)
+* ISO9660 file system type:              df invocation.       (line 216)
+* iso9660 file system type:              df invocation.       (line 216)
+* ispeed:                                Special.             (line  16)
+* istrip:                                Input.               (line  25)
+* items in date strings:                 General date syntax. (line   6)
+* iterations, selecting the number of:   shred invocation.    (line 127)
+* iuclc:                                 Input.               (line  50)
+* iutf8:                                 Input.               (line  37)
+* ixany:                                 Input.               (line  55)
+* ixoff:                                 Input.               (line  45)
+* ixon:                                  Input.               (line  40)
+* join:                                  join invocation.     (line   6)
+* kernel name:                           uname invocation.    (line  66)
+* kernel release:                        uname invocation.    (line  62)
+* kernel version:                        uname invocation.    (line  77)
+* kibibyte, definition of:               Block size.          (line  82)
+* kibibytes for file sizes:              du invocation.       (line 113)
+* kibibytes for file system sizes:       df invocation.       (line  75)
+* kill:                                  kill invocation.     (line   6)
+* kill <1>:                              Characters.          (line  27)
+* kilobyte, definition of:               Block size.          (line  78)
+* Knuth, Donald E.:                      fmt invocation.      (line  19)
+* language, in dates:                    General date syntax. (line  36)
+* language, in dates <1>:                General date syntax. (line  40)
+* last DAY:                              Day of week items.   (line  15)
+* last DAY <1>:                          Options for date.    (line  15)
+* last in date strings:                  General date syntax. (line  22)
+* last modified dates, displaying in du: du invocation.       (line 195)
+* last part of files, outputting:        tail invocation.     (line   6)
+* lcase:                                 Combination.         (line  71)
+* LCASE:                                 Combination.         (line  71)
+* lcase, converting to:                  dd invocation.       (line 172)
+* lchown:                                chown invocation.    (line 107)
+* lchown <1>:                            chown invocation.    (line 119)
+* lchown <2>:                            chgrp invocation.    (line  34)
+* lchown <3>:                            chgrp invocation.    (line  46)
+* LC_ALL:                                sort invocation.     (line  23)
+* LC_ALL <1>:                            ls invocation.       (line  17)
+* LC_COLLATE:                            sort invocation.     (line  23)
+* LC_COLLATE <1>:                        uniq invocation.     (line  21)
+* LC_COLLATE <2>:                        comm invocation.     (line  12)
+* LC_COLLATE <3>:                        Sorting files for join.
+                                                              (line  16)
+* LC_COLLATE <4>:                        Relations for expr.  (line  22)
+* LC_CTYPE:                              sort invocation.     (line  79)
+* LC_CTYPE <1>:                          sort invocation.     (line  87)
+* LC_CTYPE <2>:                          sort invocation.     (line  94)
+* LC_CTYPE <3>:                          sort invocation.     (line 149)
+* LC_CTYPE <4>:                          printf invocation.   (line  74)
+* LC_MESSAGES:                           pr invocation.       (line  13)
+* LC_NUMERIC:                            Block size.          (line  57)
+* LC_NUMERIC <1>:                        Floating point.      (line  29)
+* LC_NUMERIC <2>:                        sort invocation.     (line 105)
+* LC_NUMERIC <3>:                        sort invocation.     (line 132)
+* LC_NUMERIC <4>:                        sort invocation.     (line 166)
+* LC_NUMERIC <5>:                        printf invocation.   (line  61)
+* LC_TIME:                               pr invocation.       (line  85)
+* LC_TIME <1>:                           sort invocation.     (line 156)
+* LC_TIME <2>:                           Formatting file timestamps.
+                                                              (line  28)
+* LC_TIME <3>:                           Formatting file timestamps.
+                                                              (line  73)
+* LC_TIME <4>:                           Formatting file timestamps.
+                                                              (line  97)
+* LC_TIME <5>:                           du invocation.       (line 217)
+* LC_TIME <6>:                           date invocation.     (line  15)
+* leading directories, creating missing: install invocation.  (line  67)
+* leading directory components, stripping: basename invocation.
+                                                              (line   6)
+* leap seconds:                          touch invocation.    (line  99)
+* leap seconds <1>:                      Time conversion specifiers.
+                                                              (line  32)
+* leap seconds <2>:                      Time conversion specifiers.
+                                                              (line  36)
+* leap seconds <3>:                      Options for date.    (line 135)
+* leap seconds <4>:                      Examples of date.    (line 104)
+* leap seconds <5>:                      General date syntax. (line  65)
+* leap seconds <6>:                      Time of day items.   (line  14)
+* leap seconds <7>:                      Seconds since the Epoch.
+                                                              (line  27)
+* left margin:                           pr invocation.       (line 180)
+* length:                                String expressions.  (line  48)
+* limiting output of du:                 du invocation.       (line  76)
+* line:                                  Special.             (line  48)
+* line buffered:                         stdbuf invocation.   (line   6)
+* line count:                            wc invocation.       (line   6)
+* line numbering:                        nl invocation.       (line   6)
+* line separator character:              split invocation.    (line 152)
+* line settings of terminal:             stty invocation.     (line   6)
+* line-breaking:                         fmt invocation.      (line  19)
+* line-by-line comparison:               comm invocation.     (line   6)
+* LINES:                                 Special.             (line  41)
+* link:                                  link invocation.     (line   6)
+* links, creating:                       link invocation.     (line   6)
+* links, creating <1>:                   ln invocation.       (line   6)
+* Linux file system types:               df invocation.       (line 212)
+* literal conversion specifiers:         Literal conversion specifiers.
+                                                              (line   6)
+* litout:                                Combination.         (line  59)
+* ln:                                    ln invocation.       (line   6)
+* ln format for nl:                      nl invocation.       (line  96)
+* lnext:                                 Characters.          (line  67)
+* local file system types:               df invocation.       (line 212)
+* local settings:                        Local.               (line   6)
+* logging out and continuing to run:     nohup invocation.    (line   6)
+* logical and operator:                  Connectives for test.
+                                                              (line  29)
+* logical and operator <1>:              Relations for expr.  (line  17)
+* logical connectives:                   Connectives for test.
+                                                              (line   6)
+* logical connectives <1>:               Relations for expr.  (line   6)
+* logical or operator:                   Connectives for test.
+                                                              (line  33)
+* logical or operator <1>:               Relations for expr.  (line  11)
+* logical pages, numbering on:           nl invocation.       (line  12)
+* login name, printing:                  logname invocation.  (line   6)
+* login sessions, printing users with:   users invocation.    (line   6)
+* login time:                            who invocation.      (line  11)
+* logname:                               logname invocation.  (line   6)
+* long ls format:                        What information is listed.
+                                                              (line 133)
+* lower:                                 Character arrays.    (line 120)
+* lowercase, translating to output:      Output.              (line  12)
+* ls:                                    ls invocation.       (line   6)
+* LS_BLOCK_SIZE:                         Block size.          (line  12)
+* LS_COLORS:                             General output formatting.
+                                                              (line  37)
+* LS_COLORS <1>:                         dircolors invocation.
+                                                              (line  23)
+* lutimes:                               touch invocation.    (line  70)
+* machine type:                          uname invocation.    (line  42)
+* machine-readable stty output:          stty invocation.     (line  41)
+* MacKenzie, D.:                         Introduction.        (line  29)
+* MacKenzie, David:                      Authors of parse_datetime.
+                                                              (line   6)
+* Makefiles, installing programs in:     install invocation.  (line  29)
+* manipulating files:                    Basic operations.    (line   6)
+* manipulation of file names:            File name manipulation.
+                                                              (line   6)
+* mark parity:                           Control.             (line  16)
+* match:                                 String expressions.  (line  34)
+* matching patterns:                     String expressions.  (line  11)
+* MD5:                                   md5sum invocation.   (line   6)
+* md5sum:                                md5sum invocation.   (line   6)
+* mebibyte, definition of:               Block size.          (line  89)
+* mebibytes for file sizes:              du invocation.       (line 129)
+* megabyte, definition of:               Block size.          (line  86)
+* merging files:                         paste invocation.    (line   6)
+* merging files in parallel:             pr invocation.       (line   6)
+* merging sorted files:                  sort invocation.     (line  53)
+* message status:                        who invocation.      (line  94)
+* message-digest, 128-bit:               md5sum invocation.   (line   6)
+* message-digest, 160-bit:               sha1sum invocation.  (line   6)
+* message-digest, 224-bit:               sha2 utilities.      (line   6)
+* message-digest, 256-bit:               sha2 utilities.      (line   6)
+* message-digest, 384-bit:               sha2 utilities.      (line   6)
+* message-digest, 512-bit:               b2sum invocation.    (line   6)
+* message-digest, 512-bit <1>:           sha2 utilities.      (line   6)
+* Meyering, J.:                          Introduction.        (line  29)
+* Meyering, Jim:                         Authors of parse_datetime.
+                                                              (line   6)
+* midnight in date strings:              Time of day items.   (line  21)
+* min:                                   Special.             (line   7)
+* minute in date strings:                Relative items in date strings.
+                                                              (line  15)
+* minutes, time zone correction by:      Time of day items.   (line  29)
+* mkdir:                                 mkdir invocation.    (line   6)
+* mkfifo:                                mkfifo invocation.   (line   6)
+* mknod:                                 mknod invocation.    (line   6)
+* mktemp:                                mktemp invocation.   (line   6)
+* modem control:                         Control.             (line  38)
+* modes and umask:                       Umask and Protection.
+                                                              (line   6)
+* modes of created directories, setting: mkdir invocation.    (line  19)
+* modes of created FIFOs, setting:       mkfifo invocation.   (line  21)
+* modification timestamp, sorting files by: Sorting the output.
+                                                              (line  36)
+* modified command invocation:           Modified command invocation.
+                                                              (line   6)
+* modified environment, running a program in a: env invocation.
+                                                              (line   6)
+* modify time, changing:                 touch invocation.    (line  85)
+* month in date strings:                 Relative items in date strings.
+                                                              (line  15)
+* month names in date strings:           Calendar date items. (line  36)
+* months, sorting by:                    sort invocation.     (line 156)
+* months, written-out:                   General date syntax. (line  32)
+* MS-DOS file system:                    df invocation.       (line 220)
+* MS-Windows file system:                df invocation.       (line 220)
+* mtime:                                 File timestamps.     (line   6)
+* mtime, changing:                       touch invocation.    (line  85)
+* mtime, printing or sorting files by:   Sorting the output.  (line  50)
+* mtime-greater-atime file check:        File characteristic tests.
+                                                              (line  27)
+* multicall:                             Multi-call invocation.
+                                                              (line   6)
+* multicolumn output, generating:        pr invocation.       (line   6)
+* multiple changes to permissions:       Multiple Changes.    (line   6)
+* multiplication:                        Numeric expressions. (line  16)
+* multipliers after numbers:             dd invocation.       (line 369)
+* multithreaded sort:                    sort invocation.     (line 366)
+* mv:                                    mv invocation.       (line   6)
+* name follow option:                    tail invocation.     (line  57)
+* name of kernel:                        uname invocation.    (line  66)
+* named pipe check:                      File type tests.     (line  28)
+* named pipes, creating:                 mkfifo invocation.   (line   6)
+* network node name:                     uname invocation.    (line  47)
+* networked file systems and du:         du invocation.       (line 282)
+* never interactive option:              rm invocation.       (line  57)
+* newer files, copying only:             cp invocation.       (line 372)
+* newer files, moving only:              mv invocation.       (line  91)
+* newer-than file check:                 File characteristic tests.
+                                                              (line  15)
+* newline echoing after kill:            Local.               (line  26)
+* newline, echoing:                      Local.               (line  29)
+* newline, translating to crlf:          Output.              (line  19)
+* newline, translating to return:        Input.               (line  28)
+* next DAY:                              Day of week items.   (line  15)
+* next DAY <1>:                          Options for date.    (line  15)
+* next in date strings:                  General date syntax. (line  22)
+* NFS file system type:                  df invocation.       (line 207)
+* NFS mounts from BSD to HP-UX:          What information is listed.
+                                                              (line 244)
+* nice:                                  nice invocation.     (line   6)
+* niceness:                              nice invocation.     (line   6)
+* nl:                                    nl invocation.       (line   6)
+* nl <1>:                                Combination.         (line  18)
+* nlN:                                   Output.              (line  39)
+* no dereference:                        chcon invocation.    (line  26)
+* no-op:                                 true invocation.     (line   6)
+* noatime:                               dd invocation.       (line 324)
+* nocache:                               dd invocation.       (line 292)
+* nocreat:                               dd invocation.       (line 210)
+* noctty:                                dd invocation.       (line 330)
+* node name:                             uname invocation.    (line  47)
+* noerror:                               dd invocation.       (line 220)
+* noflsh:                                Local.               (line  32)
+* nofollow:                              dd invocation.       (line 335)
+* nohup:                                 nohup invocation.    (line   6)
+* nohup.out:                             nohup invocation.    (line   6)
+* nohup.out <1>:                         nohup invocation.    (line  20)
+* nolinks:                               dd invocation.       (line 338)
+* non-directories, copying as special files: cp invocation.   (line  96)
+* non-directories, copying as special files <1>: cp invocation.
+                                                              (line 262)
+* non-directory suffix, stripping:       dirname invocation.  (line   6)
+* nonblock:                              dd invocation.       (line 321)
+* nonblocking I/O:                       dd invocation.       (line 321)
+* nonblocking stty setting:              Special.             (line  30)
+* none backup method:                    Backup options.      (line  31)
+* none classify option:                  General output formatting.
+                                                              (line  57)
+* none color option:                     General output formatting.
+                                                              (line  30)
+* none dd status=:                       dd invocation.       (line 101)
+* none hyperlink option:                 General output formatting.
+                                                              (line  75)
+* none total option:                     wc invocation.       (line  81)
+* none, sorting option for ls:           Sorting the output.  (line  64)
+* nonempty file check:                   File characteristic tests.
+                                                              (line  12)
+* nonprinting characters, ignoring:      sort invocation.     (line 149)
+* nonzero-length string check:           String tests.        (line  19)
+* noon in date strings:                  Time of day items.   (line  21)
+* not-equal string check:                String tests.        (line  29)
+* notrunc:                               dd invocation.       (line 217)
+* now in date strings:                   Relative items in date strings.
+                                                              (line  33)
+* noxfer dd status=:                     dd invocation.       (line 105)
+* NO_NEW_PRIVS:                          runcon invocation.   (line  22)
+* nproc:                                 nproc invocation.    (line   6)
+* NTFS file system:                      df invocation.       (line 220)
+* ntfs file system file:                 df invocation.       (line 220)
+* number of inputs to merge, nmerge:     sort invocation.     (line 268)
+* numbered backup method:                Backup options.      (line  35)
+* numbering lines:                       nl invocation.       (line   6)
+* numbers, written-out:                  General date syntax. (line  22)
+* numeric expressions:                   Numeric expressions. (line   6)
+* numeric field padding:                 Padding and other flags.
+                                                              (line   6)
+* numeric modes:                         Numeric Modes.       (line   6)
+* numeric operations:                    Numeric operations.  (line   6)
+* numeric sequences:                     seq invocation.      (line   6)
+* numeric sort:                          sort invocation.     (line 166)
+* numeric tests:                         Numeric tests.       (line   6)
+* numeric uid and gid:                   What information is listed.
+                                                              (line 227)
+* numeric user and group IDs:            What information is listed.
+                                                              (line 227)
+* numfmt:                                numfmt invocation.   (line   6)
+* obs:                                   dd invocation.       (line  56)
+* ocrnl:                                 Output.              (line  16)
+* octal dump of files:                   od invocation.       (line   6)
+* octal numbers for file modes:          Numeric Modes.       (line   6)
+* od:                                    od invocation.       (line   6)
+* odd parity:                            Control.             (line  13)
+* oddp:                                  Combination.         (line  14)
+* of:                                    dd invocation.       (line  48)
+* ofdel:                                 Output.              (line  34)
+* ofill:                                 Output.              (line  30)
+* oflag:                                 dd invocation.       (line 247)
+* olcuc:                                 Output.              (line  12)
+* older-than file check:                 File characteristic tests.
+                                                              (line  19)
+* once interactive option:               rm invocation.       (line  58)
+* one file system, restricting du to:    du invocation.       (line 261)
+* one file system, restricting rm to:    rm invocation.       (line  66)
+* one-line output format:                df invocation.       (line 149)
+* onlcr:                                 Output.              (line  19)
+* onlret:                                Output.              (line  27)
+* only total option:                     wc invocation.       (line  78)
+* onocr:                                 Output.              (line  23)
+* operating on characters:               Operating on characters.
+                                                              (line   6)
+* operating on sorted files:             Operating on sorted files.
+                                                              (line   6)
+* operating system name:                 uname invocation.    (line  58)
+* opost:                                 Output.              (line   9)
+* option delimiter:                      Common options.      (line  43)
+* options for date:                      Options for date.    (line   6)
+* or operator:                           Connectives for test.
+                                                              (line  33)
+* or operator <1>:                       Relations for expr.  (line  11)
+* ordinal numbers:                       General date syntax. (line  22)
+* oseek:                                 dd invocation.       (line  80)
+* ospeed:                                Special.             (line  19)
+* other permissions:                     Setting Permissions. (line  27)
+* output block size:                     dd invocation.       (line  56)
+* output file name prefix:               split invocation.    (line  15)
+* output file name prefix <1>:           csplit invocation.   (line  64)
+* output file name suffix:               csplit invocation.   (line  68)
+* output format:                         stat invocation.     (line  50)
+* output format <1>:                     stat invocation.     (line  59)
+* output format, portable:               df invocation.       (line 149)
+* output NUL-byte-terminated lines:      cksum common options.
+                                                              (line 109)
+* output NUL-byte-terminated lines <1>:  General output formatting.
+                                                              (line 157)
+* output NUL-byte-terminated lines <2>:  readlink invocation. (line  65)
+* output NUL-byte-terminated lines <3>:  du invocation.       (line  25)
+* output NUL-byte-terminated lines <4>:  basename invocation. (line  42)
+* output NUL-byte-terminated lines <5>:  dirname invocation.  (line  31)
+* output NUL-byte-terminated lines <6>:  realpath invocation. (line  71)
+* output NUL-byte-terminated lines <7>:  printenv invocation. (line  19)
+* output NUL-byte-terminated lines <8>:  env invocation.      (line  90)
+* output of entire files:                Output of entire files.
+                                                              (line   6)
+* output of parts of files:              Output of parts of files.
+                                                              (line   6)
+* output settings:                       Output.              (line   6)
+* output tabs:                           pr invocation.       (line 117)
+* overwriting of input, allowed:         sort invocation.     (line 294)
+* overwriting of input, allowed <1>:     shuf invocation.     (line  36)
+* owned by effective group ID check:     Access permission tests.
+                                                              (line  31)
+* owned by effective user ID check:      Access permission tests.
+                                                              (line  28)
+* owner of file, permissions for:        Setting Permissions. (line  23)
+* owner, default:                        Mode Structure.      (line  27)
+* ownership of installed files, setting: install invocation.  (line  95)
+* p for FIFO file:                       mknod invocation.    (line  28)
+* pad character:                         Output.              (line  34)
+* pad instead of timing for delaying:    Output.              (line  30)
+* padding of numeric fields:             Padding and other flags.
+                                                              (line   6)
+* paragraphs, reformatting:              fmt invocation.      (line   6)
+* parenb:                                Control.             (line   9)
+* parent directories and cp:             cp invocation.       (line 249)
+* parent directories, creating:          mkdir invocation.    (line  36)
+* parent directories, creating missing:  install invocation.  (line  67)
+* parent directories, removing:          rmdir invocation.    (line  21)
+* parentheses for grouping:              expr invocation.     (line  31)
+* parity:                                Combination.         (line  10)
+* parity errors, marking:                Input.               (line  18)
+* parity, ignoring:                      Input.               (line  15)
+* parmrk:                                Input.               (line  18)
+* parodd:                                Control.             (line  13)
+* parse_datetime:                        Date input formats.  (line   6)
+* parsing date strings:                  Options for date.    (line  15)
+* parts of files, output of:             Output of parts of files.
+                                                              (line   6)
+* pass8:                                 Combination.         (line  55)
+* paste:                                 paste invocation.    (line   6)
+* Paterson, R.:                          Introduction.        (line  29)
+* PATH:                                  env invocation.      (line  28)
+* pathchk:                               pathchk invocation.  (line   6)
+* pattern matching:                      String expressions.  (line  11)
+* pebibyte, definition of:               Block size.          (line 104)
+* permission tests:                      Access permission tests.
+                                                              (line   6)
+* permissions of installed files, setting: install invocation.
+                                                              (line  83)
+* permissions, changing access:          chmod invocation.    (line   6)
+* permissions, copying existing:         Copying Permissions. (line   6)
+* permissions, for changing file timestamps: touch invocation.
+                                                              (line  21)
+* permissions, output by ls:             What information is listed.
+                                                              (line 184)
+* petabyte, definition of:               Block size.          (line 101)
+* phone directory order:                 sort invocation.     (line  87)
+* pieces, splitting a file into:         split invocation.    (line   6)
+* Pinard, F.:                            Introduction.        (line  29)
+* Pinard, F. <1>:                        Authors of parse_datetime.
+                                                              (line  19)
+* pipe fitting:                          tee invocation.      (line   6)
+* Plass, Michael F.:                     fmt invocation.      (line  19)
+* platform, hardware:                    uname invocation.    (line  35)
+* pm in date strings:                    Time of day items.   (line  21)
+* portable file names, checking for:     pathchk invocation.  (line   6)
+* portable output format:                df invocation.       (line 149)
+* POSIX:                                 Introduction.        (line  11)
+* POSIX output format:                   df invocation.       (line 149)
+* POSIXLY_CORRECT:                       Common options.      (line  11)
+* POSIXLY_CORRECT <1>:                   Standards conformance.
+                                                              (line   6)
+* POSIXLY_CORRECT <2>:                   pr invocation.       (line  85)
+* POSIXLY_CORRECT <3>:                   sort invocation.     (line 305)
+* POSIXLY_CORRECT <4>:                   sort invocation.     (line 421)
+* POSIXLY_CORRECT <5>:                   dd invocation.       (line 441)
+* POSIXLY_CORRECT <6>:                   echo invocation.     (line  72)
+* POSIXLY_CORRECT <7>:                   printf invocation.   (line  53)
+* POSIXLY_CORRECT <8>:                   id invocation.       (line  15)
+* POSIXLY_CORRECT, and block size:       Block size.          (line  12)
+* pr:                                    pr invocation.       (line   6)
+* prime factors:                         factor invocation.   (line   6)
+* print:                                 Character arrays.    (line 122)
+* print machine hardware name:           arch invocation.     (line   6)
+* print name of current directory:       pwd invocation.      (line   6)
+* print system information:              uname invocation.    (line   6)
+* print terminal file name:              tty invocation.      (line   6)
+* Print the number of processors:        nproc invocation.    (line   6)
+* printenv:                              printenv invocation. (line   6)
+* printf:                                printf invocation.   (line   6)
+* printing all or some environment variables: printenv invocation.
+                                                              (line   6)
+* printing color database:               dircolors invocation.
+                                                              (line  45)
+* printing current user information:     who invocation.      (line   6)
+* printing current usernames:            users invocation.    (line   6)
+* printing groups a user is in:          groups invocation.   (line   6)
+* printing ls colors:                    dircolors invocation.
+                                                              (line  50)
+* printing real and effective user and group IDs: id invocation.
+                                                              (line   6)
+* printing text:                         echo invocation.     (line   6)
+* printing text, commands for:           Printing text.       (line   6)
+* printing the current time:             date invocation.     (line   6)
+* printing the effective user ID:        whoami invocation.   (line   6)
+* printing the host identifier:          hostid invocation.   (line   6)
+* printing the hostname:                 hostname invocation. (line   6)
+* printing the system uptime and load:   uptime invocation.   (line   6)
+* printing user’s login name:            logname invocation.  (line   6)
+* printing, preparing files for:         pr invocation.       (line   6)
+* process zero-terminated items:         head invocation.     (line  55)
+* process zero-terminated items <1>:     tail invocation.     (line 190)
+* process zero-terminated items <2>:     sort invocation.     (line 389)
+* process zero-terminated items <3>:     shuf invocation.     (line  55)
+* process zero-terminated items <4>:     uniq invocation.     (line 140)
+* process zero-terminated items <5>:     comm invocation.     (line  89)
+* process zero-terminated items <6>:     cut invocation.      (line  94)
+* process zero-terminated items <7>:     paste invocation.    (line  72)
+* process zero-terminated items <8>:     General options in join.
+                                                              (line  93)
+* process zero-terminated items <9>:     numfmt invocation.   (line 115)
+* processes, commands for controlling:   Process control.     (line   6)
+* progress dd status=:                   dd invocation.       (line 109)
+* prompting, and ln:                     ln invocation.       (line  98)
+* prompting, and mv:                     mv invocation.       (line  34)
+* prompting, and rm:                     rm invocation.       (line  11)
+* prompts, forcing:                      mv invocation.       (line  71)
+* prompts, omitting:                     mv invocation.       (line  65)
+* prompts, omitting <1>:                 mv invocation.       (line  78)
+* prterase:                              Local.               (line  46)
+* ptx:                                   ptx invocation.      (line   6)
+* punct:                                 Character arrays.    (line 124)
+* pure numbers in date strings:          Pure numbers in date strings.
+                                                              (line   6)
+* pwd:                                   pwd invocation.      (line   6)
+* quettabyte, definition of:             Block size.          (line 126)
+* quit:                                  Characters.          (line  21)
+* quoting style:                         Formatting the file names.
+                                                              (line  34)
+* radix for file offsets:                od invocation.       (line  36)
+* random seed:                           Random sources.      (line  31)
+* random sort:                           sort invocation.     (line 195)
+* random source for shredding:           shred invocation.    (line 133)
+* random source for shuffling:           shuf invocation.     (line  42)
+* random source for sorting:             sort invocation.     (line 310)
+* random sources:                        Random sources.      (line   6)
+* ranges:                                Character arrays.    (line  65)
+* raw:                                   Combination.         (line  43)
+* raw binary checksum:                   cksum general options.
+                                                              (line  45)
+* read errors, ignoring:                 dd invocation.       (line 220)
+* read from standard input and write to standard output and files: tee invocation.
+                                                              (line   6)
+* read permission:                       Mode Structure.      (line  12)
+* read permission, symbolic:             Setting Permissions. (line  52)
+* read system call, and holes:           cp invocation.       (line 306)
+* readable file check:                   Access permission tests.
+                                                              (line  15)
+* readlink:                              readlink invocation. (line   6)
+* real user and group IDs, printing:     id invocation.       (line   6)
+* realpath:                              realpath invocation. (line   6)
+* realpath <1>:                          realpath invocation. (line   6)
+* realpath <2>:                          realpath invocation. (line   6)
+* realpath <3>:                          readlink invocation. (line   6)
+* record separator character:            split invocation.    (line 152)
+* recursive directory listing:           Which files are listed.
+                                                              (line  91)
+* recursively changing access permissions: chmod invocation.  (line  73)
+* recursively changing file ownership:   chown invocation.    (line 151)
+* recursively changing group ownership:  chgrp invocation.    (line  77)
+* recursively copying directories:       cp invocation.       (line  96)
+* recursively copying directories <1>:   cp invocation.       (line 262)
+* redirection:                           Redirection.         (line   6)
+* reference file:                        chcon invocation.    (line  30)
+* reformatting paragraph text:           fmt invocation.      (line   6)
+* regular expression matching:           String expressions.  (line  11)
+* regular file check:                    File type tests.     (line  19)
+* relations, numeric or string:          Relations for expr.  (line   6)
+* relative items in date strings:        Relative items in date strings.
+                                                              (line   6)
+* release of kernel:                     uname invocation.    (line  62)
+* relpath:                               realpath invocation. (line  49)
+* remainder:                             Numeric expressions. (line  16)
+* remote hostname:                       who invocation.      (line  11)
+* removing characters:                   Squeezing and deleting.
+                                                              (line   6)
+* removing empty directories:            rmdir invocation.    (line   6)
+* removing files after shredding:        shred invocation.    (line 144)
+* removing files or directories:         rm invocation.       (line   6)
+* removing files or directories (via the unlink syscall): unlink invocation.
+                                                              (line   6)
+* removing permissions:                  Setting Permissions. (line  38)
+* renaming files without copying them:   mv invocation.       (line  85)
+* repeat output values:                  shuf invocation.     (line  47)
+* repeated characters:                   Character arrays.    (line  85)
+* repeated lines, outputting:            uniq invocation.     (line  64)
+* repeated output of a string:           yes invocation.      (line   6)
+* restricted deletion flag:              Mode Structure.      (line  52)
+* restricted security context:           runcon invocation.   (line  22)
+* return, ignoring:                      Input.               (line  31)
+* return, translating to newline:        Input.               (line  34)
+* return, translating to newline <1>:    Output.              (line  16)
+* reverse sorting:                       sort invocation.     (line 189)
+* reverse sorting <1>:                   Sorting the output.  (line  25)
+* reversing files:                       tac invocation.      (line   6)
+* rm:                                    rm invocation.       (line   6)
+* rmdir:                                 rmdir invocation.    (line   6)
+* rn format for nl:                      nl invocation.       (line  98)
+* ronnabyte, definition of:              Block size.          (line 121)
+* root as default owner:                 install invocation.  (line  95)
+* root directory, allow recursive destruction: rm invocation. (line  89)
+* root directory, allow recursive modification: chown invocation.
+                                                              (line 132)
+* root directory, allow recursive modification <1>: chgrp invocation.
+                                                              (line  59)
+* root directory, allow recursive modification <2>: chmod invocation.
+                                                              (line  58)
+* root directory, disallow recursive destruction: rm invocation.
+                                                              (line  82)
+* root directory, disallow recursive modification: chown invocation.
+                                                              (line 127)
+* root directory, disallow recursive modification <1>: chgrp invocation.
+                                                              (line  54)
+* root directory, disallow recursive modification <2>: chmod invocation.
+                                                              (line  53)
+* root directory, running a program in a specified: chroot invocation.
+                                                              (line   6)
+* rows:                                  Special.             (line  22)
+* rprnt:                                 Characters.          (line  61)
+* RTS/CTS flow control:                  Control.             (line  41)
+* run commands with bounded time:        timeout invocation.  (line   6)
+* run with security context:             runcon invocation.   (line   6)
+* runcon:                                runcon invocation.   (line   6)
+* running a program in a modified environment: env invocation.
+                                                              (line   6)
+* running a program in a specified root directory: chroot invocation.
+                                                              (line   6)
+* rz format for nl:                      nl invocation.       (line 100)
+* Salz, Rich:                            Authors of parse_datetime.
+                                                              (line   6)
+* same file check:                       File characteristic tests.
+                                                              (line  23)
+* sane:                                  Combination.         (line  26)
+* scheduling, affecting:                 nice invocation.     (line   6)
+* screen columns:                        fold invocation.     (line  14)
+* scripts arguments:                     env invocation.      (line 192)
+* seconds since the Epoch:               Time conversion specifiers.
+                                                              (line  32)
+* section delimiters of pages:           nl invocation.       (line  63)
+* security context:                      What information is listed.
+                                                              (line 259)
+* security context <1>:                  cp invocation.       (line 417)
+* security context <2>:                  install invocation.  (line 100)
+* security context <3>:                  install invocation.  (line 143)
+* security context <4>:                  mv invocation.       (line 144)
+* security context <5>:                  mkdir invocation.    (line  59)
+* security context <6>:                  mkfifo invocation.   (line  28)
+* security context <7>:                  mknod invocation.    (line  53)
+* security context <8>:                  id invocation.       (line  51)
+* seek:                                  dd invocation.       (line  80)
+* self-backups:                          cp invocation.       (line  51)
+* SELinux:                               What information is listed.
+                                                              (line 259)
+* SELinux <1>:                           install invocation.  (line 100)
+* SELinux <2>:                           id invocation.       (line  51)
+* SELinux context:                       SELinux context.     (line   6)
+* SELinux, context:                      SELinux context.     (line   6)
+* SELinux, restoring security context:   mv invocation.       (line 144)
+* SELinux, setting/restoring security context: cp invocation. (line 417)
+* SELinux, setting/restoring security context <1>: install invocation.
+                                                              (line 143)
+* SELinux, setting/restoring security context <2>: mkdir invocation.
+                                                              (line  59)
+* SELinux, setting/restoring security context <3>: mkfifo invocation.
+                                                              (line  28)
+* SELinux, setting/restoring security context <4>: mknod invocation.
+                                                              (line  53)
+* send a signal to processes:            kill invocation.     (line   6)
+* sentences and line-breaking:           fmt invocation.      (line  19)
+* separator for numbers in seq:          seq invocation.      (line  45)
+* seq:                                   seq invocation.      (line   6)
+* sequence of numbers:                   seq invocation.      (line   6)
+* set-group-ID:                          Mode Structure.      (line  45)
+* set-group-ID check:                    Access permission tests.
+                                                              (line   9)
+* set-user-ID:                           Mode Structure.      (line  39)
+* set-user-ID check:                     Access permission tests.
+                                                              (line  18)
+* setgid:                                Mode Structure.      (line  45)
+* setting permissions:                   Setting Permissions. (line  41)
+* setting the hostname:                  hostname invocation. (line   6)
+* setting the time:                      Setting the time.    (line   6)
+* setuid:                                Mode Structure.      (line  39)
+* setup for color:                       dircolors invocation.
+                                                              (line   6)
+* sh syntax for color setup:             dircolors invocation.
+                                                              (line  34)
+* SHA-1:                                 sha1sum invocation.  (line   6)
+* SHA-2:                                 sha2 utilities.      (line   6)
+* sha1sum:                               sha1sum invocation.  (line   6)
+* sha224sum:                             sha2 utilities.      (line   6)
+* sha256sum:                             sha2 utilities.      (line   6)
+* sha384sum:                             sha2 utilities.      (line   6)
+* sha512sum:                             sha2 utilities.      (line   6)
+* shebang arguments:                     env invocation.      (line 192)
+* SHELL environment variable, and color: General output formatting.
+                                                              (line  37)
+* SHELL environment variable, and color <1>: dircolors invocation.
+                                                              (line  23)
+* shell utilities:                       Top.                 (line  18)
+* shred:                                 shred invocation.    (line   6)
+* shuf:                                  shuf invocation.     (line   6)
+* shuffling files:                       shuf invocation.     (line   6)
+* SI output:                             Block size.          (line  42)
+* SI output <1>:                         What information is listed.
+                                                              (line 251)
+* SI output <2>:                         df invocation.       (line 168)
+* SI output <3>:                         du invocation.       (line 147)
+* signals, specifying:                   Signal specifications.
+                                                              (line   6)
+* simple backup method:                  Backup options.      (line  44)
+* SIMPLE_BACKUP_SUFFIX:                  Backup options.      (line  49)
+* single quotes, and env -S:             env invocation.      (line 268)
+* single-column output of files:         General output formatting.
+                                                              (line   9)
+* size:                                  Special.             (line  41)
+* size for main memory sorting:          sort invocation.     (line 322)
+* size of file to shred:                 shred invocation.    (line 138)
+* size of files, reporting:              What information is listed.
+                                                              (line 236)
+* size of files, sorting files by:       Sorting the output.  (line  32)
+* skip:                                  dd invocation.       (line  73)
+* sleep:                                 sleep invocation.    (line   6)
+* socket check:                          File type tests.     (line  31)
+* software flow control:                 Input.               (line  45)
+* sort:                                  sort invocation.     (line   6)
+* sort field:                            sort invocation.     (line 237)
+* sort stability:                        sort invocation.     (line  12)
+* sort stability <1>:                    sort invocation.     (line 315)
+* sort’s last-resort comparison:         sort invocation.     (line  12)
+* sort’s last-resort comparison <1>:     sort invocation.     (line 315)
+* sorted files, operations on:           Operating on sorted files.
+                                                              (line   6)
+* sorting files:                         sort invocation.     (line   6)
+* sorting ls output:                     Sorting the output.  (line   6)
+* space:                                 Character arrays.    (line 126)
+* space parity:                          Control.             (line  16)
+* sparse:                                dd invocation.       (line 180)
+* sparse files, copying:                 cp invocation.       (line 306)
+* sparse files, creating:                truncate invocation. (line  13)
+* special characters:                    Characters.          (line   6)
+* special file types:                    Special file types.  (line   6)
+* special file types <1>:                Special file types.  (line   9)
+* special files:                         mknod invocation.    (line  11)
+* special settings:                      Special.             (line   6)
+* speed:                                 Special.             (line  51)
+* split:                                 split invocation.    (line   6)
+* splitting a file into pieces:          split invocation.    (line   6)
+* splitting a file into pieces by context: csplit invocation. (line   6)
+* squeezing blank lines:                 cat invocation.      (line  37)
+* squeezing empty lines:                 cat invocation.      (line  37)
+* squeezing repeat characters:           Squeezing and deleting.
+                                                              (line   6)
+* Stallman, R.:                          Introduction.        (line  29)
+* standard input:                        Common options.      (line  47)
+* standard output:                       Common options.      (line  47)
+* standard streams, buffering:           stdbuf invocation.   (line   6)
+* start:                                 Characters.          (line  49)
+* stat:                                  stat invocation.     (line   6)
+* status:                                dd invocation.       (line  96)
+* status <1>:                            Characters.          (line  45)
+* status time, printing or sorting by:   Sorting the output.  (line  13)
+* status time, show the most recent:     du invocation.       (line 202)
+* stdbuf:                                stdbuf invocation.   (line   6)
+* stick parity:                          Control.             (line  16)
+* sticky:                                Mode Structure.      (line  52)
+* sticky bit check:                      Access permission tests.
+                                                              (line  12)
+* stop:                                  Characters.          (line  52)
+* stop bits:                             Control.             (line  32)
+* storage devices, failing:              dd invocation.       (line 397)
+* strftime and date:                     Date format specifiers.
+                                                              (line   6)
+* string constants, outputting:          od invocation.       (line  81)
+* string expressions:                    String expressions.  (line   6)
+* string tests:                          String tests.        (line   6)
+* strip directory and suffix from file names: basename invocation.
+                                                              (line   6)
+* stripping non-directory suffix:        dirname invocation.  (line   6)
+* stripping symbol table information:    install invocation.  (line 117)
+* stripping trailing slashes:            cp invocation.       (line 345)
+* stripping trailing slashes <1>:        mv invocation.       (line 125)
+* stty:                                  stty invocation.     (line   6)
+* substr:                                String expressions.  (line  38)
+* subtracting permissions:               Setting Permissions. (line  38)
+* subtraction:                           Numeric expressions. (line  12)
+* successful exit:                       true invocation.     (line   6)
+* suffix, stripping from file names:     basename invocation. (line   6)
+* sum:                                   sum invocation.      (line   6)
+* summarizing files:                     Summarizing files.   (line   6)
+* superblock, writing:                   sync invocation.     (line  11)
+* supplementary groups, printing:        groups invocation.   (line   6)
+* susp:                                  Characters.          (line  55)
+* swab (byte-swapping):                  dd invocation.       (line 195)
+* swap space, saving text image in:      Mode Structure.      (line  52)
+* swtch:                                 Characters.          (line  42)
+* symbol table information, stripping:   install invocation.  (line 117)
+* symbol table information, stripping, program: install invocation.
+                                                              (line 120)
+* symbolic (soft) links, creating:       ln invocation.       (line   6)
+* symbolic link check:                   File type tests.     (line  23)
+* symbolic link to directory, controlling traversal of: Traversing symlinks.
+                                                              (line   6)
+* symbolic link to directory, never traverse: Traversing symlinks.
+                                                              (line  26)
+* symbolic link to directory, never traverse <1>: chown invocation.
+                                                              (line 172)
+* symbolic link to directory, never traverse <2>: chgrp invocation.
+                                                              (line  99)
+* symbolic link to directory, never traverse <3>: chcon invocation.
+                                                              (line  56)
+* symbolic link to directory, traverse each that is encountered: Traversing symlinks.
+                                                              (line  22)
+* symbolic link to directory, traverse each that is encountered <1>: chown invocation.
+                                                              (line 159)
+* symbolic link to directory, traverse each that is encountered <2>: chgrp invocation.
+                                                              (line  86)
+* symbolic link to directory, traverse each that is encountered <3>: chcon invocation.
+                                                              (line  52)
+* symbolic link to directory, traverse if on the command line: Traversing symlinks.
+                                                              (line  18)
+* symbolic link to directory, traverse if on the command line <1>: chown invocation.
+                                                              (line 154)
+* symbolic link to directory, traverse if on the command line <2>: chgrp invocation.
+                                                              (line  81)
+* symbolic link to directory, traverse if on the command line <3>: chcon invocation.
+                                                              (line  47)
+* symbolic link, defined:                ln invocation.       (line  42)
+* symbolic links and ln:                 ln invocation.       (line 184)
+* symbolic links and pwd:                pwd invocation.      (line  26)
+* symbolic links, changing group:        chgrp invocation.    (line  46)
+* symbolic links, changing owner:        chown invocation.    (line  84)
+* symbolic links, changing owner <1>:    chown invocation.    (line 107)
+* symbolic links, changing owner <2>:    chown invocation.    (line 119)
+* symbolic links, changing owner <3>:    chgrp invocation.    (line  34)
+* symbolic links, changing time:         touch invocation.    (line  70)
+* symbolic links, copying:               cp invocation.       (line 109)
+* symbolic links, copying <1>:           cp invocation.       (line 166)
+* symbolic links, copying with:          cp invocation.       (line 350)
+* symbolic links, dereferencing:         Which files are listed.
+                                                              (line  36)
+* symbolic links, dereferencing <1>:     Which files are listed.
+                                                              (line  41)
+* symbolic links, dereferencing <2>:     Which files are listed.
+                                                              (line  84)
+* symbolic links, dereferencing in du:   du invocation.       (line 119)
+* symbolic links, dereferencing in du <1>: du invocation.     (line 135)
+* symbolic links, dereferencing in stat: stat invocation.     (line  22)
+* symbolic links, following:             dd invocation.       (line 335)
+* symbolic links, permissions of:        chmod invocation.    (line  10)
+* symbolic modes:                        Symbolic Modes.      (line   6)
+* symlinks, resolution:                  realpath invocation. (line   6)
+* sync:                                  sync invocation.     (line   6)
+* sync <1>:                              dd invocation.       (line 289)
+* sync (padding with ASCII NULs):        dd invocation.       (line 198)
+* Synchronize cached writes to persistent storage: sync invocation.
+                                                              (line   6)
+* synchronize file system and memory:    sync invocation.     (line   6)
+* synchronized data and metadata I/O:    dd invocation.       (line 289)
+* synchronized data and metadata writes, before finishing: dd invocation.
+                                                              (line 234)
+* synchronized data reads:               dd invocation.       (line 281)
+* synchronized data writes, before finishing: dd invocation.  (line 223)
+* system context:                        System context.      (line   6)
+* system information, printing:          arch invocation.     (line   6)
+* system information, printing <1>:      nproc invocation.    (line   6)
+* system information, printing <2>:      uname invocation.    (line   6)
+* system name, printing:                 hostname invocation. (line   6)
+* System V sum:                          sum invocation.      (line  29)
+* tab stops, setting:                    expand invocation.   (line  22)
+* tabN:                                  Output.              (line  51)
+* tabs:                                  Combination.         (line  66)
+* tabs to spaces, converting:            expand invocation.   (line   6)
+* tac:                                   tac invocation.      (line   6)
+* tagged paragraphs:                     fmt invocation.      (line  40)
+* tail:                                  tail invocation.     (line   6)
+* tandem:                                Input.               (line  45)
+* target directory:                      Target directory.    (line   6)
+* target directory <1>:                  Target directory.    (line  15)
+* target directory <2>:                  Target directory.    (line  31)
+* target directory <3>:                  cp invocation.       (line 363)
+* target directory <4>:                  cp invocation.       (line 367)
+* target directory <5>:                  install invocation.  (line 129)
+* target directory <6>:                  install invocation.  (line 134)
+* target directory <7>:                  mv invocation.       (line 135)
+* target directory <8>:                  mv invocation.       (line 139)
+* target directory <9>:                  ln invocation.       (line 173)
+* target directory <10>:                 ln invocation.       (line 177)
+* tebibyte, definition of:               Block size.          (line  99)
+* tee:                                   tee invocation.      (line   6)
+* telephone directory order:             sort invocation.     (line  87)
+* temporary directory:                   sort invocation.     (line 358)
+* temporary files and directories:       mktemp invocation.   (line   6)
+* terabyte, definition of:               Block size.          (line  96)
+* terminal check:                        File type tests.     (line  34)
+* terminal file name, printing:          tty invocation.      (line   6)
+* terminal lines, currently used:        who invocation.      (line  11)
+* terminal settings:                     stty invocation.     (line   6)
+* terminal, using classify iff:          General output formatting.
+                                                              (line  58)
+* terminal, using color iff:             General output formatting.
+                                                              (line  31)
+* terminal, using hyperlink iff:         General output formatting.
+                                                              (line  76)
+* terse output:                          stat invocation.     (line  70)
+* test:                                  test invocation.     (line   6)
+* text:                                  dd invocation.       (line 345)
+* text I/O:                              dd invocation.       (line 345)
+* text image, saving in swap space:      Mode Structure.      (line  52)
+* text input files:                      cksum common options.
+                                                              (line  89)
+* text utilities:                        Top.                 (line  18)
+* text, displaying:                      echo invocation.     (line   6)
+* text, reformatting:                    fmt invocation.      (line   6)
+* this in date strings:                  Relative items in date strings.
+                                                              (line  33)
+* time:                                  touch invocation.    (line  56)
+* time <1>:                              Special.             (line  11)
+* time conversion specifiers:            Time conversion specifiers.
+                                                              (line   6)
+* time formats:                          pr invocation.       (line  78)
+* time formats <1>:                      Date format specifiers.
+                                                              (line   6)
+* time limit:                            timeout invocation.  (line   6)
+* time of day item:                      Time of day items.   (line   6)
+* time setting:                          Setting the time.    (line   6)
+* time style:                            Formatting file timestamps.
+                                                              (line  24)
+* time style <1>:                        du invocation.       (line 212)
+* time units:                            timeout invocation.  (line  66)
+* time units <1>:                        sleep invocation.    (line  11)
+* time zone correction:                  Time of day items.   (line  29)
+* time zone item:                        General date syntax. (line  40)
+* time zone item <1>:                    Time zone items.     (line   6)
+* time, printing or setting:             date invocation.     (line   6)
+* timeout:                               timeout invocation.  (line   6)
+* timestamps of installed files, preserving: install invocation.
+                                                              (line 107)
+* timestamps, changing file:             touch invocation.    (line   6)
+* TIME_STYLE:                            Formatting file timestamps.
+                                                              (line 103)
+* TIME_STYLE <1>:                        du invocation.       (line 240)
+* TMPDIR:                                sort invocation.     (line  64)
+* TMPDIR <1>:                            sort invocation.     (line 358)
+* today in date strings:                 Relative items in date strings.
+                                                              (line  33)
+* tomorrow:                              Options for date.    (line  15)
+* tomorrow in date strings:              Relative items in date strings.
+                                                              (line  29)
+* topological sort:                      tsort invocation.    (line   6)
+* tostop:                                Local.               (line  41)
+* total counts:                          wc invocation.       (line  13)
+* touch:                                 touch invocation.    (line   6)
+* tr:                                    tr invocation.       (line   6)
+* trailing slashes:                      Trailing slashes.    (line   6)
+* translating characters:                Translating.         (line   6)
+* true:                                  true invocation.     (line   6)
+* truncate:                              truncate invocation. (line   6)
+* truncating output file, avoiding:      dd invocation.       (line 217)
+* truncating, file sizes:                truncate invocation. (line   6)
+* tsort:                                 tsort invocation.    (line   6)
+* tty:                                   tty invocation.      (line   6)
+* two-way parity:                        Control.             (line   9)
+* type size:                             od invocation.       (line 122)
+* TZ:                                    pr invocation.       (line  91)
+* TZ <1>:                                Formatting file timestamps.
+                                                              (line  17)
+* TZ <2>:                                touch invocation.    (line  35)
+* TZ <3>:                                stat invocation.     (line 220)
+* TZ <4>:                                who invocation.      (line  26)
+* TZ <5>:                                date invocation.     (line  20)
+* TZ <6>:                                Options for date.    (line 135)
+* TZ <7>:                                Specifying time zone rules.
+                                                              (line   6)
+* u, and disabling special characters:   Characters.          (line  12)
+* ucase, converting to:                  dd invocation.       (line 175)
+* umask and modes:                       Umask and Protection.
+                                                              (line   6)
+* uname:                                 uname invocation.    (line   6)
+* unblock:                               dd invocation.       (line 164)
+* unexpand:                              unexpand invocation. (line   6)
+* Unicode:                               printf invocation.   (line  74)
+* uniq:                                  uniq invocation.     (line   6)
+* unique lines, outputting:              uniq invocation.     (line 128)
+* uniquify files:                        uniq invocation.     (line   6)
+* uniquifying output:                    sort invocation.     (line 374)
+* Universal Time:                        Options for date.    (line 135)
+* unlink:                                unlink invocation.   (line   6)
+* unprintable characters, ignoring:      sort invocation.     (line 149)
+* unsorted directory listing:            Sorting the output.  (line  18)
+* upper:                                 Character arrays.    (line 128)
+* uppercase, translating to lowercase:   Input.               (line  50)
+* uptime:                                uptime invocation.   (line   6)
+* use time, changing:                    touch invocation.    (line  48)
+* use time, printing or sorting files by: Sorting the output. (line  13)
+* use time, printing or sorting files by <1>: Sorting the output.
+                                                              (line  44)
+* use time, show the most recent:        du invocation.       (line 202)
+* user IDs, disambiguating:              Disambiguating names and IDs.
+                                                              (line   6)
+* user information, commands for:        User information.    (line   6)
+* user name, printing:                   logname invocation.  (line   6)
+* user names, disambiguating:            Disambiguating names and IDs.
+                                                              (line   6)
+* usernames, printing current:           users invocation.    (line   6)
+* users:                                 users invocation.    (line   6)
+* UTC:                                   Options for date.    (line 135)
+* utmp:                                  logname invocation.  (line   6)
+* utmp <1>:                              users invocation.    (line  14)
+* utmp <2>:                              who invocation.      (line  15)
+* valid file names, checking for:        pathchk invocation.  (line   6)
+* variable-length records, converting to fixed-length: dd invocation.
+                                                              (line  67)
+* vdir:                                  vdir invocation.     (line   6)
+* verbose ls format:                     What information is listed.
+                                                              (line 133)
+* verifying checksums:                   cksum common options.
+                                                              (line  54)
+* verifying checksums <1>:               cksum common options.
+                                                              (line  60)
+* verifying checksums <2>:               cksum common options.
+                                                              (line  68)
+* verifying checksums <3>:               cksum common options.
+                                                              (line  99)
+* verifying checksums <4>:               cksum common options.
+                                                              (line 104)
+* version number sort:                   sort invocation.     (line 183)
+* version number, finding:               Common options.      (line  40)
+* version of kernel:                     uname invocation.    (line  77)
+* version, sorting option for ls:        Sorting the output.  (line  71)
+* version-control Emacs variable:        Backup options.      (line  24)
+* VERSION_CONTROL:                       Backup options.      (line  13)
+* VERSION_CONTROL <1>:                   cp invocation.       (line  79)
+* VERSION_CONTROL <2>:                   install invocation.  (line  41)
+* VERSION_CONTROL <3>:                   mv invocation.       (line  56)
+* VERSION_CONTROL <4>:                   ln invocation.       (line  82)
+* vertical sorted files in columns:      General output formatting.
+                                                              (line  21)
+* vtN:                                   Output.              (line  59)
+* wc:                                    wc invocation.       (line   6)
+* week in date strings:                  Relative items in date strings.
+                                                              (line  15)
+* werase:                                Characters.          (line  64)
+* who:                                   who invocation.      (line   6)
+* who am i:                              who invocation.      (line  21)
+* whoami:                                whoami invocation.   (line   6)
+* width, sorting option for ls:          Sorting the output.  (line  77)
+* word count:                            wc invocation.       (line   6)
+* working context:                       Working context.     (line   6)
+* working directory, printing:           pwd invocation.      (line   6)
+* wrap data:                             base64 invocation.   (line  25)
+* wrapping long input lines:             fold invocation.     (line   6)
+* writable file check:                   Access permission tests.
+                                                              (line  21)
+* write permission:                      Mode Structure.      (line  14)
+* write permission, symbolic:            Setting Permissions. (line  54)
+* write, allowed:                        who invocation.      (line  94)
+* wtmp:                                  users invocation.    (line  14)
+* wtmp <1>:                              who invocation.      (line  15)
+* xcase:                                 Local.               (line  36)
+* xdigit:                                Character arrays.    (line 130)
+* xfs file system type:                  df invocation.       (line 212)
+* XON/XOFF flow control:                 Input.               (line  40)
+* year in date strings:                  Relative items in date strings.
+                                                              (line  15)
+* yes:                                   yes invocation.      (line   6)
+* yesterday:                             Options for date.    (line  15)
+* yesterday in date strings:             Relative items in date strings.
+                                                              (line  29)
+* yottabyte, definition of:              Block size.          (line 116)
+* Youmans, B.:                           Introduction.        (line  29)
+* zero-length string check:              String tests.        (line  15)
+* zettabyte, definition of:              Block size.          (line 111)
+
+
+
+Tag Table:
+Node: Top8616
+Node: Introduction23304
+Node: Common options25185
+Node: Backup options28636
+Node: Block size30662
+Node: Signal specifications36347
+Node: Disambiguating names and IDs38513
+Node: Random sources40157
+Node: Target directory42166
+Node: Trailing slashes45816
+Node: Traversing symlinks46855
+Node: Treating / specially47985
+Node: Special built-in utilities49617
+Node: Exit status50806
+Node: Floating point51681
+Node: Standards conformance53543
+Node: Multi-call invocation55277
+Node: Output of entire files55839
+Node: cat invocation56576
+Node: tac invocation58574
+Node: nl invocation60007
+Node: od invocation64287
+Node: base32 invocation72123
+Node: base64 invocation72722
+Node: basenc invocation74296
+Node: Formatting file contents77979
+Node: fmt invocation78430
+Node: pr invocation81423
+Node: fold invocation93699
+Node: Output of parts of files95214
+Node: head invocation95711
+Node: tail invocation98657
+Node: split invocation109890
+Node: csplit invocation118398
+Node: Summarizing files123884
+Node: wc invocation124595
+Node: sum invocation129058
+Node: cksum invocation130398
+Node: cksum output modes131551
+Node: cksum general options133473
+Node: cksum common options136178
+Node: md5sum invocation141927
+Node: b2sum invocation143455
+Node: sha1sum invocation144515
+Node: sha2 utilities145929
+Node: Operating on sorted files146799
+Node: sort invocation147386
+Ref: sort invocation-Footnote-1173774
+Node: shuf invocation174384
+Node: uniq invocation177585
+Node: comm invocation183726
+Node: ptx invocation187828
+Node: General options in ptx190662
+Node: Charset selection in ptx191262
+Node: Input processing in ptx192170
+Node: Output formatting in ptx197715
+Node: Compatibility in ptx204551
+Node: tsort invocation207934
+Node: tsort background211138
+Node: Operating on fields212846
+Node: cut invocation213208
+Node: paste invocation217988
+Node: join invocation220160
+Node: General options in join221624
+Node: Sorting files for join226832
+Node: Working with fields228542
+Ref: Working with fields-Footnote-1230124
+Node: Paired and unpaired lines230222
+Node: Header lines233160
+Node: Set operations234071
+Node: Operating on characters235591
+Node: tr invocation236014
+Node: Character arrays237872
+Node: Translating244093
+Node: Squeezing and deleting246250
+Node: expand invocation249240
+Node: unexpand invocation251408
+Node: Directory listing253929
+Node: ls invocation254427
+Ref: ls invocation-Footnote-1256594
+Node: Which files are listed256838
+Node: What information is listed260866
+Node: Sorting the output270742
+Node: General output formatting273930
+Node: Formatting file timestamps281563
+Node: Formatting the file names287166
+Node: dir invocation290522
+Node: vdir invocation290949
+Node: dircolors invocation291374
+Node: Basic operations293308
+Node: cp invocation293928
+Node: dd invocation313748
+Node: install invocation333088
+Node: mv invocation339574
+Node: rm invocation345819
+Node: shred invocation350736
+Node: Special file types361099
+Node: link invocation362630
+Node: ln invocation363887
+Node: mkdir invocation373043
+Node: mkfifo invocation376098
+Node: mknod invocation377573
+Node: readlink invocation380122
+Node: rmdir invocation382681
+Node: unlink invocation384301
+Node: Changing file attributes385295
+Node: chown invocation386121
+Node: chgrp invocation393591
+Node: chmod invocation397833
+Node: touch invocation401350
+Node: File space usage407061
+Node: df invocation407765
+Node: du invocation417602
+Node: stat invocation429725
+Node: sync invocation439469
+Node: truncate invocation441661
+Node: Printing text443719
+Node: echo invocation444099
+Node: printf invocation447352
+Node: yes invocation453398
+Node: Conditions454050
+Node: false invocation454645
+Node: true invocation455734
+Node: test invocation457067
+Node: File type tests459240
+Node: Access permission tests460159
+Node: File characteristic tests461073
+Node: String tests461964
+Node: Numeric tests462803
+Node: Connectives for test463638
+Node: expr invocation464892
+Node: String expressions467359
+Node: Numeric expressions470026
+Node: Relations for expr470734
+Node: Examples of expr471963
+Node: Redirection472712
+Node: tee invocation473179
+Node: File name manipulation480274
+Node: basename invocation480849
+Node: dirname invocation483068
+Node: pathchk invocation484885
+Node: mktemp invocation486699
+Node: realpath invocation492517
+Node: Realpath usage examples495580
+Node: Working context497395
+Node: pwd invocation498039
+Node: stty invocation499460
+Node: Control502445
+Node: Input503521
+Node: Output505275
+Node: Local506693
+Node: Combination508780
+Node: Characters511192
+Node: Special513027
+Node: printenv invocation515425
+Node: tty invocation516436
+Node: User information517170
+Node: id invocation517805
+Node: logname invocation520518
+Node: whoami invocation521175
+Node: groups invocation521686
+Node: users invocation522921
+Node: who invocation524101
+Node: System context527436
+Node: date invocation528101
+Node: Date format specifiers529444
+Node: Time conversion specifiers530302
+Node: Date conversion specifiers533049
+Node: Literal conversion specifiers536525
+Node: Padding and other flags536908
+Node: Setting the time540538
+Node: Options for date541701
+Node: Examples of date547351
+Ref: %s-examples548853
+Node: arch invocation552125
+Node: nproc invocation552684
+Node: uname invocation553904
+Node: hostname invocation556632
+Node: hostid invocation557462
+Node: uptime invocation558335
+Node: SELinux context559817
+Node: chcon invocation560192
+Node: runcon invocation562597
+Node: Modified command invocation564378
+Node: chroot invocation565070
+Ref: chroot invocation-Footnote-1568964
+Node: env invocation569481
+Node: nice invocation586342
+Node: nohup invocation590475
+Node: stdbuf invocation592977
+Node: timeout invocation595929
+Node: Process control600721
+Node: kill invocation600944
+Node: Delaying604138
+Node: sleep invocation604335
+Node: Numeric operations605751
+Node: factor invocation606136
+Node: numfmt invocation608104
+Node: seq invocation620199
+Node: File permissions624597
+Node: Mode Structure625290
+Node: Symbolic Modes628969
+Node: Setting Permissions630087
+Node: Copying Permissions632753
+Node: Changing Special Mode Bits633623
+Node: Conditional Executability635505
+Node: Multiple Changes636057
+Node: Umask and Protection637730
+Node: Numeric Modes638875
+Node: Operator Numeric Modes641221
+Node: Directory Setuid and Setgid642281
+Node: File timestamps645136
+Node: Date input formats648459
+Node: General date syntax650948
+Node: Calendar date items654080
+Node: Time of day items656075
+Node: Time zone items658379
+Node: Combined date and time of day items659780
+Node: Day of week items660651
+Node: Relative items in date strings661735
+Node: Pure numbers in date strings664653
+Node: Seconds since the Epoch665642
+Node: Specifying time zone rules667373
+Node: Authors of parse_datetime670988
+Ref: Authors of get_date671179
+Node: Version sort ordering672178
+Node: Version sort overview672499
+Node: Using version sort in GNU Coreutils673511
+Node: Version sort and natural sort675027
+Node: Variations in version sort order675901
+Node: Version sort implementation676681
+Node: Version-sort ordering rules677492
+Node: Version sort is not the same as numeric sort680289
+Node: Version sort punctuation682327
+Node: Punctuation vs letters683958
+Node: The tilde ~684797
+Node: Version sort ignores locale686156
+Node: Differences from Debian version sort687252
+Node: Hyphen-minus and colon687833
+Node: Special priority in GNU Coreutils version sort689464
+Node: Special handling of file extensions690640
+Node: Comparing two strings using Debian's algorithm695713
+Node: Advanced version sort topics697631
+Node: Reporting version sort bugs697921
+Node: Other version/natural sort implementations699126
+Node: Related source code701275
+Node: Opening the software toolbox702041
+Node: Toolbox introduction702839
+Node: I/O redirection705591
+Node: The who command708479
+Node: The cut command709404
+Node: The sort command710506
+Node: The uniq command711224
+Node: Putting the tools together711939
+Node: GNU Free Documentation License724276
+Node: Concept index749655
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
new file mode 100644
index 0000000..373a407
--- /dev/null
+++ b/doc/coreutils.texi
@@ -0,0 +1,20122 @@
+\input texinfo
+@c %**start of header
+@setfilename coreutils.info
+@include version.texi
+@settitle GNU Coreutils @value{VERSION}
+@documentencoding UTF-8
+@set txicodequoteundirected
+@set txicodequotebacktick
+@allowcodebreaks false
+
+@c %**end of header
+
+@include constants.texi
+
+@c Define new indices.
+@defcodeindex op
+@defcodeindex fl
+
+@c Put everything in one index (arbitrarily chosen to be the concept index).
+@syncodeindex fl cp
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex op cp
+@syncodeindex pg cp
+@syncodeindex vr cp
+
+@dircategory Basics
+@direntry
+* Coreutils: (coreutils).       Core GNU (file, text, shell) utilities.
+* Common options: (coreutils)Common options.
+* File permissions: (coreutils)File permissions.  Access modes.
+* Date input formats: (coreutils)Date input formats.
+@end direntry
+
+@c FIXME: the following need documentation
+@c * [: (coreutils)[ invocation.                   File/string tests.
+@c * pinky: (coreutils)pinky invocation.           FIXME.
+
+@dircategory Individual utilities
+@direntry
+* arch: (coreutils)arch invocation.             Print machine hardware name.
+* b2sum: (coreutils)b2sum invocation.           Print or check BLAKE2 digests.
+* base32: (coreutils)base32 invocation.         Base32 encode/decode data.
+* base64: (coreutils)base64 invocation.         Base64 encode/decode data.
+* basename: (coreutils)basename invocation.     Strip directory and suffix.
+* basenc: (coreutils)basenc invocation.         Encoding/decoding of data.
+* cat: (coreutils)cat invocation.               Concatenate and write files.
+* chcon: (coreutils)chcon invocation.           Change SELinux CTX of files.
+* chgrp: (coreutils)chgrp invocation.           Change file groups.
+* chmod: (coreutils)chmod invocation.           Change access permissions.
+* chown: (coreutils)chown invocation.           Change file owners and groups.
+* chroot: (coreutils)chroot invocation.         Specify the root directory.
+* cksum: (coreutils)cksum invocation.           Print POSIX CRC checksum.
+* comm: (coreutils)comm invocation.             Compare sorted files by line.
+* cp: (coreutils)cp invocation.                 Copy files.
+* csplit: (coreutils)csplit invocation.         Split by context.
+* cut: (coreutils)cut invocation.               Print selected parts of lines.
+* date: (coreutils)date invocation.             Print/set system date and time.
+* dd: (coreutils)dd invocation.                 Copy and convert a file.
+* df: (coreutils)df invocation.                 Report file system usage.
+* dir: (coreutils)dir invocation.               List directories briefly.
+* dircolors: (coreutils)dircolors invocation.   Color setup for ls.
+* dirname: (coreutils)dirname invocation.       Strip last file name component.
+* du: (coreutils)du invocation.                 Report file usage.
+* echo: (coreutils)echo invocation.             Print a line of text.
+* env: (coreutils)env invocation.               Modify the environment.
+* expand: (coreutils)expand invocation.         Convert tabs to spaces.
+* expr: (coreutils)expr invocation.             Evaluate expressions.
+* factor: (coreutils)factor invocation.         Print prime factors
+* false: (coreutils)false invocation.           Do nothing, unsuccessfully.
+* fmt: (coreutils)fmt invocation.               Reformat paragraph text.
+* fold: (coreutils)fold invocation.             Wrap long input lines.
+* groups: (coreutils)groups invocation.         Print group names a user is in.
+* head: (coreutils)head invocation.             Output the first part of files.
+* hostid: (coreutils)hostid invocation.         Print numeric host identifier.
+* hostname: (coreutils)hostname invocation.     Print or set system name.
+* id: (coreutils)id invocation.                 Print user identity.
+* install: (coreutils)install invocation.       Copy files and set attributes.
+* join: (coreutils)join invocation.             Join lines on a common field.
+* kill: (coreutils)kill invocation.             Send a signal to processes.
+* link: (coreutils)link invocation.             Make hard links between files.
+* ln: (coreutils)ln invocation.                 Make links between files.
+* logname: (coreutils)logname invocation.       Print current login name.
+* ls: (coreutils)ls invocation.                 List directory contents.
+* md5sum: (coreutils)md5sum invocation.         Print or check MD5 digests.
+* mkdir: (coreutils)mkdir invocation.           Create directories.
+* mkfifo: (coreutils)mkfifo invocation.         Create FIFOs (named pipes).
+* mknod: (coreutils)mknod invocation.           Create special files.
+* mktemp: (coreutils)mktemp invocation.         Create temporary files.
+* mv: (coreutils)mv invocation.                 Rename files.
+* nice: (coreutils)nice invocation.             Modify niceness.
+* nl: (coreutils)nl invocation.                 Number lines and write files.
+* nohup: (coreutils)nohup invocation.           Immunize to hangups.
+* nproc: (coreutils)nproc invocation.           Print the number of processors.
+* numfmt: (coreutils)numfmt invocation.         Reformat numbers.
+* od: (coreutils)od invocation.                 Dump files in octal, etc.
+* paste: (coreutils)paste invocation.           Merge lines of files.
+* pathchk: (coreutils)pathchk invocation.       Check file name portability.
+* pr: (coreutils)pr invocation.                 Paginate or columnate files.
+* printenv: (coreutils)printenv invocation.     Print environment variables.
+* printf: (coreutils)printf invocation.         Format and print data.
+* ptx: (coreutils)ptx invocation.               Produce permuted indexes.
+* pwd: (coreutils)pwd invocation.               Print working directory.
+* readlink: (coreutils)readlink invocation.     Print referent of a symlink.
+* realpath: (coreutils)realpath invocation.     Print resolved file names.
+* rm: (coreutils)rm invocation.                 Remove files.
+* rmdir: (coreutils)rmdir invocation.           Remove empty directories.
+* runcon: (coreutils)runcon invocation.         Run in specified SELinux CTX.
+* seq: (coreutils)seq invocation.               Print numeric sequences
+* sha1sum: (coreutils)sha1sum invocation.       Print or check SHA-1 digests.
+* sha2: (coreutils)sha2 utilities.              Print or check SHA-2 digests.
+* shred: (coreutils)shred invocation.           Remove files more securely.
+* shuf: (coreutils)shuf invocation.             Shuffling text files.
+* sleep: (coreutils)sleep invocation.           Delay for a specified time.
+* sort: (coreutils)sort invocation.             Sort text files.
+* split: (coreutils)split invocation.           Split into pieces.
+* stat: (coreutils)stat invocation.             Report file(system) status.
+* stdbuf: (coreutils)stdbuf invocation.         Modify stdio buffering.
+* stty: (coreutils)stty invocation.             Print/change terminal settings.
+* sum: (coreutils)sum invocation.               Print traditional checksum.
+* sync: (coreutils)sync invocation.             Sync files to stable storage.
+* tac: (coreutils)tac invocation.               Reverse files.
+* tail: (coreutils)tail invocation.             Output the last part of files.
+* tee: (coreutils)tee invocation.               Redirect to multiple files.
+* test: (coreutils)test invocation.             File/string tests.
+* timeout: (coreutils)timeout invocation.       Run with time limit.
+* touch: (coreutils)touch invocation.           Change file timestamps.
+* tr: (coreutils)tr invocation.                 Translate characters.
+* true: (coreutils)true invocation.             Do nothing, successfully.
+* truncate: (coreutils)truncate invocation.     Shrink/extend size of a file.
+* tsort: (coreutils)tsort invocation.           Topological sort.
+* tty: (coreutils)tty invocation.               Print terminal name.
+* uname: (coreutils)uname invocation.           Print system information.
+* unexpand: (coreutils)unexpand invocation.     Convert spaces to tabs.
+* uniq: (coreutils)uniq invocation.             Uniquify files.
+* unlink: (coreutils)unlink invocation.         Removal via unlink(2).
+* uptime: (coreutils)uptime invocation.         Print uptime and load.
+* users: (coreutils)users invocation.           Print current user names.
+* vdir: (coreutils)vdir invocation.             List directories verbosely.
+* wc: (coreutils)wc invocation.                 Line, word, and byte counts.
+* who: (coreutils)who invocation.               Print who is logged in.
+* whoami: (coreutils)whoami invocation.         Print effective user ID.
+* yes: (coreutils)yes invocation.               Print a string indefinitely.
+@end direntry
+
+@copying
+This manual documents version @value{VERSION} of the GNU core
+utilities, including the standard programs for text and file manipulation.
+
+Copyright @copyright{} 1994--2023 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end quotation
+@end copying
+
+@titlepage
+@title GNU @code{Coreutils}
+@subtitle Core GNU utilities
+@subtitle for version @value{VERSION}, @value{UPDATED}
+@author David MacKenzie et al.
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+@shortcontents
+@contents
+
+@ifnottex
+@node Top
+@top GNU Coreutils
+
+@insertcopying
+@end ifnottex
+
+@cindex core utilities
+@cindex text utilities
+@cindex shell utilities
+@cindex file utilities
+
+@menu
+* Introduction::                 Caveats, overview, and authors
+* Common options::               Common options
+* Output of entire files::       cat tac nl od base32 base64 basenc
+* Formatting file contents::     fmt pr fold
+* Output of parts of files::     head tail split csplit
+* Summarizing files::            wc sum cksum b2sum md5sum sha1sum sha2
+* Operating on sorted files::    sort shuf uniq comm ptx tsort
+* Operating on fields::          cut paste join
+* Operating on characters::      tr expand unexpand
+* Directory listing::            ls dir vdir dircolors
+* Basic operations::             cp dd install mv rm shred
+* Special file types::         mkdir rmdir unlink mkfifo mknod ln link readlink
+* Changing file attributes::     chgrp chmod chown touch
+* File space usage::             df du stat sync truncate
+* Printing text::                echo printf yes
+* Conditions::                   false true test expr
+* Redirection::                  tee
+* File name manipulation::       dirname basename pathchk mktemp realpath
+* Working context::              pwd stty printenv tty
+* User information::             id logname whoami groups users who
+* System context::               date arch nproc uname hostname hostid uptime
+* SELinux context::              chcon runcon
+* Modified command invocation::  chroot env nice nohup stdbuf timeout
+* Process control::              kill
+* Delaying::                     sleep
+* Numeric operations::           factor numfmt seq
+* File permissions::             Access modes
+* File timestamps::              File timestamp issues
+* Date input formats::           Specifying date strings
+* Version sort ordering::        Details on version-sort algorithm
+* Opening the software toolbox:: The software tools philosophy
+* GNU Free Documentation License:: Copying and sharing this manual
+* Concept index::                General index
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Common Options
+
+* Exit status::                  Indicating program success or failure
+* Backup options::               Backup options
+* Block size::                   Block size
+* Floating point::               Floating point number representation
+* Signal specifications::        Specifying signals
+* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax
+* Random sources::               Sources of random data
+* Target directory::             Target directory
+* Trailing slashes::             Trailing slashes
+* Traversing symlinks::          Traversing symlinks to directories
+* Treating / specially::         Treating / specially
+* Standards conformance::        Standards conformance
+* Multi-call invocation::        Multi-call program invocation
+
+Output of entire files
+
+* cat invocation::               Concatenate and write files
+* tac invocation::               Concatenate and write files in reverse
+* nl invocation::                Number lines and write files
+* od invocation::                Write files in octal or other formats
+* base32 invocation::            Transform data into printable data
+* base64 invocation::            Transform data into printable data
+* basenc invocation::            Transform data into printable data
+
+Formatting file contents
+
+* fmt invocation::               Reformat paragraph text
+* pr invocation::                Paginate or columnate files for printing
+* fold invocation::              Wrap input lines to fit in specified width
+
+Output of parts of files
+
+* head invocation::              Output the first part of files
+* tail invocation::              Output the last part of files
+* split invocation::             Split a file into fixed-size pieces
+* csplit invocation::            Split a file into context-determined pieces
+
+Summarizing files
+
+* wc invocation::                Print newline, word, and byte counts
+* sum invocation::               Print checksum and block counts
+* cksum invocation::             Print CRC checksum and byte counts
+* md5sum invocation::            Print or check MD5 digests
+* b2sum invocation::             Print or check BLAKE2 digests
+* sha1sum invocation::           Print or check SHA-1 digests
+* sha2 utilities::               Print or check SHA-2 digests
+
+Operating on sorted files
+
+* sort invocation::              Sort text files
+* shuf invocation::              Shuffle text files
+* uniq invocation::              Uniquify files
+* comm invocation::              Compare two sorted files line by line
+* ptx invocation::               Produce a permuted index of file contents
+* tsort invocation::             Topological sort
+
+@command{ptx}: Produce permuted indexes
+
+* General options in ptx::       Options which affect general program behavior
+* Charset selection in ptx::     Underlying character set considerations
+* Input processing in ptx::      Input fields, contexts, and keyword selection
+* Output formatting in ptx::     Types of output format, and sizing the fields
+* Compatibility in ptx::         The GNU extensions to @command{ptx}
+
+Operating on fields
+
+* cut invocation::               Print selected parts of lines
+* paste invocation::             Merge lines of files
+* join invocation::              Join lines on a common field
+
+Operating on characters
+
+* tr invocation::                Translate, squeeze, and/or delete characters
+* expand invocation::            Convert tabs to spaces
+* unexpand invocation::          Convert spaces to tabs
+
+@command{tr}: Translate, squeeze, and/or delete characters
+
+* Character arrays::             Specifying arrays of characters
+* Translating::                  Changing one set of characters to another
+* Squeezing and deleting::       Removing characters
+
+Directory listing
+
+* ls invocation::                List directory contents
+* dir invocation::               Briefly list directory contents
+* vdir invocation::              Verbosely list directory contents
+* dircolors invocation::         Color setup for @command{ls}
+
+@command{ls}:  List directory contents
+
+* Which files are listed::       Which files are listed
+* What information is listed::   What information is listed
+* Sorting the output::           Sorting the output
+* General output formatting::    General output formatting
+* Formatting the file names::    Formatting the file names
+
+Basic operations
+
+* cp invocation::                Copy files and directories
+* dd invocation::                Convert and copy a file
+* install invocation::           Copy files and set attributes
+* mv invocation::                Move (rename) files
+* rm invocation::                Remove files or directories
+* shred invocation::             Remove files more securely
+
+Special file types
+
+* link invocation::              Make a hard link via the link syscall
+* ln invocation::                Make links between files
+* mkdir invocation::             Make directories
+* mkfifo invocation::            Make FIFOs (named pipes)
+* mknod invocation::             Make block or character special files
+* readlink invocation::          Print value of a symlink or canonical file name
+* rmdir invocation::             Remove empty directories
+* unlink invocation::            Remove files via unlink syscall
+
+Changing file attributes
+
+* chown invocation::             Change file owner and group
+* chgrp invocation::             Change group ownership
+* chmod invocation::             Change access permissions
+* touch invocation::             Change file timestamps
+
+File space usage
+
+* df invocation::                Report file system space usage
+* du invocation::                Estimate file space usage
+* stat invocation::              Report file or file system status
+* sync invocation::              Synchronize cached writes to persistent storage
+* truncate invocation::          Shrink or extend the size of a file
+
+Printing text
+
+* echo invocation::              Print a line of text
+* printf invocation::            Format and print data
+* yes invocation::               Print a string until interrupted
+
+Conditions
+
+* false invocation::             Do nothing, unsuccessfully
+* true invocation::              Do nothing, successfully
+* test invocation::              Check file types and compare values
+* expr invocation::              Evaluate expressions
+
+@command{test}: Check file types and compare values
+
+* File type tests::              File type tests
+* Access permission tests::      Access permission tests
+* File characteristic tests::    File characteristic tests
+* String tests::                 String tests
+* Numeric tests::                Numeric tests
+
+@command{expr}: Evaluate expression
+
+* String expressions::           @code{+ : match substr index length}
+* Numeric expressions::          @code{+ - * / %}
+* Relations for expr::           @code{| & < <= = == != >= >}
+* Examples of expr::             Examples of using @command{expr}
+
+Redirection
+
+* tee invocation::               Redirect output to multiple files or processes
+
+File name manipulation
+
+* basename invocation::          Strip directory and suffix from a file name
+* dirname invocation::           Strip last file name component
+* pathchk invocation::           Check file name validity and portability
+* mktemp invocation::            Create temporary file or directory
+* realpath invocation::          Print resolved file names
+
+Working context
+
+* pwd invocation::               Print working directory
+* stty invocation::              Print or change terminal characteristics
+* printenv invocation::          Print all or some environment variables
+* tty invocation::               Print file name of terminal on standard input
+
+@command{stty}: Print or change terminal characteristics
+
+* Control::                      Control settings
+* Input::                        Input settings
+* Output::                       Output settings
+* Local::                        Local settings
+* Combination::                  Combination settings
+* Characters::                   Special characters
+* Special::                      Special settings
+
+User information
+
+* id invocation::                Print user identity
+* logname invocation::           Print current login name
+* whoami invocation::            Print effective user ID
+* groups invocation::            Print group names a user is in
+* users invocation::             Print login names of users currently logged in
+* who invocation::               Print who is currently logged in
+
+System context
+
+* arch invocation::              Print machine hardware name
+* date invocation::              Print or set system date and time
+* nproc invocation::             Print the number of processors
+* uname invocation::             Print system information
+* hostname invocation::          Print or set system name
+* hostid invocation::            Print numeric host identifier
+* uptime invocation::            Print system uptime and load
+
+@command{date}: Print or set system date and time
+
+* Time conversion specifiers::   %[HIklMNpPrRsSTXzZ]
+* Date conversion specifiers::   %[aAbBcCdDeFgGhjmuUVwWxyY]
+* Literal conversion specifiers:: %[%nt]
+* Padding and other flags::      Pad with zeros, spaces, etc.
+* Setting the time::             Changing the system clock
+* Options for date::             Instead of the current time
+* Date input formats::           Specifying date strings
+* Examples of date::             Examples
+
+SELinux context
+
+* chcon invocation::             Change SELinux context of file
+* runcon invocation::            Run a command in specified SELinux context
+
+Modified command invocation
+
+* chroot invocation::            Run a command with a different root directory
+* env invocation::               Run a command in a modified environment
+* nice invocation::              Run a command with modified niceness
+* nohup invocation::             Run a command immune to hangups
+* stdbuf invocation::            Run a command with modified I/O buffering
+* timeout invocation::           Run a command with a time limit
+
+Process control
+
+* kill invocation::              Sending a signal to processes.
+
+Delaying
+
+* sleep invocation::             Delay for a specified time
+
+Numeric operations
+
+* factor invocation::            Print prime factors
+* numfmt invocation::            Reformat numbers
+* seq invocation::               Print numeric sequences
+
+
+File timestamps
+
+* File timestamps::              File timestamp issues
+
+File permissions
+
+* Mode Structure::               Structure of file mode bits
+* Symbolic Modes::               Mnemonic representation of file mode bits
+* Numeric Modes::                File mode bits as octal numbers
+* Directory Setuid and Setgid::  Set-user-ID and set-group-ID on directories
+
+Date input formats
+
+* General date syntax::          Common rules
+* Calendar date items::          @samp{14 Nov 2022}
+* Time of day items::            @samp{9:02pm}
+* Time zone items::              @samp{UTC}, @samp{-0700}, @samp{+0900}, @dots{}
+* Combined date and time of day items:: @samp{2022-11-14T21:02:42,000000-0500}
+* Day of week items::            @samp{Monday} and others
+* Relative items in date strings:: @samp{next tuesday, 2 years ago}
+* Pure numbers in date strings:: @samp{20221114}, @samp{2102}
+* Seconds since the Epoch::      @samp{@@1668477762}
+* Specifying time zone rules::   @samp{TZ="America/New_York"}, @samp{TZ="UTC0"}
+* Authors of parse_datetime::    Bellovin, Eggert, Salz, Berets, et al.
+
+Version sorting order
+
+* Version sort overview::
+* Version sort implementation::
+* Differences from Debian version sort::
+* Advanced version sort topics::
+
+Opening the software toolbox
+
+* Toolbox introduction::         Toolbox introduction
+* I/O redirection::              I/O redirection
+* The who command::              The @command{who} command
+* The cut command::              The @command{cut} command
+* The sort command::             The @command{sort} command
+* The uniq command::             The @command{uniq} command
+* Putting the tools together::   Putting the tools together
+
+Copying This Manual
+
+* GNU Free Documentation License::     Copying and sharing this manual
+
+@end detailmenu
+@end menu
+
+
+@node Introduction
+@chapter Introduction
+
+This manual is a work in progress: many sections make no attempt to explain
+basic concepts in a way suitable for novices.  Thus, if you are interested,
+please get involved in improving this manual.  The entire GNU community
+will benefit.
+
+@cindex POSIX
+The GNU utilities documented here are mostly compatible with the
+POSIX standard.
+@cindex bugs, reporting
+
+Please report bugs to @email{bug-coreutils@@gnu.org}.
+Include the version number, machine architecture, input files, and
+any other information needed to reproduce the bug: your input, what you
+expected, what you got, and why it is wrong.
+
+If you have a problem with @command{sort} or @command{date}, try using the
+@option{--debug} option, as it can often help find and fix problems without
+having to wait for an answer to a bug report.  If the debug output
+does not suffice to fix the problem on your own, please compress and
+attach it to the rest of your bug report.
+
+Although diffs are welcome,
+please include a description of the problem as well, since this is
+sometimes difficult to infer.  @xref{Bugs, , , gcc, Using and Porting GNU CC}.
+
+@cindex Berry, K.
+@cindex Paterson, R.
+@cindex Stallman, R.
+@cindex Pinard, F.
+@cindex MacKenzie, D.
+@cindex Meyering, J.
+@cindex Youmans, B.
+This manual was originally derived from the Unix man pages in the
+distributions, which were written by David MacKenzie and updated by Jim
+Meyering.  What you are reading now is the authoritative documentation
+for these utilities; the man pages are no longer being maintained.  The
+original @command{fmt} man page was written by Ross Paterson.  Fran@,{c}ois
+Pinard did the initial conversion to Texinfo format.  Karl Berry did the
+indexing, some reorganization, and editing of the results.  Brian
+Youmans of the Free Software Foundation office staff combined the
+manuals for textutils, fileutils, and sh-utils to produce the present
+omnibus manual.  Richard Stallman contributed his usual invaluable
+insights to the overall process.
+
+@node Common options
+@chapter Common options
+
+@macro optBackup
+@item -b
+@itemx --backup[=@var{method}]
+@opindex -b
+@opindex --backup
+@vindex VERSION_CONTROL
+@cindex backups, making
+@xref{Backup options}.
+Make a backup of each file that would otherwise be overwritten or removed.
+@end macro
+
+@macro optBackupSuffix
+@item -S @var{suffix}
+@itemx --suffix=@var{suffix}
+@opindex -S
+@opindex --suffix
+Append @var{suffix} to each backup file made with @option{-b}.
+@xref{Backup options}.
+@end macro
+
+@macro optTargetDirectory
+@item -t @var{directory}
+@itemx --target-directory=@var{directory}
+@opindex -t
+@opindex --target-directory
+@cindex target directory
+@cindex destination directory
+Specify the destination @var{directory}.
+@xref{Target directory}.
+@end macro
+
+@macro optNoTargetDirectory
+@item -T
+@itemx --no-target-directory
+@opindex -T
+@opindex --no-target-directory
+@cindex target directory
+@cindex destination directory
+Do not treat the last operand specially when it is a directory or a
+symbolic link to a directory.  @xref{Target directory}.
+@end macro
+
+@macro outputNUL
+@cindex output NUL-byte-terminated lines
+Output a zero byte (ASCII NUL) at the end of each line,
+rather than a newline.  This option enables other programs to parse the
+output even when that output would contain data with embedded newlines.
+@end macro
+
+@macro optNull
+@item -0
+@itemx --null
+@opindex -0
+@opindex --null
+@outputNUL
+@end macro
+
+@macro optZero
+@item -z
+@itemx --zero
+@opindex -z
+@opindex --zero
+@outputNUL
+@end macro
+
+@macro optZeroTerminated
+@item -z
+@itemx --zero-terminated
+@opindex -z
+@opindex --zero-terminated
+@cindex process zero-terminated items
+Delimit items with a zero byte rather than a newline (ASCII LF).
+I.e., treat input as items separated by ASCII NUL
+and terminate output items with ASCII NUL.
+This option can be useful in conjunction with @samp{perl -0} or
+@samp{find -print0} and @samp{xargs -0} which do the same in order to
+reliably handle arbitrary file names (even those containing blanks
+or other special characters).
+@end macro
+
+@macro optSi
+@item --si
+@opindex --si
+@cindex SI output
+Append an SI-style abbreviation to each size, such as @samp{M} for
+megabytes.  Powers of 1000 are used, not 1024; @samp{M} stands for
+1,000,000 bytes.  This option is equivalent to
+@option{--block-size=si}.  Use the @option{-h} or
+@option{--human-readable} option if
+you prefer powers of 1024.
+@end macro
+
+@macro optHumanReadable
+@item -h
+@itemx --human-readable
+@opindex -h
+@opindex --human-readable
+@cindex human-readable output
+Append a size letter to each size, such as @samp{M} for mebibytes.
+Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes.
+This option is equivalent to @option{--block-size=human-readable}.
+Use the @option{--si} option if you prefer powers of 1000.
+@end macro
+
+@macro optStripTrailingSlashes
+@item --strip-trailing-slashes
+@opindex --strip-trailing-slashes
+@cindex stripping trailing slashes
+Remove any trailing slashes from each @var{source} argument.
+@xref{Trailing slashes}.
+@end macro
+
+@macro mayConflictWithShellBuiltIn{cmd}
+@cindex conflicts with shell built-ins
+@cindex built-in shell commands, conflicts with
+Due to shell aliases and built-in @command{\cmd\} functions, using an
+unadorned @command{\cmd\} interactively or in a script may get you
+different functionality than that described here.  Invoke it via
+@command{env} (i.e., @code{env \cmd\ @dots{}}) to avoid interference
+from the shell.
+
+@end macro
+
+@macro multiplierSuffixes{varName}
+@var{\varName\} may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
+@example
+@samp{b}  =>            512 ("blocks")
+@samp{KB} =>           1000 (KiloBytes)
+@samp{K}  =>           1024 (KibiBytes)
+@samp{MB} =>      1000*1000 (MegaBytes)
+@samp{M}  =>      1024*1024 (MebiBytes)
+@samp{GB} => 1000*1000*1000 (GigaBytes)
+@samp{G}  => 1024*1024*1024 (GibiBytes)
+@end example
+and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y},
+@samp{R}, and @samp{Q}.
+Binary prefixes can be used, too: @samp{KiB}=@samp{K}, @samp{MiB}=@samp{M},
+and so on.
+@end macro
+
+@c FIXME: same as above, but no ``blocks'' line.
+@macro multiplierSuffixesNoBlocks{varName}
+@var{\varName\} may be, or may be an integer optionally followed by,
+one of the following multiplicative suffixes:
+@example
+@samp{KB} =>           1000 (KiloBytes)
+@samp{K}  =>           1024 (KibiBytes)
+@samp{MB} =>      1000*1000 (MegaBytes)
+@samp{M}  =>      1024*1024 (MebiBytes)
+@samp{GB} => 1000*1000*1000 (GigaBytes)
+@samp{G}  => 1024*1024*1024 (GibiBytes)
+@end example
+and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y},
+@samp{R}, and @samp{Q}.
+Binary prefixes can be used, too: @samp{KiB}=@samp{K}, @samp{MiB}=@samp{M},
+and so on.
+@end macro
+
+@cindex common options
+
+Certain options are available in all of these programs.  Rather than
+writing identical descriptions for each of the programs, they are
+described here.  (In fact, every GNU program accepts (or should accept)
+these options.)
+
+@vindex POSIXLY_CORRECT
+Normally options and operands can appear in any order, and programs act
+as if all the options appear before any operands.  For example,
+@samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since
+@samp{:} is an option-argument of @option{-t}.  However, if the
+@env{POSIXLY_CORRECT} environment variable is set, options must appear
+before operands, unless otherwise specified for a particular command.
+
+A few programs can usefully have trailing operands with leading
+@samp{-}.  With such a program, options must precede operands even if
+@env{POSIXLY_CORRECT} is not set, and this fact is noted in the
+program description.  For example, the @command{env} command's options
+must appear before its operands, since in some cases the operands
+specify a command that itself contains options.
+
+Most programs that accept long options recognize unambiguous
+abbreviations of those options.  For example, @samp{rmdir
+--ignore-fail-on-non-empty} can be invoked as @samp{rmdir
+--ignore-fail} or even @samp{rmdir --i}.  Ambiguous options, such as
+@samp{ls --h}, are identified as such.
+
+Some of these programs recognize the @option{--help} and @option{--version}
+options only when one of them is the sole command line argument.  For
+these programs, abbreviations of the long options are not always recognized.
+
+@table @samp
+
+@item --help
+@opindex --help
+@cindex help, online
+Print a usage message listing all available options, then exit successfully.
+
+@item --version
+@opindex --version
+@cindex version number, finding
+Print the version number, then exit successfully.
+
+@item --
+@opindex --
+@cindex option delimiter
+Delimit the option list.  Later arguments, if any, are treated as
+operands even if they begin with @samp{-}.  For example, @samp{sort --
+-r} reads from the file named @file{-r}.
+
+@end table
+
+@cindex standard input
+@cindex standard output
+A single @samp{-} operand is not really an option, though it looks like one.  It
+stands for a file operand, and some tools treat it as standard input, or as
+standard output if that is clear from the context.  For example, @samp{sort -}
+reads from standard input, and is equivalent to plain @samp{sort}.  Unless
+otherwise specified, a @samp{-} can appear as any operand that requires a file
+name.
+
+@menu
+Items shared between some programs:
+
+* Backup options::               @option{-b} @option{-S}.
+* Block size::                   BLOCK_SIZE and @option{--block-size}.
+* Signal specifications::        Specifying signals with @option{--signal}.
+* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax
+* Random sources::               @option{--random-source}.
+* Target directory::             Specifying a target directory.
+* Trailing slashes::             @option{--strip-trailing-slashes}.
+* Traversing symlinks::          @option{-H}, @option{-L}, or @option{-P}.
+* Treating / specially::         @option{--preserve-root} and the converse.
+* Special built-in utilities::   @command{break}, @command{:}, @dots{}
+
+Items applicable to all programs:
+
+* Exit status::                  Indicating program success or failure.
+* Floating point::               Floating point number representation.
+* Standards conformance::        Conformance to the POSIX standard.
+* Multi-call invocation::        Multi-call program invocation.
+@end menu
+
+
+@node Backup options
+@section Backup options
+
+@cindex backup options
+
+Some GNU programs (at least @command{cp}, @command{install},
+@command{ln}, and @command{mv}) optionally make backups of files
+before writing new versions.
+These options control the details of these backups.  The options are also
+briefly mentioned in the descriptions of the particular programs.
+
+@table @samp
+
+@item -b
+@itemx --backup[=@var{method}]
+@opindex -b
+@opindex --backup
+@vindex VERSION_CONTROL
+@cindex backups, making
+Make a backup of each file that would otherwise be overwritten or removed.
+Without this option, the original versions are destroyed.
+Use @var{method} to determine the type of backups to make.
+When this option is used but @var{method} is not specified,
+then the value of the @env{VERSION_CONTROL}
+environment variable is used.  And if @env{VERSION_CONTROL} is not set,
+the default backup type is @samp{existing}.
+
+Note that the short form of this option, @option{-b} does not accept any
+argument.  Using @option{-b} is equivalent to using @option{--backup=existing}.
+
+@vindex version-control @r{Emacs variable}
+This option corresponds to the Emacs variable @samp{version-control};
+the values for @var{method} are the same as those used in Emacs.
+This option also accepts more descriptive names.
+The valid @var{method}s are (unique abbreviations are accepted):
+
+@table @samp
+@item none
+@itemx off
+@opindex none @r{backup method}
+Never make backups.
+
+@item numbered
+@itemx t
+@opindex numbered @r{backup method}
+Always make numbered backups.
+
+@item existing
+@itemx nil
+@opindex existing @r{backup method}
+Make numbered backups of files that already have them, simple backups
+of the others.
+
+@item simple
+@itemx never
+@opindex simple @r{backup method}
+Always make simple backups.  Please note @samp{never} is not to be
+confused with @samp{none}.
+
+@end table
+
+@item -S @var{suffix}
+@itemx --suffix=@var{suffix}
+@opindex -S
+@opindex --suffix
+@cindex backup suffix
+@vindex SIMPLE_BACKUP_SUFFIX
+Append @var{suffix} to each backup file made with @option{-b}.  If this
+option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
+environment variable is used.  And if @env{SIMPLE_BACKUP_SUFFIX} is not
+set, the default is @samp{~}, just as in Emacs.
+
+@end table
+
+@node Block size
+@section Block size
+
+@cindex block size
+
+Some GNU programs (at least @command{df}, @command{du}, and
+@command{ls}) display sizes in ``blocks''.  You can adjust the block size
+and method of display to make sizes easier to read.  The block size
+used for display is independent of any file system block size.
+Fractional block counts are rounded up to the nearest integer.
+
+@opindex --block-size=@var{size}
+@vindex BLOCKSIZE
+@vindex BLOCK_SIZE
+@vindex DF_BLOCK_SIZE
+@vindex DU_BLOCK_SIZE
+@vindex LS_BLOCK_SIZE
+@vindex POSIXLY_CORRECT@r{, and block size}
+
+The default block size is chosen by examining the following environment
+variables in turn; the first one that is set determines the block size.
+
+@table @code
+
+@item DF_BLOCK_SIZE
+This specifies the default block size for the @command{df} command.
+Similarly, @env{DU_BLOCK_SIZE} specifies the default for @command{du} and
+@env{LS_BLOCK_SIZE} for @command{ls}.
+
+@item BLOCK_SIZE
+This specifies the default block size for all three commands, if the
+above command-specific environment variables are not set.
+
+@item BLOCKSIZE
+This specifies the default block size for all values that are normally
+printed as blocks, if neither @env{BLOCK_SIZE} nor the above
+command-specific environment variables are set.  Unlike the other
+environment variables, @env{BLOCKSIZE} does not affect values that are
+normally printed as byte counts, e.g., the file sizes contained in
+@code{ls -l} output.
+
+@item POSIXLY_CORRECT
+If neither @env{@var{command}_BLOCK_SIZE}, nor @env{BLOCK_SIZE}, nor
+@env{BLOCKSIZE} is set, but this variable is set, the block size
+defaults to 512.
+
+@end table
+
+If none of the above environment variables are set, the block size
+currently defaults to 1024 bytes in most contexts, but this number may
+change in the future.  For @command{ls} file sizes, the block size
+defaults to 1 byte.
+
+@cindex human-readable output
+@cindex SI output
+
+A block size specification can be a positive integer specifying the number
+of bytes per block, or it can be @code{human-readable} or @code{si} to
+select a human-readable format.  Integers may be followed by suffixes
+that are upward compatible with the
+@uref{http://www.bipm.org/en/publications/si-brochure/chapter3.html,
+SI prefixes}
+for decimal multiples and with the
+@uref{https://physics.nist.gov/cuu/Units/binary.html, ISO/IEC 80000-13
+(formerly IEC 60027-2) prefixes} for binary multiples.
+
+With human-readable formats, output sizes are followed by a size letter
+such as @samp{M} for megabytes.  @code{BLOCK_SIZE=human-readable} uses
+powers of 1024; @samp{M} stands for 1,048,576 bytes.
+@code{BLOCK_SIZE=si} is similar, but uses powers of 1000 and appends
+@samp{B}; @samp{MB} stands for 1,000,000 bytes.
+
+@vindex LC_NUMERIC
+A block size specification preceded by @samp{'} causes output sizes to
+be displayed with thousands separators.  The @env{LC_NUMERIC} locale
+specifies the thousands separator and grouping.  For example, in an
+American English locale, @samp{--block-size="'1kB"} would cause a size
+of 1234000 bytes to be displayed as @samp{1,234}.  In the default C
+locale, there is no thousands separator so a leading @samp{'} has no
+effect.
+
+An integer block size can be followed by a suffix to specify a
+multiple of that size.  A bare size letter,
+or one followed by @samp{iB}, specifies
+a multiple using powers of 1024.  A size letter followed by @samp{B}
+specifies powers of 1000 instead.  For example, @samp{1M} and
+@samp{1MiB} are equivalent to @samp{1048576}, whereas @samp{1MB} is
+equivalent to @samp{1000000}.
+
+A plain suffix without a preceding integer acts as if @samp{1} were
+prepended, except that it causes a size indication to be appended to
+the output.  For example, @samp{--block-size="kB"} displays 3000 as
+@samp{3kB}.
+
+The following suffixes are defined.  Large sizes like @code{1Q}
+may be rejected by your computer due to limitations of its arithmetic.
+
+@table @samp
+@item kB
+@cindex kilobyte, definition of
+kilobyte: @math{10^3 = 1000}.
+@item k
+@itemx K
+@itemx KiB
+@cindex kibibyte, definition of
+kibibyte: @math{2^{10} = 1024}.  @samp{K} is special: the SI prefix is
+@samp{k} and the ISO/IEC 80000-13 prefix is @samp{Ki}, but tradition and
+POSIX use @samp{k} to mean @samp{KiB}.
+@item MB
+@cindex megabyte, definition of
+megabyte: @math{10^6 = 1,000,000}.
+@item M
+@itemx MiB
+@cindex mebibyte, definition of
+mebibyte: @math{2^{20} = 1,048,576}.
+@item GB
+@cindex gigabyte, definition of
+gigabyte: @math{10^9 = 1,000,000,000}.
+@item G
+@itemx GiB
+@cindex gibibyte, definition of
+gibibyte: @math{2^{30} = 1,073,741,824}.
+@item TB
+@cindex terabyte, definition of
+terabyte:  @math{10^{12} = 1,000,000,000,000}.
+@item T
+@itemx TiB
+@cindex tebibyte, definition of
+tebibyte: @math{2^{40} = 1,099,511,627,776}.
+@item PB
+@cindex petabyte, definition of
+petabyte: @math{10^{15} = 1,000,000,000,000,000}.
+@item P
+@itemx PiB
+@cindex pebibyte, definition of
+pebibyte: @math{2^{50} = 1,125,899,906,842,624}.
+@item EB
+@cindex exabyte, definition of
+exabyte: @math{10^{18} = 1,000,000,000,000,000,000}.
+@item E
+@itemx EiB
+@cindex exbibyte, definition of
+exbibyte: @math{2^{60} = 1,152,921,504,606,846,976}.
+@item ZB
+@cindex zettabyte, definition of
+zettabyte: @math{10^{21} = 1,000,000,000,000,000,000,000}
+@item Z
+@itemx ZiB
+zebibyte: @math{2^{70} = 1,180,591,620,717,411,303,424}.
+@item YB
+@cindex yottabyte, definition of
+yottabyte: @math{10^{24} = 1,000,000,000,000,000,000,000,000}.
+@item Y
+@itemx YiB
+yobibyte: @math{2^{80} = 1,208,925,819,614,629,174,706,176}.
+@item RB
+@cindex ronnabyte, definition of
+ronnabyte: @math{10^{27} = 1,000,000,000,000,000,000,000,000,000}.
+@item R
+@itemx RiB
+robibyte: @math{2^{90} = 1,237,940,039,285,380,274,899,124,224}.
+@item QB
+@cindex quettabyte, definition of
+quettabyte: @math{10^{30} = 1,000,000,000,000,000,000,000,000,000,000}.
+@item Q
+@itemx QiB
+quebibyte: @math{2^{100} = 1,267,650,600,228,229,401,496,703,205,376}.
+@end table
+
+@opindex -k
+@opindex -h
+@opindex --block-size
+@opindex --human-readable
+@opindex --si
+
+Block size defaults can be overridden by an explicit
+@option{--block-size=@var{size}} option.  The @option{-k}
+option is equivalent to @option{--block-size=1K}, which
+is the default unless the @env{POSIXLY_CORRECT} environment variable is
+set.  The @option{-h} or @option{--human-readable} option is equivalent to
+@option{--block-size=human-readable}.  The @option{--si} option is
+equivalent to @option{--block-size=si}.  Note for @command{ls}
+the @option{-k} option does not control the display of the
+apparent file sizes, whereas the @option{--block-size} option does.
+
+@node Signal specifications
+@section Signal specifications
+@cindex signals, specifying
+
+A @var{signal} may be a signal name like @samp{HUP}, or a signal
+number like @samp{1}, or an exit status of a process terminated by the
+signal.  A signal name can be given in canonical form or prefixed by
+@samp{SIG}@.  The case of the letters is ignored.  The following signal names
+and numbers are supported on all POSIX compliant systems:
+
+@table @samp
+@item HUP
+1.  Hangup.
+@item INT
+2.  Terminal interrupt.
+@item QUIT
+3.  Terminal quit.
+@item ABRT
+6.  Process abort.
+@item KILL
+9.  Kill (cannot be caught or ignored).
+@item ALRM
+14.  Alarm Clock.
+@item TERM
+15.  Termination.
+@end table
+
+@noindent
+Other supported signal names have system-dependent corresponding
+numbers.  All systems conforming to POSIX 1003.1-2001 also
+support the following signals:
+
+@table @samp
+@item BUS
+Access to an undefined portion of a memory object.
+@item CHLD
+Child process terminated, stopped, or continued.
+@item CONT
+Continue executing, if stopped.
+@item FPE
+Erroneous arithmetic operation.
+@item ILL
+Illegal Instruction.
+@item PIPE
+Write on a pipe with no one to read it.
+@item SEGV
+Invalid memory reference.
+@item STOP
+Stop executing (cannot be caught or ignored).
+@item TSTP
+Terminal stop.
+@item TTIN
+Background process attempting read.
+@item TTOU
+Background process attempting write.
+@item URG
+High bandwidth data is available at a socket.
+@item USR1
+User-defined signal 1.
+@item USR2
+User-defined signal 2.
+@end table
+
+@noindent
+POSIX 1003.1-2001 systems that support the XSI extension
+also support the following signals:
+
+@table @samp
+@item POLL
+Pollable event.
+@item PROF
+Profiling timer expired.
+@item SYS
+Bad system call.
+@item TRAP
+Trace/breakpoint trap.
+@item VTALRM
+Virtual timer expired.
+@item XCPU
+CPU time limit exceeded.
+@item XFSZ
+File size limit exceeded.
+@end table
+
+@noindent
+POSIX 1003.1-2001 systems that support the XRT extension
+also support at least eight real-time signals called @samp{RTMIN},
+@samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}.
+
+@node Disambiguating names and IDs
+@section chown, chgrp, chroot, id: Disambiguating user names and IDs
+@cindex user names, disambiguating
+@cindex user IDs, disambiguating
+@cindex group names, disambiguating
+@cindex group IDs, disambiguating
+@cindex disambiguating group names and IDs
+
+Since the @var{user} and @var{group} arguments to these commands
+may be specified as names or numeric IDs, there is an
+apparent ambiguity.
+What if a user or group @emph{name} is a string of digits?
+Should the command interpret it as a user name or as an ID@?
+(Using a number as a user name is common in some environments.)
+POSIX requires that these commands
+first attempt to resolve the specified string as a name, and
+only once that fails, then try to interpret it as an ID@.
+This is troublesome when you want to specify a numeric ID, say 42,
+and it must work even in a pathological situation where
+@samp{42} is a user name that maps to some other user ID, say 1000.
+Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to
+1000 -- not what you intended.
+
+GNU @command{chown}, @command{chgrp}, @command{chroot}, and @command{id}
+provide a way to work around this, that at the same time may result in a
+significant performance improvement by eliminating a database look-up.
+Simply precede each numeric user ID and/or group ID with a @samp{+},
+in order to force its interpretation as an integer:
+
+@example
+chown +42 F
+chgrp +$numeric_group_id another-file
+chown +0:+0 /
+@end example
+
+The name look-up process is skipped for each @samp{+}-prefixed string,
+because a string containing @samp{+} is never a valid user or group name.
+This syntax is accepted on most common Unix systems, but not on Solaris 10.
+
+@node Random sources
+@section Sources of random data
+
+@cindex random sources
+
+The @command{shuf}, @command{shred}, and @command{sort} commands
+sometimes need random data to do their work.  For example, @samp{sort
+-R} must choose a hash function at random, and it needs random data to
+make this selection.
+
+By default these commands use an internal pseudo-random generator
+initialized by a small amount of entropy, but can be directed to use
+an external source with the @option{--random-source=@var{file}} option.
+An error is reported if @var{file} does not contain enough bytes.
+
+For example, the device file @file{/dev/urandom} could be used as the
+source of random data.  Typically, this device gathers environmental
+noise from device drivers and other sources into an entropy pool, and
+uses the pool to generate random bits.  If the pool is short of data,
+the device reuses the internal pool to produce more bits, using a
+cryptographically secure pseudo-random number generator.  But be aware
+that this device is not designed for bulk random data generation
+and is relatively slow.
+
+@file{/dev/urandom} suffices for most practical uses, but applications
+requiring high-value or long-term protection of private data may
+require an alternate data source like @file{/dev/random} or
+@file{/dev/arandom}.  The set of available sources depends on your
+operating system.
+
+To reproduce the results of an earlier invocation of a command, you
+can save some random data into a file and then use that file as the
+random source in earlier and later invocations of the command.
+@cindex random seed
+Rather than depending on a file, one can generate a reproducible
+arbitrary amount of pseudo-random data given a seed value, using
+for example:
+
+@example
+get_seeded_random()
+@{
+  seed="$1"
+  openssl enc -aes-256-ctr -pass pass:"$seed" -nosalt \
+    </dev/zero 2>/dev/null
+@}
+
+shuf -i1-100 --random-source=<(get_seeded_random 42)
+@end example
+
+@node Target directory
+@section Target directory
+
+@cindex target directory
+
+The @command{cp}, @command{install}, @command{ln}, and @command{mv}
+commands normally treat the last operand specially when it is a
+directory or a symbolic link to a directory.  For example, @samp{cp
+source dest} is equivalent to @samp{cp source dest/source} if
+@file{dest} is a directory.  Sometimes this behavior is not exactly
+what is wanted, so these commands support the following options to
+allow more fine-grained control:
+
+@table @samp
+
+@item -T
+@itemx --no-target-directory
+@opindex --no-target-directory
+@cindex target directory
+@cindex destination directory
+Do not treat the last operand specially when it is a directory or a
+symbolic link to a directory.  This can help avoid race conditions in
+programs that operate in a shared area.  For example, when the command
+@samp{mv /tmp/source /tmp/dest} succeeds, there is no guarantee that
+@file{/tmp/source} was renamed to @file{/tmp/dest}: it could have been
+renamed to @file{/tmp/dest/source} instead, if some other process
+created @file{/tmp/dest} as a directory.  However, if @file{mv
+-T /tmp/source /tmp/dest} succeeds, there is no
+question that @file{/tmp/source} was renamed to @file{/tmp/dest}.
+
+In the opposite situation, where you want the last operand to be
+treated as a directory and want a diagnostic otherwise, you can use
+the @option{--target-directory} (@option{-t}) option.
+
+@item -t @var{directory}
+@itemx --target-directory=@var{directory}
+@opindex --target-directory
+@cindex target directory
+@cindex destination directory
+Use @var{directory} as the directory component of each destination
+file name.
+
+The interface for most programs is that after processing options and a
+finite (possibly zero) number of fixed-position arguments, the remaining
+argument list is either expected to be empty, or is a list of items
+(usually files) that will all be handled identically.  The @command{xargs}
+program is designed to work well with this convention.
+
+The commands in the @command{mv}-family are unusual in that they take
+a variable number of arguments with a special case at the @emph{end}
+(namely, the target directory).  This makes it nontrivial to perform some
+operations, e.g., ``move all files from here to ../d/'', because
+@code{mv * ../d/} might exhaust the argument space, and @code{ls | xargs ...}
+doesn't have a clean way to specify an extra final argument for each
+invocation of the subject command.  (It can be done by going through a
+shell command, but that requires more human labor and brain power than
+it should.)
+
+The @option{--target-directory} (@option{-t}) option allows the @command{cp},
+@command{install}, @command{ln}, and @command{mv} programs to be used
+conveniently with @command{xargs}.  For example, you can move the files
+from the current directory to a sibling directory, @code{d} like this:
+
+@example
+ls | xargs mv -t ../d --
+@end example
+
+However, this doesn't move files whose names begin with @samp{.}.
+If you use the GNU @command{find} program, you can move those
+files too, with this command:
+
+@example
+find . -mindepth 1 -maxdepth 1 \
+  | xargs mv -t ../d
+@end example
+
+But both of the above approaches fail if there are no files in the
+current directory, or if any file has a name containing a blank or
+some other special characters.
+The following example removes those limitations and requires both
+GNU @command{find} and GNU @command{xargs}:
+
+@example
+find . -mindepth 1 -maxdepth 1 -print0 \
+  | xargs --null --no-run-if-empty \
+      mv -t ../d
+@end example
+
+@end table
+
+@noindent
+The @option{--target-directory} (@option{-t}) and
+@option{--no-target-directory} (@option{-T})
+options cannot be combined.
+
+@node Trailing slashes
+@section Trailing slashes
+
+@cindex trailing slashes
+
+Some GNU programs (at least @command{cp} and @command{mv}) allow you to
+remove any trailing slashes from each @var{source} argument before
+operating on it.  The @option{--strip-trailing-slashes} option enables
+this behavior.
+
+This is useful when a @var{source} argument may have a trailing slash and
+@c FIXME: mv's behavior in this case is system-dependent
+specify a symbolic link to a directory.  This scenario is in fact rather
+common because some shells can automatically append a trailing slash when
+performing file name completion on such symbolic links.  Without this
+option, @command{mv}, for example, (via the system's rename function) must
+interpret a trailing slash as a request to dereference the symbolic link
+and so must rename the indirectly referenced @emph{directory} and not
+the symbolic link.  Although it may seem surprising that such behavior
+be the default, it is required by POSIX and is consistent with
+other parts of that standard.
+
+@node Traversing symlinks
+@section Traversing symlinks
+
+@cindex symbolic link to directory, controlling traversal of
+
+The following options modify how @command{chown} and @command{chgrp}
+@c FIXME: note that 'du' has these options, too, but they have slightly
+@c different meaning.
+traverse a hierarchy when the @option{--recursive} (@option{-R})
+option is also specified.
+If more than one of the following options is specified, only the final
+one takes effect.
+These options specify whether processing a symbolic link to a directory
+entails operating on just the symbolic link or on all files in the
+hierarchy rooted at that directory.
+
+These options are independent of @option{--dereference} and
+@option{--no-dereference} (@option{-h}), which control whether to modify
+a symlink or its referent.
+
+@table @samp
+
+@macro choptH
+@item -H
+@opindex -H
+@cindex symbolic link to directory, traverse if on the command line
+If @option{--recursive} (@option{-R}) is specified and
+a command line argument is a symbolic link to a directory, traverse it.
+@end macro
+@choptH
+
+@macro choptL
+@item -L
+@opindex -L
+@cindex symbolic link to directory, traverse each that is encountered
+In a recursive traversal, traverse every symbolic link to a directory
+that is encountered.
+@end macro
+
+@c Append the following warning to -L where appropriate (e.g. chown).
+@macro warnOptDerefWithRec
+
+Combining this dereferencing option with the @option{--recursive} option
+may create a security risk:
+During the traversal of the directory tree, an attacker may be able to
+introduce a symlink to an arbitrary target; when the tool reaches that,
+the operation will be performed on the target of that symlink,
+possibly allowing the attacker to escalate privileges.
+
+@end macro
+
+@choptL
+
+@macro choptP
+@item -P
+@opindex -P
+@cindex symbolic link to directory, never traverse
+Do not traverse any symbolic links.
+This is the default if none of @option{-H}, @option{-L},
+or @option{-P} is specified.
+@end macro
+@choptP
+
+@end table
+
+
+@node Treating / specially
+@section Treating @file{/} specially
+
+Certain commands can operate destructively on entire hierarchies.
+For example, if a user with appropriate privileges mistakenly runs
+@samp{rm -rf / tmp/junk}, that may remove
+all files on the entire system.  Since there are so few
+legitimate uses for such a command,
+GNU @command{rm} normally declines to operate on any directory
+that resolves to @file{/}.  If you really want to try to remove all
+the files on your system, you can use the @option{--no-preserve-root}
+option, but the default behavior, specified by the
+@option{--preserve-root} option, is safer for most purposes.
+
+The commands @command{chgrp}, @command{chmod} and @command{chown}
+can also operate destructively on entire hierarchies, so they too
+support these options.  Although, unlike @command{rm}, they don't
+actually unlink files, these commands are arguably more dangerous
+when operating recursively on @file{/}, since they often work much
+more quickly, and hence damage more files before an alert user can
+interrupt them.  Tradition and POSIX require these commands
+to operate recursively on @file{/}, so they default to
+@option{--no-preserve-root}, but using the @option{--preserve-root}
+option makes them safer for most purposes.  For convenience you can
+specify @option{--preserve-root} in an alias or in a shell function.
+
+Note that the @option{--preserve-root} option also ensures
+that @command{chgrp} and @command{chown} do not modify @file{/}
+even when dereferencing a symlink pointing to @file{/}.
+
+@node Special built-in utilities
+@section Special built-in utilities
+
+Some programs like @command{nice} can invoke other programs; for
+example, the command @samp{nice cat file} invokes the program
+@command{cat} by executing the command @samp{cat file}.  However,
+@dfn{special built-in utilities} like @command{exit} cannot be invoked
+this way.  For example, the command @samp{nice exit} does not have a
+well-defined behavior: it may generate an error message instead of
+exiting.
+
+Here is a list of the special built-in utilities that are standardized
+by POSIX 1003.1-2004.
+
+@quotation
+@t{.@: : break continue eval exec exit export readonly
+return set shift times trap unset}
+@end quotation
+
+For example, because @samp{.}, @samp{:}, and @samp{exec} are special,
+the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec
+pwd} do not work as you might expect.
+
+Many shells extend this list.  For example, Bash has several extra
+special built-in utilities like @command{history}, and
+@command{suspend}, and with Bash the command @samp{nice suspend}
+generates an error message instead of suspending.
+
+
+@node Exit status
+@section Exit status
+
+@macro exitstatus
+An exit status of zero indicates success,
+and a nonzero value indicates failure.
+@end macro
+
+Nearly every command invocation yields an integral @dfn{exit status}
+that can be used to change how other commands work.
+For the vast majority of commands, an exit status of zero indicates
+success.  Failure is indicated by a nonzero value -- typically
+@samp{1}, though it may differ on unusual platforms as POSIX
+requires only that it be nonzero.
+
+However, some of the programs documented here do produce
+other exit status values and a few associate different
+meanings with the values @samp{0} and @samp{1}.
+Here are the exceptions:
+@c You can generate the following list with:
+@c grep initialize_exit_failure src/*.c | cut -f1 -d: |
+@c sed -n 's|src/\(.*\)\.c|@command{\1},|p' | sort | fmt
+@command{chroot}, @command{env}, @command{expr}, @command{ls},
+@command{nice}, @command{nohup}, @command{numfmt}, @command{printenv},
+@command{runcon}, @command{sort}, @command{stdbuf}, @command{test},
+@command{timeout}, @command{tty}.
+
+@node Floating point
+@section Floating point numbers
+@cindex floating point
+@cindex IEEE floating point
+
+Commands that accept or produce floating point numbers employ the
+floating point representation of the underlying system, and suffer
+from rounding error, overflow, and similar floating-point issues.
+Almost all modern systems use IEEE-754 floating point, and it is
+typically portable to assume IEEE-754 behavior these days.  IEEE-754
+has positive and negative infinity, distinguishes positive from
+negative zero, and uses special values called NaNs to represent
+invalid computations such as dividing zero by itself.  For more
+information, please see David Goldberg's paper
+@uref{https://@/docs.oracle.com/@/cd/@/E19957-01/@/806-3568/@/ncg_goldberg.html,
+What Every Computer Scientist Should Know About Floating-Point Arithmetic}.
+
+Commands that accept floating point numbers as options, operands or
+input use the standard C functions @code{strtod} and @code{strtold} to
+convert from text to floating point numbers.  These floating point
+numbers therefore can use scientific notation like @code{1.0e-34} and
+@code{-10e100}.  Commands that parse floating point also understand
+case-insensitive @code{inf}, @code{infinity}, and @code{NaN}, although
+whether such values are useful depends on the command in question.
+Modern C implementations also accept hexadecimal floating point
+numbers such as @code{-0x.ep-3}, which stands for @minus{}14/16 times
+@math{2^-3}, which equals @minus{}0.109375.  @xref{Parsing of
+Floats,,, libc, The GNU C Library Reference Manual}.
+
+@vindex LC_NUMERIC
+Normally the @env{LC_NUMERIC} locale determines the decimal-point
+character.  However, some commands' descriptions specify that they
+accept numbers in either the current or the C locale; for example,
+they treat @samp{3.14} like @samp{3,14} if the current locale uses
+comma as a decimal point.
+
+
+@node Standards conformance
+@section Standards conformance
+
+@vindex POSIXLY_CORRECT
+In a few cases, the GNU utilities' default behavior is
+incompatible with the POSIX standard.  To suppress these
+incompatibilities, define the @env{POSIXLY_CORRECT} environment
+variable.  Unless you are checking for POSIX conformance, you
+probably do not need to define @env{POSIXLY_CORRECT}.
+
+Newer versions of POSIX are occasionally incompatible with older
+versions.  For example, older versions of POSIX required the
+command @samp{sort +1} to sort based on the second and succeeding
+fields in each input line, but in POSIX 1003.1-2001
+the same command is required to sort the file named @file{+1}, and you
+must instead use the command @samp{sort -k 2} to get the field-based
+sort.  To complicate things further, POSIX 1003.1-2008 allows an
+implementation to have either the old or the new behavior.
+
+@vindex _POSIX2_VERSION
+The GNU utilities normally conform to the version of POSIX
+that is standard for your system.  To cause them to conform to a
+different version of POSIX, define the @env{_POSIX2_VERSION}
+environment variable to a value of the form @var{yyyymm} specifying
+the year and month the standard was adopted.  Three values are currently
+supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
+POSIX 1003.2-1992, @samp{200112} stands for POSIX
+1003.1-2001, and @samp{200809} stands for POSIX 1003.1-2008.
+For example, if you have a POSIX 1003.1-2001 system but are running software
+containing traditional usage like @samp{sort +1} or @samp{tail +10},
+you can work around the compatibility problems by setting
+@samp{_POSIX2_VERSION=200809} in your environment.
+
+@c This node is named "Multi-call invocation", not the usual
+@c "coreutils invocation", so that shell commands like
+@c 'info coreutils "touch invocation"' work as expected.
+@node Multi-call invocation
+@section @command{coreutils}: Multi-call program
+
+@pindex multicall
+@cindex combined
+@cindex calling combined multi-call program
+
+The @command{coreutils} command invokes an individual utility, either
+implicitly selected by the last component of the name used to invoke
+@command{coreutils}, or explicitly with the
+@option{--coreutils-prog} option.  Synopsis:
+
+@example
+coreutils @option{--coreutils-prog=PROGRAM} @dots{}
+@end example
+
+The @command{coreutils} command is not installed by default, so
+portable scripts should not rely on its existence.
+
+@node Output of entire files
+@chapter Output of entire files
+
+@cindex output of entire files
+@cindex entire files, output of
+
+These commands read and write entire files, possibly transforming them
+in some way.
+
+@menu
+* cat invocation::              Concatenate and write files.
+* tac invocation::              Concatenate and write files in reverse.
+* nl invocation::               Number lines and write files.
+* od invocation::               Write files in octal or other formats.
+* base32 invocation::           Transform data into printable data.
+* base64 invocation::           Transform data into printable data.
+* basenc invocation::           Transform data into printable data.
+@end menu
+
+@node cat invocation
+@section @command{cat}: Concatenate and write files
+
+@pindex cat
+@cindex concatenate and write files
+@cindex copying files
+
+@command{cat} copies each @var{file} (@samp{-} means standard input), or
+standard input if none are given, to standard output.  Synopsis:
+
+@example
+cat [@var{option}] [@var{file}]@dots{}
+@end example
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -A
+@itemx --show-all
+@opindex -A
+@opindex --show-all
+Equivalent to @option{-vET}.
+
+@item -b
+@itemx --number-nonblank
+@opindex -b
+@opindex --number-nonblank
+Number all nonempty output lines, starting with 1.
+
+@item -e
+@opindex -e
+Equivalent to @option{-vE}.
+
+@item -E
+@itemx --show-ends
+@opindex -E
+@opindex --show-ends
+Display a @samp{$} after the end of each line.
+The @code{\r\n} combination is shown as @samp{^M$}.
+
+@item -n
+@itemx --number
+@opindex -n
+@opindex --number
+Number all output lines, starting with 1.  This option is ignored
+if @option{-b} is in effect.
+
+@item -s
+@itemx --squeeze-blank
+@opindex -s
+@opindex --squeeze-blank
+@cindex squeezing empty lines
+@cindex squeezing blank lines
+Suppress repeated adjacent blank lines; output just one empty line
+instead of several.
+
+@item -t
+@opindex -t
+Equivalent to @option{-vT}.
+
+@item -T
+@itemx --show-tabs
+@opindex -T
+@opindex --show-tabs
+Display TAB characters as @samp{^I}.
+
+@item -u
+@opindex -u
+Ignored; for POSIX compatibility.
+
+@item -v
+@itemx --show-nonprinting
+@opindex -v
+@opindex --show-nonprinting
+Display control characters except for LFD and TAB using
+@samp{^} notation and precede characters that have the high bit set with
+@samp{M-}.
+
+@end table
+
+On systems like MS-DOS that distinguish between text and binary files,
+@command{cat} normally reads and writes in binary mode.  However,
+@command{cat} reads in text mode if one of the options
+@option{-bensAE} is used or if @command{cat} is reading from standard
+input and standard input is a terminal.  Similarly, @command{cat}
+writes in text mode if one of the options @option{-bensAE} is used or
+if standard output is a terminal.
+
+@exitstatus
+
+Examples:
+
+@example
+# Output f's contents, then standard input, then g's contents.
+cat f - g
+
+# Copy standard input to standard output.
+cat
+@end example
+
+
+@node tac invocation
+@section @command{tac}: Concatenate and write files in reverse
+
+@pindex tac
+@cindex reversing files
+
+@command{tac} copies each @var{file} (@samp{-} means standard input), or
+standard input if none are given, to standard output, reversing the
+records (lines by default) in each separately.  Synopsis:
+
+@example
+tac [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@dfn{Records} are separated by instances of a string (newline by
+default).  By default, this separator string is attached to the end of
+the record that it follows in the file.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -b
+@itemx --before
+@opindex -b
+@opindex --before
+The separator is attached to the beginning of the record that it
+precedes in the file.
+
+@item -r
+@itemx --regex
+@opindex -r
+@opindex --regex
+Treat the separator string as a regular expression.
+
+@item -s @var{separator}
+@itemx --separator=@var{separator}
+@opindex -s
+@opindex --separator
+Use @var{separator} as the record separator, instead of newline.
+Note an empty @var{separator} is treated as a zero byte.
+I.e., input and output items are delimited with ASCII NUL.
+
+@end table
+
+On systems like MS-DOS that distinguish between text and binary files,
+@command{tac} reads and writes in binary mode.
+
+@exitstatus
+
+Example:
+
+@example
+# Reverse a file character by character.
+tac -r -s 'x\|[^x]'
+@end example
+
+
+@node nl invocation
+@section @command{nl}: Number lines and write files
+
+@pindex nl
+@cindex numbering lines
+@cindex line numbering
+
+@command{nl} writes each @var{file} (@samp{-} means standard input), or
+standard input if none are given, to standard output, with line numbers
+added to some or all of the lines.  Synopsis:
+
+@example
+nl [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@cindex logical pages, numbering on
+@command{nl} decomposes its input into (logical) page sections;
+by default, the line number is reset to 1 at each logical page section.
+@command{nl} treats all of the input files as a single document;
+it does not reset line numbers or logical pages between files.
+
+@cindex headers, numbering
+@cindex body, numbering
+@cindex footers, numbering
+A logical page consists of three sections: header, body, and footer.
+Any of the sections can be empty.  Each can be numbered in a different
+style from the others.
+
+The beginnings of the sections of logical pages are indicated in the
+input file by a line containing exactly one of these delimiter strings:
+
+@table @samp
+@item \:\:\:
+start of header;
+@item \:\:
+start of body;
+@item \:
+start of footer.
+@end table
+
+The characters from which these strings are made can be changed from
+@samp{\} and @samp{:} via options (see below), but the pattern
+of each string cannot be changed.
+
+A section delimiter is replaced by an empty line on output.  Any text
+that comes before the first section delimiter string in the input file
+is considered to be part of a body section, so @command{nl} treats a
+file that contains no section delimiters as a single body section.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -b @var{style}
+@itemx --body-numbering=@var{style}
+@opindex -b
+@opindex --body-numbering
+Select the numbering style for lines in the body section of each
+logical page.  When a line is not numbered, the current line number
+is not incremented, but the line number separator character is still
+prepended to the line.  The styles are:
+
+@table @samp
+@item a
+number all lines,
+@item t
+number only nonempty lines (default for body),
+@item n
+do not number lines (default for header and footer),
+@item p@var{bre}
+number only lines that contain a match for the basic regular
+expression @var{bre}.
+@xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}.
+@end table
+
+@item -d @var{cd}
+@itemx --section-delimiter=@var{cd}
+@opindex -d
+@opindex --section-delimiter
+@cindex section delimiters of pages
+Set the section delimiter characters to @var{cd}; default is
+@samp{\:}.  If only @var{c} is given, the second remains @samp{:}.
+As a GNU extension more than two characters can be specified,
+and also if @var{cd} is empty (@option{-d ''}), then section
+matching is disabled.
+(Remember to protect @samp{\} or other metacharacters from shell
+expansion with quotes or extra backslashes.)
+
+@item -f @var{style}
+@itemx --footer-numbering=@var{style}
+@opindex -f
+@opindex --footer-numbering
+Analogous to @option{--body-numbering}.
+
+@item -h @var{style}
+@itemx --header-numbering=@var{style}
+@opindex -h
+@opindex --header-numbering
+Analogous to @option{--body-numbering}.
+
+@item -i @var{number}
+@itemx --line-increment=@var{number}
+@opindex -i
+@opindex --line-increment
+Increment line numbers by @var{number} (default 1).
+@var{number} can be negative to decrement.
+
+@item -l @var{number}
+@itemx --join-blank-lines=@var{number}
+@opindex -l
+@opindex --join-blank-lines
+@cindex empty lines, numbering
+@cindex blank lines, numbering
+Consider @var{number} (default 1) consecutive empty lines to be one
+logical line for numbering, and only number the last one.  Where fewer
+than @var{number} consecutive empty lines occur, do not number them.
+An empty line is one that contains no characters, not even spaces
+or tabs.
+
+@item -n @var{format}
+@itemx --number-format=@var{format}
+@opindex -n
+@opindex --number-format
+Select the line numbering format (default is @code{rn}):
+
+@table @samp
+@item ln
+@opindex ln @r{format for @command{nl}}
+left justified, no leading zeros;
+@item rn
+@opindex rn @r{format for @command{nl}}
+right justified, no leading zeros;
+@item rz
+@opindex rz @r{format for @command{nl}}
+right justified, leading zeros.
+@end table
+
+@item -p
+@itemx --no-renumber
+@opindex -p
+@opindex --no-renumber
+Do not reset the line number at the start of a logical page.
+
+@item -s @var{string}
+@itemx --number-separator=@var{string}
+@opindex -s
+@opindex --number-separator
+Separate the line number from the text line in the output with
+@var{string} (default is the TAB character).
+
+@item -v @var{number}
+@itemx --starting-line-number=@var{number}
+@opindex -v
+@opindex --starting-line-number
+Set the initial line number on each logical page to @var{number} (default 1).
+The starting @var{number} can be negative.
+
+@item -w @var{number}
+@itemx --number-width=@var{number}
+@opindex -w
+@opindex --number-width
+Use @var{number} characters for line numbers (default 6).
+
+@end table
+
+@exitstatus
+
+
+@node od invocation
+@section @command{od}: Write files in octal or other formats
+
+@pindex od
+@cindex octal dump of files
+@cindex hex dump of files
+@cindex ASCII dump of files
+@cindex file contents, dumping unambiguously
+
+@command{od} writes an unambiguous representation of each @var{file}
+(@samp{-} means standard input), or standard input if none are given.
+Synopses:
+
+@example
+od [@var{option}]@dots{} [@var{file}]@dots{}
+od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]]
+od [@var{option}]@dots{} --traditional [@var{file}]@c
+ [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
+@end example
+
+Each line of output consists of the offset in the input, followed by
+groups of data from the file.  By default, @command{od} prints the offset in
+octal, and each group of file data is a C @code{short int}'s worth of input
+printed as a single octal number.
+
+If @var{offset} is given, it specifies how many input bytes to skip
+before formatting and writing.  By default, it is interpreted as an
+octal number, but the optional trailing decimal point causes it to be
+interpreted as decimal.  If no decimal is specified and the offset
+begins with @samp{0x} or @samp{0X} it is interpreted as a hexadecimal
+number.  If there is a trailing @samp{b}, the number of bytes skipped
+will be @var{offset} multiplied by 512.
+
+If a command is of both the first and second forms, the second form is
+assumed if the last operand begins with @samp{+} or (if there are two
+operands) a digit.  For example, in @samp{od foo 10} and @samp{od +10}
+the @samp{10} is an offset, whereas in @samp{od 10} the @samp{10} is a
+file name.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -A @var{radix}
+@itemx --address-radix=@var{radix}
+@opindex -A
+@opindex --address-radix
+@cindex radix for file offsets
+@cindex file offset radix
+Select the base in which file offsets are printed.  @var{radix} can
+be one of the following:
+
+@table @samp
+@item d
+decimal;
+@item o
+octal;
+@item x
+hexadecimal;
+@item n
+none (do not print offsets).
+@end table
+
+The default is octal.
+
+@item --endian=@var{order}
+@opindex --endian
+@cindex byte-swapping
+@cindex endianness
+Reorder input bytes, to handle inputs with differing byte orders,
+or to provide consistent output independent of the endian convention
+of the current system.  Swapping is performed according to the
+specified @option{--type} size and endian @var{order}, which can be
+@samp{little} or @samp{big}.
+
+@item -j @var{bytes}
+@itemx --skip-bytes=@var{bytes}
+@opindex -j
+@opindex --skip-bytes
+Skip @var{bytes} input bytes before formatting and writing.  If
+@var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in
+hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise,
+in decimal.
+@multiplierSuffixes{bytes}
+
+@item -N @var{bytes}
+@itemx --read-bytes=@var{bytes}
+@opindex -N
+@opindex --read-bytes
+Output at most @var{bytes} bytes of the input.  Prefixes and suffixes on
+@code{bytes} are interpreted as for the @option{-j} option.
+
+@item -S @var{bytes}
+@itemx --strings[=@var{bytes}]
+@opindex -S
+@opindex --strings
+@cindex string constants, outputting
+Instead of the normal output, output only @dfn{string constants}: at
+least @var{bytes} consecutive printable characters,
+followed by a zero byte (ASCII NUL).
+Prefixes and suffixes on @var{bytes} are interpreted as for the
+@option{-j} option.
+
+If @var{bytes} is omitted with @option{--strings}, the default is 3.
+
+@item -t @var{type}
+@itemx --format=@var{type}
+@opindex -t
+@opindex --format
+Select the format in which to output the file data.  @var{type} is a
+string of one or more of the below type indicator characters.  If you
+include more than one type indicator character in a single @var{type}
+string, or use this option more than once, @command{od} writes one copy
+of each output line using each of the data types that you specified,
+in the order that you specified.
+
+Adding a trailing ``z'' to any type specification appends a display
+of the single byte character representation of the printable characters
+to the output line generated by the type specification.
+
+@table @samp
+@item a
+named character, ignoring high-order bit
+@item c
+printable single byte character, C backslash escape
+or a 3 digit octal sequence
+@item d
+signed decimal
+@item f
+floating point (@pxref{Floating point})
+@item o
+octal
+@item u
+unsigned decimal
+@item x
+hexadecimal
+@end table
+
+The type @code{a} outputs things like @samp{sp} for space, @samp{nl} for
+newline, and @samp{nul} for a zero byte.  Only the least significant
+seven bits of each byte is used; the high-order bit is ignored.
+Type @code{c} outputs
+@samp{ }, @samp{\n}, and @code{\0}, respectively.
+
+@cindex type size
+Except for types @samp{a} and @samp{c}, you can specify the number
+of bytes to use in interpreting each number in the given data type
+by following the type indicator character with a decimal integer.
+Alternately, you can specify the size of one of the C compiler's
+built-in data types by following the type indicator character with
+one of the following characters.  For integers (@samp{d}, @samp{o},
+@samp{u}, @samp{x}):
+
+@table @samp
+@item C
+char
+@item S
+short
+@item I
+int
+@item L
+long
+@end table
+
+For floating point (@code{f}):
+
+@table @asis
+@item F
+float
+@item D
+double
+@item L
+long double
+@end table
+
+@item -v
+@itemx --output-duplicates
+@opindex -v
+@opindex --output-duplicates
+Output consecutive lines that are identical.  By default, when two or
+more consecutive output lines would be identical, @command{od} outputs only
+the first line, and puts just an asterisk on the following line to
+indicate the elision.
+
+@item -w[@var{n}]
+@itemx --width[=@var{n}]
+@opindex -w
+@opindex --width
+Dump @code{n} input bytes per output line.  This must be a multiple of
+the least common multiple of the sizes associated with the specified
+output types.
+
+If this option is not given at all, the default is 16.  If @var{n} is
+omitted, the default is 32.
+
+@end table
+
+The next several options are shorthands for format specifications.
+GNU @command{od} accepts any combination of shorthands and format
+specification options.  These options accumulate.
+
+@table @samp
+
+@item -a
+@opindex -a
+Output as named characters.  Equivalent to @samp{-t a}.
+
+@item -b
+@opindex -b
+Output as octal bytes.  Equivalent to @samp{-t o1}.
+
+@item -c
+@opindex -c
+Output as printable single byte characters, C backslash escapes
+or 3 digit octal sequences.  Equivalent to @samp{-t c}.
+
+@item -d
+@opindex -d
+Output as unsigned decimal two-byte units.  Equivalent to @samp{-t u2}.
+
+@item -f
+@opindex -f
+Output as floats.  Equivalent to @samp{-t fF}.
+
+@item -i
+@opindex -i
+Output as decimal ints.  Equivalent to @samp{-t dI}.
+
+@item -l
+@opindex -l
+Output as decimal long ints.  Equivalent to @samp{-t dL}.
+
+@item -o
+@opindex -o
+Output as octal two-byte units.  Equivalent to @option{-t o2}.
+
+@item -s
+@opindex -s
+Output as decimal two-byte units.  Equivalent to @option{-t d2}.
+
+@item -x
+@opindex -x
+Output as hexadecimal two-byte units.  Equivalent to @samp{-t x2}.
+
+@item --traditional
+@opindex --traditional
+Recognize the non-option label argument that traditional @command{od}
+accepted.  The following syntax:
+
+@example
+od --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]]
+@end example
+
+@noindent
+can be used to specify at most one file and optional arguments
+specifying an offset and a pseudo-start address, @var{label}.
+The @var{label} argument is interpreted
+just like @var{offset}, but it specifies an initial pseudo-address.  The
+pseudo-addresses are displayed in parentheses following any normal
+address.
+
+@end table
+
+@exitstatus
+
+
+@node base32 invocation
+@section @command{base32}: Transform data into printable data
+
+@pindex base32
+@cindex base32 encoding
+
+@command{base32} transforms data read from a file, or standard input,
+into (or from) base32 encoded form.  The base32 encoded form uses
+printable ASCII characters to represent binary data.
+The usage and options of this command are precisely the
+same as for @command{base64}.  @xref{base64 invocation}.
+For more general encoding functionality see @ref{basenc invocation}.
+
+
+@node base64 invocation
+@section @command{base64}: Transform data into printable data
+
+@pindex base64
+@cindex base64 encoding
+
+@command{base64} transforms data read from a file, or standard input,
+into (or from) base64 encoded form.  The base64 encoded form uses
+printable ASCII characters to represent binary data.
+Synopses:
+
+@example
+base64 [@var{option}]@dots{} [@var{file}]
+base64 --decode [@var{option}]@dots{} [@var{file}]
+@end example
+
+The base64 encoding expands data to roughly 133% of the original.
+The base32 encoding expands data to roughly 160% of the original.
+The format conforms to
+@uref{https://tools.ietf.org/search/rfc4648, RFC 4648}.
+
+For more general encoding functionality see @ref{basenc invocation}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -w @var{cols}
+@itemx --wrap=@var{cols}
+@opindex -w
+@opindex --wrap
+@cindex wrap data
+@cindex column to wrap data after
+During encoding, wrap lines after @var{cols} characters.  This must be
+a positive number.
+
+The default is to wrap after 76 characters.  Use the value 0 to
+disable line wrapping altogether.
+
+@item -d
+@itemx --decode
+@opindex -d
+@opindex --decode
+@cindex Decode base64 data
+@cindex Base64 decoding
+Change the mode of operation, from the default of encoding data, to
+decoding data.  Input is expected to be base64 encoded data, and the
+output will be the original data.
+
+@item -i
+@itemx --ignore-garbage
+@opindex -i
+@opindex --ignore-garbage
+@cindex Ignore garbage in base64 stream
+When decoding, newlines are always accepted.
+During decoding, ignore unrecognized bytes,
+to permit distorted data to be decoded.
+
+@end table
+
+@exitstatus
+
+@node basenc invocation
+@section @command{basenc}: Transform data into printable data
+
+@pindex basenc
+@cindex base32 encoding
+
+@command{basenc} transforms data read from a file, or standard input,
+into (or from) various common encoding forms.  The encoded form uses
+printable ASCII characters to represent binary data.
+
+Synopses:
+
+@example
+basenc @var{encoding} [@var{option}]@dots{} [@var{file}]
+basenc @var{encoding} --decode [@var{option}]@dots{} [@var{file}]
+@end example
+
+The @var{encoding} argument is required. If @var{file} is omitted,
+@command{basenc} reads from standard input.
+The @option{-w/--wrap},@option{-i/--ignore-garbage},
+@option{-d/--decode} options of this command are precisely the same as
+for @command{base64}. @xref{base64 invocation}.
+
+
+Supported @var{encoding}s are:
+
+@table @samp
+
+@item --base64
+@opindex --base64
+Encode into (or decode from with @option{-d/--decode}) base64 form.
+The format conforms to
+@uref{https://tools.ietf.org/search/rfc4648#section-4, RFC 4648#4}.
+Equivalent to the @command{base64} command.
+
+@item --base64url
+@opindex --base64url
+Encode into (or decode from with @option{-d/--decode}) file-and-url-safe
+base64 form (using @samp{_} and @samp{-} instead of @samp{+} and @samp{/}).
+The format conforms to
+@uref{https://tools.ietf.org/search/rfc4648#section-5, RFC 4648#5}.
+
+@item --base32
+@opindex --base32
+Encode into (or decode from with @option{-d/--decode}) base32 form.
+The encoded data uses the @samp{ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=} characters.
+The format conforms to
+@uref{https://tools.ietf.org/search/rfc4648#section-6, RFC 4648#6}.
+Equivalent to the @command{base32} command.
+
+@item --base32hex
+@opindex --base32hex
+Encode into (or decode from with @option{-d/--decode}) Extended Hex Alphabet
+base32 form. The encoded data uses the
+@samp{0123456789ABCDEFGHIJKLMNOPQRSTUV=} characters. The format conforms to
+@uref{https://tools.ietf.org/search/rfc4648#section-7, RFC 4648#7}.
+
+@item --base16
+@opindex --base16
+Encode into (or decode from with @option{-d/--decode}) base16 (hexadecimal)
+form. The encoded data uses the @samp{0123456789ABCDEF} characters. The format
+conforms to
+@uref{https://tools.ietf.org/search/rfc4648#section-8, RFC 4648#8}.
+
+@item --base2lsbf
+@opindex --base2lsbf
+Encode into (or decode from with @option{-d/--decode}) binary string form
+(@samp{0} and @samp{1}) with the @emph{least} significant bit of every byte
+first.
+
+@item --base2msbf
+@opindex --base2msbf
+Encode into (or decode from with @option{-d/--decode}) binary string form
+(@samp{0} and @samp{1}) with the @emph{most} significant bit of every byte
+first.
+
+@item --z85
+@opindex --z85
+Encode into (or decode from with @option{-d/--decode}) Z85 form
+(a modified Ascii85 form). The encoded data uses the
+@samp{0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU@
+VWXYZ.-:+=^!/*?&<>()[]@{@}@@%$#}.
+characters. The format conforms to
+@uref{https://rfc.zeromq.org/spec:32/Z85/, ZeroMQ spec:32/Z85}.
+
+When encoding with @option{--z85}, input length must be a multiple of 4;
+when decoding with @option{--z85}, input length must be a multiple of 5.
+
+@end table
+
+
+
+Encoding/decoding examples:
+
+@example
+$ printf '\376\117\202' | basenc --base64
+/k+C
+
+$ printf '\376\117\202' | basenc --base64url
+_k-C
+
+$ printf '\376\117\202' | basenc --base32
+7ZHYE===
+
+$ printf '\376\117\202' | basenc --base32hex
+VP7O4===
+
+$ printf '\376\117\202' | basenc --base16
+FE4F82
+
+$ printf '\376\117\202' | basenc --base2lsbf
+011111111111001001000001
+
+$ printf '\376\117\202' | basenc --base2msbf
+111111100100111110000010
+
+$ printf '\376\117\202\000' | basenc --z85
+@@.FaC
+
+$ printf 01010100 | basenc --base2msbf --decode
+T
+
+$ printf 01010100 | basenc --base2lsbf --decode
+*
+@end example
+
+
+
+@node Formatting file contents
+@chapter Formatting file contents
+
+@cindex formatting file contents
+
+These commands reformat the contents of files.
+
+@menu
+* fmt invocation::              Reformat paragraph text.
+* pr invocation::               Paginate or columnate files for printing.
+* fold invocation::             Wrap input lines to fit in specified width.
+@end menu
+
+
+@node fmt invocation
+@section @command{fmt}: Reformat paragraph text
+
+@pindex fmt
+@cindex reformatting paragraph text
+@cindex paragraphs, reformatting
+@cindex text, reformatting
+
+@command{fmt} fills and joins lines to produce output lines of (at most)
+a given number of characters (75 by default).  Synopsis:
+
+@example
+fmt [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@command{fmt} reads from the specified @var{file} arguments (or standard
+input if none are given), and writes to standard output.
+
+By default, blank lines, spaces between words, and indentation are
+preserved in the output; successive input lines with different
+indentation are not joined; tabs are expanded on input and introduced on
+output.
+
+@cindex line-breaking
+@cindex sentences and line-breaking
+@cindex Knuth, Donald E.
+@cindex Plass, Michael F.
+@command{fmt} prefers breaking lines at the end of a sentence, and tries to
+avoid line breaks after the first word of a sentence or before the last
+word of a sentence.  A @dfn{sentence break} is defined as either the end
+of a paragraph or a word ending in any of @samp{.?!}, followed by two
+spaces or end of line, ignoring any intervening parentheses or quotes.
+Like @TeX{}, @command{fmt} reads entire ``paragraphs'' before choosing line
+breaks; the algorithm is a variant of that given by Donald E. Knuth
+and Michael F. Plass in ``Breaking Paragraphs Into Lines'',
+@cite{Software: Practice & Experience} @b{11}, 11 (November 1981),
+1119--1184.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c
+@itemx --crown-margin
+@opindex -c
+@opindex --crown-margin
+@cindex crown margin
+@dfn{Crown margin} mode: preserve the indentation of the first two
+lines within a paragraph, and align the left margin of each subsequent
+line with that of the second line.
+
+@item -t
+@itemx --tagged-paragraph
+@opindex -t
+@opindex --tagged-paragraph
+@cindex tagged paragraphs
+@dfn{Tagged paragraph} mode: like crown margin mode, except that if
+indentation of the first line of a paragraph is the same as the
+indentation of the second, the first line is treated as a one-line
+paragraph.
+
+@item -s
+@itemx --split-only
+@opindex -s
+@opindex --split-only
+Split lines only.  Do not join short lines to form longer ones.  This
+prevents sample lines of code, and other such ``formatted'' text from
+being unduly combined.
+
+@item -u
+@itemx --uniform-spacing
+@opindex -u
+@opindex --uniform-spacing
+Uniform spacing.  Reduce spacing between words to one space, and spacing
+between sentences to two spaces.
+
+@item -@var{width}
+@itemx -w @var{width}
+@itemx --width=@var{width}
+@opindex -@var{width}
+@opindex -w
+@opindex --width
+Fill output lines up to @var{width} characters (default 75 or @var{goal}
+plus 10, if @var{goal} is provided).
+
+@item -g @var{goal}
+@itemx --goal=@var{goal}
+@opindex -g
+@opindex --goal
+@command{fmt} initially tries to make lines @var{goal} characters wide.
+By default, this is 7% shorter than @var{width}.
+
+@item -p @var{prefix}
+@itemx --prefix=@var{prefix}
+Only lines beginning with @var{prefix} (possibly preceded by whitespace)
+are subject to formatting.  The prefix and any preceding whitespace are
+stripped for the formatting and then re-attached to each formatted output
+line.  One use is to format certain kinds of program comments, while
+leaving the code unchanged.
+
+@end table
+
+@exitstatus
+
+@node pr invocation
+@section @command{pr}: Paginate or columnate files for printing
+
+@pindex pr
+@cindex printing, preparing files for
+@cindex multicolumn output, generating
+@cindex merging files in parallel
+
+@command{pr} writes each @var{file} (@samp{-} means standard input), or
+standard input if none are given, to standard output, paginating and
+optionally outputting in multicolumn format; optionally merges all
+@var{file}s, printing all in parallel, one per column.  Synopsis:
+
+@example
+pr [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@vindex LC_MESSAGES
+By default, a 5-line header is printed at each page: two blank lines;
+a line with the date, the file name, and the page count; and two more
+blank lines.  A footer of five blank lines is also printed.
+The default @var{page_length} is 66
+lines.  The default number of text lines is therefore 56.
+The text line of the header takes the form
+@samp{@var{date} @var{string} @var{page}}, with spaces inserted around
+@var{string} so that the line takes up the full @var{page_width}.  Here,
+@var{date} is the date (see the @option{-D} or @option{--date-format}
+option for details), @var{string} is the centered header string, and
+@var{page} identifies the page number.  The @env{LC_MESSAGES} locale
+category affects the spelling of @var{page}; in the default C locale, it
+is @samp{Page @var{number}} where @var{number} is the decimal page
+number.
+
+Form feeds in the input cause page breaks in the output.  Multiple form
+feeds produce empty pages.
+
+Columns are of equal width, separated by an optional string (default
+is @samp{space}).  For multicolumn output, lines will always be truncated to
+@var{page_width} (default 72), unless you use the @option{-J} option.
+For single
+column output no line truncation occurs by default.  Use @option{-W} option to
+truncate lines in that case.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item +@var{first_page}[:@var{last_page}]
+@itemx --pages=@var{first_page}[:@var{last_page}]
+@c The two following @opindex lines evoke warnings because they contain ':'
+@c The 'info' spec does not permit that.  If we use those lines, we end
+@c up with truncated index entries that don't work.
+@c @opindex +@var{first_page}[:@var{last_page}]
+@c @opindex --pages=@var{first_page}[:@var{last_page}]
+@opindex +@var{page_range}
+@opindex --pages=@var{page_range}
+Begin printing with page @var{first_page} and stop with @var{last_page}.
+Missing @samp{:@var{last_page}} implies end of file.  While estimating
+the number of skipped pages each form feed in the input file results
+in a new page.  Page counting with and without @samp{+@var{first_page}}
+is identical.  By default, counting starts with the first page of input
+file (not first page printed).  Line numbering may be altered by @option{-N}
+option.
+
+@item -@var{column}
+@itemx --columns=@var{column}
+@opindex -@var{column}
+@opindex --columns
+@cindex down columns
+With each single @var{file}, produce @var{column} columns of output
+(default is 1) and print columns down, unless @option{-a} is used.  The
+column width is automatically decreased as @var{column} increases; unless
+you use the @option{-W/-w} option to increase @var{page_width} as well.
+This option might well cause some lines to be truncated.  The number of
+lines in the columns on each page are balanced.  The options @option{-e}
+and @option{-i} are on for multiple text-column output.  Together with
+@option{-J} option column alignment and line truncation is turned off.
+Lines of full length are joined in a free field format and @option{-S}
+option may set field separators.  @option{-@var{column}} may not be used
+with @option{-m} option.
+
+@item -a
+@itemx --across
+@opindex -a
+@opindex --across
+@cindex across columns
+With each single @var{file}, print columns across rather than down.  The
+@option{-@var{column}} option must be given with @var{column} greater than one.
+If a line is too long to fit in a column, it is truncated.
+
+@item -c
+@itemx --show-control-chars
+@opindex -c
+@opindex --show-control-chars
+Print control characters using hat notation (e.g., @samp{^G}); print
+other nonprinting characters in octal backslash notation.  By default,
+nonprinting characters are not changed.
+
+@item -d
+@itemx --double-space
+@opindex -d
+@opindex --double-space
+@cindex double spacing
+Double space the output.
+
+@item -D @var{format}
+@itemx --date-format=@var{format}
+@cindex time formats
+@cindex formatting times
+Format header dates using @var{format}, using the same conventions as
+for the command @samp{date +@var{format}}.  @xref{date invocation}.
+Except for directives, which start with
+@samp{%}, characters in @var{format} are printed unchanged.  You can use
+this option to specify an arbitrary string in place of the header date,
+e.g., @option{--date-format="Monday morning"}.
+
+@vindex POSIXLY_CORRECT
+@vindex LC_TIME
+The default date format is @samp{%Y-%m-%d %H:%M} (for example,
+@samp{2020-07-09 23:59});
+but if the @env{POSIXLY_CORRECT} environment variable is set
+and the @env{LC_TIME} locale category specifies the POSIX
+locale, the default is @samp{%b %e %H:%M %Y} (for example,
+@samp{Jul@ @ 9 23:59 2020}.
+
+@vindex TZ
+Timestamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
+@env{TZ} is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
+
+@item -e[@var{in-tabchar}[@var{in-tabwidth}]]
+@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]]
+@opindex -e
+@opindex --expand-tabs
+@cindex input tabs
+Expand @var{tab}s to spaces on input.  Optional argument @var{in-tabchar} is
+the input tab character (default is the TAB character).  Second optional
+argument @var{in-tabwidth} is the input tab character's width (default
+is 8).
+
+@item -f
+@itemx -F
+@itemx --form-feed
+@opindex -F
+@opindex -f
+@opindex --form-feed
+Use a form feed instead of newlines to separate output pages.  This does
+not alter the default page length of 66 lines.
+
+@item -h @var{header}
+@itemx --header=@var{header}
+@opindex -h
+@opindex --header
+Replace the file name in the header with the centered string @var{header}.
+When using the shell, @var{header} should be quoted and should be
+separated from @option{-h} by a space.
+
+@item -i[@var{out-tabchar}[@var{out-tabwidth}]]
+@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]]
+@opindex -i
+@opindex --output-tabs
+@cindex output tabs
+Replace spaces with @var{tab}s on output.  Optional argument @var{out-tabchar}
+is the output tab character (default is the TAB character).  Second optional
+argument @var{out-tabwidth} is the output tab character's width (default
+is 8).
+
+@item -J
+@itemx --join-lines
+@opindex -J
+@opindex --join-lines
+Merge lines of full length.  Used together with the column options
+@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}.  Turns off
+@option{-W/-w} line truncation;
+no column alignment used; may be used with
+@option{--sep-string[=@var{string}]}.  @option{-J} has been introduced
+(together with @option{-W} and @option{--sep-string})
+to disentangle the old (POSIX-compliant) options @option{-w} and
+@option{-s} along with the three column options.
+
+
+@item -l @var{page_length}
+@itemx --length=@var{page_length}
+@opindex -l
+@opindex --length
+Set the page length to @var{page_length} (default 66) lines, including
+the lines of the header [and the footer].  If @var{page_length} is less
+than or equal to 10, the header and footer are omitted, as if the
+@option{-t} option had been given.
+
+@item -m
+@itemx --merge
+@opindex -m
+@opindex --merge
+Merge and print all @var{file}s in parallel, one in each column.  If a
+line is too long to fit in a column, it is truncated, unless the @option{-J}
+option is used.  @option{--sep-string[=@var{string}]} may be used.
+Empty pages in
+some @var{file}s (form feeds set) produce empty columns, still marked
+by @var{string}.  The result is a continuous line numbering and column
+marking throughout the whole merged file.  Completely empty merged pages
+show no separators or line numbers.  The default header becomes
+@samp{@var{date} @var{page}} with spaces inserted in the middle; this
+may be used with the @option{-h} or @option{--header} option to fill up
+the middle blank part.
+
+@item -n[@var{number-separator}[@var{digits}]]
+@itemx --number-lines[=@var{number-separator}[@var{digits}]]
+@opindex -n
+@opindex --number-lines
+Provide @var{digits} digit line numbering (default for @var{digits} is
+5).  With multicolumn output the number occupies the first @var{digits}
+column positions of each text column or only each line of @option{-m}
+output.  With single column output the number precedes each line just as
+@option{-m} does.  Default counting of the line numbers starts with the
+first line of the input file (not the first line printed, compare the
+@option{--page} option and @option{-N} option).
+Optional argument @var{number-separator} is the character appended to
+the line number to separate it from the text followed.  The default
+separator is the TAB character.  In a strict sense a TAB is always
+printed with single column output only.  The TAB width varies
+with the TAB position, e.g., with the left @var{margin} specified
+by @option{-o} option.  With multicolumn output priority is given to
+@samp{equal width of output columns} (a POSIX specification).
+The TAB width is fixed to the value of the first column and does
+not change with different values of left @var{margin}.  That means a
+fixed number of spaces is always printed in the place of the
+@var{number-separator} TAB@.  The tabification depends upon the output
+position.
+
+@item -N @var{line_number}
+@itemx --first-line-number=@var{line_number}
+@opindex -N
+@opindex --first-line-number
+Start line counting with the number @var{line_number} at first line of
+first page printed (in most cases not the first line of the input file).
+
+@item -o @var{margin}
+@itemx --indent=@var{margin}
+@opindex -o
+@opindex --indent
+@cindex indenting lines
+@cindex left margin
+Indent each line with a margin @var{margin} spaces wide (default is zero).
+The total page width is the size of the margin plus the @var{page_width}
+set with the @option{-W/-w} option.  A limited overflow may occur with
+numbered single column output (compare @option{-n} option).
+
+@item -r
+@itemx --no-file-warnings
+@opindex -r
+@opindex --no-file-warnings
+Do not print a warning message when an argument @var{file} cannot be
+opened.  (The exit status will still be nonzero, however.)
+
+@item -s[@var{char}]
+@itemx --separator[=@var{char}]
+@opindex -s
+@opindex --separator
+Separate columns by a single character @var{char}.  The default for
+@var{char} is the TAB character without @option{-w} and @samp{no
+character} with @option{-w}.  Without @option{-s} the default separator
+@samp{space} is set.  @option{-s[char]} turns off line truncation of all
+three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless
+@option{-w} is set.  This is a POSIX-compliant formulation.
+
+
+@item -S[@var{string}]
+@itemx --sep-string[=@var{string}]
+@opindex -S
+@opindex --sep-string
+Use @var{string} to separate output columns.  The @option{-S} option doesn't
+affect the @option{-W/-w} option, unlike the @option{-s} option which does.  It
+does not affect line truncation or column alignment.
+Without @option{-S}, and with @option{-J}, @command{pr} uses the default output
+separator, TAB@.
+Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space}
+(same as @option{-S"@w{ }"}).
+If no @samp{@var{string}} argument is specified, @samp{""} is assumed.
+
+@item -t
+@itemx --omit-header
+@opindex -t
+@opindex --omit-header
+Do not print the usual header [and footer] on each page, and do not fill
+out the bottom of pages (with blank lines or a form feed).  No page
+structure is produced, but form feeds set in the input files are retained.
+The predefined pagination is not changed.  @option{-t} or @option{-T} may be
+useful together with other options; e.g.: @option{-t -e4}, expand TAB characters
+in the input file to 4 spaces but don't make any other changes.  Use of
+@option{-t} overrides @option{-h}.
+
+@item -T
+@itemx --omit-pagination
+@opindex -T
+@opindex --omit-pagination
+Do not print header [and footer].  In addition eliminate all form feeds
+set in the input files.
+
+@item -v
+@itemx --show-nonprinting
+@opindex -v
+@opindex --show-nonprinting
+Print nonprinting characters in octal backslash notation.
+
+@item -w @var{page_width}
+@itemx --width=@var{page_width}
+@opindex -w
+@opindex --width
+Set page width to @var{page_width} characters for multiple text-column
+output only (default for @var{page_width} is 72).  The specified
+@var{page_width} is rounded down so that columns have equal width.
+@option{-s[CHAR]} turns off the default page width and any line truncation
+and column alignment.
+Lines of full length are merged, regardless of the column options
+set.  No @var{page_width} setting is possible with single column output.
+A POSIX-compliant formulation.
+
+@item -W @var{page_width}
+@itemx --page_width=@var{page_width}
+@opindex -W
+@opindex --page_width
+Set the page width to @var{page_width} characters, honored with and
+without a column option.  With a column option, the specified @var{page_width}
+is rounded down so that columns have equal width.  Text lines are truncated,
+unless @option{-J} is used. Together with one of the three column options
+(@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column
+alignment is always used.  The separator options @option{-S} or @option{-s}
+don't disable the @option{-W} option.  Default is 72 characters.  Without
+@option{-W @var{page_width}} and without any of the column options NO line
+truncation is used (defined to keep downward compatibility and to meet
+most frequent tasks).  That's equivalent to @option{-W 72 -J}@.  The header
+line is never truncated.
+
+@end table
+
+@exitstatus
+
+
+@node fold invocation
+@section @command{fold}: Wrap input lines to fit in specified width
+
+@pindex fold
+@cindex wrapping long input lines
+@cindex folding long input lines
+
+@command{fold} writes each @var{file} (@option{-} means standard input), or
+standard input if none are given, to standard output, breaking long
+lines.  Synopsis:
+
+@example
+fold [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+By default, @command{fold} breaks lines wider than 80 columns.  The output
+is split into as many lines as necessary.
+
+@cindex screen columns
+@command{fold} counts screen columns by default; thus, a tab may count more
+than one column, backspace decreases the column count, and carriage
+return sets the column to zero.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -b
+@itemx --bytes
+@opindex -b
+@opindex --bytes
+Count bytes rather than columns, so that tabs, backspaces, and carriage
+returns are each counted as taking up one column, just like other
+characters.
+
+@item -s
+@itemx --spaces
+@opindex -s
+@opindex --spaces
+Break at word boundaries: the line is broken after the last blank before
+the maximum line length.  If the line contains no such blanks, the line
+is broken at the maximum line length as usual.
+
+@item -w @var{width}
+@itemx --width=@var{width}
+@opindex -w
+@opindex --width
+Use a maximum line length of @var{width} columns instead of 80.
+
+For compatibility @command{fold} supports an obsolete option syntax
+@option{-@var{width}}.  New scripts should use @option{-w @var{width}}
+instead.
+
+@end table
+
+@exitstatus
+
+
+@node Output of parts of files
+@chapter Output of parts of files
+
+@cindex output of parts of files
+@cindex parts of files, output of
+
+These commands output pieces of the input.
+
+@menu
+* head invocation::             Output the first part of files.
+* tail invocation::             Output the last part of files.
+* split invocation::            Split a file into pieces.
+* csplit invocation::           Split a file into context-determined pieces.
+@end menu
+
+@node head invocation
+@section @command{head}: Output the first part of files
+
+@pindex head
+@cindex initial part of files, outputting
+@cindex first part of files, outputting
+
+@command{head} prints the first part (10 lines by default) of each
+@var{file}; it reads from standard input if no files are given or
+when given a @var{file} of @option{-}.  Synopsis:
+
+@example
+head [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+If more than one @var{file} is specified, @command{head} prints a
+one-line header consisting of:
+
+@example
+==> @var{file name} <==
+@end example
+
+@noindent
+before the output for each @var{file}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c [-]@var{num}
+@itemx --bytes=[-]@var{num}
+@opindex -c
+@opindex --bytes
+Print the first @var{num} bytes, instead of initial lines.
+However, if @var{num} is prefixed with a @samp{-},
+print all but the last @var{num} bytes of each file.
+@multiplierSuffixes{num}
+
+@item -n [-]@var{num}
+@itemx --lines=[-]@var{num}
+@opindex -n
+@opindex --lines
+Output the first @var{num} lines.
+However, if @var{num} is prefixed with a @samp{-},
+print all but the last @var{num} lines of each file.
+Size multiplier suffixes are the same as with the @option{-c} option.
+
+@item -q
+@itemx --quiet
+@itemx --silent
+@opindex -q
+@opindex --quiet
+@opindex --silent
+Never print file name headers.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Always print file name headers.
+
+@optZeroTerminated
+
+@end table
+
+For compatibility @command{head} also supports an obsolete option syntax
+@option{-[@var{num}][bkm][cqv]}, which is recognized only if it is
+specified first.  @var{num} is a decimal number optionally followed
+by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or
+@samp{l} to mean count by lines, or other option letters (@samp{cqv}).
+Scripts intended for standard hosts should use @option{-c @var{num}}
+or @option{-n @var{num}} instead.  If your script must also run on
+hosts that support only the obsolete syntax, it is usually simpler to
+avoid @command{head}, e.g., by using @samp{sed 5q} instead of
+@samp{head -5}.
+
+@exitstatus
+
+
+@node tail invocation
+@section @command{tail}: Output the last part of files
+
+@pindex tail
+@cindex last part of files, outputting
+
+@command{tail} prints the last part (10 lines by default) of each
+@var{file}; it reads from standard input if no files are given or
+when given a @var{file} of @samp{-}.  Synopsis:
+
+@example
+tail [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+If more than one @var{file} is specified, @command{tail} prints a
+one-line header before the output for each @var{file}, consisting of:
+
+@example
+==> @var{file name} <==
+@end example
+
+For further processing of tail output, it can be useful to convert the
+file headers to line prefixes, which can be done like:
+
+@example
+tail @dots{} |
+awk '
+  /^==> .* <==$/ @{prefix=substr($0,5,length-8)":"; next@}
+  @{print prefix$0@}
+' | @dots{}
+@end example
+
+@cindex BSD @command{tail}
+GNU @command{tail} can output any amount of data (some other versions of
+@command{tail} cannot).  It also has no @option{-r} option (print in
+reverse), since reversing a file is really a different job from printing
+the end of a file; BSD @command{tail} (which is the one with @option{-r}) can
+only reverse files that are at most as large as its buffer, which is
+typically 32 KiB@.  A more reliable and versatile way to reverse files is
+the GNU @command{tac} command.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c [+]@var{num}
+@itemx --bytes=[+]@var{num}
+@opindex -c
+@opindex --bytes
+Output the last @var{num} bytes, instead of final lines.
+If @var{num} is prefixed with a @samp{+}, start printing with
+byte @var{num} from the start of each file. For example to skip the first byte
+use @code{tail -c +2}, while to skip all but the last byte use @code{tail -c 1}.
+@multiplierSuffixes{num}
+
+@item -f
+@itemx --follow[=@var{how}]
+@opindex -f
+@opindex --follow
+@cindex growing files
+@vindex name @r{follow option}
+@vindex descriptor @r{follow option}
+Loop forever trying to read more characters at the end of the file,
+presumably because the file is growing.
+If more than one file is given, @command{tail} prints a header whenever it
+gets output from a different file, to indicate which file that output is
+from.
+
+There are two ways to specify how you'd like to track files with this option,
+but that difference is noticeable only when a followed file is removed or
+renamed.
+If you'd like to continue to track the end of a growing file even after
+it has been unlinked, use @option{--follow=descriptor}.  This is the default
+behavior, but it is not useful if you're tracking a log file that may be
+rotated (removed or renamed, then reopened).  In that case, use
+@option{--follow=name} to track the named file, perhaps by reopening it
+periodically to see if it has been removed and recreated by some other program.
+Note that the inotify-based implementation handles this case without
+the need for any periodic reopening.
+
+No matter which method you use, if the tracked file is determined to have
+shrunk, @command{tail} prints a message saying the file has been truncated
+and resumes tracking from the start of the file, assuming it has been
+truncated to 0, which is the usual truncation operation for log files.
+
+When a file is removed, @command{tail}'s behavior depends on whether it is
+following the name or the descriptor.  When following by name, tail can
+detect that a file has been removed and gives a message to that effect,
+and if @option{--retry} has been specified it will continue checking
+periodically to see if the file reappears.
+When following a descriptor, tail does not detect that the file has
+been unlinked or renamed and issues no message;  even though the file
+may no longer be accessible via its original name, it may still be
+growing.
+
+The option values @samp{descriptor} and @samp{name} may be specified only
+with the long form of the option, not with @option{-f}.
+
+The @option{-f} option is ignored if
+no @var{file} operand is specified and standard input is a FIFO or a pipe.
+Likewise, the @option{-f} option has no effect for any
+operand specified as @samp{-}, when standard input is a FIFO or a pipe.
+
+With kernel inotify support, output is triggered by file changes
+and is generally very prompt.
+Otherwise, @command{tail} sleeps for one second between checks --
+use @option{--sleep-interval=@var{n}} to change that default -- which can
+make the output appear slightly less responsive or bursty.
+When using tail without inotify support, you can make it more responsive
+by using a sub-second sleep interval, e.g., via an alias like this:
+
+@example
+alias tail='tail -s.1'
+@end example
+
+@item -F
+@opindex -F
+This option is the same as @option{--follow=name --retry}.  That is, tail
+will attempt to reopen a file when it is removed.  Should this fail, tail
+will keep trying until it becomes accessible again.
+
+@item --max-unchanged-stats=@var{n}
+@opindex --max-unchanged-stats
+When tailing a file by name, if there have been @var{n} (default
+n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive
+iterations for which the file has not changed, then
+@code{open}/@code{fstat} the file to determine if that file name is
+still associated with the same device/inode-number pair as before.
+When following a log file that is rotated, this is approximately the
+number of seconds between when tail prints the last pre-rotation lines
+and when it prints the lines that have accumulated in the new log file.
+This option is meaningful only when polling (i.e., without inotify)
+and when following by name.
+
+@item -n [+]@var{num}
+@itemx --lines=[+]@var{}
+@opindex -n
+@opindex --lines
+Output the last @var{num} lines.
+If @var{num} is prefixed with a @samp{+}, start printing with
+line @var{num} from the start of each file. For example to skip the first line
+use @code{tail -n +2}, while to skip all but the last line use @code{tail -n 1}.
+Size multiplier suffixes are the same as with the @option{-c} option.
+
+@item --pid=@var{pid}
+@opindex --pid
+When following by name or by descriptor, you may specify the process ID,
+@var{pid}, of the sole writer of all @var{file} arguments.  Then, shortly
+after that process terminates, tail will also terminate.  This will
+work properly only if the writer and the tailing process are running on
+the same machine.  For example, to save the output of a build in a file
+and to watch the file grow, if you invoke @command{make} and @command{tail}
+like this then the tail process will stop when your build completes.
+Without this option, you would have had to kill the @code{tail -f}
+process yourself.
+
+@example
+$ make >& makerr & tail --pid=$! -f makerr
+@end example
+
+If you specify a @var{pid} that is not in use or that does not correspond
+to the process that is writing to the tailed files, then @command{tail}
+may terminate long before any @var{file}s stop growing or it may not
+terminate until long after the real writer has terminated.
+Note that @option{--pid} cannot be supported on some systems; @command{tail}
+will print a warning if this is the case.
+
+@item -q
+@itemx --quiet
+@itemx --silent
+@opindex -q
+@opindex --quiet
+@opindex --silent
+Never print file name headers.
+
+@item --retry
+@opindex --retry
+Indefinitely try to open the specified file.
+This option is useful mainly when following (and otherwise issues a warning).
+
+When following by file descriptor (i.e., with @option{--follow=descriptor}),
+this option only affects the initial open of the file, as after a successful
+open, @command{tail} will start following the file descriptor.
+
+When following by name (i.e., with @option{--follow=name}), @command{tail}
+infinitely retries to re-open the given files until killed.
+
+Without this option, when @command{tail} encounters a file that doesn't
+exist or is otherwise inaccessible, it reports that fact and
+never checks it again.
+
+@item -s @var{number}
+@itemx --sleep-interval=@var{number}
+@opindex -s
+@opindex --sleep-interval
+Change the number of seconds to wait between iterations (the default is 1.0).
+During one iteration, every specified file is checked to see if it has
+changed size.
+When @command{tail} uses inotify, this polling-related option
+is usually ignored.  However, if you also specify @option{--pid=@var{p}},
+@command{tail} checks whether process @var{p} is alive at least
+every @var{number} seconds.
+The @var{number} must be non-negative and can be a floating-point number
+in either the current or the C locale.  @xref{Floating point}.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Always print file name headers.
+
+@optZeroTerminated
+
+@end table
+
+For compatibility @command{tail} also supports an obsolete usage
+@samp{tail -[@var{num}][bcl][f] [@var{file}]}, which is recognized
+only if it does not conflict with the usage described
+above.  This obsolete form uses exactly one option and at most one
+file.  In the option, @var{num} is an optional decimal number optionally
+followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count
+by 512-byte blocks, bytes, or lines, optionally followed by @samp{f}
+which has the same meaning as @option{-f}.
+
+@vindex _POSIX2_VERSION
+On systems not conforming to POSIX 1003.1-2001, the leading @samp{-}
+can be replaced by @samp{+} in the traditional option syntax with the
+same meaning as in counts, and on obsolete systems predating POSIX
+1003.1-2001 traditional usage overrides normal usage when the two
+conflict.  This behavior can be controlled with the
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
+conformance}).
+
+Scripts intended for use on standard hosts should avoid traditional
+syntax and should use @option{-c @var{num}[b]}, @option{-n
+@var{num}}, and/or @option{-f} instead.  If your script must also
+run on hosts that support only the traditional syntax, you can often
+rewrite it to avoid problematic usages, e.g., by using @samp{sed -n
+'$p'} rather than @samp{tail -1}.  If that's not possible, the script
+can use a test like @samp{if tail -c +1 </dev/null >/dev/null 2>&1;
+then @dots{}} to decide which syntax to use.
+
+Even if your script assumes the standard behavior, you should still
+beware usages whose behaviors differ depending on the POSIX
+version.  For example, avoid @samp{tail - main.c}, since it might be
+interpreted as either @samp{tail main.c} or as @samp{tail -- -
+main.c}; avoid @samp{tail -c 4}, since it might mean either @samp{tail
+-c4} or @samp{tail -c 10 4}; and avoid @samp{tail +4}, since it might
+mean either @samp{tail ./+4} or @samp{tail -n +4}.
+
+@exitstatus
+
+
+@node split invocation
+@section @command{split}: Split a file into pieces.
+
+@pindex split
+@cindex splitting a file into pieces
+@cindex pieces, splitting a file into
+
+@command{split} creates output files containing consecutive or interleaved
+sections of @var{input}  (standard input if none is given or @var{input}
+is @samp{-}).  Synopsis:
+
+@example
+split [@var{option}] [@var{input} [@var{prefix}]]
+@end example
+
+By default, @command{split} puts 1000 lines of @var{input} (or whatever is
+left over for the last section), into each output file.
+
+@cindex output file name prefix
+The output files' names consist of @var{prefix} (@samp{x} by default)
+followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by
+default), such that concatenating the output files in traditional
+sorted order by file name produces the original input file (except
+@option{-nr/@var{n}}).  By default split will initially create files
+with two generated suffix characters, and will increase this width by two
+when the next most significant position reaches the last character.
+(@samp{yz}, @samp{zaaa}, @samp{zaab}, @dots{}).  In this way an arbitrary
+number of output files are supported, which sort as described above,
+even in the presence of an @option{--additional-suffix} option.
+If the @option{-a} option is specified and the output file names are
+exhausted, @command{split} reports an error without deleting the
+output files that it did create.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -l @var{lines}
+@itemx --lines=@var{lines}
+@opindex -l
+@opindex --lines
+Put @var{lines} lines of @var{input} into each output file.
+If @option{--separator} is specified, then @var{lines} determines
+the number of records.
+
+For compatibility @command{split} also supports an obsolete
+option syntax @option{-@var{lines}}.  New scripts should use
+@option{-l @var{lines}} instead.
+
+@item -b @var{size}
+@itemx --bytes=@var{size}
+@opindex -b
+@opindex --bytes
+Put @var{size} bytes of @var{input} into each output file.
+@multiplierSuffixes{size}
+
+@item -C @var{size}
+@itemx --line-bytes=@var{size}
+@opindex -C
+@opindex --line-bytes
+Put into each output file as many complete lines of @var{input} as
+possible without exceeding @var{size} bytes.  Individual lines or records
+longer than @var{size} bytes are broken into multiple files.
+@var{size} has the same format as for the @option{--bytes} option.
+If @option{--separator} is specified, then @var{lines} determines
+the number of records.
+
+@item --filter=@var{command}
+@opindex --filter
+With this option, rather than simply writing to each output file,
+write through a pipe to the specified shell @var{command} for each output file.
+@var{command} should use the $FILE environment variable, which is set
+to a different output file name for each invocation of the command.
+For example, imagine that you have a 1TiB compressed file
+that, if uncompressed, would be too large to reside on secondary storage,
+yet you must split it into individually-compressed pieces
+of a more manageable size.
+To do that, you might run this command:
+
+@example
+xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big-
+@end example
+
+Assuming a 10:1 compression ratio, that would create about fifty 20GiB files
+with names @file{big-aa.xz}, @file{big-ab.xz}, @file{big-ac.xz}, etc.
+
+@item -n @var{chunks}
+@itemx --number=@var{chunks}
+@opindex -n
+@opindex --number
+
+Split @var{input} to @var{chunks} output files where @var{chunks} may be:
+
+@example
+@var{n}      generate @var{n} files based on current size of @var{input}
+@var{k}/@var{n}    output only @var{k}th of @var{n} to standard output
+l/@var{n}    generate @var{n} files without splitting lines or records
+l/@var{k}/@var{n}  likewise but output only @var{k}th of @var{n} to stdout
+r/@var{n}    like @samp{l} but use round robin distribution
+r/@var{k}/@var{n}  likewise but output only @var{k}th of @var{n} to stdout
+@end example
+
+If the input size is not a multiple of @var{n}, early output files are
+one byte longer than later output files, to make up the difference.
+Any excess bytes appearing after the initial calculation are discarded
+(except when using @samp{r} mode).
+
+All @var{n} files are created even if there are fewer than @var{n} lines,
+or the @var{input} is truncated.
+
+For @samp{l} mode, chunks are approximately @var{input} size / @var{n}.
+Although the @var{input} is still partitioned as before into @var{n} regions
+of approximately equal size, if a line @emph{starts} within a partition
+it is written completely to the corresponding file.  Since lines or records
+are not split even if they overlap a partition, the files written
+can be larger or smaller than the partition size, and even empty
+if a line/record is so long as to completely overlap the partition.
+
+When the input is a pipe or some other special file where the size
+cannot easily be determined, there is no trouble for @samp{r} mode
+because the size of the input is irrelevant.  For other modes, such an
+input is first copied to a temporary to determine its size.
+
+@item -a @var{length}
+@itemx --suffix-length=@var{length}
+@opindex -a
+@opindex --suffix-length
+Use suffixes of length @var{length}.  If a @var{length} of 0 is specified,
+this is the same as if (any previous) @option{-a} was not specified, and
+thus enables the default behavior, which starts the suffix length at 2,
+and unless @option{-n} or @option{--numeric-suffixes=@var{from}} is
+specified, will auto increase the length by 2 as required.
+
+@item -d
+@itemx --numeric-suffixes[=@var{from}]
+@opindex -d
+@opindex --numeric-suffixes
+Use digits in suffixes rather than lower-case letters.  The numerical
+suffix counts from @var{from} if specified, 0 otherwise.
+
+@var{from} is supported with the long form option, and is used to either set the
+initial suffix for a single run, or to set the suffix offset for independently
+split inputs, and consequently the auto suffix length expansion described above
+is disabled.  Therefore you may also want to use option @option{-a} to allow
+suffixes beyond @samp{99}.  Note if option @option{--number} is specified and
+the number of files is less than @var{from}, a single run is assumed and the
+minimum suffix length required is automatically determined.
+
+@item -x
+@itemx --hex-suffixes[=@var{from}]
+@opindex -x
+@opindex --hex-suffixes
+Like @option{--numeric-suffixes}, but use hexadecimal numbers (in lower case).
+
+@item --additional-suffix=@var{suffix}
+@opindex --additional-suffix
+Append an additional @var{suffix} to output file names.  @var{suffix}
+must not contain slash.
+
+@item -e
+@itemx --elide-empty-files
+@opindex -e
+@opindex --elide-empty-files
+Suppress the generation of zero-length output files.  This can happen
+with the @option{--number} option if a file is (truncated to be) shorter
+than the number requested, or if a line is so long as to completely
+span a chunk.  The output file sequence numbers, always run consecutively
+even when this option is specified.
+
+@item -t @var{separator}
+@itemx --separator=@var{separator}
+@opindex -t
+@opindex --separator
+@cindex line separator character
+@cindex record separator character
+Use character @var{separator} as the record separator instead of the default
+newline character (ASCII LF).
+To specify ASCII NUL as the separator, use the two-character string @samp{\0},
+e.g., @samp{split -t '\0'}.
+
+@item -u
+@itemx --unbuffered
+@opindex -u
+@opindex --unbuffered
+Immediately copy input to output in @option{--number r/@dots{}} mode,
+which is a much slower mode of operation.
+
+@item --verbose
+@opindex --verbose
+Write a diagnostic just before each output file is opened.
+
+@end table
+
+@exitstatus
+
+Here are a few examples to illustrate how the
+@option{--number} (@option{-n}) option works:
+
+Notice how, by default, one line may be split onto two or more:
+
+@example
+$ seq -w 6 10 > k; split -n3 k; head xa?
+==> xaa <==
+06
+07
+==> xab <==
+
+08
+0
+==> xac <==
+9
+10
+@end example
+
+Use the "l/" modifier to suppress that:
+
+@example
+$ seq -w 6 10 > k; split -nl/3 k; head xa?
+==> xaa <==
+06
+07
+
+==> xab <==
+08
+09
+
+==> xac <==
+10
+@end example
+
+Use the "r/" modifier to distribute lines in a round-robin fashion:
+
+@example
+$ seq -w 6 10 > k; split -nr/3 k; head xa?
+==> xaa <==
+06
+09
+
+==> xab <==
+07
+10
+
+==> xac <==
+08
+@end example
+
+You can also extract just the Kth chunk.
+This extracts and prints just the 7th "chunk" of 33:
+
+@example
+$ seq 100 > k; split -nl/7/33 k
+20
+21
+22
+@end example
+
+
+@node csplit invocation
+@section @command{csplit}: Split a file into context-determined pieces
+
+@pindex csplit
+@cindex context splitting
+@cindex splitting a file into pieces by context
+
+@command{csplit} creates zero or more output files containing sections of
+@var{input} (standard input if @var{input} is @samp{-}).  Synopsis:
+
+@example
+csplit [@var{option}]@dots{} @var{input} @var{pattern}@dots{}
+@end example
+
+The contents of the output files are determined by the @var{pattern}
+arguments, as detailed below.  An error occurs if a @var{pattern}
+argument refers to a nonexistent line of the input file (e.g., if no
+remaining line matches a given regular expression).  After every
+@var{pattern} has been matched, any remaining input is copied into one
+last output file.
+
+By default, @command{csplit} prints the number of bytes written to each
+output file after it has been created.
+
+The types of pattern arguments are:
+
+@table @samp
+
+@item @var{n}
+Create an output file containing the input up to but not including line
+@var{n} (a positive integer).  If followed by a repeat count, also
+create an output file containing the next @var{n} lines of the input
+file once for each repeat.
+
+@item /@var{regexp}/[@var{offset}]
+Create an output file containing the current line up to (but not
+including) the next line of the input file that contains a match for
+@var{regexp}.  The optional @var{offset} is an integer, that can
+be preceded by @samp{+} or @samp{-}.
+If it is given, the input up to (but not including) the
+matching line plus or minus @var{offset} is put into the output file,
+and the line after that begins the next section of input.
+Note lines within a negative offset of a regexp pattern
+are not matched in subsequent regexp patterns.
+
+@item %@var{regexp}%[@var{offset}]
+Like the previous type, except that it does not create an output
+file, so that section of the input file is effectively ignored.
+
+@item @{@var{repeat-count}@}
+Repeat the previous pattern @var{repeat-count} additional
+times.  The @var{repeat-count} can either be a positive integer or an
+asterisk, meaning repeat as many times as necessary until the input is
+exhausted.
+
+@end table
+
+The output files' names consist of a prefix (@samp{xx} by default)
+followed by a suffix.  By default, the suffix is an ascending sequence
+of two-digit decimal numbers from @samp{00} to @samp{99}.  In any case,
+concatenating the output files in sorted order by file name produces the
+original input file, excluding portions skipped with a %@var{regexp}%
+pattern or the @option{--suppress-matched} option.
+
+By default, if @command{csplit} encounters an error or receives a hangup,
+interrupt, quit, or terminate signal, it removes any output files
+that it has created so far before it exits.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -f @var{prefix}
+@itemx --prefix=@var{prefix}
+@opindex -f
+@opindex --prefix
+@cindex output file name prefix
+Use @var{prefix} as the output file name prefix.
+
+@item -b @var{format}
+@itemx --suffix-format=@var{format}
+@opindex -b
+@opindex --suffix-format
+@cindex output file name suffix
+Use @var{format} as the output file name suffix.  When this option is
+specified, the suffix string must include exactly one
+@code{printf(3)}-style conversion specification, possibly including
+format specification flags, a field width, a precision specification,
+or all of these kinds of modifiers.  The format letter must convert a
+binary unsigned integer argument to readable form.  The format letters
+@samp{d} and @samp{i} are aliases for @samp{u}, and the
+@samp{u}, @samp{o}, @samp{x}, and @samp{X} conversions are allowed.  The
+entire @var{format} is given (with the current output file number) to
+@code{sprintf(3)} to form the file name suffixes for each of the
+individual output files in turn.  If this option is used, the
+@option{--digits} option is ignored.
+
+@item -n @var{digits}
+@itemx --digits=@var{digits}
+@opindex -n
+@opindex --digits
+Use output file names containing numbers that are @var{digits} digits
+long instead of the default 2.
+
+@item -k
+@itemx --keep-files
+@opindex -k
+@opindex --keep-files
+Do not remove output files when errors are encountered.
+
+@item --suppress-matched
+@opindex --suppress-matched
+Do not output lines matching the specified @var{pattern}.
+I.e., suppress the boundary line from the start of the second
+and subsequent splits.
+
+@item -z
+@itemx --elide-empty-files
+@opindex -z
+@opindex --elide-empty-files
+Suppress the generation of zero-length output files.  (In cases where
+the section delimiters of the input file are supposed to mark the first
+lines of each of the sections, the first output file will generally be a
+zero-length file unless you use this option.)  The output file sequence
+numbers always run consecutively starting from 0, even when this option
+is specified.
+
+@item -s
+@itemx -q
+@itemx --silent
+@itemx --quiet
+@opindex -s
+@opindex -q
+@opindex --silent
+@opindex --quiet
+Do not print counts of output file sizes.
+
+@end table
+
+@exitstatus
+
+Here is an example of its usage.
+First, create an empty directory for the exercise,
+and cd into it:
+
+@example
+$ mkdir d && cd d
+@end example
+
+Now, split the sequence of 1..14 on lines that end with 0 or 5:
+
+@example
+$ seq 14 | csplit - '/[05]$/' '@{*@}'
+8
+10
+15
+@end example
+
+Each number printed above is the size of an output
+file that csplit has just created.
+List the names of those output files:
+
+@example
+$ ls
+xx00  xx01  xx02
+@end example
+
+Use @command{head} to show their contents:
+
+@example
+$ head xx*
+==> xx00 <==
+1
+2
+3
+4
+
+==> xx01 <==
+5
+6
+7
+8
+9
+
+==> xx02 <==
+10
+11
+12
+13
+14
+@end example
+
+Example of splitting input by empty lines:
+
+@example
+$ csplit --suppress-matched @var{input.txt} '/^$/' '@{*@}'
+@end example
+
+@c
+@c TODO: "uniq" already supports "--group".
+@c        when it gets the "--key" option, uncomment this example.
+@c
+@c Example of splitting input file, based on the value of column 2:
+@c
+@c @example
+@c $ cat @var{input.txt} |
+@c       sort -k2,2 |
+@c       uniq --group -k2,2 |
+@c       csplit -m '/^$/' '@{*@}'
+@c @end example
+
+@node Summarizing files
+@chapter Summarizing files
+
+@cindex summarizing files
+
+These commands generate just a few numbers representing entire
+contents of files.
+
+@menu
+* wc invocation::               Print newline, word, and byte counts.
+* sum invocation::              Print checksum and block counts.
+* cksum invocation::            Print CRC checksum and byte counts.
+* md5sum invocation::           Print or check MD5 digests.
+* b2sum invocation::            Print or check BLAKE2 digests.
+* sha1sum invocation::          Print or check SHA-1 digests.
+* sha2 utilities::              Print or check SHA-2 digests.
+@end menu
+
+
+@node wc invocation
+@section @command{wc}: Print newline, word, and byte counts
+
+@pindex wc
+@cindex byte count
+@cindex character count
+@cindex word count
+@cindex line count
+
+@command{wc} counts the number of bytes, characters, words, and newlines
+in each given @var{file}, or standard input if none are given
+or for a @var{file} of @samp{-}.  A word is a nonzero length
+sequence of printable characters delimited by white space.  Synopsis:
+
+@example
+wc [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@cindex total counts
+@command{wc} prints one line of counts for each file, and if the file was
+given as an argument, it prints the file name following the counts. By default
+if more than one @var{file} is given, @command{wc} prints a final line
+containing the cumulative counts, with the file name @file{total}.
+This @samp{total} line can be controlled with the @option{--total} option,
+which is a GNU extension.
+The counts are printed in this order: newlines, words, characters, bytes,
+maximum line length.
+Each count is printed right-justified in a field with at least one
+space between fields so that the numbers and file names normally line
+up nicely in columns.  The width of the count fields varies depending
+on the inputs, so you should not depend on a particular field width.
+However, as a GNU extension, if only one count is printed,
+it is guaranteed to be printed without leading spaces.
+
+By default, @command{wc} prints three counts: the newline, words, and byte
+counts.  Options can specify that only certain counts be printed.
+Options do not undo others previously given, so
+
+@example
+wc --bytes --words
+@end example
+
+@noindent
+prints both the byte counts and the word counts.
+
+With the @option{--max-line-length} option, @command{wc} prints the length
+of the longest line per file, and if there is more than one file it
+prints the maximum (not the sum) of those lengths.  The line lengths here
+are measured in screen columns, according to the current locale and
+assuming tab positions in every 8th column.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c
+@itemx --bytes
+@opindex -c
+@opindex --bytes
+Print only the byte counts.
+
+@item -m
+@itemx --chars
+@opindex -m
+@opindex --chars
+Print only the character counts, as per the current locale.
+Invalid characters are not counted.
+
+@item -w
+@itemx --words
+@opindex -w
+@opindex --words
+Print only the word counts.  A word is a nonzero length
+sequence of printable characters separated by white space.
+
+@item -l
+@itemx --lines
+@opindex -l
+@opindex --lines
+Print only the newline character counts.
+Note a file without a trailing newline character,
+will not have that last portion included in the line count.
+
+@item -L
+@itemx --max-line-length
+@opindex -L
+@opindex --max-line-length
+Print only the maximum display widths.
+Tabs are set at every 8th column.
+Display widths of wide characters are considered.
+Non-printable characters are given 0 width.
+
+@item --total=@var{when}
+@opindex --total=@var{when}
+Control when and how the final line with cumulative counts is printed.
+@var{when} is one of:
+@itemize @bullet
+@item auto
+@vindex auto @r{total option}
+- This is the default mode of @command{wc} when no @option{--total}
+option is specified.  Output a total line if more than one @var{file}
+is specified.
+@item always
+@vindex always @r{total option}
+- Always output a total line, irrespective of the number of files processed.
+@item only
+@vindex only @r{total option}
+- Only output total counts.  I.e., don't print individual file counts,
+suppress any leading spaces, and don't print the @samp{total} word itself,
+to simplify subsequent processing.
+@item never
+@vindex none @r{total option}
+- Never output a total line.
+@end itemize
+
+@macro filesZeroFromOption{cmd,withTotalOption,subListOutput}
+@item --files0-from=@var{file}
+@opindex --files0-from=@var{file}
+@c This is commented out to avoid a texi2dvi failure.
+@c texi2dvi (GNU Texinfo 4.11) 1.104
+@c @cindex including files from @command{\cmd\}
+Disallow processing files named on the command line, and instead process
+those named in file @var{file}; each name being terminated by a zero byte
+(ASCII NUL).
+This is useful \withTotalOption\
+when the list of file names is so long that it may exceed a command line
+length limitation.
+In such cases, running @command{\cmd\} via @command{xargs} is undesirable
+because it splits the list into pieces and makes @command{\cmd\} print
+\subListOutput\ for each sublist rather than for the entire list.
+One way to produce a list of ASCII NUL terminated file
+names is with GNU
+@command{find}, using its @option{-print0} predicate.
+If @var{file} is @samp{-} then the ASCII NUL terminated
+file names are read from standard input.
+@end macro
+@filesZeroFromOption{wc,,a total}
+
+For example, to find the length of the longest line in any @file{.c} or
+@file{.h} file in the current hierarchy, do this:
+
+@example
+find . -name '*.[ch]' -print0 |
+  wc -L --files0-from=- | tail -n1
+@end example
+
+@end table
+
+@exitstatus
+
+
+@node sum invocation
+@section @command{sum}: Print checksum and block counts
+
+@pindex sum
+@cindex 16-bit checksum
+@cindex checksum, 16-bit
+
+@command{sum} computes a 16-bit checksum for each given @var{file}, or
+standard input if none are given or for a @var{file} of @samp{-}.  Synopsis:
+
+@example
+sum [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@command{sum} prints the checksum for each @var{file} followed by the
+number of blocks in the file (rounded up).  If at least one @var{file}
+is given, file names are also printed.
+
+By default, GNU @command{sum} computes checksums using an algorithm
+compatible with BSD @command{sum} and prints file sizes in units of
+1024-byte blocks.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -r
+@opindex -r
+@cindex BSD @command{sum}
+Use the default (BSD compatible) algorithm.  This option is included for
+compatibility with the System V @command{sum}.  Unless @option{-s} was also
+given, it has no effect.
+
+@item -s
+@itemx --sysv
+@opindex -s
+@opindex --sysv
+@cindex System V @command{sum}
+Compute checksums using an algorithm compatible with System V
+@command{sum}'s default, and print file sizes in units of 512-byte blocks.
+
+@end table
+
+@command{sum} is provided for compatibility; the @command{cksum} program (see
+next section) is preferable in new applications.
+
+@exitstatus
+
+
+@node cksum invocation
+@section @command{cksum}: Print and verify file checksums
+
+@pindex cksum
+@cindex cyclic redundancy check
+@cindex CRC checksum
+@cindex 32-bit checksum
+@cindex checksum, 32-bit
+@cindex digest
+
+@command{cksum} by default computes a 32-bit cyclic redundancy check (CRC)
+checksum for each given @var{file}, or standard input if none are given or for
+a @var{file} of @samp{-}.
+
+cksum also supports the @option{-a/--algorithm} option to select the
+digest algorithm to use. @command{cksum} is the preferred interface
+to these digests, subsuming the other standalone checksumming utilities,
+which can be emulated using @code{cksum -a md5 --untagged "$@@"} etc.
+Synopsis:
+
+@example
+cksum [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@command{cksum} is typically used to ensure that files have not been corrupted,
+by comparing the @command{cksum} output for the received files with the
+@command{cksum} output for the original files (typically given in the
+distribution).
+
+@menu
+* cksum output modes::          Legacy and non Legacy output formats
+* cksum general options::       Options supported only by cksum
+* cksum common options::        Options supported also by standalone utilities
+@end menu
+
+@node cksum output modes
+
+@table @asis
+
+@item Legacy output format
+@command{cksum} by default prints the POSIX standard CRC checksum
+for each file along with the number of bytes in the file,
+and the file name unless no arguments were given.
+The 32-bit CRC used is based on the polynomial used
+for CRC error checking in the ISO/IEC 8802-3:1996 standard (Ethernet).
+Similar output formats are used for the other legacy checksums
+selectable with @option{--algorithm=sysv} or @option{--algorithm=bsd},
+detailed at @ref{sum invocation}.
+
+@item Tagged output format
+With the @option{--algorithm} option selecting non legacy checksums,
+the @command{cksum} command defaults to output of the form:
+@example
+@var{digest_name} (@var{file name}) = @var{digest}
+@end example
+Note the standalone checksum utilities can select this output
+mode by using the @option{--tag} option.
+
+@item Untagged output format
+With the @option{--untagged} option and the @option{--algorithm} option
+selecting non legacy checksums, the following output format is used.
+Note this is the default output format of the standalone checksum utilities.
+For each @var{file}, we print the checksum, a space, a flag indicating
+binary or text input mode, and the file name.
+Binary mode is indicated with @samp{*}, text mode with @samp{ } (space).
+Binary mode is the default on systems where it's significant,
+otherwise text mode is the default.
+
+@end table
+
+Note without @option{--zero}, and with non legacy output formats,
+if @var{file} contains a backslash, newline, or carriage return,
+the line is started with a backslash, and each problematic character
+in the file name is escaped with a backslash, making the output unambiguous
+even in the presence of arbitrary file names.
+Since the backslash character itself is escaped, any other backslash
+escape sequences are reserved for future use.
+
+@node cksum general options
+@table @samp
+
+@item -a
+@itemx --algorithm
+@opindex -a
+@opindex --algorithm
+@cindex digest algorithm
+Compute checksums using the specified digest algorithm.
+
+Supported legacy checksums (which are not supported by @option{--check}):
+@example
+@samp{sysv}      equivalent to @command{sum -s}
+@samp{bsd}       equivalent to @command{sum -r}
+@samp{crc}       equivalent to @command{cksum} (the default)
+@end example
+
+Supported more modern digest algorithms are:
+@example
+@samp{md5}       equivalent to @command{md5sum}
+@samp{sha1}      equivalent to @command{sha1sum}
+@samp{sha224}    equivalent to @command{sha224sum}
+@samp{sha256}    equivalent to @command{sha256sum}
+@samp{sha384}    equivalent to @command{sha384sum}
+@samp{sha512}    equivalent to @command{sha512sum}
+@samp{blake2b}   equivalent to @command{b2sum}
+@samp{sm3}       only available through @command{cksum}
+@end example
+
+@item --base64
+@opindex --base64
+@cindex base64 checksum encoding
+Print base64-encoded digests not hexadecimal.
+This option is ignored with @option{--check}.
+The format conforms to
+@uref{https://tools.ietf.org/search/rfc4648#section-4, RFC 4648#4}.
+
+Note that each base64-encoded digest has zero, one or two trailing padding
+(@samp{=}) bytes.  The length of that padding is the checksum-bit-length
+modulo 3, and the @option{--check} parser requires precisely the same
+input digest string as what is output.  I.e., removing or adding any
+@samp{=} padding renders a digest non-matching.
+
+@item --debug
+@opindex --debug
+Output extra information to stderr, like the checksum implementation being used.
+
+@macro cksumLengthOption
+@item -l
+@itemx --length
+@opindex -l
+@opindex --length
+@cindex BLAKE2 hash length
+Change (shorten) the default digest length.
+This is specified in bits and thus must be a multiple of 8.
+This option is ignored when @option{--check} is specified,
+as the length is automatically determined when checking.
+@end macro
+@cksumLengthOption
+
+@item --raw
+@opindex --raw
+@cindex raw binary checksum
+Print only the unencoded raw binary digest for a single input.
+Do not output the file name or anything else.
+Use network byte order (big endian) where applicable:
+for @samp{bsd}, @samp{crc}, and @samp{sysv}.
+This option works only with a single input.
+Unlike other output formats, @command{cksum} provides no way to
+@option{--check} a @option{--raw} checksum.
+
+@item --untagged
+@opindex --untagged
+Output using the original Coreutils format used by the other
+standalone checksum utilities like @command{md5sum} for example.
+This format has the checksum at the start of the line, and may be
+more amenable to further processing by other utilities,
+especially in combination with the @option{--zero} option.
+Note this does not identify the digest algorithm used for the checksum.
+@xref{cksum output modes} for details of this format.
+@end table
+
+@node cksum common options
+@table @samp
+
+@item -b
+@itemx --binary
+@opindex -b
+@opindex --binary
+@cindex binary input files
+Note this option is not supported by the @command{cksum} command,
+as it operates in binary mode exclusively.
+Treat each input file as binary, by reading it in binary mode and
+outputting a @samp{*} flag.  This is the inverse of @option{--text}.
+On systems like GNU that do not distinguish between binary
+and text files, this option merely flags each input mode as binary:
+the checksum is unaffected.  This option is the default on systems
+like MS-DOS that distinguish between binary and text files, except
+for reading standard input when standard input is a terminal.
+
+@item -c
+@itemx --check
+Read file names and checksum information (not data) from each
+@var{file} (or from standard input if no @var{file} was specified) and report
+whether the checksums match the contents of the named files.
+The input to this mode is usually the output of
+a prior, checksum-generating run of the command.
+
+Three input formats are supported.  Either the default output
+format described above, the @option{--tag} output format,
+or the BSD reversed mode format which is similar to the default mode,
+but doesn't use a character to distinguish binary and text modes.
+
+For the @command{cksum} command, the @option{--check} option
+supports auto-detecting the digest algorithm to use,
+when presented with checksum information in the @option{--tag} output format.
+
+Also for the @command{cksum} command, the @option{--check} option
+auto-detects the digest encoding, accepting both standard hexadecimal
+checksums and those generated via @command{cksum} with its
+@option{--base64} option.
+
+Output with @option{--zero} enabled is not supported by @option{--check}.
+@sp 1
+For each such line, @command{cksum} reads the named file and computes its
+checksum.  Then, if the computed message digest does not match the
+one on the line with the file name, the file is noted as having
+failed the test.  Otherwise, the file passes the test.
+By default, for each valid line, one line is written to standard
+output indicating whether the named file passed the test.
+After all checks have been performed, if there were any failures,
+a warning is issued to standard error.
+Use the @option{--status} option to inhibit that output.
+If any listed file cannot be opened or read, if any valid line has
+a checksum inconsistent with the associated file, or if no valid
+line is found, @command{cksum} exits with nonzero status.  Otherwise,
+it exits successfully.
+Note the @command{cksum} command doesn't support @option{--check}
+with the older @samp{sysv}, @samp{bsd}, or @samp{crc} algorithms.
+
+@item --ignore-missing
+@opindex --ignore-missing
+@cindex verifying checksums
+This option is useful only when verifying checksums.
+When verifying checksums, don't fail or report any status
+for missing files.  This is useful when verifying a subset
+of downloaded files given a larger list of checksums.
+
+@item --quiet
+@opindex --quiet
+@cindex verifying checksums
+This option is useful only when verifying checksums.
+When verifying checksums, don't generate an 'OK' message per successfully
+checked file.  Files that fail the verification are reported in the
+default one-line-per-file format.  If there is any checksum mismatch,
+print a warning summarizing the failures to standard error.
+
+@item --status
+@opindex --status
+@cindex verifying checksums
+This option is useful only when verifying checksums.
+When verifying checksums, don't generate the default one-line-per-file
+diagnostic and don't output the warning summarizing any failures.
+Failures to open or read a file still evoke individual diagnostics to
+standard error.
+If all listed files are readable and are consistent with the associated
+checksums, exit successfully.  Otherwise exit with a status code
+indicating there was a failure.
+
+@item --tag
+@opindex --tag
+@cindex BSD output
+Output BSD style checksums, which indicate the checksum algorithm used.
+As a GNU extension, if @option{--zero} is not used, file names with problematic
+characters are escaped as described above, using the same escaping indicator of
+@samp{\} at the start of the line, as used with the other output format.
+The @option{--tag} option implies binary mode, and is disallowed with
+@option{--text} mode as supporting that would unnecessarily complicate
+the output format, while providing little benefit.
+@xref{cksum output modes} for details of this format.
+The @command{cksum} command, uses @option{--tag} as its default output format.
+
+@item -t
+@itemx --text
+@opindex -t
+@opindex --text
+@cindex text input files
+Note this option is not supported by the @command{cksum} command.
+Treat each input file as text, by reading it in text mode and
+outputting a @samp{ } flag.  This is the inverse of @option{--binary}.
+This option is the default on systems like GNU that do not
+distinguish between binary and text files.  On other systems, it is
+the default for reading standard input when standard input is a
+terminal.  This mode is never defaulted to if @option{--tag} is used.
+
+@item -w
+@itemx --warn
+@opindex -w
+@opindex --warn
+@cindex verifying checksums
+When verifying checksums, warn about improperly formatted checksum lines.
+This option is useful only if all but a few lines in the checked input
+are valid.
+
+@item --strict
+@opindex --strict
+@cindex verifying checksums
+When verifying checksums,
+if one or more input line is invalid,
+exit nonzero after all warnings have been issued.
+
+@optZero
+Also file name escaping is not used.
+@end table
+
+@node md5sum invocation
+@section @command{md5sum}: Print or check MD5 digests
+
+@pindex md5sum
+@cindex MD5
+@cindex 128-bit checksum
+@cindex checksum, 128-bit
+@cindex fingerprint, 128-bit
+@cindex message-digest, 128-bit
+
+@command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or
+@dfn{message-digest}) for each specified @var{file}.
+
+@macro weakHash{hash}
+Note: The \hash\ digest is more reliable than a simple CRC (provided by
+the @command{cksum} command) for detecting accidental file corruption,
+as the chances of accidentally having two files with identical \hash\
+are vanishingly small.  However, it should not be considered secure
+against malicious tampering: although finding a file with a given \hash\
+fingerprint is considered infeasible at the moment, it is known how
+to modify certain files, including digital certificates, so that they
+appear valid when signed with an \hash\ digest.  For more secure hashes,
+consider using SHA-2, or the newer @command{b2sum} command.
+@xref{sha2 utilities}. @xref{b2sum invocation}.
+@end macro
+@weakHash{MD5}
+
+@macro checksumUsage{command}
+If a @var{file} is specified as @samp{-} or if no files are given
+@command{\command\} computes the checksum for the standard input.
+@command{\command\} can also determine whether a file and checksum are
+consistent.  Synopsis:
+
+@example
+\command\ [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@command{\command\} uses the @samp{Untagged output format}
+for each specified file, as described at @ref{cksum output modes}.
+
+The program accepts @ref{cksum common options}.  Also see @ref{Common options}.
+@end macro
+@checksumUsage{md5sum}
+
+@exitstatus
+
+
+@node b2sum invocation
+@section @command{b2sum}: Print or check BLAKE2 digests
+
+@pindex b2sum
+@cindex BLAKE2
+@cindex 512-bit checksum
+@cindex checksum, 512-bit
+@cindex fingerprint, 512-bit
+@cindex message-digest, 512-bit
+
+@command{b2sum} computes a 512-bit checksum for each specified
+@var{file}.
+
+@checksumUsage{b2sum}
+
+In addition @command{b2sum} supports the following options.
+
+@table @samp
+@cksumLengthOption
+@end table
+
+
+@node sha1sum invocation
+@section @command{sha1sum}: Print or check SHA-1 digests
+
+@pindex sha1sum
+@cindex SHA-1
+@cindex 160-bit checksum
+@cindex checksum, 160-bit
+@cindex fingerprint, 160-bit
+@cindex message-digest, 160-bit
+
+@command{sha1sum} computes a 160-bit checksum for each specified @var{file}.
+
+@weakHash{SHA-1}
+
+@checksumUsage{sha1sum}
+
+@node sha2 utilities
+@section sha2 utilities: Print or check SHA-2 digests
+
+@pindex sha224sum
+@pindex sha256sum
+@pindex sha384sum
+@pindex sha512sum
+@cindex SHA-2
+@cindex 224-bit checksum
+@cindex 256-bit checksum
+@cindex 384-bit checksum
+@cindex 512-bit checksum
+@cindex checksum, 224-bit
+@cindex checksum, 256-bit
+@cindex checksum, 384-bit
+@cindex checksum, 512-bit
+@cindex fingerprint, 224-bit
+@cindex fingerprint, 256-bit
+@cindex fingerprint, 384-bit
+@cindex fingerprint, 512-bit
+@cindex message-digest, 224-bit
+@cindex message-digest, 256-bit
+@cindex message-digest, 384-bit
+@cindex message-digest, 512-bit
+
+The commands @command{sha224sum}, @command{sha256sum},
+@command{sha384sum} and @command{sha512sum} compute checksums of
+various lengths (respectively 224, 256, 384 and 512 bits),
+collectively known as the SHA-2 hashes.
+
+@checksumUsage{sha???sum}
+
+
+@node Operating on sorted files
+@chapter Operating on sorted files
+
+@cindex operating on sorted files
+@cindex sorted files, operations on
+
+These commands work with (or produce) sorted files.
+
+@menu
+* sort invocation::             Sort text files.
+* shuf invocation::             Shuffle text files.
+* uniq invocation::             Uniquify files.
+* comm invocation::             Compare two sorted files line by line.
+* ptx invocation::              Produce a permuted index of file contents.
+* tsort invocation::            Topological sort.
+@end menu
+
+
+@node sort invocation
+@section @command{sort}: Sort text files
+
+@pindex sort
+@cindex sorting files
+
+@command{sort} sorts, merges, or compares all the lines from the given
+files, or standard input if none are given or for a @var{file} of
+@samp{-}.  By default, @command{sort} writes the results to standard
+output.  Synopsis:
+
+@example
+sort [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@cindex sort stability
+@cindex sort's last-resort comparison
+Many options affect how @command{sort} compares lines; if the results
+are unexpected, try the @option{--debug} option to see what happened.
+A pair of lines is compared as follows:
+@command{sort} compares each pair of fields (see @option{--key}), in the
+order specified on the command line, according to the associated
+ordering options, until a difference is found or no fields are left.
+If no key fields are specified, @command{sort} uses a default key of
+the entire line.  Finally, as a last resort when all keys compare
+equal, @command{sort} compares entire lines as if no ordering options
+other than @option{--reverse} (@option{-r}) were specified.  The
+@option{--stable} (@option{-s}) option disables this @dfn{last-resort
+comparison} so that lines in which all fields compare equal are left
+in their original relative order.  The @option{--unique}
+(@option{-u}) option also disables the last-resort comparison.
+@vindex LC_ALL
+@vindex LC_COLLATE
+
+Unless otherwise specified, all comparisons use the character collating
+sequence specified by the @env{LC_COLLATE} locale.@footnote{If you
+use a non-POSIX locale (e.g., by setting @env{LC_ALL}
+to @samp{en_US}), then @command{sort} may produce output that is sorted
+differently than you're accustomed to.  In that case, set the @env{LC_ALL}
+environment variable to @samp{C}@.  Note that setting only @env{LC_COLLATE}
+has two problems.  First, it is ineffective if @env{LC_ALL} is also set.
+Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if
+@env{LC_CTYPE} is unset) is set to an incompatible value.  For example,
+you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but
+@env{LC_COLLATE} is @code{en_US.UTF-8}.}
+A line's trailing newline is not part of the line for comparison
+purposes.  If the final byte of an input file is not a newline, GNU
+@command{sort} silently supplies one.  GNU @command{sort} (as
+specified for all GNU utilities) has no limit on input line length or
+restrictions on bytes allowed within lines.
+
+@command{sort} has three modes of operation: sort (the default), merge,
+and check for order.  The following options change the operation
+mode:
+
+@table @samp
+
+@item -c
+@itemx --check
+@itemx --check=diagnose-first
+@opindex -c
+@opindex --check
+@cindex checking whether a file is sorted
+Check whether the given file is already sorted: if it is not all
+sorted, print a diagnostic containing the first out-of-order line and
+exit with a status of 1.
+Otherwise, exit successfully.
+At most one input file can be given.
+
+@item -C
+@itemx --check=quiet
+@itemx --check=silent
+@opindex -c
+@opindex --check
+@cindex checking whether a file is sorted
+Exit successfully if the given file is already sorted, and
+exit with status 1 otherwise.
+At most one input file can be given.
+This is like @option{-c}, except it does not print a diagnostic.
+
+@item -m
+@itemx --merge
+@opindex -m
+@opindex --merge
+@cindex merging sorted files
+Merge the given files by sorting them as a group.  Each input file must
+always be individually sorted.  It always works to sort instead of
+merge; merging is provided because it is faster, in the case where it
+works.
+
+@end table
+
+@cindex exit status of @command{sort}
+Exit status:
+
+@display
+0 if no error occurred
+1 if invoked with @option{-c} or @option{-C} and the input is not sorted
+2 if an error occurred
+@end display
+
+@vindex TMPDIR
+If the environment variable @env{TMPDIR} is set, @command{sort} uses its
+value as the directory for temporary files instead of @file{/tmp}.  The
+@option{--temporary-directory} (@option{-T}) option in turn overrides
+the environment variable.
+
+The following options affect the ordering of output lines.  They may be
+specified globally or as part of a specific key field.  If no key
+fields are specified, global options apply to comparison of entire
+lines; otherwise the global options are inherited by key fields that do
+not specify any special options of their own.  In pre-POSIX
+versions of @command{sort}, global options affect only later key fields,
+so portable shell scripts should specify global options first.
+
+@table @samp
+
+@item -b
+@itemx --ignore-leading-blanks
+@opindex -b
+@opindex --ignore-leading-blanks
+@cindex blanks, ignoring leading
+@vindex LC_CTYPE
+Ignore leading blanks when finding sort keys in each line.
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
+can change this.  Note blanks may be ignored by your locale's collating
+rules, but without this option they will be significant for character
+positions specified in keys with the @option{-k} option.
+
+@item -d
+@itemx --dictionary-order
+@opindex -d
+@opindex --dictionary-order
+@cindex dictionary order
+@cindex phone directory order
+@cindex telephone directory order
+@vindex LC_CTYPE
+Sort in @dfn{phone directory} order: ignore all characters except
+letters, digits and blanks when sorting.
+By default letters and digits are those of ASCII and a blank
+is a space or a tab, but the @env{LC_CTYPE} locale can change this.
+
+@item -f
+@itemx --ignore-case
+@opindex -f
+@opindex --ignore-case
+@cindex ignoring case
+@cindex case folding
+@vindex LC_CTYPE
+Fold lowercase characters into the equivalent uppercase characters when
+comparing so that, for example, @samp{b} and @samp{B} sort as equal.
+The @env{LC_CTYPE} locale determines character types.
+When used with @option{--unique} those lower case equivalent lines are
+thrown away.  (There is currently no way to throw away the upper case
+equivalent instead.  (Any @option{--reverse} given would only affect
+the final result, after the throwing away.))
+
+@item -g
+@itemx --general-numeric-sort
+@itemx --sort=general-numeric
+@opindex -g
+@opindex --general-numeric-sort
+@opindex --sort
+@cindex general numeric sort
+@vindex LC_NUMERIC
+Sort numerically, converting a prefix of each line to a long
+double-precision floating point number.  @xref{Floating point}.
+Do not report overflow, underflow, or conversion errors.
+Use the following collating sequence:
+
+@itemize @bullet
+@item
+Lines that do not start with numbers (all considered to be equal).
+@item
+NaNs (``Not a Number'' values, in IEEE floating point arithmetic)
+in a consistent but machine-dependent order.
+@item
+Minus infinity.
+@item
+Finite numbers in ascending numeric order (with @math{-0} and @math{+0} equal).
+@item
+Plus infinity.
+@end itemize
+
+Use this option only if there is no alternative; it is much slower than
+@option{--numeric-sort} (@option{-n}) and it can lose information when
+converting to floating point.
+
+You can use this option to sort hexadecimal numbers prefixed with
+@samp{0x} or @samp{0X}, where those numbers are not fixed width,
+or of varying case.  However for hex numbers of consistent case,
+and left padded with @samp{0} to a consistent width, a standard
+lexicographic sort will be faster.
+
+@item -h
+@itemx --human-numeric-sort
+@itemx --sort=human-numeric
+@opindex -h
+@opindex --human-numeric-sort
+@opindex --sort
+@cindex human numeric sort
+@vindex LC_NUMERIC
+Sort numerically, first by numeric sign (negative, zero, or positive);
+then by SI suffix (either empty, or @samp{k} or @samp{K}, or
+one of @samp{MGTPEZYRQ}, in that order; @pxref{Block size}); and finally
+by numeric value.  For example, @samp{1023M} sorts before @samp{1G}
+because @samp{M} (mega) precedes @samp{G} (giga) as an SI
+suffix.  This option sorts values that are consistently scaled to the
+nearest suffix, regardless of whether suffixes denote powers of 1000
+or 1024, and it therefore sorts the output of any single invocation of
+the @command{df}, @command{du}, or @command{ls} commands that are
+invoked with their @option{--human-readable} or @option{--si} options.
+The syntax for numbers is the same as for the @option{--numeric-sort}
+option; the SI suffix must immediately follow the number.
+Note also the @command{numfmt} command, which can be used to reformat
+numbers to human format @emph{after} the sort, thus often allowing
+sort to operate on more accurate numbers.
+
+@item -i
+@itemx --ignore-nonprinting
+@opindex -i
+@opindex --ignore-nonprinting
+@cindex nonprinting characters, ignoring
+@cindex unprintable characters, ignoring
+@vindex LC_CTYPE
+Ignore nonprinting characters.
+The @env{LC_CTYPE} locale determines character types.
+This option has no effect if the stronger @option{--dictionary-order}
+(@option{-d}) option is also given.
+
+@item -M
+@itemx --month-sort
+@itemx --sort=month
+@opindex -M
+@opindex --month-sort
+@opindex --sort
+@cindex months, sorting by
+@vindex LC_TIME
+An initial string, consisting of any amount of blanks, followed
+by a month name abbreviation, is folded to UPPER case and
+compared in the order @samp{JAN} < @samp{FEB} < @dots{} < @samp{DEC}@.
+Invalid names compare low to valid names.  The @env{LC_TIME} locale
+category determines the month spellings.
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
+can change this.
+
+@item -n
+@itemx --numeric-sort
+@itemx --sort=numeric
+@opindex -n
+@opindex --numeric-sort
+@opindex --sort
+@cindex numeric sort
+@vindex LC_NUMERIC
+Sort numerically.  The number begins each line and consists
+of optional blanks, an optional @samp{-} sign, and zero or more
+digits possibly separated by thousands separators, optionally followed
+by a decimal-point character and zero or more digits.  An empty
+number is treated as @samp{0}.  The @env{LC_NUMERIC}
+locale specifies the decimal-point character and thousands separator.
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
+can change this.
+
+Comparison is exact; there is no rounding error.
+
+Neither a leading @samp{+} nor exponential notation is recognized.
+To compare such strings numerically, use the
+@option{--general-numeric-sort} (@option{-g}) option.
+
+@item -V
+@itemx --version-sort
+@opindex -V
+@opindex --version-sort
+@cindex version number sort
+Sort by version name and number.  It behaves like a standard sort,
+except that each sequence of decimal digits is treated numerically
+as an index/version number.  (@xref{Version sort ordering}.)
+
+@item -r
+@itemx --reverse
+@opindex -r
+@opindex --reverse
+@cindex reverse sorting
+Reverse the result of comparison, so that lines with greater key values
+appear earlier in the output instead of later.
+
+@item -R
+@itemx --random-sort
+@itemx --sort=random
+@opindex -R
+@opindex --random-sort
+@opindex --sort
+@cindex random sort
+Sort by hashing the input keys and then sorting the hash values.
+Choose the hash function at random, ensuring that it is free of
+collisions so that differing keys have differing hash values.  This is
+like a random permutation of the inputs (@pxref{shuf invocation}),
+except that keys with the same value sort together.
+
+If multiple random sort fields are specified, the same random hash
+function is used for all fields.  To use different random hash
+functions for different fields, you can invoke @command{sort} more
+than once.
+
+The choice of hash function is affected by the
+@option{--random-source} option.
+
+@end table
+
+Other options are:
+
+@table @samp
+
+@item --compress-program=@var{prog}
+Compress any temporary files with the program @var{prog}.
+
+With no arguments, @var{prog} must compress standard input to standard
+output, and when given the @option{-d} option it must decompress
+standard input to standard output.
+
+Terminate with an error if @var{prog} exits with nonzero status.
+
+White space and the backslash character should not appear in
+@var{prog}; they are reserved for future use.
+
+@filesZeroFromOption{sort,,sorted output}
+
+@item -k @var{pos1}[,@var{pos2}]
+@itemx --key=@var{pos1}[,@var{pos2}]
+@opindex -k
+@opindex --key
+@cindex sort field
+Specify a sort field that consists of the part of the line between
+@var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is
+omitted), @emph{inclusive}.
+
+In its simplest form @var{pos} specifies a field number (starting with 1),
+with fields being separated by runs of blank characters, and by default
+those blanks being included in the comparison at the start of each field.
+To adjust the handling of blank characters see the @option{-b} and
+@option{-t} options.
+
+More generally,
+each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]},
+where @var{f} is the number of the field to use, and @var{c} is the number
+of the first character from the beginning of the field.  Fields and character
+positions are numbered starting with 1; a character position of zero in
+@var{pos2} indicates the field's last character.  If @samp{.@var{c}} is
+omitted from @var{pos1}, it defaults to 1 (the beginning of the field);
+if omitted from @var{pos2}, it defaults to 0 (the end of the field).
+@var{opts} are ordering options, allowing individual keys to be sorted
+according to different rules; see below for details.  Keys can span
+multiple fields.
+
+Example:  To sort on the second field, use @option{--key=2,2}
+(@option{-k 2,2}).  See below for more notes on keys and more examples.
+See also the @option{--debug} option to help determine the part
+of the line being used in the sort.
+
+@item --debug
+Highlight the portion of each line used for sorting.
+Also issue warnings about questionable usage to standard error.
+
+@item --batch-size=@var{nmerge}
+@opindex --batch-size
+@cindex number of inputs to merge, nmerge
+Merge at most @var{nmerge} inputs at once.
+
+When @command{sort} has to merge more than @var{nmerge} inputs,
+it merges them in groups of @var{nmerge}, saving the result in
+a temporary file, which is then used as an input in a subsequent merge.
+
+A large value of @var{nmerge} may improve merge performance and decrease
+temporary storage utilization at the expense of increased memory usage
+and I/O@.  Conversely a small value of @var{nmerge} may reduce memory
+requirements and I/O at the expense of temporary storage consumption and
+merge performance.
+
+The value of @var{nmerge} must be at least 2.  The default value is
+currently 16, but this is implementation-dependent and may change in
+the future.
+
+The value of @var{nmerge} may be bounded by a resource limit for open
+file descriptors.  The commands @samp{ulimit -n} or @samp{getconf
+OPEN_MAX} may display limits for your systems; these limits may be
+modified further if your program already has some files open, or if
+the operating system has other limits on the number of open files.  If
+the value of @var{nmerge} exceeds the resource limit, @command{sort}
+silently uses a smaller value.
+
+@item -o @var{output-file}
+@itemx --output=@var{output-file}
+@opindex -o
+@opindex --output
+@cindex overwriting of input, allowed
+Write output to @var{output-file} instead of standard output.
+Normally, @command{sort} reads all input before opening
+@var{output-file}, so you can sort a file in place by using
+commands like @code{sort -o F F} and @code{cat F | sort -o F}@.
+However, it is often safer to output to an otherwise-unused file, as
+data may be lost if the system crashes or @command{sort} encounters
+an I/O or other serious error while a file is being sorted in place.
+Also, @command{sort} with @option{--merge} (@option{-m}) can open
+the output file before reading all input, so a command like @code{cat
+F | sort -m -o F - G} is not safe as @command{sort} might start
+writing @file{F} before @command{cat} is done reading it.
+
+@vindex POSIXLY_CORRECT
+On newer systems, @option{-o} cannot appear after an input file if
+@env{POSIXLY_CORRECT} is set, e.g., @samp{sort F -o F}@.  Portable
+scripts should specify @option{-o @var{output-file}} before any input
+files.
+
+@item --random-source=@var{file}
+@opindex --random-source
+@cindex random source for sorting
+Use @var{file} as a source of random data used to determine which
+random hash function to use with the @option{-R} option.  @xref{Random
+sources}.
+
+@item -s
+@itemx --stable
+@opindex -s
+@opindex --stable
+@cindex sort stability
+@cindex sort's last-resort comparison
+
+Make @command{sort} stable by disabling its last-resort comparison.
+This option has no effect if no fields or global ordering options
+other than @option{--reverse} (@option{-r}) are specified.
+
+@item -S @var{size}
+@itemx --buffer-size=@var{size}
+@opindex -S
+@opindex --buffer-size
+@cindex size for main memory sorting
+Use a main-memory sort buffer of the given @var{size}.  By default,
+@var{size} is in units of 1024 bytes.  Appending @samp{%} causes
+@var{size} to be interpreted as a percentage of physical memory.
+Appending @samp{K} multiplies @var{size} by 1024 (the default),
+@samp{M} by 1,048,576, @samp{G} by 1,073,741,824, and so on for
+@samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y}, @samp{R}, and @samp{Q}@.
+Appending
+@samp{b} causes @var{size} to be interpreted as a byte count, with no
+multiplication.
+
+This option can improve the performance of @command{sort} by causing it
+to start with a larger or smaller sort buffer than the default.
+However, this option affects only the initial buffer size.  The buffer
+grows beyond @var{size} if @command{sort} encounters input lines larger
+than @var{size}.
+
+@item -t @var{separator}
+@itemx --field-separator=@var{separator}
+@opindex -t
+@opindex --field-separator
+@cindex field separator character
+Use character @var{separator} as the field separator when finding the
+sort keys in each line.  By default, fields are separated by the empty
+string between a non-blank character and a blank character.
+By default a blank is a space or a tab, but the @env{LC_CTYPE} locale
+can change this.
+
+That is, given the input line @w{@samp{ foo bar}}, @command{sort} breaks it
+into fields @w{@samp{ foo}} and @w{@samp{ bar}}.  The field separator is
+not considered to be part of either the field preceding or the field
+following, so with @samp{sort @w{-t " "}} the same input line has
+three fields: an empty field, @samp{foo}, and @samp{bar}.
+However, fields that extend to the end of the line,
+as @option{-k 2}, or fields consisting of a range, as @option{-k 2,3},
+retain the field separators present between the endpoints of the range.
+
+To specify ASCII NUL as the field separator,
+use the two-character string @samp{\0}, e.g., @samp{sort -t '\0'}.
+
+@item -T @var{tempdir}
+@itemx --temporary-directory=@var{tempdir}
+@opindex -T
+@opindex --temporary-directory
+@cindex temporary directory
+@vindex TMPDIR
+Use directory @var{tempdir} to store temporary files, overriding the
+@env{TMPDIR} environment variable.  If this option is given more than
+once, temporary files are stored in all the directories given.  If you
+have a large sort or merge that is I/O-bound, you can often improve
+performance by using this option to specify directories on different
+file systems.
+
+@item --parallel=@var{n}
+@opindex --parallel
+@cindex multithreaded sort
+Set the number of sorts run in parallel to @var{n}. By default,
+@var{n} is set to the number of available processors, but limited
+to 8, as there are diminishing performance gains after that.
+Note also that using @var{n} threads increases the memory usage by
+a factor of log @var{n}.  Also see @ref{nproc invocation}.
+
+@item -u
+@itemx --unique
+@opindex -u
+@opindex --unique
+@cindex uniquifying output
+
+Normally, output only the first of a sequence of lines that compare
+equal.  For the @option{--check} (@option{-c} or @option{-C}) option,
+check that no pair of consecutive lines compares equal.
+
+This option also disables the default last-resort comparison.
+
+The commands @code{sort -u} and @code{sort | uniq} are equivalent, but
+this equivalence does not extend to arbitrary @command{sort} options.
+For example, @code{sort -n -u} inspects only the value of the initial
+numeric string when checking for uniqueness, whereas @code{sort -n |
+uniq} inspects the entire line.  @xref{uniq invocation}.
+
+@optZeroTerminated
+@macro newlineFieldSeparator
+Note with @option{-z} the newline character is treated as a field separator.
+@end macro
+
+@end table
+
+Historical (BSD and System V) implementations of @command{sort} have
+differed in their interpretation of some options, particularly
+@option{-b}, @option{-f}, and @option{-n}.
+GNU sort follows the POSIX
+behavior, which is usually (but not always!) like the System V behavior.
+According to POSIX, @option{-n} no longer implies @option{-b}.  For
+consistency, @option{-M} has been changed in the same way.  This may
+affect the meaning of character positions in field specifications in
+obscure cases.  The only fix is to add an explicit @option{-b}.
+
+A position in a sort field specified with @option{-k} may have any
+of the option letters @samp{MbdfghinRrV} appended to it, in which case no
+global ordering options are inherited by that particular field.  The
+@option{-b} option may be independently attached to either or both of
+the start and end positions of a field specification, and if it is
+inherited from the global options it will be attached to both.
+If input lines can contain leading or adjacent blanks and @option{-t}
+is not used, then @option{-k} is typically combined with @option{-b} or
+an option that implicitly ignores leading blanks (@samp{Mghn}) as otherwise
+the varying numbers of leading blanks in fields can cause confusing results.
+
+If the start position in a sort field specifier falls after the end of
+the line or after the end field, the field is empty.  If the @option{-b}
+option was specified, the @samp{.@var{c}} part of a field specification
+is counted from the first nonblank character of the field.
+
+@vindex _POSIX2_VERSION
+@vindex POSIXLY_CORRECT
+On systems not conforming to POSIX 1003.1-2001,
+@command{sort} supports a traditional origin-zero
+syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys.
+The traditional command @samp{sort +@var{a}.@var{x} -@var{b}.@var{y}}
+is equivalent to @samp{sort -k @var{a+1}.@var{x+1},@var{b}} if @var{y}
+is @samp{0} or absent, otherwise it is equivalent to @samp{sort -k
+@var{a+1}.@var{x+1},@var{b+1}.@var{y}}.
+
+This traditional behavior can be controlled with the
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
+conformance}); it can also be enabled when @env{POSIXLY_CORRECT} is
+not set by using the traditional syntax with @samp{-@var{pos2}} present.
+
+Scripts intended for use on standard hosts should avoid traditional
+syntax and should use @option{-k} instead.  For example, avoid
+@samp{sort +2}, since it might be interpreted as either @samp{sort
+./+2} or @samp{sort -k 3}.  If your script must also run on hosts that
+support only the traditional syntax, it can use a test like @samp{if sort
+-k 1 </dev/null >/dev/null 2>&1; then @dots{}} to decide which syntax
+to use.
+
+Here are some examples to illustrate various combinations of options.
+
+@itemize @bullet
+
+@item
+Sort in descending (reverse) numeric order.
+
+@example
+sort -n -r
+@end example
+
+@item
+Run no more than 4 sorts concurrently, using a buffer size of 10M.
+
+@example
+sort --parallel=4 -S 10M
+@end example
+
+@item
+Sort alphabetically, omitting the first and second fields
+and the blanks at the start of the third field.
+This uses a single key composed of the characters beginning
+at the start of the first nonblank character in field three
+and extending to the end of each line.
+
+@example
+sort -k 3b
+@end example
+
+@item
+Sort numerically on the second field and resolve ties by sorting
+alphabetically on the third and fourth characters of field five.
+Use @samp{:} as the field delimiter.
+
+@example
+sort -t : -k 2,2n -k 5.3,5.4
+@end example
+
+Note that if you had written @option{-k 2n} instead of @option{-k 2,2n}
+@command{sort} would have used all characters beginning in the second field
+and extending to the end of the line as the primary @emph{numeric}
+key.  For the large majority of applications, treating keys spanning
+more than one field as numeric will not do what you expect.
+
+Also note that the @samp{n} modifier was applied to the field-end
+specifier for the first key.  It would have been equivalent to
+specify @option{-k 2n,2} or @option{-k 2n,2n}.  All modifiers except
+@samp{b} apply to the associated @emph{field}, regardless of whether
+the modifier character is attached to the field-start and/or the
+field-end part of the key specifier.
+
+@item
+Sort the password file on the fifth field and ignore any
+leading blanks.  Sort lines with equal values in field five
+on the numeric user ID in field three.  Fields are separated
+by @samp{:}.
+
+@example
+sort -t : -k 5b,5 -k 3,3n /etc/passwd
+sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
+sort -t : -b -k 5,5 -k 3,3n /etc/passwd
+@end example
+
+These three commands have equivalent effect.  The first specifies that
+the first key's start position ignores leading blanks and the second
+key is sorted numerically.  The other two commands rely on global
+options being inherited by sort keys that lack modifiers.  The inheritance
+works in this case because @option{-k 5b,5b} and @option{-k 5b,5} are
+equivalent, as the location of a field-end lacking a @samp{.@var{c}}
+character position is not affected by whether initial blanks are
+skipped.
+
+@item
+Sort a set of log files, primarily by IPv4 address and secondarily by
+timestamp.  If two lines' primary and secondary keys are identical,
+output the lines in the same order that they were input.  The log
+files contain lines that look like this:
+
+@example
+4.150.156.3 - - [01/Apr/2020:06:31:51 +0000] message 1
+211.24.3.231 - - [24/Apr/2020:20:17:39 +0000] message 2
+@end example
+
+Fields are separated by exactly one space.  Sort IPv4 addresses
+lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201
+because 61 is less than 129.
+
+@example
+sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log |
+sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n
+@end example
+
+This example cannot be done with a single POSIX @command{sort} invocation,
+since IPv4 address components are separated by @samp{.} while dates
+come just after a space.  So it is broken down into two invocations of
+@command{sort}: the first sorts by timestamp and the second by IPv4
+address.  The timestamp is sorted by year, then month, then day, and
+finally by hour-minute-second field, using @option{-k} to isolate each
+field.  Except for hour-minute-second there's no need to specify the
+end of each key field, since the @samp{n} and @samp{M} modifiers sort
+based on leading prefixes that cannot cross field boundaries.  The
+IPv4 addresses are sorted lexicographically.  The second sort uses
+@samp{-s} so that ties in the primary key are broken by the secondary
+key; the first sort uses @samp{-s} so that the combination of the two
+sorts is stable.  Note as a GNU extension, the above example could
+be achieved in a single @command{sort} invocation by sorting the
+IPv4 address field using a @samp{V} version type, like @samp{-k1,1V}.
+
+@item
+Generate a tags file in case-insensitive sorted order.
+
+@example
+find src -type f -print0 | sort -z -f | xargs -0 etags --append
+@end example
+
+The use of @option{-print0}, @option{-z}, and @option{-0} in this case means
+that file names that contain blanks or other special characters are
+not broken up
+by the sort operation.
+
+@c This example is a bit contrived and needs more explanation.
+@c @item
+@c Sort records separated by an arbitrary string by using a pipe to convert
+@c each record delimiter string to @samp{\0},
+@c then using sort's @option{-z} option,
+@c and converting each @samp{\0} back to the original record delimiter.
+@c
+@c @example
+@c printf 'c\n\nb\n\na\n' |
+@c perl -0pe 's/\n\n/\n\0/g' |
+@c sort -z |
+@c perl -0pe 's/\0/\n/g'
+@c @end example
+
+@item
+Use the common DSU, Decorate Sort Undecorate idiom to
+sort lines according to their length.
+
+@example
+awk '@{print length, $0@}' /etc/passwd | sort -n | cut -f2- -d' '
+@end example
+
+In general this technique can be used to sort data that the @command{sort}
+command does not support, or is inefficient at, sorting directly.
+
+@item
+Shuffle a list of directories, but preserve the order of files within
+each directory.  For instance, one could use this to generate a music
+playlist in which albums are shuffled but the songs of each album are
+played in order.
+
+@example
+ls */* | sort -t / -k 1,1R -k 2,2
+@end example
+
+@end itemize
+
+
+@node shuf invocation
+@section @command{shuf}: Shuffling text
+
+@pindex shuf
+@cindex shuffling files
+
+@command{shuf} shuffles its input by outputting a random permutation
+of its input lines.  Each output permutation is equally likely.
+Synopses:
+
+@example
+shuf [@var{option}]@dots{} [@var{file}]
+shuf -e [@var{option}]@dots{} [@var{arg}]@dots{}
+shuf -i @var{lo}-@var{hi} [@var{option}]@dots{}
+@end example
+
+@command{shuf} has three modes of operation that affect where it
+obtains its input lines.  By default, it reads lines from standard
+input.  The following options change the operation mode:
+
+@table @samp
+
+@item -e
+@itemx --echo
+@opindex -c
+@opindex --echo
+@cindex command-line operands to shuffle
+Treat each command-line operand as an input line.
+
+@item -i @var{lo}-@var{hi}
+@itemx --input-range=@var{lo}-@var{hi}
+@opindex -i
+@opindex --input-range
+@cindex input range to shuffle
+Act as if input came from a file containing the range of unsigned
+decimal integers @var{lo}@dots{}@var{hi}, one per line.
+
+@end table
+
+@command{shuf}'s other options can affect its behavior in all
+operation modes:
+
+@table @samp
+
+@item -n @var{count}
+@itemx --head-count=@var{count}
+@opindex -n
+@opindex --head-count
+@cindex head of output
+Output at most @var{count} lines.  By default, all input lines are
+output.
+
+@item -o @var{output-file}
+@itemx --output=@var{output-file}
+@opindex -o
+@opindex --output
+@cindex overwriting of input, allowed
+Write output to @var{output-file} instead of standard output.
+@command{shuf} reads all input before opening
+@var{output-file}, so you can safely shuffle a file in place by using
+commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}.
+
+@item --random-source=@var{file}
+@opindex --random-source
+@cindex random source for shuffling
+Use @var{file} as a source of random data used to determine which
+permutation to generate.  @xref{Random sources}.
+
+@item -r
+@itemx --repeat
+@opindex -r
+@opindex --repeat
+@cindex repeat output values
+Repeat output values, that is, select with replacement.  With this
+option the output is not a permutation of the input; instead, each
+output line is randomly chosen from all the inputs.  This option is
+typically combined with @option{--head-count}; if
+@option{--head-count} is not given, @command{shuf} repeats
+indefinitely.
+
+@optZeroTerminated
+
+@end table
+
+For example:
+
+@example
+shuf <<EOF
+A man,
+a plan,
+a canal:
+Panama!
+EOF
+@end example
+
+@noindent
+might produce the output
+
+@example
+Panama!
+A man,
+a canal:
+a plan,
+@end example
+
+@noindent
+Similarly, the command:
+
+@example
+shuf -e clubs hearts diamonds spades
+@end example
+
+@noindent
+might output:
+
+@example
+clubs
+diamonds
+spades
+hearts
+@end example
+
+@noindent
+and the command @samp{shuf -i 1-4} might output:
+
+@example
+4
+2
+1
+3
+@end example
+
+@noindent
+The above examples all have four input lines, so @command{shuf} might
+produce any of the twenty-four possible permutations of the input.  In
+general, if there are @var{n} input lines, there are @var{n}! (i.e.,
+@var{n} factorial, or @var{n} * (@var{n} - 1) * @dots{} * 1) possible
+output permutations.
+
+@noindent
+To output 50 random numbers each in the range 0 through 9, use:
+
+@example
+shuf -r -n 50 -i 0-9
+@end example
+
+@noindent
+To simulate 100 coin flips, use:
+
+@example
+shuf -r -n 100 -e Head Tail
+@end example
+
+@exitstatus
+
+
+@node uniq invocation
+@section @command{uniq}: Uniquify files
+
+@pindex uniq
+@cindex uniquify files
+
+@command{uniq} writes the unique lines in the given @file{input}, or
+standard input if nothing is given or for an @var{input} name of
+@samp{-}.  Synopsis:
+
+@example
+uniq [@var{option}]@dots{} [@var{input} [@var{output}]]
+@end example
+
+By default, @command{uniq} prints its input lines, except that
+it discards all but the first of adjacent repeated lines, so that
+no output lines are repeated.  Optionally, it can instead discard
+lines that are not repeated, or all repeated lines.
+
+The input need not be sorted, but repeated input lines are detected
+only if they are adjacent.  If you want to discard non-adjacent
+duplicate lines, perhaps you want to use @code{sort -u}.
+@xref{sort invocation}.
+
+@vindex LC_COLLATE
+Comparisons honor the rules specified by the @env{LC_COLLATE}
+locale category.
+
+If no @var{output} file is specified, @command{uniq} writes to standard
+output.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -f @var{n}
+@itemx --skip-fields=@var{n}
+@opindex -f
+@opindex --skip-fields
+Skip @var{n} fields on each line before checking for uniqueness.  Use
+a null string for comparison if a line has fewer than @var{n} fields.
+Fields are a sequence of blank characters followed by non-blank characters.
+Field numbers are one based, i.e., @option{-f 1} will skip the first
+field (which may optionally have leading blanks).
+
+For compatibility @command{uniq} supports a traditional option syntax
+@option{-@var{n}}.  New scripts should use @option{-f @var{n}} instead.
+
+@item -s @var{n}
+@itemx --skip-chars=@var{n}
+@opindex -s
+@opindex --skip-chars
+Skip @var{n} characters before checking for uniqueness.  Use a null string
+for comparison if a line has fewer than @var{n} characters.  If you use both
+the field and character skipping options, fields are skipped over first.
+
+@vindex _POSIX2_VERSION
+On systems not conforming to POSIX 1003.1-2001,
+@command{uniq} supports a traditional option syntax
+@option{+@var{n}}.
+Although this traditional behavior can be controlled with the
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
+conformance}), portable scripts should avoid commands whose
+behavior depends on this variable.
+For example, use @samp{uniq ./+10} or @samp{uniq -s 10} rather than
+the ambiguous @samp{uniq +10}.
+
+@item -c
+@itemx --count
+@opindex -c
+@opindex --count
+Print the number of times each line occurred along with the line.
+
+@item -i
+@itemx --ignore-case
+@opindex -i
+@opindex --ignore-case
+Ignore differences in case when comparing lines.
+
+@item -d
+@itemx --repeated
+@opindex -d
+@opindex --repeated
+@cindex repeated lines, outputting
+Discard lines that are not repeated.  When used by itself, this option
+causes @command{uniq} to print the first copy of each repeated line,
+and nothing else.
+
+@item -D
+@itemx --all-repeated[=@var{delimit-method}]
+@opindex -D
+@opindex --all-repeated
+@cindex all repeated lines, outputting
+Do not discard the second and subsequent repeated input lines,
+but discard lines that are not repeated.
+This option is useful mainly in conjunction with other options e.g.,
+to ignore case or to compare only selected fields.
+The optional @var{delimit-method}, supported with the long form option,
+specifies how to delimit groups of repeated lines, and must be one of the
+following:
+
+@table @samp
+
+@item none
+Do not delimit groups of repeated lines.
+This is equivalent to @option{--all-repeated} (@option{-D}).
+
+@item prepend
+Output a newline before each group of repeated lines.
+@macro nulOutputNote
+With @option{--zero-terminated} (@option{-z}), use a zero
+byte (ASCII NUL) instead of a newline as the delimiter.
+@end macro
+@nulOutputNote
+
+@item separate
+Separate groups of repeated lines with a single newline.
+This is the same as using @samp{prepend}, except that
+no delimiter is inserted before the first group, and hence
+may be better suited for output direct to users.
+@nulOutputNote
+@end table
+
+@macro ambiguousGroupNote
+Note that when groups are delimited and the input stream contains
+blank lines, then the output is ambiguous.
+To avoid that, filter the input through @samp{tr -s '\\n'} to
+remove blank lines.
+@end macro
+@ambiguousGroupNote
+
+This is a GNU extension.
+@c FIXME: give an example showing *how* it's useful
+
+@item --group[=@var{delimit-method}]
+@opindex --group
+@cindex all lines, grouping
+Output all lines, and delimit each unique group.
+@nulOutputNote
+The optional @var{delimit-method} specifies how to delimit
+groups, and must be one of the following:
+
+@table @samp
+
+@item separate
+Separate unique groups with a single delimiter.
+This is the default delimiting method if none is specified,
+and better suited for output direct to users.
+
+@item prepend
+Output a delimiter before each group of unique items.
+
+@item append
+Output a delimiter after each group of unique items.
+
+@item both
+Output a delimiter around each group of unique items.
+@end table
+
+@ambiguousGroupNote
+
+This is a GNU extension.
+
+@item -u
+@itemx --unique
+@opindex -u
+@opindex --unique
+@cindex unique lines, outputting
+Discard the last line that would be output for a repeated input group.
+When used by itself, this option causes @command{uniq} to print unique
+lines, and nothing else.
+
+@item -w @var{n}
+@itemx --check-chars=@var{n}
+@opindex -w
+@opindex --check-chars
+Compare at most @var{n} characters on each line (after skipping any specified
+fields and characters).  By default the entire rest of the lines are
+compared.
+
+@optZeroTerminated
+@newlineFieldSeparator
+
+@end table
+
+@exitstatus
+
+
+@node comm invocation
+@section @command{comm}: Compare two sorted files line by line
+
+@pindex comm
+@cindex line-by-line comparison
+@cindex comparing sorted files
+
+@command{comm} writes to standard output lines that are common, and lines
+that are unique, to two input files; a file name of @samp{-} means
+standard input.  Synopsis:
+
+@example
+comm [@var{option}]@dots{} @var{file1} @var{file2}
+@end example
+
+@vindex LC_COLLATE
+Before @command{comm} can be used, the input files must be sorted using the
+collating sequence specified by the @env{LC_COLLATE} locale.
+If an input file ends in a non-newline
+character, a newline is silently appended.  The @command{sort} command with
+no options always outputs a file that is suitable input to @command{comm}.
+
+@cindex differing lines
+@cindex common lines
+With no options, @command{comm} produces three-column output.  Column one
+contains lines unique to @var{file1}, column two contains lines unique
+to @var{file2}, and column three contains lines common to both files.
+Columns are separated by a single TAB character.
+@c FIXME: when there's an option to supply an alternative separator
+@c string, append "by default" to the above sentence.
+
+@opindex -1
+@opindex -2
+@opindex -3
+The options @option{-1}, @option{-2}, and @option{-3} suppress printing of
+the corresponding columns (and separators).  Also see @ref{Common options}.
+
+Unlike some other comparison utilities, @command{comm} has an exit
+status that does not depend on the result of the comparison.
+Upon normal completion @command{comm} produces an exit code of zero.
+If there is an error it exits with nonzero status.
+
+@macro checkOrderOption{cmd}
+If the @option{--check-order} option is given, unsorted inputs will
+cause a fatal error message.  If the option @option{--nocheck-order}
+is given, unsorted inputs will never cause an error message.  If neither
+of these options is given, wrongly sorted inputs are diagnosed
+only if an input file is found to contain unpairable
+@ifset JOIN_COMMAND
+lines, and when both input files are non empty.
+@end ifset
+@ifclear JOIN_COMMAND
+lines.
+@end ifclear
+If an input file is diagnosed as being unsorted, the @command{\cmd\}
+command will exit with a nonzero status (and the output should not be used).
+
+Forcing @command{\cmd\} to process wrongly sorted input files
+containing unpairable lines by specifying @option{--nocheck-order} is
+not guaranteed to produce any particular output.  The output will
+probably not correspond with whatever you hoped it would be.
+@end macro
+@checkOrderOption{comm}
+
+@table @samp
+
+@item --check-order
+Fail with an error message if either input file is wrongly ordered.
+
+@item --nocheck-order
+Do not check that both input files are in sorted order.
+
+Other options are:
+
+@item --output-delimiter=@var{str}
+Print @var{str} between adjacent output columns,
+rather than the default of a single TAB character.
+
+The delimiter @var{str} may be empty, in which case
+the ASCII NUL character is used to delimit output columns.
+
+@item --total
+Output a summary at the end.
+
+Similar to the regular output,
+column one contains the total number of lines unique to @var{file1},
+column two contains the total number of lines unique to @var{file2}, and
+column three contains the total number of lines common to both files,
+followed by the word @samp{total} in the additional column four.
+
+In the following example, @command{comm} omits the regular output
+(@option{-123}), thus just printing the summary:
+
+@example
+$ printf '%s\n' a b c d e     > file1
+$ printf '%s\n'   b c d e f g > file2
+$ comm --total -123 file1 file2
+1       2       4       total
+@end example
+
+This option is a GNU extension.  Portable scripts should use @command{wc} to
+get the totals, e.g. for the above example files:
+
+@example
+$ comm -23 file1 file2 | wc -l    # number of lines only in file1
+1
+$ comm -13 file1 file2 | wc -l    # number of lines only in file2
+2
+$ comm -12 file1 file2 | wc -l    # number of lines common to both files
+4
+@end example
+
+@optZeroTerminated
+
+@end table
+
+@node ptx invocation
+@section @command{ptx}: Produce permuted indexes
+
+@pindex ptx
+
+@command{ptx} reads a text file and essentially produces a permuted index, with
+each keyword in its context.  The calling sketch is either one of:
+
+@example
+ptx [@var{option} @dots{}] [@var{file} @dots{}]
+ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]]
+@end example
+
+The @option{-G} (or its equivalent: @option{--traditional}) option disables
+all GNU extensions and reverts to traditional mode, thus introducing some
+limitations and changing several of the program's default option values.
+When @option{-G} is not specified, GNU extensions are always enabled.
+GNU extensions to @command{ptx} are documented wherever appropriate in this
+document.  @xref{Compatibility in ptx}, for the full list.
+
+Individual options are explained in the following sections.
+
+When GNU extensions are enabled, there may be zero, one or several
+@var{file}s after the options.  If there is no @var{file}, the program
+reads the standard input.  If there is one or several @var{file}s, they
+give the name of input files which are all read in turn, as if all the
+input files were concatenated.  However, there is a full contextual
+break between each file and, when automatic referencing is requested,
+file names and line numbers refer to individual text input files.  In
+all cases, the program outputs the permuted index to the standard
+output.
+
+When GNU extensions are @emph{not} enabled, that is, when the program
+operates in traditional mode, there may be zero, one or two parameters
+besides the options.  If there are no parameters, the program reads the
+standard input and outputs the permuted index to the standard output.
+If there is only one parameter, it names the text @var{input} to be read
+instead of the standard input.  If two parameters are given, they give
+respectively the name of the @var{input} file to read and the name of
+the @var{output} file to produce.  @emph{Be very careful} to note that,
+in this case, the contents of file given by the second parameter is
+destroyed.  This behavior is dictated by System V @command{ptx}
+compatibility; GNU Standards normally discourage output parameters not
+introduced by an option.
+
+Note that for @emph{any} file named as the value of an option or as an
+input text file, a single dash @samp{-} may be used, in which case
+standard input is assumed.  However, it would not make sense to use this
+convention more than once per program invocation.
+
+@menu
+* General options in ptx::      Options which affect general program behavior.
+* Charset selection in ptx::    Underlying character set considerations.
+* Input processing in ptx::     Input fields, contexts, and keyword selection.
+* Output formatting in ptx::    Types of output format, and sizing the fields.
+* Compatibility in ptx::
+@end menu
+
+
+@node General options in ptx
+@subsection General options
+
+@table @samp
+
+@item -G
+@itemx --traditional
+As already explained, this option disables all GNU extensions to
+@command{ptx} and switches to traditional mode.
+
+@item --help
+Print a short help on standard output, then exit without further
+processing.
+
+@item --version
+Print the program version on standard output, then exit without further
+processing.
+
+@end table
+
+@exitstatus
+
+
+@node Charset selection in ptx
+@subsection Charset selection
+
+As it is set up now, @command{ptx} assumes that the input file is coded
+using 8-bit characters, and it may not work well in multibyte locales.
+In a single-byte locale, the default regular expression
+for a keyword allows foreign or diacriticized letters.  Keyword sorting,
+however, is still crude; it obeys the underlying character set ordering
+quite blindly.
+
+The output of @command{ptx} assumes the locale's character encoding.
+For example, with @command{ptx}'s @option{-T} option, if the locale
+uses the Latin-1 encoding you may need a LaTeX directive like
+@samp{\usepackage[latin1]@{inputenc@}} to render non-ASCII characters
+correctly.
+
+@table @samp
+
+@item -f
+@itemx --ignore-case
+@opindex -f
+@opindex --ignore-case
+Fold lower case letters to upper case for sorting.
+
+@end table
+
+
+@node Input processing in ptx
+@subsection Word selection and input processing
+
+@table @samp
+
+@item -b @var{file}
+@itemx --break-file=@var{file}
+@opindex -b
+@opindex --break-file
+
+This option provides an alternative (to @option{-W}) method of describing
+which characters make up words.  It introduces the name of a
+file which contains a list of characters which can@emph{not} be part of
+one word; this file is called the @dfn{Break file}.  Any character which
+is not part of the Break file is a word constituent.  If both options
+@option{-b} and @option{-W} are specified, then @option{-W} has precedence and
+@option{-b} is ignored.
+
+When GNU extensions are enabled, the only way to avoid newline as a
+break character is to write all the break characters in the file with no
+newline at all, not even at the end of the file.  When GNU extensions
+are disabled, spaces, tabs and newlines are always considered as break
+characters even if not included in the Break file.
+
+@item -i @var{file}
+@itemx --ignore-file=@var{file}
+@opindex -i
+@opindex --ignore-file
+
+The file associated with this option contains a list of words which will
+never be taken as keywords in concordance output.  It is called the
+@dfn{Ignore file}.  The file contains exactly one word in each line; the
+end of line separation of words is not subject to the value of the
+@option{-S} option.
+
+@item -o @var{file}
+@itemx --only-file=@var{file}
+@opindex -o
+@opindex --only-file
+
+The file associated with this option contains a list of words which will
+be retained in concordance output; any word not mentioned in this file
+is ignored.  The file is called the @dfn{Only file}.  The file contains
+exactly one word in each line; the end of line separation of words is
+not subject to the value of the @option{-S} option.
+
+There is no default for the Only file.  When both an Only file and an
+Ignore file are specified, a word is considered a keyword only
+if it is listed in the Only file and not in the Ignore file.
+
+@item -r
+@itemx --references
+@opindex -r
+@opindex --references
+
+On each input line, the leading sequence of non-white space characters will be
+taken to be a reference that has the purpose of identifying this input
+line in the resulting permuted index.
+@xref{Output formatting in ptx},
+for more information about reference production.
+Using this option changes the default value for option @option{-S}.
+
+Using this option, the program does not try very hard to remove
+references from contexts in output, but it succeeds in doing so
+@emph{when} the context ends exactly at the newline.  If option
+@option{-r} is used with @option{-S} default value, or when GNU extensions
+are disabled, this condition is always met and references are completely
+excluded from the output contexts.
+
+@item -S @var{regexp}
+@itemx --sentence-regexp=@var{regexp}
+@opindex -S
+@opindex --sentence-regexp
+
+This option selects which regular expression will describe the end of a
+line or the end of a sentence.  In fact, this regular expression is not
+the only distinction between end of lines or end of sentences, and input
+line boundaries have no special significance outside this option.  By
+default, when GNU extensions are enabled and if @option{-r} option is not
+used, end of sentences are used.  In this case, this @var{regex} is
+imported from GNU Emacs:
+
+@example
+[.?!][]\"')@}]*\\($\\|\t\\|  \\)[ \t\n]*
+@end example
+
+Whenever GNU extensions are disabled or if @option{-r} option is used, end
+of lines are used; in this case, the default @var{regexp} is just:
+
+@example
+\n
+@end example
+
+Using an empty @var{regexp} is equivalent to completely disabling end of
+line or end of sentence recognition.  In this case, the whole file is
+considered to be a single big line or sentence.  The user might want to
+disallow all truncation flag generation as well, through option @option{-F
+""}.  @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
+Manual}.
+
+When the keywords happen to be near the beginning of the input line or
+sentence, this often creates an unused area at the beginning of the
+output context line; when the keywords happen to be near the end of the
+input line or sentence, this often creates an unused area at the end of
+the output context line.  The program tries to fill those unused areas
+by wrapping around context in them; the tail of the input line or
+sentence is used to fill the unused area on the left of the output line;
+the head of the input line or sentence is used to fill the unused area
+on the right of the output line.
+
+As a matter of convenience to the user, many usual backslashed escape
+sequences from the C language are recognized and converted to the
+corresponding characters by @command{ptx} itself.
+
+@item -W @var{regexp}
+@itemx --word-regexp=@var{regexp}
+@opindex -W
+@opindex --word-regexp
+
+This option selects which regular expression will describe each keyword.
+By default, if GNU extensions are enabled, a word is a sequence of
+letters; the @var{regexp} used is @samp{\w+}.  When GNU extensions are
+disabled, a word is by default anything which ends with a space, a tab
+or a newline; the @var{regexp} used is @samp{[^ \t\n]+}.
+
+An empty @var{regexp} is equivalent to not using this option.
+@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs
+Manual}.
+
+As a matter of convenience to the user, many usual backslashed escape
+sequences, as found in the C language, are recognized and converted to
+the corresponding characters by @command{ptx} itself.
+
+@end table
+
+
+@node Output formatting in ptx
+@subsection Output formatting
+
+Output format is mainly controlled by the @option{-O} and @option{-T} options
+described in the table below.  When neither @option{-O} nor @option{-T} are
+selected, and if GNU extensions are enabled, the program chooses an
+output format suitable for a dumb terminal.  Each keyword occurrence is
+output to the center of one line, surrounded by its left and right
+contexts.  Each field is properly justified, so the concordance output
+can be readily observed.  As a special feature, if automatic
+references are selected by option @option{-A} and are output before the
+left context, that is, if option @option{-R} is @emph{not} selected, then
+a colon is added after the reference; this nicely interfaces with GNU
+Emacs @code{next-error} processing.  In this default output format, each
+white space character, like newline and tab, is merely changed to
+exactly one space, with no special attempt to compress consecutive
+spaces.  This might change in the future.  Except for those white space
+characters, every other character of the underlying set of 256
+characters is transmitted verbatim.
+
+Output format is further controlled by the following options.
+
+@table @samp
+
+@item -g @var{number}
+@itemx --gap-size=@var{number}
+@opindex -g
+@opindex --gap-size
+
+Select the size of the minimum white space gap between the fields on the
+output line.
+
+@item -w @var{number}
+@itemx --width=@var{number}
+@opindex -w
+@opindex --width
+
+Select the maximum output width of each final line.  If references are
+used, they are included or excluded from the maximum output width
+depending on the value of option @option{-R}@.  If this option is not
+selected, that is, when references are output before the left context,
+the maximum output width takes into account the maximum length of all
+references.  If this option is selected, that is, when references are
+output after the right context, the maximum output width does not take
+into account the space taken by references, nor the gap that precedes
+them.
+
+@item -A
+@itemx --auto-reference
+@opindex -A
+@opindex --auto-reference
+
+Select automatic references.  Each input line will have an automatic
+reference made up of the file name and the line ordinal, with a single
+colon between them.  However, the file name will be empty when standard
+input is being read.  If both @option{-A} and @option{-r} are selected, then
+the input reference is still read and skipped, but the automatic
+reference is used at output time, overriding the input reference.
+
+@item -R
+@itemx --right-side-refs
+@opindex -R
+@opindex --right-side-refs
+
+In the default output format, when option @option{-R} is not used, any
+references produced by the effect of options @option{-r} or @option{-A} are
+placed to the far right of output lines, after the right context.  With
+default output format, when the @option{-R} option is specified, references
+are rather placed at the beginning of each output line, before the left
+context.  For any other output format, option @option{-R} is
+ignored, with one exception:  with @option{-R} the width of references
+is @emph{not} taken into account in total output width given by @option{-w}.
+
+This option is automatically selected whenever GNU extensions are
+disabled.
+
+@item -F @var{string}
+@itemx --flag-truncation=@var{string}
+@opindex -F
+@opindex --flag-truncation
+
+This option will request that any truncation in the output be reported
+using the string @var{string}.  Most output fields theoretically extend
+towards the beginning or the end of the current line, or current
+sentence, as selected with option @option{-S}@.  But there is a maximum
+allowed output line width, changeable through option @option{-w}, which is
+further divided into space for various output fields.  When a field has
+to be truncated because it cannot extend beyond the beginning or the end of
+the current line to fit in, then a truncation occurs.  By default,
+the string used is a single slash, as in @option{-F /}.
+
+@var{string} may have more than one character, as in @option{-F @dots{}}.
+Also, in the particular case when @var{string} is empty (@option{-F ""}),
+truncation flagging is disabled, and no truncation marks are appended in
+this case.
+
+As a matter of convenience to the user, many usual backslashed escape
+sequences, as found in the C language, are recognized and converted to
+the corresponding characters by @command{ptx} itself.
+
+@item -M @var{string}
+@itemx --macro-name=@var{string}
+@opindex -M
+@opindex --macro-name
+
+Select another @var{string} to be used instead of @samp{xx}, while
+generating output suitable for @command{nroff}, @command{troff} or @TeX{}.
+
+@item -O
+@itemx --format=roff
+@opindex -O
+@opindex --format=roff
+
+Choose an output format suitable for @command{nroff} or @command{troff}
+processing.  Each output line will look like:
+
+@example
+.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}"@c
+ "@var{head}" "@var{ref}"
+@end example
+
+so it will be possible to write a @samp{.xx} roff macro to take care of
+the output typesetting.  This is the default output format when GNU
+extensions are disabled.  Option @option{-M} can be used to change
+@samp{xx} to another macro name.
+
+In this output format, each non-graphical character, like newline and
+tab, is merely changed to exactly one space, with no special attempt to
+compress consecutive spaces.  Each quote character @samp{"} is doubled
+so it will be correctly processed by @command{nroff} or @command{troff}.
+
+@item -T
+@itemx --format=tex
+@opindex -T
+@opindex --format=tex
+
+Choose an output format suitable for @TeX{} processing.  Each output
+line will look like:
+
+@example
+\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@c
+@{@var{after}@}@{@var{head}@}@{@var{ref}@}
+@end example
+
+@noindent
+so it will be possible to write a @code{\xx} definition to take care of
+the output typesetting.  Note that when references are not being
+produced, that is, neither option @option{-A} nor option @option{-r} is
+selected, the last parameter of each @code{\xx} call is inhibited.
+Option @option{-M} can be used to change @samp{xx} to another macro
+name.
+
+In this output format, some special characters, like @samp{$}, @samp{%},
+@samp{&}, @samp{#} and @samp{_} are automatically protected with a
+backslash.  Curly brackets @samp{@{}, @samp{@}} are protected with a
+backslash and a pair of dollar signs (to force mathematical mode).  The
+backslash itself produces the sequence @code{\backslash@{@}}.
+Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and
+@code{~\@{ @}} respectively.  Other diacriticized characters of the
+underlying character set produce an appropriate @TeX{} sequence as far
+as possible.  The other non-graphical characters, like newline and tab,
+and all other characters which are not part of ASCII, are merely
+changed to exactly one space, with no special attempt to compress
+consecutive spaces.  Let me know how to improve this special character
+processing for @TeX{}.
+
+@end table
+
+
+@node Compatibility in ptx
+@subsection The GNU extensions to @command{ptx}
+
+This version of @command{ptx} contains a few features which do not exist in
+System V @command{ptx}.  These extra features are suppressed by using the
+@option{-G} command line option, unless overridden by other command line
+options.  Some GNU extensions cannot be recovered by overriding, so the
+simple rule is to avoid @option{-G} if you care about GNU extensions.
+Here are the differences between this program and System V @command{ptx}.
+
+@itemize @bullet
+
+@item
+This program can read many input files at once, it always writes the
+resulting concordance on standard output.  On the other hand, System V
+@command{ptx} reads only one file and sends the result to standard output
+or, if a second @var{file} parameter is given on the command, to that
+@var{file}.
+
+Having output parameters not introduced by options is a dangerous
+practice which GNU avoids as far as possible.  So, for using @command{ptx}
+portably between GNU and System V, you should always use it with a
+single input file, and always expect the result on standard output.  You
+might also want to automatically configure in a @option{-G} option to
+@command{ptx} calls in products using @command{ptx}, if the configurator finds
+that the installed @command{ptx} accepts @option{-G}.
+
+@item
+The only options available in System V @command{ptx} are options @option{-b},
+@option{-f}, @option{-g}, @option{-i}, @option{-o}, @option{-r}, @option{-t} and
+@option{-w}.  All other options are GNU extensions and are not repeated in
+this enumeration.  Moreover, some options have a slightly different
+meaning when GNU extensions are enabled, as explained below.
+
+@item
+By default, concordance output is not formatted for @command{troff} or
+@command{nroff}.  It is rather formatted for a dumb terminal.  @command{troff}
+or @command{nroff} output may still be selected through option @option{-O}.
+
+@item
+Unless @option{-R} option is used, the maximum reference width is
+subtracted from the total output line width.  With GNU extensions
+disabled, width of references is not taken into account in the output
+line width computations.
+
+@item
+All 256 bytes, even ASCII NUL bytes, are always read and
+processed from input file with no adverse effect, even if GNU extensions
+are disabled.  However, System V @command{ptx} does not accept 8-bit
+characters, a few control characters are rejected, and the tilde
+@samp{~} is also rejected.
+
+@item
+Input line length is only limited by available memory, even if GNU
+extensions are disabled.  However, System V @command{ptx} processes only
+the first 200 characters in each line.
+
+@item
+The break (non-word) characters default to be every character except all
+letters of the underlying character set, diacriticized or not.  When GNU
+extensions are disabled, the break characters default to space, tab and
+newline only.
+
+@item
+The program makes better use of output line width.  If GNU extensions
+are disabled, the program rather tries to imitate System V @command{ptx},
+but still, there are some slight disposition glitches this program does
+not completely reproduce.
+
+@item
+The user can specify both an Ignore file and an Only file.  This is not
+allowed with System V @command{ptx}.
+
+@end itemize
+
+
+@node tsort invocation
+@section @command{tsort}: Topological sort
+
+@pindex tsort
+@cindex topological sort
+
+@command{tsort} performs a topological sort on the given @var{file}, or
+standard input if no input file is given or for a @var{file} of
+@samp{-}.  For more details and some history, see @ref{tsort background}.
+Synopsis:
+
+@example
+tsort [@var{option}] [@var{file}]
+@end example
+
+@command{tsort} reads its input as pairs of strings, separated by blanks,
+indicating a partial ordering.  The output is a total ordering that
+corresponds to the given partial ordering.
+
+For example
+
+@example
+tsort <<EOF
+a b c
+d
+e f
+b c d e
+EOF
+@end example
+
+@noindent
+will produce the output
+
+@example
+a
+b
+c
+d
+e
+f
+@end example
+
+Consider a more realistic example.
+You have a large set of functions all in one file, and they may all be
+declared static except one.  Currently that one (say @code{main}) is the
+first function defined in the file, and the ones it calls directly follow
+it, followed by those they call, etc.  Let's say that you are determined
+to take advantage of prototypes, so you have to choose between declaring
+all of those functions (which means duplicating a lot of information from
+the definitions) and rearranging the functions so that as many as possible
+are defined before they are used.  One way to automate the latter process
+is to get a list for each function of the functions it calls directly.
+Many programs can generate such lists.  They describe a call graph.
+Consider the following list, in which a given line indicates that the
+function on the left calls the one on the right directly.
+
+@example
+main parse_options
+main tail_file
+main tail_forever
+tail_file pretty_name
+tail_file write_header
+tail_file tail
+tail_forever recheck
+tail_forever pretty_name
+tail_forever write_header
+tail_forever dump_remainder
+tail tail_lines
+tail tail_bytes
+tail_lines start_lines
+tail_lines dump_remainder
+tail_lines file_lines
+tail_lines pipe_lines
+tail_bytes xlseek
+tail_bytes start_bytes
+tail_bytes dump_remainder
+tail_bytes pipe_bytes
+file_lines dump_remainder
+recheck pretty_name
+@end example
+
+then you can use @command{tsort} to produce an ordering of those
+functions that satisfies your requirement.
+
+@example
+example$ tsort call-graph | tac
+dump_remainder
+start_lines
+file_lines
+pipe_lines
+xlseek
+start_bytes
+pipe_bytes
+tail_lines
+tail_bytes
+pretty_name
+write_header
+tail
+recheck
+parse_options
+tail_file
+tail_forever
+main
+@end example
+
+@command{tsort} detects any cycles in the input and writes the first cycle
+encountered to standard error.
+
+Note that for a given partial ordering, generally there is no unique
+total ordering.  In the context of the call graph above, the function
+@code{parse_options} may be placed anywhere in the list as long as it
+precedes @code{main}.
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+@exitstatus
+
+@menu
+* tsort background::            Where tsort came from.
+@end menu
+
+@node tsort background
+@subsection @command{tsort}: Background
+
+@command{tsort} exists because very early versions of the Unix linker processed
+an archive file exactly once, and in order.  As @command{ld} read each object
+in the archive, it decided whether it was needed in the program based on
+whether it defined any symbols which were undefined at that point in
+the link.
+
+This meant that dependencies within the archive had to be handled
+specially.  For example, @code{scanf} probably calls @code{read}.  That means
+that in a single pass through an archive, it was important for @code{scanf.o}
+to appear before read.o, because otherwise a program which calls
+@code{scanf} but not @code{read} might end up with an unexpected unresolved
+reference to @code{read}.
+
+The way to address this problem was to first generate a set of
+dependencies of one object file on another.  This was done by a shell
+script called @command{lorder}.  The GNU tools don't provide a version of
+lorder, as far as I know, but you can still find it in BSD
+distributions.
+
+Then you ran @command{tsort} over the @command{lorder} output, and you used the
+resulting sort to define the order in which you added objects to the archive.
+
+This whole procedure has been obsolete since about 1980, because
+Unix archives now contain a symbol table (traditionally built by
+@command{ranlib}, now generally built by @command{ar} itself), and the Unix
+linker uses the symbol table to effectively make multiple passes over
+an archive file.
+
+Anyhow, that's where tsort came from.  To solve an old problem with
+the way the linker handled archive files, which has since been solved
+in different ways.
+
+
+@node Operating on fields
+@chapter Operating on fields
+
+@menu
+* cut invocation::              Print selected parts of lines.
+* paste invocation::            Merge lines of files.
+* join invocation::             Join lines on a common field.
+@end menu
+
+
+@node cut invocation
+@section @command{cut}: Print selected parts of lines
+
+@pindex cut
+@command{cut} writes to standard output selected parts of each line of each
+input file, or standard input if no files are given or for a file name of
+@samp{-}.  Synopsis:
+
+@example
+cut @var{option}@dots{} [@var{file}]@dots{}
+@end example
+
+In the table which follows, the @var{byte-list}, @var{character-list},
+and @var{field-list} are one or more numbers or ranges (two numbers
+separated by a dash) separated by commas.  Bytes, characters, and
+fields are numbered starting at 1.  Incomplete ranges may be
+given: @option{-@var{m}} means @samp{1-@var{m}}; @samp{@var{n}-} means
+@samp{@var{n}} through end of line or last field.  The list elements
+can be repeated, can overlap, and can be specified in any order; but
+the selected input is written in the same order that it is read, and
+is written exactly once.
+
+The program accepts the following options.  Also see @ref{Common
+options}.
+
+@table @samp
+
+@item -b @var{byte-list}
+@itemx --bytes=@var{byte-list}
+@opindex -b
+@opindex --bytes
+Select for printing only the bytes in positions listed in
+@var{byte-list}.  Tabs and backspaces are treated like any other
+character; they take up 1 byte.  If an output delimiter is specified,
+(see the description of @option{--output-delimiter}), then output that
+string between ranges of selected bytes.
+
+@item -c @var{character-list}
+@itemx --characters=@var{character-list}
+@opindex -c
+@opindex --characters
+Select for printing only the characters in positions listed in
+@var{character-list}.  The same as @option{-b} for now, but
+internationalization will change that.  Tabs and backspaces are
+treated like any other character; they take up 1 character.  If an
+output delimiter is specified, (see the description of
+@option{--output-delimiter}), then output that string between ranges
+of selected bytes.
+
+@item -f @var{field-list}
+@itemx --fields=@var{field-list}
+@opindex -f
+@opindex --fields
+Select for printing only the fields listed in @var{field-list}.
+Fields are separated by a TAB character by default.  Also print any
+line that contains no delimiter character, unless the
+@option{--only-delimited} (@option{-s}) option is specified.
+
+Note @command{awk} supports more sophisticated field processing,
+like reordering fields, and handling fields aligned with blank characters.
+By default @command{awk} uses (and discards) runs of blank characters
+to separate fields, and ignores leading and trailing blanks.
+@example
+@verbatim
+awk '{print $2}'      # print the second field
+awk '{print $(NF-1)}' # print the penultimate field
+awk '{print $2,$1}'   # reorder the first two fields
+@end verbatim
+@end example
+Note while @command{cut} accepts field specifications in
+arbitrary order, output is always in the order encountered in the file.
+
+In the unlikely event that @command{awk} is unavailable,
+one can use the @command{join} command, to process blank
+characters as @command{awk} does above.
+@example
+@verbatim
+join -a1 -o 1.2     - /dev/null # print the second field
+join -a1 -o 1.2,1.1 - /dev/null # reorder the first two fields
+@end verbatim
+@end example
+
+@item -d @var{input_delim_byte}
+@itemx --delimiter=@var{input_delim_byte}
+@opindex -d
+@opindex --delimiter
+With @option{-f}, use the first byte of @var{input_delim_byte} as
+the input fields separator (default is TAB).
+
+@item -n
+@opindex -n
+Do not split multi-byte characters (no-op for now).
+
+@item -s
+@itemx --only-delimited
+@opindex -s
+@opindex --only-delimited
+For @option{-f}, do not print lines that do not contain the field separator
+character.  Normally, any line without a field separator is printed verbatim.
+
+@item --output-delimiter=@var{output_delim_string}
+@opindex --output-delimiter
+With @option{-f}, output fields are separated by @var{output_delim_string}.
+The default with @option{-f} is to use the input delimiter.
+When using @option{-b} or @option{-c} to select ranges of byte or
+character offsets (as opposed to ranges of fields),
+output @var{output_delim_string} between non-overlapping
+ranges of selected bytes.
+
+@item --complement
+@opindex --complement
+This option is a GNU extension.
+Select for printing the complement of the bytes, characters or fields
+selected with the @option{-b}, @option{-c} or @option{-f} options.
+In other words, do @emph{not} print the bytes, characters or fields
+specified via those options.  This option is useful when you have
+many fields and want to print all but a few of them.
+
+@optZeroTerminated
+
+@end table
+
+@exitstatus
+
+
+@node paste invocation
+@section @command{paste}: Merge lines of files
+
+@pindex paste
+@cindex merging files
+
+@command{paste} writes to standard output lines consisting of sequentially
+corresponding lines of each given file, separated by a TAB character.
+Standard input is used for a file name of @samp{-} or if no input files
+are given.
+
+Synopsis:
+
+@example
+paste [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+For example, with:
+@example
+$ cat num2
+1
+2
+$ cat let3
+a
+b
+c
+@end example
+
+Take lines sequentially from each file:
+@example
+$ paste num2 let3
+1       a
+2       b
+       @ c
+@end example
+
+Duplicate lines from a file:
+@example
+$ paste num2 let3 num2
+1       a      1
+2       b      2
+       @ c
+@end example
+
+Intermix lines from standard input:
+@example
+$ paste - let3 - < num2
+1       a      2
+       @ b
+       @ c
+@end example
+
+Join consecutive lines with a space:
+@example
+$ seq 4 | paste -d ' ' - -
+1 2
+3 4
+@end example
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -s
+@itemx --serial
+@opindex -s
+@opindex --serial
+Paste the lines of one file at a time rather than one line from each
+file.  Using the above example data:
+
+@example
+$ paste -s num2 let3
+1       2
+a       b       c
+@end example
+
+@item -d @var{delim-list}
+@itemx --delimiters=@var{delim-list}
+@opindex -d
+@opindex --delimiters
+Consecutively use the characters in @var{delim-list} instead of
+TAB to separate merged lines.  When @var{delim-list} is
+exhausted, start again at its beginning.  Using the above example data:
+
+@example
+$ paste -d '%_' num2 let3 num2
+1%a_1
+2%b_2
+%c_
+@end example
+
+@optZeroTerminated
+
+@end table
+
+@exitstatus
+
+
+@node join invocation
+@section @command{join}: Join lines on a common field
+
+@pindex join
+@cindex common field, joining on
+
+@command{join} writes to standard output a line for each pair of input
+lines that have identical join fields.  Synopsis:
+
+@example
+join [@var{option}]@dots{} @var{file1} @var{file2}
+@end example
+
+Either @var{file1} or @var{file2} (but not both) can be @samp{-},
+meaning standard input.  @var{file1} and @var{file2} should be
+sorted on the join fields.
+
+@example
+@group
+$ cat file1
+a 1
+b 2
+e 5
+
+$ cat file2
+a X
+e Y
+f Z
+
+$ join file1 file2
+a 1 X
+e 5 Y
+@end group
+@end example
+
+
+@noindent
+@command{join}'s default behavior (when no options are given):
+@itemize
+@item the join field is the first field in each line;
+@item fields in the input are separated by one or more blanks, with leading
+blanks on the line ignored;
+@item fields in the output are separated by a space;
+@item each output line consists of the join field, the remaining
+fields from @var{file1}, then the remaining fields from @var{file2}.
+@end itemize
+
+
+@menu
+* General options in join::      Options which affect general program behavior.
+* Sorting files for join::       Using @command{sort} before @command{join}.
+* Working with fields::          Joining on different fields.
+* Paired and unpaired lines::    Controlling @command{join}'s field matching.
+* Header lines::                 Working with header lines in files.
+* Set operations::               Union, Intersection and Difference of files.
+@end menu
+
+@node General options in join
+@subsection General options
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -a @var{file-number}
+@opindex -a
+Print a line for each unpairable line in file @var{file-number} (either
+@samp{1} or @samp{2}), in addition to the normal output.
+
+@item --check-order
+Fail with an error message if either input file is wrongly ordered.
+
+@item --nocheck-order
+Do not check that both input files are in sorted order.  This is the default.
+
+@item -e @var{string}
+@opindex -e
+Replace those output fields that are missing in the input with @var{string}.
+I.e., missing fields specified with the @option{-12jo} options.
+
+@item --header
+@opindex --header
+Treat the first line of each input file as a header line.  The header lines
+will be joined and printed as the first output line.  If @option{-o} is used to
+specify output format, the header line will be printed according to the
+specified format.  The header lines will not be checked for ordering even if
+@option{--check-order} is specified.  Also if the header lines from each file
+do not match, the heading fields from the first file will be used.
+
+@item -i
+@itemx --ignore-case
+@opindex -i
+@opindex --ignore-case
+Ignore differences in case when comparing keys.
+With this option, the lines of the input files must be ordered in the same way.
+Use @samp{sort -f} to produce this ordering.
+
+@item -1 @var{field}
+@opindex -1
+Join on field @var{field} (a positive integer) of file 1.
+
+@item -2 @var{field}
+@opindex -2
+Join on field @var{field} (a positive integer) of file 2.
+
+@item -j @var{field}
+Equivalent to @option{-1 @var{field} -2 @var{field}}.
+
+@item -o @var{field-list}
+@itemx -o auto
+If the keyword @samp{auto} is specified, infer the output format from
+the first line in each file.  This is the same as the default output format
+but also ensures the same number of fields are output for each line.
+Missing fields are replaced with the @option{-e} option and extra fields
+are discarded.
+
+Otherwise, construct each output line according to the format in
+@var{field-list}.  Each element in @var{field-list} is either the single
+character @samp{0} or has the form @var{m.n} where the file number, @var{m},
+is @samp{1} or @samp{2} and @var{n} is a positive field number.
+
+A field specification of @samp{0} denotes the join field.
+In most cases, the functionality of the @samp{0} field spec
+may be reproduced using the explicit @var{m.n} that corresponds
+to the join field.  However, when printing unpairable lines
+(using either of the @option{-a} or @option{-v} options), there is no way
+to specify the join field using @var{m.n} in @var{field-list}
+if there are unpairable lines in both files.
+To give @command{join} that functionality, POSIX invented the @samp{0}
+field specification notation.
+
+The elements in @var{field-list}
+are separated by commas or blanks.
+Blank separators typically need to be quoted for the shell.  For
+example, the commands @samp{join -o 1.2,2.2} and @samp{join -o '1.2
+2.2'} are equivalent.
+
+All output lines -- including those printed because of any @option{-a}
+or @option{-v} option -- are subject to the specified @var{field-list}.
+
+@item -t @var{char}
+Use character @var{char} as the input and output field separator.
+Treat as significant each occurrence of @var{char} in the input file.
+Use @samp{sort -t @var{char}}, without the @option{-b} option of
+@samp{sort}, to produce this ordering.  If @samp{join -t ''} is specified,
+the whole line is considered, matching the default operation of sort.
+If @samp{-t '\0'} is specified then the ASCII NUL
+character is used to delimit the fields.
+
+@item -v @var{file-number}
+Print a line for each unpairable line in file @var{file-number}
+(either @samp{1} or @samp{2}), instead of the normal output.
+
+@optZeroTerminated
+@newlineFieldSeparator
+
+@end table
+
+@exitstatus
+
+@set JOIN_COMMAND
+@checkOrderOption{join}
+@clear JOIN_COMMAND
+
+
+
+@node Sorting files for join
+@subsection Pre-sorting
+
+@command{join} requires sorted input files. Each input file should be
+sorted according to the key (=field/column number) used in
+@command{join}. The recommended sorting option is @samp{sort -k 1b,1}
+(assuming the desired key is in the first column).
+
+@noindent Typical usage:
+@example
+@group
+$ sort -k 1b,1 file1 > file1.sorted
+$ sort -k 1b,1 file2 > file2.sorted
+$ join file1.sorted file2.sorted > file3
+@end group
+@end example
+
+@vindex LC_COLLATE
+Normally, the sort order is that of the
+collating sequence specified by the @env{LC_COLLATE} locale.  Unless
+the @option{-t} option is given, the sort comparison ignores blanks at
+the start of the join field, as in @code{sort -b}.  If the
+@option{--ignore-case} option is given, the sort comparison ignores
+the case of characters in the join field, as in @code{sort -f}:
+
+@example
+@group
+$ sort -k 1bf,1 file1 > file1.sorted
+$ sort -k 1bf,1 file2 > file2.sorted
+$ join --ignore-case file1.sorted file2.sorted > file3
+@end group
+@end example
+
+The @command{sort} and @command{join} commands should use consistent
+locales and options if the output of @command{sort} is fed to
+@command{join}.  You can use a command like @samp{sort -k 1b,1} to
+sort a file on its default join field, but if you select a non-default
+locale, join field, separator, or comparison options, then you should
+do so consistently between @command{join} and @command{sort}.
+
+@noindent To avoid any locale-related issues, it is recommended to use the
+@samp{C} locale for both commands:
+
+@example
+@group
+$ LC_ALL=C sort -k 1b,1 file1 > file1.sorted
+$ LC_ALL=C sort -k 1b,1 file2 > file2.sorted
+$ LC_ALL=C join file1.sorted file2.sorted > file3
+@end group
+@end example
+
+
+@node Working with fields
+@subsection Working with fields
+
+Use @option{-1},@option{-2} to set the key fields for each of the input files.
+Ensure the preceding @command{sort} commands operated on the same fields.
+
+@noindent
+The following example joins two files, using the values from seventh field
+of the first file and the third field of the second file:
+
+@example
+@group
+$ sort -k 7b,7 file1 > file1.sorted
+$ sort -k 3b,3 file2 > file2.sorted
+$ join -1 7 -2 3 file1.sorted file2.sorted > file3
+@end group
+@end example
+
+@noindent
+If the field number is the same for both files, use @option{-j}:
+
+@example
+@group
+$ sort -k4b,4 file1 > file1.sorted
+$ sort -k4b,4 file2 > file2.sorted
+$ join -j4    file1.sorted file2.sorted > file3
+@end group
+@end example
+
+@noindent
+Both @command{sort} and @command{join} operate of whitespace-delimited
+fields. To specify a different delimiter, use @option{-t} in @emph{both}:
+
+@example
+@group
+$ sort -t, -k3b,3 file1 > file1.sorted
+$ sort -t, -k3b,3 file2 > file2.sorted
+$ join -t, -j3    file1.sorted file2.sorted > file3
+@end group
+@end example
+
+@noindent
+To specify a tab (@sc{ascii} 0x09) character instead of whitespace,
+use:@footnote{the @code{$'\t'} is supported in most modern shells.
+For older shells, use a literal tab.}
+
+@example
+@group
+$ sort -t$'\t' -k3b,3 file1 > file1.sorted
+$ sort -t$'\t' -k3b,3 file2 > file2.sorted
+$ join -t$'\t' -j3    file1.sorted file2.sorted > file3
+@end group
+@end example
+
+
+@noindent
+If @samp{join -t ''} is specified then the whole line is considered which
+matches the default operation of sort:
+
+@example
+@group
+$ sort file1 > file1.sorted
+$ sort file2 > file2.sorted
+$ join -t '' file1.sorted file2.sorted > file3
+@end group
+@end example
+
+
+@node Paired and unpaired lines
+@subsection Controlling @command{join}'s field matching
+
+In this section the @command{sort} commands are omitted for brevity.
+Sorting the files before joining is still required.
+
+@command{join}'s default behavior is to print only lines common to
+both input files. Use @option{-a} and @option{-v} to print unpairable lines
+from one or both files.
+
+@noindent
+All examples below use the following two (pre-sorted) input files:
+
+@multitable @columnfractions .5 .5
+@item
+@example
+$ cat file1
+a 1
+b 2
+@end example
+
+@tab
+@example
+$ cat file2
+a A
+c C
+@end example
+@end multitable
+
+
+@c TODO: Find better column widths that work for both HTML and PDF
+@c       and disable indentation of @example.
+@multitable @columnfractions 0.5 0.5
+
+@headitem Command @tab Outcome
+
+
+@item
+@example
+$ join file1 file2
+a 1 A
+@end example
+@tab
+common lines
+(@emph{intersection})
+
+
+
+@item
+@example
+$ join -a 1 file1 file2
+a 1 A
+b 2
+@end example
+@tab
+common lines @emph{and} unpaired
+lines from the first file
+
+
+@item
+@example
+$ join -a 2 file1 file2
+a 1 A
+c C
+@end example
+@tab
+common lines @emph{and} unpaired lines from the second file
+
+
+@item
+@example
+$ join -a 1 -a 2 file1 file2
+a 1 A
+b 2
+c C
+@end example
+@tab
+all lines (paired and unpaired) from both files
+(@emph{union}).
+@*
+see note below regarding @code{-o auto}.
+
+
+@item
+@example
+$ join -v 1 file1 file2
+b 2
+@end example
+@tab
+unpaired lines from the first file
+(@emph{difference})
+
+
+@item
+@example
+$ join -v 2 file1 file2
+c C
+@end example
+@tab
+unpaired lines from the second file
+(@emph{difference})
+
+
+@item
+@example
+$ join -v 1 -v 2 file1 file2
+b 2
+c C
+@end example
+@tab
+unpaired lines from both files, omitting common lines
+(@emph{symmetric difference}).
+
+
+@end multitable
+
+@noindent
+The @option{-o auto -e X} options are useful when dealing with unpaired lines.
+The following example prints all lines (common and unpaired) from both files.
+Without @option{-o auto} it is not easy to discern which fields originate from
+which file:
+
+@example
+$ join -a 1 -a 2 file1 file2
+a 1 A
+b 2
+c C
+
+$ join -o auto -e X -a 1 -a 2 file1 file2
+a 1 A
+b 2 X
+c X C
+@end example
+
+
+If the input has no unpairable lines, a GNU extension is
+available; the sort order can be any order that considers two fields
+to be equal if and only if the sort comparison described above
+considers them to be equal.  For example:
+
+@example
+@group
+$ cat file1
+a a1
+c c1
+b b1
+
+$ cat file2
+a a2
+c c2
+b b2
+
+$ join file1 file2
+a a1 a2
+c c1 c2
+b b1 b2
+@end group
+@end example
+
+
+@node Header lines
+@subsection Header lines
+
+The @option{--header} option can be used when the files to join
+have a header line which is not sorted:
+
+@example
+@group
+$ cat file1
+Name     Age
+Alice    25
+Charlie  34
+
+$ cat file2
+Name   Country
+Alice  France
+Bob    Spain
+
+$ join --header -o auto -e NA -a1 -a2 file1 file2
+Name     Age   Country
+Alice    25    France
+Bob      NA    Spain
+Charlie  34    NA
+@end group
+@end example
+
+
+To sort a file with a header line, use GNU @command{sed -u}.
+The following example sort the files but keeps the first line of each
+file in place:
+
+@example
+@group
+$ ( sed -u 1q ; sort -k2b,2 ) < file1 > file1.sorted
+$ ( sed -u 1q ; sort -k2b,2 ) < file2 > file2.sorted
+$ join --header -o auto -e NA -a1 -a2 file1.sorted file2.sorted > file3
+@end group
+@end example
+
+@node Set operations
+@subsection Union, Intersection and Difference of files
+
+Combine @command{sort}, @command{uniq} and @command{join} to
+perform the equivalent of set operations on files:
+
+@c From https://www.pixelbeat.org/cmdline.html#sets
+@multitable @columnfractions 0.5 0.5
+@headitem Command @tab outcome
+@item @code{sort -u file1 file2}
+@tab Union of unsorted files
+
+@item @code{sort file1 file2 | uniq -d}
+@tab Intersection of unsorted files
+
+@item @code{sort file1 file1 file2 | uniq -u}
+@tab Difference of unsorted files
+
+@item @code{sort file1 file2 | uniq -u}
+@tab Symmetric Difference of unsorted files
+
+@item @code{join -t '' -a1 -a2 file1 file2}
+@tab Union of sorted files
+
+@item @code{join -t '' file1 file2}
+@tab Intersection of sorted files
+
+@item @code{join -t '' -v2 file1 file2}
+@tab Difference of sorted files
+
+@item @code{join -t '' -v1 -v2 file1 file2}
+@tab Symmetric Difference of sorted files
+
+@end multitable
+
+All examples above operate on entire lines and not on specific fields:
+@command{sort} without @option{-k} and @command{join -t ''} both consider
+entire lines as the key.
+
+
+@node Operating on characters
+@chapter Operating on characters
+
+@cindex operating on characters
+
+These commands operate on individual characters.
+
+@menu
+* tr invocation::               Translate, squeeze, and/or delete characters.
+* expand invocation::           Convert tabs to spaces.
+* unexpand invocation::         Convert spaces to tabs.
+@end menu
+
+
+@node tr invocation
+@section @command{tr}: Translate, squeeze, and/or delete characters
+
+@pindex tr
+
+Synopsis:
+
+@example
+tr [@var{option}]@dots{} @var{string1} [@var{string2}]
+@end example
+
+@command{tr} copies standard input to standard output, performing
+one of the following operations:
+
+@itemize @bullet
+@item
+translate, and optionally squeeze repeated characters in the result,
+@item
+squeeze repeated characters,
+@item
+delete characters,
+@item
+delete characters, then squeeze repeated characters from the result.
+@end itemize
+
+The @var{string1} and @var{string2} operands define arrays of
+characters @var{array1} and @var{array2}.  By default @var{array1}
+lists input characters that @command{tr} operates on, and @var{array2}
+lists corresponding translations.  In some cases the second operand is
+omitted.
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+
+@item -c
+@itemx -C
+@itemx --complement
+@opindex -c
+@opindex -C
+@opindex --complement
+Instead of @var{array1}, use its complement (all characters not
+specified by @var{string1}), in ascending order.  Use this option with
+caution in multibyte locales where its meaning is not always clear
+or portable; see @ref{Character arrays}.
+
+@item -d
+@itemx --delete
+@opindex -d
+@opindex --delete
+Delete characters in @var{array1}; do not translate.
+
+@item -s
+@itemx --squeeze-repeats
+@opindex -s
+@opindex --squeeze-repeats
+Replace each sequence of a repeated character that is listed in
+the last specified @var{array}, with a single occurrence of that character.
+
+@item -t
+@itemx --truncate-set1
+@opindex -t
+@opindex --truncate-set1
+Truncate @var{array1} to the length of @var{array2}.
+
+@end table
+
+
+@exitstatus
+
+@menu
+* Character arrays::            Specifying arrays of characters.
+* Translating::                 Changing characters to other characters.
+* Squeezing and deleting::      Removing characters.
+@end menu
+
+
+@node Character arrays
+@subsection Specifying arrays of characters
+
+@cindex arrays of characters in @command{tr}
+
+The @var{string1} and @var{string2} operands are not regular
+expressions, even though they may look similar.  Instead, they
+merely represent arrays of characters.  As a GNU extension to POSIX,
+an empty string operand represents an empty array of characters.
+
+The interpretation of @var{string1} and @var{string2} depends on locale.
+GNU @command{tr} fully supports only safe single-byte locales,
+where each possible input byte represents a single character.
+Unfortunately, this means GNU @command{tr} will not handle commands
+like @samp{tr @"o @L{}} the way you might expect,
+since (assuming a UTF-8 encoding) this is equivalent to
+@samp{tr '\303\266' '\305\201'} and GNU @command{tr} will
+simply transliterate all @samp{\303} bytes to @samp{\305} bytes, etc.
+POSIX does not clearly specify the behavior of @command{tr} in locales
+where characters are represented by byte sequences instead of by
+individual bytes, or where data might contain invalid bytes that are
+encoding errors.  To avoid problems in this area, you can run
+@command{tr} in a safe single-byte locale by using a shell command
+like @samp{LC_ALL=C tr} instead of plain @command{tr}.
+
+Although most characters simply represent themselves in @var{string1}
+and @var{string2}, the strings can contain shorthands listed below,
+for convenience.  Some shorthands can be used only in @var{string1} or
+@var{string2}, as noted below.
+
+@table @asis
+
+@item Backslash escapes
+@cindex backslash escapes
+
+The following backslash escape sequences are recognized:
+
+@table @samp
+@item \a
+Bell (BEL, Control-G).
+@item \b
+Backspace (BS, Control-H).
+@item \f
+Form feed (FF, Control-L).
+@item \n
+Newline (LF, Control-J).
+@item \r
+Carriage return (CR, Control-M).
+@item \t
+Tab (HT, Control-I).
+@item \v
+Vertical tab (VT, Control-K).
+@item \@var{ooo}
+The eight-bit byte with the value given by @var{ooo}, which is the longest
+sequence of one to three octal digits following the backslash.
+For portability, @var{ooo} should represent a value that fits in eight bits.
+As a GNU extension to POSIX, if the value would not fit, then only the
+first two digits of @var{ooo} are used, e.g., @samp{\400}
+is equivalent to @samp{\0400} and represents a two-byte sequence.
+@item \\
+A backslash.
+@end table
+
+It is an error if no character follows an unescaped backslash.
+As a GNU extension, a backslash followed by a character not listed
+above is interpreted as that character, removing any special
+significance; this can be used to escape the characters
+@samp{[} and @samp{-} when they would otherwise be special.
+
+@item Ranges
+@cindex ranges
+
+The notation @samp{@var{m}-@var{n}} expands to the characters
+from @var{m} through @var{n}, in ascending order.  @var{m} should
+not collate after @var{n}; if it does, an error results.  As an example,
+@samp{0-9} is the same as @samp{0123456789}.
+
+GNU @command{tr} does not support the System V syntax that uses square
+brackets to enclose ranges.  Translations specified in that format
+sometimes work as expected, since the brackets are often transliterated
+to themselves.  However, they should be avoided because they sometimes
+behave unexpectedly.  For example, @samp{tr -d '[0-9]'} deletes brackets
+as well as digits.
+
+Many historically common and even accepted uses of ranges are not fully
+portable.  For example, on EBCDIC hosts using the @samp{A-Z}
+range will not do what most would expect because @samp{A} through @samp{Z}
+are not contiguous as they are in ASCII@.
+One way to work around this is to use character classes (see below).
+Otherwise, it is most portable (and most ugly) to enumerate the members
+of the ranges.
+
+@item Repeated characters
+@cindex repeated characters
+
+The notation @samp{[@var{c}*@var{n}]} in @var{string2} expands to @var{n}
+copies of character @var{c}.  Thus, @samp{[y*6]} is the same as
+@samp{yyyyyy}.  The notation @samp{[@var{c}*]} in @var{string2} expands
+to as many copies of @var{c} as are needed to make @var{array2} as long as
+@var{array1}.  If @var{n} begins with @samp{0}, it is interpreted in
+octal, otherwise in decimal.  A zero-valued @var{n} is treated as if
+it were absent.
+
+@item Character classes
+@cindex character classes
+
+The notation @samp{[:@var{class}:]} expands to all characters in
+the (predefined) class @var{class}.  When the @option{--delete} (@option{-d})
+and @option{--squeeze-repeats} (@option{-s}) options are both given, any
+character class can be used in @var{string2}.  Otherwise, only the
+character classes @code{lower} and @code{upper} are accepted in
+@var{string2}, and then only if the corresponding character class
+(@code{upper} and @code{lower}, respectively) is specified in the same
+relative position in @var{string1}.  Doing this specifies case conversion.
+Except for case conversion, a class's characters appear in no particular order.
+The class names are given below; an error results when an invalid class
+name is given.
+
+@table @code
+@item alnum
+@opindex alnum
+Letters and digits.
+@item alpha
+@opindex alpha
+Letters.
+@item blank
+@opindex blank
+Horizontal whitespace.
+@item cntrl
+@opindex cntrl
+Control characters.
+@item digit
+@opindex digit
+Digits.
+@item graph
+@opindex graph
+Printable characters, not including space.
+@item lower
+@opindex lower
+Lowercase letters.
+@item print
+@opindex print
+Printable characters, including space.
+@item punct
+@opindex punct
+Punctuation characters.
+@item space
+@opindex space
+Horizontal or vertical whitespace.
+@item upper
+@opindex upper
+Uppercase letters.
+@item xdigit
+@opindex xdigit
+Hexadecimal digits.
+@end table
+
+@item Equivalence classes
+@cindex equivalence classes
+
+The syntax @samp{[=@var{c}=]} expands to all characters equivalent to
+@var{c}, in no particular order.  These equivalence classes are
+allowed in @var{string2} only when @option{--delete} (@option{-d}) and
+@option{--squeeze-repeats} @option{-s} are both given.
+
+Although equivalence classes are intended to support non-English alphabets,
+there seems to be no standard way to define them or determine their
+contents.  Therefore, they are not fully implemented in GNU @command{tr};
+each character's equivalence class consists only of that character,
+which is of no particular use.
+
+@end table
+
+
+@node Translating
+@subsection Translating
+
+@cindex translating characters
+
+@command{tr} performs translation when @var{string1} and @var{string2} are
+both given and the @option{--delete} (@option{-d}) option is not given.
+@command{tr} translates each character of its input that is in @var{array1}
+to the corresponding character in @var{array2}.  Characters not in
+@var{array1} are passed through unchanged.
+
+As a GNU extension to POSIX, when a character appears more than once
+in @var{array1}, only the final instance is used.  For example, these
+two commands are equivalent:
+
+@example
+tr aaa xyz
+tr a z
+@end example
+
+A common use of @command{tr} is to convert lowercase characters to
+uppercase.  This can be done in many ways.  Here are three of them:
+
+@example
+tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
+tr a-z A-Z
+tr '[:lower:]' '[:upper:]'
+@end example
+
+@noindent
+However, ranges like @code{a-z} are not portable outside the C locale.
+
+When @command{tr} is performing translation, @var{array1} and @var{array2}
+typically have the same length.  If @var{array1} is shorter than
+@var{array2}, the extra characters at the end of @var{array2} are ignored.
+
+On the other hand, making @var{array1} longer than @var{array2} is not
+portable; POSIX says that the result is undefined.  In this situation,
+BSD @command{tr} pads @var{array2} to the length of @var{array1} by repeating
+the last character of @var{array2} as many times as necessary.  System V
+@command{tr} truncates @var{array1} to the length of @var{array2}.
+
+By default, GNU @command{tr} handles this case like BSD @command{tr}.
+When the @option{--truncate-set1} (@option{-t}) option is given,
+GNU @command{tr} handles this case like the System V @command{tr}
+instead.  This option is ignored for operations other than translation.
+
+Acting like System V @command{tr} in this case breaks the relatively common
+BSD idiom:
+
+@example
+tr -cs A-Za-z0-9 '\012'
+@end example
+
+@noindent
+because it converts only zero bytes (the first element in the
+complement of @var{array1}), rather than all non-alphanumerics, to
+newlines.
+
+@noindent
+By the way, the above idiom is not portable because it uses ranges, and
+it assumes that the octal code for newline is 012.  Here is a better
+way to write it:
+
+@example
+tr -cs '[:alnum:]' '[\n*]'
+@end example
+
+
+@node Squeezing and deleting
+@subsection Squeezing repeats and deleting
+
+@cindex squeezing repeat characters
+@cindex deleting characters
+@cindex removing characters
+
+When given just the @option{--delete} (@option{-d}) option, @command{tr}
+removes any input characters that are in @var{array1}.
+
+When given just the @option{--squeeze-repeats} (@option{-s}) option
+and not translating, @command{tr} replaces each input sequence of a
+repeated character that is in @var{array1} with a single occurrence of
+that character.
+
+When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr}
+first performs any deletions using @var{array1}, then squeezes repeats
+from any remaining characters using @var{array2}.
+
+The @option{--squeeze-repeats} option may also be used when translating,
+in which case @command{tr} first performs translation, then squeezes
+repeats from any remaining characters using @var{array2}.
+
+Here are some examples to illustrate various combinations of options:
+
+@itemize @bullet
+
+@item
+Remove all zero bytes:
+
+@example
+tr -d '\0'
+@end example
+
+@item
+Put all words on lines by themselves.  This converts all
+non-alphanumeric characters to newlines, then squeezes each string
+of repeated newlines into a single newline:
+
+@example
+tr -cs '[:alnum:]' '[\n*]'
+@end example
+
+@item
+Convert each sequence of repeated newlines to a single newline.
+I.e., delete empty lines:
+
+@example
+tr -s '\n'
+@end example
+
+@item
+Find doubled occurrences of words in a document.
+@c Separate the following two "the"s, so typo checkers don't complain.
+For example, people often write ``the @w{}the'' with the repeated words
+separated by a newline.  The Bourne shell script below works first
+by converting each sequence of punctuation and blank characters to a
+single newline.  That puts each ``word'' on a line by itself.
+Next it maps all uppercase characters to lower case, and finally it
+runs @command{uniq} with the @option{-d} option to print out only the words
+that were repeated.
+
+@example
+#!/bin/sh
+cat -- "$@@" \
+  | tr -s '[:punct:][:blank:]' '[\n*]' \
+  | tr '[:upper:]' '[:lower:]' \
+  | uniq -d
+@end example
+
+@item
+Deleting a small set of characters is usually straightforward.  For example,
+to remove all @samp{a}s, @samp{x}s, and @samp{M}s you would do this:
+
+@example
+tr -d axM
+@end example
+
+However, when @samp{-} is one of those characters, it can be tricky because
+@samp{-} has special meanings.  Performing the same task as above but also
+removing all @samp{-} characters, we might try @code{tr -d -axM}, but
+that would fail because @command{tr} would try to interpret @option{-a} as
+a command-line option.  Alternatively, we could try putting the hyphen
+inside the string, @code{tr -d a-xM}, but that wouldn't work either because
+it would make @command{tr} interpret @code{a-x} as the range of characters
+@samp{a}@dots{}@samp{x} rather than the three.
+One way to solve the problem is to put the hyphen at the end of the list
+of characters:
+
+@example
+tr -d axM-
+@end example
+
+Or you can use @samp{--} to terminate option processing:
+
+@example
+tr -d -- -axM
+@end example
+
+@end itemize
+
+
+@node expand invocation
+@section @command{expand}: Convert tabs to spaces
+
+@pindex expand
+@cindex tabs to spaces, converting
+@cindex converting tabs to spaces
+
+@command{expand} writes the contents of each given @var{file}, or standard
+input if none are given or for a @var{file} of @samp{-}, to standard
+output, with tab characters converted to the appropriate number of
+spaces.  Synopsis:
+
+@example
+expand [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+By default, @command{expand} converts all tabs to spaces.  It preserves
+backspace characters in the output; they decrement the column count for
+tab calculations.  The default action is equivalent to @option{-t 8} (set
+tabs every 8 columns).
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -t @var{tab1}[,@var{tab2}]@dots{}
+@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
+@opindex -t
+@opindex --tabs
+@cindex tab stops, setting
+If only one tab stop is given, set the tabs @var{tab1} spaces apart
+(default is 8).  Otherwise, set the tabs at columns @var{tab1},
+@var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the
+last tab stop given with single spaces.
+@macro gnuExpandTabs
+Tab stops can be separated by blanks as well as by commas.
+
+As a GNU extension the last @var{tab} specified can be prefixed
+with a @samp{/} to indicate a tab size to use for remaining positions.
+For example, @option{--tabs=2,4,/8} will set tab stops at position 2 and 4,
+and every multiple of 8 after that.
+
+Also the last @var{tab} specified can be prefixed with a @samp{+} to indicate
+a tab size to use for remaining positions, offset from the final explicitly
+specified tab stop.
+For example, to ignore the 1 character gutter present in diff output,
+one can specify a 1 character offset using @option{--tabs=1,+8},
+which will set tab stops at positions 1,9,17,@dots{}
+@end macro
+@gnuExpandTabs
+
+
+For compatibility, GNU @command{expand} also accepts the obsolete
+option syntax, @option{-@var{t1}[,@var{t2}]@dots{}}.  New scripts
+should use @option{-t @var{t1}[,@var{t2}]@dots{}} instead.
+
+@item -i
+@itemx --initial
+@opindex -i
+@opindex --initial
+@cindex initial tabs, converting
+Only convert initial tabs (those that precede all non-space or non-tab
+characters) on each line to spaces.
+
+@end table
+
+@exitstatus
+
+
+@node unexpand invocation
+@section @command{unexpand}: Convert spaces to tabs
+
+@pindex unexpand
+
+@command{unexpand} writes the contents of each given @var{file}, or
+standard input if none are given or for a @var{file} of @samp{-}, to
+standard output, converting blanks at the beginning of each line into
+as many tab characters as needed.  In the default POSIX
+locale, a @dfn{blank} is a space or a tab; other locales may specify
+additional blank characters.  Synopsis:
+
+@example
+unexpand [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+By default, @command{unexpand} converts only initial blanks (those
+that precede all non-blank characters) on each line.  It
+preserves backspace characters in the output; they decrement the column
+count for tab calculations.  By default, tabs are set at every 8th
+column.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -t @var{tab1}[,@var{tab2}]@dots{}
+@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{}
+@opindex -t
+@opindex --tabs
+If only one tab stop is given, set the tabs @var{tab1} columns apart
+instead of the default 8.  Otherwise, set the tabs at columns
+@var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave blanks
+beyond the tab stops given unchanged.
+@gnuExpandTabs
+
+This option implies the @option{-a} option.
+
+For compatibility, GNU @command{unexpand} supports the obsolete option syntax,
+@option{-@var{tab1}[,@var{tab2}]@dots{}}, where tab stops must be
+separated by commas.  (Unlike @option{-t}, this obsolete option does
+not imply @option{-a}.)  New scripts should use @option{--first-only -t
+@var{tab1}[,@var{tab2}]@dots{}} instead.
+
+@item -a
+@itemx --all
+@opindex -a
+@opindex --all
+Also convert all sequences of two or more blanks just before a tab stop,
+even if they occur after non-blank characters in a line.
+
+@end table
+
+@exitstatus
+
+
+@node Directory listing
+@chapter Directory listing
+
+This chapter describes the @command{ls} command and its variants @command{dir}
+and @command{vdir}, which list information about files.
+
+@menu
+* ls invocation::               List directory contents.
+* dir invocation::              Briefly ls.
+* vdir invocation::             Verbosely ls.
+* dircolors invocation::        Color setup for ls, etc.
+@end menu
+
+
+@node ls invocation
+@section @command{ls}: List directory contents
+
+@pindex ls
+@cindex directory listing
+
+The @command{ls} program lists information about files (of any type,
+including directories).  Options and file arguments can be intermixed
+arbitrarily, as usual.  Later options override earlier options that
+are incompatible.
+
+For non-option command-line arguments that are directories, by default
+@command{ls} lists the contents of directories, not recursively, and
+omitting files with names beginning with @samp{.}.  For other non-option
+arguments, by default @command{ls} lists just the file name.  If no
+non-option argument is specified, @command{ls} operates on the current
+directory, acting as if it had been invoked with a single argument of @samp{.}.
+
+@vindex LC_ALL
+By default, the output is sorted alphabetically, according to the locale
+settings in effect.@footnote{If you use a non-POSIX
+locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may
+produce output that is sorted differently than you're accustomed to.
+In that case, set the @env{LC_ALL} environment variable to @samp{C}.}
+If standard output is
+a terminal, the output is in columns (sorted vertically) and control
+characters are output as question marks; otherwise, the output is listed
+one per line and control characters are output as-is.
+
+Because @command{ls} is such a fundamental program, it has accumulated many
+options over the years.  They are described in the subsections below;
+within each section, options are listed alphabetically (ignoring case).
+The division of options into the subsections is not absolute, since some
+options affect more than one aspect of @command{ls}'s operation.
+
+@cindex exit status of @command{ls}
+Exit status:
+
+@display
+0 success
+1 minor problems  (e.g., failure to access a file or directory not
+  specified as a command line argument.  This happens when listing a
+  directory in which entries are actively being removed or renamed.)
+2 serious trouble (e.g., memory exhausted, invalid option, failure
+  to access a file or directory specified as a command line argument
+  or a directory loop)
+@end display
+
+Also see @ref{Common options}.
+
+@menu
+* Which files are listed::
+* What information is listed::
+* Sorting the output::
+* General output formatting::
+* Formatting file timestamps::
+* Formatting the file names::
+@end menu
+
+
+@node Which files are listed
+@subsection Which files are listed
+
+These options determine which files @command{ls} lists information for.
+By default, @command{ls} lists files and the contents of any
+directories on the command line, except that in directories it ignores
+files whose names start with @samp{.}.
+
+@table @samp
+
+@item -a
+@itemx --all
+@opindex -a
+@opindex --all
+In directories, do not ignore file names that start with @samp{.}.
+
+@item -A
+@itemx --almost-all
+@opindex -A
+@opindex --almost-all
+In directories, do not ignore all file names that start with @samp{.};
+ignore only @file{.} and @file{..}.  The @option{--all} (@option{-a})
+option overrides this option.
+
+@item -B
+@itemx --ignore-backups
+@opindex -B
+@opindex --ignore-backups
+@cindex backup files, ignoring
+In directories, ignore files that end with @samp{~}.  This option is
+equivalent to @samp{--ignore='*~' --ignore='.*~'}.
+
+@item -d
+@itemx --directory
+@opindex -d
+@opindex --directory
+List just the names of directories, as with other types of files, rather
+than listing their contents.
+@c The following sentence is the same as the one for -F.
+Do not follow symbolic links listed on the
+command line unless the @option{--dereference-command-line} (@option{-H}),
+@option{--dereference} (@option{-L}), or
+@option{--dereference-command-line-symlink-to-dir} options are specified.
+
+@item -H
+@itemx --dereference-command-line
+@opindex -H
+@opindex --dereference-command-line
+@cindex symbolic links, dereferencing
+If a command line argument specifies a symbolic link, show information
+for the file the link references rather than for the link itself.
+
+@item --dereference-command-line-symlink-to-dir
+@opindex --dereference-command-line-symlink-to-dir
+@cindex symbolic links, dereferencing
+Do not dereference symbolic links, with one exception:
+if a command line argument specifies a symbolic link that refers to
+a directory, show information for that directory rather than for the
+link itself.
+This is the default behavior unless long format is being used
+or any of the following options is in effect:
+@option{--classify} (@option{-F}),
+@option{--directory} (@option{-d}),
+@option{--dereference} (@option{-L}), or
+@option{--dereference-command-line} (@option{-H})).
+
+@item --group-directories-first
+@opindex --group-directories-first
+Group all the directories before the files and then sort the
+directories and the files separately using the selected sort key
+(see @option{--sort} option).
+That is, this option specifies a primary sort key,
+and the @option{--sort} option specifies a secondary key.
+However, any use of @option{--sort=none}
+(@option{-U}) disables this option altogether.
+
+@item --hide=PATTERN
+@opindex --hide=@var{pattern}
+In directories, ignore files whose names match the shell pattern
+@var{pattern}, unless the @option{--all} (@option{-a}) or
+@option{--almost-all} (@option{-A}) is also given.  This
+option acts like @option{--ignore=@var{pattern}} except that it has no
+effect if @option{--all} (@option{-a}) or @option{--almost-all}
+(@option{-A}) is also given.
+
+This option can be useful in shell aliases.  For example, if
+@command{lx} is an alias for @samp{ls --hide='*~'} and @command{ly} is
+an alias for @samp{ls --ignore='*~'}, then the command @samp{lx -A}
+lists the file @file{README~} even though @samp{ly -A} would not.
+
+@item -I @var{pattern}
+@itemx --ignore=@var{pattern}
+@opindex -I
+@opindex --ignore=@var{pattern}
+In directories, ignore files whose names match the shell pattern
+(not regular expression) @var{pattern}.  As
+in the shell, an initial @samp{.} in a file name does not match a
+wildcard at the start of @var{pattern}.  Sometimes it is useful
+to give this option several times.  For example,
+
+@example
+$ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
+@end example
+
+The first option ignores names of length 3 or more that start with @samp{.},
+the second ignores all two-character names that start with @samp{.}
+except @samp{..}, and the third ignores names that start with @samp{#}.
+
+@item -L
+@itemx --dereference
+@opindex -L
+@opindex --dereference
+@cindex symbolic links, dereferencing
+When showing file information for a symbolic link, show information
+for the file the link references rather than the link itself.
+However, even with this option, @command{ls} still prints the name
+of the link itself, not the name of the file that the link points to.
+
+@item -R
+@itemx --recursive
+@opindex -R
+@opindex --recursive
+@cindex recursive directory listing
+@cindex directory listing, recursive
+List the contents of all directories recursively.
+
+@end table
+
+
+@node What information is listed
+@subsection What information is listed
+
+These options affect the information that @command{ls} displays.  By
+default, only file names are shown.
+
+@table @samp
+
+@item --author
+@opindex --author
+@cindex hurd, author, printing
+In long format, list each file's author.
+In GNU/Hurd, file authors can differ from their owners, but in other
+operating systems the two are the same.
+
+@item -D
+@itemx --dired
+@opindex -D
+@opindex --dired
+@cindex dired Emacs mode support
+Print an additional line after the main output:
+
+@example
+//DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{}
+@end example
+
+@noindent
+The @var{begn} and @var{endn} are unsigned integers that record the
+byte position of the beginning and end of each file name in the output.
+This makes it easy for Emacs to find the names, even when they contain
+unusual characters such as space or newline, without fancy searching.
+
+If directories are being listed recursively via
+@option{--recursive} (@option{-R}), output a similar
+line with offsets for each subdirectory name:
+
+@example
+//SUBDIRED// @var{beg1} @var{end1} @dots{}
+@end example
+
+Finally, output a line of the form:
+
+@example
+//DIRED-OPTIONS// --quoting-style=@var{word}
+@end example
+
+@noindent
+where @var{word} is the quoting style (@pxref{Formatting the file names}).
+
+Here is an actual example:
+
+@example
+$ mkdir -p a/sub/deeper a/sub2
+$ touch a/f1 a/f2
+$ touch a/sub/deeper/file
+$ ls -gloRF --dired a
+  a:
+  total 8
+  -rw-r--r-- 1    0 Jun 10 12:27 f1
+  -rw-r--r-- 1    0 Jun 10 12:27 f2
+  drwxr-xr-x 3 4096 Jun 10 12:27 sub/
+  drwxr-xr-x 2 4096 Jun 10 12:27 sub2/
+
+  a/sub:
+  total 4
+  drwxr-xr-x 2 4096 Jun 10 12:27 deeper/
+
+  a/sub/deeper:
+  total 0
+  -rw-r--r-- 1 0 Jun 10 12:27 file
+
+  a/sub2:
+  total 0
+//DIRED// 48 50 84 86 120 123 158 162 217 223 282 286
+//SUBDIRED// 2 3 167 172 228 240 290 296
+//DIRED-OPTIONS// --quoting-style=literal
+@end example
+
+The pairs of offsets on the @samp{//DIRED//} line above delimit
+these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper},
+@file{file}.
+The offsets on the @samp{//SUBDIRED//} line delimit the following
+directory names: @file{a}, @file{a/sub}, @file{a/sub/deeper}, @file{a/sub2}.
+
+Here is an example of how to extract the fifth entry name, @samp{deeper},
+corresponding to the pair of offsets, 222 and 228:
+
+@example
+$ ls -gloRF --dired a > out
+$ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo
+deeper
+@end example
+
+Although the listing above includes a trailing slash
+for the @samp{deeper} entry, the offsets select the name without
+the trailing slash.  However, if you invoke @command{ls} with @option{--dired}
+(@option{-D}) along with an option like
+@option{--escape} (@option{-b}) and operate
+on a file whose name contains special characters, the backslash
+@emph{is} included:
+
+@example
+$ touch 'a b'
+$ ls -blog --dired 'a b'
+  -rw-r--r-- 1 0 Jun 10 12:28 a\ b
+//DIRED// 30 34
+//DIRED-OPTIONS// --quoting-style=escape
+@end example
+
+If you use a quoting style like @option{--quoting-style=c} (@option{-Q})
+that adds quote marks, then the offsets include the quote marks.
+So beware that the user may select the quoting style via the environment
+variable @env{QUOTING_STYLE}@.  Hence, applications using @option{--dired}
+should either specify an explicit @option{--quoting-style=literal}
+(@option{-N}) option on the command line, or else be
+prepared to parse the escaped names.
+
+The @option{--dired} (@option{-D}) option has well-defined behavior
+only when long format is in effect and hyperlinks are disabled (e.g.,
+@option{--hyperlink=none}).
+
+@item --full-time
+@opindex --full-time
+Produce long format, and list times in full.  It is
+equivalent to using @option{--format=long} (@option{-l}) with
+@option{--time-style=full-iso} (@pxref{Formatting file timestamps}).
+
+@item -g
+@opindex -g
+Produce long format, but omit owner information.
+
+@item -G
+@itemx --no-group
+@opindex -G
+@opindex --no-group
+Inhibit display of group information in long format.
+(This is the default in some non-GNU versions of @command{ls}, so we
+provide this option for compatibility.)
+
+@optHumanReadable
+
+@item -i
+@itemx --inode
+@opindex -i
+@opindex --inode
+@cindex inode number, printing
+Print the inode number (also called the file serial number and index
+number) of each file to the left of the file name.  (This number
+uniquely identifies each file within a particular file system.)
+
+@item -l
+@itemx --format=long
+@itemx --format=verbose
+@opindex -l
+@opindex --format
+@opindex long ls @r{format}
+@opindex verbose ls @r{format}
+Produce long format.
+In addition to the name of each file, print the file type, file mode bits,
+number of hard links, owner name, group name, size, and
+timestamp (@pxref{Formatting file timestamps}), normally
+the modification timestamp (the mtime, @pxref{File timestamps}).
+If the owner or group name cannot be determined, print
+the owner or group ID instead, right-justified as a cue
+that it is a number rather than a textual name.
+Print question marks for other information that
+cannot be determined.
+
+Normally the size is printed as a byte count without punctuation, but
+this can be overridden (@pxref{Block size}).
+For example, @option{--human-readable} (@option{-h})
+prints an abbreviated, human-readable count, and
+@samp{--block-size="'1"} prints a byte count with the thousands
+separator of the current locale.
+
+For each directory that is listed, preface the files with a line
+@samp{total @var{blocks}}, where @var{blocks} is the file system allocation
+for all files in that directory.  The block size currently defaults to 1024
+bytes, but this can be overridden (@pxref{Block size}).
+The @var{blocks} computed counts each hard link separately;
+this is arguably a deficiency.
+
+The file type is one of the following characters:
+
+@c The commented-out entries are ones we're not sure about.
+
+@table @samp
+@item -
+regular file
+@item b
+block special file
+@item c
+character special file
+@item C
+high performance (``contiguous data'') file
+@item d
+directory
+@item D
+door (Solaris)
+@c @item F
+@c semaphore, if this is a distinct file type
+@item l
+symbolic link
+@c @item m
+@c multiplexed file (7th edition Unix; obsolete)
+@item M
+off-line (``migrated'') file (Cray DMF)
+@item n
+network special file (HP-UX)
+@item p
+FIFO (named pipe)
+@item P
+port (Solaris)
+@c @item Q
+@c message queue, if this is a distinct file type
+@item s
+socket
+@c @item S
+@c shared memory object, if this is a distinct file type
+@c @item T
+@c typed memory object, if this is a distinct file type
+@c @item w
+@c whiteout (4.4BSD; not implemented)
+@item ?
+some other file type
+@end table
+
+@cindex permissions, output by @command{ls}
+The file mode bits listed are similar to symbolic mode specifications
+(@pxref{Symbolic Modes}).  But @command{ls} combines multiple bits into the
+third character of each set of permissions as follows:
+
+@table @samp
+@item s
+If the set-user-ID or set-group-ID bit and the corresponding executable bit
+are both set.
+
+@item S
+If the set-user-ID or set-group-ID bit is set but the corresponding
+executable bit is not set.
+
+@item t
+If the restricted deletion flag or sticky bit, and the
+other-executable bit, are both set.  The restricted deletion flag is
+another name for the sticky bit.  @xref{Mode Structure}.
+
+@item T
+If the restricted deletion flag or sticky bit is set but the
+other-executable bit is not set.
+
+@item x
+If the executable bit is set and none of the above apply.
+
+@item -
+Otherwise.
+@end table
+
+Following the file mode bits is a single character that specifies
+whether an alternate access method such as an access control list
+applies to the file.  When the character following the file mode bits is a
+space, there is no alternate access method.  When it is a printing
+character, then there is such a method.
+
+GNU @command{ls} uses a @samp{.} character to indicate a file
+with a security context, but no other alternate access method.
+
+A file with any other combination of alternate access methods
+is marked with a @samp{+} character.
+
+@item -n
+@itemx --numeric-uid-gid
+@opindex -n
+@opindex --numeric-uid-gid
+@cindex numeric uid and gid
+@cindex numeric user and group IDs
+Produce long format, but
+display right-justified numeric user and group IDs
+instead of left-justified owner and group names.
+
+@item -o
+@opindex -o
+Produce long format, but omit group information.
+It is equivalent to using @option{--format=long} (@option{-l})
+with @option{--no-group} (@option{-G}).
+
+@item -s
+@itemx --size
+@opindex -s
+@opindex --size
+@cindex file system allocation
+@cindex size of files, reporting
+Print the file system allocation of each file to the left of the file name.
+This is the amount of file system space used by the file, which is usually a
+bit more than the file's size, but it can be less if the file has holes.
+
+Normally the allocation is printed in units of
+1024 bytes, but this can be overridden (@pxref{Block size}).
+
+@cindex NFS mounts from BSD to HP-UX
+For files that are NFS-mounted from an HP-UX system to a BSD system,
+this option reports sizes that are half the correct values.  On HP-UX
+systems, it reports sizes that are twice the correct values for files
+that are NFS-mounted from BSD systems.  This is due to a flaw in HP-UX;
+it also affects the HP-UX @command{ls} program.
+
+@optSi
+
+@item -Z
+@itemx --context
+@opindex -Z
+@opindex --context
+@cindex SELinux
+@cindex security context
+Display the SELinux security context or @samp{?} if none is found.
+In long format, print the security context to the left of the size column.
+
+@end table
+
+
+@node Sorting the output
+@subsection Sorting the output
+
+@cindex sorting @command{ls} output
+These options change the order in which @command{ls} sorts the information
+it outputs.  By default, sorting is done by character code
+(e.g., ASCII order).
+
+@table @samp
+
+@item -c
+@itemx --time=ctime
+@itemx --time=status
+@opindex -c
+@opindex --time
+@opindex ctime@r{, printing or sorting by}
+@opindex status time@r{, printing or sorting by}
+@opindex use time@r{, printing or sorting files by}
+In long format,
+print the status change timestamp (the ctime) instead of the mtime.
+When sorting by time or when not using long format,
+sort according to the ctime.  @xref{File timestamps}.
+
+@item -f
+@opindex -f
+@cindex unsorted directory listing
+@cindex directory order, listing by
+Produce an unsorted directory listing.
+This is equivalent to the combination of @option{--all} (@option{-a}),
+@option{--sort=none} (@option{-U}), @option{-1},
+@option{--color=none}, and @option{--hyperlink=none},
+while also disabling any previous use of @option{--size} (@option{-s}).
+
+@item -r
+@itemx --reverse
+@opindex -r
+@opindex --reverse
+@cindex reverse sorting
+Reverse whatever the sorting method is -- e.g., list files in reverse
+alphabetical order, youngest first, smallest first, or whatever.
+This option has no effect when @option{--sort=none} (@option{-U})
+is in effect.
+
+@item -S
+@itemx --sort=size
+@opindex -S
+@opindex --sort
+@opindex size of files@r{, sorting files by}
+Sort by file size, largest first.
+
+@item -t
+@itemx --sort=time
+@opindex -t
+@opindex --sort
+@opindex modification timestamp@r{, sorting files by}
+Sort by modification timestamp (mtime) by default, newest first.
+The timestamp to order by can be changed with the @option{--time} option.
+@xref{File timestamps}.
+
+@item -u
+@itemx --time=atime
+@itemx --time=access
+@itemx --time=use
+@opindex -u
+@opindex --time
+@opindex use time@r{, printing or sorting files by}
+@opindex atime@r{, printing or sorting files by}
+@opindex access timestamp@r{, printing or sorting files by}
+In long format, print the last access timestamp (the atime).
+When sorting by time or when not using long format,
+sort according to the atime.
+@xref{File timestamps}.
+
+@item --time=mtime
+@itemx --time=modification
+@opindex --time
+@opindex data modification time@r{, printing or sorting files by}
+@opindex mtime@r{, printing or sorting files by}
+This is the default timestamp display and sorting mode.
+In long format, print the last data modification timestamp (the mtime).
+When sorting by time or when not using long format,
+sort according to the mtime.
+@xref{File timestamps}.
+
+@item --time=birth
+@itemx --time=creation
+@opindex --time
+@opindex birth time@r{, printing or sorting files by}
+@opindex creation timestamp@r{, printing or sorting files by}
+In long format, print the file creation timestamp if available,
+falling back to the file modification timestamp (mtime) if not.
+When sorting by time or when not using long format,
+sort according to the birth time.
+@xref{File timestamps}.
+
+@item -U
+@itemx --sort=none
+@opindex -U
+@opindex --sort
+@opindex none@r{, sorting option for @command{ls}}
+Do not sort; list the files in whatever order they are
+stored in the directory.  (Do not do any of the other unrelated things
+that @option{-f} does.)  This can be useful when listing large
+directories, where sorting can take some time.
+
+@item -v
+@itemx --sort=version
+@opindex -v
+@opindex --sort
+@opindex version@r{, sorting option for @command{ls}}
+Sort by version name and number, lowest first.  It behaves like a default
+sort, except that each sequence of decimal digits is treated numerically
+as an index/version number.  @xref{Version sort ordering}.
+
+@item --sort=width
+@opindex --sort
+@opindex width@r{, sorting option for @command{ls}}
+Sort by printed width of file names.
+This can be useful with the @option{--format=vertical} (@option{-C})
+output format, to most densely display the listed files.
+
+@item -X
+@itemx --sort=extension
+@opindex -X
+@opindex --sort
+@opindex extension@r{, sorting files by}
+Sort directory contents alphabetically by file extension (characters
+after the last @samp{.}); files with no extension are sorted first.
+
+@end table
+
+
+@node General output formatting
+@subsection General output formatting
+
+These options affect the appearance of the overall output.
+
+@table @samp
+
+@item --format=single-column
+@opindex --format
+@opindex single-column @r{output of files}
+List one file name per line, with no other information.
+This is the default for @command{ls} when standard
+output is not a terminal.  See also the @option{--escape} (@option{-b}),
+@option{--hide-control-chars} (@option{-q}), and @option{--zero} options
+to disambiguate output of file names containing newline characters.
+
+@item -1
+@opindex -1
+List one file per line.  This is like @option{--format=single-column}
+except that it has no effect if long format is also in effect.
+
+@item -C
+@itemx --format=vertical
+@opindex -C
+@opindex --format
+@opindex vertical @r{sorted files in columns}
+List files in columns, sorted vertically, with no other information.
+This is the default for @command{ls} if standard output is a terminal.
+It is always the default for the @command{dir} program.
+GNU @command{ls} uses variable width columns to display as many files as
+possible in the fewest lines.
+
+@item --color [=@var{when}]
+@opindex --color
+@cindex color, distinguishing file types with
+Specify whether to use color for distinguishing file types; @var{when}
+may be omitted, or one of:
+@itemize @bullet
+@item none
+@vindex none @r{color option}
+- Do not use color at all.  This is the default.
+@item auto
+@vindex auto @r{color option}
+@cindex terminal, using color iff
+- Only use color if standard output is a terminal.
+@item always
+@vindex always @r{color option}
+- Always use color.
+@end itemize
+Specifying @option{--color} and no @var{when} is equivalent to
+@option{--color=always}.
+If piping a colored listing through a pager like @command{less},
+use the pager's @option{-R} option to pass the color codes to the terminal.
+
+@vindex LS_COLORS
+@vindex SHELL @r{environment variable, and color}
+Using the @option{--color} option may incur a noticeable
+performance penalty when run in a large directory,
+because the default settings require that @command{ls} @code{stat} every
+single file it lists.
+However, if you would like most of the file-type coloring
+but can live without the other coloring options (e.g.,
+executable, orphan, sticky, other-writable, capability), use
+@command{dircolors} to set the @env{LS_COLORS} environment variable like this,
+@example
+eval $(dircolors -p | perl -pe \
+  's/^((CAP|S[ET]|O[TR]|M|E)\w+).*/$1 00/' | dircolors -)
+@end example
+and on a @code{dirent.d_type}-capable file system, @command{ls}
+will perform only one @code{stat} call per command line argument.
+
+@item -F
+@itemx --classify [=@var{when}]
+@itemx --indicator-style=classify
+@opindex -F
+@opindex --classify
+@opindex --indicator-style
+@cindex file type and executables, marking
+@cindex executables and file type, marking
+Append a character to each file name indicating the file type.  Also,
+for regular files that are executable, append @samp{*}.  The file type
+indicators are @samp{/} for directories, @samp{@@} for symbolic links,
+@samp{|} for FIFOs, @samp{=} for sockets, @samp{>} for doors,
+and nothing for regular files.
+@var{when} may be omitted, or one of:
+@itemize @bullet
+@item none
+@vindex none @r{classify option}
+- Do not classify.  This is the default.
+@item auto
+@vindex auto @r{classify option}
+@cindex terminal, using classify iff
+- Only classify if standard output is a terminal.
+@item always
+@vindex always @r{classify option}
+- Always classify.
+@end itemize
+Specifying @option{--classify} and no @var{when} is equivalent to
+@option{--classify=always}.
+@c The following sentence is the same as the one for -d.
+Do not follow symbolic links listed on the
+command line unless the @option{--dereference-command-line} (@option{-H}),
+@option{--dereference} (@option{-L}), or
+@option{--dereference-command-line-symlink-to-dir} options are specified.
+
+@item --file-type
+@itemx --indicator-style=file-type
+@opindex --file-type
+@opindex --indicator-style
+@cindex file type, marking
+Append a character to each file name indicating the file type.  This is
+like @option{--classify} (@option{-F}, except that executables are not marked.
+
+@item --hyperlink [=@var{when}]
+@opindex --hyperlink
+@cindex hyperlink, linking to files
+Output codes recognized by some terminals to link
+to files using the @samp{file://} URI format.
+@var{when} may be omitted, or one of:
+@itemize @bullet
+@item none
+@vindex none @r{hyperlink option}
+- Do not use hyperlinks at all.  This is the default.
+@item auto
+@vindex auto @r{hyperlink option}
+@cindex terminal, using hyperlink iff
+- Only use hyperlinks if standard output is a terminal.
+@item always
+@vindex always @r{hyperlink option}
+- Always use hyperlinks.
+@end itemize
+Specifying @option{--hyperlink} and no @var{when} is equivalent to
+@option{--hyperlink=always}.
+
+@item --indicator-style=@var{word}
+@opindex --indicator-style
+Append a character indicator with style @var{word} to entry names,
+as follows:
+
+@table @samp
+@item none
+Do not append any character indicator; this is the default.
+@item slash
+Append @samp{/} for directories.  This is the same as the @option{-p}
+option.
+@item file-type
+Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|}
+for FIFOs, @samp{=} for sockets, and nothing for regular files.  This is
+the same as the @option{--file-type} option.
+@item classify
+Append @samp{*} for executable regular files, otherwise behave as for
+@samp{file-type}.  This is the same as the @option{--classify}
+(@option{-F}) option.
+@end table
+
+@item -k
+@itemx --kibibytes
+@opindex -k
+@opindex --kibibytes
+Set the default block size to its normal value of 1024 bytes,
+overriding any contrary specification in environment variables
+(@pxref{Block size}).  If @option{--block-size},
+@option{--human-readable} (@option{-h}), or @option{--si} options are used,
+they take precedence even if @option{--kibibytes} (@option{-k}) is placed after
+
+The @option{--kibibytes} (@option{-k}) option affects the
+per-directory block count written in long format,
+and the file system allocation written by the @option{--size} (@option{-s})
+option.  It does not affect the file size in bytes that is written in
+long format.
+
+@item -m
+@itemx --format=commas
+@opindex -m
+@opindex --format
+@opindex commas@r{, outputting between files}
+List files horizontally, with as many as will fit on each line,
+separated by @samp{, } (a comma and a space),
+and with no other information.
+
+@item -p
+@itemx --indicator-style=slash
+@opindex -p
+@opindex --indicator-style
+@cindex file type, marking
+Append a @samp{/} to directory names.
+
+@item -x
+@itemx --format=across
+@itemx --format=horizontal
+@opindex -x
+@opindex --format
+@opindex across@r{, listing files}
+@opindex horizontal@r{, listing files}
+List the files in columns, sorted horizontally.
+
+@item -T @var{cols}
+@itemx --tabsize=@var{cols}
+@opindex -T
+@opindex --tabsize
+Assume that each tab stop is @var{cols} columns wide.  The default is 8.
+@command{ls} uses tabs where possible in the output, for efficiency.  If
+@var{cols} is zero, do not use tabs at all.
+
+Some terminal emulators might not properly align columns to the right of a
+TAB following a non-ASCII byte.  You can avoid that issue by using the
+@option{-T0} option or put @code{TABSIZE=0} in your environment, to tell
+@command{ls} to align using spaces, not tabs.
+
+If you set a terminal's hardware tabs to anything other than the default,
+you should also use a @command{--tabsize} option or @env{TABSIZE}
+environment variable either to match the hardware tabs, or to disable
+the use of hardware tabs.  Otherwise, the output of @command{ls} may
+not line up.  For example, if you run the shell command @samp{tabs -4}
+to set hardware tabs to every four columns, you should also run
+@samp{export TABSIZE=4} or @samp{export TABSIZE=0}, or use the
+corresponding @option{--tabsize} options.
+
+@item -w @var{cols}
+@itemx --width=@var{cols}
+@opindex -w
+@opindex --width
+@vindex COLUMNS
+Assume the screen is @var{cols} columns wide.  The default is taken
+from the terminal settings if possible; otherwise the environment
+variable @env{COLUMNS} is used if it is set; otherwise the default
+is 80.  With a @var{cols} value of @samp{0}, there is no limit on
+the length of the output line, and that single output line will
+be delimited with spaces, not tabs.
+
+@item --zero
+@opindex --zero
+@outputNUL
+This option is incompatible with the @option{--dired} (@option{-D}) option.
+This option also implies the options @option{--show-control-chars},
+@option{-1}, @option{--color=none}, and
+@option{--quoting-style=literal} (@option{-N}).
+
+@end table
+
+
+@node Formatting file timestamps
+@subsection Formatting file timestamps
+
+By default, file timestamps are listed in abbreviated form, using
+a date like @samp{Mar 30@ @ 2020} for non-recent timestamps, and a
+date-without-year and time like @samp{Mar 30 23:45} for recent timestamps.
+This format can change depending on the current locale as detailed below.
+
+@cindex clock skew
+A timestamp is considered to be @dfn{recent} if it is less than six
+months old, and is not dated in the future.  If a timestamp dated
+today is not listed in recent form, the timestamp is in the future,
+which means you probably have clock skew problems which may break
+programs like @command{make} that rely on file timestamps.
+@xref{File timestamps}.
+
+@vindex TZ
+Timestamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
+@env{TZ} is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
+
+The following option changes how file timestamps are printed.
+
+@table @samp
+@item --time-style=@var{style}
+@opindex --time-style
+@cindex time style
+List timestamps in style @var{style}.  The @var{style} should
+be one of the following:
+
+@table @samp
+@item +@var{format}
+@vindex LC_TIME
+List timestamps using @var{format}, where @var{format} is interpreted
+like the format argument of @command{date} (@pxref{date invocation}).
+For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
+@command{ls} to list timestamps like @samp{2020-03-30 23:45:56}.  As
+with @command{date}, @var{format}'s interpretation is affected by the
+@env{LC_TIME} locale category.
+
+If @var{format} contains two format strings separated by a newline,
+the former is used for non-recent files and the latter for recent
+files; if you want output columns to line up, you may need to insert
+spaces in one of the two formats.
+
+@item full-iso
+List timestamps in full using ISO 8601-like date, time, and time zone
+components with nanosecond precision, e.g., @samp{2020-07-21
+23:45:56.477817180 -0400}.  This style is equivalent to
+@samp{+%Y-%m-%d %H:%M:%S.%N %z}.
+
+This is useful because the time output includes all the information that
+is available from the operating system.  For example, this can help
+explain @command{make}'s behavior, since GNU @command{make}
+uses the full timestamp to determine whether a file is out of date.
+
+@item long-iso
+List ISO 8601 date and time components with minute precision, e.g.,
+@samp{2020-03-30 23:45}.  These timestamps are shorter than
+@samp{full-iso} timestamps, and are usually good enough for everyday
+work.  This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
+
+@item iso
+List ISO 8601 dates for non-recent timestamps (e.g.,
+@samp{2020-03-30@ }), and ISO 8601-like month, day, hour, and
+minute for recent timestamps (e.g., @samp{03-30 23:45}).  These
+timestamps are uglier than @samp{long-iso} timestamps, but they carry
+nearly the same information in a smaller space and their brevity helps
+@command{ls} output fit within traditional 80-column output lines.
+The following two @command{ls} invocations are equivalent:
+
+@example
+newline='
+'
+ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M"
+ls -l --time-style="iso"
+@end example
+
+@item locale
+@vindex LC_TIME
+List timestamps in a locale-dependent form.  For example, a French
+locale might list non-recent timestamps like @samp{30 mars@ @ @ 2020}
+and recent timestamps like @samp{30 mars@ @ 23:45}.  Locale-dependent
+timestamps typically consume more space than @samp{iso} timestamps and
+are harder for programs to parse because locale conventions vary so
+widely, but they are easier for many people to read.
+
+The @env{LC_TIME} locale category specifies the timestamp format.  The
+default POSIX locale uses timestamps like @samp{Mar 30@
+@ 2020} and @samp{Mar 30 23:45}; in this locale, the following two
+@command{ls} invocations are equivalent:
+
+@example
+newline='
+'
+ls -l --time-style="+%b %e  %Y$newline%b %e %H:%M"
+ls -l --time-style="locale"
+@end example
+
+Other locales behave differently.  For example, in a German locale,
+@option{--time-style="locale"} might be equivalent to
+@option{--time-style="+%e. %b %Y $newline%e. %b %H:%M"}
+and might generate timestamps like @samp{30. M@"ar 2020@ } and
+@samp{30. M@"ar 23:45}.
+
+@item posix-@var{style}
+@vindex LC_TIME
+List POSIX-locale timestamps if the @env{LC_TIME} locale
+category is POSIX, @var{style} timestamps otherwise.  For
+example, the @samp{posix-long-iso} style lists
+timestamps like @samp{Mar 30@ @ 2020} and @samp{Mar 30 23:45} when in
+the POSIX locale, and like @samp{2020-03-30 23:45} otherwise.
+@end table
+@end table
+
+@vindex TIME_STYLE
+You can specify the default value of the @option{--time-style} option
+with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
+the default style is @samp{locale}.  GNU Emacs 21.3 and
+later use the @option{--dired} option and therefore can parse any date
+format, but if you are using Emacs 21.1 or 21.2 and specify a
+non-POSIX locale you may need to set
+@samp{TIME_STYLE="posix-long-iso"}.
+
+To avoid certain denial-of-service attacks, timestamps that would be
+longer than 1000 bytes may be treated as errors.
+
+
+@node Formatting the file names
+@subsection Formatting the file names
+
+These options change how file names themselves are printed.
+
+@table @samp
+
+@item -b
+@itemx --escape
+@itemx --quoting-style=escape
+@opindex -b
+@opindex --escape
+@opindex --quoting-style
+@cindex backslash sequences for file names
+Quote nongraphic characters in file names using alphabetic and octal
+backslash sequences like those used in C.
+
+@item -N
+@itemx --literal
+@itemx --quoting-style=literal
+@opindex -N
+@opindex --literal
+@opindex --quoting-style
+Do not quote file names.  However, with @command{ls} nongraphic
+characters are still printed as question marks if the output is a
+terminal and you do not specify the @option{--show-control-chars}
+option.
+
+@item -q
+@itemx --hide-control-chars
+@opindex -q
+@opindex --hide-control-chars
+Print question marks instead of nongraphic characters in file names.
+This is the default if the output is a terminal and the program is
+@command{ls}.
+
+@item -Q
+@itemx --quote-name
+@itemx --quoting-style=c
+@opindex -Q
+@opindex --quote-name
+@opindex --quoting-style
+Enclose file names in double quotes and quote nongraphic characters as
+in C.
+
+@item --quoting-style=@var{word}
+@opindex --quoting-style
+@cindex quoting style
+Use style @var{word} to quote file names and other strings that may
+contain arbitrary characters.  The @var{word} should
+be one of the following:
+
+@macro quotingStyles
+@table @samp
+@item literal
+Output strings as-is; this is the same as the @option{--literal} (@option{-N})
+option.
+@item shell
+Quote strings for the shell if they contain shell metacharacters or would
+cause ambiguous output.
+The quoting is suitable for POSIX-compatible shells like
+@command{bash}, but it does not always work for incompatible shells
+like @command{csh}.
+@item shell-always
+Quote strings for the shell, even if they would normally not require quoting.
+@item shell-escape
+Like @samp{shell}, but also quoting non-printable characters using the POSIX
+proposed @samp{$''} syntax suitable for most shells.
+@item shell-escape-always
+Like @samp{shell-escape}, but quote strings even if they would
+normally not require quoting.
+@item c
+Quote strings as for C character string literals, including the
+surrounding double-quote characters; this is the same as the
+@option{--quote-name} (@option{-Q}) option.
+@item escape
+Quote strings as for C character string literals, except omit the
+surrounding double-quote
+characters; this is the same as the @option{--escape} (@option{-b}) option.
+@item clocale
+Quote strings as for C character string literals, except use
+surrounding quotation marks appropriate for the
+locale.
+@item locale
+@c Use @t instead of @samp to avoid duplicate quoting in some output styles.
+Quote strings as for C character string literals, except use
+surrounding quotation marks appropriate for the locale, and quote
+@t{'like this'} instead of @t{"like
+this"} in the default C locale.  This looks nicer on many displays.
+@end table
+@end macro
+@quotingStyles
+
+You can specify the default value of the @option{--quoting-style} option
+with the environment variable @env{QUOTING_STYLE}@.  If that environment
+variable is not set, the default value is @samp{shell-escape} when the
+output is a terminal, and @samp{literal} otherwise.
+
+@item --show-control-chars
+@opindex --show-control-chars
+Print nongraphic characters as-is in file names.
+This is the default unless the output is a terminal and the program is
+@command{ls}.
+
+@end table
+
+
+@node dir invocation
+@section @command{dir}: Briefly list directory contents
+
+@pindex dir
+@cindex directory listing, brief
+
+@command{dir} is equivalent to @code{ls -C
+-b}; that is, by default files are listed in columns, sorted vertically,
+and special characters are represented by backslash escape sequences.
+
+@xref{ls invocation, @command{ls}}.
+
+
+@node vdir invocation
+@section @command{vdir}: Verbosely list directory contents
+
+@pindex vdir
+@cindex directory listing, verbose
+
+@command{vdir} is equivalent to @code{ls -l
+-b}; that is, by default files are listed in long format and special
+characters are represented by backslash escape sequences.
+
+@xref{ls invocation, @command{ls}}.
+
+@node dircolors invocation
+@section @command{dircolors}: Color setup for @command{ls}
+
+@pindex dircolors
+@cindex color setup
+@cindex setup for color
+
+@command{dircolors} outputs a sequence of shell commands to set up the
+terminal for color output from @command{ls} (and @command{dir}, etc.).
+Typical usage:
+
+@example
+eval "$(dircolors [@var{option}]@dots{} [@var{file}])"
+@end example
+
+If @var{file} is specified, @command{dircolors} reads it to determine which
+colors to use for which file types and extensions.  Otherwise, a
+precompiled database is used.  For details on the format of these files,
+run @samp{dircolors --print-database}.
+
+To make @command{dircolors} read a @file{~/.dircolors} file if it
+exists, you can put the following lines in your @file{~/.bashrc} (or
+adapt them to your favorite shell):
+
+@example
+d=.dircolors
+test -r $d && eval "$(dircolors $d)"
+@end example
+
+@vindex LS_COLORS
+@vindex SHELL @r{environment variable, and color}
+The output is a shell command to set the @env{LS_COLORS} environment
+variable.  You can specify the shell syntax to use on the command line,
+or @command{dircolors} will guess it from the value of the @env{SHELL}
+environment variable.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+@item -b
+@itemx --sh
+@itemx --bourne-shell
+@opindex -b
+@opindex --sh
+@opindex --bourne-shell
+@cindex Bourne shell syntax for color setup
+@cindex @command{sh} syntax for color setup
+Output Bourne shell commands.  This is the default if the @env{SHELL}
+environment variable is set and does not end with @samp{csh} or
+@samp{tcsh}.
+
+@item -c
+@itemx --csh
+@itemx --c-shell
+@opindex -c
+@opindex --csh
+@opindex --c-shell
+@cindex C shell syntax for color setup
+@cindex @command{csh} syntax for color setup
+Output C shell commands.  This is the default if @code{SHELL} ends with
+@command{csh} or @command{tcsh}.
+
+@item -p
+@itemx --print-database
+@opindex -p
+@opindex --print-database
+@cindex color database, printing
+@cindex database for color setup, printing
+@cindex printing color database
+Print the (compiled-in) default color configuration database.  This
+output is itself a valid configuration file, and is fairly descriptive
+of the possibilities.
+
+@item --print-ls-colors
+@opindex --print-ls-colors
+@cindex printing ls colors
+Print the LS_COLORS entries on separate lines,
+each colored as per the color they represent.
+
+@end table
+
+@exitstatus
+
+
+@node Basic operations
+@chapter Basic operations
+
+@cindex manipulating files
+
+This chapter describes the commands for basic file manipulation:
+copying, moving (renaming), and deleting (removing).
+
+@menu
+* cp invocation::               Copy files.
+* dd invocation::               Convert and copy a file.
+* install invocation::          Copy files and set attributes.
+* mv invocation::               Move (rename) files.
+* rm invocation::               Remove files or directories.
+* shred invocation::            Remove files more securely.
+@end menu
+
+
+@node cp invocation
+@section @command{cp}: Copy files and directories
+
+@pindex cp
+@cindex copying files and directories
+@cindex files, copying
+@cindex directories, copying
+
+@command{cp} copies files (or, optionally, directories).  The copy is
+completely independent of the original.  You can either copy one file to
+another, or copy arbitrarily many files to a destination directory.
+Synopses:
+
+@example
+cp [@var{option}]@dots{} [-T] @var{source} @var{dest}
+cp [@var{option}]@dots{} @var{source}@dots{} @var{directory}
+cp [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
+@end example
+
+@itemize @bullet
+@item
+If two file names are given, @command{cp} copies the first file to the
+second.
+
+@item
+If the @option{--target-directory} (@option{-t}) option is given, or
+failing that if the last file is a directory and the
+@option{--no-target-directory} (@option{-T}) option is not given,
+@command{cp} copies each @var{source} file to the specified directory,
+using the @var{source}s' names.
+@end itemize
+
+Generally, files are written just as they are read.  For exceptions,
+see the @option{--sparse} option below.
+
+By default, @command{cp} does not copy directories.  However, the
+@option{-R}, @option{-a}, and @option{-r} options cause @command{cp} to
+copy recursively by descending into source directories and copying files
+to corresponding destination directories.
+
+When copying from a symbolic link, @command{cp} normally follows the
+link only when not copying recursively or when @option{--link}
+(@option{-l}) is used.  This default can be overridden with the
+@option{--archive} (@option{-a}), @option{-d}, @option{--dereference}
+(@option{-L}), @option{--no-dereference} (@option{-P}), and
+@option{-H} options.  If more than one of these options is specified,
+the last one silently overrides the others.
+
+When copying to a symbolic link, @command{cp} follows the
+link only when it refers to an existing regular file.
+However, when copying to a dangling symbolic link, @command{cp}
+refuses by default, and fails with a diagnostic, since the operation
+is inherently dangerous.  This behavior is contrary to historical
+practice and to POSIX@.
+Set @env{POSIXLY_CORRECT} to make @command{cp} attempt to create
+the target of a dangling destination symlink, in spite of the possible risk.
+Also, when an option like
+@option{--backup} or @option{--link} acts to rename or remove the
+destination before copying, @command{cp} renames or removes the
+symbolic link rather than the file it points to.
+
+By default, @command{cp} copies the contents of special files only
+when not copying recursively.  This default can be overridden with the
+@option{--copy-contents} option.
+
+@cindex self-backups
+@cindex backups, making only
+@command{cp} generally refuses to copy a file onto itself, with the
+following exception: if @option{--force --backup} is specified with
+@var{source} and @var{dest} identical, and referring to a regular file,
+@command{cp} will make a backup file, either regular or numbered, as
+specified in the usual ways (@pxref{Backup options}).  This is useful when
+you simply want to make a backup of an existing file before changing it.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+@item -a
+@itemx --archive
+@opindex -a
+@opindex --archive
+Preserve as much as possible of the structure and attributes of the
+original files in the copy (but do not attempt to preserve internal
+directory structure; i.e., @samp{ls -U} may list the entries in a copied
+directory in a different order).
+Try to preserve SELinux security context and extended attributes (xattr),
+but ignore any failure to do that and print no corresponding diagnostic.
+Equivalent to @option{-dR --preserve=all} with the reduced diagnostics.
+
+@item --attributes-only
+@opindex --attributes-only
+Copy only the specified attributes of the source file to the destination.
+If the destination already exists, do not alter its contents.
+See the @option{--preserve} option for controlling which attributes to copy.
+
+@item -b
+@itemx --backup[=@var{method}]
+@opindex -b
+@opindex --backup
+@vindex VERSION_CONTROL
+@cindex backups, making
+@xref{Backup options}.
+Make a backup of each file that would otherwise be overwritten or removed.
+As a special case, @command{cp} makes a backup of @var{source} when the force
+and backup options are given and @var{source} and @var{dest} are the same
+name for an existing, regular file.  One useful application of this
+combination of options is this tiny Bourne shell script:
+
+@example
+#!/bin/sh
+# Usage: backup FILE...
+# Create a GNU-style backup of each listed FILE.
+fail=0
+for i; do
+  cp --backup --force --preserve=all -- "$i" "$i" || fail=1
+done
+exit $fail
+@end example
+
+@item --copy-contents
+@cindex directories, copying recursively
+@cindex copying directories recursively
+@cindex recursively copying directories
+@cindex non-directories, copying as special files
+If copying recursively, copy the contents of any special files (e.g.,
+FIFOs and device files) as if they were regular files.  This means
+trying to read the data in each source file and writing it to the
+destination.  It is usually a mistake to use this option, as it
+normally has undesirable effects on special files like FIFOs and the
+ones typically found in the @file{/dev} directory.  In most cases,
+@code{cp -R --copy-contents} will hang indefinitely trying to read
+from FIFOs and special files like @file{/dev/console}, and it will
+fill up your destination file system if you use it to copy @file{/dev/zero}.
+This option has no effect unless copying recursively, and it does not
+affect the copying of symbolic links.
+
+@item -d
+@opindex -d
+@cindex symbolic links, copying
+@cindex hard links, preserving
+Copy symbolic links as symbolic links rather than copying the files that
+they point to, and preserve hard links between source files in the copies.
+Equivalent to @option{--no-dereference --preserve=links}.
+
+@macro optDebugCopy
+@item --debug
+@opindex --debug
+@cindex debugging, copying
+Print extra information to stdout, explaining how files are copied.
+This option implies the @option{--verbose} option.
+@end macro
+@optDebugCopy
+
+@item -f
+@itemx --force
+@opindex -f
+@opindex --force
+When copying without this option and an existing destination file cannot
+be opened for writing, the copy fails.  However, with @option{--force},
+when a destination file cannot be opened, @command{cp} then
+tries to recreate the file by first removing it.  Note @option{--force}
+alone will not remove dangling symlinks.
+When this option is combined with
+@option{--link} (@option{-l}) or @option{--symbolic-link}
+(@option{-s}), the destination link is replaced, and unless
+@option{--backup} (@option{-b}) is also given there is no brief
+moment when the destination does not exist.  Also see the
+description of @option{--remove-destination}.
+
+This option is independent of the @option{--interactive} or
+@option{-i} option: neither cancels the effect of the other.
+
+This option is ignored when the @option{--no-clobber} or @option{-n} option
+is also used.
+
+@item -H
+@opindex -H
+If a command line argument specifies a symbolic link, then copy the
+file it points to rather than the symbolic link itself.  However,
+copy (preserving its nature) any symbolic link that is encountered
+via recursive traversal.
+
+@item -i
+@itemx --interactive
+@opindex -i
+@opindex --interactive
+When copying a file other than a directory, prompt whether to
+overwrite an existing destination file, and fail if the response
+is not affirmative.  The @option{-i} option overrides
+a previous @option{-n} option.
+
+@item -l
+@itemx --link
+@opindex -l
+@opindex --link
+Make hard links instead of copies of non-directories.
+
+@item -L
+@itemx --dereference
+@opindex -L
+@opindex --dereference
+Follow symbolic links when copying from them.
+With this option, @command{cp} cannot create a symbolic link.
+For example, a symlink (to regular file) in the source tree will be copied to
+a regular file in the destination tree.
+
+@item -n
+@itemx --no-clobber
+@opindex -n
+@opindex --no-clobber
+Do not overwrite an existing file; silently fail instead.
+This option overrides a previous
+@option{-i} option.  This option is mutually exclusive with @option{-b} or
+@option{--backup} option.
+
+@item -P
+@itemx --no-dereference
+@opindex -P
+@opindex --no-dereference
+@cindex symbolic links, copying
+Copy symbolic links as symbolic links rather than copying the files that
+they point to.  This option affects only symbolic links in the source;
+symbolic links in the destination are always followed if possible.
+
+@item -p
+@itemx --preserve[=@var{attribute_list}]
+@opindex -p
+@opindex --preserve
+@cindex file information, preserving, extended attributes, xattr
+Preserve the specified attributes of the original files.
+If specified, the @var{attribute_list} must be a comma-separated list
+of one or more of the following strings:
+
+@table @samp
+@item mode
+@cindex access control lists (ACLs)
+Preserve attributes relevant to access permissions,
+including file mode bits and (if possible) access control lists (ACLs).
+ACL preservation is system-dependent, and ACLs are not necessarily
+translated when the source and destination are on file systems with
+different ACL formats (e.g., NFSv4 versus POSIX formats).
+
+@item ownership
+Preserve the owner and group.  On most modern systems,
+only users with appropriate privileges may change the owner of a file,
+and ordinary users
+may preserve the group ownership of a file only if they happen to be
+a member of the desired group.
+@item timestamps
+Preserve the times of last access and last modification, when possible.
+On older systems, it is not possible to preserve these attributes
+when the affected file is a symbolic link.
+However, many systems now provide the @code{utimensat} function,
+which makes it possible even for symbolic links.
+@item links
+Preserve in the destination files
+any links between corresponding source files.
+Note that with @option{-L} or @option{-H}, this option can convert
+symbolic links to hard links.  For example,
+@example
+$ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c
+74161745 a
+74161745 b
+@end example
+@noindent
+Note the inputs: @file{b} is a symlink to regular file @file{a},
+yet the files in destination directory, @file{c/}, are hard-linked.
+Since @option{-a} implies @option{--no-dereference} it would copy the symlink,
+but the later @option{-H} tells @command{cp} to dereference the command line
+arguments where it then sees two files with the same inode number.
+Then the @option{--preserve=links} option also implied by @option{-a}
+will preserve the perceived hard link.
+
+Here is a similar example that exercises @command{cp}'s @option{-L} option:
+@example
+$ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b
+74163295 a
+74163295 b
+@end example
+
+@item context
+Preserve SELinux security context of the file, or fail with full diagnostics.
+@item xattr
+@cindex access control lists (ACLs)
+Preserve extended attributes of the file, or fail with full diagnostics.
+If @command{cp} is built without xattr support, ignore this option.
+If SELinux context, ACLs or Capabilities are implemented using xattrs,
+they are preserved implicitly by this option as well, i.e., even without
+specifying @option{--preserve=mode} or @option{--preserve=context}.
+@item all
+Preserve all file attributes.
+Equivalent to specifying all of the above, but with the difference
+that failure to preserve SELinux security context or extended attributes
+does not change @command{cp}'s exit status.  In contrast to @option{-a},
+all but @samp{Operation not supported} warnings are output.
+@end table
+
+Using @option{--preserve} with no @var{attribute_list} is equivalent
+to @option{--preserve=mode,ownership,timestamps}.
+
+In the absence of this option, the permissions of existing destination
+files are unchanged.  Each new file is created with the mode of the
+corresponding source file minus the set-user-ID, set-group-ID, and
+sticky bits as the create mode; the operating system then applies either
+the umask or a default ACL, possibly resulting in a more restrictive
+file mode.
+@xref{File permissions}.
+
+@item --no-preserve=@var{attribute_list}
+@cindex file information, preserving
+Do not preserve the specified attributes.  The @var{attribute_list}
+has the same form as for @option{--preserve}.
+
+@item --parents
+@opindex --parents
+@cindex parent directories and @command{cp}
+Form the name of each destination file by appending to the target
+directory a slash and the specified name of the source file.  The last
+argument given to @command{cp} must be the name of an existing directory.
+For example, the command:
+
+@example
+cp --parents a/b/c existing_dir
+@end example
+
+@noindent
+copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating
+any missing intermediate directories.
+
+@item -R
+@itemx -r
+@itemx --recursive
+@opindex -R
+@opindex -r
+@opindex --recursive
+@cindex directories, copying recursively
+@cindex copying directories recursively
+@cindex recursively copying directories
+@cindex non-directories, copying as special files
+Copy directories recursively.  By default, do not follow symbolic
+links in the source unless used together with the @option{--link}
+(@option{-l}) option; see the @option{--archive} (@option{-a}), @option{-d},
+@option{--dereference} (@option{-L}), @option{--no-dereference}
+(@option{-P}), and @option{-H} options.  Special files are copied by
+creating a destination file of the same type as the source; see the
+@option{--copy-contents} option.  It is not portable to use
+@option{-r} to copy symbolic links or special files.  On some
+non-GNU systems, @option{-r} implies the equivalent of
+@option{-L} and @option{--copy-contents} for historical reasons.
+Also, it is not portable to use @option{-R} to copy symbolic links
+unless you also specify @option{-P}, as POSIX allows
+implementations that dereference symbolic links by default.
+
+@item --reflink[=@var{when}]
+@opindex --reflink[=@var{when}]
+@cindex COW
+@cindex clone
+@cindex copy on write
+Perform a lightweight, copy-on-write (COW) copy, if supported by the
+file system.  Once it has succeeded, beware that the source and destination
+files share the same data blocks as long as they remain unmodified.
+Thus, if an I/O error affects data blocks of one of the files,
+the other suffers the same fate.
+
+The @var{when} value can be one of the following:
+
+@table @samp
+@item always
+If the copy-on-write operation is not supported
+then report the failure for each file and exit with a failure status.
+Plain @option{--reflink} is equivalent to @option{--reflink=always}.
+
+@item auto
+If the copy-on-write operation is not supported then fall back
+to the standard copy behavior.
+This is the default if no @option{--reflink} option is given.
+
+@item never
+Disable copy-on-write operation and use the standard copy behavior.
+@end table
+
+This option is overridden by the @option{--link}, @option{--symbolic-link}
+and @option{--attributes-only} options, thus allowing it to be used
+to configure the default data copying behavior for @command{cp}.
+
+@item --remove-destination
+@opindex --remove-destination
+Remove each existing destination file before attempting to open it
+(contrast with @option{-f} above).
+
+@item --sparse=@var{when}
+@opindex --sparse=@var{when}
+@cindex sparse files, copying
+@cindex holes, copying files with
+@findex read @r{system call, and holes}
+A @dfn{sparse file} contains @dfn{holes} -- a sequence of zero bytes that
+does not occupy any file system blocks; the @samp{read} system call
+reads these as zeros.  This can both save considerable space and
+increase speed, since many binary files contain lots of consecutive zero
+bytes.  By default, @command{cp} detects holes in input source files via a crude
+heuristic and makes the corresponding output file sparse as well.
+Only regular files may be sparse.
+
+The @var{when} value can be one of the following:
+
+@table @samp
+@item auto
+The default behavior: if the input file is sparse, attempt to make
+the output file sparse, too.  However, if an output file exists but
+refers to a non-regular file, then do not attempt to make it sparse.
+
+@item always
+For each sufficiently long sequence of zero bytes in the input file,
+attempt to create a corresponding hole in the output file, even if the
+input file does not appear to be sparse.
+This is useful when the input file resides on a file system
+that does not support sparse files
+(for example,  @samp{efs} file systems in SGI IRIX 5.3 and earlier),
+but the output file is on a type of file system that does support them.
+Holes may be created only in regular files, so if the destination file
+is of some other type, @command{cp} does not even try to make it sparse.
+
+@item never
+Never make the output file sparse.
+This is useful in creating a file for use with the @command{mkswap} command,
+since such a file must not have any holes.
+@end table
+
+For example, with the following alias, @command{cp} will use the
+minimum amount of space supported by the file system.
+(Older versions of @command{cp} can also benefit from
+@option{--reflink=auto} here.)
+
+@example
+alias cp='cp --sparse=always'
+@end example
+
+@optStripTrailingSlashes
+
+@item -s
+@itemx --symbolic-link
+@opindex -s
+@opindex --symbolic-link
+@cindex symbolic links, copying with
+Make symbolic links instead of copies of non-directories.  All source
+file names must be absolute (starting with @samp{/}) unless the
+destination files are in the current directory.  This option merely
+results in an error message on systems that do not support symbolic links.
+
+@optBackupSuffix
+
+@optTargetDirectory
+
+@optNoTargetDirectory
+
+@item -u
+@itemx --update[=@var{which}]
+@opindex -u
+@opindex --update[=@var{which}]
+@cindex newer files, copying only
+Do not copy a non-directory that has an existing destination with the
+same or newer modification timestamp; instead, silently skip the file
+without failing.  If timestamps are being preserved,
+the comparison is to the source timestamp truncated to the
+resolutions of the destination file system and of the system calls
+used to update timestamps; this avoids duplicate work if several
+@samp{cp -pu} commands are executed with the same source and destination.
+This option is ignored if the @option{-n} or @option{--no-clobber}
+option is also specified.
+Also, if @option{--preserve=links} is also specified (like with @samp{cp -au}
+for example), that will take precedence; consequently, depending on the
+order that files are processed from the source, newer files in the destination
+may be replaced, to mirror hard links in the source.
+
+@macro whichUpdate
+@var{which} gives more control over which existing files in the
+destination are replaced, and its value can be one of the following:
+
+@table @samp
+@item all
+This is the default operation when an @option{--update} option is not specified,
+and results in all existing files in the destination being replaced.
+
+@item none
+This is similar to the @option{--no-clobber} option, in that no files in the
+destination are replaced, but also skipping a file does not induce a failure.
+
+@item older
+This is the default operation when @option{--update} is specified, and results
+in files being replaced if they're older than the corresponding source file.
+@end table
+@end macro
+@whichUpdate
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Print the name of each file before copying it.
+
+@item -x
+@itemx --one-file-system
+@opindex -x
+@opindex --one-file-system
+@cindex file systems, omitting copying to different
+Skip subdirectories that are on different file systems from the one that
+the copy started on.
+However, mount point directories @emph{are} copied.
+
+@macro optContext
+@item -Z
+@itemx --context[=@var{context}]
+@opindex -Z
+@opindex --context
+@cindex SELinux, setting/restoring security context
+@cindex security context
+Without a specified @var{context}, adjust the SELinux security context according
+to the system default type for destination files, similarly to the
+@command{restorecon} command.
+The long form of this option with a specific context specified,
+will set the context for newly created files only.
+With a specified context, if both SELinux and SMACK are disabled, a warning is
+issued.
+@end macro
+@optContext
+This option is mutually exclusive with the @option{--preserve=context}
+option, and overrides the @option{--preserve=all} and @option{-a} options.
+
+@end table
+
+@exitstatus
+
+
+@node dd invocation
+@section @command{dd}: Convert and copy a file
+
+@pindex dd
+@cindex converting while copying a file
+
+@command{dd} copies input to output with a changeable I/O block size,
+while optionally performing conversions on the data.  Synopses:
+
+@example
+dd [@var{operand}]@dots{}
+dd @var{option}
+@end example
+
+The only options are @option{--help} and @option{--version}.
+@xref{Common options}.
+
+By default, @command{dd} copies standard input to standard output.
+To copy, @command{dd} repeatedly does the following steps in order:
+
+@enumerate
+@item
+Read an input block.
+
+@item
+If converting via @samp{sync}, pad as needed to meet the input block size.
+Pad with spaces if converting via @samp{block} or @samp{unblock}, NUL
+bytes otherwise.
+
+@item
+If @samp{bs=} is given and no conversion mentioned in steps (4) or (5)
+is given, output the data as a single block and skip all remaining steps.
+
+@item
+If the @samp{swab} conversion is given, swap each pair of input bytes.
+If the input data length is odd, preserve the last input byte
+(since there is nothing to swap it with).
+
+@item
+If any of the conversions @samp{swab}, @samp{block}, @samp{unblock},
+@samp{lcase}, @samp{ucase}, @samp{ascii}, @samp{ebcdic} and @samp{ibm}
+are given, do these conversions.  These conversions operate
+independently of input blocking, and might deal with records that span
+block boundaries.
+
+@item
+Aggregate the resulting data into output blocks of the specified size,
+and output each output block in turn.  Do not pad the last output block;
+it can be shorter than usual.
+@end enumerate
+
+@command{dd} accepts the following operands,
+whose syntax was inspired by the DD (data definition) statement of
+OS/360 JCL.
+
+@table @samp
+
+@item if=@var{file}
+@opindex if
+Read from @var{file} instead of standard input.
+
+@item of=@var{file}
+@opindex of
+Write to @var{file} instead of standard output.  Unless
+@samp{conv=notrunc} is given, truncate @var{file} before writing it.
+
+@item ibs=@var{bytes}
+@opindex ibs
+@cindex block size of input
+@cindex input block size
+Set the input block size to @var{bytes}.
+This makes @command{dd} read @var{bytes} per block.
+The default is 512 bytes.
+
+@item obs=@var{bytes}
+@opindex obs
+@cindex block size of output
+@cindex output block size
+Set the output block size to @var{bytes}.
+This makes @command{dd} write @var{bytes} per block.
+The default is 512 bytes.
+
+@item bs=@var{bytes}
+@opindex bs
+@cindex block size
+Set both input and output block sizes to @var{bytes}.
+This makes @command{dd} read and write @var{bytes} per block,
+overriding any @samp{ibs} and @samp{obs} settings.
+In addition, if no data-transforming @option{conv} operand is specified,
+input is copied to the output as soon as it's read,
+even if it is smaller than the block size.
+
+@item cbs=@var{bytes}
+@opindex cbs
+@cindex block size of conversion
+@cindex conversion block size
+@cindex fixed-length records, converting to variable-length
+@cindex variable-length records, converting to fixed-length
+Set the conversion block size to @var{bytes}.
+When converting variable-length records to fixed-length ones
+(@option{conv=block}) or the reverse (@option{conv=unblock}),
+use @var{bytes} as the fixed record length.
+
+@item skip=@var{n}
+@itemx iseek=@var{n}
+@opindex skip
+@opindex iseek
+Skip @var{n} @samp{ibs}-byte blocks in the input file before copying.
+If @var{n} ends in the letter @samp{B}, interpret @var{n}
+as a byte count rather than a block count.
+(@samp{B} and the @samp{iseek=} spelling are GNU extensions to POSIX.)
+
+@item seek=@var{n}
+@itemx oseek=@var{n}
+@opindex seek
+@opindex oseek
+Skip @var{n} @samp{obs}-byte blocks in the output file before
+truncating or copying.
+If @var{n} ends in the letter @samp{B}, interpret @var{n}
+as a byte count rather than a block count.
+(@samp{B} and the @samp{oseek=} spelling are GNU extensions to POSIX.)
+
+@item count=@var{n}
+@opindex count
+Copy @var{n} @samp{ibs}-byte blocks from the input file, instead
+of everything until the end of the file.
+If @var{n} ends in the letter @samp{B},
+interpret @var{n} as a byte count rather than a block count;
+this is a GNU extension to POSIX.
+If short reads occur, as could be the case
+when reading from a pipe for example, @samp{iflag=fullblock}
+ensures that @samp{count=} counts complete input blocks
+rather than input read operations.
+As an extension to POSIX, @samp{count=0} copies zero blocks
+instead of copying all blocks.
+
+@item status=@var{level}
+@opindex status
+Specify the amount of information printed.
+If this operand is given multiple times, the last one takes precedence.
+The @var{level} value can be one of the following:
+
+@table @samp
+
+@item none
+@opindex none @r{dd status=}
+Do not print any informational or warning messages to standard error.
+Error messages are output as normal.
+
+@item noxfer
+@opindex noxfer @r{dd status=}
+Do not print the final transfer rate and volume statistics
+that normally make up the last status line.
+
+@item progress
+@opindex progress @r{dd status=}
+Print the transfer rate and volume statistics on standard error,
+when processing each input block.  Statistics are output
+on a single line at most once every second, but updates
+can be delayed when waiting on I/O.
+
+@end table
+
+Transfer information is normally output to standard error upon
+receipt of the @samp{INFO} signal or when @command{dd} exits,
+and defaults to the following form in the C locale:
+
+@example
+7287+1 records in
+116608+0 records out
+59703296 bytes (60 MB, 57 MiB) copied, 0.0427974 s, 1.4 GB/s
+@end example
+
+The notation @samp{@var{w}+@var{p}} stands for @var{w} whole blocks
+and @var{p} partial blocks.  A partial block occurs when a read or
+write operation succeeds but transfers less data than the block size.
+An additional line like @samp{1 truncated record} or @samp{10
+truncated records} is output after the @samp{records out} line if
+@samp{conv=block} processing truncated one or more input records.
+
+The @samp{status=} operand is a GNU extension to POSIX.
+
+@item conv=@var{conversion}[,@var{conversion}]@dots{}
+@opindex conv
+Convert the file as specified by the @var{conversion} argument(s).
+(No spaces around any comma(s).)
+
+Conversions:
+
+@table @samp
+
+@item ascii
+@opindex ascii@r{, converting to}
+Convert EBCDIC to ASCII,
+using the conversion table specified by POSIX@.
+This provides a 1:1 translation for all 256 bytes.
+This implies @samp{conv=unblock}; input is converted to
+ASCII before trailing spaces are deleted.
+
+@item ebcdic
+@opindex ebcdic@r{, converting to}
+Convert ASCII to EBCDIC@.
+This is the inverse of the @samp{ascii} conversion.
+This implies @samp{conv=block}; trailing spaces are added
+before being converted to EBCDIC@.
+
+@item ibm
+@opindex alternate ebcdic@r{, converting to}
+This acts like @samp{conv=ebcdic}, except it
+uses the alternate conversion table specified by POSIX@.
+This is not a 1:1 translation, but reflects common historical practice
+for @samp{~}, @samp{[}, and @samp{]}.
+
+The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are
+mutually exclusive.  If you use any of these conversions, you should also
+use the @samp{cbs=} operand.
+
+@item block
+@opindex block @r{(space-padding)}
+For each line in the input, output @samp{cbs} bytes, replacing the
+input newline with a space and truncating or padding input lines with
+spaces as necessary.
+
+@item unblock
+@opindex unblock
+Remove any trailing spaces in each @samp{cbs}-sized input block,
+and append a newline.
+
+The @samp{block} and @samp{unblock} conversions are mutually exclusive.
+If you use either of these conversions, you should also use the
+@samp{cbs=} operand.
+
+@item lcase
+@opindex lcase@r{, converting to}
+Change uppercase letters to lowercase.
+
+@item ucase
+@opindex ucase@r{, converting to}
+Change lowercase letters to uppercase.
+
+The @samp{lcase} and @samp{ucase} conversions are mutually exclusive.
+
+@item sparse
+@opindex sparse
+Try to seek rather than write NUL output blocks.
+On a file system that supports sparse files, this will create
+sparse output when extending the output file.
+Be careful when using this conversion in conjunction with
+@samp{conv=notrunc} or @samp{oflag=append}.
+With @samp{conv=notrunc}, existing data in the output file
+corresponding to NUL blocks from the input, will be untouched.
+With @samp{oflag=append} the seeks performed will be ineffective.
+Similarly, when the output is a device rather than a file,
+NUL input blocks are not copied, and therefore this conversion
+is most useful with virtual or pre zeroed devices.
+
+The @samp{sparse} conversion is a GNU extension to POSIX.
+
+@item swab
+@opindex swab @r{(byte-swapping)}
+@cindex byte-swapping
+Swap every pair of input bytes.
+
+@item sync
+@opindex sync @r{(padding with ASCII NULs)}
+Pad every input block to size of @samp{ibs} with trailing zero bytes.
+When used with @samp{block} or @samp{unblock}, pad with spaces instead of
+zero bytes.
+
+@end table
+
+The following ``conversions'' are really file flags
+and don't affect internal processing:
+
+@table @samp
+@item excl
+@opindex excl
+@cindex creating output file, requiring
+Fail if the output file already exists; @command{dd} must create the
+output file itself.
+
+@item nocreat
+@opindex nocreat
+@cindex creating output file, avoiding
+Do not create the output file; the output file must already exist.
+
+The @samp{excl} and @samp{nocreat} conversions are mutually exclusive,
+and are GNU extensions to POSIX.
+
+@item notrunc
+@opindex notrunc
+@cindex truncating output file, avoiding
+Do not truncate the output file.
+
+@item noerror
+@opindex noerror
+@cindex read errors, ignoring
+Continue after read errors.
+
+@item fdatasync
+@opindex fdatasync
+@cindex synchronized data writes, before finishing
+Synchronize output data just before finishing,
+even if there were write errors.
+This forces a physical write of output data,
+so that even if power is lost the output data will be preserved.
+If neither this nor @samp{fsync} are specified, output is treated as
+usual with file systems, i.e., output data and metadata may be cached
+in primary memory for some time before the operating system physically
+writes it, and thus output data and metadata may be lost if power is lost.
+@xref{sync invocation}.
+This conversion is a GNU extension to POSIX.
+
+@item fsync
+@opindex fsync
+@cindex synchronized data and metadata writes, before finishing
+Synchronize output data and metadata just before finishing,
+even if there were write errors.
+This acts like @samp{fdatasync} except it also preserves output metadata,
+such as the last-modified time of the output file; for this reason it
+may be a bit slower than @samp{fdatasync} although the performance
+difference is typically insignificant for @command{dd}.
+This conversion is a GNU extension to POSIX.
+
+@end table
+
+@item iflag=@var{flag}[,@var{flag}]@dots{}
+@opindex iflag
+Access the input file using the flags specified by the @var{flag}
+argument(s).  (No spaces around any comma(s).)
+
+@item oflag=@var{flag}[,@var{flag}]@dots{}
+@opindex oflag
+Access the output file using the flags specified by the @var{flag}
+argument(s).  (No spaces around any comma(s).)
+
+Here are the flags.
+
+@table @samp
+
+@item append
+@opindex append
+@cindex appending to the output file
+Write in append mode, so that even if some other process is writing to
+this file, every @command{dd} write will append to the current
+contents of the file.  This flag makes sense only for output.
+If you combine this flag with the @samp{of=@var{file}} operand,
+you should also specify @samp{conv=notrunc} unless you want the
+output file to be truncated before being appended to.
+
+@item cio
+@opindex cio
+@cindex concurrent I/O
+Use concurrent I/O mode for data.  This mode performs direct I/O
+and drops the POSIX requirement to serialize all I/O to the same file.
+A file cannot be opened in CIO mode and with a standard open at the
+same time.
+
+@item direct
+@opindex direct
+@cindex direct I/O
+Use direct I/O for data, avoiding the buffer cache.
+Note that the kernel may impose restrictions on read or write buffer sizes.
+For example, with an ext4 destination file system and a Linux-based kernel,
+using @samp{oflag=direct} will cause writes to fail with @code{EINVAL} if the
+output buffer size is not a multiple of 512.
+
+@item directory
+@opindex directory
+@cindex directory I/O
+
+Fail unless the file is a directory.  Most operating systems do not
+allow I/O to a directory, so this flag has limited utility.
+
+@item dsync
+@opindex dsync
+@cindex synchronized data reads
+Use synchronized I/O for data.  For the output file, this forces a
+physical write of output data on each write.  For the input file,
+this flag can matter when reading from a remote file that has been
+written to synchronously by some other process.  Metadata (e.g.,
+last-access and last-modified time) is not necessarily synchronized.
+
+@item sync
+@opindex sync
+@cindex synchronized data and metadata I/O
+Use synchronized I/O for both data and metadata.
+
+@item nocache
+@opindex nocache
+@cindex discarding file cache
+Request to discard the system data cache for a file.
+When count=0 all cached data for the file is specified,
+otherwise the cache is dropped for the processed
+portion of the file.  Also when count=0,
+failure to discard the cache is diagnosed
+and reflected in the exit status.
+
+Note data that is not already persisted to storage will not
+be discarded from cache, so note the use of the @samp{sync} conversions
+in the examples below, which are used to maximize the
+effectiveness of the @samp{nocache} flag.
+
+Here are some usage examples:
+
+@example
+# Advise to drop cache for whole file
+dd if=ifile iflag=nocache count=0
+
+# Ensure drop cache for the whole file
+dd of=ofile oflag=nocache conv=notrunc,fdatasync count=0
+
+# Advise to drop cache for part of file
+# Note the kernel will only consider complete and
+# already persisted pages.
+dd if=ifile iflag=nocache skip=10 count=10 of=/dev/null
+
+# Stream data using just the read-ahead cache.
+# See also the @samp{direct} flag.
+dd if=ifile of=ofile iflag=nocache oflag=nocache,sync
+@end example
+
+@item nonblock
+@opindex nonblock
+@cindex nonblocking I/O
+Use non-blocking I/O.
+
+@item noatime
+@opindex noatime
+@cindex access timestamp
+Do not update the file's access timestamp.
+@xref{File timestamps}.
+Some older file systems silently ignore this flag, so it is a good
+idea to test it on your files before relying on it.
+
+@item noctty
+@opindex noctty
+@cindex controlling terminal
+Do not assign the file to be a controlling terminal for @command{dd}.
+This has no effect when the file is not a terminal.
+On many hosts (e.g., GNU/Linux hosts), this flag has no effect
+at all.
+
+@item nofollow
+@opindex nofollow
+@cindex symbolic links, following
+Do not follow symbolic links.
+
+@item nolinks
+@opindex nolinks
+@cindex hard links
+Fail if the file has multiple hard links.
+
+@item binary
+@opindex binary
+@cindex binary I/O
+Use binary I/O@.  This flag has an effect only on nonstandard
+platforms that distinguish binary from text I/O.
+
+@item text
+@opindex text
+@cindex text I/O
+Use text I/O@.  Like @samp{binary}, this flag has no effect on
+standard platforms.
+
+@item fullblock
+@opindex fullblock
+Accumulate full blocks from input.  The @code{read} system call
+may return early if a full block is not available.
+When that happens, continue calling @code{read} to fill the remainder
+of the block.
+This flag can be used only with @code{iflag}.
+This flag is useful with pipes for example
+as they may return short reads. In that case,
+this flag is needed to ensure that a @samp{count=} argument is
+interpreted as a block count rather than a count of read operations.
+
+@end table
+
+These flags are all GNU extensions to POSIX.
+They are not supported on all systems, and @samp{dd} rejects
+attempts to use them when they are not supported.  When reading from
+standard input or writing to standard output, the @samp{nofollow} and
+@samp{noctty} flags should not be specified, and the other flags
+(e.g., @samp{nonblock}) can affect how other processes behave with the
+affected file descriptors, even after @command{dd} exits.
+
+@end table
+
+The behavior of @command{dd} is unspecified if operands other than
+@samp{conv=}, @samp{iflag=}, @samp{oflag=}, and @samp{status=} are
+specified more than once.
+
+@cindex multipliers after numbers
+The numeric-valued strings above (@var{n} and @var{bytes})
+are unsigned decimal integers that
+can be followed by a multiplier: @samp{b}=512, @samp{c}=1,
+@samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the
+standard block size suffixes like @samp{k}=1024 (@pxref{Block size}).
+These multipliers are GNU extensions to POSIX, except that
+POSIX allows @var{bytes} to be followed by @samp{k}, @samp{b}, and
+@samp{x@var{m}}. Note @samp{x@var{m}} can be used more than once in a number.
+Block sizes (i.e., specified by @var{bytes} strings) must be nonzero.
+
+Any block size you specify via @samp{bs=}, @samp{ibs=}, @samp{obs=}, @samp{cbs=}
+should not be too large -- values larger than a few megabytes
+are generally wasteful or (as in the gigabyte..exabyte case) downright
+counterproductive or error-inducing.
+
+To process data with offset or size that is not a multiple of the I/O
+block size, you can use a numeric string @var{n} that ends in the
+letter @samp{B}.
+For example, the following shell commands copy data
+in 1 MiB blocks between a flash drive and a tape, but do not save
+or restore a 512-byte area at the start of the flash drive:
+
+@example
+flash=/dev/sda
+tape=/dev/st0
+
+# Copy all but the initial 512 bytes from flash to tape.
+dd if=$flash iseek=512B bs=1MiB of=$tape
+
+# Copy from tape back to flash, leaving initial 512 bytes alone.
+dd if=$tape bs=1MiB of=$flash oseek=512B
+@end example
+
+@cindex ddrescue
+@cindex storage devices, failing
+For failing storage devices, other tools come with a great variety of extra
+functionality to ease the saving of as much data as possible before the
+device finally dies, e.g.
+@uref{https://www.gnu.org/software/ddrescue/, GNU @command{ddrescue}}.
+However, in some cases such a tool is not available or the administrator
+feels more comfortable with the handling of @command{dd}.
+As a simple rescue method, call @command{dd} as shown in the following
+example: the operand @samp{conv=noerror,sync} is used to continue
+after read errors and to pad out bad reads with NULs, while
+@samp{iflag=fullblock} caters for short reads (which traditionally never
+occur on flash or similar devices):
+
+@example
+# Rescue data from an (unmounted!) partition of a failing device.
+dd conv=noerror,sync iflag=fullblock </dev/sda1 > /mnt/rescue.img
+@end example
+
+Sending an @samp{INFO} signal (or @samp{USR1} signal where that is unavailable)
+to a running @command{dd} process makes it print I/O statistics to
+standard error and then resume copying.   In the example below,
+@command{dd} is run in the background to copy 5GB of data.
+The @command{kill} command makes it output intermediate I/O statistics,
+and when @command{dd} completes normally or is killed by the
+@code{SIGINT} signal, it outputs the final statistics.
+
+@example
+# Ignore the signal so we never inadvertently terminate the dd child.
+# Note this is not needed when SIGINFO is available.
+trap '' USR1
+
+# Run dd with the fullblock iflag to avoid short reads
+# which can be triggered by reception of signals.
+dd iflag=fullblock if=/dev/zero of=/dev/null count=5000000 bs=1000 & pid=$!
+
+# Output stats every second.
+while kill -s USR1 $pid 2>/dev/null; do sleep 1; done
+@end example
+
+The above script will output in the following format:
+
+@example
+3441325+0 records in
+3441325+0 records out
+3441325000 bytes (3.4 GB, 3.2 GiB) copied, 1.00036 s, 3.4 GB/s
+5000000+0 records in
+5000000+0 records out
+5000000000 bytes (5.0 GB, 4.7 GiB) copied, 1.44433 s, 3.5 GB/s
+@end example
+
+The @samp{status=progress} operand periodically updates the last line
+of the transfer statistics above.
+
+@vindex POSIXLY_CORRECT
+On systems lacking the @samp{INFO} signal @command{dd} responds to the
+@samp{USR1} signal instead, unless the @env{POSIXLY_CORRECT}
+environment variable is set.
+
+@exitstatus
+
+
+@node install invocation
+@section @command{install}: Copy files and set attributes
+
+@pindex install
+@cindex copying files and setting attributes
+
+@command{install} copies files while setting their file mode bits and, if
+possible, their owner and group.  Synopses:
+
+@example
+install [@var{option}]@dots{} [-T] @var{source} @var{dest}
+install [@var{option}]@dots{} @var{source}@dots{} @var{directory}
+install [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
+install [@var{option}]@dots{} -d @var{directory}@dots{}
+@end example
+
+@itemize @bullet
+@item
+If two file names are given, @command{install} copies the first file to the
+second.
+
+@item
+If the @option{--target-directory} (@option{-t}) option is given, or
+failing that if the last file is a directory and the
+@option{--no-target-directory} (@option{-T}) option is not given,
+@command{install} copies each @var{source} file to the specified
+directory, using the @var{source}s' names.
+
+@item
+If the @option{--directory} (@option{-d}) option is given,
+@command{install} creates each @var{directory} and any missing parent
+directories.  Parent directories are created with mode
+@samp{u=rwx,go=rx} (755), regardless of the @option{-m} option or the
+current umask.  @xref{Directory Setuid and Setgid}, for how the
+set-user-ID and set-group-ID bits of parent directories are inherited.
+@end itemize
+
+@cindex Makefiles, installing programs in
+@command{install} is similar to @command{cp}, but allows you to control the
+attributes of destination files.  It is typically used in Makefiles to
+copy programs into their destination directories.  It refuses to copy
+files onto themselves.
+
+@cindex extended attributes, xattr
+@command{install} never preserves extended attributes (xattr).
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@optBackup
+
+@item -C
+@itemx --compare
+@opindex -C
+@opindex --compare
+Compare content of source and destination files, and if there would be no
+change to the destination content, owner, group, permissions, and possibly
+SELinux context, then do not modify the destination at all.
+Note this option is best used in conjunction with @option{--user},
+@option{--group} and @option{--mode} options, lest @command{install}
+incorrectly determines the default attributes that installed files would have
+(as it doesn't consider setgid directories and POSIX default ACLs for example).
+This could result in redundant copies or attributes that are not reset to the
+correct defaults.
+
+@item -c
+@opindex -c
+Ignored; for compatibility with old Unix versions of @command{install}.
+
+@item -D
+@opindex -D
+Create any missing parent directories of @var{dest},
+then copy @var{source} to @var{dest}.
+Explicitly specifying the @option{--target-directory=@var{dir}} will similarly
+ensure the presence of that hierarchy before copying @var{source} arguments.
+
+@item -d
+@itemx --directory
+@opindex -d
+@opindex --directory
+@cindex directories, creating with given attributes
+@cindex parent directories, creating missing
+@cindex leading directories, creating missing
+Create any missing parent directories, giving them the default
+attributes.  Then create each given directory, setting their owner,
+group and mode as given on the command line or to the defaults.
+
+@optDebugCopy
+
+@item -g @var{group}
+@itemx --group=@var{group}
+@opindex -g
+@opindex --group
+@cindex group ownership of installed files, setting
+Set the group ownership of installed files or directories to
+@var{group}.  The default is the process's current group.  @var{group}
+may be either a group name or a numeric group ID.
+
+@item -m @var{mode}
+@itemx --mode=@var{mode}
+@opindex -m
+@opindex --mode
+@cindex permissions of installed files, setting
+Set the file mode bits for the installed file or directory to @var{mode},
+which can be either an octal number, or a symbolic mode as in
+@command{chmod}, with @samp{a=} (no access allowed to anyone) as the
+point of departure (@pxref{File permissions}).
+The default mode is @samp{u=rwx,go=rx,a-s} -- read, write, and
+execute for the owner, read and execute for group and other, and with
+set-user-ID and set-group-ID disabled.
+This default is not quite the same as @samp{755}, since it disables
+instead of preserving set-user-ID and set-group-ID on directories.
+@xref{Directory Setuid and Setgid}.
+
+@item -o @var{owner}
+@itemx --owner=@var{owner}
+@opindex -o
+@opindex --owner
+@cindex ownership of installed files, setting
+@cindex appropriate privileges
+@vindex root @r{as default owner}
+If @command{install} has appropriate privileges (is run as root), set the
+ownership of installed files or directories to @var{owner}.  The default
+is @code{root}.  @var{owner} may be either a user name or a numeric user
+ID.
+
+@item --preserve-context
+@opindex --preserve-context
+@cindex SELinux
+@cindex security context
+Preserve the SELinux security context of files and directories.
+Failure to preserve the context in all of the files or directories
+will result in an exit status of 1.  If SELinux is disabled then
+print a warning and ignore the option.
+
+@item -p
+@itemx --preserve-timestamps
+@opindex -p
+@opindex --preserve-timestamps
+@cindex timestamps of installed files, preserving
+Set the time of last access and the time of last modification of each
+installed file to match those of each corresponding original file.
+When a file is installed without this option, its last access and
+last modification timestamps are both set to the time of installation.
+This option is useful if you want to use the last modification timestamps
+of installed files to keep track of when they were last built as opposed
+to when they were last installed.
+
+@item -s
+@itemx --strip
+@opindex -s
+@opindex --strip
+@cindex symbol table information, stripping
+@cindex stripping symbol table information
+Strip the symbol tables from installed binary executables.
+
+@item --strip-program=@var{program}
+@opindex --strip-program
+@cindex symbol table information, stripping, program
+Program used to strip binaries.
+
+@optBackupSuffix
+
+@optTargetDirectory
+Also specifying the @option{-D} option will ensure the directory is present.
+
+@optNoTargetDirectory
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Print the name of each file before copying it.
+
+@optContext
+This option is mutually exclusive with the @option{--preserve-context} option.
+
+
+@end table
+
+@exitstatus
+
+
+@node mv invocation
+@section @command{mv}: Move (rename) files
+
+@pindex mv
+
+@command{mv} moves or renames files (or directories).  Synopses:
+
+@example
+mv [@var{option}]@dots{} [-T] @var{source} @var{dest}
+mv [@var{option}]@dots{} @var{source}@dots{} @var{directory}
+mv [@var{option}]@dots{} -t @var{directory} @var{source}@dots{}
+@end example
+
+@itemize @bullet
+@item
+If two file names are given, @command{mv} moves the first file to the
+second.
+
+@item
+If the @option{--target-directory} (@option{-t}) option is given, or
+failing that if the last file is a directory and the
+@option{--no-target-directory} (@option{-T}) option is not given,
+@command{mv} moves each @var{source} file to the specified
+directory, using the @var{source}s' names.
+@end itemize
+
+To move a file, @command{mv} ordinarily simply renames it.
+However, if renaming does not work because the destination's file
+system differs, @command{mv} falls back on copying as if by @code{cp -a},
+then (assuming the copy succeeded) it removes the original.
+If the copy fails, then @command{mv} removes any partially created
+copy in the destination.  If you were to copy three directories from
+one file system to another and the copy of the first
+directory succeeded, but the second didn't, the first would be left on
+the destination file system and the second and third would be left on the
+original file system.
+
+@cindex extended attributes, xattr
+@command{mv} always tries to copy extended attributes (xattr), which may
+include SELinux context, ACLs or Capabilities.
+Upon failure all but @samp{Operation not supported} warnings are output.
+
+@cindex prompting, and @command{mv}
+If a destination file exists but is normally unwritable, standard input
+is a terminal, and the @option{-f} or @option{--force} option is not given,
+@command{mv} prompts the user for whether to replace the file.  (You might
+own the file, or have write permission on its directory.)  If the
+response is not affirmative, the file is skipped.
+
+@emph{Warning}: Avoid specifying a source name with a trailing slash,
+when it might be a symlink to a directory.
+Otherwise, @command{mv} may do something very surprising, since
+its behavior depends on the underlying rename system call.
+On a system with a modern Linux-based kernel, it fails with
+@code{errno=ENOTDIR}@.
+However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently
+renames not the symlink but rather the directory referenced by the symlink.
+@xref{Trailing slashes}.
+
+@emph{Note}: @command{mv} will only replace empty directories in the
+destination.  Conflicting populated directories are skipped with a diagnostic.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@optBackup
+
+@optDebugCopy
+
+@item -f
+@itemx --force
+@opindex -f
+@opindex --force
+@cindex prompts, omitting
+Do not prompt the user before removing a destination file.
+@macro mvOptsIfn
+If you specify more than one of the @option{-i}, @option{-f}, @option{-n}
+options, only the final one takes effect.
+@end macro
+@mvOptsIfn
+
+@item -i
+@itemx --interactive
+@opindex -i
+@opindex --interactive
+@cindex prompts, forcing
+Prompt whether to overwrite each existing destination file, regardless
+of its permissions, and fail if the response is not affirmative.
+@mvOptsIfn
+
+@item -n
+@itemx --no-clobber
+@opindex -n
+@opindex --no-clobber
+@cindex prompts, omitting
+Do not overwrite an existing file; silently fail instead.
+@mvOptsIfn
+This option is mutually exclusive with @option{-b} or @option{--backup} option.
+See also the @option{--update=none} option which will
+skip existing files but not fail.
+
+@item --no-copy
+@opindex --no-copy
+@cindex renaming files without copying them
+If a file cannot be renamed because the destination file system differs,
+fail with a diagnostic instead of copying and then removing the file.
+
+@item -u
+@itemx --update
+@opindex -u
+@opindex --update
+@cindex newer files, moving only
+Do not move a non-directory that has an existing destination with the
+same or newer modification timestamp;
+instead, silently skip the file without failing.
+If the move is across file system boundaries, the comparison is to the
+source timestamp truncated to the resolutions of the destination file
+system and of the system calls used to update timestamps; this avoids
+duplicate work if several @samp{mv -u} commands are executed with the
+same source and destination.
+This option is ignored if the @option{-n} or @option{--no-clobber}
+option is also specified.
+
+@whichUpdate
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Print the name of each file before moving it.
+
+@optStripTrailingSlashes
+
+@optBackupSuffix
+
+@optTargetDirectory
+
+@optNoTargetDirectory
+
+@item -Z
+@itemx --context
+@opindex -Z
+@opindex --context
+@cindex SELinux, restoring security context
+@cindex security context
+This option functions similarly to the @command{restorecon} command,
+by adjusting the SELinux security context according
+to the system default type for destination files and each created directory.
+
+@end table
+
+@exitstatus
+
+
+@node rm invocation
+@section @command{rm}: Remove files or directories
+
+@pindex rm
+@cindex removing files or directories
+
+@command{rm} removes each given @var{file}.  By default, it does not remove
+directories.  Synopsis:
+
+@example
+rm [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+@cindex prompting, and @command{rm}
+If the @option{-I} or @option{--interactive=once} option is given,
+and there are more than three files or the @option{-r}, @option{-R},
+or @option{--recursive} are given, then @command{rm} prompts the user
+for whether to proceed with the entire operation.  If the response is
+not affirmative, the entire command is aborted.
+
+Otherwise, if a file is unwritable, standard input is a terminal, and
+the @option{-f} or @option{--force} option is not given, or the
+@option{-i} or @option{--interactive=always} option @emph{is} given,
+@command{rm} prompts the user for whether to remove the file.
+If the response is not affirmative, the file is skipped.
+
+Any attempt to remove a file whose last file name component is
+@file{.} or @file{..} is rejected without any prompting, as mandated
+by POSIX.
+
+@emph{Warning}: If you use @command{rm} to remove a file, it is usually
+possible to recover the contents of that file.  If you want more assurance
+that the contents are unrecoverable, consider using @command{shred}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -d
+@itemx --dir
+@opindex -d
+@opindex --dir
+@cindex directories, removing
+Remove the listed directories if they are empty.
+
+@item -f
+@itemx --force
+@opindex -f
+@opindex --force
+Ignore nonexistent files and missing operands, and never prompt the user.
+Ignore any previous @option{--interactive} (@option{-i}) option.
+
+@item -i
+@opindex -i
+Prompt whether to remove each file.
+If the response is not affirmative, silently skip the file without failing.
+Ignore any previous @option{--force} (@option{-f}) option.
+Equivalent to @option{--interactive=always}.
+
+@item -I
+@opindex -I
+Prompt once whether to proceed with the command, if more than three
+files are named or if a recursive removal is requested.  Ignore any
+previous @option{--force} (@option{-f}) option.  Equivalent to
+@option{--interactive=once}.
+
+@item --interactive [=@var{when}]
+@opindex --interactive
+Specify when to issue an interactive prompt.  @var{when} may be
+omitted, or one of:
+@itemize @bullet
+@item never
+@vindex never @r{interactive option}
+- Do not prompt at all.
+@item once
+@vindex once @r{interactive option}
+- Prompt once if more than three files are named or if a recursive
+removal is requested.  Equivalent to @option{-I}.
+@item always
+@vindex always @r{interactive option}
+- Prompt for every file being removed.  Equivalent to @option{-i}.
+@end itemize
+@option{--interactive} with no @var{when} is equivalent to
+@option{--interactive=always}.
+
+@item --one-file-system
+@opindex --one-file-system
+@cindex one file system, restricting @command{rm} to
+When removing a hierarchy recursively, do not remove any directory that is on a
+file system different from that of the corresponding command line argument.
+@cindex bind mount
+This option is useful when removing a build ``chroot'' hierarchy,
+which normally contains no valuable data.  However, it is not uncommon
+to bind-mount @file{/home} into such a hierarchy, to make it easier to
+use one's start-up file.  The catch is that it's easy to forget to
+unmount @file{/home}.  Then, when you use @command{rm -rf} to remove
+your normally throw-away chroot, that command will remove everything
+under @file{/home}, too.
+Use the @option{--one-file-system} option, and it will
+diagnose and skip directories on other file systems.
+Of course, this will not save your @file{/home} if it and your
+chroot happen to be on the same file system.
+See also @option{--preserve-root=all} to protect command line arguments
+themselves.
+
+@item --preserve-root [=all]
+@opindex --preserve-root
+@cindex root directory, disallow recursive destruction
+Fail upon any attempt to remove the root directory, @file{/},
+when used with the @option{--recursive} option.
+This is the default behavior.
+@xref{Treating / specially}.
+When @samp{all} is specified, reject any command line argument
+that is not on the same file system as its parent.
+
+@item --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive destruction
+Do not treat @file{/} specially when removing recursively.
+This option is not recommended unless you really want to
+remove all the files on your computer.
+@xref{Treating / specially}.
+
+@item -r
+@itemx -R
+@itemx --recursive
+@opindex -r
+@opindex -R
+@opindex --recursive
+@cindex directories, removing (recursively)
+Remove the listed directories and their contents recursively.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Print the name of each file before removing it.
+
+@end table
+
+@cindex files beginning with @samp{-}, removing
+@cindex @samp{-}, removing files beginning with
+One common question is how to remove files whose names begin with a
+@samp{-}.  GNU @command{rm}, like every program that uses the @code{getopt}
+function to parse its arguments, lets you use the @samp{--} option to
+indicate that all following arguments are non-options.  To remove a file
+called @file{-f} in the current directory, you could type either:
+
+@example
+rm -- -f
+@end example
+
+@noindent
+or:
+
+@example
+rm ./-f
+@end example
+
+@opindex - @r{and Unix @command{rm}}
+The Unix @command{rm} program's use of a single @samp{-} for this purpose
+predates the development of the @code{getopt} standard syntax.
+
+@exitstatus
+
+
+@node shred invocation
+@section @command{shred}: Remove files more securely
+
+@pindex shred
+@cindex data, erasing
+@cindex erasing data
+
+@command{shred} overwrites devices or files, to help prevent even
+extensive forensics from recovering the data.
+
+Ordinarily when you remove a file (@pxref{rm invocation}), its data
+and metadata are not actually destroyed.  Only the file's directory
+entry is removed, and the file's storage is reclaimed only when no
+process has the file open and no other directory entry links to the
+file.  And even if file's data and metadata's storage space is freed
+for further reuse, there are undelete utilities that will attempt to
+reconstruct the file from the data in freed storage, and that can
+bring the file back if the storage was not rewritten.
+
+On a busy system with a nearly-full device, space can get reused in a few
+seconds.  But there is no way to know for sure.  And although the
+undelete utilities and already-existing processes require insider or
+superuser access, you may be wary of the superuser,
+of processes running on your behalf, or of attackers
+that can physically access the storage device.  So if you have sensitive
+data, you may want to be sure that recovery is not possible
+by plausible attacks like these.
+
+The best way to remove something irretrievably is to destroy the media
+it's on with acid, melt it down, or the like.  For cheap removable media
+this is often the preferred method.  However, some storage devices
+are expensive or are harder to destroy, so the @command{shred} utility tries
+to achieve a similar effect non-destructively, by overwriting the file
+with non-sensitive data.
+
+@strong{Please note} that @command{shred} relies on a crucial
+assumption: that the file system and hardware overwrite data in place.
+Although this is common and is the traditional
+way to do things, many modern file system designs do not satisfy this
+assumption.  Exceptions include:
+
+@itemize @bullet
+
+@item
+Log-structured or journaled file systems, such as ext3/ext4 (in
+@code{data=journal} mode), Btrfs, NTFS, ReiserFS, XFS, ZFS, file
+systems supplied with AIX and Solaris, etc., when they are configured to
+journal data.
+
+@item
+File systems that write redundant data and carry on even if some writes
+fail, such as RAID-based file systems.
+
+@item
+File systems that make snapshots, such as Network Appliance's NFS server.
+
+@item
+File systems that cache in temporary locations, such as NFS version 3
+clients.
+
+@item
+Compressed file systems.
+@end itemize
+
+For ext3 and ext4 file systems, @command{shred} is less effective
+when the file system is in @code{data=journal}
+mode, which journals file data in addition to just metadata.  In both
+the @code{data=ordered} (default) and @code{data=writeback} modes,
+@command{shred} works as usual.  The ext3/ext4 journaling modes can be changed
+by adding the @code{data=something} option to the mount options for a
+particular file system in the @file{/etc/fstab} file, as documented in
+the @command{mount} man page (@samp{man mount}).  Alternatively, if
+you know how large the journal is, you can shred the journal by
+shredding enough file data so that the journal cycles around and fills
+up with shredded data.
+
+If you are not sure how your file system operates, then you should assume
+that it does not overwrite data in place, which means @command{shred} cannot
+reliably operate on regular files in your file system.
+
+Generally speaking, it is more reliable to shred a device than a file,
+since this bypasses file system design issues mentioned above.
+However, devices are also problematic for shredding, for reasons
+such as the following:
+
+@itemize @bullet
+
+@item
+Solid-state storage devices (SSDs) typically do wear leveling to
+prolong service life, and this means writes are distributed to other
+blocks by the hardware, so ``overwritten'' data blocks are still
+present in the underlying device.
+
+@item
+Most storage devices map out bad blocks invisibly to
+the application; if the bad blocks contain sensitive data,
+@command{shred} won't be able to destroy it.
+
+@item
+With some obsolete storage technologies,
+it may be possible to take (say) a floppy disk back
+to a laboratory and use a lot of sensitive (and expensive) equipment
+to look for the faint ``echoes'' of the original data underneath the
+overwritten data.  With these older technologies, if the file has been
+overwritten only once, it's reputedly not even that hard.  Luckily,
+this kind of data recovery has become difficult, and there is no
+public evidence that today's higher-density storage devices can be
+analyzed in this way.
+
+The @command{shred} command can use many overwrite passes,
+with data patterns chosen to
+maximize the damage they do to the old data.
+By default the patterns are designed for best effect on hard drives using
+now-obsolete technology; for newer devices, a single pass should suffice.
+For more details, see the source code and Peter Gutmann's paper
+@uref{https://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html,
+@cite{Secure Deletion of Data from Magnetic and Solid-State Memory}},
+from the proceedings of the Sixth USENIX Security Symposium (San Jose,
+California, July 22--25, 1996).
+@end itemize
+
+@command{shred} makes no attempt to detect or report these problems, just as
+it makes no attempt to do anything about backups.  However, since it is
+more reliable to shred devices than files, @command{shred} by default does
+not deallocate or remove the output file.  This default is more suitable
+for devices, which typically cannot be deallocated and should not be
+removed.
+
+Finally, consider the risk of backups and mirrors.
+File system backups and remote mirrors may contain copies of the
+file that cannot be removed, and that will allow a shredded file
+to be recovered later.  So if you keep any data you may later want
+to destroy using @command{shred}, be sure that it is not backed up or mirrored.
+
+@example
+shred [@var{option}]@dots{} @var{file}[@dots{}]
+@end example
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -f
+@itemx --force
+@opindex -f
+@opindex --force
+@cindex force deletion
+Override file permissions if necessary to allow overwriting.
+
+@item -n @var{number}
+@itemx --iterations=@var{number}
+@opindex -n @var{number}
+@opindex --iterations=@var{number}
+@cindex iterations, selecting the number of
+By default, @command{shred} uses @value{SHRED_DEFAULT_PASSES} passes of
+overwrite.  You can reduce this to save time, or increase it if you think it's
+appropriate.  After 25 passes all of the internal overwrite patterns will have
+been used at least once.
+
+@item --random-source=@var{file}
+@opindex --random-source
+@cindex random source for shredding
+Use @var{file} as a source of random data used to overwrite and to
+choose pass ordering.  @xref{Random sources}.
+
+@item -s @var{bytes}
+@itemx --size=@var{bytes}
+@opindex -s @var{bytes}
+@opindex --size=@var{bytes}
+@cindex size of file to shred
+Shred the first @var{bytes} bytes of the file.  The default is to shred
+the whole file.  @var{bytes} can be followed by a size specification like
+@samp{K}, @samp{M}, or @samp{G} to specify a multiple.  @xref{Block size}.
+
+@item -u
+@itemx --remove[=@var{how}]
+@opindex -u
+@opindex --remove
+@opindex --remove=unlink
+@opindex --remove=wipe
+@opindex --remove=wipesync
+@cindex removing files after shredding
+After shredding a file, deallocate it (if possible) and then remove it.
+If a file has multiple links, only the named links will be removed.
+Often the file name is less sensitive than the file data, in which case
+the optional @var{how} parameter, supported with the long form option,
+gives control of how to more efficiently remove each directory entry.
+The @samp{unlink} parameter will just use a standard unlink call,
+@samp{wipe} will also first obfuscate bytes in the name, and
+@samp{wipesync} will also sync each obfuscated byte in the name to
+the file system.
+Note @samp{wipesync} is the default method, but can be expensive,
+requiring a sync for every character in every file.  This can become
+significant with many files, or is redundant if your file system provides
+synchronous metadata updates.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Display to standard error all status updates as sterilization proceeds.
+
+@item -x
+@itemx --exact
+@opindex -x
+@opindex --exact
+By default, @command{shred} rounds the size of a regular file up to the next
+multiple of the file system block size to fully erase the slack space in
+the last block of the file.  This space may contain portions of the current
+system memory on some systems for example.
+Use @option{--exact} to suppress that behavior.
+Thus, by default if you shred a 10-byte regular file on a system with 512-byte
+blocks, the resulting file will be 512 bytes long.  With this option,
+shred does not increase the apparent size of the file.
+
+@item -z
+@itemx --zero
+@opindex -z
+@opindex --zero
+Normally, the last pass that @command{shred} writes is made up of
+random data.  If this would be conspicuous on your storage device (for
+example, because it looks like encrypted data), or you just think
+it's tidier, the @option{--zero} option adds an additional overwrite pass with
+all zero bits.  This is in addition to the number of passes specified
+by the @option{--iterations} option.
+
+@end table
+
+You might use the following command to erase the file system you
+created on a USB flash drive.  This command typically takes several
+minutes, depending on the drive's size and write speed.  On modern
+storage devices a single pass should be adequate, and will take one
+third the time of the default three-pass approach.
+
+@example
+shred -v -n 1 /dev/sdd1
+@end example
+
+Similarly, to erase all data on a selected partition of
+your device, you could give a command like the following.
+
+@example
+# 1 pass, write pseudo-random data; 3x faster than the default
+shred -v -n1 /dev/sda5
+@end example
+
+To be on the safe side, use at least one pass that overwrites using
+pseudo-random data.  I.e., don't be tempted to use @samp{-n0 --zero},
+in case some device controller optimizes the process of writing blocks
+of all zeros, and thereby does not clear all bytes in a block.
+Some SSDs may do just that.
+
+A @var{file} of @samp{-} denotes standard output.
+The intended use of this is to shred a removed temporary file.
+For example:
+
+@example
+i=$(mktemp)
+exec 3<>"$i"
+rm -- "$i"
+echo "Hello, world" >&3
+shred - >&3
+exec 3>-
+@end example
+
+However, the command @samp{shred - >file} does not shred the contents
+of @var{file}, since the shell truncates @var{file} before invoking
+@command{shred}.  Use the command @samp{shred file} or (if using a
+Bourne-compatible shell) the command @samp{shred - 1<>file} instead.
+
+@exitstatus
+
+
+@node Special file types
+@chapter Special file types
+
+@cindex special file types
+@cindex file types, special
+
+This chapter describes commands which create special types of files (and
+@command{rmdir}, which removes directories, one special file type).
+
+@cindex special file types
+@cindex file types
+Although Unix-like operating systems have markedly fewer special file
+types than others, not @emph{everything} can be treated only as the
+undifferentiated byte stream of @dfn{normal files}.  For example, when a
+file is created or removed, the system must record this information,
+which it does in a @dfn{directory} -- a special type of file.  Although
+you can read directories as normal files, if you're curious, in order
+for the system to do its job it must impose a structure, a certain
+order, on the bytes of the file.  Thus it is a ``special'' type of file.
+
+Besides directories, other special file types include named pipes
+(FIFOs), symbolic links, sockets, and so-called @dfn{special files}.
+
+@menu
+* link invocation::             Make a hard link via the link syscall
+* ln invocation::               Make links between files.
+* mkdir invocation::            Make directories.
+* mkfifo invocation::           Make FIFOs (named pipes).
+* mknod invocation::            Make block or character special files.
+* readlink invocation::         Print value of a symlink or canonical file name.
+* rmdir invocation::            Remove empty directories.
+* unlink invocation::           Remove files via the unlink syscall
+@end menu
+
+
+@node link invocation
+@section @command{link}: Make a hard link via the link syscall
+
+@pindex link
+@cindex links, creating
+@cindex hard links, creating
+@cindex creating links (hard only)
+
+@command{link} creates a single hard link at a time.
+It is a minimalist interface to the system-provided
+@code{link} function.  @xref{Hard Links, , , libc,
+The GNU C Library Reference Manual}.
+It avoids the bells and whistles of the more commonly-used
+@command{ln} command (@pxref{ln invocation}).
+Synopsis:
+
+@example
+link @var{filename} @var{linkname}
+@end example
+
+@var{filename} must specify an existing file, and @var{linkname}
+must specify a nonexistent entry in an existing directory.
+@command{link} simply calls @code{link (@var{filename}, @var{linkname})}
+to create the link.
+
+On a GNU system, this command acts like @samp{ln --directory
+--no-target-directory @var{filename} @var{linkname}}.  However, the
+@option{--directory} and @option{--no-target-directory} options are
+not specified by POSIX, and the @command{link} command is
+more portable in practice.
+
+If @var{filename} is a symbolic link, it is unspecified whether
+@var{linkname} will be a hard link to the symbolic link or to the
+target of the symbolic link.  Use @command{ln -P} or @command{ln -L}
+to specify which behavior is desired.
+
+@exitstatus
+
+
+@node ln invocation
+@section @command{ln}: Make links between files
+
+@pindex ln
+@cindex links, creating
+@cindex hard links, creating
+@cindex symbolic (soft) links, creating
+@cindex creating links (hard or soft)
+
+@cindex file systems and hard links
+@command{ln} makes links between files.  By default, it makes hard links;
+with the @option{-s} option, it makes symbolic (or @dfn{soft}) links.
+Synopses:
+
+@example
+ln [@var{option}]@dots{} [-T] @var{target} @var{linkname}
+ln [@var{option}]@dots{} @var{target}
+ln [@var{option}]@dots{} @var{target}@dots{} @var{directory}
+ln [@var{option}]@dots{} -t @var{directory} @var{target}@dots{}
+@end example
+
+@itemize @bullet
+
+@item
+If two file names are given, @command{ln} creates a link to the first
+file from the second.
+
+@item
+If one @var{target} is given, @command{ln} creates a link to that file
+in the current directory.
+
+@item
+If the @option{--target-directory} (@option{-t}) option is given, or
+failing that if the last file is a directory and the
+@option{--no-target-directory} (@option{-T}) option is not given,
+@command{ln} creates a link to each @var{target} file in the specified
+directory, using the @var{target}s' names.
+
+@end itemize
+
+Normally @command{ln} does not replace existing files.  Use the
+@option{--force} (@option{-f}) option to replace them unconditionally,
+the @option{--interactive} (@option{-i}) option to replace them
+conditionally, and the @option{--backup} (@option{-b}) option to
+rename them.  Unless the @option{--backup} (@option{-b}) option is
+used there is no brief moment when the destination does not exist;
+this is an extension to POSIX.
+
+@cindex hard link, defined
+@cindex inode, and hard links
+A @dfn{hard link} is another name for an existing file; the link and the
+original are indistinguishable.  Technically speaking, they share the
+same inode, and the inode contains all the information about a
+file -- indeed, it is not incorrect to say that the inode @emph{is} the
+file.  Most systems prohibit making a hard link to
+a directory; on those where it is allowed, only the super-user can do
+so (and with caution, since creating a cycle will cause problems to many
+other utilities).  Hard links cannot cross file system boundaries.  (These
+restrictions are not mandated by POSIX, however.)
+
+@cindex dereferencing symbolic links
+@cindex symbolic link, defined
+@dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are
+a special file type (which not all kernels support: System V release 3
+(and older) systems lack symlinks) in which the link file actually
+refers to a different file, by name.  When most operations (opening,
+reading, writing, and so on) are passed the symbolic link file, the
+kernel automatically @dfn{dereferences} the link and operates on the
+target of the link.  But some operations (e.g., removing) work on the
+link file itself, rather than on its target.  The owner and group of a
+symlink are not significant to file access performed through
+the link, but do have implications on deleting a symbolic link from a
+directory with the restricted deletion bit set.  On the GNU system,
+the mode of a symlink has no significance and cannot be changed, but
+on some BSD systems, the mode can be changed and will affect whether
+the symlink will be traversed in file name resolution.  @xref{Symbolic Links,,,
+libc, The GNU C Library Reference Manual}.
+
+Symbolic links can contain arbitrary strings; a @dfn{dangling symlink}
+occurs when the string in the symlink does not resolve to a file.
+There are no restrictions against creating dangling symbolic links.
+There are trade-offs to using absolute or relative symlinks.  An
+absolute symlink always points to the same file, even if the directory
+containing the link is moved.  However, if the symlink is visible from
+more than one machine (such as on a networked file system), the file
+pointed to might not always be the same.  A relative symbolic link is
+resolved in relation to the directory that contains the link, and is
+often useful in referring to files on the same device without regards
+to what name that device is mounted on when accessed via networked
+machines.
+
+When creating a relative symlink in a different location than the
+current directory, the resolution of the symlink will be different
+than the resolution of the same string from the current directory.
+Therefore, many users prefer to first change directories to the
+location where the relative symlink will be created, so that
+tab-completion or other file resolution will find the same target as
+what will be placed in the symlink.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@optBackup
+
+@item -d
+@itemx -F
+@itemx --directory
+@opindex -d
+@opindex -F
+@opindex --directory
+@cindex hard links to directories
+Allow users with appropriate privileges to attempt to make hard links
+to directories.
+However, note that this will probably fail due to
+system restrictions, even for the super-user.
+
+@item -f
+@itemx --force
+@opindex -f
+@opindex --force
+Remove existing destination files.
+
+@item -i
+@itemx --interactive
+@opindex -i
+@opindex --interactive
+@cindex prompting, and @command{ln}
+Prompt whether to remove existing destination files,
+and fail if the response is not affirmative.
+
+@item -L
+@itemx --logical
+@opindex -L
+@opindex --logical
+If @option{-s} is not in effect, and the source file is a symbolic
+link, create the hard link to the file referred to by the symbolic
+link, rather than the symbolic link itself.
+
+@item -n
+@itemx --no-dereference
+@opindex -n
+@opindex --no-dereference
+Do not treat the last operand specially when it is a symbolic link to
+a directory.  Instead, treat it as if it were a normal file.
+
+When the destination is an actual directory (not a symlink to one),
+there is no ambiguity.  The link is created in that directory.
+But when the specified destination is a symlink to a directory,
+there are two ways to treat the user's request.  @command{ln} can
+treat the destination just as it would a normal directory and create
+the link in it.  On the other hand, the destination can be viewed as a
+non-directory -- as the symlink itself.  In that case, @command{ln}
+must delete or backup that symlink before creating the new link.
+The default is to treat a destination that is a symlink to a directory
+just like a directory.
+
+This option is weaker than the @option{--no-target-directory}
+(@option{-T}) option, so it has no effect if both options are given.
+
+@item -P
+@itemx --physical
+@opindex -P
+@opindex --physical
+If @option{-s} is not in effect, and the source file is a symbolic
+link, create the hard link to the symbolic link itself.  On platforms
+where this is not supported by the kernel, this option creates a
+symbolic link with identical contents; since symbolic link contents
+cannot be edited, any file name resolution performed through either
+link will be the same as if a hard link had been created.
+
+@item -r
+@itemx --relative
+@opindex -r
+@opindex --relative
+Make symbolic links relative to the link location.
+This option is only valid with the @option{--symbolic} option.
+
+Example:
+
+@example
+ln -srv /a/file /tmp
+'/tmp/file' -> '../a/file'
+@end example
+
+Relative symbolic links are generated based on their canonicalized
+containing directory, and canonicalized targets.  I.e., all symbolic
+links in these file names will be resolved.
+@xref{realpath invocation}, which gives greater control
+over relative file name generation, as demonstrated in the following example:
+
+@example
+@verbatim
+ln--relative() {
+  test "$1" = --no-symlinks && { nosym=$1; shift; }
+  target="$1";
+  test -d "$2" && link="$2/." || link="$2"
+  rtarget="$(realpath $nosym -m "$target" \
+              --relative-to "$(dirname "$link")")"
+  ln -s -v "$rtarget" "$link"
+}
+@end verbatim
+@end example
+
+@item -s
+@itemx --symbolic
+@opindex -s
+@opindex --symbolic
+Make symbolic links instead of hard links.  This option merely produces
+an error message on systems that do not support symbolic links.
+
+@optBackupSuffix
+
+@optTargetDirectory
+
+@optNoTargetDirectory
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Print the name of each file after linking it successfully.
+
+@end table
+
+@cindex hard links to symbolic links
+@cindex symbolic links and @command{ln}
+If @option{-L} and @option{-P} are both given, the last one takes
+precedence.  If @option{-s} is also given, @option{-L} and @option{-P}
+are silently ignored.  If neither option is given, then this
+implementation defaults to @option{-P} if the system @code{link} supports
+hard links to symbolic links (such as the GNU system), and @option{-L}
+if @code{link} follows symbolic links (such as on BSD).
+
+@exitstatus
+
+Examples:
+
+@example
+Bad Example:
+
+# Create link ../a pointing to a in that directory.
+# Not really useful because it points to itself.
+ln -s a ..
+
+Better Example:
+
+# Change to the target before creating symlinks to avoid being confused.
+cd ..
+ln -s adir/a .
+
+Bad Example:
+
+# Hard coded file names don't move well.
+ln -s $(pwd)/a /some/dir/
+
+Better Example:
+
+# Relative file names survive directory moves and also
+# work across networked file systems.
+ln -s afile anotherfile
+ln -s ../adir/afile yetanotherfile
+@end example
+
+
+@node mkdir invocation
+@section @command{mkdir}: Make directories
+
+@pindex mkdir
+@cindex directories, creating
+@cindex creating directories
+
+@command{mkdir} creates directories with the specified names.  Synopsis:
+
+@example
+mkdir [@var{option}]@dots{} @var{name}@dots{}
+@end example
+
+@command{mkdir} creates each directory @var{name} in the order given.
+It reports an error if @var{name} already exists, unless the
+@option{-p} option is given and @var{name} is a directory.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -m @var{mode}
+@itemx --mode=@var{mode}
+@opindex -m
+@opindex --mode
+@cindex modes of created directories, setting
+Set the file permission bits of created directories to @var{mode},
+which uses the same syntax as
+in @command{chmod} and uses @samp{a=rwx} (read, write and execute allowed for
+everyone) for the point of the departure.  @xref{File permissions}.
+This option affects only directories given on the command line;
+it does not affect any parents that may be created via the @option{-p} option.
+
+Normally the directory has the desired file mode bits at the moment it
+is created.  As a GNU extension, @var{mode} may also mention
+special mode bits, but in this case there may be a temporary window
+during which the directory exists but its special mode bits are
+incorrect.  @xref{Directory Setuid and Setgid}, for how the
+set-user-ID and set-group-ID bits of directories are inherited unless
+overridden in this way.
+
+@item -p
+@itemx --parents
+@opindex -p
+@opindex --parents
+@cindex parent directories, creating
+Make any missing parent directories for each argument, setting their
+file permission bits to @samp{=rwx,u+wx},
+that is, with the umask modified by @samp{u+wx}.  Ignore
+existing parent directories, and do not change their file permission
+bits.
+
+If the @option{-m} option is also given, it does not affect
+file permission bits of any newly-created parent directories.
+To control these bits, set the
+umask before invoking @command{mkdir}.  For example, if the shell
+command @samp{(umask u=rwx,go=rx; mkdir -p P/Q)} creates the parent
+@file{P} it sets the parent's file permission bits to @samp{u=rwx,go=rx}.
+(The umask must include @samp{u=wx} for this method to work.)
+To set a parent's special mode bits as well, you can invoke
+@command{chmod} after @command{mkdir}.  @xref{Directory Setuid and
+Setgid}, for how the set-user-ID and set-group-ID bits of
+newly-created parent directories are inherited.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Print a message for each created directory.  This is most useful with
+@option{--parents}.
+
+@optContext
+
+@end table
+
+@exitstatus
+
+
+@node mkfifo invocation
+@section @command{mkfifo}: Make FIFOs (named pipes)
+
+@pindex mkfifo
+@cindex FIFOs, creating
+@cindex named pipes, creating
+@cindex creating FIFOs (named pipes)
+
+@command{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the
+specified names.  Synopsis:
+
+@example
+mkfifo [@var{option}] @var{name}@dots{}
+@end example
+
+A @dfn{FIFO} is a special file type that permits independent processes
+to communicate.  One process opens the FIFO file for writing, and
+another for reading, after which data can flow as with the usual
+anonymous pipe in shells or elsewhere.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -m @var{mode}
+@itemx --mode=@var{mode}
+@opindex -m
+@opindex --mode
+@cindex modes of created FIFOs, setting
+Set the mode of created FIFOs to @var{mode}, which is symbolic as in
+@command{chmod} and uses @samp{a=rw} (read and write allowed for everyone)
+for the point of departure.  @var{mode} should specify only file
+permission bits.  @xref{File permissions}.
+
+@optContext
+
+@end table
+
+@exitstatus
+
+
+@node mknod invocation
+@section @command{mknod}: Make block or character special files
+
+@pindex mknod
+@cindex block special files, creating
+@cindex character special files, creating
+
+@command{mknod} creates a FIFO, character special file, or block special
+file with the specified name.  Synopsis:
+
+@example
+mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}]
+@end example
+
+@cindex special files
+@cindex block special files
+@cindex character special files
+Unlike the phrase ``special file type'' above, the term @dfn{special
+file} has a technical meaning on Unix: something that can generate or
+receive data.  Usually this corresponds to a physical piece of hardware,
+e.g., a printer or a flash drive.  (These files are typically created at
+system-configuration time.)  The @command{mknod} command is what creates
+files of this type.  Such devices can be read either a character at a
+time or a ``block'' (many characters) at a time, hence we say there are
+@dfn{block special} files and @dfn{character special} files.
+
+@c mknod is a shell built-in at least with OpenBSD's /bin/sh
+@mayConflictWithShellBuiltIn{mknod}
+
+The arguments after @var{name} specify the type of file to make:
+
+@table @samp
+
+@item p
+@opindex p @r{for FIFO file}
+for a FIFO
+
+@item b
+@opindex b @r{for block special file}
+for a block special file
+
+@item c
+@c Don't document the 'u' option -- it's just a synonym for 'c'.
+@c Do *any* versions of mknod still use it?
+@c @itemx u
+@opindex c @r{for character special file}
+@c @opindex u @r{for character special file}
+for a character special file
+
+@end table
+
+When making a block or character special file, the major and minor
+device numbers must be given after the file type.
+If a major or minor device number begins with @samp{0x} or @samp{0X},
+it is interpreted as hexadecimal; otherwise, if it begins with @samp{0},
+as octal; otherwise, as decimal.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -m @var{mode}
+@itemx --mode=@var{mode}
+@opindex -m
+@opindex --mode
+Set the mode of created files to @var{mode}, which is symbolic as in
+@command{chmod} and uses @samp{a=rw} as the point of departure.
+@var{mode} should specify only file permission bits.
+@xref{File permissions}.
+
+@optContext
+
+@end table
+
+@exitstatus
+
+
+@node readlink invocation
+@section @command{readlink}: Print value of a symlink or canonical file name
+
+@pindex readlink
+@cindex displaying value of a symbolic link
+@cindex canonical file name
+@cindex canonicalize a file name
+@cindex realpath
+
+@command{readlink} may work in one of two supported modes:
+
+@table @samp
+
+@item Readlink mode
+
+@command{readlink} outputs the value of the given symbolic links.
+If @command{readlink} is invoked with an argument other than the name
+of a symbolic link, it produces no output and exits with a nonzero exit code.
+
+@item Canonicalize mode
+
+@command{readlink} outputs the absolute name of the given files which contain
+no @file{.}, @file{..} components nor any repeated separators
+(@file{/}) or symbolic links.  Note the @command{realpath} command is the
+preferred command to use for canonicalization.  @xref{realpath invocation}.
+
+@end table
+
+@example
+readlink [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+By default, @command{readlink} operates in readlink mode.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -f
+@itemx --canonicalize
+@opindex -f
+@opindex --canonicalize
+Activate canonicalize mode.
+If any component of the file name except the last one is missing or unavailable,
+@command{readlink} produces no output and exits with a nonzero exit
+code.  A trailing slash is ignored.
+
+@item -e
+@itemx --canonicalize-existing
+@opindex -e
+@opindex --canonicalize-existing
+Activate canonicalize mode.
+If any component is missing or unavailable, @command{readlink} produces
+no output and exits with a nonzero exit code.  A trailing slash
+requires that the name resolve to a directory.
+
+@item -m
+@itemx --canonicalize-missing
+@opindex -m
+@opindex --canonicalize-missing
+Activate canonicalize mode.
+If any component is missing or unavailable, @command{readlink} treats it
+as a directory.
+
+@item -n
+@itemx --no-newline
+@opindex -n
+@opindex --no-newline
+Do not print the output delimiter, when a single @var{file} is specified.
+Print a warning if specified along with multiple @var{file}s.
+
+@item -s
+@itemx -q
+@itemx --silent
+@itemx --quiet
+@opindex -s
+@opindex -q
+@opindex --silent
+@opindex --quiet
+Suppress most error messages.  On by default.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Report error messages.
+
+@optZero
+
+@end table
+
+The @command{readlink} utility first appeared in OpenBSD 2.1.
+
+The @command{realpath} command without options, operates like
+@command{readlink} in canonicalize mode.
+
+@exitstatus
+
+
+@node rmdir invocation
+@section @command{rmdir}: Remove empty directories
+
+@pindex rmdir
+@cindex removing empty directories
+@cindex directories, removing empty
+
+@command{rmdir} removes empty directories.  Synopsis:
+
+@example
+rmdir [@var{option}]@dots{} @var{directory}@dots{}
+@end example
+
+If any @var{directory} argument does not refer to an existing empty
+directory, it is an error.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item --ignore-fail-on-non-empty
+@opindex --ignore-fail-on-non-empty
+@cindex directory deletion, ignoring failures
+Ignore each failure to remove a directory that is non-empty.
+
+@item -p
+@itemx --parents
+@opindex -p
+@opindex --parents
+@cindex parent directories, removing
+Remove @var{directory}, then try to remove each component of @var{directory}.
+So, for example, @samp{rmdir -p a/b/c} is similar to @samp{rmdir a/b/c a/b a}.
+As such, it fails if any of those directories turns out not to be empty.
+Use the @option{--ignore-fail-on-non-empty} option to make it so such
+a failure does not evoke a diagnostic and does not cause @command{rmdir} to
+exit unsuccessfully.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+@cindex directory deletion, reporting
+Give a diagnostic for each successful removal.
+@var{directory} is removed.
+
+@end table
+
+@xref{rm invocation}, for how to remove non-empty directories recursively.
+
+To remove all empty directories under @var{dirname}, including
+directories that become empty because other directories are removed,
+you can use either of the following commands:
+
+@example
+# This uses GNU extensions.
+find @var{dirname} -type d -empty -delete
+
+# This runs on any POSIX platform.
+find @var{dirname} -depth -type d -exec rmdir @{@} +
+@end example
+
+@exitstatus
+
+
+@node unlink invocation
+@section @command{unlink}: Remove files via the unlink syscall
+
+@pindex unlink
+@cindex removing files or directories (via the unlink syscall)
+
+@command{unlink} deletes a single specified file name.
+It is a minimalist interface to the system-provided
+@code{unlink} function.  @xref{Deleting Files, , , libc,
+The GNU C Library Reference Manual}.  Synopsis:
+It avoids the bells and whistles of the more commonly-used
+@command{rm} command (@pxref{rm invocation}).
+
+@example
+unlink @var{filename}
+@end example
+
+On some systems @code{unlink} can be used to delete the name of a
+directory.  On others, it can be used that way only by a privileged user.
+In the GNU system @code{unlink} can never delete the name of a directory.
+
+The @command{unlink} command honors the @option{--help} and
+@option{--version} options.  To remove a file whose name begins with
+@samp{-}, prefix the name with @samp{./}, e.g., @samp{unlink ./--help}.
+
+@exitstatus
+
+
+@node Changing file attributes
+@chapter Changing file attributes
+
+@cindex changing file attributes
+@cindex file attributes, changing
+@cindex attributes, file
+
+A file is not merely its contents, a name, and a file type
+(@pxref{Special file types}).  A file also has an owner (a user ID), a
+group (a group ID), permissions (what the owner can do with the file,
+what people in the group can do, and what everyone else can do), various
+timestamps, and other information.  Collectively, we call these a file's
+@dfn{attributes}.
+
+These commands change file attributes.
+
+@menu
+* chown invocation::            Change file owners and groups.
+* chgrp invocation::            Change file groups.
+* chmod invocation::            Change access permissions.
+* touch invocation::            Change file timestamps.
+@end menu
+
+
+@node chown invocation
+@section @command{chown}: Change file owner and group
+
+@pindex chown
+@cindex file ownership, changing
+@cindex group ownership, changing
+@cindex changing file ownership
+@cindex changing group ownership
+
+@command{chown} changes the user and/or group ownership of each given @var{file}
+to @var{new-owner} or to the user and group of an existing reference file.
+Synopsis:
+
+@example
+chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
+@end example
+
+If used, @var{new-owner} specifies the new owner and/or group as follows
+(with no embedded white space):
+
+@example
+[@var{owner}] [ : [@var{group}] ]
+@end example
+
+Specifically:
+
+@table @var
+@item owner
+If only an @var{owner} (a user name or numeric user ID) is given, that
+user is made the owner of each given file, and the files' group is not
+changed.
+
+@item owner@samp{:}group
+If the @var{owner} is followed by a colon and a @var{group} (a
+group name or numeric group ID), with no spaces between them, the group
+ownership of the files is changed as well (to @var{group}).
+
+@item owner@samp{:}
+If a colon but no group name follows @var{owner}, that user is
+made the owner of the files and the group of the files is changed to
+@var{owner}'s login group.
+
+@item @samp{:}group
+If the colon and following @var{group} are given, but the owner
+is omitted, only the group of the files is changed; in this case,
+@command{chown} performs the same function as @command{chgrp}.
+
+@item @samp{:}
+If only a colon is given, or if @var{new-owner} is empty, neither the
+owner nor the group is changed.
+
+@end table
+
+If @var{owner} or @var{group} is intended to represent a numeric user
+or group ID, then you may specify it with a leading @samp{+}.
+@xref{Disambiguating names and IDs}.
+
+Some older scripts may still use @samp{.} in place of the @samp{:} separator.
+POSIX 1003.1-2001 (@pxref{Standards conformance}) does not
+require support for that, but for backward compatibility GNU
+@command{chown} supports @samp{.} so long as no ambiguity results,
+although it issues a warning and support may be removed in future versions.
+New scripts should avoid the use of @samp{.} because it is not
+portable, and because it has undesirable results if the entire
+@var{owner@samp{.}group} happens to identify a user whose name
+contains @samp{.}.
+
+@macro chownGroupRestrictions
+It is system dependent whether a user can change the group to an arbitrary one,
+or the more portable behavior of being restricted to setting a group of
+which the user is a member.
+@end macro
+@chownGroupRestrictions
+
+The @command{chown} command sometimes clears the set-user-ID or
+set-group-ID permission bits.  This behavior depends on the policy and
+functionality of the underlying @code{chown} system call, which may
+make system-dependent file mode modifications outside the control of
+the @command{chown} command.  For example, the @command{chown} command
+might not affect those bits when invoked by a user with appropriate
+privileges, or when the
+bits signify some function other than executable permission (e.g.,
+mandatory locking).
+When in doubt, check the underlying system behavior.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c
+@itemx --changes
+@opindex -c
+@opindex --changes
+@cindex changed owners, verbosely describing
+Verbosely describe the action for each @var{file} whose ownership
+actually changes.
+
+@item -f
+@itemx --silent
+@itemx --quiet
+@opindex -f
+@opindex --silent
+@opindex --quiet
+@cindex error messages, omitting
+Do not print error messages about files whose ownership cannot be
+changed.
+
+@item --from=@var{old-owner}
+@opindex --from
+@cindex symbolic links, changing owner
+Change a @var{file}'s ownership only if it has current attributes specified
+by @var{old-owner}.  @var{old-owner} has the same form as @var{new-owner}
+described above.
+This option is useful primarily from a security standpoint in that
+it narrows considerably the window of potential abuse.
+For example, to reflect a user ID numbering change for one user's files
+without an option like this, @code{root} might run
+
+@example
+find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER
+@end example
+
+But that is dangerous because the interval between when the @command{find}
+tests the existing file's owner and when the @command{chown} is actually run
+may be quite large.
+One way to narrow the gap would be to invoke chown for each file
+as it is found:
+
+@example
+find / -owner OLDUSER -exec chown -h NEWUSER @{@} \;
+@end example
+
+But that is very slow if there are many affected files.
+With this option, it is safer (the gap is narrower still)
+though still not perfect:
+
+@example
+chown -h -R --from=OLDUSER NEWUSER /
+@end example
+
+@item --dereference
+@opindex --dereference
+@cindex symbolic links, changing owner
+@findex lchown
+Do not act on symbolic links themselves but rather on what they point to.
+This is the default when not operating recursively.
+@warnOptDerefWithRec
+
+@item -h
+@itemx --no-dereference
+@opindex -h
+@opindex --no-dereference
+@cindex symbolic links, changing owner
+@findex lchown
+Act on symbolic links themselves instead of what they point to.
+This mode relies on the @code{lchown} system call.
+On systems that do not provide the @code{lchown} system call,
+@command{chown} fails when a file specified on the command line
+is a symbolic link.
+By default, no diagnostic is issued for symbolic links encountered
+during a recursive traversal, but see @option{--verbose}.
+
+@item --preserve-root
+@opindex --preserve-root
+@cindex root directory, disallow recursive modification
+Fail upon any attempt to recursively change the root directory, @file{/}.
+Without @option{--recursive}, this option has no effect.
+@xref{Treating / specially}.
+
+@item --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive modification
+Cancel the effect of any preceding @option{--preserve-root} option.
+@xref{Treating / specially}.
+
+@item --reference=@var{ref_file}
+@opindex --reference
+Change the user and group of each @var{file} to be the same as those of
+@var{ref_file}.  If @var{ref_file} is a symbolic link, do not use the
+user and group of the symbolic link, but rather those of the file it
+refers to.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Output a diagnostic for every file processed.
+If a symbolic link is encountered during a recursive traversal
+on a system without the @code{lchown} system call, and @option{--no-dereference}
+is in effect, then issue a diagnostic saying neither the symbolic link nor
+its referent is being changed.
+
+@item -R
+@itemx --recursive
+@opindex -R
+@opindex --recursive
+@cindex recursively changing file ownership
+Recursively change ownership of directories and their contents.
+
+@choptH
+@xref{Traversing symlinks}.
+
+@choptL
+@warnOptDerefWithRec
+@xref{Traversing symlinks}.
+
+@choptP
+@xref{Traversing symlinks}.
+
+@end table
+
+@exitstatus
+
+Examples:
+
+@example
+# Change the owner of /u to "root".
+chown root /u
+
+# Likewise, but also change its group to "staff".
+chown root:staff /u
+
+# Change the owner of /u and subfiles to "root".
+chown -hR root /u
+@end example
+
+
+@node chgrp invocation
+@section @command{chgrp}: Change group ownership
+
+@pindex chgrp
+@cindex group ownership, changing
+@cindex changing group ownership
+
+@command{chgrp} changes the group ownership of each given @var{file}
+to @var{group} (which can be either a group name or a numeric group ID)
+or to the group of an existing reference file.  @xref{chown invocation}.
+Synopsis:
+
+@example
+chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
+@end example
+
+If @var{group} is intended to represent a
+numeric group ID, then you may specify it with a leading @samp{+}.
+@xref{Disambiguating names and IDs}.
+
+@chownGroupRestrictions
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c
+@itemx --changes
+@opindex -c
+@opindex --changes
+@cindex changed files, verbosely describing
+Verbosely describe the action for each @var{file} whose group actually
+changes.
+
+@item -f
+@itemx --silent
+@itemx --quiet
+@opindex -f
+@opindex --silent
+@opindex --quiet
+@cindex error messages, omitting
+Do not print error messages about files whose group cannot be
+changed.
+
+@item --dereference
+@opindex --dereference
+@cindex symbolic links, changing owner
+@findex lchown
+Do not act on symbolic links themselves but rather on what they point to.
+This is the default when not operating recursively.
+@warnOptDerefWithRec
+
+@item -h
+@itemx --no-dereference
+@opindex -h
+@opindex --no-dereference
+@cindex symbolic links, changing group
+@findex lchown
+Act on symbolic links themselves instead of what they point to.
+This mode relies on the @code{lchown} system call.
+On systems that do not provide the @code{lchown} system call,
+@command{chgrp} fails when a file specified on the command line
+is a symbolic link.
+By default, no diagnostic is issued for symbolic links encountered
+during a recursive traversal, but see @option{--verbose}.
+
+@item --preserve-root
+@opindex --preserve-root
+@cindex root directory, disallow recursive modification
+Fail upon any attempt to recursively change the root directory, @file{/}.
+Without @option{--recursive}, this option has no effect.
+@xref{Treating / specially}.
+
+@item --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive modification
+Cancel the effect of any preceding @option{--preserve-root} option.
+@xref{Treating / specially}.
+
+@item --reference=@var{ref_file}
+@opindex --reference
+Change the group of each @var{file} to be the same as that of
+@var{ref_file}.  If @var{ref_file} is a symbolic link, do not use the
+group of the symbolic link, but rather that of the file it refers to.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Output a diagnostic for every file processed.
+If a symbolic link is encountered during a recursive traversal
+on a system without the @code{lchown} system call, and @option{--no-dereference}
+is in effect, then issue a diagnostic saying neither the symbolic link nor
+its referent is being changed.
+
+@item -R
+@itemx --recursive
+@opindex -R
+@opindex --recursive
+@cindex recursively changing group ownership
+Recursively change the group ownership of directories and their contents.
+
+@choptH
+@xref{Traversing symlinks}.
+
+@choptL
+@warnOptDerefWithRec
+@xref{Traversing symlinks}.
+
+@choptP
+@xref{Traversing symlinks}.
+
+@end table
+
+@exitstatus
+
+Examples:
+
+@example
+# Change the group of /u to "staff".
+chgrp staff /u
+
+# Change the group of /u and subfiles to "staff".
+chgrp -hR staff /u
+@end example
+
+
+@node chmod invocation
+@section @command{chmod}: Change access permissions
+
+@pindex chmod
+@cindex changing access permissions
+@cindex access permissions, changing
+@cindex permissions, changing access
+
+@command{chmod} changes the access permissions of the named files.  Synopsis:
+
+@example
+chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@}@c
+ @var{file}@dots{}
+@end example
+
+@cindex symbolic links, permissions of
+@command{chmod} never changes the permissions of symbolic links, since
+the @command{chmod} system call cannot change their permissions.
+This is not a problem since the permissions of symbolic links are
+never used.  However, for each symbolic link listed on the command
+line, @command{chmod} changes the permissions of the pointed-to file.
+In contrast, @command{chmod} ignores symbolic links encountered during
+recursive directory traversals.
+
+Only a process whose effective user ID matches the user ID of the file,
+or a process with appropriate privileges, is permitted to change the
+file mode bits of a file.
+
+A successful use of @command{chmod} clears the set-group-ID bit of a
+regular file if the file's group ID does not match the user's
+effective group ID or one of the user's supplementary group IDs,
+unless the user has appropriate privileges.  Additional restrictions
+may cause the set-user-ID and set-group-ID bits of @var{mode} or
+@var{ref_file} to be ignored.  This behavior depends on the policy and
+functionality of the underlying @code{chmod} system call.  When in
+doubt, check the underlying system behavior.
+
+If used, @var{mode} specifies the new file mode bits.
+For details, see the section on @ref{File permissions}.
+If you really want @var{mode} to have a leading @samp{-}, you should
+use @option{--} first, e.g., @samp{chmod -- -w file}.  Typically,
+though, @samp{chmod a-w file} is preferable, and @command{chmod -w
+file} (without the @option{--}) complains if it behaves differently
+from what @samp{chmod a-w file} would do.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c
+@itemx --changes
+@opindex -c
+@opindex --changes
+Verbosely describe the action for each @var{file} whose permissions
+actually change.
+
+@item -f
+@itemx --silent
+@itemx --quiet
+@opindex -f
+@opindex --silent
+@opindex --quiet
+@cindex error messages, omitting
+Do not print error messages about files whose permissions cannot be
+changed.
+
+@item --preserve-root
+@opindex --preserve-root
+@cindex root directory, disallow recursive modification
+Fail upon any attempt to recursively change the root directory, @file{/}.
+Without @option{--recursive}, this option has no effect.
+@xref{Treating / specially}.
+
+@item --no-preserve-root
+@opindex --no-preserve-root
+@cindex root directory, allow recursive modification
+Cancel the effect of any preceding @option{--preserve-root} option.
+@xref{Treating / specially}.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Verbosely describe the action or non-action taken for every @var{file}.
+
+@item --reference=@var{ref_file}
+@opindex --reference
+Change the mode of each @var{file} to be the same as that of @var{ref_file}.
+@xref{File permissions}.
+If @var{ref_file} is a symbolic link, do not use the mode
+of the symbolic link, but rather that of the file it refers to.
+
+@item -R
+@itemx --recursive
+@opindex -R
+@opindex --recursive
+@cindex recursively changing access permissions
+Recursively change permissions of directories and their contents.
+
+@end table
+
+@exitstatus
+
+Examples:
+
+@smallexample
+# Change file permissions of FOO to be world readable
+# and user writable, with no other permissions.
+chmod 644 foo
+chmod a=r,u+w foo
+
+# Add user and group execute permissions to FOO.
+chmod +110 file
+chmod ug+x file
+
+# Set file permissions of DIR and subsidiary files to
+# be the umask default, assuming execute permissions for
+# directories and for files already executable.
+chmod -R a=,+rwX dir
+@end smallexample
+
+
+@node touch invocation
+@section @command{touch}: Change file timestamps
+
+@pindex touch
+@cindex changing file timestamps
+@cindex file timestamps, changing
+@cindex timestamps, changing file
+
+@command{touch} changes the access and/or modification timestamps of the
+specified files.  Synopsis:
+
+@example
+touch [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+@cindex empty files, creating
+Any @var{file} argument that does not exist is created empty, unless
+option @option{--no-create} (@option{-c}) or @option{--no-dereference}
+(@option{-h}) was in effect.
+
+A @var{file} argument string of @samp{-} is handled specially and
+causes @command{touch} to change the times of the file associated with
+standard output.
+
+By default, @command{touch} sets file timestamps to the current time.
+Because @command{touch} acts on its operands left to right, the
+resulting timestamps of earlier and later operands may disagree.
+
+@cindex permissions, for changing file timestamps
+When setting file timestamps to the current time, @command{touch} can
+change the timestamps for files that the user does not own but has
+write permission for.  Otherwise, the user must own the files.  Some
+older systems have a further restriction: the user must own the files
+unless both the access and modification timestamps are being set to the
+current time.
+
+The @command{touch} command cannot set a file's status change timestamp to
+a user-specified value, and cannot change the file's birth time (if
+supported) at all.  Also, @command{touch} has issues similar to those
+affecting all programs that update file timestamps.  For example,
+@command{touch} may set a file's timestamp to a value that differs
+slightly from the requested time.  @xref{File timestamps}.
+
+@vindex TZ
+Timestamps assume the time zone rules specified by the @env{TZ}
+environment variable, or by the system default rules if @env{TZ} is
+not set.  @xref{TZ Variable,, Specifying the Time Zone with @env{TZ},
+libc, The GNU C Library Reference Manual}.
+You can avoid ambiguities during
+daylight saving transitions by using UTC timestamps.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -a
+@itemx --time=atime
+@itemx --time=access
+@itemx --time=use
+@opindex -a
+@opindex --time
+@opindex atime@r{, changing}
+@opindex access @r{time, changing}
+@opindex use @r{time, changing}
+Change the access timestamp only.  @xref{File timestamps}.
+
+@item -c
+@itemx --no-create
+@opindex -c
+@opindex --no-create
+Do not warn about or create files that do not exist.
+
+@item -d @var{time}
+@itemx --date=@var{time}
+@opindex -d
+@opindex --date
+@opindex time
+Use @var{time} instead of the current time.  It can contain month names,
+time zones, @samp{am} and @samp{pm}, @samp{yesterday}, etc.  For
+example, @option{--date="2020-07-21 14:19:13.489392193 +0530"}
+specifies the instant of time that is 489,392,193 nanoseconds after
+July 21, 2020 at 2:19:13 PM in a time zone that is 5 hours and 30
+minutes east of UTC@.  @xref{Date input formats}.
+File systems that do not support high-resolution timestamps
+silently ignore any excess precision here.
+
+@item -f
+@opindex -f
+@cindex BSD @command{touch} compatibility
+Ignored; for compatibility with BSD versions of @command{touch}.
+
+@item -h
+@itemx --no-dereference
+@opindex -h
+@opindex --no-dereference
+@cindex symbolic links, changing time
+@findex lutimes
+Attempt to change the timestamps of a symbolic link, rather than what
+the link refers to.  When using this option, empty files are not
+created, but option @option{-c} must also be used to avoid warning
+about files that do not exist.  Not all systems support changing the
+timestamps of symlinks, since underlying system support for this
+action was not required until POSIX 2008.  Also, on some
+systems, the mere act of examining a symbolic link changes the access
+timestamp, such that only changes to the modification timestamp will persist
+long enough to be observable.  When coupled with option @option{-r}, a
+reference timestamp is taken from a symbolic link rather than the file
+it refers to.
+
+@item -m
+@itemx --time=mtime
+@itemx --time=modify
+@opindex -m
+@opindex --time
+@opindex mtime@r{, changing}
+@opindex modify @r{time, changing}
+Change the modification timestamp only.
+
+@item -r @var{file}
+@itemx --reference=@var{file}
+@opindex -r
+@opindex --reference
+Use the times of the reference @var{file} instead of the current time.
+If this option is combined with the @option{--date=@var{time}}
+(@option{-d @var{time}}) option, the reference @var{file}'s time is
+the origin for any relative @var{time}s given, but is otherwise ignored.
+For example, @samp{-r foo -d '-5 seconds'} specifies a timestamp
+equal to five seconds before the corresponding timestamp for @file{foo}.
+If @var{file} is a symbolic link, the reference timestamp is taken
+from the target of the symlink, unless @option{-h} was also in effect.
+
+@item -t [[@var{cc}]@var{yy}]@var{mmddhhmm}[.@var{ss}]
+@cindex leap seconds
+Use the argument (optional four-digit or two-digit years, months,
+days, hours, minutes, optional seconds) instead of the current time.
+If the year is specified with only two digits, then @var{cc}
+is 20 for years in the range 0 @dots{} 68, and 19 for years in
+69 @dots{} 99.  If no digits of the year are specified,
+the argument is interpreted as a date in the current year.
+On the atypical systems that support leap seconds, @var{ss} may be
+@samp{60}.
+
+@end table
+
+@vindex _POSIX2_VERSION
+On systems predating POSIX 1003.1-2001,
+@command{touch} supports an obsolete syntax, as follows.
+If no timestamp is given with any of the @option{-d}, @option{-r}, or
+@option{-t} options, and if there are two or more @var{file}s and the
+first @var{file} is of the form @samp{@var{mmddhhmm}[@var{yy}]} and this
+would be a valid argument to the @option{-t} option (if the @var{yy}, if
+any, were moved to the front), and if the represented year
+is in the range 1969--1999, that argument is interpreted as the time
+for the other files instead of as a file name.
+Although this obsolete behavior can be controlled with the
+@env{_POSIX2_VERSION} environment variable (@pxref{Standards
+conformance}), portable scripts should avoid commands whose
+behavior depends on this variable.
+For example, use @samp{touch ./12312359 main.c} or @samp{touch -t
+12312359 main.c} rather than the ambiguous @samp{touch 12312359 main.c}.
+
+@exitstatus
+
+
+@node File space usage
+@chapter File space usage
+
+@cindex File space usage
+@cindex disk usage
+
+No file system can hold an infinite amount of data.  These commands report
+how much storage is in use or available, report other file and
+file status information, and write buffers to file systems.
+
+@menu
+* df invocation::               Report file system space usage.
+* du invocation::               Estimate file space usage.
+* stat invocation::             Report file or file system status.
+* sync invocation::             Synchronize cached writes to persistent storage.
+* truncate invocation::         Shrink or extend the size of a file.
+@end menu
+
+
+@node df invocation
+@section @command{df}: Report file system space usage
+
+@pindex df
+@cindex file system usage
+@cindex disk usage by file system
+
+@command{df} reports the amount of space used and available on
+file systems.  Synopsis:
+
+@example
+df [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+With no arguments, @command{df} reports the space used and available on all
+currently mounted file systems (of all types).  Otherwise, @command{df}
+reports on the file system containing each argument @var{file}.
+
+Normally the space is printed in units of
+1024 bytes, but this can be overridden (@pxref{Block size}).
+Non-integer quantities are rounded up to the next higher unit.
+
+For bind mounts and without arguments, @command{df} only outputs the statistics
+for that device with the shortest mount point name in the list of file systems
+(@var{mtab}), i.e., it hides duplicate entries, unless the @option{-a} option is
+specified.
+
+With the same logic, @command{df} elides a mount entry of a dummy pseudo device
+if there is another mount entry of a real block device for that mount point with
+the same device number, e.g. the early-boot pseudo file system @samp{rootfs} is
+not shown per default when already the real root device has been mounted.
+
+@cindex disk device file
+@cindex device file
+If an argument @var{file} resolves to a special file containing
+a mounted file system, @command{df} shows the space available on that
+file system rather than on the file system containing the device node.
+GNU @command{df} does not attempt to determine the usage
+on unmounted file systems, because on most kinds of systems doing so
+requires extremely non-portable intimate knowledge of file system structures.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -a
+@itemx --all
+@opindex -a
+@opindex --all
+@cindex ignore file systems
+Include in the listing dummy, duplicate, or inaccessible file systems, which
+are omitted by default.  Dummy file systems are typically special purpose
+pseudo file systems such as @samp{/proc}, with no associated storage.
+Duplicate file systems are local or remote file systems that are mounted
+at separate locations in the local file hierarchy, or bind mounted locations.
+Inaccessible file systems are those which are mounted but subsequently
+over-mounted by another file system at that point, or otherwise inaccessible
+due to permissions of the mount point etc.
+
+@item -B @var{size}
+@itemx --block-size=@var{size}
+@opindex -B
+@opindex --block-size
+@cindex file system sizes
+Scale sizes by @var{size} before printing them (@pxref{Block size}).
+For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
+
+@optHumanReadable
+
+@item -H
+@opindex -H
+Equivalent to @option{--si}.
+
+@item -i
+@itemx --inodes
+@opindex -i
+@opindex --inodes
+@cindex inode usage
+List inode usage information instead of block usage.  An inode (short
+for index node) contains information about a file such as its owner,
+permissions, timestamps, and location on the file system.
+
+@item -k
+@opindex -k
+@cindex kibibytes for file system sizes
+Print sizes in 1024-byte blocks, overriding the default block size
+(@pxref{Block size}).
+This option is equivalent to @option{--block-size=1K}.
+
+@item -l
+@itemx --local
+@opindex -l
+@opindex --local
+@cindex file system types, limiting output to certain
+Limit the listing to local file systems.  By default, remote file systems
+are also listed.
+
+@item --no-sync
+@opindex --no-sync
+@cindex file system space, retrieving old data more quickly
+Do not invoke the @code{sync} system call before getting any usage data.
+This may make @command{df} run significantly faster on systems with many
+file systems, but on some systems (notably Solaris) the results may be slightly
+out of date.  This is the default.
+
+@item --output
+@itemx --output[=@var{field_list}]
+@opindex --output
+Use the output format defined by @var{field_list}, or print all fields if
+@var{field_list} is omitted.  In the latter case, the order of the columns
+conforms to the order of the field descriptions below.
+
+The use of the @option{--output} together with each of the options @option{-i},
+@option{-P}, and @option{-T} is mutually exclusive.
+
+FIELD_LIST is a comma-separated list of columns to be included in @command{df}'s
+output and therefore effectively controls the order of output columns.
+Each field can thus be used at the place of choice, but yet must only be
+used once.
+
+Valid field names in the @var{field_list} are:
+@table @samp
+@item source
+The source of the mount point, usually a device.
+@item fstype
+File system type.
+
+@item itotal
+Total number of inodes.
+@item iused
+Number of used inodes.
+@item iavail
+Number of available inodes.
+@item ipcent
+Percentage of @var{iused} divided by @var{itotal}.
+
+@item size
+Total number of blocks.
+@item used
+Number of used blocks.
+@item avail
+Number of available blocks.
+@item pcent
+Percentage of @var{used} divided by @var{size}.
+
+@item file
+The file name if specified on the command line.
+@item target
+The mount point.
+@end table
+
+The fields for block and inodes statistics are affected by the scaling
+options like @option{-h} as usual.
+
+The definition of the @var{field_list} can even be split among several
+@option{--output} uses.
+
+@example
+#!/bin/sh
+# Print the TARGET (i.e., the mount point) along with their percentage
+# statistic regarding the blocks and the inodes.
+df --out=target --output=pcent,ipcent
+
+# Print all available fields.
+df --o
+@end example
+
+
+@item -P
+@itemx --portability
+@opindex -P
+@opindex --portability
+@cindex one-line output format
+@cindex POSIX output format
+@cindex portable output format
+@cindex output format, portable
+Use the POSIX output format.  This is like the default format except
+for the following:
+
+@enumerate
+@item
+The information about each file system is always printed on exactly
+one line; a mount device is never put on a line by itself.  This means
+that if the mount device name is more than 20 characters long (e.g., for
+some network mounts), the columns are misaligned.
+
+@item
+The labels in the header output line are changed to conform to POSIX.
+
+@item
+The default block size and output format are unaffected by the
+@env{DF_BLOCK_SIZE}, @env{BLOCK_SIZE} and @env{BLOCKSIZE} environment
+variables.  However, the default block size is still affected by
+@env{POSIXLY_CORRECT}: it is 512 if @env{POSIXLY_CORRECT} is set, 1024
+otherwise.  @xref{Block size}.
+@end enumerate
+
+@optSi
+
+@item --sync
+@opindex --sync
+@cindex file system space, retrieving current data more slowly
+Invoke the @code{sync} system call before getting any usage data.  On
+some systems (notably Solaris), doing this yields more up to date results,
+but in general this option makes @command{df} much slower, especially when
+there are many or very busy file systems.
+
+@item --total
+@opindex --total
+@cindex grand total of file system size, usage and available space
+Print a grand total of all arguments after all arguments have
+been processed.  This can be used to find out the total size, usage
+and available space of all listed devices.  If no arguments are specified
+df will try harder to elide file systems insignificant to the total
+available space, by suppressing duplicate remote file systems.
+
+For the grand total line, @command{df} prints @samp{"total"} into the
+@var{source} column, and @samp{"-"} into the @var{target} column.
+If there is no @var{source} column (see @option{--output}), then
+@command{df} prints @samp{"total"} into the @var{target} column,
+if present.
+
+@item -t @var{fstype}
+@itemx --type=@var{fstype}
+@opindex -t
+@opindex --type
+@cindex file system types, limiting output to certain
+Limit the listing to file systems of type @var{fstype}.  Multiple
+file system types can be specified by giving multiple @option{-t} options.
+By default, nothing is omitted.
+
+@item -T
+@itemx --print-type
+@opindex -T
+@opindex --print-type
+@cindex file system types, printing
+Print each file system's type.  The types printed here are the same ones
+you can include or exclude with @option{-t} and @option{-x}.  The particular
+types printed are whatever is supported by the system.  Here are some of
+the common names (this list is certainly not exhaustive):
+
+@table @samp
+
+@item nfs
+@cindex NFS file system type
+An NFS file system, i.e., one mounted over a network from another
+machine.  This is the one type name which seems to be used uniformly by
+all systems.
+
+@item ext2@r{, }ext3@r{, }ext4@r{, }xfs@r{, }btrfs@dots{}
+@cindex Linux file system types
+@cindex local file system types
+@opindex ext2 @r{file system type}
+@opindex ext3 @r{file system type}
+@opindex ext4 @r{file system type}
+@opindex xfs @r{file system type}
+@opindex btrfs @r{file system type}
+A file system on a locally-mounted device.  (The system might even
+support more than one type here; GNU/Linux does.)
+
+@item iso9660@r{, }cdfs
+@cindex CD-ROM file system type
+@cindex DVD file system type
+@cindex ISO9660 file system type
+@opindex iso9660 @r{file system type}
+@opindex cdfs @r{file system type}
+A file system on a CD or DVD drive.  HP-UX uses @samp{cdfs}, most other
+systems use @samp{iso9660}.
+
+@item ntfs@r{,}fat
+@cindex NTFS file system
+@cindex DOS file system
+@cindex MS-DOS file system
+@cindex MS-Windows file system
+@opindex ntfs @r{file system file}
+@opindex fat @r{file system file}
+File systems used by MS-Windows / MS-DOS.
+
+@end table
+
+@item -x @var{fstype}
+@itemx --exclude-type=@var{fstype}
+@opindex -x
+@opindex --exclude-type
+Limit the listing to file systems not of type @var{fstype}.
+Multiple file system types can be eliminated by giving multiple
+@option{-x} options.  By default, no file system types are omitted.
+
+@item -v
+Ignored; for compatibility with System V versions of @command{df}.
+
+@end table
+
+@command{df} is installed only on systems that have usable mount tables,
+so portable scripts should not rely on its existence.
+
+@exitstatus
+Failure includes the case where no output is generated, so you can
+inspect the exit status of a command like @samp{df -t ext3 -t reiserfs
+@var{dir}} to test whether @var{dir} is on a file system of type
+@samp{ext3} or @samp{reiserfs}.
+
+Since the list of file systems (@var{mtab}) is needed to determine the
+file system type, failure includes the cases when that list cannot
+be read and one or more of the options @option{-a}, @option{-l}, @option{-t}
+or @option{-x} is used together with a file name argument.
+
+
+@node du invocation
+@section @command{du}: Estimate file space usage
+
+@pindex du
+@cindex file space usage
+@cindex disk usage for files
+
+@command{du} reports the space needed to represent a set of files.
+Synopsis:
+
+@example
+du [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+With no arguments, @command{du} reports the space needed to represent
+the files at or under the current directory.
+Normally the space is printed in units of
+1024 bytes, but this can be overridden (@pxref{Block size}).
+Non-integer quantities are rounded up to the next higher unit.
+
+If two or more hard links point to the same file, only one of the hard
+links is counted.  The @var{file} argument order affects which links
+are counted, and changing the argument order may change the numbers
+and entries that @command{du} outputs.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@optNull
+
+@item -a
+@itemx --all
+@opindex -a
+@opindex --all
+Show counts for all files, not just directories.
+
+@item --apparent-size
+@opindex --apparent-size
+Print apparent sizes, rather than file system usage.  The apparent size of a
+file is the number of bytes reported by @code{wc -c} on regular files,
+or more generally, @code{ls -l --block-size=1} or @code{stat --format=%s}.
+For example, a file containing the word @samp{zoo} with no newline would,
+of course, have an apparent size of 3.  Such a small file may require
+anywhere from 0 to 16 KiB or more of file system space, depending on
+the type and configuration of the file system on which the file resides.
+However, a sparse file created with this command:
+
+@example
+dd bs=1 seek=2GiB if=/dev/null of=big
+@end example
+
+@noindent
+has an apparent size of 2 GiB, yet on most modern
+file systems, it actually uses almost no space.
+
+Apparent sizes are meaningful only for regular files and symbolic links.
+Other file types do not contribute to apparent size.
+
+@item -B @var{size}
+@itemx --block-size=@var{size}
+@opindex -B
+@opindex --block-size
+@cindex file sizes
+Scale sizes by @var{size} before printing them (@pxref{Block size}).
+For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes.
+
+@item -b
+@itemx --bytes
+@opindex -b
+@opindex --bytes
+Equivalent to @code{--apparent-size --block-size=1}.
+
+@item -c
+@itemx --total
+@opindex -c
+@opindex --total
+@cindex grand total of file system space
+Print a grand total of all arguments after all arguments have
+been processed.  This can be used to find out the total file system usage of
+a given set of files or directories.
+
+@item -D
+@itemx --dereference-args
+@opindex -D
+@opindex --dereference-args
+Dereference symbolic links that are command line arguments.
+Does not affect other symbolic links.  This is helpful for finding
+out the file system usage of directories, such as @file{/usr/tmp}, which
+are often symbolic links.
+
+@item -d @var{depth}
+@itemx --max-depth=@var{depth}
+@opindex -d @var{depth}
+@opindex --max-depth=@var{depth}
+@cindex limiting output of @command{du}
+Show the total for each directory (and file if @option{--all}) that is at
+most MAX_DEPTH levels down from the root of the hierarchy.  The root
+is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}.
+
+@c --files0-from=FILE
+@filesZeroFromOption{du,, with the @option{--total} (@option{-c}) option}
+
+@item -H
+@opindex -H
+Equivalent to @option{--dereference-args} (@option{-D}).
+
+@optHumanReadable
+
+@item --inodes
+@opindex --inodes
+@cindex inode usage, dereferencing in @command{du}
+List inode usage information instead of block usage.
+This option is useful for finding directories which contain many files, and
+therefore eat up most of the inodes space of a file system (see @command{df},
+option @option{--inodes}).
+It can well be combined with the options @option{-a}, @option{-c},
+@option{-h}, @option{-l}, @option{-s}, @option{-S}, @option{-t} and
+@option{-x}; however, passing other options regarding the block size, for
+example @option{-b}, @option{-m} and @option{--apparent-size}, is ignored.
+
+@item -k
+@opindex -k
+@cindex kibibytes for file sizes
+Print sizes in 1024-byte blocks, overriding the default block size
+(@pxref{Block size}).
+This option is equivalent to @option{--block-size=1K}.
+
+@item -L
+@itemx --dereference
+@opindex -L
+@opindex --dereference
+@cindex symbolic links, dereferencing in @command{du}
+Dereference symbolic links (show the file system space used by the file
+or directory that the link points to instead of the space used by
+the link).
+
+@item -l
+@itemx --count-links
+@opindex -l
+@opindex --count-links
+@cindex hard links, counting in @command{du}
+Count the size of all files, even if they have appeared already (as a
+hard link).
+
+@item -m
+@opindex -m
+@cindex mebibytes for file sizes
+Print sizes in 1,048,576-byte blocks, overriding the default block size
+(@pxref{Block size}).
+This option is equivalent to @option{--block-size=1M}.
+
+@item -P
+@itemx --no-dereference
+@opindex -P
+@opindex --no-dereference
+@cindex symbolic links, dereferencing in @command{du}
+For each symbolic link encountered by @command{du},
+consider the file system space used by the symbolic link itself.
+
+@item -S
+@itemx --separate-dirs
+@opindex -S
+@opindex --separate-dirs
+Normally, in the output of @command{du} (when not using @option{--summarize}),
+the size listed next to a directory name, @var{d}, represents the sum
+of sizes of all entries beneath @var{d} as well as the size of @var{d} itself.
+With @option{--separate-dirs}, the size reported for a directory name,
+@var{d}, will exclude the size of any subdirectories.
+
+@optSi
+
+@item -s
+@itemx --summarize
+@opindex -s
+@opindex --summarize
+Display only a total for each argument.
+
+@item -t @var{size}
+@itemx --threshold=@var{size}
+@opindex -t
+@opindex --threshold
+Exclude entries based on a given @var{size}.  The @var{size} refers to used
+blocks in normal mode (@pxref{Block size}), or inodes count in conjunction
+with the @option{--inodes} option.
+
+If @var{size} is positive, then @command{du} will only print entries with a size
+greater than or equal to that.
+
+If @var{size} is negative, then @command{du} will only print entries with a size
+smaller than or equal to that.
+
+Although GNU @command{find} can be used to find files of a certain size,
+@command{du}'s @option{--threshold} option can be used to also filter
+directories based on a given size.
+
+When combined with the @option{--apparent-size} option, the
+@option{--threshold} option elides entries based on apparent size.
+When combined with the @option{--inodes} option, it elides entries
+based on inode counts.
+
+Here's how you would use @option{--threshold} to find directories with a size
+greater than or equal to 200 megabytes:
+
+@example
+du --threshold=200MB
+@end example
+
+Here's how you would use @option{--threshold} to find directories and
+files -- note the @option{-a} -- with an apparent size smaller than or
+equal to 500 bytes:
+
+@example
+du -a -t -500 --apparent-size
+@end example
+
+Here's how you would use @option{--threshold} to find directories on the root
+file system with more than 20000 inodes used in the directory tree below:
+
+@example
+du --inodes -x --threshold=20000 /
+@end example
+
+
+@item --time
+@opindex --time
+@cindex last modified dates, displaying in @command{du}
+Show the most recent modification timestamp (mtime) of any file in the
+directory, or any of its subdirectories.  @xref{File timestamps}.
+
+@item --time=ctime
+@itemx --time=status
+@itemx --time=use
+@opindex --time
+@opindex ctime@r{, show the most recent}
+@opindex status time@r{, show the most recent}
+@opindex use time@r{, show the most recent}
+Show the most recent status change timestamp (ctime) of any file in
+the directory, or any of its subdirectories.  @xref{File timestamps}.
+
+@item --time=atime
+@itemx --time=access
+@opindex --time
+@opindex atime@r{, show the most recent}
+@opindex access timestamp@r{, show the most recent}
+Show the most recent access timestamp (atime) of any file in the
+directory, or any of its subdirectories.  @xref{File timestamps}.
+
+@item --time-style=@var{style}
+@opindex --time-style
+@cindex time style
+List timestamps in style @var{style}.  This option has an effect only if
+the @option{--time} option is also specified.  The @var{style} should
+be one of the following:
+
+@table @samp
+@item +@var{format}
+@vindex LC_TIME
+List timestamps using @var{format}, where @var{format} is interpreted
+like the format argument of @command{date} (@pxref{date invocation}).
+For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes
+@command{du} to list timestamps like @samp{2020-07-21 23:45:56}.  As
+with @command{date}, @var{format}'s interpretation is affected by the
+@env{LC_TIME} locale category.
+
+@item full-iso
+List timestamps in full using ISO 8601-like date, time, and time zone
+components with nanosecond precision, e.g., @samp{2020-07-21
+23:45:56.477817180 -0400}.  This style is equivalent to
+@samp{+%Y-%m-%d %H:%M:%S.%N %z}.
+
+@item long-iso
+List ISO 8601 date and time components with minute precision, e.g.,
+@samp{2020-07-21 23:45}.  These timestamps are shorter than
+@samp{full-iso} timestamps, and are usually good enough for everyday
+work.  This style is equivalent to @samp{+%Y-%m-%d %H:%M}.
+
+@item iso
+List ISO 8601 dates for timestamps, e.g., @samp{2020-07-21}.
+This style is equivalent to @samp{+%Y-%m-%d}.
+@end table
+
+@vindex TIME_STYLE
+You can specify the default value of the @option{--time-style} option
+with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set
+the default style is @samp{long-iso}.  For compatibility with @command{ls},
+if @env{TIME_STYLE} begins with @samp{+} and contains a newline,
+the newline and any later characters are ignored; if @env{TIME_STYLE}
+begins with @samp{posix-} the @samp{posix-} is ignored; and if
+@env{TIME_STYLE} is @samp{locale} it is ignored.
+
+@item -X @var{file}
+@itemx --exclude-from=@var{file}
+@opindex -X @var{file}
+@opindex --exclude-from=@var{file}
+@cindex excluding files from @command{du}
+Like @option{--exclude}, except take the patterns to exclude from @var{file},
+one per line.  If @var{file} is @samp{-}, take the patterns from standard
+input.
+
+@item --exclude=@var{pattern}
+@opindex --exclude=@var{pattern}
+@cindex excluding files from @command{du}
+When recursing, skip subdirectories or files matching @var{pattern}.
+For example, @code{du --exclude='*.o'} excludes files whose names
+end in @samp{.o}.
+
+@item -x
+@itemx --one-file-system
+@opindex -x
+@opindex --one-file-system
+@cindex one file system, restricting @command{du} to
+Skip directories that are on different file systems from the one that
+the argument being processed is on.
+
+@end table
+
+Since @command{du} relies on information reported by the operating
+system, its output might not reflect the space consumed in the
+underlying devices.  For example;
+
+@itemize @bullet
+@item
+Operating systems normally do not report device space consumed by
+duplicate or backup blocks, error correction bits, and so forth.
+This causes @command{du} to underestimate the device space actually used.
+
+@item
+@cindex copy-on-write and @command{du}
+In file systems that use copy-on-write, if two distinct files share
+space the output of @command{du} typically counts the space that would
+be consumed if all files' non-holes were rewritten, not the space
+currently consumed.
+
+@item
+@cindex compression and @command{du}
+In file systems that use compression, the operating system might
+report the uncompressed space.  (If it does report the compressed space,
+that report might change after one merely overwrites existing file data.)
+
+@item
+@cindex networked file systems and @command{du}
+Networked file systems historically have had difficulty communicating
+accurate file system information from server to client.
+@end itemize
+
+@noindent
+For these reasons @command{du} might better be thought of as an
+estimate of the size of a @command{tar} or other conventional backup
+for a set of files, rather than as a measure of space consumed in the
+underlying devices.
+
+@exitstatus
+
+
+@node stat invocation
+@section @command{stat}: Report file or file system status
+
+@pindex stat
+@cindex file status
+@cindex file system status
+
+@command{stat} displays information about the specified file(s).  Synopsis:
+
+@example
+stat [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+With no option, @command{stat} reports all information about the given files.
+But it also can be used to report the information of the file systems the
+given files are located on.  If the files are links, @command{stat} can
+also give information about the files the links point to.
+
+@mayConflictWithShellBuiltIn{stat}
+
+@table @samp
+
+@item -L
+@itemx --dereference
+@opindex -L
+@opindex --dereference
+@cindex symbolic links, dereferencing in @command{stat}
+Change how @command{stat} treats symbolic links.
+With this option, @command{stat} acts on the file referenced
+by each symbolic link argument.
+Without it, @command{stat} acts on any symbolic link argument directly.
+
+@item -f
+@itemx --file-system
+@opindex -f
+@opindex --file-system
+@cindex file systems
+Report information about the file systems where the given files are located
+instead of information about the files themselves.
+This option implies the @option{-L} option.
+
+@item --cached=@var{mode}
+@opindex --cached=@var{mode}
+@cindex attribute caching
+Control how attributes are read from the file system;
+if supported by the system.  This allows one to
+control the trade-off between freshness and efficiency
+of attribute access, especially useful with remote file systems.
+@var{mode} can be:
+
+@table @samp
+@item always
+Always read the already cached attributes if available.
+
+@item never
+Always synchronize with the latest file system attributes.
+This also mounts automounted files.
+
+@item default
+Leave the caching behavior to the underlying file system.
+
+@end table
+
+@item -c
+@itemx --format=@var{format}
+@opindex -c
+@opindex --format=@var{format}
+@cindex output format
+Use @var{format} rather than the default format.
+@var{format} is automatically newline-terminated, so
+running a command like the following with two or more @var{file}
+operands produces a line of output for each operand:
+@example
+$ stat --format=%d:%i / /usr
+2050:2
+2057:2
+@end example
+
+@item --printf=@var{format}
+@opindex --printf=@var{format}
+@cindex output format
+Use @var{format} rather than the default format.
+Like @option{--format}, but interpret backslash escapes,
+and do not output a mandatory trailing newline.
+If you want a newline, include @samp{\n} in the @var{format}.
+Here's how you would use @option{--printf} to print the device
+and inode numbers of @file{/} and @file{/usr}:
+@example
+$ stat --printf='%d:%i\n' / /usr
+2050:2
+2057:2
+@end example
+
+@item -t
+@itemx --terse
+@opindex -t
+@opindex --terse
+@cindex terse output
+Print the information in terse form, suitable for parsing by other programs.
+
+The output of the following commands are identical and the @option{--format}
+also identifies the items printed (in fuller form) in the default format.
+Note the format string would include another @samp{%C} at the end with an
+active SELinux security context.
+@example
+$ stat --format="%n %s %b %f %u %g %D %i %h %t %T %X %Y %Z %W %o" ...
+$ stat --terse ...
+@end example
+
+The same illustrating terse output in @option{--file-system} mode:
+@example
+$ stat -f --format="%n %i %l %t %s %S %b %f %a %c %d" ...
+$ stat -f --terse ...
+@end example
+@end table
+
+The valid @var{format} directives for files with @option{--format} and
+@option{--printf} are:
+
+@itemize @bullet
+@item %a -- Permission bits in octal (note @samp{#} and @samp{0} printf flags)
+@item %A -- Permission bits in symbolic form (similar to @command{ls -ld})
+@item %b -- Number of blocks allocated (see @samp{%B})
+@item %B -- The size in bytes of each block reported by @samp{%b}
+@item %C -- The SELinux security context of a file, if available
+@item %d -- Device number in decimal (st_dev)
+@item %D -- Device number in hex (st_dev)
+@item %Hd -- Major device number in decimal
+@item %Ld -- Minor device number in decimal
+@item %f -- Raw mode in hex
+@item %F -- File type
+@item %g -- Group ID of owner
+@item %G -- Group name of owner
+@item %h -- Number of hard links
+@item %i -- Inode number
+@item %m -- Mount point (See note below)
+@item %n -- File name
+@item %N -- Quoted file name with dereference if symbolic link (see below)
+@item %o -- Optimal I/O transfer size hint
+@item %s -- Total size, in bytes
+@item %r -- Device type in decimal (st_rdev)
+@item %R -- Device type in hex (st_rdev)
+@item %Hr -- Major device type in decimal (see below)
+@item %Lr -- Minor device type in decimal (see below)
+@item %t -- Major device type in hex (see below)
+@item %T -- Minor device type in hex (see below)
+@item %u -- User ID of owner
+@item %U -- User name of owner
+@item %w -- Time of file birth, or @samp{-} if unknown
+@item %W -- Time of file birth as seconds since Epoch, or @samp{0}
+@item %x -- Time of last access
+@item %X -- Time of last access as seconds since Epoch
+@item %y -- Time of last data modification
+@item %Y -- Time of last data modification as seconds since Epoch
+@item %z -- Time of last status change
+@item %Z -- Time of last status change as seconds since Epoch
+@end itemize
+
+The @samp{%a} format prints the octal mode, and so it is useful
+to control the zero padding of the output with the @samp{#} and @samp{0}
+printf flags. For example to pad to at least 3 wide while making larger
+numbers unambiguously octal, you can use @samp{%#03a}.
+
+The @samp{%N} format can be set with the environment variable
+@env{QUOTING_STYLE}@.  If that environment variable is not set,
+the default value is @samp{shell-escape-always}.  Valid quoting styles are:
+@quotingStyles
+
+The @samp{r}, @samp{R}, @samp{%t}, and @samp{%T} formats operate on the st_rdev
+member of the stat(2) structure, i.e., the represented device rather than
+the containing device, and so are only defined for character and block
+special files.  On some systems or file types, st_rdev may be used to
+represent other quantities.
+
+The @samp{%W}, @samp{%X}, @samp{%Y}, and @samp{%Z} formats accept a
+precision preceded by a period to specify the number of digits to
+print after the decimal point.  For example, @samp{%.3X} outputs the
+access timestamp to millisecond precision.  If a period is given but no
+precision, @command{stat} uses 9 digits, so @samp{%.X} is equivalent to
+@samp{%.9X}@.  When discarding excess precision, timestamps are truncated
+toward minus infinity.
+
+@example
+zero pad:
+  $ stat -c '[%015Y]' /usr
+  [000001288929712]
+space align:
+  $ stat -c '[%15Y]' /usr
+  [     1288929712]
+  $ stat -c '[%-15Y]' /usr
+  [1288929712     ]
+precision:
+  $ stat -c '[%.3Y]' /usr
+  [1288929712.114]
+  $ stat -c '[%.Y]' /usr
+  [1288929712.114951834]
+@end example
+
+The mount point printed by @samp{%m} is similar to that output
+by @command{df}, except that:
+@itemize @bullet
+@item
+stat does not dereference symlinks by default
+(unless @option{-L} is specified)
+@item
+stat does not search for specified device nodes in the
+file system list, instead operating on them directly
+@item
+@cindex bind mount
+stat outputs the alias for a bind mounted file, rather than
+the initial mount point of its backing device.
+One can recursively call stat until there is no change in output,
+to get the current base mount point
+@end itemize
+
+When listing file system information (@option{--file-system} (@option{-f})),
+you must use a different set of @var{format} directives:
+
+@itemize @bullet
+@item %a -- Free blocks available to non-super-user
+@item %b -- Total data blocks in file system
+@item %c -- Total file nodes in file system
+@item %d -- Free file nodes in file system
+@item %f -- Free blocks in file system
+@item %i -- File System ID in hex
+@item %l -- Maximum length of file names
+@item %n -- File name
+@item %s -- Block size (for faster transfers)
+@item %S -- Fundamental block size (for block counts)
+@item %t -- Type in hex
+@item %T -- Type in human readable form
+@end itemize
+
+@vindex TZ
+Timestamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
+@env{TZ} is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
+
+@exitstatus
+
+
+@node sync invocation
+@section @command{sync}: Synchronize cached writes to persistent storage
+
+@pindex sync
+@cindex synchronize file system and memory
+@cindex Synchronize cached writes to persistent storage
+
+@command{sync} synchronizes in memory files or file systems to persistent
+storage.  Synopsis:
+
+@example
+sync [@var{option}] [@var{file}]@dots{}
+@end example
+
+@cindex superblock, writing
+@cindex inodes, written buffered
+@command{sync} writes any data buffered in memory out to the storage device.
+This can
+include (but is not limited to) modified superblocks, modified inodes,
+and delayed reads and writes.  This must be implemented by the kernel;
+The @command{sync} program does nothing but exercise the @code{sync},
+@code{syncfs}, @code{fsync}, and @code{fdatasync} system calls.
+
+@cindex crashes and corruption
+The kernel keeps data in memory to avoid doing (relatively slow) device
+reads and writes.  This improves performance, but if the computer
+crashes, data may be lost or the file system corrupted as a
+result.  The @command{sync} command instructs the kernel to write
+data in memory to persistent storage.
+
+If any argument is specified then only those files will be
+synchronized using the fsync(2) syscall by default.
+
+If at least one file is specified, it is possible to change the
+synchronization method with the following options.  Also see
+@ref{Common options}.
+
+@table @samp
+@item -d
+@itemx --data
+@opindex --data
+Use fdatasync(2) to sync only the data for the file,
+and any metadata required to maintain file system consistency.
+
+@item -f
+@itemx --file-system
+@opindex --file-system
+Synchronize all the I/O waiting for the file systems that contain the file,
+using the syscall syncfs(2).  Note you would usually @emph{not} specify
+this option if passing a device node like @samp{/dev/sda} for example,
+as that would sync the containing file system rather than the referenced one.
+Note also that depending on the system, passing individual device nodes or files
+may have different sync characteristics than using no arguments.
+I.e., arguments passed to fsync(2) may provide greater guarantees through
+write barriers, than a global sync(2) used when no arguments are provided.
+@end table
+
+@exitstatus
+
+
+@node truncate invocation
+@section @command{truncate}: Shrink or extend the size of a file
+
+@pindex truncate
+@cindex truncating, file sizes
+
+@command{truncate} shrinks or extends the size of each @var{file} to the
+specified size.  Synopsis:
+
+@example
+truncate @var{option}@dots{} @var{file}@dots{}
+@end example
+
+@cindex files, creating
+Any @var{file} that does not exist is created.
+
+@cindex sparse files, creating
+@cindex holes, creating files with
+If a @var{file} is larger than the specified size, the extra data is lost.
+If a @var{file} is shorter, it is extended and the sparse extended part
+(or hole) reads as zero bytes.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c
+@itemx --no-create
+@opindex -c
+@opindex --no-create
+Do not create files that do not exist.
+
+@item -o
+@itemx --io-blocks
+@opindex -o
+@opindex --io-blocks
+Treat @var{size} as number of I/O blocks of the @var{file} rather than bytes.
+
+@item -r @var{rfile}
+@itemx --reference=@var{rfile}
+@opindex -r
+@opindex --reference
+Base the size of each @var{file} on the size of @var{rfile}.
+
+@item -s @var{size}
+@itemx --size=@var{size}
+@opindex -s
+@opindex --size
+Set or adjust the size of each @var{file} according to @var{size}.
+@var{size} is in bytes unless @option{--io-blocks} is specified.
+@multiplierSuffixesNoBlocks{size}
+
+@var{size} may also be prefixed by one of the following to adjust
+the size of each @var{file} based on its current size:
+@example
+@samp{+}  => extend by
+@samp{-}  => reduce by
+@samp{<}  => at most
+@samp{>}  => at least
+@samp{/}  => round down to multiple of
+@samp{%}  => round up to multiple of
+@end example
+
+@end table
+
+@exitstatus
+
+
+@node Printing text
+@chapter Printing text
+
+@cindex printing text, commands for
+@cindex commands for printing text
+
+This section describes commands that display text strings.
+
+@menu
+* echo invocation::             Print a line of text.
+* printf invocation::           Format and print data.
+* yes invocation::              Print a string until interrupted.
+@end menu
+
+
+@node echo invocation
+@section @command{echo}: Print a line of text
+
+@pindex echo
+@cindex displaying text
+@cindex printing text
+@cindex text, displaying
+@cindex arbitrary text, displaying
+
+@command{echo} writes each given @var{string} to standard output, with a
+space between each and a newline after the last one.  Synopsis:
+
+@example
+echo [@var{option}]@dots{} [@var{string}]@dots{}
+@end example
+
+@mayConflictWithShellBuiltIn{echo}
+
+Due to historical and backwards compatibility reasons, certain bare option-like
+strings cannot be passed to @command{echo} as non-option arguments.
+It is therefore not advisable to use @command{echo} for printing unknown or
+variable arguments.  The @command{printf} command is recommended as a more
+portable and flexible replacement for tasks historically performed by
+@command{echo}.  @xref{printf invocation}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands, and the normally-special argument
+@samp{--} has no special meaning and is treated like any other
+@var{string}.
+
+@table @samp
+@item -n
+@opindex -n
+Do not output the trailing newline.
+
+@item -e
+@opindex -e
+@cindex backslash escapes
+Enable interpretation of the following backslash-escaped characters in
+each @var{string}:
+
+@table @samp
+@item \a
+alert (bell)
+@item \b
+backspace
+@item \c
+produce no further output
+@item \e
+escape
+@item \f
+form feed
+@item \n
+newline
+@item \r
+carriage return
+@item \t
+horizontal tab
+@item \v
+vertical tab
+@item \\
+backslash
+@item \0@var{nnn}
+the eight-bit value that is the octal number @var{nnn}
+(zero to three octal digits), if @var{nnn} is
+a nine-bit value, the ninth bit is ignored
+@item \@var{nnn}
+the eight-bit value that is the octal number @var{nnn}
+(one to three octal digits), if @var{nnn} is
+a nine-bit value, the ninth bit is ignored
+@item \x@var{hh}
+the eight-bit value that is the hexadecimal number @var{hh}
+(one or two hexadecimal digits)
+@end table
+
+@item -E
+@opindex -E
+@cindex backslash escapes
+Disable interpretation of backslash escapes in each @var{string}.
+This is the default.  If @option{-e} and @option{-E} are both
+specified, the last one given takes effect.
+
+@end table
+
+@vindex POSIXLY_CORRECT
+If the @env{POSIXLY_CORRECT} environment variable is set, then when
+@command{echo}'s first argument is not @option{-n} it outputs
+option-like arguments instead of treating them as options.  For
+example, @code{echo -ne hello} outputs @samp{-ne hello} instead of
+plain @samp{hello}.  Also backslash escapes are always enabled.
+Note to echo the string @samp{-n}, one of the characters
+can be escaped in either octal or hexadecimal representation.
+For example, @code{echo -e '\x2dn'}.
+
+POSIX does not require support for any options, and says
+that the behavior of @command{echo} is implementation-defined if any
+@var{string} contains a backslash or if the first argument is @option{-n}.
+Portable programs should use the @command{printf} command instead.
+@xref{printf invocation}.
+
+@exitstatus
+
+
+@node printf invocation
+@section @command{printf}: Format and print data
+
+@pindex printf
+@command{printf} does formatted printing of text.  Synopsis:
+
+@example
+printf @var{format} [@var{argument}]@dots{}
+@end example
+
+@command{printf} prints the @var{format} string, interpreting @samp{%}
+directives and @samp{\} escapes to format numeric and string arguments
+in a way that is mostly similar to the C @samp{printf} function.
+@xref{Output Conversion Syntax,, @command{printf} format directives,
+libc, The GNU C Library Reference Manual}, for details.
+The differences are listed below.
+
+@mayConflictWithShellBuiltIn{printf}
+
+@itemize @bullet
+
+@item
+The @var{format} argument is reused as necessary to convert all the
+given @var{argument}s.  For example, the command @samp{printf %s a b}
+outputs @samp{ab}.
+
+@item
+Missing @var{argument}s are treated as null strings or as zeros,
+depending on whether the context expects a string or a number.  For
+example, the command @samp{printf %sx%d} prints @samp{x0}.
+
+@item
+@kindex \c
+An additional escape, @samp{\c}, causes @command{printf} to produce no
+further output.  For example, the command @samp{printf 'A%sC\cD%sF' B
+E} prints @samp{ABC}.
+
+@item
+The hexadecimal escape sequence @samp{\x@var{hh}} has at most two
+digits, as opposed to C where it can have an unlimited number of
+digits.  For example, the command @samp{printf '\x07e'} prints two
+bytes, whereas the C statement @samp{printf ("\x07e")} prints just
+one.
+
+@item
+@kindex %b
+An additional directive @samp{%b}, prints its
+argument string with @samp{\} escapes interpreted in the same way as in
+the @var{format} string, except that octal escapes are of the form
+@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits.  If
+@samp{\@var{ooo}} is nine-bit value, ignore the ninth bit.
+If a precision is also given, it limits the number of bytes printed
+from the converted string.
+
+@item
+@kindex %q
+An additional directive @samp{%q}, prints its argument string
+in a format that can be reused as input by most shells.
+Non-printable characters are escaped with the POSIX proposed @samp{$''} syntax,
+and shell metacharacters are quoted appropriately.
+This is an equivalent format to @command{ls --quoting=shell-escape} output.
+
+@item
+Numeric arguments must be single C constants, possibly with leading
+@samp{+} or @samp{-}.  For example, @samp{printf %.4d -3} outputs
+@samp{-0003}.
+
+@item
+@vindex POSIXLY_CORRECT
+If the leading character of a numeric argument is @samp{"} or @samp{'}
+then its value is the numeric value of the immediately following
+character.  Any remaining characters are silently ignored if the
+@env{POSIXLY_CORRECT} environment variable is set; otherwise, a
+warning is printed.  For example, @samp{printf "%d" "'a"} outputs
+@samp{97} on hosts that use the ASCII character set, since
+@samp{a} has the numeric value 97 in ASCII.
+
+@end itemize
+
+@vindex LC_NUMERIC
+A floating point argument is interpreted according to
+the @env{LC_NUMERIC} category of either the current or the C locale,
+and is printed according to the current locale.
+For example, in a locale whose decimal point character is a comma,
+the command @samp{printf '%g %g' 2,5 2.5} outputs @samp{2,5 2,5}.
+@xref{Floating point}.
+
+@kindex \@var{ooo}
+@kindex \x@var{hh}
+@command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number
+(if @var{ooo} is 1 to 3 octal digits) specifying a byte to print,
+and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex
+digits) specifying a character to print.
+Note however that when @samp{\@var{ooo}} specifies a number larger than 255,
+@command{printf} ignores the ninth bit.
+For example, @samp{printf '\400'} is equivalent to @samp{printf '\0'}.
+
+@kindex \uhhhh
+@kindex \Uhhhhhhhh
+@cindex Unicode
+@cindex ISO/IEC 10646
+@vindex LC_CTYPE
+@command{printf} interprets two syntax forms for specifying Unicode
+(ISO/IEC 10646) characters.
+@samp{\u} for 16-bit Unicode characters, specified as
+four hexadecimal digits @var{hhhh}, and @samp{\U} for 32-bit Unicode
+characters, specified as eight hexadecimal digits @var{hhhhhhhh}.
+@command{printf} outputs the Unicode characters
+according to the @env{LC_CTYPE} locale.  Unicode characters in the range
+U+D800@dots{}U+DFFF cannot be specified by this syntax.
+This syntax fully supports the universal character subset
+introduced in ISO C 99.
+
+The processing of @samp{\u} and @samp{\U} requires a full-featured
+@code{iconv} facility.  It is activated on systems with glibc 2.2 (or newer),
+or when @code{libiconv} is installed prior to this package.  Otherwise
+@samp{\u} and @samp{\U} will print as-is.
+
+Unicode character syntax is useful for writing strings in a locale
+independent way.  For example, a string containing the Euro currency symbol
+
+@example
+$ env printf '\u20AC 14.95'
+@end example
+
+@noindent
+will be output correctly in all locales supporting the Euro symbol
+(ISO-8859-15, UTF-8, and others).  Similarly, a Chinese string
+
+@example
+$ env printf '\u4e2d\u6587'
+@end example
+
+@noindent
+will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc).
+
+Note that in these examples, the @command{printf} command has been
+invoked via @command{env} to ensure that we run the program found via
+your shell's search path, and not a shell alias or a built-in function.
+
+For larger strings, you don't need to look up the hexadecimal code
+values of each character one by one.  ASCII characters mixed with \u
+escape sequences is also known as the JAVA source file encoding.  You can
+use GNU recode 3.5c (or newer) to convert strings to this encoding.  Here
+is how to convert a piece of text into a shell script which will output
+this text in a locale-independent way:
+
+@example
+$ LC_CTYPE=zh_TW.big5 env printf \
+    '\u4e2d\u6587\n' > sample.txt
+$ recode BIG5..JAVA < sample.txt \
+    | sed -e "s|^|env printf '|" -e "s|%|%%|g" -e "s|$|\\\\n'|" \
+    > sample.sh
+@end example
+
+The only options are a lone @option{--help} or
+@option{--version}.  @xref{Common options}.
+Options must precede operands.
+
+@exitstatus
+
+
+@node yes invocation
+@section @command{yes}: Print a string until interrupted
+
+@pindex yes
+@cindex repeated output of a string
+
+@command{yes} prints the command line arguments, separated by spaces and
+followed by a newline, forever until it is killed.  If no arguments are
+given, it prints @samp{y} followed by a newline forever until killed.
+
+Upon a write error, @command{yes} exits with status @samp{1}.
+
+The only options are a lone @option{--help} or @option{--version}.
+To output an argument that begins with
+@samp{-}, precede it with @option{--}, e.g., @samp{yes -- --help}.
+@xref{Common options}.
+
+
+@node Conditions
+@chapter Conditions
+
+@cindex conditions
+@cindex commands for exit status
+@cindex exit status commands
+
+This section describes commands that are primarily useful for their exit
+status, rather than their output.  Thus, they are often used as the
+condition of shell @code{if} statements, or as the last command in a
+pipeline.
+
+@menu
+* false invocation::            Do nothing, unsuccessfully.
+* true invocation::             Do nothing, successfully.
+* test invocation::             Check file types and compare values.
+* expr invocation::             Evaluate expressions.
+@end menu
+
+
+@node false invocation
+@section @command{false}: Do nothing, unsuccessfully
+
+@pindex false
+@cindex do nothing, unsuccessfully
+@cindex failure exit status
+@cindex exit status of @command{false}
+
+@command{false} does nothing except return an exit status of 1, meaning
+@dfn{failure}.  It can be used as a place holder in shell scripts
+where an unsuccessful command is needed.
+In most modern shells, @command{false} is a built-in command, so when
+you use @samp{false} in a script, you're probably using the built-in
+command, not the one documented here.
+
+@command{false} honors the @option{--help} and @option{--version} options.
+
+This version of @command{false} is implemented as a C program, and is thus
+more secure and faster than a shell script implementation, and may safely
+be used as a dummy shell for the purpose of disabling accounts.
+
+Note that @command{false} (unlike all other programs documented herein)
+exits unsuccessfully, even when invoked with
+@option{--help} or @option{--version}.
+
+Portable programs should not assume that the exit status of
+@command{false} is 1, as it is greater than 1 on some
+non-GNU hosts.
+
+
+@node true invocation
+@section @command{true}: Do nothing, successfully
+
+@pindex true
+@cindex do nothing, successfully
+@cindex no-op
+@cindex successful exit
+@cindex exit status of @command{true}
+
+@command{true} does nothing except return an exit status of 0, meaning
+@dfn{success}.  It can be used as a place holder in shell scripts
+where a successful command is needed, although the shell built-in
+command @code{:} (colon) may do the same thing faster.
+In most modern shells, @command{true} is a built-in command, so when
+you use @samp{true} in a script, you're probably using the built-in
+command, not the one documented here.
+
+@command{true} honors the @option{--help} and @option{--version} options.
+
+Note, however, that it is possible to cause @command{true}
+to exit with nonzero status: with the @option{--help} or @option{--version}
+option, and with standard
+output already closed or redirected to a file that evokes an I/O error.
+For example, using a Bourne-compatible shell:
+
+@example
+$ ./true --version >&-
+./true: write error: Bad file number
+$ ./true --version > /dev/full
+./true: write error: No space left on device
+@end example
+
+This version of @command{true} is implemented as a C program, and is thus
+more secure and faster than a shell script implementation, and may safely
+be used as a dummy shell for the purpose of disabling accounts.
+
+@node test invocation
+@section @command{test}: Check file types and compare values
+
+@pindex test
+@cindex check file types
+@cindex compare values
+@cindex expression evaluation
+
+@command{test} returns a status of 0 (true) or 1 (false) depending on the
+evaluation of the conditional expression @var{expr}.  Each part of the
+expression must be a separate argument.
+
+@command{test} has file status checks, string operators, and numeric
+comparison operators.
+
+@command{test} has an alternate form that uses opening and closing
+square brackets instead a leading @samp{test}.  For example, instead
+of @samp{test -d /}, you can write @samp{[ -d / ]}.  The square
+brackets must be separate arguments; for example, @samp{[-d /]} does
+not have the desired effect.  Since @samp{test @var{expr}} and @samp{[
+@var{expr} ]} have the same meaning, only the former form is discussed
+below.
+
+Synopses:
+
+@example
+test @var{expression}
+test
+[ @var{expression} ]
+[ ]
+[ @var{option}
+@end example
+
+@mayConflictWithShellBuiltIn{test}
+
+If @var{expression} is omitted, @command{test} returns false.
+If @var{expression} is a single argument,
+@command{test} returns false if the argument is null and true
+otherwise.  The argument
+can be any string, including strings like @samp{-d}, @samp{-1},
+@samp{--}, @samp{--help}, and @samp{--version} that most other
+programs would treat as options.  To get help and version information,
+invoke the commands @samp{[ --help} and @samp{[ --version}, without
+the usual closing brackets.  @xref{Common options}.
+
+@cindex exit status of @command{test}
+Exit status:
+
+@display
+0 if the expression is true,
+1 if the expression is false,
+2 if an error occurred.
+@end display
+
+@menu
+* File type tests::             @code{-[bcdfhLpSt]}
+* Access permission tests::     @code{-[gkruwxOG]}
+* File characteristic tests::   @code{-e -s -nt -ot -ef}
+* String tests::                @code{-z -n = == !=}
+* Numeric tests::               @code{-eq -ne -lt -le -gt -ge}
+* Connectives for test::        @code{! -a -o}
+@end menu
+
+
+@node File type tests
+@subsection File type tests
+
+@cindex file type tests
+
+These options test for particular types of files.  (Everything's a file,
+but not all files are the same!)
+
+@table @samp
+
+@item -b @var{file}
+@opindex -b
+@cindex block special check
+True if @var{file} exists and is a block special device.
+
+@item -c @var{file}
+@opindex -c
+@cindex character special check
+True if @var{file} exists and is a character special device.
+
+@item -d @var{file}
+@opindex -d
+@cindex directory check
+True if @var{file} exists and is a directory.
+
+@item -f @var{file}
+@opindex -f
+@cindex regular file check
+True if @var{file} exists and is a regular file.
+
+@item -h @var{file}
+@itemx -L @var{file}
+@opindex -L
+@opindex -h
+@cindex symbolic link check
+True if @var{file} exists and is a symbolic link.
+Unlike all other file-related tests, this test does not dereference
+@var{file} if it is a symbolic link.
+
+@item -p @var{file}
+@opindex -p
+@cindex named pipe check
+True if @var{file} exists and is a named pipe.
+
+@item -S @var{file}
+@opindex -S
+@cindex socket check
+True if @var{file} exists and is a socket.
+
+@item -t @var{fd}
+@opindex -t
+@cindex terminal check
+True if @var{fd} is a file descriptor that is associated with a
+terminal.
+
+@end table
+
+
+@node Access permission tests
+@subsection Access permission tests
+
+@cindex access permission tests
+@cindex permission tests
+
+These options test for particular access permissions.
+
+@table @samp
+
+@item -g @var{file}
+@opindex -g
+@cindex set-group-ID check
+True if @var{file} exists and has its set-group-ID bit set.
+
+@item -k @var{file}
+@opindex -k
+@cindex sticky bit check
+True if @var{file} exists and has its @dfn{sticky} bit set.
+
+@item -r @var{file}
+@opindex -r
+@cindex readable file check
+True if @var{file} exists and the user has read access.
+
+@item -u @var{file}
+@opindex -u
+@cindex set-user-ID check
+True if @var{file} exists and has its set-user-ID bit set.
+
+@item -w @var{file}
+@opindex -w
+@cindex writable file check
+True if @var{file} exists and the user has write access.
+
+@item -x @var{file}
+@opindex -x
+@cindex executable file check
+True if @var{file} exists and the user has execute access
+(or search permission, if it is a directory).
+
+@item -O @var{file}
+@opindex -O
+@cindex owned by effective user ID check
+True if @var{file} exists and is owned by the current effective user ID.
+
+@item -G @var{file}
+@opindex -G
+@cindex owned by effective group ID check
+True if @var{file} exists and is owned by the current effective group ID.
+
+@end table
+
+@node File characteristic tests
+@subsection File characteristic tests
+
+@cindex file characteristic tests
+
+These options test other file characteristics.
+
+@table @samp
+
+@item -e @var{file}
+@opindex -e
+@cindex existence-of-file check
+True if @var{file} exists.
+
+@item -s @var{file}
+@opindex -s
+@cindex nonempty file check
+True if @var{file} exists and has a size greater than zero.
+
+@item @var{file1} -nt @var{file2}
+@opindex -nt
+@cindex newer-than file check
+True if @var{file1} is newer (according to modification date) than
+@var{file2}, or if @var{file1} exists and @var{file2} does not.
+
+@item @var{file1} -ot @var{file2}
+@opindex -ot
+@cindex older-than file check
+True if @var{file1} is older (according to modification date) than
+@var{file2}, or if @var{file2} exists and @var{file1} does not.
+
+@item @var{file1} -ef @var{file2}
+@opindex -ef
+@cindex same file check
+@cindex hard link check
+True if @var{file1} and @var{file2} have the same device and inode
+numbers, i.e., if they are hard links to each other.
+
+@item -N @var{file}
+@opindex -N
+@cindex mtime-greater-atime file check
+True if @var{file} exists and has been modified (mtime) since it was
+last read (atime).
+
+@end table
+
+
+@node String tests
+@subsection String tests
+
+@cindex string tests
+
+These options test string characteristics.  You may need to quote
+@var{string} arguments for the shell.  For example:
+
+@example
+test -n "$V"
+@end example
+
+The quotes here prevent the wrong arguments from being passed to
+@command{test} if @samp{$V} is empty or contains special characters.
+
+@table @samp
+
+@item -z @var{string}
+@opindex -z
+@cindex zero-length string check
+True if the length of @var{string} is zero.
+
+@item -n @var{string}
+@itemx @var{string}
+@opindex -n
+@cindex nonzero-length string check
+True if the length of @var{string} is nonzero.
+
+@item @var{string1} = @var{string2}
+@opindex =
+@cindex equal string check
+True if the strings are equal.
+
+@item @var{string1} == @var{string2}
+@opindex ==
+@cindex equal string check
+True if the strings are equal (synonym for =).
+Note this form is not as portable to other
+shells and systems.
+
+@item @var{string1} != @var{string2}
+@opindex !=
+@cindex not-equal string check
+True if the strings are not equal.
+
+@end table
+
+
+@node Numeric tests
+@subsection Numeric tests
+
+@cindex numeric tests
+@cindex arithmetic tests
+
+Numeric relational operators.  The arguments must be entirely numeric
+(possibly negative), or the special expression @w{@code{-l @var{string}}},
+which evaluates to the length of @var{string}.
+
+@table @samp
+
+@item @var{arg1} -eq @var{arg2}
+@itemx @var{arg1} -ne @var{arg2}
+@itemx @var{arg1} -lt @var{arg2}
+@itemx @var{arg1} -le @var{arg2}
+@itemx @var{arg1} -gt @var{arg2}
+@itemx @var{arg1} -ge @var{arg2}
+@opindex -eq
+@opindex -ne
+@opindex -lt
+@opindex -le
+@opindex -gt
+@opindex -ge
+These arithmetic binary operators return true if @var{arg1} is equal,
+not-equal, less-than, less-than-or-equal, greater-than, or
+greater-than-or-equal than @var{arg2}, respectively.
+
+@end table
+
+For example:
+
+@example
+test -1 -gt -2 && echo yes
+@result{} yes
+test -l abc -gt 1 && echo yes
+@result{} yes
+test 0x100 -eq 1
+@error{} test: integer expression expected before -eq
+@end example
+
+
+@node Connectives for test
+@subsection Connectives for @command{test}
+
+@cindex logical connectives
+@cindex connectives, logical
+
+Note it's preferred to use shell logical primitives
+rather than these logical connectives internal to @command{test},
+because an expression may become ambiguous
+depending on the expansion of its parameters.
+
+For example, this becomes ambiguous when @samp{$1}
+is set to @samp{'!'} and @samp{$2} to the empty string @samp{''}:
+
+@example
+test "$1" -a "$2"
+@end example
+
+and should be written as:
+
+@example
+test "$1" && test "$2"
+@end example
+
+Note the shell logical primitives also benefit from
+short circuit operation, which can be significant
+for file attribute tests.
+
+@table @samp
+
+@item ! @var{expr}
+@opindex !
+True if @var{expr} is false.
+@samp{!} has lower precedence than all parts of @var{expr}.
+Note @samp{!} needs to be specified to the left
+of a binary expression, I.e., @samp{'!' 1 -gt 2}
+rather than @samp{1 '!' -gt 2}.
+Also @samp{!} is often a shell special character
+and is best used quoted.
+
+
+@item @var{expr1} -a @var{expr2}
+@opindex -a
+@cindex logical and operator
+@cindex and operator
+True if both @var{expr1} and @var{expr2} are true.
+@samp{-a} is left associative,
+and has a higher precedence than @samp{-o}.
+
+@item @var{expr1} -o @var{expr2}
+@opindex -o
+@cindex logical or operator
+@cindex or operator
+True if either @var{expr1} or @var{expr2} is true.
+@samp{-o} is left associative.
+
+@end table
+
+
+@node expr invocation
+@section @command{expr}: Evaluate expressions
+
+@pindex expr
+@cindex expression evaluation
+@cindex evaluation of expressions
+
+@command{expr} evaluates an expression and writes the result on standard
+output.  Each token of the expression must be a separate argument.
+
+Operands are either integers or strings.  Integers consist of one or
+more decimal digits, with an optional leading @samp{-}.
+@command{expr} converts
+anything appearing in an operand position to an integer or a string
+depending on the operation being applied to it.
+
+Strings are not quoted for @command{expr} itself, though you may need to
+quote them to protect characters with special meaning to the shell,
+e.g., spaces.  However, regardless of whether it is quoted, a string
+operand should not be a parenthesis or any of @command{expr}'s
+operators like @code{+}, so you cannot safely pass an arbitrary string
+@code{$str} to expr merely by quoting it to the shell.  One way to
+work around this is to use the GNU extension @code{+},
+(e.g., @code{+ "$str" = foo}); a more portable way is to use
+@code{@w{" $str"}} and to adjust the rest of the expression to take
+the leading space into account (e.g., @code{@w{" $str" = " foo"}}).
+
+You should not pass a negative integer or a string with leading
+@samp{-} as @command{expr}'s first argument, as it might be
+misinterpreted as an option; this can be avoided by parenthesization.
+Also, portable scripts should not use a string operand that happens to
+take the form of an integer; this can be worked around by inserting
+leading spaces as mentioned above.
+
+@cindex parentheses for grouping
+Operators may be given as infix symbols or prefix keywords.  Parentheses
+may be used for grouping in the usual manner.  You must quote
+parentheses and many operators to avoid the shell evaluating them,
+however.
+
+Because @command{expr} uses multiple-precision arithmetic, it works
+with integers wider than those of machine registers.
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.  Options must precede operands.
+
+@cindex exit status of @command{expr}
+Exit status:
+
+@display
+0 if the expression is neither null nor 0,
+1 if the expression is null or 0,
+2 if the expression is invalid,
+3 if an internal error occurred (e.g., arithmetic overflow).
+@end display
+
+@menu
+* String expressions::          @code{+ : match substr index length}
+* Numeric expressions::         @code{+ - * / %}
+* Relations for expr::          @code{| & < <= = == != >= >}
+* Examples of expr::            Examples.
+@end menu
+
+
+@node String expressions
+@subsection String expressions
+
+@cindex string expressions
+@cindex expressions, string
+
+@command{expr} supports pattern matching and other string operators.  These
+have higher precedence than both the numeric and relational operators (in
+the next sections).
+
+@table @samp
+
+@item @var{string} : @var{regex}
+@cindex pattern matching
+@cindex regular expression matching
+@cindex matching patterns
+Perform pattern matching.  The arguments are converted to strings and the
+second is considered to be a (basic, a la GNU @code{grep}) regular
+expression, with a @code{^} implicitly prepended.  The first argument is
+then matched against this regular expression.
+
+If @var{regex} does not use @samp{\(} and @samp{\)}, the @code{:}
+expression returns the number of characters matched, or 0 if the match
+fails.
+
+If @var{regex} uses @samp{\(} and @samp{\)}, the @code{:} expression
+returns the part of @var{string} that matched the subexpression, or
+the null string if the match failed or the subexpression did not
+contribute to the match.
+
+@kindex \( @r{regexp operator}
+Only the first @samp{\( @dots{} \)} pair is relevant to the return
+value; additional pairs are meaningful only for grouping the regular
+expression operators.
+
+@kindex \+ @r{regexp operator}
+@kindex \? @r{regexp operator}
+@kindex \| @r{regexp operator}
+In the regular expression, @code{\+}, @code{\?}, and @code{\|} are
+operators which respectively match one or more, zero or one, or separate
+alternatives.  These operators are GNU extensions.  @xref{Regular Expressions,,
+Regular Expressions, grep, The GNU Grep Manual}, for details of
+regular expression syntax.  Some examples are in @ref{Examples of expr}.
+
+@item match @var{string} @var{regex}
+@findex match
+An alternative way to do pattern matching.  This is the same as
+@w{@samp{@var{string} : @var{regex}}}.
+
+@item substr @var{string} @var{position} @var{length}
+@findex substr
+Returns the substring of @var{string} beginning at @var{position}
+with length at most @var{length}.  If either @var{position} or
+@var{length} is negative, zero, or non-numeric, returns the null string.
+
+@item index @var{string} @var{charset}
+@findex index
+Returns the first position in @var{string} where the first character in
+@var{charset} was found.  If no character in @var{charset} is found in
+@var{string}, return 0.
+
+@item length @var{string}
+@findex length
+Returns the length of @var{string}.
+
+@item + @var{token}
+@kindex +
+Interpret @var{token} as a string, even if it is a keyword like @var{match}
+or an operator like @code{/}.
+This makes it possible to test @code{expr length + "$x"} or
+@code{expr + "$x" : '.*/\(.\)'} and have it do the right thing even if
+the value of @var{$x} happens to be (for example) @code{/} or @code{index}.
+This operator is a GNU extension.  Portable shell scripts should use
+@code{@w{" $token"} : @w{' \(.*\)'}} instead of @code{+ "$token"}.
+
+@end table
+
+To make @command{expr} interpret keywords as strings, you must use the
+@code{quote} operator.
+
+
+@node Numeric expressions
+@subsection Numeric expressions
+
+@cindex numeric expressions
+@cindex expressions, numeric
+
+@command{expr} supports the usual numeric operators, in order of increasing
+precedence.  These numeric operators have lower precedence than the
+string operators described in the previous section, and higher precedence
+than the connectives (next section).
+
+@table @samp
+
+@item + -
+@kindex +
+@kindex -
+@cindex addition
+@cindex subtraction
+Addition and subtraction.  Both arguments are converted to integers;
+an error occurs if this cannot be done.
+
+@item * / %
+@kindex *
+@kindex /
+@kindex %
+@cindex multiplication
+@cindex division
+@cindex remainder
+Multiplication, division, remainder.  Both arguments are converted to
+integers; an error occurs if this cannot be done.
+
+@end table
+
+
+@node Relations for expr
+@subsection Relations for @command{expr}
+
+@cindex connectives, logical
+@cindex logical connectives
+@cindex relations, numeric or string
+
+@command{expr} supports the usual logical connectives and relations.  These
+have lower precedence than the string and numeric operators
+(previous sections).  Here is the list, lowest-precedence operator first.
+
+@table @samp
+
+@item |
+@kindex |
+@cindex logical or operator
+@cindex or operator
+Returns its first argument if that is neither null nor zero, otherwise
+its second argument if it is neither null nor zero, otherwise 0.  It
+does not evaluate its second argument if its first argument is neither
+null nor zero.
+
+@item &
+@kindex &
+@cindex logical and operator
+@cindex and operator
+Return its first argument if neither argument is null or zero, otherwise
+0.  It does not evaluate its second argument if its first argument is
+null or zero.
+
+@item < <= = == != >= >
+@kindex <
+@kindex <=
+@kindex =
+@kindex ==
+@kindex >
+@kindex >=
+@cindex comparison operators
+@vindex LC_COLLATE
+Compare the arguments and return 1 if the relation is true, 0 otherwise.
+@code{==} is a synonym for @code{=}.  @command{expr} first tries to convert
+both arguments to integers and do a numeric comparison; if either
+conversion fails, it does a lexicographic comparison using the character
+collating sequence specified by the @env{LC_COLLATE} locale.
+
+@end table
+
+
+@node Examples of expr
+@subsection Examples of using @command{expr}
+
+@cindex examples of @command{expr}
+Here are a few examples, including quoting for shell metacharacters.
+
+To add 1 to the shell variable @code{foo}, in Bourne-compatible shells:
+
+@example
+foo=$(expr $foo + 1)
+@end example
+
+To print the non-directory part of the file name stored in
+@code{$fname}, which need not contain a @code{/}:
+
+@example
+expr $fname : '.*/\(.*\)' '|' $fname
+@end example
+
+An example showing that @code{\+} is an operator:
+
+@example
+expr aaa : 'a\+'
+@result{} 3
+@end example
+
+@example
+expr abc : 'a\(.\)c'
+@result{} b
+expr index abcdef cz
+@result{} 3
+expr index index a
+@error{} expr: syntax error
+expr index + index a
+@result{} 0
+@end example
+
+
+@node Redirection
+@chapter Redirection
+
+@cindex redirection
+@cindex commands for redirection
+
+Unix shells commonly provide several forms of @dfn{redirection} -- ways
+to change the input source or output destination of a command.  But one
+useful redirection is performed by a separate command, not by the shell;
+it's described here.
+
+@menu
+* tee invocation::              Redirect output to multiple files or processes.
+@end menu
+
+
+@node tee invocation
+@section @command{tee}: Redirect output to multiple files or processes
+
+@pindex tee
+@cindex pipe fitting
+@cindex destinations, multiple output
+@cindex read from standard input and write to standard output and files
+
+The @command{tee} command copies standard input to standard output and also
+to any files given as arguments.  This is useful when you want not only
+to send some data down a pipe, but also to save a copy.  Synopsis:
+
+@example
+tee [@var{option}]@dots{} [@var{file}]@dots{}
+@end example
+
+If a file being written to does not already exist, it is created.  If a
+file being written to already exists, the data it previously contained
+is overwritten unless the @option{-a} option is used.
+
+In previous versions of GNU Coreutils (5.3.0--8.23),
+a @var{file} of @samp{-}
+caused @command{tee} to send another copy of input to standard output.
+However, as the interleaved output was not very useful, @command{tee} now
+conforms to POSIX and treats @samp{-} as a file name.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+@item -a
+@itemx --append
+@opindex -a
+@opindex --append
+Append standard input to the given files rather than overwriting
+them.
+
+@item -i
+@itemx --ignore-interrupts
+@opindex -i
+@opindex --ignore-interrupts
+Ignore interrupt signals.
+
+@item -p
+@itemx --output-error[=@var{mode}]
+@opindex -p
+@opindex --output-error
+Adjust the behavior with errors on the outputs.
+In summary @option{-p} allows @command{tee} to operate in a more
+appropriate manner with pipes, and to continue to process data
+to any remaining outputs, if any pipe outputs exit early.
+The default operation when @option{--output-error} is @emph{not}
+specified is to exit immediately on error writing to a pipe,
+and diagnose errors writing to a non-pipe.
+The long form @option{--output-error} option supports selection
+between the following @var{mode}s:
+
+@table @samp
+@item warn
+Warn on error opening or writing any output, including pipes.
+Writing is continued to still open files/pipes.
+Exit status indicates failure if any output has an error.
+
+@item warn-nopipe
+This is the default @var{mode} when not specified,
+or when the short form @option{-p} is used.
+Warn on error opening or writing any output, except pipes.
+Writing is continued to still open files/pipes.
+Exit immediately if all remaining outputs become broken pipes.
+Exit status indicates failure if any non pipe output had an error.
+
+@item exit
+Exit on error opening or writing any output, including pipes.
+
+@item exit-nopipe
+Exit on error opening or writing any output, except pipes.
+Exit immediately if all remaining outputs become broken pipes.
+@end table
+
+@end table
+
+The @command{tee} command is useful when you happen to be transferring a large
+amount of data and also want to summarize that data without reading
+it a second time.  For example, when you are downloading a DVD image,
+you often want to verify its signature or checksum right away.
+The inefficient way to do it is simply:
+
+@example
+wget https://example.com/some.iso && sha1sum some.iso
+@end example
+
+One problem with the above is that it makes you wait for the
+download to complete before starting the time-consuming SHA1 computation.
+Perhaps even more importantly, the above requires reading
+the DVD image a second time (the first was from the network).
+
+The efficient way to do it is to interleave the download
+and SHA1 computation.  Then, you'll get the checksum for
+free, because the entire process parallelizes so well:
+
+@example
+# slightly contrived, to demonstrate process substitution
+wget -O - https://example.com/dvd.iso \
+  | tee >(sha1sum > dvd.sha1) > dvd.iso
+@end example
+
+That makes @command{tee} write not just to the expected output file,
+but also to a pipe running @command{sha1sum} and saving the final
+checksum in a file named @file{dvd.sha1}.
+
+Note, however, that this example relies on a feature of modern shells
+called @dfn{process substitution}
+(the @samp{>(command)} syntax, above;
+@xref{Process Substitution,,Process Substitution, bash,
+The Bash Reference Manual}.),
+so it works with @command{zsh}, @command{bash}, and @command{ksh},
+but not with @command{/bin/sh}.  So if you write code like this
+in a shell script, be sure to start the script with @samp{#!/bin/bash}.
+
+Note also that if any of the process substitutions (or piped standard output)
+might exit early without consuming all the data, the @option{-p} option
+is needed to allow @command{tee} to continue to process the input
+to any remaining outputs.
+
+Since the above example writes to one file and one process,
+a more conventional and portable use of @command{tee} is even better:
+
+@example
+wget -O - https://example.com/dvd.iso \
+  | tee dvd.iso | sha1sum > dvd.sha1
+@end example
+
+You can extend this example to make @command{tee} write to two processes,
+computing MD5 and SHA1 checksums in parallel.  In this case,
+process substitution is required:
+
+@example
+wget -O - https://example.com/dvd.iso \
+  | tee >(sha1sum > dvd.sha1) \
+        >(md5sum > dvd.md5) \
+  > dvd.iso
+@end example
+
+This technique is also useful when you want to make a @emph{compressed}
+copy of the contents of a pipe.
+Consider a tool to graphically summarize file system usage data from
+@samp{du -ak}.
+For a large hierarchy, @samp{du -ak} can run for a long time,
+and can easily produce terabytes of data, so you won't want to
+rerun the command unnecessarily.  Nor will you want to save
+the uncompressed output.
+
+Doing it the inefficient way, you can't even start the GUI
+until after you've compressed all of the @command{du} output:
+
+@example
+du -ak | gzip -9 > /tmp/du.gz
+gzip -d /tmp/du.gz | checkspace -a
+@end example
+
+With @command{tee} and process substitution, you start the GUI
+right away and eliminate the decompression completely:
+
+@example
+du -ak | tee >(gzip -9 > /tmp/du.gz) | checkspace -a
+@end example
+
+Finally, if you regularly create more than one type of
+compressed tarball at once, for example when @code{make dist} creates
+both @command{gzip}-compressed and @command{bzip2}-compressed tarballs,
+there may be a better way.
+Typical @command{automake}-generated @file{Makefile} rules create
+the two compressed tar archives with commands in sequence, like this
+(slightly simplified):
+
+@example
+tardir=your-pkg-M.N
+tar chof - "$tardir" | gzip  -9 -c > your-pkg-M.N.tar.gz
+tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2
+@end example
+
+However, if the hierarchy you are archiving and compressing is larger
+than a couple megabytes, and especially if you are using a multi-processor
+system with plenty of memory, then you can do much better by reading the
+directory contents only once and running the compression programs in parallel:
+
+@example
+tardir=your-pkg-M.N
+tar chof - "$tardir" \
+  | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \
+  | bzip2 -9 -c > your-pkg-M.N.tar.bz2
+@end example
+
+If you want to further process the output from process substitutions,
+and those processes write atomically (i.e., write less than the system's
+PIPE_BUF size at a time), that's possible with a construct like:
+
+@example
+tardir=your-pkg-M.N
+tar chof - "$tardir" \
+  | tee >(md5sum --tag) > >(sha256sum --tag) \
+  | sort | gpg --clearsign > your-pkg-M.N.tar.sig
+@end example
+
+@exitstatus
+
+
+@node File name manipulation
+@chapter File name manipulation
+
+@cindex file name manipulation
+@cindex manipulation of file names
+@cindex commands for file name manipulation
+
+This section describes commands that manipulate file names.
+
+@menu
+* basename invocation::         Strip directory and suffix from a file name.
+* dirname invocation::          Strip last file name component.
+* pathchk invocation::          Check file name validity and portability.
+* mktemp invocation::           Create temporary file or directory.
+* realpath invocation::         Print resolved file names.
+@end menu
+
+
+@node basename invocation
+@section @command{basename}: Strip directory and suffix from a file name
+
+@pindex basename
+@cindex strip directory and suffix from file names
+@cindex directory, stripping from file names
+@cindex suffix, stripping from file names
+@cindex file names, stripping directory and suffix
+@cindex leading directory components, stripping
+
+@command{basename} removes any leading directory components from
+@var{name}.  Synopsis:
+
+@example
+basename @var{name} [@var{suffix}]
+basename @var{option}@dots{} @var{name}@dots{}
+@end example
+
+If @var{suffix} is specified and is identical to the end of @var{name},
+it is removed from @var{name} as well.  Note that since trailing slashes
+are removed prior to suffix matching, @var{suffix} will do nothing if it
+contains slashes.  @command{basename} prints the result on standard
+output.
+
+@c This test is used both here and in the section on dirname.
+@macro basenameAndDirname
+Together, @command{basename} and @command{dirname} are designed such
+that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd
+"$(dirname "$name")"; ls "$(basename "$name")"} will, too.  This works
+for everything except file names containing a trailing newline.
+@end macro
+@basenameAndDirname
+
+POSIX allows the implementation to define the results if
+@var{name} is empty or @samp{//}.  In the former case, GNU
+@command{basename} returns the empty string.  In the latter case, the
+result is @samp{//} on platforms where @var{//} is distinct from
+@var{/}, and @samp{/} on platforms where there is no difference.
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+
+@item -a
+@itemx --multiple
+@opindex -a
+@opindex --multiple
+Support more than one argument.  Treat every argument as a @var{name}.
+With this, an optional @var{suffix} must be specified using the
+@option{-s} option.
+
+@item -s @var{suffix}
+@itemx --suffix=@var{suffix}
+@opindex -s
+@opindex --suffix
+Remove a trailing @var{suffix}.
+This option implies the @option{-a} option.
+
+@optZero
+
+@end table
+
+@exitstatus
+
+Examples:
+
+@example
+# Output "sort".
+basename /usr/bin/sort
+
+# Output "stdio".
+basename include/stdio.h .h
+
+# Output "stdio".
+basename -s .h include/stdio.h
+
+# Output "stdio" followed by "stdlib"
+basename -a -s .h include/stdio.h include/stdlib.h
+@end example
+
+
+@node dirname invocation
+@section @command{dirname}: Strip last file name component
+
+@pindex dirname
+@cindex directory components, printing
+@cindex stripping non-directory suffix
+@cindex non-directory suffix, stripping
+
+@command{dirname} prints all but the final slash-delimited component
+of each @var{name}.  Slashes on either side of the final component are
+also removed.  If the string contains no slash, @command{dirname}
+prints @samp{.} (meaning the current directory).  Synopsis:
+
+@example
+dirname [@var{option}] @var{name}@dots{}
+@end example
+
+@var{name} need not be a file name, but if it is, this operation
+effectively lists the directory that contains the final component,
+including the case when the final component is itself a directory.
+
+@basenameAndDirname
+
+POSIX allows the implementation to define the results if
+@var{name} is @samp{//}.  With GNU @command{dirname}, the
+result is @samp{//} on platforms where @var{//} is distinct from
+@var{/}, and @samp{/} on platforms where there is no difference.
+
+The program accepts the following option.  Also see @ref{Common options}.
+
+@table @samp
+
+@optZero
+
+@end table
+
+@exitstatus
+
+Examples:
+
+@example
+# Output "/usr/bin".
+dirname /usr/bin/sort
+dirname /usr/bin//.//
+
+# Output "dir1" followed by "dir2"
+dirname dir1/str dir2/str
+
+# Output ".".
+dirname stdio.h
+@end example
+
+
+@node pathchk invocation
+@section @command{pathchk}: Check file name validity and portability
+
+@pindex pathchk
+@cindex file names, checking validity and portability
+@cindex valid file names, checking for
+@cindex portable file names, checking for
+
+@command{pathchk} checks validity and portability of file names.  Synopsis:
+
+@example
+pathchk [@var{option}]@dots{} @var{name}@dots{}
+@end example
+
+For each @var{name}, @command{pathchk} prints an error message if any of
+these conditions is true:
+
+@enumerate
+@item
+One of the existing directories in @var{name} does not have search
+(execute) permission,
+@item
+The length of @var{name} is larger than the maximum supported by the
+operating system.
+@item
+The length of one component of @var{name} is longer than
+its file system's maximum.
+@end enumerate
+
+A nonexistent @var{name} is not an error, so long as a file with that
+name could be created under the above conditions.
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+
+@item -p
+@opindex -p
+Instead of performing checks based on the underlying file system,
+print an error message if any of these conditions is true:
+
+@enumerate
+@item
+A file name is empty.
+
+@item
+A file name contains a character outside the POSIX portable file
+name character set, namely, the ASCII letters and digits, @samp{.},
+@samp{_}, @samp{-}, and @samp{/}.
+
+@item
+The length of a file name or one of its components exceeds the
+POSIX minimum limits for portability.
+@end enumerate
+
+@item -P
+@opindex -P
+Print an error message if a file name is empty, or if it contains a component
+that begins with @samp{-}.
+
+@item --portability
+@opindex --portability
+Print an error message if a file name is not portable to all POSIX
+hosts.  This option is equivalent to @samp{-p -P}.
+
+@end table
+
+@cindex exit status of @command{pathchk}
+Exit status:
+
+@display
+0 if all specified file names passed all checks,
+1 otherwise.
+@end display
+
+@node mktemp invocation
+@section @command{mktemp}: Create temporary file or directory
+
+@pindex mktemp
+@cindex file names, creating temporary
+@cindex directory, creating temporary
+@cindex temporary files and directories
+
+@command{mktemp} manages the creation of temporary files and
+directories.  Synopsis:
+
+@example
+mktemp [@var{option}]@dots{} [@var{template}]
+@end example
+
+Safely create a temporary file or directory based on @var{template},
+and print its name.  If given, @var{template} must include at least
+three consecutive @samp{X}s in the last component.  If omitted, the template
+@samp{tmp.XXXXXXXXXX} is used, and option @option{--tmpdir} is
+implied.  The final run of @samp{X}s in the @var{template} will be replaced
+by alpha-numeric characters; thus, on a case-sensitive file system,
+and with a @var{template} including a run of @var{n} instances of @samp{X},
+there are @samp{62**@var{n}} potential file names.
+
+Older scripts used to create temporary files by simply joining the
+name of the program with the process id (@samp{$$}) as a suffix.
+However, that naming scheme is easily predictable, and suffers from a
+race condition where the attacker can create an appropriately named
+symbolic link, such that when the script then opens a handle to what
+it thought was an unused file, it is instead modifying an existing
+file.  Using the same scheme to create a directory is slightly safer,
+since the @command{mkdir} will fail if the target already exists, but
+it is still inferior because it allows for denial of service attacks.
+Therefore, modern scripts should use the @command{mktemp} command to
+guarantee that the generated name will be unpredictable, and that
+knowledge of the temporary file name implies that the file was created
+by the current script and cannot be modified by other users.
+
+When creating a file, the resulting file has read and write
+permissions for the current user, but no permissions for the group or
+others; these permissions are reduced if the current umask is more
+restrictive.
+
+Here are some examples (although note that if you repeat them, you
+will most likely get different file names):
+
+@itemize @bullet
+
+@item
+Create a temporary file in the current directory.
+@example
+$ mktemp file.XXXX
+file.H47c
+@end example
+
+@item
+Create a temporary file with a known suffix.
+@example
+$ mktemp --suffix=.txt file-XXXX
+file-H08W.txt
+$ mktemp file-XXXX-XXXX.txt
+file-XXXX-eI9L.txt
+@end example
+
+@item
+Create a secure fifo relative to the user's choice of @env{TMPDIR},
+but falling back to the current directory rather than @file{/tmp}.
+Note that @command{mktemp} does not create fifos, but can create a
+secure directory in which the fifo can live.  Exit the shell if the
+directory or fifo could not be created.
+@example
+$ dir=$(mktemp -p "$@{TMPDIR:-.@}" -d dir-XXXX) || exit 1
+$ fifo=$dir/fifo
+$ mkfifo "$fifo" || @{ rmdir "$dir"; exit 1; @}
+@end example
+
+@item
+Create and use a temporary file if possible, but ignore failure.  The
+file will reside in the directory named by @env{TMPDIR}, if specified,
+or else in @file{/tmp}.
+@example
+$ file=$(mktemp -q) && @{
+>   # Safe to use $file only within this block.  Use quotes,
+>   # since $TMPDIR, and thus $file, may contain whitespace.
+>   echo ... > "$file"
+>   rm "$file"
+> @}
+@end example
+
+@item
+Act as a semi-random character generator (it is not fully random,
+since it is impacted by the contents of the current directory).  To
+avoid security holes, do not use the resulting names to create a file.
+@example
+$ mktemp -u XXX
+Gb9
+$ mktemp -u XXX
+nzC
+@end example
+
+@end itemize
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -d
+@itemx --directory
+@opindex -d
+@opindex --directory
+Create a directory rather than a file.  The directory will have read,
+write, and search permissions for the current user, but no permissions
+for the group or others; these permissions are reduced if the current
+umask is more restrictive.
+
+@item -q
+@itemx --quiet
+@opindex -q
+@opindex --quiet
+Suppress diagnostics about failure to create a file or directory.  The
+exit status will still reflect whether a file was created.
+
+@item -u
+@itemx --dry-run
+@opindex -u
+@opindex --dry-run
+Generate a temporary name that does not name an existing file, without
+changing the file system contents.  Using the output of this command
+to create a new file is inherently unsafe, as there is a window of
+time between generating the name and using it where another process
+can create an object by the same name.
+
+@item -p @var{dir}
+@itemx --tmpdir[=@var{dir}]
+@opindex -p
+@opindex --tmpdir
+Treat @var{template} relative to the directory @var{dir}.  If
+@var{dir} is not specified (only possible with the long option
+@option{--tmpdir}) or is the empty string, use the value of
+@env{TMPDIR} if available, otherwise use @samp{/tmp}.  If this is
+specified, @var{template} must not be absolute.  However,
+@var{template} can still contain slashes, although intermediate
+directories must already exist.
+
+@item --suffix=@var{suffix}
+@opindex --suffix
+Append @var{suffix} to the @var{template}.  @var{suffix} must not
+contain slash.  If @option{--suffix} is specified, @var{template} must
+end in @samp{X}; if it is not specified, then an appropriate
+@option{--suffix} is inferred by finding the last @samp{X} in
+@var{template}.  This option exists for use with the default
+@var{template} and for the creation of a @var{suffix} that starts with
+@samp{X}.
+
+@item -t
+@opindex -t
+Treat @var{template} as a single file relative to the value of
+@env{TMPDIR} if available, or to the directory specified by
+@option{-p}, otherwise to @samp{/tmp}.  @var{template} must not
+contain slashes.  This option is deprecated; the use of @option{-p}
+without @option{-t} offers better defaults (by favoring the command
+line over @env{TMPDIR}) and more flexibility (by allowing intermediate
+directories).
+
+@end table
+
+@cindex exit status of @command{mktemp}
+Exit status:
+
+@display
+0 if the file was created,
+1 otherwise.
+@end display
+
+
+@node realpath invocation
+@section @command{realpath}: Print the resolved file name.
+
+@pindex realpath
+@cindex file names, canonicalization
+@cindex symlinks, resolution
+@cindex canonical file name
+@cindex canonicalize a file name
+@pindex realpath
+@findex realpath
+
+@command{realpath} expands all symbolic links and resolves references to
+@samp{/./}, @samp{/../} and extra @samp{/} characters.  By default,
+all but the last component of the specified files must exist.  Synopsis:
+
+@example
+realpath [@var{option}]@dots{} @var{file}@dots{}
+@end example
+
+The file name canonicalization functionality overlaps with that of the
+@command{readlink} command.  This is the preferred command for
+canonicalization as it's a more suitable and standard name.  In addition
+this command supports relative file name processing functionality.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -e
+@itemx --canonicalize-existing
+@opindex -e
+@opindex --canonicalize-existing
+Ensure that all components of the specified file names exist.
+If any component is missing or unavailable, @command{realpath} will output
+a diagnostic unless the @option{-q} option is specified, and exit with a
+nonzero exit code.  A trailing slash requires that the name resolve to a
+directory.
+
+@item -m
+@itemx --canonicalize-missing
+@opindex -m
+@opindex --canonicalize-missing
+If any component of a specified file name is missing or unavailable,
+treat it as a directory.
+
+@item -L
+@itemx --logical
+@opindex -L
+@opindex --logical
+Symbolic links are resolved in the specified file names,
+but they are resolved after any subsequent @samp{..} components are processed.
+
+@item -P
+@itemx --physical
+@opindex -P
+@opindex --physical
+Symbolic links are resolved in the specified file names,
+and they are resolved before any subsequent @samp{..} components are processed.
+This is the default mode of operation.
+
+@item -q
+@itemx --quiet
+@opindex -q
+@opindex --quiet
+Suppress diagnostic messages for specified file names.
+
+@item --relative-to=@var{dir}
+@opindex --relative-to
+@cindex relpath
+Print the resolved file names relative to the specified directory.
+Note this option honors the @option{-m} and @option{-e} options
+pertaining to file existence.
+
+@item --relative-base=@var{dir}
+@opindex --relative-base
+Print the resolved file names as relative @emph{if} the files
+are descendants of @var{dir}.
+Otherwise, print the resolved file names as absolute.
+Note this option honors the @option{-m} and @option{-e} options
+pertaining to file existence.
+For details about combining @option{--relative-to} and @option{--relative-base},
+@pxref{Realpath usage examples}.
+
+@item -s
+@itemx --strip
+@itemx --no-symlinks
+@opindex -s
+@opindex --strip
+@opindex --no-symlinks
+Do not resolve symbolic links.  Only resolve references to
+@samp{/./}, @samp{/../} and remove extra @samp{/} characters.
+When combined with the @option{-m} option, realpath operates
+only on the file name, and does not touch any actual file.
+
+@optZero
+
+@end table
+
+@cindex exit status of @command{realpath}
+Exit status:
+
+@display
+0 if all file names were printed without issue.
+1 otherwise.
+@end display
+
+@menu
+* Realpath usage examples::              Realpath usage examples.
+@end menu
+
+
+@node Realpath usage examples
+@subsection Realpath usage examples
+
+@opindex --relative-to
+@opindex --relative-base
+
+By default, @command{realpath} prints the absolute file name of given files
+(symlinks are resolved, @file{words} is resolved to @file{american-english}):
+
+@example
+@group
+cd /home/user
+realpath /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+@result{} /usr/bin/sort
+@result{} /tmp/foo
+@result{} /usr/share/dict/american-english
+@result{} /home/user/1.txt
+@end group
+@end example
+
+With @option{--relative-to}, file names are printed relative to
+the given directory:
+
+@example
+@group
+realpath --relative-to=/usr/bin \
+         /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+@result{} sort
+@result{} ../../tmp/foo
+@result{} ../share/dict/american-english
+@result{} ../../home/user/1.txt
+@end group
+@end example
+
+With @option{--relative-base}, relative file names are printed @emph{if}
+the resolved file name is below the given base directory. For files outside the
+base directory absolute file names are printed:
+
+@example
+@group
+realpath --relative-base=/usr \
+         /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+@result{} bin/sort
+@result{} /tmp/foo
+@result{} share/dict/american-english
+@result{} /home/user/1.txt
+@end group
+@end example
+
+When both @option{--relative-to=DIR1} and @option{--relative-base=DIR2}
+are used, file names are printed relative to @var{dir1} @emph{if} they are
+located below @var{dir2}. If the files are not below @var{dir2}, they are
+printed as absolute file names:
+
+@example
+@group
+realpath --relative-to=/usr/bin --relative-base=/usr \
+         /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt
+@result{} sort
+@result{} /tmp/foo
+@result{} ../share/dict/american-english
+@result{} /home/user/1.txt
+@end group
+@end example
+
+When both @option{--relative-to=DIR1} and @option{--relative-base=DIR2}
+are used, @var{dir1} @emph{must} be a subdirectory of @var{dir2}. Otherwise,
+@command{realpath} prints absolutes file names.
+
+
+@node Working context
+@chapter Working context
+
+@cindex working context
+@cindex commands for printing the working context
+
+This section describes commands that display or alter the context in
+which you are working: the current directory, the terminal settings, and
+so forth.  See also the user-related commands in the next section.
+
+@menu
+* pwd invocation::              Print working directory.
+* stty invocation::             Print or change terminal characteristics.
+* printenv invocation::         Print environment variables.
+* tty invocation::              Print file name of terminal on standard input.
+@end menu
+
+
+@node pwd invocation
+@section @command{pwd}: Print working directory
+
+@pindex pwd
+@cindex print name of current directory
+@cindex current working directory, printing
+@cindex working directory, printing
+
+
+@command{pwd} prints the name of the current directory.  Synopsis:
+
+@example
+pwd [@var{option}]@dots{}
+@end example
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+@item -L
+@itemx --logical
+@opindex -L
+@opindex --logical
+If the contents of the environment variable @env{PWD} provide an
+absolute name of the current directory with no @samp{.} or @samp{..}
+components, but possibly with symbolic links, then output those
+contents.  Otherwise, fall back to default @option{-P} handling.
+
+@item -P
+@itemx --physical
+@opindex -P
+@opindex --physical
+Print a fully resolved name for the current directory.  That is, all
+components of the printed name will be actual directory names -- none
+will be symbolic links.
+@end table
+
+@cindex symbolic links and @command{pwd}
+If @option{-L} and @option{-P} are both given, the last one takes
+precedence.  If neither option is given, then this implementation uses
+@option{-P} as the default unless the @env{POSIXLY_CORRECT}
+environment variable is set.
+
+@mayConflictWithShellBuiltIn{pwd}
+
+@exitstatus
+
+
+@node stty invocation
+@section @command{stty}: Print or change terminal characteristics
+
+@pindex stty
+@cindex change or print terminal settings
+@cindex terminal settings
+@cindex line settings of terminal
+
+@command{stty} prints or changes terminal characteristics, such as baud rate.
+Synopses:
+
+@example
+stty [@var{option}] [@var{setting}]@dots{}
+stty [@var{option}]
+@end example
+
+If given no line settings, @command{stty} prints the baud rate, line
+discipline number (on systems that support it), and line settings
+that have been changed from the values set by @samp{stty sane}.
+By default, mode reading and setting are performed on the tty line
+connected to standard input, although this can be modified by the
+@option{--file} option.
+
+@command{stty} accepts many non-option arguments that change aspects of
+the terminal line operation, as described below.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+@item -a
+@itemx --all
+@opindex -a
+@opindex --all
+Print all current settings in human-readable form.  This option may not
+be used in combination with any line settings.
+
+@item -F @var{device}
+@itemx --file=@var{device}
+@opindex -F
+@opindex --file
+Set the line opened by the file name specified in @var{device} instead of
+the tty line connected to standard input.  This option is necessary
+because opening a POSIX tty requires use of the
+@code{O_NONDELAY} flag to prevent a POSIX tty from blocking
+until the carrier detect line is high if
+the @code{clocal} flag is not set.  Hence, it is not always possible
+to allow the shell to open the device in the traditional manner.
+
+@item -g
+@itemx --save
+@opindex -g
+@opindex --save
+@cindex machine-readable @command{stty} output
+Print all current settings in a form that can be used as an argument to
+another @command{stty} command to restore the current settings.  This option
+may not be used in combination with any line settings.
+
+@end table
+
+Many settings can be turned off by preceding them with a @samp{-}.
+Such arguments are marked below with ``May be negated'' in their
+description.  The descriptions themselves refer to the positive
+case, that is, when @emph{not} negated (unless stated otherwise,
+of course).
+
+Some settings are not available on all POSIX systems, since they use
+extensions.  Such arguments are marked below with
+``Non-POSIX'' in their description.  On non-POSIX
+systems, those or other settings also may not
+be available, but it's not feasible to document all the variations: just
+try it and see.
+
+@command{stty} is installed only on platforms with the POSIX terminal
+interface, so portable scripts should not rely on its existence on
+non-POSIX platforms.
+
+@exitstatus
+
+@menu
+* Control::                     Control settings
+* Input::                       Input settings
+* Output::                      Output settings
+* Local::                       Local settings
+* Combination::                 Combination settings
+* Characters::                  Special characters
+* Special::                     Special settings
+@end menu
+
+
+@node Control
+@subsection Control settings
+
+@cindex control settings
+Control settings:
+
+@table @samp
+@item parenb
+@opindex parenb
+@cindex two-way parity
+Generate parity bit in output and expect parity bit in input.
+May be negated.
+
+@item parodd
+@opindex parodd
+@cindex odd parity
+@cindex even parity
+Set odd parity (even if negated).  May be negated.
+
+@item cmspar
+@opindex cmspar
+@cindex constant parity
+@cindex stick parity
+@cindex mark parity
+@cindex space parity
+Use "stick" (mark/space) parity.  If parodd is set, the parity bit is
+always 1; if parodd is not set, the parity bit is always zero.
+Non-POSIX@.  May be negated.
+
+@item cs5
+@itemx cs6
+@itemx cs7
+@itemx cs8
+@opindex cs@var{n}
+@cindex character size
+@cindex eight-bit characters
+Set character size to 5, 6, 7, or 8 bits.
+
+@item hup
+@itemx hupcl
+@opindex hup[cl]
+Send a hangup signal when the last process closes the tty.  May be
+negated.
+
+@item cstopb
+@opindex cstopb
+@cindex stop bits
+Use two stop bits per character (one if negated).  May be negated.
+
+@item cread
+@opindex cread
+Allow input to be received.  May be negated.
+
+@item clocal
+@opindex clocal
+@cindex modem control
+Disable modem control signals.  May be negated.
+
+@item crtscts
+@opindex crtscts
+@cindex hardware flow control
+@cindex flow control, hardware
+@cindex RTS/CTS flow control
+Enable RTS/CTS flow control.  Non-POSIX@.  May be negated.
+
+@item cdtrdsr
+@opindex cdtrdsr
+@cindex hardware flow control
+@cindex flow control, hardware
+@cindex DTR/DSR flow control
+Enable DTR/DSR flow control. Non-POSIX@.  May be negated.
+@end table
+
+
+@node Input
+@subsection Input settings
+
+@cindex input settings
+These settings control operations on data received from the terminal.
+
+@table @samp
+@item ignbrk
+@opindex ignbrk
+@cindex breaks, ignoring
+Ignore break characters.  May be negated.
+
+@item brkint
+@opindex brkint
+@cindex breaks, cause interrupts
+Make breaks cause an interrupt signal.  May be negated.
+
+@item ignpar
+@opindex ignpar
+@cindex parity, ignoring
+Ignore characters with parity errors.  May be negated.
+
+@item parmrk
+@opindex parmrk
+@cindex parity errors, marking
+Mark parity errors (with a 255-0-character sequence).  May be negated.
+
+@item inpck
+@opindex inpck
+Enable input parity checking.  May be negated.
+
+@item istrip
+@opindex istrip
+@cindex eight-bit input
+Clear high (8th) bit of input characters.  May be negated.
+
+@item inlcr
+@opindex inlcr
+@cindex newline, translating to return
+Translate newline to carriage return.  May be negated.
+
+@item igncr
+@opindex igncr
+@cindex return, ignoring
+Ignore carriage return.  May be negated.
+
+@item icrnl
+@opindex icrnl
+@cindex return, translating to newline
+Translate carriage return to newline.  May be negated.
+
+@item iutf8
+@opindex iutf8
+@cindex input encoding, UTF-8
+Assume input characters are UTF-8 encoded.  May be negated.
+
+@item ixon
+@opindex ixon
+@kindex C-s/C-q flow control
+@cindex XON/XOFF flow control
+Enable XON/XOFF flow control (that is, @kbd{Ctrl-S}/@kbd{Ctrl-Q}).  May
+be negated.
+
+@item ixoff
+@itemx tandem
+@opindex ixoff
+@opindex tandem
+@cindex software flow control
+@cindex flow control, software
+Enable sending of @code{stop} character when the system input buffer
+is almost full, and @code{start} character when it becomes almost
+empty again.  May be negated.
+
+@item iuclc
+@opindex iuclc
+@cindex uppercase, translating to lowercase
+Translate uppercase characters to lowercase.  Non-POSIX@.  May be
+negated.  Note ilcuc is not implemented, as one would not be able to issue
+almost any (lowercase) Unix command, after invoking it.
+
+@item ixany
+@opindex ixany
+Allow any character to restart output (only the start character
+if negated).  Non-POSIX@.  May be negated.
+
+@item imaxbel
+@opindex imaxbel
+@cindex beeping at input buffer full
+Enable beeping and not flushing input buffer if a character arrives
+when the input buffer is full.  Non-POSIX@.  May be negated.
+@end table
+
+
+@node Output
+@subsection Output settings
+
+@cindex output settings
+These settings control operations on data sent to the terminal.
+
+@table @samp
+@item opost
+@opindex opost
+Postprocess output.  May be negated.
+
+@item olcuc
+@opindex olcuc
+@cindex lowercase, translating to output
+Translate lowercase characters to uppercase.  Non-POSIX@.  May be
+negated.  (Note ouclc is not currently implemented.)
+
+@item ocrnl
+@opindex ocrnl
+@cindex return, translating to newline
+Translate carriage return to newline.  Non-POSIX@.  May be negated.
+
+@item onlcr
+@opindex onlcr
+@cindex newline, translating to crlf
+Translate newline to carriage return-newline.  Non-POSIX@.  May be
+negated.
+
+@item onocr
+@opindex onocr
+Do not print carriage returns in the first column.  Non-POSIX@.
+May be negated.
+
+@item onlret
+@opindex onlret
+Newline performs a carriage return.  Non-POSIX@.  May be negated.
+
+@item ofill
+@opindex ofill
+@cindex pad instead of timing for delaying
+Use fill (padding) characters instead of timing for delays.
+Non-POSIX@.
+May be negated.
+
+@item ofdel
+@opindex ofdel
+@cindex pad character
+Use ASCII DEL characters for fill instead of
+ASCII NUL characters.  Non-POSIX@.
+May be negated.
+
+@item nl1
+@itemx nl0
+@opindex nl@var{n}
+Newline delay style.  Non-POSIX.
+
+@item cr3
+@itemx cr2
+@itemx cr1
+@itemx cr0
+@opindex cr@var{n}
+Carriage return delay style.  Non-POSIX.
+
+@item tab3
+@itemx tab2
+@itemx tab1
+@itemx tab0
+@opindex tab@var{n}
+Horizontal tab delay style.  Non-POSIX.
+
+@item bs1
+@itemx bs0
+@opindex bs@var{n}
+Backspace delay style.  Non-POSIX.
+
+@item vt1
+@itemx vt0
+@opindex vt@var{n}
+Vertical tab delay style.  Non-POSIX.
+
+@item ff1
+@itemx ff0
+@opindex ff@var{n}
+Form feed delay style.  Non-POSIX.
+@end table
+
+
+@node Local
+@subsection Local settings
+
+@cindex local settings
+
+@table @samp
+@item isig
+@opindex isig
+Enable @code{interrupt}, @code{quit}, and @code{suspend} special
+characters.  May be negated.
+
+@item icanon
+@opindex icanon
+Enable @code{erase}, @code{kill}, @code{werase}, and @code{rprnt}
+special characters.  May be negated.
+
+@item iexten
+@opindex iexten
+Enable non-POSIX special characters.  May be negated.
+
+@item echo
+@opindex echo
+Echo input characters.  May be negated.
+
+@item echoe
+@itemx crterase
+@opindex echoe
+@opindex crterase
+Echo @code{erase} characters as backspace-space-backspace.  May be
+negated.
+
+@item echok
+@opindex echok
+@cindex newline echoing after @code{kill}
+Echo a newline after a @code{kill} character.  May be negated.
+
+@item echonl
+@opindex echonl
+@cindex newline, echoing
+Echo newline even if not echoing other characters.  May be negated.
+
+@item noflsh
+@opindex noflsh
+@cindex flushing, disabling
+Disable flushing after @code{interrupt} and @code{quit} special
+characters.  May be negated.
+
+@item xcase
+@opindex xcase
+@cindex case translation
+Enable input and output of uppercase characters by preceding their
+lowercase equivalents with @samp{\}, when @code{icanon} is set.
+Non-POSIX@.  May be negated.
+
+@item tostop
+@opindex tostop
+@cindex background jobs, stopping at terminal write
+Stop background jobs that try to write to the terminal.  Non-POSIX@.
+May be negated.
+
+@item echoprt
+@itemx prterase
+@opindex echoprt
+@opindex prterase
+Echo erased characters backward, between @samp{\} and @samp{/}.
+Non-POSIX@.  May be negated.
+
+@item echoctl
+@itemx ctlecho
+@opindex echoctl
+@opindex ctlecho
+@cindex control characters, using @samp{^@var{c}}
+@cindex hat notation for control characters
+Echo control characters in hat notation (@samp{^@var{c}}) instead
+of literally.  Non-POSIX@.  May be negated.
+
+@item echoke
+@itemx crtkill
+@opindex echoke
+@opindex crtkill
+Echo the @code{kill} special character by erasing each character on
+the line as indicated by the @code{echoprt} and @code{echoe} settings,
+instead of by the @code{echoctl} and @code{echok} settings.
+Non-POSIX@.
+May be negated.
+
+@item extproc
+@opindex extproc
+Enable @samp{LINEMODE}, which is used to avoid echoing
+each character over high latency links.  See also
+@uref{https://tools.ietf.org/search/rfc1116, Internet RFC 1116}.
+Non-POSIX@.
+May be negated.
+
+@item flusho
+@opindex flusho
+Discard output.
+Note this setting is currently ignored on GNU/Linux systems.
+Non-POSIX@.
+May be negated.
+@end table
+
+
+@node Combination
+@subsection Combination settings
+
+@cindex combination settings
+Combination settings:
+
+@table @samp
+@item evenp
+@opindex evenp
+@itemx parity
+@opindex parity
+Same as @code{parenb -parodd cs7}.  May be negated.  If negated, same
+as @code{-parenb cs8}.
+
+@item oddp
+@opindex oddp
+Same as @code{parenb parodd cs7}.  May be negated.  If negated, same
+as @code{-parenb cs8}.
+
+@item nl
+@opindex nl
+Same as @code{-icrnl -onlcr}.  May be negated.  If negated, same as
+@code{icrnl -inlcr -igncr onlcr -ocrnl -onlret}.
+
+@item ek
+@opindex ek
+Reset the @code{erase} and @code{kill} special characters to their default
+values.
+
+@item sane
+@opindex sane
+Same as:
+
+@c This is too long to write inline.
+@example
+cread -ignbrk brkint -inlcr -igncr icrnl
+icanon iexten echo echoe echok -echonl -noflsh
+-ixoff -iutf8 -iuclc -ixany imaxbel -xcase -olcuc -ocrnl
+opost -ofill onlcr -onocr -onlret nl0 cr0 tab0 bs0 vt0 ff0
+isig -tostop -ofdel -echoprt echoctl echoke -extproc
+@end example
+
+@noindent
+and also sets all special characters to their default values.
+
+@item cooked
+@opindex cooked
+Same as @code{brkint ignpar istrip icrnl ixon opost isig icanon}, plus
+sets the @code{eof} and @code{eol} characters to their default values
+if they are the same as the @code{min} and @code{time} characters.
+May be negated.  If negated, same as @code{raw}.
+
+@item raw
+@opindex raw
+Same as:
+
+@example
+-ignbrk -brkint -ignpar -parmrk -inpck -istrip
+-inlcr -igncr -icrnl -ixon -ixoff -icanon -opost
+-isig -iuclc -ixany -imaxbel -xcase min 1 time 0
+@end example
+
+@noindent
+May be negated.  If negated, same as @code{cooked}.
+
+@item cbreak
+@opindex cbreak
+Same as @option{-icanon}.  May be negated.  If negated, same as
+@code{icanon}.
+
+@item pass8
+@opindex pass8
+@cindex eight-bit characters
+Same as @code{-parenb -istrip cs8}.  May be negated.  If negated,
+same as @code{parenb istrip cs7}.
+
+@item litout
+@opindex litout
+Same as @option{-parenb -istrip -opost cs8}.  May be negated.
+If negated, same as @code{parenb istrip opost cs7}.
+
+@item decctlq
+@opindex decctlq
+Same as @option{-ixany}.  Non-POSIX@.  May be negated.
+
+@item tabs
+@opindex tabs
+Same as @code{tab0}.  Non-POSIX@.  May be negated.  If negated, same
+as @code{tab3}.
+
+@item lcase
+@itemx LCASE
+@opindex lcase
+@opindex LCASE
+Same as @code{xcase iuclc olcuc}.  Non-POSIX@.  May be negated.
+(Used for terminals with uppercase characters only.)
+
+@item crt
+@opindex crt
+Same as @code{echoe echoctl echoke}.
+
+@item dec
+@opindex dec
+Same as @code{echoe echoctl echoke -ixany intr ^C erase ^? kill C-u}.
+@end table
+
+
+@node Characters
+@subsection Special characters
+
+@cindex special characters
+@cindex characters, special
+
+The special characters' default values vary from system to system.
+They are set with the syntax @samp{name value}, where the names are
+listed below and the value can be given either literally, in hat
+notation (@samp{^@var{c}}), or as an integer which may start with
+@samp{0x} to indicate hexadecimal, @samp{0} to indicate octal, or
+any other digit to indicate decimal.
+
+@cindex disabling special characters
+@kindex u@r{, and disabling special characters}
+For GNU stty, giving a value of @code{^-} or @code{undef} disables that
+special character.  (This is incompatible with Ultrix @command{stty},
+which uses  a value of @samp{u} to disable a special character.  GNU
+@command{stty} treats a value @samp{u} like any other, namely to set that
+special character to @key{U}.)
+
+@table @samp
+
+@item intr
+@opindex intr
+Send an interrupt signal.
+
+@item quit
+@opindex quit
+Send a quit signal.
+
+@item erase
+@opindex erase
+Erase the last character typed.
+
+@item kill
+@opindex kill
+Erase the current line.
+
+@item eof
+@opindex eof
+Send an end of file (terminate the input).
+
+@item eol
+@opindex eol
+End the line.
+
+@item eol2
+@opindex eol2
+Alternate character to end the line.  Non-POSIX.
+
+@item discard
+@opindex discard
+@opindex flush
+Alternate character to toggle discarding of output.  Non-POSIX.
+
+@item swtch
+@opindex swtch
+Switch to a different shell layer.  Non-POSIX.
+
+@item status
+@opindex status
+Send an info signal.  Not currently supported on GNU/Linux.  Non-POSIX.
+
+@item start
+@opindex start
+Restart the output after stopping it.
+
+@item stop
+@opindex stop
+Stop the output.
+
+@item susp
+@opindex susp
+Send a terminal stop signal.
+
+@item dsusp
+@opindex dsusp
+Send a terminal stop signal after flushing the input.  Non-POSIX.
+
+@item rprnt
+@opindex rprnt
+Redraw the current line.  Non-POSIX.
+
+@item werase
+@opindex werase
+Erase the last word typed.  Non-POSIX.
+
+@item lnext
+@opindex lnext
+Enter the next character typed literally, even if it is a special
+character.  Non-POSIX.
+@end table
+
+
+@node Special
+@subsection Special settings
+
+@cindex special settings
+
+@table @samp
+@item min @var{n}
+@opindex min
+Set the minimum number of characters that will satisfy a read until
+the time value has expired, when @option{-icanon} is set.
+
+@item time @var{n}
+@opindex time
+Set the number of tenths of a second before reads time out if the minimum
+number of characters have not been read, when @option{-icanon} is set.
+
+@item ispeed @var{n}
+@opindex ispeed
+Set the input speed to @var{n}.
+
+@item ospeed @var{n}
+@opindex ospeed
+Set the output speed to @var{n}.
+
+@item rows @var{n}
+@opindex rows
+Tell the tty kernel driver that the terminal has @var{n} rows.
+Non-POSIX.
+
+@item cols @var{n}
+@itemx columns @var{n}
+@opindex cols
+@opindex columns
+Tell the kernel that the terminal has @var{n} columns.  Non-POSIX.
+
+@item drain
+@opindex drain
+@cindex nonblocking @command{stty} setting
+Apply settings after first waiting for pending output to be transmitted.
+This is enabled by default for GNU @command{stty}.
+Note this is treated as an option rather than a line setting,
+and will follow the option processing rules described in the summary above.
+It is useful to disable this option
+in cases where the system may be in a state where serial transmission
+is not possible.
+For example, if the system has received the @samp{DC3} character
+with @code{ixon} (software flow control) enabled, then @command{stty} would
+block without @code{-drain} being specified.
+May be negated. Non-POSIX.
+
+@item size
+@opindex size
+@vindex LINES
+@vindex COLUMNS
+Print the number of rows and columns that the kernel thinks the
+terminal has.  (Systems that don't support rows and columns in the kernel
+typically use the environment variables @env{LINES} and @env{COLUMNS}
+instead; however, GNU @command{stty} does not know anything about them.)
+Non-POSIX.
+
+@item line @var{n}
+@opindex line
+Use line discipline @var{n}.  Non-POSIX.
+
+@item speed
+@opindex speed
+Print the terminal speed.
+
+@item @var{n}
+@cindex baud rate, setting
+Set the input and output speeds to @var{n}.  @var{n} can be one of: 0
+50 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 19200
+38400 @code{exta} @code{extb}.  @code{exta} is the same as 19200;
+@code{extb} is the same as 38400.  Many systems, including GNU/Linux,
+support higher speeds.  The @command{stty} command includes support
+for speeds of
+57600,
+115200,
+230400,
+460800,
+500000,
+576000,
+921600,
+1000000,
+1152000,
+1500000,
+2000000,
+2500000,
+3000000,
+3500000,
+or
+4000000 where the system supports these.
+0 hangs up the line if @option{-clocal} is set.
+@end table
+
+
+@node printenv invocation
+@section @command{printenv}: Print all or some environment variables
+
+@pindex printenv
+@cindex printing all or some environment variables
+@cindex environment variables, printing
+
+@command{printenv} prints environment variable values.  Synopsis:
+
+@example
+printenv [@var{option}] [@var{variable}]@dots{}
+@end example
+
+If no @var{variable}s are specified, @command{printenv} prints the value of
+every environment variable.  Otherwise, it prints the value of each
+@var{variable} that is set, and nothing for those that are not set.
+
+The program accepts the following option.  Also see @ref{Common options}.
+
+@table @samp
+
+@optNull
+
+@end table
+
+@cindex exit status of @command{printenv}
+Exit status:
+
+@display
+0 if all variables specified were found
+1 if at least one specified variable was not found
+2 if a write error occurred
+@end display
+
+
+@node tty invocation
+@section @command{tty}: Print file name of terminal on standard input
+
+@pindex tty
+@cindex print terminal file name
+@cindex terminal file name, printing
+
+@command{tty} prints the file name of the terminal connected to its standard
+input.  It prints @samp{not a tty} if standard input is not a terminal.
+Synopsis:
+
+@example
+tty [@var{option}]@dots{}
+@end example
+
+The program accepts the following option.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -s
+@itemx --silent
+@itemx --quiet
+@opindex -s
+@opindex --silent
+@opindex --quiet
+Print nothing; only return an exit status.
+
+@end table
+
+@cindex exit status of @command{tty}
+Exit status:
+
+@display
+0 if standard input is a terminal
+1 if standard input is a non-terminal file
+2 if given incorrect arguments
+3 if a write error occurs
+@end display
+
+
+@node User information
+@chapter User information
+
+@cindex user information, commands for
+@cindex commands for printing user information
+
+This section describes commands that print user-related information:
+logins, groups, and so forth.
+
+@menu
+* id invocation::               Print user identity.
+* logname invocation::          Print current login name.
+* whoami invocation::           Print effective user ID.
+* groups invocation::           Print group names a user is in.
+* users invocation::            Print login names of users currently logged in.
+* who invocation::              Print who is currently logged in.
+@end menu
+
+
+@node id invocation
+@section @command{id}: Print user identity
+
+@pindex id
+@cindex real user and group IDs, printing
+@cindex effective user and group IDs, printing
+@cindex printing real and effective user and group IDs
+
+@command{id} prints information about the given user, or the process
+running it if no user is specified.  Synopsis:
+
+@example
+id [@var{option}]@dots{} [@var{user}]@dots{}
+@end example
+
+@var{user} can be either a user ID or a name, with name look-up
+taking precedence unless the ID is specified with a leading @samp{+}.
+@xref{Disambiguating names and IDs}.
+
+@vindex POSIXLY_CORRECT
+By default, it prints the real user ID, real group ID, effective user ID
+if different from the real user ID, effective group ID if different from
+the real group ID, and supplemental group IDs.
+In addition, if SELinux
+is enabled and the @env{POSIXLY_CORRECT} environment variable is not set,
+then print @samp{context=@var{c}}, where @var{c} is the security context.
+
+Each of these numeric values is preceded by an identifying string and
+followed by the corresponding user or group name in parentheses.
+
+The options cause @command{id} to print only part of the above information.
+Also see @ref{Common options}.
+
+@table @samp
+@item -g
+@itemx --group
+@opindex -g
+@opindex --group
+Print only the group ID.
+
+@item -G
+@itemx --groups
+@opindex -G
+@opindex --groups
+Print only the group ID and the supplementary groups.
+
+@item -n
+@itemx --name
+@opindex -n
+@opindex --name
+Print the user or group name instead of the ID number.  Requires
+@option{-u}, @option{-g}, or @option{-G}.
+
+@item -r
+@itemx --real
+@opindex -r
+@opindex --real
+Print the real, instead of effective, user or group ID@.  Requires
+@option{-u}, @option{-g}, or @option{-G}.
+
+@item -u
+@itemx --user
+@opindex -u
+@opindex --user
+Print only the user ID.
+
+@item -Z
+@itemx --context
+@opindex -Z
+@opindex --context
+@cindex SELinux
+@cindex security context
+Print only the security context of the process, which is generally
+the user's security context inherited from the parent process.
+If neither SELinux or SMACK is enabled then print a warning and
+set the exit status to 1.
+
+@item -z
+@itemx --zero
+@opindex -z
+@opindex --zero
+Delimit output items with ASCII NUL characters.
+This option is not permitted when using the default format.
+When multiple users are specified, and the @option{--groups} option
+is also in effect, groups are delimited with a single NUL character,
+while users are delimited with two NUL characters.
+
+Example:
+@example
+$ id -Gn --zero
+users <NUL> devs <NUL>
+@end example
+
+@end table
+
+@macro primaryAndSupplementaryGroups{cmd,arg}
+Primary and supplementary groups for a process are normally inherited
+from its parent and are usually unchanged since login.  This means
+that if you change the group database after logging in, @command{\cmd\}
+will not reflect your changes within your existing login session.
+Running @command{\cmd\} with a \arg\ causes the user and group
+database to be consulted afresh, and so will give a different result.
+@end macro
+@primaryAndSupplementaryGroups{id,user argument}
+
+@exitstatus
+
+@node logname invocation
+@section @command{logname}: Print current login name
+
+@pindex logname
+@cindex printing user's login name
+@cindex login name, printing
+@cindex user name, printing
+
+@flindex utmp
+@command{logname} prints the calling user's name, as found in a
+system-maintained file (often @file{/var/run/utmp} or
+@file{/etc/utmp}), and exits with a status of 0.  If there is no entry
+for the calling process, @command{logname} prints
+an error message and exits with a status of 1.
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+@exitstatus
+
+
+@node whoami invocation
+@section @command{whoami}: Print effective user name
+
+@pindex whoami
+@cindex effective user name, printing
+@cindex printing the effective user ID
+
+@command{whoami} prints the user name associated with the current
+effective user ID@.  It is equivalent to the command @samp{id -un}.
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+@exitstatus
+
+
+@node groups invocation
+@section @command{groups}: Print group names a user is in
+
+@pindex groups
+@cindex printing groups a user is in
+@cindex supplementary groups, printing
+
+@command{groups} prints the names of the primary and any supplementary
+groups for each given @var{username}, or the current process if no names
+are given.  If more than one name is given, the name of each user is
+printed before
+the list of that user's groups and the user name is separated from the
+group list by a colon.  Synopsis:
+
+@example
+groups [@var{username}]@dots{}
+@end example
+
+The group lists are equivalent to the output of the command @samp{id -Gn}.
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+@primaryAndSupplementaryGroups{groups,list of users}
+
+@exitstatus
+
+@node users invocation
+@section @command{users}: Print login names of users currently logged in
+
+@pindex users
+@cindex printing current usernames
+@cindex usernames, printing current
+
+@cindex login sessions, printing users with
+@command{users} prints on a single line a blank-separated list of user
+names of users currently logged in to the current host.  Each user name
+corresponds to a login session, so if a user has more than one login
+session, that user's name will appear the same number of times in the
+output.  Synopsis:
+
+@example
+users [@var{file}]
+@end example
+
+@flindex utmp
+@flindex wtmp
+With no @var{file} argument, @command{users} extracts its information from
+a system-maintained file (often @file{/var/run/utmp} or
+@file{/etc/utmp}).  If a file argument is given, @command{users} uses
+that file instead.  A common choice is @file{/var/log/wtmp}.
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+The @command{users} command is installed only on platforms with the
+POSIX @code{<utmpx.h>} include file or equivalent, so portable scripts
+should not rely on its existence on non-POSIX platforms.
+
+@exitstatus
+
+
+@node who invocation
+@section @command{who}: Print who is currently logged in
+
+@pindex who
+@cindex printing current user information
+@cindex information, about current users
+
+@command{who} prints information about users who are currently logged on.
+Synopsis:
+
+@example
+@command{who} [@var{option}] [@var{file}] [am i]
+@end example
+
+@cindex terminal lines, currently used
+@cindex login time
+@cindex remote hostname
+If given no non-option arguments, @command{who} prints the following
+information for each user currently logged on: login name, terminal
+line, login time, and remote hostname or X display.
+
+@flindex utmp
+@flindex wtmp
+If given one non-option argument, @command{who} uses that instead of
+a default system-maintained file (often @file{/var/run/utmp} or
+@file{/etc/utmp}) as the name of the file containing the record of
+users logged on.  @file{/var/log/wtmp} is commonly given as an argument
+to @command{who} to look at who has previously logged on.
+
+@opindex am i
+@opindex who am i
+If given two non-option arguments, @command{who} prints only the entry
+for the user running it (determined from its standard input), preceded
+by the hostname.  Traditionally, the two arguments given are @samp{am
+i}, as in @samp{who am i}.
+
+@vindex TZ
+Timestamps are listed according to the time zone rules specified by
+the @env{TZ} environment variable, or by the system default rules if
+@env{TZ} is not set.  @xref{TZ Variable,, Specifying the Time Zone
+with @env{TZ}, libc, The GNU C Library Reference Manual}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -a
+@itemx --all
+@opindex -a
+@opindex --all
+Same as @samp{-b -d --login -p -r -t -T -u}.
+
+@item -b
+@itemx --boot
+@opindex -b
+@opindex --boot
+Print the date and time of last system boot.
+
+@item -d
+@itemx --dead
+@opindex -d
+@opindex --dead
+Print information corresponding to dead processes.
+
+@item -H
+@itemx --heading
+@opindex -H
+@opindex --heading
+Print a line of column headings.
+
+@item -l
+@itemx --login
+@opindex -l
+@opindex --login
+List only the entries that correspond to processes via which the
+system is waiting for a user to login.  The user name is always @samp{LOGIN}.
+
+@item --lookup
+@opindex --lookup
+Attempt to canonicalize hostnames found in utmp through a DNS lookup.  This
+is not the default because it can cause significant delays on systems with
+automatic dial-up internet access.
+
+@item -m
+@opindex -m
+Same as @samp{who am i}.
+
+@item -p
+@itemx --process
+@opindex -p
+@opindex --process
+List active processes spawned by init.
+
+@item -q
+@itemx --count
+@opindex -q
+@opindex --count
+Print only the login names and the number of users logged on.
+Overrides all other options.
+
+@item -r
+@itemx --runlevel
+@opindex -r
+@opindex --runlevel
+Print the current (and maybe previous) run-level of the init process.
+
+@item -s
+@opindex -s
+Ignored; for compatibility with other versions of @command{who}.
+
+@item -t
+@itemx --time
+@opindex -t
+@opindex --time
+Print last system clock change.
+
+@item -u
+@opindex -u
+@cindex idle time
+After the login time, print the number of hours and minutes that the
+user has been idle.  @samp{.} means the user was active in the last minute.
+@samp{old} means the user has been idle for more than 24 hours.
+
+@item -w
+@itemx -T
+@itemx --mesg
+@itemx --message
+@itemx --writable
+@opindex -w
+@opindex -T
+@opindex --mesg
+@opindex --message
+@opindex --writable
+@cindex message status
+@pindex write@r{, allowed}
+After each login name print a character indicating the user's message status:
+
+@display
+@samp{+} allowing @code{write} messages
+@samp{-} disallowing @code{write} messages
+@samp{?} cannot find terminal device
+@end display
+
+@end table
+
+The @command{who} command is installed only on platforms with the
+POSIX @code{<utmpx.h>} include file or equivalent, so portable scripts
+should not rely on its existence on non-POSIX platforms.
+
+@exitstatus
+
+
+@node System context
+@chapter System context
+
+@cindex system context
+@cindex context, system
+@cindex commands for system context
+
+This section describes commands that print or change system-wide
+information.
+
+@menu
+* date invocation::             Print or set system date and time.
+* arch invocation::             Print machine hardware name.
+* nproc invocation::            Print the number of processors.
+* uname invocation::            Print system information.
+* hostname invocation::         Print or set system name.
+* hostid invocation::           Print numeric host identifier.
+* uptime invocation::           Print system uptime and load.
+@end menu
+
+@node date invocation
+@section @command{date}: Print or set system date and time
+
+@pindex date
+@cindex time, printing or setting
+@cindex printing the current time
+
+Synopses:
+
+@example
+date [@var{option}]@dots{} [+@var{format}]
+date [-u|--utc|--universal] @c this avoids a newline in the output
+[ MMDDhhmm[[CC]YY][.ss] ]
+@end example
+
+The @command{date} command displays the date and time.
+With the @option{--set} (@option{-s}) option, or with
+@samp{MMDDhhmm[[CC]YY][.ss]},
+it sets the date and time.
+
+@vindex LC_TIME
+Invoking @command{date} with no @var{format} argument is equivalent to invoking
+it with a default format that depends on the @env{LC_TIME} locale category.
+In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'},
+so the output looks like @samp{Thu Jul @ 9 17:00:00 EDT 2020}.
+
+@vindex TZ
+Normally, @command{date} uses the time zone rules indicated by the
+@env{TZ} environment variable, or the system default rules if @env{TZ}
+is not set.  @xref{TZ Variable,, Specifying the Time Zone with
+@env{TZ}, libc, The GNU C Library Reference Manual}.
+
+@exitstatus
+
+@menu
+* Date format specifiers::         Used in @samp{date '+...'}
+* Setting the time::               Changing the system clock.
+* Options for date::               Instead of the current time.
+@detailmenu
+* Date input formats::             Specifying date strings.
+@end detailmenu
+* Examples of date::               Examples.
+@end menu
+
+@node Date format specifiers
+@subsection Specifying the format of @command{date} output
+
+@findex strftime @r{and @command{date}}
+@cindex time formats
+@cindex formatting times
+If given an argument that starts with a @samp{+}, @command{date} prints the
+current date and time (or the date and time specified by the
+@option{--date} option, see below) in the format defined by that argument,
+which is similar to that of the @code{strftime} function.  Except for
+conversion specifiers, which start with @samp{%}, characters in the
+format string are printed unchanged.  The conversion specifiers are
+described below.
+
+@menu
+* Time conversion specifiers::     %[HIklMNpPrRsSTXzZ]
+* Date conversion specifiers::     %[aAbBcCdDeFgGhjmuUVwWxyY]
+* Literal conversion specifiers::  %[%nt]
+* Padding and other flags::        Pad with zeros, spaces, etc.
+@end menu
+
+@node Time conversion specifiers
+@subsubsection Time conversion specifiers
+
+@cindex time conversion specifiers
+@cindex conversion specifiers, time
+
+@command{date} conversion specifiers related to times.
+
+@table @samp
+@item %H
+hour (@samp{00}@dots{}@samp{23})
+@item %I
+hour (@samp{01}@dots{}@samp{12})
+@item %k
+hour, space padded (@samp{ 0}@dots{}@samp{23}); equivalent to @samp{%_H}@.
+This is a GNU extension.
+@item %l
+hour, space padded (@samp{ 1}@dots{}@samp{12}); equivalent to @samp{%_I}@.
+This is a GNU extension.
+@item %M
+minute (@samp{00}@dots{}@samp{59})
+@item %N
+nanoseconds (@samp{000000000}@dots{}@samp{999999999}).
+This is a GNU extension.
+@item %p
+locale's equivalent of either @samp{AM} or @samp{PM};
+blank in many locales.
+Noon is treated as @samp{PM} and midnight as @samp{AM}.
+@item %P
+like @samp{%p}, except lower case.
+This is a GNU extension.
+@item %r
+locale's 12-hour clock time (e.g., @samp{11:11:04 PM})
+@item %R
+24-hour hour and minute.  Same as @samp{%H:%M}.
+@item %s
+@cindex Epoch, seconds since
+@cindex seconds since the Epoch
+@cindex beginning of time
+@cindex leap seconds
+seconds since the Epoch, i.e., since 1970-01-01 00:00 UTC@.
+Leap seconds are not counted unless leap second support is available.
+@xref{%s-examples}, for examples.
+This is a GNU extension.
+@item %S
+@cindex leap seconds
+second (@samp{00}@dots{}@samp{60}).
+This may be @samp{60} if leap seconds are supported.
+@item %T
+24-hour hour, minute, and second.  Same as @samp{%H:%M:%S}.
+@item %X
+locale's time representation (e.g., @samp{23:13:48})
+@item %z
+Four-digit numeric time zone, e.g., @samp{-0600} or @samp{+0530}, or
+@samp{-0000} if no
+time zone is determinable.  This value reflects the numeric time zone
+appropriate for the current time, using the time zone rules specified
+by the @env{TZ} environment variable.  A time zone is not determinable if
+its numeric offset is zero and its abbreviation begins with @samp{-}.
+The time (and optionally, the time zone rules) can be overridden
+by the @option{--date} option.
+@item %:z
+Numeric time zone with @samp{:}, e.g., @samp{-06:00} or
+@samp{+05:30}), or @samp{-00:00} if no time zone is determinable.
+This is a GNU extension.
+@item %::z
+Numeric time zone to the nearest second with @samp{:} (e.g.,
+@samp{-06:00:00} or @samp{+05:30:00}), or @samp{-00:00:00} if no time zone is
+determinable.
+This is a GNU extension.
+@item %:::z
+Numeric time zone with @samp{:} using the minimum necessary precision
+(e.g., @samp{-06}, @samp{+05:30}, or @samp{-04:56:02}), or @samp{-00} if
+no time zone is determinable.
+This is a GNU extension.
+@item %Z
+alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no
+time zone is determinable.  See @samp{%z} for how it is determined.
+@end table
+
+
+@node Date conversion specifiers
+@subsubsection Date conversion specifiers
+
+@cindex date conversion specifiers
+@cindex conversion specifiers, date
+
+@command{date} conversion specifiers related to dates.
+
+@table @samp
+@item %a
+locale's abbreviated weekday name (e.g., @samp{Sun})
+@item %A
+locale's full weekday name, variable length (e.g., @samp{Sunday})
+@item %b
+locale's abbreviated month name (e.g., @samp{Jan})
+@item %B
+locale's full month name, variable length (e.g., @samp{January})
+@item %c
+locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2020})
+@item %C
+century.  This is like @samp{%Y}, except the last two digits are omitted.
+For example, it is @samp{20} if @samp{%Y} is @samp{2019},
+and is @samp{-0} if @samp{%Y} is @samp{-001}.
+It is normally at least two characters, but it may be more.
+@item %d
+day of month (e.g., @samp{01})
+@item %D
+date; same as @samp{%m/%d/%y}
+@item %e
+day of month, space padded; same as @samp{%_d}
+@item %F
+full date in ISO 8601 format; like @samp{%+4Y-%m-%d}
+except that any flags or field width override the @samp{+}
+and (after subtracting 6) the @samp{4}.
+This is a good choice for a date format, as it is standard and
+is easy to sort in the usual case where years are in the range
+0000@dots{}9999.
+@item %g
+year corresponding to the ISO week number, but without the century
+(range @samp{00} through @samp{99}).  This has the same format and value
+as @samp{%y}, except that if the ISO week number (see
+@samp{%V}) belongs
+to the previous or next year, that year is used instead.
+@item %G
+year corresponding to the ISO week number.  This has the
+same format and value as @samp{%Y}, except that if the ISO
+week number (see
+@samp{%V}) belongs to the previous or next year, that year is used
+instead.
+It is normally useful only if @samp{%V} is also used;
+for example, the format @samp{%G-%m-%d} is probably a mistake,
+since it combines the ISO week number year with the conventional month and day.
+@item %h
+same as @samp{%b}
+@item %j
+day of year (@samp{001}@dots{}@samp{366})
+@item %m
+month (@samp{01}@dots{}@samp{12})
+@item %q
+quarter of year (@samp{1}@dots{}@samp{4})
+@item %u
+day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday
+@item %U
+week number of year, with Sunday as the first day of the week
+(@samp{00}@dots{}@samp{53}).
+Days in a new year preceding the first Sunday are in week zero.
+@item %V
+ISO week number, that is, the
+week number of year, with Monday as the first day of the week
+(@samp{01}@dots{}@samp{53}).
+If the week containing January 1 has four or more days in
+the new year, then it is considered week 1; otherwise, it is week 53 of
+the previous year, and the next week is week 1.  (See the ISO 8601
+standard.)
+@item %w
+day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday
+@item %W
+week number of year, with Monday as first day of week
+(@samp{00}@dots{}@samp{53}).
+Days in a new year preceding the first Monday are in week zero.
+@item %x
+locale's date representation (e.g., @samp{12/31/99})
+@item %y
+last two digits of year (@samp{00}@dots{}@samp{99})
+@item %Y
+year.  This is normally at least four characters, but it may be more.
+Year @samp{0000} precedes year @samp{0001}, and year @samp{-001}
+precedes year @samp{0000}.
+@end table
+
+
+@node Literal conversion specifiers
+@subsubsection Literal conversion specifiers
+
+@cindex literal conversion specifiers
+@cindex conversion specifiers, literal
+
+@command{date} conversion specifiers that produce literal strings.
+
+@table @samp
+@item %%
+a literal %
+@item %n
+a newline
+@item %t
+a horizontal tab
+@end table
+
+
+@node Padding and other flags
+@subsubsection Padding and other flags
+
+@cindex numeric field padding
+@cindex padding of numeric fields
+@cindex fields, padding numeric
+
+Unless otherwise specified, @command{date} normally pads numeric fields
+with zeros, so that, for
+example, numeric months are always output as two digits.
+Most numeric fields are padded on the left.
+However, nanoseconds are padded on the right since they are commonly
+used after decimal points in formats like @samp{%s.%-N}.
+Also, seconds since the Epoch are not padded
+since there is no natural width for them.
+
+The following optional flags can appear after the @samp{%}:
+
+@table @samp
+@item -
+(hyphen) Do not pad the field; useful if the output is intended for
+human consumption.
+This is a GNU extension.
+As a special case, @samp{%-N} outputs only enough trailing digits to
+not lose information, assuming that the timestamp's resolution is the
+same as the current hardware clock.  For example, if the hardware
+clock resolution is 1 microsecond, @samp{%s.%-N} outputs something
+like @samp{1640890100.395710}.
+
+@item _
+(underscore) Pad with spaces; useful if you need a fixed
+number of characters in the output, but zeros are too distracting.
+This is a GNU extension.
+@item 0
+(zero) Pad with zeros even if the conversion specifier
+would normally pad with spaces.
+@item +
+Pad with zeros, like @samp{0}.  In addition, precede any year number
+with @samp{+} if it exceeds 9999 or if its field width exceeds 4;
+similarly, precede any century number with @samp{+} if it exceeds 99
+or if its field width exceeds 2.  This supports ISO 8601 formats
+for dates far in the future; for example, the command @code{date
+--date=12019-02-25 +%+13F} outputs the string @samp{+012019-02-25}.
+@item ^
+Use upper case characters if possible.
+This is a GNU extension.
+@item #
+Use opposite case characters if possible.
+A field that is normally upper case becomes lower case, and vice versa.
+This is a GNU extension.
+@end table
+
+@noindent
+Here are some examples of padding:
+
+@example
+date +%d/%m -d "Feb 1"
+@result{} 01/02
+date +%-d/%-m -d "Feb 1"
+@result{} 1/2
+date +%_d/%_m -d "Feb 1"
+@result{}  1/ 2
+@end example
+
+You can optionally specify the field width
+(after any flag, if present) as a decimal number.  If the natural size of the
+output of the field has less than the specified number of characters,
+the result is normally written right adjusted and padded to the given
+size.  For example, @samp{%9B} prints the right adjusted month name in
+a field of width 9.  Nanoseconds are left adjusted, and are truncated
+or padded to the field width.
+
+An optional modifier can follow the optional flag and width
+specification.  The modifiers are:
+
+@table @samp
+@item E
+Use the locale's alternate representation for date and time.  This
+modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X},
+@samp{%y} and @samp{%Y} conversion specifiers.  In a Japanese locale, for
+example, @samp{%Ex} might yield a date format based on the Japanese
+Emperors' reigns.
+
+@item O
+Use the locale's alternate numeric symbols for numbers.  This modifier
+applies only to numeric conversion specifiers.
+@end table
+
+If the format supports the modifier but no alternate representation
+is available, it is ignored.
+
+POSIX specifies the behavior of flags and field widths only for
+@samp{%C}, @samp{%F}, @samp{%G}, and @samp{%Y} (all without
+modifiers), and requires a flag to be present if and only if a field
+width is also present.  Other combinations of flags, field widths and
+modifiers are GNU extensions.
+
+
+@node Setting the time
+@subsection Setting the time
+
+@cindex setting the time
+@cindex time setting
+@cindex appropriate privileges
+
+You must have appropriate privileges to set the
+system clock.  For changes to persist across a reboot, the
+hardware clock may need to be updated from the system clock, which
+might not happen automatically on your system.
+
+To set the clock, you can use the @option{--set} (@option{-s}) option
+(@pxref{Options for date}).  To set the clock without using GNU
+extensions, you can give @command{date} an argument of the form
+@samp{MMDDhhmm[[CC]YY][.ss]} where each two-letter
+component stands for two digits with the following meanings:
+
+@table @var
+@item MM
+month
+@item DD
+day within month
+@item hh
+hour
+@item mm
+minute
+@item CC
+first two digits of year (optional)
+@item YY
+last two digits of year (optional)
+@item ss
+second (optional)
+@end table
+
+Note, the @option{--date} and @option{--set} options may not be used with an
+argument in the above format.  The @option{--universal} option may be used
+with such an argument to indicate that the specified date and time are
+relative to Universal Time rather than to the local time zone.
+
+
+@node Options for date
+@subsection Options for @command{date}
+
+@cindex @command{date} options
+@cindex options for @command{date}
+
+The program accepts the following options.  Also see @ref{Common options}.
+Except for @option{-u}, these options are all GNU extensions to POSIX.
+
+All options that specify the date to display are mutually exclusive.
+I.e.: @option{--date}, @option{--file}, @option{--reference},
+@option{--resolution}.
+
+@table @samp
+
+@item -d @var{datestr}
+@itemx --date=@var{datestr}
+@opindex -d
+@opindex --date
+@cindex parsing date strings
+@cindex date strings, parsing
+@cindex arbitrary date strings, parsing
+@opindex yesterday
+@opindex tomorrow
+@opindex next @var{day}
+@opindex last @var{day}
+Display the date and time specified in @var{datestr} instead of the
+current date and time.  @var{datestr} can be in almost any common
+format.  It can contain month names, time zones, @samp{am} and @samp{pm},
+@samp{yesterday}, etc.  For example, @option{--date="2020-07-21
+14:19:13.489392193 +0530"} specifies the instant of time that is
+489,392,193 nanoseconds after July 21, 2020 at 2:19:13 PM in a
+time zone that is 5 hours and 30 minutes east of UTC.@*
+Note: input currently must be in locale independent format.  E.g., the
+LC_TIME=C below is needed to print back the correct date in many locales:
+@example
+date -d "$(LC_TIME=C date)"
+@end example
+@xref{Date input formats}.
+
+@item --debug
+@opindex --debug
+@cindex debugging date strings
+@cindex date strings, debugging
+@cindex arbitrary date strings, debugging
+Annotate the parsed date, display the effective time zone, and warn about
+potential misuse.
+
+@item -f @var{datefile}
+@itemx --file=@var{datefile}
+@opindex -f
+@opindex --file
+Parse each line in @var{datefile} as with @option{-d} and display the
+resulting date and time.  If @var{datefile} is @samp{-}, use standard
+input.  This is useful when you have many dates to process, because the
+system overhead of starting up the @command{date} executable many times can
+be considerable.
+
+@item -I[@var{timespec}]
+@itemx --iso-8601[=@var{timespec}]
+@opindex -I[@var{timespec}]
+@opindex --iso-8601[=@var{timespec}]
+Display the date using an ISO 8601 format, @samp{%Y-%m-%d}.
+
+The argument @var{timespec} specifies the number of additional
+terms of the time to include.  It can be one of the following:
+@table @samp
+@item auto
+Print just the date.  This is the default if @var{timespec} is omitted.
+This is like the format @code{%Y-%m-%d}.
+
+@item hours
+Also print hours and time zone.
+This is like the format @code{%Y-%m-%dT%H%:z}.
+
+@item minutes
+Also print minutes.
+This is like the format @code{%Y-%m-%dT%H:%M%:z}.
+
+@item seconds
+Also print seconds.
+This is like the format @code{%Y-%m-%dT%H:%M:%S%:z}.
+
+@item ns
+Also print nanoseconds.
+This is like the format @code{%Y-%m-%dT%H:%M:%S,%N%:z}.
+@end table
+
+@macro dateParseNote
+This format is always suitable as input
+for the @option{--date} (@option{-d}) and @option{--file}
+(@option{-f}) options, regardless of the current locale.
+@end macro
+@dateParseNote
+
+@item -r @var{file}
+@itemx --reference=@var{file}
+@opindex -r
+@opindex --reference
+Display the date and time of the last modification of @var{file},
+instead of the current date and time.
+
+@item --resolution
+@opindex --resolution
+Display the timestamp resolution instead of the time.
+Current clock timestamps that are output by @command{date}
+are integer multiples of the timestamp resolution.
+With this option, the format defaults to @samp{%s.%N}.
+For example, if the clock resolution is 1 millisecond,
+the output is:
+
+@example
+0.001000000
+@end example
+
+@item -R
+@itemx --rfc-email
+@opindex -R
+@opindex --rfc-email
+Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S
+%z}, evaluated in the C locale so abbreviations are always in English.
+For example:
+
+@example
+Mon, 09 Jul 2020 17:00:00 -0400
+@end example
+
+@opindex --rfc-822
+@opindex --rfc-2822
+This format conforms to Internet RFCs
+@uref{https://tools.ietf.org/search/rfc5322, 5322},
+@uref{https://tools.ietf.org/search/rfc2822, 2822} and
+@uref{https://tools.ietf.org/search/rfc822, 822}, the
+current and previous standards for Internet email.
+For compatibility with older versions of @command{date},
+@option{--rfc-2822} and @option{--rfc-822} are aliases for
+@option{--rfc-email}.
+
+@item --rfc-3339=@var{timespec}
+@opindex --rfc-3339=@var{timespec}
+Display the date using a format specified by
+@uref{https://tools.ietf.org/search/rfc3339, Internet
+RFC 3339}.  This is like @option{--iso-8601}, except that a space rather
+than a @samp{T} separates dates from times, and a period rather than
+a comma separates seconds from subseconds.
+@dateParseNote
+
+The argument @var{timespec} specifies how much of the time to include.
+It can be one of the following:
+
+@table @samp
+@item date
+Print just the full-date, e.g., @samp{2020-07-21}.
+This is like the format @samp{%Y-%m-%d}.
+
+@item seconds
+Print the full-date and full-time separated by a space, e.g.,
+@samp{2020-07-21 04:30:37+05:30}.  The output ends with a numeric
+time-offset; here the @samp{+05:30} means that local time is five
+hours and thirty minutes east of UTC@.  This is like
+the format @samp{%Y-%m-%d %H:%M:%S%:z}.
+
+@item ns
+Like @samp{seconds}, but also print nanoseconds, e.g.,
+@samp{2020-07-21 04:30:37.998458565+05:30}.
+This is like the format @samp{%Y-%m-%d %H:%M:%S.%N%:z}.
+
+@end table
+
+@item -s @var{datestr}
+@itemx --set=@var{datestr}
+@opindex -s
+@opindex --set
+Set the date and time to @var{datestr}.  See @option{-d} above.
+See also @ref{Setting the time}.
+
+@item -u
+@itemx --utc
+@itemx --universal
+@opindex -u
+@opindex --utc
+@opindex --universal
+@cindex Coordinated Universal Time
+@cindex UTC
+@cindex Greenwich Mean Time
+@cindex GMT
+@cindex leap seconds
+@vindex TZ
+@cindex Universal Time
+Use Universal Time by operating as if the
+@env{TZ} environment variable were set to the string @samp{UTC0}.
+UTC stands for Coordinated Universal Time, established in 1960.
+Universal Time is often called ``Greenwich Mean Time'' (GMT) for
+historical reasons.
+Typically, systems ignore leap seconds and thus implement an
+approximation to UTC rather than true UTC.
+@end table
+
+
+@node Examples of date
+@subsection Examples of @command{date}
+
+@cindex examples of @command{date}
+
+Here are a few examples.  Also see the documentation for the @option{-d}
+option in the previous section.
+
+@itemize @bullet
+
+@item
+To print the date of the day before yesterday:
+
+@example
+date --date='2 days ago'
+@end example
+
+@item
+To print the date of the day three months and one day hence:
+
+@example
+date --date='3 months 1 day'
+@end example
+
+@item
+To print the day of year of Christmas in the current year:
+
+@example
+date --date='25 Dec' +%j
+@end example
+
+@item
+To print the current full month name and the day of the month:
+
+@example
+date '+%B %d'
+@end example
+
+But this may not be what you want because for the first nine days of
+the month, the @samp{%d} expands to a zero-padded two-digit field,
+for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}.
+
+@item
+To print a date without the leading zero for one-digit days
+of the month, you can use the (GNU extension)
+@samp{-} flag to suppress
+the padding altogether:
+
+@example
+date -d 1may '+%B %-d'
+@end example
+
+@item
+To print the current date and time in the format required by many
+non-GNU versions of @command{date} when setting the system clock:
+
+@example
+date +%m%d%H%M%Y.%S
+@end example
+
+@item
+To set the system clock forward by two minutes:
+
+@example
+date --set='+2 minutes'
+@end example
+
+@item
+To print the date in Internet RFC 5322 format,
+use @samp{date --rfc-email}.  Here is some example output:
+
+@example
+Tue, 09 Jul 2020 19:00:37 -0400
+@end example
+
+@anchor{%s-examples}
+@item
+To convert a date string to the number of seconds since the Epoch
+(which is 1970-01-01 00:00 UTC), use the @option{--date} option with
+the @samp{%s} format.  That can be useful in sorting and/or graphing
+and/or comparing data by date.  The following command outputs the
+number of the seconds since the Epoch for the time two minutes after the
+Epoch:
+
+@example
+date --date='1970-01-01 00:02:00 +0000' +%s
+120
+@end example
+
+To convert a date string from one time zone @var{from} to another @var{to},
+specify @samp{TZ="@var{from}"} in the environment and @samp{TZ="@var{to}"}
+in the @option{--date} option.  @xref{Specifying time zone rules}.
+For example:
+
+@smallexample
+TZ="Asia/Tokyo" date --date='TZ="America/New_York" 2023-05-07 12:23'
+Mon May @ 8 01:23:00 JST 2023
+@end smallexample
+
+If you do not specify time zone information in the date string,
+@command{date} uses your computer's idea of the time zone when
+interpreting the string.  For example, if your computer's time zone is
+that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000
+seconds) behind UTC:
+
+@example
+# local time zone used
+date --date='1970-01-01 00:02:00' +%s
+18120
+@end example
+
+@item
+If you're sorting or graphing dated data, your raw date values may be
+represented as seconds since the Epoch.  But few people can look at
+the date @samp{1577836800} and casually note ``Oh, that's the first
+second of the year 2020 in Greenwich, England.''
+
+@example
+date --date='2020-01-01 UTC' +%s
+1577836800
+@end example
+
+An alternative is to use the @option{--utc} (@option{-u}) option.
+Then you may omit @samp{UTC} from the date string.  Although this
+produces the same result for @samp{%s} and many other format sequences,
+with a time zone offset different from zero, it would give a different
+result for zone-dependent formats like @samp{%z}.
+
+@example
+date -u --date=2020-07-21 +%s
+1595289600
+@end example
+
+To convert such an unwieldy number of seconds back to
+a more readable form, use a command like this:
+
+@example
+date -d @@1595289600 +"%F %T %z"
+2020-07-20 20:00:00 -0400
+@end example
+
+Often it is better to output UTC-relative date and time:
+
+@example
+date -u -d @@1595289600 +"%F %T %z"
+2020-07-21 00:00:00 +0000
+@end example
+
+@item
+@cindex leap seconds
+Typically the seconds count omits leap seconds, but some systems are
+exceptions.  Because leap seconds are not predictable, the mapping
+between the seconds count and a future timestamp is not reliable on
+the atypical systems that include leap seconds in their counts.
+
+Here is how the two kinds of systems handle the leap second at
+the end of the year 2016:
+
+@example
+# Typical systems ignore leap seconds:
+date --date='2016-12-31 23:59:59 +0000' +%s
+1483228799
+date --date='2016-12-31 23:59:60 +0000' +%s
+date: invalid date '2016-12-31 23:59:60 +0000'
+date --date='2017-01-01 00:00:00 +0000' +%s
+1483228800
+@end example
+
+@example
+# Atypical systems count leap seconds:
+date --date='2016-12-31 23:59:59 +0000' +%s
+1483228825
+date --date='2016-12-31 23:59:60 +0000' +%s
+1483228826
+date --date='2017-01-01 00:00:00 +0000' +%s
+1483228827
+@end example
+
+@end itemize
+
+
+@node arch invocation
+@section @command{arch}: Print machine hardware name
+
+@pindex arch
+@cindex print machine hardware name
+@cindex system information, printing
+
+@command{arch} prints the machine hardware name,
+and is equivalent to @samp{uname -m}.
+Synopsis:
+
+@example
+arch [@var{option}]
+@end example
+
+The program accepts the @ref{Common options} only.
+
+@command{arch} is not installed by default, so portable scripts should
+not rely on its existence.
+
+@exitstatus
+
+
+@node nproc invocation
+@section @command{nproc}: Print the number of available processors
+
+@pindex nproc
+@cindex Print the number of processors
+@cindex system information, printing
+
+Print the number of processing units available to the current process,
+which may be less than the number of online processors.
+If this information is not accessible, then print the number of
+processors installed.  If the @env{OMP_NUM_THREADS} or @env{OMP_THREAD_LIMIT}
+environment variables are set, then they will determine the minimum
+and maximum returned value respectively.  The result is guaranteed to be
+greater than zero.  Synopsis:
+
+@example
+nproc [@var{option}]
+@end example
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item --all
+@opindex --all
+Print the number of installed processors on the system, which may
+be greater than the number online or available to the current process.
+The @env{OMP_NUM_THREADS} or @env{OMP_THREAD_LIMIT} environment variables
+are not honored in this case.
+
+@item --ignore=@var{number}
+@opindex --ignore
+If possible, exclude this @var{number} of processing units.
+
+@end table
+
+@exitstatus
+
+
+@node uname invocation
+@section @command{uname}: Print system information
+
+@pindex uname
+@cindex print system information
+@cindex system information, printing
+
+@command{uname} prints information about the machine and operating system
+it is run on.  If no options are given, @command{uname} acts as if the
+@option{-s} option were given.  Synopsis:
+
+@example
+uname [@var{option}]@dots{}
+@end example
+
+If multiple options or @option{-a} are given, the selected information is
+printed in this order:
+
+@example
+@var{kernel-name} @var{nodename} @var{kernel-release} @var{kernel-version}
+@var{machine} @var{processor} @var{hardware-platform} @var{operating-system}
+@end example
+
+The information may contain internal spaces, so such output cannot be
+parsed reliably.  In the following example, @var{kernel-version} is
+@samp{#1 SMP Fri Jul 17 17:18:38 UTC 2020}:
+
+@example
+uname -a
+@result{} Linux dumdum.example.org 5.9.16-200.fc33.x86_64@c
+ #1 SMP Mon Dec 21 14:08:22 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux
+@end example
+
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -a
+@itemx --all
+@opindex -a
+@opindex --all
+Print all of the below information, except omit the processor type
+and the hardware platform name if they are unknown.
+
+@item -i
+@itemx --hardware-platform
+@opindex -i
+@opindex --hardware-platform
+@cindex implementation, hardware
+@cindex hardware platform
+@cindex platform, hardware
+Print the hardware platform name
+(sometimes called the hardware implementation).
+Print @samp{unknown} if this information is not available.
+Note this is non-portable (even across GNU/Linux distributions).
+
+@item -m
+@itemx --machine
+@opindex -m
+@opindex --machine
+@cindex machine type
+@cindex hardware class
+@cindex hardware type
+Print the machine hardware name (sometimes called the hardware class
+or hardware type).
+
+@item -n
+@itemx --nodename
+@opindex -n
+@opindex --nodename
+@cindex hostname
+@cindex node name
+@cindex network node name
+Print the network node hostname.
+
+@item -p
+@itemx --processor
+@opindex -p
+@opindex --processor
+@cindex host processor type
+Print the processor type (sometimes called the instruction set
+architecture or ISA).
+Print @samp{unknown} if this information is not available.
+Note this is non-portable (even across GNU/Linux distributions).
+
+@item -o
+@itemx --operating-system
+@opindex -o
+@opindex --operating-system
+@cindex operating system name
+Print the name of the operating system.
+
+@item -r
+@itemx --kernel-release
+@opindex -r
+@opindex --kernel-release
+@cindex kernel release
+@cindex release of kernel
+Print the kernel release.
+
+@item -s
+@itemx --kernel-name
+@opindex -s
+@opindex --kernel-name
+@cindex kernel name
+@cindex name of kernel
+Print the kernel name.
+POSIX 1003.1-2001 (@pxref{Standards conformance}) calls this
+``the implementation of the operating system'', because the
+POSIX specification itself has no notion of ``kernel''.
+The kernel name might be the same as the operating system name printed
+by the @option{-o} or @option{--operating-system} option, but it might
+differ.  Some operating systems (e.g., FreeBSD, HP-UX) have the same
+name as their underlying kernels; others (e.g., GNU/Linux, Solaris)
+do not.
+
+@item -v
+@itemx --kernel-version
+@opindex -v
+@opindex --kernel-version
+@cindex kernel version
+@cindex version of kernel
+Print the kernel version.
+
+@end table
+
+@exitstatus
+
+
+@node hostname invocation
+@section @command{hostname}: Print or set system name
+
+@pindex hostname
+@cindex setting the hostname
+@cindex printing the hostname
+@cindex system name, printing
+@cindex appropriate privileges
+
+With no arguments, @command{hostname} prints the name of the current host
+system.  With one argument, it sets the current host name to the
+specified string.  You must have appropriate privileges to set the host
+name.  Synopsis:
+
+@example
+hostname [@var{name}]
+@end example
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+@command{hostname} is not installed by default, and other packages
+also supply a @command{hostname} command, so portable scripts should
+not rely on its existence or on the exact behavior documented above.
+
+@exitstatus
+
+
+@node hostid invocation
+@section @command{hostid}: Print numeric host identifier
+
+@pindex hostid
+@cindex printing the host identifier
+
+@command{hostid} prints the numeric identifier of the current host
+in hexadecimal.  This command accepts no arguments.
+The only options are @option{--help} and @option{--version}.
+@xref{Common options}.
+
+For example, here's what it prints on one system I use:
+
+@example
+$ hostid
+1bac013d
+@end example
+
+On that system, the 32-bit quantity happens to be closely
+related to the system's Internet address, but that isn't always
+the case.
+
+@command{hostid} is installed only on systems that have the
+@code{gethostid} function, so portable scripts should not rely on its
+existence.
+
+@exitstatus
+
+@node uptime invocation
+@section @command{uptime}: Print system uptime and load
+
+@pindex uptime
+@cindex printing the system uptime and load
+
+@command{uptime} prints the current time, the system's uptime, the
+number of logged-in users and the current load average.
+
+If an argument is specified, it is used as the file to be read
+to discover how many users are logged in.  If no argument is
+specified, a system default is used (@command{uptime --help} indicates
+the default setting).
+
+The only options are @option{--help} and @option{--version}.
+@xref{Common options}.
+
+For example, here's what it prints right now on one system I use:
+
+@example
+$ uptime
+ 14:07  up   3:35,  3 users,  load average: 1.39, 1.15, 1.04
+@end example
+
+The precise method of calculation of load average varies somewhat
+between systems.  Some systems calculate it as the average number of
+runnable processes over the last 1, 5 and 15 minutes, but some systems
+also include processes in the uninterruptible sleep state (that is,
+those processes which are waiting for device I/O).  The Linux kernel
+includes uninterruptible processes.
+
+@command{uptime} is installed only on platforms with infrastructure
+for obtaining the boot time, and other packages also supply an
+@command{uptime} command, so portable scripts should not rely on its
+existence or on the exact behavior documented above.
+
+@exitstatus
+
+@node SELinux context
+@chapter SELinux context
+
+@cindex SELinux context
+@cindex SELinux, context
+@cindex commands for SELinux context
+
+This section describes commands for operations with SELinux
+contexts.
+
+@menu
+* chcon invocation::            Change SELinux context of file
+* runcon invocation::           Run a command in specified SELinux context
+@end menu
+
+@node chcon invocation
+@section @command{chcon}: Change SELinux context of file
+
+@pindex chcon
+@cindex changing security context
+@cindex change SELinux context
+
+@command{chcon} changes the SELinux security context of the selected files.
+Synopses:
+
+@example
+chcon [@var{option}]@dots{} @var{context} @var{file}@dots{}
+chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}]@c
+ [-t @var{type}] @var{file}@dots{}
+chcon [@var{option}]@dots{} --reference=@var{rfile} @var{file}@dots{}
+@end example
+
+Change the SELinux security context of each @var{file} to @var{context}.
+With @option{--reference}, change the security context of each @var{file}
+to that of @var{rfile}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item --dereference
+@opindex --dereference
+Do not affect symbolic links but what they refer to; this is the default.
+
+@item -h
+@itemx --no-dereference
+@opindex -h
+@opindex --no-dereference
+@cindex no dereference
+Affect the symbolic links themselves instead of any referenced file.
+
+@item --reference=@var{rfile}
+@opindex --reference
+@cindex reference file
+Use @var{rfile}'s security context rather than specifying a @var{context} value.
+
+@item -R
+@itemx --recursive
+@opindex -R
+@opindex --recursive
+Operate on files and directories recursively.
+
+@item --preserve-root
+@opindex --preserve-root
+Refuse to operate recursively on the root directory, @file{/},
+when used together with the @option{--recursive} option.
+@xref{Treating / specially}.
+
+@item --no-preserve-root
+@opindex --no-preserve-root
+Do not treat the root directory, @file{/}, specially when operating
+recursively; this is the default.
+@xref{Treating / specially}.
+
+@choptH
+@xref{Traversing symlinks}.
+
+@choptL
+@xref{Traversing symlinks}.
+
+@choptP
+@xref{Traversing symlinks}.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+@cindex diagnostic
+Output a diagnostic for every file processed.
+
+@item -u @var{user}
+@itemx --user=@var{user}
+@opindex -u
+@opindex --user
+Set user @var{user} in the target security context.
+
+@item -r @var{role}
+@itemx --role=@var{role}
+@opindex -r
+@opindex --role
+Set role @var{role} in the target security context.
+
+@item -t @var{type}
+@itemx --type=@var{type}
+@opindex -t
+@opindex --type
+Set type @var{type} in the target security context.
+
+@item -l @var{range}
+@itemx --range=@var{range}
+@opindex -l
+@opindex --range
+Set range @var{range} in the target security context.
+
+@end table
+
+@exitstatus
+
+@node runcon invocation
+@section @command{runcon}: Run a command in specified SELinux context
+
+@pindex runcon
+@cindex run with security context
+
+
+@command{runcon} runs file in specified SELinux security context.
+
+Synopses:
+@example
+runcon @var{context} @var{command} [@var{args}]
+runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}]@c
+ [-l @var{range}] @var{command} [@var{args}]
+@end example
+
+Run @var{command} with completely-specified @var{context}, or with
+current or transitioned security context modified by one or more of @var{level},
+@var{role}, @var{type} and @var{user}.
+
+If none of @option{-c}, @option{-t}, @option{-u}, @option{-r}, or @option{-l}
+is specified, the first argument is used as the complete context.
+Any additional arguments after @var{command}
+are interpreted as arguments to the command.
+
+With neither @var{context} nor @var{command}, print the current
+security context.
+
+@cindex restricted security context
+@cindex NO_NEW_PRIVS
+Note also the @command{setpriv} command which can be used to set the
+NO_NEW_PRIVS bit using @command{setpriv --no-new-privs runcon ...},
+thus disallowing usage of a security context with more privileges
+than the process would normally have.
+
+@command{runcon} accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -c
+@itemx --compute
+@opindex -c
+@opindex --compute
+Compute process transition context before modifying.
+
+@item -u @var{user}
+@itemx --user=@var{user}
+@opindex -u
+@opindex --user
+Set user @var{user} in the target security context.
+
+@item -r @var{role}
+@itemx --role=@var{role}
+@opindex -r
+@opindex --role
+Set role @var{role} in the target security context.
+
+@item -t @var{type}
+@itemx --type=@var{type}
+@opindex -t
+@opindex --type
+Set type @var{type} in the target security context.
+
+@item -l @var{range}
+@itemx --range=@var{range}
+@opindex -l
+@opindex --range
+Set range @var{range} in the target security context.
+
+@end table
+
+@cindex exit status of @command{runcon}
+Exit status:
+
+@display
+125 if @command{runcon} itself fails
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+the exit status of @var{command} otherwise
+@end display
+
+@node Modified command invocation
+@chapter Modified command invocation
+
+@cindex modified command invocation
+@cindex invocation of commands, modified
+@cindex commands for invoking other commands
+
+This section describes commands that run other commands in some context
+different than the current one: a modified environment, as a different
+user, etc.
+
+@menu
+* chroot invocation::           Modify the root directory.
+* env invocation::              Modify environment variables.
+* nice invocation::             Modify niceness.
+* nohup invocation::            Immunize to hangups.
+* stdbuf invocation::           Modify buffering of standard streams.
+* timeout invocation::          Run with time limit.
+@end menu
+
+
+@node chroot invocation
+@section @command{chroot}: Run a command with a different root directory
+
+@pindex chroot
+@cindex running a program in a specified root directory
+@cindex root directory, running a program in a specified
+
+@command{chroot} runs a command with a specified root directory.
+On many systems, only the super-user can do this.@footnote{However,
+some systems (e.g., FreeBSD) can be configured to allow certain regular
+users to use the @code{chroot} system call, and hence to run this program.
+Also, on Cygwin, anyone can run the @command{chroot} command, because the
+underlying function is non-privileged due to lack of support in MS-Windows.
+Furthermore, the @command{chroot} command avoids the @code{chroot} system call
+when @var{newroot} is identical to the old @file{/} directory for consistency
+with systems where this is allowed for non-privileged users.}.
+Synopses:
+
+@example
+chroot @var{option} @var{newroot} [@var{command} [@var{args}]@dots{}]
+chroot @var{option}
+@end example
+
+Ordinarily, file names are looked up starting at the root of the
+directory structure, i.e., @file{/}.  @command{chroot} changes the root to
+the directory @var{newroot} (which must exist), then changes the working
+directory to @file{/}, and finally runs @var{command} with optional @var{args}.
+If @var{command} is not specified, the default is the value of the @env{SHELL}
+environment variable or @command{/bin/sh} if not set, invoked with the
+@option{-i} option.
+@var{command} must not be a special built-in utility
+(@pxref{Special built-in utilities}).
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+
+@item --groups=@var{groups}
+@opindex --groups
+Use this option to override the supplementary @var{groups} to be
+used by the new process.
+The items in the list (names or numeric IDs) must be separated by commas.
+Use @samp{--groups=''} to disable the supplementary group look-up
+implicit in the @option{--userspec} option.
+
+@item --userspec=@var{user}[:@var{group}]
+@opindex --userspec
+By default, @var{command} is run with the same credentials
+as the invoking process.
+Use this option to run it as a different @var{user} and/or with a
+different primary @var{group}.
+If a @var{user} is specified then the supplementary groups
+are set according to the system defined list for that user,
+unless overridden with the @option{--groups} option.
+
+@item --skip-chdir
+@opindex --skip-chdir
+Use this option to not change the working directory to @file{/} after changing
+the root directory to @var{newroot}, i.e., inside the chroot.
+This option is only permitted when @var{newroot} is the old @file{/} directory,
+and therefore is mostly useful together with the @option{--groups} and
+@option{--userspec} options to retain the previous working directory.
+
+@end table
+
+The user and group name look-up performed by the @option{--userspec}
+and @option{--groups} options, is done both outside and inside
+the chroot, with successful look-ups inside the chroot taking precedence.
+If the specified user or group items are intended to represent a numeric ID,
+then a name to ID resolving step is avoided by specifying a leading @samp{+}.
+@xref{Disambiguating names and IDs}.
+
+Here are a few tips to help avoid common problems in using chroot.
+To start with a simple example, make @var{command} refer to a statically
+linked binary.  If you were to use a dynamically linked executable, then
+you'd have to arrange to have the shared libraries in the right place under
+your new root directory.
+
+For example, if you create a statically linked @command{ls} executable,
+and put it in @file{/tmp/empty}, you can run this command as root:
+
+@example
+$ chroot /tmp/empty /ls -Rl /
+@end example
+
+Then you'll see output like this:
+
+@example
+/:
+total 1023
+-rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls
+@end example
+
+If you want to use a dynamically linked executable, say @command{bash},
+then first run @samp{ldd bash} to see what shared objects it needs.
+Then, in addition to copying the actual binary, also copy the listed
+files to the required positions under your intended new root directory.
+Finally, if the executable requires any other files (e.g., data, state,
+device files), copy them into place, too.
+
+@command{chroot} is installed only on systems that have the
+@code{chroot} function, so portable scripts should not rely on its
+existence.
+
+@cindex exit status of @command{chroot}
+Exit status:
+
+@display
+125 if @command{chroot} itself fails
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+the exit status of @var{command} otherwise
+@end display
+
+
+@node env invocation
+@section @command{env}: Run a command in a modified environment
+
+@pindex env
+@cindex environment, running a program in a modified
+@cindex modified environment, running a program in a
+@cindex running a program in a modified environment
+
+@command{env} runs a command with a modified environment.  Synopses:
+
+@example
+env [@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
+[@var{command} [@var{args}]@dots{}]
+env -[v]S'[@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
+[@var{command} [@var{args}]@dots{}]'
+env
+@end example
+
+@command{env} is commonly used on first line of scripts (shebang line):
+@example
+#!/usr/bin/env @var{command}
+#!/usr/bin/env -[v]S[@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c
+@var{command} [@var{args}]@dots{}
+@end example
+
+Operands of the form @samp{@var{variable}=@var{value}} set
+the environment variable @var{variable} to value @var{value}.
+@var{value} may be empty (@samp{@var{variable}=}).  Setting a variable
+to an empty value is different from unsetting it.
+These operands are evaluated left-to-right, so if two operands
+mention the same variable the earlier is ignored.
+
+Environment variable names can be empty, and can contain any
+characters other than @samp{=} and ASCII NUL.
+However, it is wise to limit yourself to names that
+consist solely of underscores, digits, and ASCII letters,
+and that begin with a non-digit, as applications like the shell do not
+work well with other names.
+
+@vindex PATH
+The first operand that does not contain the character @samp{=}
+specifies the program to invoke; it is
+searched for according to the @env{PATH} environment variable.  Any
+remaining arguments are passed as arguments to that program.
+The program should not be a special built-in utility
+(@pxref{Special built-in utilities}).
+
+Modifications to @env{PATH} take effect prior to searching for
+@var{command}.  Use caution when reducing @env{PATH}; behavior is
+not portable when @env{PATH} is undefined or omits key directories
+such as @file{/bin}.
+
+In the rare case that a utility contains a @samp{=} in the name, the
+only way to disambiguate it from a variable assignment is to use an
+intermediate command for @var{command}, and pass the problematic
+program name via @var{args}.  For example, if @file{./prog=} is an
+executable in the current @env{PATH}:
+
+@example
+env prog= true # runs 'true', with prog= in environment
+env ./prog= true # runs 'true', with ./prog= in environment
+env -- prog= true # runs 'true', with prog= in environment
+env sh -c '\prog= true' # runs 'prog=' with argument 'true'
+env sh -c 'exec "$@@"' sh prog= true # also runs 'prog='
+@end example
+
+@cindex environment, printing
+
+If no command name is specified following the environment
+specifications, the resulting environment is printed.  This is like
+specifying the @command{printenv} program.
+
+For some examples, suppose the environment passed to @command{env}
+contains @samp{LOGNAME=rms}, @samp{EDITOR=emacs}, and
+@samp{PATH=.:/gnubin:/hacks}:
+
+@itemize @bullet
+
+@item
+Output the current environment.
+@example
+$ env | LC_ALL=C sort
+EDITOR=emacs
+LOGNAME=rms
+PATH=.:/gnubin:/hacks
+@end example
+
+@item
+Run @command{foo} with a reduced environment, preserving only the
+original @env{PATH} to avoid problems in locating @command{foo}.
+@example
+env - PATH="$PATH" foo
+@end example
+
+@item
+Run @command{foo} with the environment containing @samp{LOGNAME=rms},
+@samp{EDITOR=emacs}, and @samp{PATH=.:/gnubin:/hacks}, and guarantees
+that @command{foo} was found in the file system rather than as a shell
+built-in.
+@example
+env foo
+@end example
+
+@item
+Run @command{nemacs} with the environment containing @samp{LOGNAME=foo},
+@samp{EDITOR=emacs}, @samp{PATH=.:/gnubin:/hacks}, and
+@samp{DISPLAY=gnu:0}.
+@example
+env DISPLAY=gnu:0 LOGNAME=foo nemacs
+@end example
+
+@item
+Attempt to run the program @command{/energy/--} (as that is the only
+possible path search result); if the command exists, the environment
+will contain @samp{LOGNAME=rms} and @samp{PATH=/energy}, and the
+arguments will be @samp{e=mc2}, @samp{bar}, and @samp{baz}.
+@example
+env -u EDITOR PATH=/energy -- e=mc2 bar baz
+@end example
+
+@end itemize
+
+
+@subsection General options
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+
+@optNull
+
+@item -u @var{name}
+@itemx --unset=@var{name}
+@opindex -u
+@opindex --unset
+Remove variable @var{name} from the environment, if it was in the
+environment.
+
+@item -
+@itemx -i
+@itemx --ignore-environment
+@opindex -
+@opindex -i
+@opindex --ignore-environment
+Start with an empty environment, ignoring the inherited environment.
+
+@item -C @var{dir}
+@itemx --chdir=@var{dir}
+@opindex -C
+@opindex --chdir
+Change the working directory to @var{dir} before invoking @var{command}.
+This differs from the shell built-in @command{cd} in that it starts
+@var{command} as a subprocess rather than altering the shell's own working
+directory; this allows it to be chained with other commands that run commands
+in a different context.  For example:
+
+@example
+# Run 'true' with /chroot as its root directory and /srv as its working
+# directory.
+chroot /chroot env --chdir=/srv true
+# Run 'true' with /build as its working directory, FOO=bar in its
+# environment, and a time limit of five seconds.
+env --chdir=/build FOO=bar timeout 5 true
+@end example
+
+@item --default-signal[=@var{sig}]
+Unblock and reset signal @var{sig} to its default signal handler.
+Without @var{sig} all known signals are unblocked and reset to their defaults.
+Multiple signals can be comma-separated. An empty @var{sig} argument is a no-op.
+The following command runs @command{seq} with SIGINT and SIGPIPE set to their
+default (which is to terminate the program):
+
+@example
+env --default-signal=PIPE,INT seq 1000 | head -n1
+@end example
+
+In the following example, we see how this is not
+possible to do with traditional shells.
+Here the first trap command sets SIGPIPE to ignore.
+The second trap command ostensibly sets it back to its default,
+but POSIX mandates that the shell must not change inherited
+state of the signal -- so it is a no-op.
+
+@example
+trap '' PIPE && sh -c 'trap - PIPE ; seq inf | head -n1'
+@end example
+
+Using @option{--default-signal=PIPE} we can
+ensure the signal handling is set to its default behavior:
+
+@example
+trap '' PIPE && sh -c 'env --default-signal=PIPE seq inf | head -n1'
+@end example
+
+
+@item --ignore-signal[=@var{sig}]
+Ignore signal @var{sig} when running a program.  Without @var{sig} all
+known signals are set to ignore.  Multiple signals can be comma-separated.
+An empty @var{sig} argument is a no-op. The following command runs @command{seq}
+with SIGINT set to be ignored -- pressing @kbd{Ctrl-C} will not terminate it:
+
+@example
+env --ignore-signal=INT seq inf > /dev/null
+@end example
+
+@samp{SIGCHLD} is special, in that @option{--ignore-signal=CHLD} might have
+no effect (POSIX says it's unspecified).
+
+Most operating systems do not allow ignoring @samp{SIGKILL}, @samp{SIGSTOP}
+(and possibly other signals).  Attempting to ignore these signals will fail.
+
+Multiple (and contradictory) @option{--default-signal=SIG} and
+@option{--ignore-signal=SIG} options are processed left-to-right,
+with the latter taking precedence.  In the following example, @samp{SIGPIPE} is
+set to default while @samp{SIGINT} is ignored:
+
+@example
+env --default-signal=INT,PIPE --ignore-signal=INT
+@end example
+
+@item --block-signal[=@var{sig}]
+Block signal(s) @var{sig} from being delivered.  Without @var{sig} all
+known signals are set to blocked.  Multiple signals can be comma-separated.
+An empty @var{sig} argument is a no-op.
+
+@item --list-signal-handling
+List blocked or ignored signals to standard error, before executing a command.
+
+@item -v
+@itemx --debug
+@opindex -v
+@opindex --debug
+Show verbose information for each processing step.
+
+@example
+$ env -v -uTERM A=B uname -s
+unset:    TERM
+setenv:   A=B
+executing: uname
+   arg[0]= 'uname'
+   arg[1]= '-s'
+Linux
+@end example
+
+When combined with @option{-S} it is recommended to list @option{-v}
+first, e.g. @command{env -vS'string'}.
+
+@item -S @var{string}
+@itemx --split-string=@var{string}
+@opindex -S
+@opindex --split-string
+@cindex shebang arguments
+@cindex scripts arguments
+@cindex env in scripts
+process and split @var{string} into separate arguments used to pass
+multiple arguments on shebang lines.  @command{env} supports FreeBSD's
+syntax of several escape sequences and environment variable
+expansions. See below for details and examples.
+
+@end table
+
+@cindex exit status of @command{env}
+Exit status:
+
+@display
+0   if no @var{command} is specified and the environment is output
+125 if @command{env} itself fails
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+the exit status of @var{command} otherwise
+@end display
+
+@subsection @option{-S}/@option{--split-string} usage in scripts
+
+The @option{-S}/@option{--split-string} option enables use of multiple
+arguments on the first line of scripts (the shebang line, @samp{#!}).
+
+When a script's interpreter is in a known location, scripts typically
+contain the absolute file name in their first line:
+
+@multitable {Python Script:} {#!/usr/bin/python3}
+@item Shell script:
+@tab
+@example
+#!/bin/sh
+echo hello
+@end example
+
+@item Perl script:
+@tab
+@example
+#!/usr/bin/perl
+print "hello\n";
+@end example
+
+@item Python script:
+@tab
+@example
+#!/usr/bin/python3
+print("hello")
+@end example
+
+@end multitable
+
+When a script's interpreter is in a non-standard location
+in the @env{PATH} environment variable, it is recommended
+to use @command{env} on the first line of the script to
+find the executable and run it:
+
+@multitable {Python Script:} {#!/usr/bin/env python3}
+@item Shell script:
+@tab
+@example
+#!/usr/bin/env bash
+echo hello
+@end example
+
+@item Perl script:
+@tab
+@example
+#!/usr/bin/env perl
+print "hello\n";
+@end example
+
+@item Python script:
+@tab
+@example
+#!/usr/bin/env python3
+print("hello")
+@end example
+
+@end multitable
+
+Most operating systems (e.g. GNU/Linux, BSDs) treat all text after the
+first space as a single argument. When using @command{env} in a script
+it is thus not possible to specify multiple arguments.
+
+In the following example:
+@example
+#!/usr/bin/env perl -T -w
+print "hello\n";
+@end example
+
+The operating system treats @samp{perl -T -w} as one argument (the
+program's name), and executing the script fails with:
+
+@example
+/usr/bin/env: 'perl -T -w': No such file or directory
+@end example
+
+The @option{-S} option instructs @command{env} to split the single string
+into multiple arguments. The following example works as expected:
+
+@example
+$ cat hello.pl
+#!/usr/bin/env -S perl -T -w
+print "hello\n";
+
+$ chmod a+x hello.pl
+$ ./hello.pl
+hello
+@end example
+
+And is equivalent to running @command{perl -T -w hello.pl} on the command line
+prompt.
+
+@unnumberedsubsubsec Testing and troubleshooting
+
+@cindex single quotes, and @command{env -S}
+@cindex @command{env -S}, and single quotes
+@cindex @option{-S}, env and single quotes
+To test @command{env -S} on the command line, use single quotes for the
+@option{-S} string to emulate a single parameter. Single quotes are not
+needed when using @command{env -S} in a shebang line on the first line of a
+script (the operating system already treats it as one argument).
+
+The following command is equivalent to the @file{hello.pl} script above:
+
+@example
+$ env -S'perl -T -w' hello.pl
+@end example
+
+@cindex @command{env -S}, debugging
+@cindex debugging, @command{env -S}
+
+To troubleshoot @option{-S} usage add the @option{-v} as the first
+argument (before @option{-S}).
+
+Using @option{-vS} on a shebang line in a script:
+
+@example
+$ cat hello-debug.pl
+#!/usr/bin/env -vS perl -T -w
+print "hello\n";
+
+$ chmod a+x hello-debug.pl
+$ ./hello-debug.pl
+split -S:  'perl -T -w'
+ into:    'perl'
+     &    '-T'
+     &    '-w'
+executing: perl
+   arg[0]= 'perl'
+   arg[1]= '-T'
+   arg[2]= '-w'
+   arg[3]= './hello-debug.pl'
+hello
+@end example
+
+Using @option{-vS} on the command line prompt (adding single quotes):
+
+@example
+$ env -vS'perl -T -w' hello-debug.pl
+split -S:  'perl -T -w'
+ into:    'perl'
+     &    '-T'
+     &    '-w'
+executing: perl
+   arg[0]= 'perl'
+   arg[1]= '-T'
+   arg[2]= '-w'
+   arg[3]= 'hello-debug.pl'
+hello
+@end example
+
+@subsection @option{-S}/@option{--split-string} syntax
+
+@unnumberedsubsubsec Splitting arguments by whitespace
+
+Running @command{env -Sstring} splits the @var{string} into
+arguments based on unquoted spaces or tab characters.
+(Newlines, carriage returns, vertical tabs and form feeds are treated
+like spaces and tabs.)
+
+In the following contrived example the @command{awk} variable
+@samp{OFS} will be @code{<space>xyz<space>} as these spaces are inside
+double quotes. The other space characters are used as argument separators:
+
+@example
+$ cat one.awk
+#!/usr/bin/env -S awk -v OFS=" xyz " -f
+BEGIN @{print 1,2,3@}
+
+$ chmod a+x one.awk
+$ ./one.awk
+1 xyz 2 xyz 3
+@end example
+
+When using @option{-S} on the command line prompt, remember to add
+single quotes around the entire string:
+
+@example
+$ env -S'awk -v OFS=" xyz " -f' one.awk
+1 xyz 2 xyz 3
+@end example
+
+@unnumberedsubsubsec Escape sequences
+
+@command{env} supports several escape sequences. These sequences
+are processed when unquoted or inside double quotes (unless otherwise noted).
+Single quotes disable escape sequences except @samp{\'} and @samp{\\}.
+
+@multitable @columnfractions .10 .90
+
+@item @code{\c}
+@tab Ignore the remaining characters in the string.
+Cannot be used inside double quotes.
+
+@item @code{\f}
+@tab form-feed character (ASCII 0x0C)
+
+@item @code{\n}
+@tab new-line character (ASCII 0x0A)
+
+@item @code{\r}
+@tab carriage-return character (ASCII 0x0D)
+
+@item @code{\t}
+@tab tab character (ASCII 0x09)
+
+@item @code{\v}
+@tab vertical tab character (ASCII 0x0B)
+
+@item @code{\#}
+@tab A hash @samp{#} character. Used when a @samp{#} character
+is needed as the first character of an argument (see 'comments' section
+below).
+
+@item @code{\$}
+@tab A dollar-sign character @samp{$}. Unescaped @samp{$} characters
+are used to expand environment variables (see 'variables' section below).
+
+@item @code{\_}
+@tab Inside double-quotes, replaced with a single space character.
+Outside quotes, treated as an argument separator. @samp{\_} can be used
+to avoid space characters in a shebang line (see examples below).
+
+@item @code{\"}
+@tab A double-quote character.
+
+@item @code{\'}
+@tab A single-quote character.
+This escape sequence works inside single-quoted strings.
+
+@item @code{\\}
+@tab A backslash character.
+This escape sequence works inside single-quoted strings.
+
+@end multitable
+
+The following @command{awk} script will use tab character as input and output
+field separator (instead of spaces and tabs):
+
+@example
+$ cat tabs.awk
+#!/usr/bin/env -S awk -v FS="\t" -v OFS="\t" -f
+...
+@end example
+
+@unnumberedsubsubsec Comments
+
+The escape sequence @samp{\c} (used outside single/double quotes)
+causes @command{env} to ignore the rest of the string.
+
+The @samp{#} character causes @command{env} to ignore the rest of
+the string when it appears as the first character of an argument.
+Use @samp{\#} to reverse this behavior.
+
+@example
+$ env -S'printf %s\n A B C'
+A
+B
+C
+
+$ env -S'printf %s\n A# B C'
+A#
+B
+C
+
+$ env -S'printf %s\n A #B C'
+A
+
+$ env -S'printf %s\n A \#B C'
+A
+#B
+C
+
+$ env -S'printf %s\n A\cB C'
+A
+@end example
+
+NOTE: The above examples use single quotes as they are executed
+on the command-line.
+
+
+
+@unnumberedsubsubsec Environment variable expansion
+
+The pattern @samp{$@{VARNAME@}} is used to substitute a value from
+the environment variable. The pattern must include the curly braces
+(@samp{@{},@samp{@}}). Without them @command{env} will reject the string.
+Special shell variables (such as @samp{$@@}, @samp{$*}, @samp{$$}) are
+not supported.
+
+If the environment variable is empty or not set, the pattern will be replaced
+by an empty string. The value of @samp{$@{VARNAME@}} will be that of
+the executed @command{env}, before any modifications using
+@option{-i}/@option{--ignore-environment}/@option{-u}/@option{--unset} or
+setting new values using @samp{VAR=VALUE}.
+
+The following python script prepends @file{/opt/custom/modules} to the python
+module search path environment variable (@samp{PYTHONPATH}):
+
+@example
+$ cat custom.py
+#!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$@{PYTHONPATH@} python
+print "hello"
+...
+@end example
+
+The expansion of @samp{$@{PYTHONPATH@}} is performed by @command{env},
+not by a shell. If the curly braces are omitted, @command{env} will fail:
+
+@example
+$ cat custom.py
+#!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$PYTHONPATH python
+print "hello"
+...
+
+$ chmod a+x custom.py
+$ custom.py
+/usr/bin/env: only $@{VARNAME@} expansion is supported, error at: $PYTHONPATH @c
+python
+@end example
+
+Environment variable expansion happens before clearing the environment
+(with @option{-i}) or unsetting specific variables (with @option{-u}):
+
+@example
+$ env -S'-i OLDUSER=$@{USER@} env'
+OLDUSER=gordon
+@end example
+
+Use @option{-v} to diagnose the operations step-by-step:
+
+@example
+$ env -vS'-i OLDUSER=$@{USER@} env'
+expanding $@{USER@} into 'gordon'
+split -S:  '-i OLDUSER=$@{USER@} env'
+ into:    '-i'
+     &    'OLDUSER=gordon'
+     &    'env'
+cleaning environ
+setenv:   OLDUSER=gordon
+executing: env
+   arg[0]= 'env'
+OLDUSER=gordon
+@end example
+
+
+
+@node nice invocation
+@section @command{nice}: Run a command with modified niceness
+
+@pindex nice
+@cindex niceness
+@cindex scheduling, affecting
+@cindex appropriate privileges
+
+@command{nice} prints a process's @dfn{niceness}, or runs
+a command with modified niceness.  @dfn{niceness} affects how
+favorably the process is scheduled in the system.
+Synopsis:
+
+@example
+nice [@var{option}]@dots{} [@var{command} [@var{arg}]@dots{}]
+@end example
+
+If no arguments are given, @command{nice} prints the current niceness.
+Otherwise, @command{nice} runs the given @var{command} with its
+niceness adjusted.  By default, its niceness is incremented by 10.
+
+Niceness values range at least from @minus{}20 (process has high priority
+and gets more resources, thus slowing down other processes) through 19
+(process has lower priority and runs slowly itself, but has less impact
+on the speed of other running processes).  Some systems
+may have a wider range of niceness values; conversely, other systems may
+enforce more restrictive limits.  An attempt to set the niceness
+outside the supported range is treated as an attempt to use the
+minimum or maximum supported value.
+
+A niceness should not be confused with a scheduling priority, which
+lets applications determine the order in which threads are scheduled
+to run.  Unlike a priority, a niceness is merely advice to the
+scheduler, which the scheduler is free to ignore.  Also, as a point of
+terminology, POSIX defines the behavior of @command{nice} in
+terms of a @dfn{nice value}, which is the non-negative difference
+between a niceness and the minimum niceness.  Though @command{nice}
+conforms to POSIX, its documentation and diagnostics use the
+term ``niceness'' for compatibility with historical practice.
+
+@var{command} must not be a special built-in utility (@pxref{Special
+built-in utilities}).
+
+@mayConflictWithShellBuiltIn{nice}
+
+Note to change the @dfn{niceness} of an existing process,
+one needs to use the @command{renice} command.
+
+The program accepts the following option.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+@item -n @var{adjustment}
+@itemx --adjustment=@var{adjustment}
+@opindex -n
+@opindex --adjustment
+Add @var{adjustment} instead of 10 to the command's niceness.  If
+@var{adjustment} is negative and you lack appropriate privileges,
+@command{nice} issues a warning but otherwise acts as if you specified
+a zero adjustment.
+
+For compatibility @command{nice} also supports an obsolete
+option syntax @option{-@var{adjustment}}.  New scripts should use
+@option{-n @var{adjustment}} instead.
+
+@end table
+
+@command{nice} is installed only on systems that have the POSIX
+@code{setpriority} function, so portable scripts should not rely on
+its existence on non-POSIX platforms.
+
+@cindex exit status of @command{nice}
+Exit status:
+
+@display
+0   if no @var{command} is specified and the niceness is output
+125 if @command{nice} itself fails
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+the exit status of @var{command} otherwise
+@end display
+
+It is sometimes useful to run a non-interactive program with reduced niceness.
+
+@example
+$ nice factor 4611686018427387903
+@end example
+
+Since @command{nice} prints the current niceness,
+you can invoke it through itself to demonstrate how it works.
+
+The default behavior is to increase the niceness by @samp{10}:
+
+@example
+$ nice
+0
+$ nice nice
+10
+$ nice -n 10 nice
+10
+@end example
+
+The @var{adjustment} is relative to the current niceness.  In the
+next example, the first @command{nice} invocation runs the second one
+with niceness 10, and it in turn runs the final one with a niceness
+that is 3 more:
+
+@example
+$ nice nice -n 3 nice
+13
+@end example
+
+Specifying a niceness larger than the supported range
+is the same as specifying the maximum supported value:
+
+@example
+$ nice -n 10000000000 nice
+19
+@end example
+
+Only a privileged user may run a process with lower niceness:
+
+@example
+$ nice -n -1 nice
+nice: cannot set niceness: Permission denied
+0
+$ sudo nice -n -1 nice
+-1
+@end example
+
+
+@node nohup invocation
+@section @command{nohup}: Run a command immune to hangups
+
+@pindex nohup
+@cindex hangups, immunity to
+@cindex immunity to hangups
+@cindex logging out and continuing to run
+
+@flindex nohup.out
+@command{nohup} runs the given @var{command} with hangup signals ignored,
+so that the command can continue running in the background after you log
+out.  Synopsis:
+
+@example
+nohup @var{command} [@var{arg}]@dots{}
+@end example
+
+If standard input is a terminal, redirect it so that terminal sessions
+do not mistakenly consider the terminal to be used by the command.
+Make the substitute file descriptor unreadable, so that commands that
+mistakenly attempt to read from standard input can report an error.
+This redirection is a GNU extension; programs intended to be portable
+to non-GNU hosts can use @samp{nohup @var{command} [@var{arg}]@dots{}
+0>/dev/null} instead.
+
+@flindex nohup.out
+If standard output is a terminal, the command's standard output is appended
+to the file @file{nohup.out}; if that cannot be written to, it is appended
+to the file @file{$HOME/nohup.out}; and if that cannot be written to, the
+command is not run.
+Any @file{nohup.out} or @file{$HOME/nohup.out} file created by
+@command{nohup} is made readable and writable only to the user,
+regardless of the current umask settings.
+
+If standard error is a terminal, it is normally redirected to the same file
+descriptor as the (possibly-redirected) standard output.
+However, if standard output is closed, standard error terminal output
+is instead appended to the file @file{nohup.out} or
+@file{$HOME/nohup.out} as above.
+
+To capture the command's output to a file other than @file{nohup.out}
+you can redirect it.  For example, to capture the output of
+@command{make}:
+
+@example
+nohup make > make.log
+@end example
+
+@command{nohup} does not automatically put the command it runs in the
+background; you must do that explicitly, by ending the command line
+with an @samp{&}.  Also, @command{nohup} does not alter the
+niceness of @var{command}; use @command{nice} for that,
+e.g., @samp{nohup nice @var{command}}.
+
+@var{command} must not be a special built-in utility (@pxref{Special
+built-in utilities}).
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.  Options must precede operands.
+
+@cindex exit status of @command{nohup}
+Exit status:
+
+@display
+125 if @command{nohup} itself fails, and @env{POSIXLY_CORRECT} is not set
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+the exit status of @var{command} otherwise
+@end display
+
+If @env{POSIXLY_CORRECT} is set, internal failures give status 127
+instead of 125.
+
+
+@node stdbuf invocation
+@section @command{stdbuf}: Run a command with modified I/O stream buffering
+
+@pindex stdbuf
+@cindex standard streams, buffering
+@cindex line buffered
+
+@command{stdbuf} allows one to modify the buffering operations of the
+three standard I/O streams associated with a program.  Synopsis:
+
+@example
+stdbuf @var{option}@dots{} @var{command}
+@end example
+
+@var{command} must start with the name of a program that
+@enumerate
+@item
+uses the ISO C @code{FILE} streams for input/output (note the
+programs @command{dd} and @command{cat} don't do that),
+
+@item
+does not adjust the buffering of its standard streams (note the
+program @command{tee} is not in this category).
+@end enumerate
+
+Any additional @var{arg}s are passed as additional arguments to the
+@var{command}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item -i @var{mode}
+@itemx --input=@var{mode}
+@opindex -i
+@opindex --input
+Adjust the standard input stream buffering.
+
+@item -o @var{mode}
+@itemx --output=@var{mode}
+@opindex -o
+@opindex --output
+Adjust the standard output stream buffering.
+
+@item -e @var{mode}
+@itemx --error=@var{mode}
+@opindex -e
+@opindex --error
+Adjust the standard error stream buffering.
+
+@end table
+
+The @var{mode} can be specified as follows:
+
+@table @samp
+
+@item L
+Set the stream to line buffered mode.
+In this mode data is coalesced until a newline is output or
+input is read from any stream attached to a terminal device.
+This option is invalid with standard input.
+
+@item 0
+Disable buffering of the selected stream.
+In this mode, data is output immediately and only the
+amount of data requested is read from input.
+Note the difference in function for input and output.
+Disabling buffering for input will not influence the responsiveness
+or blocking behavior of the stream input functions.
+For example @code{fread} will still block until @code{EOF} or error,
+even if the underlying @code{read} returns less data than requested.
+
+@item @var{size}
+Specify the size of the buffer to use in fully buffered mode.
+@multiplierSuffixesNoBlocks{size}
+
+@end table
+
+@command{stdbuf} is installed only on platforms that use the
+Executable and Linkable Format (ELF) and support the
+@code{constructor} attribute, so portable scripts should not rely on
+its existence.
+
+@cindex exit status of @command{stdbuf}
+Exit status:
+
+@display
+125 if @command{stdbuf} itself fails
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+the exit status of @var{command} otherwise
+@end display
+
+
+@node timeout invocation
+@section @command{timeout}: Run a command with a time limit
+
+@pindex timeout
+@cindex time limit
+@cindex run commands with bounded time
+
+@command{timeout} runs the given @var{command} and kills it if it is
+still running after the specified time interval.  Synopsis:
+
+@example
+timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{}
+@end example
+
+@var{command} must not be a special built-in utility (@pxref{Special
+built-in utilities}).
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+@item --preserve-status
+@opindex --preserve-status
+Return the exit status of the managed @var{command} on timeout, rather than
+a specific exit status indicating a timeout.  This is useful if the
+managed @var{command} supports running for an indeterminate amount of time.
+
+@item --foreground
+@opindex --foreground
+Don't create a separate background program group, so that
+the managed @var{command} can use the foreground TTY normally.
+This is needed to support two situations when timing out commands,
+when not invoking @command{timeout} from an interactive shell.
+@enumerate
+@item
+@var{command} is interactive and needs to read from the terminal for example
+@item
+the user wants to support sending signals directly to @var{command}
+from the terminal (like Ctrl-C for example)
+@end enumerate
+
+Note in this mode of operation, any children of @var{command}
+will not be timed out.  Also SIGCONT will not be sent to @var{command},
+as it's generally not needed with foreground processes, and can
+cause intermittent signal delivery issues with programs that are monitors
+themselves (like GDB for example).
+
+@item -k @var{duration}
+@itemx --kill-after=@var{duration}
+@opindex -k
+@opindex --kill-after
+Ensure the monitored @var{command} is killed by also sending a @samp{KILL}
+signal.
+
+The specified @var{duration} starts from the point in time when
+@command{timeout} sends the initial signal to @var{command}, i.e.,
+not from the beginning when the @var{command} is started.
+
+This option has no effect if either the main @var{duration}
+of the @command{timeout} command, or the @var{duration} specified
+to this option, is 0.
+
+This option may be useful if the selected signal did not kill the @var{command},
+either because the signal was blocked or ignored, or if the @var{command} takes
+too long (e.g. for cleanup work) to terminate itself within a certain amount
+of time.
+
+@item -s @var{signal}
+@itemx --signal=@var{signal}
+@opindex -s
+@opindex --signal
+Send this @var{signal} to @var{command} on timeout, rather than the
+default @samp{TERM} signal.  @var{signal} may be a name like @samp{HUP}
+or a number.  @xref{Signal specifications}.
+
+@item -v
+@itemx --verbose
+@opindex -v
+@opindex --verbose
+Diagnose to standard error, any signal sent upon timeout.
+@end table
+
+@cindex time units
+@var{duration} is a floating point number in either the current or the
+C locale (@pxref{Floating point}) followed by an optional unit:
+@display
+@samp{s} for seconds (the default)
+@samp{m} for minutes
+@samp{h} for hours
+@samp{d} for days
+@end display
+A duration of 0 disables the associated timeout.
+Note that the actual timeout duration is dependent on system conditions,
+which should be especially considered when specifying sub-second timeouts.
+
+@cindex exit status of @command{timeout}
+Exit status:
+
+@display
+124 if @var{command} times out, and @option{--preserve-status} is not specified
+125 if @command{timeout} itself fails
+126 if @var{command} is found but cannot be invoked
+127 if @var{command} cannot be found
+137 if @var{command} or @command{timeout} is sent the KILL(9) signal (128+9)
+the exit status of @var{command} otherwise
+@end display
+
+In the case of the @samp{KILL(9)} signal, @command{timeout} returns with
+exit status 137, regardless of whether that signal is sent to @var{command}
+or to @command{timeout} itself, i.e., these cases cannot be distinguished.
+In the latter case, the @var{command} process may still be alive after
+@command{timeout} has forcefully been terminated.
+
+Examples:
+
+@example
+# Send the default TERM signal after 20s to a short-living 'sleep 1'.
+# As that terminates long before the given duration, 'timeout' returns
+# with the same exit status as the command, 0 in this case.
+timeout 20 sleep 1
+
+# Send the INT signal after 5s to the 'sleep' command.  Returns after
+# 5 seconds with exit status 124 to indicate the sending of the signal.
+timeout -s INT 5 sleep 20
+
+# Likewise, but the command ignoring the INT signal due to being started
+# via 'env --ignore-signal'.  Thus, 'sleep' terminates regularly after
+# the full 20 seconds, still 'timeout' returns with exit status 124.
+timeout -s INT 5s env --ignore-signal=INT sleep 20
+
+# Likewise, but sending the KILL signal 3 seconds after the initial
+# INT signal.  Hence, 'sleep' is forcefully terminated after about
+# 8 seconds (5+3), and 'timeout' returns with an exit status of 137.
+timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20
+@end example
+
+@node Process control
+@chapter Process control
+
+@cindex processes, commands for controlling
+@cindex commands for controlling processes
+
+@menu
+* kill invocation::             Sending a signal to processes.
+@end menu
+
+
+@node kill invocation
+@section @command{kill}: Send a signal to processes
+
+@pindex kill
+@cindex send a signal to processes
+
+The @command{kill} command sends a signal to processes, causing them
+to terminate or otherwise act upon receiving the signal in some way.
+Alternatively, it lists information about signals.  Synopses:
+
+@example
+kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{}
+kill [-l | --list | -t | --table] [@var{signal}]@dots{}
+@end example
+
+@mayConflictWithShellBuiltIn{kill}
+
+The first form of the @command{kill} command sends a signal to all
+@var{pid} arguments.  The default signal to send if none is specified
+is @samp{TERM}@.  The special signal number @samp{0} does not denote a
+valid signal, but can be used to test whether the @var{pid} arguments
+specify processes to which a signal could be sent.
+
+If @var{pid} is positive, the signal is sent to the process with the
+process ID @var{pid}.  If @var{pid} is zero, the signal is sent to all
+processes in the process group of the current process.  If @var{pid}
+is @minus{}1, the signal is sent to all processes for which the user has
+permission to send a signal.  If @var{pid} is less than @minus{}1, the signal
+is sent to all processes in the process group that equals the absolute
+value of @var{pid}.
+
+If @var{pid} is not positive, a system-dependent set of system
+processes is excluded from the list of processes to which the signal
+is sent.
+
+If a negative @var{pid} argument is desired as the first one, it
+should be preceded by @option{--}.  However, as a common extension to
+POSIX, @option{--} is not required with @samp{kill
+-@var{signal} -@var{pid}}.  The following commands are equivalent:
+
+@example
+kill -15 -1
+kill -TERM -1
+kill -s TERM -- -1
+kill -- -1
+@end example
+
+The first form of the @command{kill} command succeeds if every @var{pid}
+argument specifies at least one process that the signal was sent to.
+
+The second form of the @command{kill} command lists signal information.
+Either the @option{-l} or @option{--list} option, or the @option{-t}
+or @option{--table} option must be specified.  Without any
+@var{signal} argument, all supported signals are listed.  The output
+of @option{-l} or @option{--list} is a list of the signal names, one
+per line; if @var{signal} is already a name, the signal number is
+printed instead.  The output of @option{-t} or @option{--table} is a
+table of signal numbers, names, and descriptions.  This form of the
+@command{kill} command succeeds if all @var{signal} arguments are valid
+and if there is no output error.
+
+The @command{kill} command also supports the @option{--help} and
+@option{--version} options.  @xref{Common options}.
+
+A @var{signal} may be a signal name like @samp{HUP}, or a signal
+number like @samp{1}, or an exit status of a process terminated by the
+signal.  A signal name can be given in canonical form or prefixed by
+@samp{SIG}@.  The case of the letters is ignored, except for the
+@option{-@var{signal}} option which must use upper case to avoid
+ambiguity with lower case option letters.
+@xref{Signal specifications}, for a list of supported
+signal names and numbers.
+
+@node Delaying
+@chapter Delaying
+
+@cindex delaying commands
+@cindex commands for delaying
+
+@c Perhaps @command{wait} or other commands should be described here also?
+
+@menu
+* sleep invocation::            Delay for a specified time.
+@end menu
+
+
+@node sleep invocation
+@section @command{sleep}: Delay for a specified time
+
+@pindex sleep
+@cindex delay for a specified time
+
+@command{sleep} pauses for an amount of time specified by the sum of
+the values of the command line arguments.
+Synopsis:
+
+@example
+sleep @var{number}[smhd]@dots{}
+@end example
+
+@cindex time units
+Each argument is a non-negative number followed by an optional unit; the default
+is seconds.  The units are:
+
+@table @samp
+@item s
+seconds
+@item m
+minutes
+@item h
+hours
+@item d
+days
+@end table
+
+Although portable POSIX scripts must give @command{sleep} a single
+non-negative integer argument without a suffix, GNU @command{sleep}
+also accepts two or more arguments, unit suffixes, and floating-point
+numbers in either the current or the C locale.  @xref{Floating point}.
+
+For instance, the following could be used to @command{sleep} for
+1 second, 234 milli-, 567 micro- and 890 nanoseconds:
+
+@example
+sleep 1234e-3 567.89e-6
+@end example
+
+Also one could sleep indefinitely like:
+
+@example
+sleep inf
+@end example
+
+The only options are @option{--help} and @option{--version}.  @xref{Common
+options}.
+
+@c sleep is a shell built-in at least with Solaris 11's /bin/sh
+@mayConflictWithShellBuiltIn{sleep}
+
+@exitstatus
+
+
+@node Numeric operations
+@chapter Numeric operations
+
+@cindex numeric operations
+These programs do numerically-related operations.
+
+@menu
+* factor invocation::              Show factors of numbers.
+* numfmt invocation::              Reformat numbers.
+* seq invocation::                 Print sequences of numbers.
+@end menu
+
+
+@node factor invocation
+@section @command{factor}: Print prime factors
+
+@pindex factor
+@cindex prime factors
+
+@command{factor} prints prime factors.  Synopsis:
+
+@example
+factor [@var{option}]@dots{} [@var{number}]@dots{}
+@end example
+
+If no @var{number} is specified on the command line, @command{factor} reads
+numbers from standard input, delimited by newlines, tabs, or spaces.
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+@item -h
+@itemx --exponents
+@opindex -h
+@opindex --exponents
+print factors in the form @math{p^e}, rather than repeating
+the prime @samp{p}, @samp{e} times. If the exponent @samp{e} is 1,
+then it is omitted.
+
+@example
+$ factor --exponents 3000
+3000: 2^3 3 5^3
+@end example
+@end table
+
+If the number to be factored is small (less than @math{2^{127}} on
+typical machines), @command{factor} uses a faster algorithm.
+For example, on a circa-2017 Intel Xeon Silver 4116, factoring the
+product of the eighth and ninth Mersenne primes (approximately
+@math{2^{92}}) takes about 4 ms of CPU time:
+
+@example
+$ M8=$(echo 2^31-1 | bc)
+$ M9=$(echo 2^61-1 | bc)
+$ n=$(echo "$M8 * $M9" | bc)
+$ bash -c "time factor $n"
+4951760154835678088235319297: 2147483647 2305843009213693951
+
+real	0m0.004s
+user	0m0.004s
+sys	0m0.000s
+@end example
+
+For larger numbers, @command{factor} uses a slower algorithm.  On the
+same platform, factoring the eighth Fermat number @math{2^{256} + 1}
+takes about 14 seconds, and the slower algorithm would have taken
+about 750 ms to factor @math{2^{127} - 3} instead of the 50 ms needed by
+the faster algorithm.
+
+Factoring large numbers is, in general, hard.  The Pollard-Brent rho
+algorithm used by @command{factor} is particularly effective for
+numbers with relatively small factors.  If you wish to factor large
+numbers which do not have small factors (for example, numbers which
+are the product of two large primes), other methods are far better.
+
+@exitstatus
+
+
+@node numfmt invocation
+@section @command{numfmt}: Reformat numbers
+
+@pindex numfmt
+
+@command{numfmt} reads numbers in various representations and reformats them
+as requested.  The most common usage is converting numbers to/from @emph{human}
+representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}).
+
+@example
+numfmt [@var{option}]@dots{} [@var{number}]
+@end example
+
+@command{numfmt} converts each @var{number} on the command-line according to the
+specified options (see below).  If no @var{number}s are given, it reads numbers
+from standard input.  @command{numfmt} can optionally extract numbers from
+specific columns, maintaining proper line padding and alignment.
+
+@exitstatus
+
+See @option{--invalid} for additional information regarding exit status.
+
+@subsection General options
+
+The program accepts the following options.  Also see @ref{Common options}.
+
+@table @samp
+
+@item --debug
+@opindex --debug
+Print (to standard error) warning messages about possible erroneous usage.
+
+@item -d @var{d}
+@itemx --delimiter=@var{d}
+@opindex -d
+@opindex --delimiter
+Use the character @var{d} as input field separator (default: whitespace).
+@emph{Note}: Using non-default delimiter turns off automatic padding.
+
+@item --field=@var{fields}
+@opindex --field
+Convert the number in input field @var{fields} (default: 1).
+@var{fields} supports @command{cut} style field ranges:
+
+@example
+N    N'th field, counted from 1
+N-   from N'th field, to end of line
+N-M  from N'th to M'th field (inclusive)
+-M   from first to M'th field (inclusive)
+-    all fields
+@end example
+
+
+@item --format=@var{format}
+@opindex --format
+Use printf-style floating FORMAT string.  The @var{format} string must contain
+one @samp{%f} directive, optionally with @samp{'}, @samp{-}, @samp{0}, width
+or precision modifiers.  The @samp{'} modifier will enable @option{--grouping},
+the @samp{-} modifier will enable left-aligned @option{--padding} and the width
+modifier will enable right-aligned @option{--padding}.  The @samp{0} width
+modifier (without the @samp{-} modifier) will generate leading zeros on the
+number, up to the specified width.  A precision specification like @samp{%.1f}
+will override the precision determined from the input data or set due to
+@option{--to} option auto scaling.
+
+@item --from=@var{unit}
+@opindex --from
+Auto-scales input numbers according to @var{unit}.  See UNITS below.
+The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will
+trigger an error.
+
+@item --from-unit=@var{n}
+@opindex --from-unit
+Specify the input unit size (instead of the default 1).  Use this option when
+the input numbers represent other units (e.g. if the input number @samp{10}
+represents 10 units of 512 bytes, use @samp{--from-unit=512}).
+Suffixes are handled as with @samp{--from=auto}.
+
+@item --grouping
+@opindex --grouping
+Group digits in output numbers according to the current locale's grouping rules
+(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,}
+comma).  This option has no effect in @samp{POSIX/C} locale.
+
+@item --header[=@var{n}]
+@opindex --header
+@opindex --header=N
+Print the first @var{n} (default: 1) lines without any conversion.
+
+@item --invalid=@var{mode}
+@opindex --invalid
+The default action on input errors is to exit immediately with status code 2.
+@option{--invalid=@samp{abort}} explicitly specifies this default mode.
+With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion
+error, and exit with status 2.  With a @var{mode} of @samp{warn}, exit with
+status 0, even in the presence of conversion errors, and with a @var{mode} of
+@samp{ignore} do not even print diagnostics.
+
+@item --padding=@var{n}
+@opindex --padding
+Pad the output numbers to @var{n} characters, by adding spaces.  If @var{n} is
+a positive number, numbers will be right-aligned.  If @var{n} is a negative
+number, numbers will be left-aligned.  By default, numbers are automatically
+aligned based on the input line's width (only with the default delimiter).
+
+@item --round=@var{method}
+@opindex --round
+@opindex --round=up
+@opindex --round=down
+@opindex --round=from-zero
+@opindex --round=towards-zero
+@opindex --round=nearest
+When converting number representations, round the number according to
+@var{method}, which can be @samp{up}, @samp{down},
+@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}.
+
+@item --suffix=@var{suffix}
+@opindex --suffix
+Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in
+input numbers.
+
+@item --to=@var{unit}
+@opindex --to
+Auto-scales output numbers according to @var{unit}.  See @emph{Units} below.
+The default is no scaling, meaning all the digits of the number are printed.
+
+@item --to-unit=@var{n}
+@opindex --to-unit
+Specify the output unit size (instead of the default 1).  Use this option when
+the output numbers represent other units (e.g. to represent @samp{4,000,000}
+bytes in blocks of 1KB, use @samp{--to=si --to-unit=1000}).
+Suffixes are handled as with @samp{--from=auto}.
+
+@optZeroTerminated
+@newlineFieldSeparator
+
+@end table
+
+@subsection Possible @var{unit}s:
+
+The following are the possible @var{unit} options with @option{--from=UNITS} and
+@option{--to=UNITS}:
+
+@table @var
+
+@item none
+No scaling is performed.  For input numbers, no suffixes are accepted, and any
+trailing characters following the number will trigger an error.  For output
+numbers, all digits of the numbers will be printed.
+
+@item si
+Auto-scale numbers according to the @emph{International System of Units (SI)}
+standard.
+For input numbers, accept one of the following suffixes.
+For output numbers, values larger than 1000 will be rounded, and printed with
+one of the following suffixes:
+
+@example
+@samp{K}  =>  @math{1000^1 = 10^3} (Kilo)
+@samp{M}  =>  @math{1000^2 = 10^6} (Mega)
+@samp{G}  =>  @math{1000^3 = 10^9} (Giga)
+@samp{T}  =>  @math{1000^4 = 10^{12}} (Tera)
+@samp{P}  =>  @math{1000^5 = 10^{15}} (Peta)
+@samp{E}  =>  @math{1000^6 = 10^{18}} (Exa)
+@samp{Z}  =>  @math{1000^7 = 10^{21}} (Zetta)
+@samp{Y}  =>  @math{1000^8 = 10^{24}} (Yotta)
+@samp{R}  =>  @math{1000^9 = 10^{27}} (Ronna)
+@samp{Q}  =>  @math{1000^{10} = 10^{30}} (Quetta)
+@end example
+
+@item iec
+Auto-scale numbers according to the @emph{International Electrotechnical
+Commission (IEC)} standard.
+For input numbers, accept one of the following suffixes.
+For output numbers, values larger than 1024 will be rounded, and printed with
+one of the following suffixes:
+
+@example
+@samp{K}  =>  @math{1024^1 = 2^{10}} (Kibi)
+@samp{M}  =>  @math{1024^2 = 2^{20}} (Mebi)
+@samp{G}  =>  @math{1024^3 = 2^{30}} (Gibi)
+@samp{T}  =>  @math{1024^4 = 2^{40}} (Tebi)
+@samp{P}  =>  @math{1024^5 = 2^{50}} (Pebi)
+@samp{E}  =>  @math{1024^6 = 2^{60}} (Exbi)
+@samp{Z}  =>  @math{1024^7 = 2^{70}} (Zebi)
+@samp{Y}  =>  @math{1024^8 = 2^{80}} (Yobi)
+@samp{R}  =>  @math{1024^9 = 2^{90}} (Robi)
+@samp{Q}  =>  @math{1024^{10} = 2^{100}} (Quebi)
+@end example
+
+The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is
+not fully standard, as the @emph{iec} standard recommends a two-letter symbol
+(e.g @samp{Gi}) -- but in practice, this method is common.  Compare with
+the @option{iec-i} option.
+
+@item iec-i
+Auto-scale numbers according to the @emph{International Electrotechnical
+Commission (IEC)} standard.
+For input numbers, accept one of the following suffixes.
+For output numbers, values larger than 1024 will be rounded, and printed with
+one of the following suffixes:
+
+@example
+@samp{Ki}  =>  @math{1024^1 = 2^{10}} (Kibi)
+@samp{Mi}  =>  @math{1024^2 = 2^{20}} (Mebi)
+@samp{Gi}  =>  @math{1024^3 = 2^{30}} (Gibi)
+@samp{Ti}  =>  @math{1024^4 = 2^{40}} (Tebi)
+@samp{Pi}  =>  @math{1024^5 = 2^{50}} (Pebi)
+@samp{Ei}  =>  @math{1024^6 = 2^{60}} (Exbi)
+@samp{Zi}  =>  @math{1024^7 = 2^{70}} (Zebi)
+@samp{Yi}  =>  @math{1024^8 = 2^{80}} (Yobi)
+@samp{Ri}  =>  @math{1024^9 = 2^{90}} (Robi)
+@samp{Qi}  =>  @math{1024^{10} = 2^{100}} (Quebi)
+@end example
+
+The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}),
+as the @emph{iec} standard recommends, but this is not always common in
+practice.  Compare with the @option{iec} option.
+
+@item auto
+@samp{auto} can only be used with @option{--from}.  With this method, numbers
+with single-letter suffixes like @samp{K}
+suffixes are interpreted as @emph{SI} values, and numbers with
+two-letter suffixes like @samp{Ki}
+are interpreted as @emph{IEC} values.
+
+@end table
+
+@subsection Examples of using @command{numfmt}
+
+Converting a single number from/to @emph{human} representation:
+@example
+$ numfmt --to=si 500000
+500K
+
+$ numfmt --to=iec 500000
+489K
+
+$ numfmt --to=iec-i 500000
+489Ki
+
+$ numfmt --from=si 1M
+1000000
+
+$ numfmt --from=iec 1M
+1048576
+
+# with '--from=auto', M=Mega, Mi=Mebi
+$ numfmt --from=auto 1M
+1000000
+$ numfmt --from=auto 1Mi
+1048576
+@end example
+
+Converting from @samp{SI} to @samp{IEC} scales (e.g. when a drive's capacity is
+advertised as @samp{1TB}, while checking the drive's capacity gives lower
+values):
+
+@example
+$ numfmt --from=si --to=iec 1T
+932G
+@end example
+
+With both input and output scales specified,
+the largest defined prefixes are supported:
+
+@example
+$ numfmt --from=si --to=iec-i 2000R
+1.6Qi
+@end example
+
+Converting a single field from an input file / piped input (these contrived
+examples are for demonstration purposes only, as both @command{ls} and
+@command{df} support the @option{--human-readable} option to
+output sizes in human-readable format):
+
+@example
+# Third field (file size) will be shown in SI representation
+$ ls -log | numfmt --field 3 --header --to=si | head -n4
+-rw-r--r--  1     94K Aug 23  2011 ABOUT-NLS
+-rw-r--r--  1    3.7K Jan  7 16:15 AUTHORS
+-rw-r--r--  1     36K Jun  1  2011 COPYING
+-rw-r--r--  1       0 Jan  7 15:15 ChangeLog
+
+# Second field (size) will be shown in IEC representation
+$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4
+File system   1B-blocks        Used  Available Use% Mounted on
+rootfs             132G   104741408   26554036  80% /
+tmpfs              794M        7580     804960   1% /run/shm
+/dev/sdb1          694G   651424756   46074696  94% /home
+@end example
+
+
+Output can be tweaked using @option{--padding} or @option{--format}:
+
+@example
+# Pad to 10 characters, right-aligned
+$ du -s * | numfmt --to=si --padding=10
+      2.5K config.log
+       108 config.status
+      1.7K configure
+        20 configure.ac
+
+# Pad to 10 characters, left-aligned
+$ du -s * | numfmt --to=si --padding=-10
+2.5K       config.log
+108        config.status
+1.7K       configure
+20         configure.ac
+
+# Pad to 10 characters, left-aligned, using 'format'
+$ du -s * | numfmt --to=si --format="%10f"
+      2.5K config.log
+       108 config.status
+      1.7K configure
+        20 configure.ac
+
+# Pad to 10 characters, left-aligned, using 'format'
+$ du -s * | numfmt --to=si --padding="%-10f"
+2.5K       config.log
+108        config.status
+1.7K       configure
+20         configure.ac
+@end example
+
+With locales that support grouping digits, using @option{--grouping} or
+@option{--format} enables grouping.  In @samp{POSIX} locale, grouping is
+silently ignored:
+
+@example
+$ LC_ALL=C numfmt --from=iec --grouping 2G
+2147483648
+
+$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G
+2,147,483,648
+
+$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G
+2,14,74,83,648
+
+$ LC_ALL=C numfmt --from=iec --format="==%'15f==" 2G
+==     2147483648==
+
+$ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'15f==" 2G
+==  2,147,483,648==
+
+$ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'-15f==" 2G
+==2,147,483,648  ==
+
+$ LC_ALL=ta_IN numfmt --from=iec --format="==%'15f==" 2G
+== 2,14,74,83,648==
+@end example
+
+
+@node seq invocation
+@section @command{seq}: Print numeric sequences
+
+@pindex seq
+@cindex numeric sequences
+@cindex sequence of numbers
+
+@command{seq} prints a sequence of numbers to standard output.  Synopses:
+
+@example
+seq [@var{option}]@dots{} @var{last}
+seq [@var{option}]@dots{} @var{first} @var{last}
+seq [@var{option}]@dots{} @var{first} @var{increment} @var{last}
+@end example
+
+@command{seq} prints the numbers from @var{first} to @var{last} by
+@var{increment}.  By default, each number is printed on a separate line.
+When @var{increment} is not specified, it defaults to @samp{1},
+even when @var{first} is larger than @var{last}.
+@var{first} also defaults to @samp{1}.  So @code{seq 1} prints
+@samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output.
+The sequence of numbers ends when the sum of the current number and
+@var{increment} would become greater than @var{last},
+so @code{seq 1 10 10} only produces @samp{1}.
+@var{increment} must not be @samp{0}; use the tool @command{yes} to get
+repeated output of a constant number.
+@var{first}, @var{increment} and @var{last} must not be @code{NaN},
+but @code{inf} is supported.
+Floating-point numbers may be specified in either the current or
+the C locale.  @xref{Floating point}.
+
+The program accepts the following options.  Also see @ref{Common options}.
+Options must precede operands.
+
+@table @samp
+@item -f @var{format}
+@itemx --format=@var{format}
+@opindex -f
+@opindex --format
+@cindex formatting of numbers in @command{seq}
+Print all numbers using @var{format}.
+@var{format} must contain exactly one of the @samp{printf}-style
+floating point conversion specifications @samp{%a}, @samp{%e},
+@samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}@.
+The @samp{%} may be followed by zero or more flags taken from the set
+@samp{-+#0 '}, then an optional width containing one or more digits,
+then an optional precision consisting of a @samp{.} followed by zero
+or more digits.  @var{format} may also contain any number of @samp{%%}
+conversion specifications.  All conversion specifications have the
+same meaning as with @samp{printf}.
+
+The default format is derived from @var{first}, @var{step}, and
+@var{last}.  If these all use a fixed point decimal representation,
+the default format is @samp{%.@var{p}f}, where @var{p} is the minimum
+precision that can represent the output numbers exactly.  Otherwise,
+the default format is @samp{%g}.
+
+@item -s @var{string}
+@itemx --separator=@var{string}
+@opindex -s
+@opindex --separator
+@cindex separator for numbers in @command{seq}
+Separate numbers with @var{string}; default is a newline.
+The output always terminates with a newline.
+
+@item -w
+@itemx --equal-width
+@opindex -w
+@opindex --equal-width
+Print all numbers with the same width, by padding with leading zeros.
+@var{first}, @var{step}, and @var{last} should all use a fixed point
+decimal representation.
+(To have other kinds of padding, use @option{--format}).
+
+@end table
+
+You can get finer-grained control over output with @option{-f}:
+
+@example
+$ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6
+(-9.00E+05)
+( 2.00E+05)
+( 1.30E+06)
+@end example
+
+If you want hexadecimal integer output, you can use @command{printf}
+to perform the conversion:
+
+@example
+$ printf '%x\n' $(seq 1048575 1024 1050623)
+fffff
+1003ff
+1007ff
+@end example
+
+For very long lists of numbers, use xargs to avoid
+system limitations on the length of an argument list:
+
+@example
+$ seq 1000000 | xargs printf '%x\n' | tail -n 3
+f423e
+f423f
+f4240
+@end example
+
+To generate octal output, use the printf @code{%o} format instead
+of @code{%x}.
+
+On most systems, seq can produce whole-number output for values up to
+at least @math{2^{53}}.  Larger integers are approximated.  The details
+differ depending on your floating-point implementation.
+@xref{Floating point}.  A common
+case is that @command{seq} works with integers through @math{2^{64}},
+and larger integers may not be numerically correct:
+
+@example
+$ seq 50000000000000000000 2 50000000000000000004
+50000000000000000000
+50000000000000000000
+50000000000000000004
+@end example
+
+However, note that when limited to non-negative whole numbers,
+an increment of less than 200, and no format-specifying option,
+seq can print arbitrarily large numbers.
+Therefore @command{seq inf} can be used to
+generate an infinite sequence of numbers.
+
+Be careful when using @command{seq} with outlandish values: otherwise
+you may see surprising results, as @command{seq} uses floating point
+internally.  For example, on the x86 platform, where the internal
+representation uses a 64-bit fraction, the command:
+
+@example
+seq 1 0.0000000000000000001 1.0000000000000000009
+@end example
+
+outputs 1.0000000000000000007 twice and skips 1.0000000000000000008.
+
+@exitstatus
+
+
+@node File permissions
+@chapter File permissions
+@include perm.texi
+
+
+@node File timestamps
+@chapter File timestamps
+
+@cindex atime
+@cindex birthtime
+@cindex ctime
+@cindex mtime
+Standard POSIX files have three timestamps: the access timestamp
+(atime) of the last read, the modification timestamp (mtime) of the
+last write, and the status change timestamp (ctime) of the last change
+to the file's meta-information.  Some file systems support a
+fourth time: the birth timestamp (birthtime) of when the file was
+created; by definition, birthtime never changes.
+
+One common example of a ctime change is when the permissions of a file
+change.  Changing the permissions doesn't access the file, so atime
+doesn't change, nor does it modify the file, so the mtime doesn't
+change.  Yet, something about the file itself has changed, and this
+must be noted somewhere.  This is the job of the ctime field.  This is
+necessary, so that, for example, a backup program can make a fresh
+copy of the file, including the new permissions value.  Another
+operation that modifies a file's ctime without affecting the others is
+renaming.
+
+Naively, a file's atime, mtime, and ctime are set to the current time
+whenever you read, write, or change the attributes of the file
+respectively, and searching a directory counts as reading it.  A
+file's atime and mtime can also be set directly, via the
+@command{touch} command (@pxref{touch invocation}).  In practice,
+though, timestamps are not updated quite that way.
+
+For efficiency reasons, many systems are lazy about updating atimes:
+when a program accesses a file, they may delay updating the file's
+atime, or may not update the file's atime if the file has been
+accessed recently, or may not update the atime at all.  Similar
+laziness, though typically not quite so extreme, applies to mtimes and
+ctimes.
+
+Some systems emulate timestamps instead of supporting them directly,
+and these emulations may disagree with the naive interpretation.  For
+example, a system may fake an atime or ctime by using the mtime.
+
+@cindex clock skew
+The determination of what time is ``current'' depends on the
+platform.  Platforms with network file systems often use different
+clocks for the operating system and for file systems; because
+updates typically uses file systems' clocks by default, clock
+skew can cause the resulting file timestamps to appear to be in a
+program's ``future'' or ``past''.
+
+@cindex file timestamp resolution
+When the system updates a file timestamp to a desired time @var{t}
+(which is either the current time, or a time specified via the
+@command{touch} command), there are several reasons the file's
+timestamp may be set to a value that differs from @var{t}.  First,
+@var{t} may have a higher resolution than supported.  Second, a file
+system may use different resolutions for different types of times.
+Third, file timestamps may use a different resolution than operating
+system timestamps.  Fourth, the operating system primitives used to
+update timestamps may employ yet a different resolution.  For example,
+in theory a file system might use 10-microsecond resolution for access
+timestamp and 100-nanosecond resolution for modification timestamp, and the
+operating system might use nanosecond resolution for the current time
+and microsecond resolution for the primitive that @command{touch} uses
+to set a file's timestamp to an arbitrary value.
+
+
+@include parse-datetime.texi
+
+@include sort-version.texi
+
+@c              What's GNU?
+@c              Arnold Robbins
+@node Opening the software toolbox
+@chapter Opening the Software Toolbox
+
+An earlier version of this chapter appeared in
+@uref{https://www.linuxjournal.com/article.php?sid=2762, the
+@cite{What's GNU@?} column of the June 1994 @cite{Linux Journal}}.
+It was written by Arnold Robbins.
+
+@menu
+* Toolbox introduction::        Toolbox introduction
+* I/O redirection::             I/O redirection
+* The who command::             The @command{who} command
+* The cut command::             The @command{cut} command
+* The sort command::            The @command{sort} command
+* The uniq command::            The @command{uniq} command
+* Putting the tools together::  Putting the tools together
+@end menu
+
+
+@node Toolbox introduction
+@unnumberedsec Toolbox Introduction
+
+This month's column is only peripherally related to the GNU Project, in
+that it describes a number of the GNU tools on your GNU/Linux system
+and how they
+might be used.  What it's really about is the ``Software Tools'' philosophy
+of program development and usage.
+
+The software tools philosophy was an important and integral concept
+in the initial design and development of Unix (of which GNU/Linux and GNU are
+essentially clones).  Unfortunately, in the modern day press of
+Internetworking and flashy GUIs, it seems to have fallen by the
+wayside.  This is a shame, since it provides a powerful mental model
+for solving many kinds of problems.
+
+Many people carry a Swiss Army knife around in their pants pockets (or
+purse).  A Swiss Army knife is a handy tool to have: it has several knife
+blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps
+a number of other things on it.  For the everyday, small miscellaneous jobs
+where you need a simple, general purpose tool, it's just the thing.
+
+On the other hand, an experienced carpenter doesn't build a house using
+a Swiss Army knife.  Instead, he has a toolbox chock full of specialized
+tools -- a saw, a hammer, a screwdriver, a plane, and so on.  And he knows
+exactly when and where to use each tool; you won't catch him hammering nails
+with the handle of his screwdriver.
+
+The Unix developers at Bell Labs were all professional programmers and trained
+computer scientists.  They had found that while a one-size-fits-all program
+might appeal to a user because there's only one program to use, in practice
+such programs are
+
+@enumerate a
+@item
+difficult to write,
+
+@item
+difficult to maintain and
+debug, and
+
+@item
+difficult to extend to meet new situations.
+@end enumerate
+
+Instead, they felt that programs should be specialized tools.  In short, each
+program ``should do one thing well.''  No more and no less.  Such programs are
+simpler to design, write, and get right -- they only do one thing.
+
+Furthermore, they found that with the right machinery for hooking programs
+together, that the whole was greater than the sum of the parts.  By combining
+several special purpose programs, you could accomplish a specific task
+that none of the programs was designed for, and accomplish it much more
+quickly and easily than if you had to write a special purpose program.
+We will see some (classic) examples of this further on in the column.
+(An important additional point was that, if necessary, take a detour
+and build any software tools you may need first, if you don't already
+have something appropriate in the toolbox.)
+
+@node I/O redirection
+@unnumberedsec I/O Redirection
+
+Hopefully, you are familiar with the basics of I/O redirection in the
+shell, in particular the concepts of ``standard input,'' ``standard output,''
+and ``standard error''.  Briefly, ``standard input'' is a data source, where
+data comes from.  A program should not need to either know or care if the
+data source is a regular file, a keyboard, a magnetic tape, or even a punched
+card reader.  Similarly, ``standard output'' is a data sink, where data goes
+to.  The program should neither know nor care where this might be.
+Programs that only read their standard input, do something to the data,
+and then send it on, are called @dfn{filters}, by analogy to filters in a
+water pipeline.
+
+With the Unix shell, it's very easy to set up data pipelines:
+
+@example
+program_to_create_data | filter1 | ... | filterN > final.pretty.data
+@end example
+
+We start out by creating the raw data; each filter applies some successive
+transformation to the data, until by the time it comes out of the pipeline,
+it is in the desired form.
+
+This is fine and good for standard input and standard output.  Where does the
+standard error come in to play?  Well, think about @command{filter1} in
+the pipeline above.  What happens if it encounters an error in the data it
+sees?  If it writes an error message to standard output, it will just
+disappear down the pipeline into @command{filter2}'s input, and the
+user will probably never see it.  So programs need a place where they can send
+error messages so that the user will notice them.  This is standard error,
+and it is usually connected to your console or window, even if you have
+redirected standard output of your program away from your screen.
+
+For filter programs to work together, the format of the data has to be
+agreed upon.  The most straightforward and easiest format to use is simply
+lines of text.  Unix data files are generally just streams of bytes, with
+lines delimited by the ASCII LF (Line Feed) character,
+conventionally called a ``newline'' in the Unix literature.  (This is
+@code{'\n'} if you're a C programmer.)  This is the format used by all
+the traditional filtering programs.  (Many earlier operating systems
+had elaborate facilities and special purpose programs for managing
+binary data.  Unix has always shied away from such things, under the
+philosophy that it's easiest to simply be able to view and edit your
+data with a text editor.)
+
+OK, enough introduction.  Let's take a look at some of the tools, and then
+we'll see how to hook them together in interesting ways.   In the following
+discussion, we will only present those command line options that interest
+us.  As you should always do, double check your system documentation
+for the full story.
+
+@node The who command
+@unnumberedsec The @command{who} Command
+
+The first program is the @command{who} command.  By itself, it generates a
+list of the users who are currently logged in.  Although I'm writing
+this on a single-user system, we'll pretend that several people are
+logged in:
+
+@example
+$ who
+@print{} arnold   console Jan 22 19:57
+@print{} miriam   ttyp0   Jan 23 14:19(:0.0)
+@print{} bill     ttyp1   Jan 21 09:32(:0.0)
+@print{} arnold   ttyp2   Jan 23 20:48(:0.0)
+@end example
+
+Here, the @samp{$} is the usual shell prompt, at which I typed @samp{who}.
+There are three people logged in, and I am logged in twice.  On traditional
+Unix systems, user names are never more than eight characters long.  This
+little bit of trivia will be useful later.  The output of @command{who} is nice,
+but the data is not all that exciting.
+
+@node The cut command
+@unnumberedsec The @command{cut} Command
+
+The next program we'll look at is the @command{cut} command.  This program
+cuts out columns or fields of input data.  For example, we can tell it
+to print just the login name and full name from the @file{/etc/passwd}
+file.  The @file{/etc/passwd} file has seven fields, separated by
+colons:
+
+@example
+arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash
+@end example
+
+To get the first and fifth fields, we would use @command{cut} like this:
+
+@example
+$ cut -d: -f1,5 /etc/passwd
+@print{} root:Operator
+@dots{}
+@print{} arnold:Arnold D. Robbins
+@print{} miriam:Miriam A. Robbins
+@dots{}
+@end example
+
+With the @option{-c} option, @command{cut} will cut out specific characters
+(i.e., columns) in the input lines.  This is useful for input data
+that has fixed width fields, and does not have a field separator.  For
+example, list the Monday dates for the current month:
+
+@c Is using cal ok?  Looked at gcal, but I don't like it.
+@example
+$ cal | cut -c 3-5
+@print{}Mo
+@print{}
+@print{}  6
+@print{} 13
+@print{} 20
+@print{} 27
+@end example
+
+@node The sort command
+@unnumberedsec The @command{sort} Command
+
+Next we'll look at the @command{sort} command.  This is one of the most
+powerful commands on a Unix-style system; one that you will often find
+yourself using when setting up fancy data plumbing.
+
+The @command{sort}
+command reads and sorts each file named on the command line.  It then
+merges the sorted data and writes it to standard output.  It will read
+standard input if no files are given on the command line (thus
+making it into a filter).  The sort is based on the character collating
+sequence or based on user-supplied ordering criteria.
+
+
+@node The uniq command
+@unnumberedsec The @command{uniq} Command
+
+Finally (at least for now), we'll look at the @command{uniq} program.  When
+sorting data, you will often end up with duplicate lines, lines that
+are identical.  Usually, all you need is one instance of each line.
+This is where @command{uniq} comes in.  The @command{uniq} program reads its
+standard input.  It prints only one
+copy of each repeated line.  It does have several options.  Later on,
+we'll use the @option{-c} option, which prints each unique line, preceded
+by a count of the number of times that line occurred in the input.
+
+
+@node Putting the tools together
+@unnumberedsec Putting the Tools Together
+
+Now, let's suppose this is a large ISP server system with dozens of users
+logged in.  The management wants the system administrator to write a
+program that will
+generate a sorted list of logged in users.  Furthermore, even if a user
+is logged in multiple times, his or her name should only show up in the
+output once.
+
+The administrator could sit down with the system documentation and write a C
+program that did this.  It would take perhaps a couple of hundred lines
+of code and about two hours to write it, test it, and debug it.
+However, knowing the software toolbox, the administrator can instead start out
+by generating just a list of logged on users:
+
+@example
+$ who | cut -c1-8
+@print{} arnold
+@print{} miriam
+@print{} bill
+@print{} arnold
+@end example
+
+Next, sort the list:
+
+@example
+$ who | cut -c1-8 | sort
+@print{} arnold
+@print{} arnold
+@print{} bill
+@print{} miriam
+@end example
+
+Finally, run the sorted list through @command{uniq}, to weed out duplicates:
+
+@example
+$ who | cut -c1-8 | sort | uniq
+@print{} arnold
+@print{} bill
+@print{} miriam
+@end example
+
+The @command{sort} command actually has a @option{-u} option that does what
+@command{uniq} does.  However, @command{uniq} has other uses for which one
+cannot substitute @samp{sort -u}.
+
+The administrator puts this pipeline into a shell script, and makes it
+available for
+all the users on the system (@samp{#} is the system administrator,
+or @code{root}, prompt):
+
+@example
+# cat > /usr/local/bin/listusers
+who | cut -c1-8 | sort | uniq
+^D
+# chmod +x /usr/local/bin/listusers
+@end example
+
+There are four major points to note here.  First, with just four
+programs, on one command line, the administrator was able to save about two
+hours worth of work.  Furthermore, the shell pipeline is just about as
+efficient as the C program would be, and it is much more efficient in
+terms of programmer time.  People time is much more expensive than
+computer time, and in our modern ``there's never enough time to do
+everything'' society, saving two hours of programmer time is no mean
+feat.
+
+Second, it is also important to emphasize that with the
+@emph{combination} of the tools, it is possible to do a special
+purpose job never imagined by the authors of the individual programs.
+
+Third, it is also valuable to build up your pipeline in stages, as we did here.
+This allows you to view the data at each stage in the pipeline, which helps
+you acquire the confidence that you are indeed using these tools correctly.
+
+Finally, by bundling the pipeline in a shell script, other users can use
+your command, without having to remember the fancy plumbing you set up for
+them.  In terms of how you run them, shell scripts and compiled programs are
+indistinguishable.
+
+After the previous warm-up exercise, we'll look at two additional, more
+complicated pipelines.  For them, we need to introduce two more tools.
+
+The first is the @command{tr} command, which stands for ``transliterate.''
+The @command{tr} command works on a character-by-character basis, changing
+characters.  Normally it is used for things like mapping upper case to
+lower case:
+
+@example
+$ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]'
+@print{} this example has mixed case!
+@end example
+
+There are several options of interest:
+
+@table @code
+@item -c
+work on the complement of the listed characters, i.e.,
+operations apply to characters not in the given set
+
+@item -d
+delete characters in the first set from the output
+
+@item -s
+squeeze repeated characters in the output into just one character.
+@end table
+
+We will be using all three options in a moment.
+
+The other command we'll look at is @command{comm}.  The @command{comm}
+command takes two sorted input files as input data, and prints out the
+files' lines in three columns.  The output columns are the data lines
+unique to the first file, the data lines unique to the second file, and
+the data lines that are common to both.  The @option{-1}, @option{-2}, and
+@option{-3} command line options @emph{omit} the respective columns.  (This is
+non-intuitive and takes a little getting used to.)  For example:
+
+@example
+$ cat f1
+@print{} 11111
+@print{} 22222
+@print{} 33333
+@print{} 44444
+$ cat f2
+@print{} 00000
+@print{} 22222
+@print{} 33333
+@print{} 55555
+$ comm f1 f2
+@print{}         00000
+@print{} 11111
+@print{}                 22222
+@print{}                 33333
+@print{} 44444
+@print{}         55555
+@end example
+
+The file name @file{-} tells @command{comm} to read standard input
+instead of a regular file.
+
+Now we're ready to build a fancy pipeline.  The first application is a word
+frequency counter.  This helps an author determine if he or she is over-using
+certain words.
+
+The first step is to change the case of all the letters in our input file
+to one case.  ``The'' and ``the'' are the same word when doing counting.
+
+@example
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | ...
+@end example
+
+The next step is to get rid of punctuation.  Quoted words and unquoted words
+should be treated identically; it's easiest to just get the punctuation out of
+the way.
+
+@example
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ...
+@end example
+
+The second @command{tr} command operates on the complement of the listed
+characters, which are all the letters, the digits, the underscore, and
+the blank.  The @samp{\n} represents the newline character; it has to
+be left alone.  (The ASCII tab character should also be included for
+good measure in a production script.)
+
+At this point, we have data consisting of words separated by blank space.
+The words only contain alphanumeric characters (and the underscore).  The
+next step is break the data apart so that we have one word per line.  This
+makes the counting operation much easier, as we will see shortly.
+
+@example
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+> tr -s ' ' '\n' | ...
+@end example
+
+This command turns blanks into newlines.  The @option{-s} option squeezes
+multiple newline characters in the output into just one, removing
+blank lines.  (The @samp{>} is the shell's ``secondary prompt.''
+This is what the shell prints when it notices you haven't finished
+typing in all of a command.)
+
+We now have data consisting of one word per line, no punctuation, all one
+case.  We're ready to count each word:
+
+@example
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+> tr -s ' ' '\n' | sort | uniq -c | ...
+@end example
+
+At this point, the data might look something like this:
+
+@example
+     60 a
+      2 able
+      6 about
+      1 above
+      2 accomplish
+      1 acquire
+      1 actually
+      2 additional
+@end example
+
+The output is sorted by word, not by count!  What we want is the most
+frequently used words first.  Fortunately, this is easy to accomplish,
+with the help of two more @command{sort} options:
+
+@table @code
+@item -n
+do a numeric sort, not a textual one
+
+@item -r
+reverse the order of the sort
+@end table
+
+The final pipeline looks like this:
+
+@example
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+> tr -s ' ' '\n' | sort | uniq -c | sort -n -r
+@print{}    156 the
+@print{}     60 a
+@print{}     58 to
+@print{}     51 of
+@print{}     51 and
+@dots{}
+@end example
+
+Whew!  That's a lot to digest.  Yet, the same principles apply.  With six
+commands, on two lines (really one long one split for convenience), we've
+created a program that does something interesting and useful, in much
+less time than we could have written a C program to do the same thing.
+
+A minor modification to the above pipeline can give us a simple spelling
+checker!  To determine if you've spelled a word correctly, all you have to
+do is look it up in a dictionary.  If it is not there, then chances are
+that your spelling is incorrect.  So, we need a dictionary.
+The conventional location for a dictionary is @file{/usr/share/dict/words}.
+
+Now, how to compare our file with the dictionary?  As before, we generate
+a sorted list of words, one per line:
+
+@example
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+> tr -s ' ' '\n' | sort -u | ...
+@end example
+
+Now, all we need is a list of words that are @emph{not} in the
+dictionary.  Here is where the @command{comm} command comes in.
+Unfortunately @command{comm} operates on sorted input and
+@file{/usr/share/dict/words} is not sorted the way that @command{sort}
+and @command{comm} normally use, so we first create a properly-sorted
+copy of the dictionary and then run a pipeline that uses the copy.
+
+@example
+$ sort /usr/share/dict/words > sorted-words
+$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' |
+> tr -s ' ' '\n' | sort -u |
+> comm -23 - sorted-words
+@end example
+
+The @option{-2} and @option{-3} options eliminate lines that are only in the
+dictionary (the second file), and lines that are in both files.  Lines
+only in the first file (standard input, our stream of words), are
+words that are not in the dictionary.  These are likely candidates for
+spelling errors.  This pipeline was the first cut at a production
+spelling checker on Unix.
+
+There are some other tools that deserve brief mention.
+
+@table @command
+@item grep
+search files for text that matches a regular expression
+
+@item wc
+count lines, words, characters
+
+@item tee
+a T-fitting for data pipes, copies data to files and to standard output
+
+@item sed
+the stream editor, an advanced tool
+
+@item awk
+a data manipulation language, another advanced tool
+@end table
+
+The software tools philosophy also espoused the following bit of
+advice: ``Let someone else do the hard part.''  This means, take
+something that gives you most of what you need, and then massage it the
+rest of the way until it's in the form that you want.
+
+To summarize:
+
+@enumerate 1
+@item
+Each program should do one thing well.  No more, no less.
+
+@item
+Combining programs with appropriate plumbing leads to results where
+the whole is greater than the sum of the parts.  It also leads to novel
+uses of programs that the authors might never have imagined.
+
+@item
+Programs should never print extraneous header or trailer data, since these
+could get sent on down a pipeline.  (A point we didn't mention earlier.)
+
+@item
+Let someone else do the hard part.
+
+@item
+Know your toolbox!  Use each program appropriately.  If you don't have an
+appropriate tool, build one.
+@end enumerate
+
+All the programs discussed are available as described in
+@uref{https://www.gnu.org/software/coreutils/coreutils.html,
+GNU core utilities}.
+
+None of what I have presented in this column is new.  The Software Tools
+philosophy was first introduced in the book @cite{Software Tools}, by
+Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X).
+This book showed how to write and use software tools.  It was written in
+1976, using a preprocessor for FORTRAN named @command{ratfor} (RATional
+FORtran).  At the time, C was not as ubiquitous as it is now; FORTRAN
+was.  The last chapter presented a @command{ratfor} to FORTRAN
+processor, written in @command{ratfor}.  @command{ratfor} looks an awful
+lot like C; if you know C, you won't have any problem following the
+code.
+
+In 1981, the book was updated and made available as @cite{Software Tools
+in Pascal} (Addison-Wesley, ISBN 0-201-10342-7).  Both books are
+still in print and are well worth
+reading if you're a programmer.  They certainly made a major change in
+how I view programming.
+
+The programs in both books are available from
+@uref{https://www.cs.princeton.edu/~bwk/, Brian Kernighan's home page}.
+For a number of years, there was an active
+Software Tools Users Group, whose members had ported the original
+@command{ratfor} programs to essentially every computer system with a
+FORTRAN compiler.  The popularity of the group waned in the middle 1980s
+as Unix began to spread beyond universities.
+
+With the current proliferation of GNU code and other clones of Unix programs,
+these programs now receive little attention; modern C versions are
+much more efficient and do more than these programs do.  Nevertheless, as
+exposition of good programming style, and evangelism for a still-valuable
+philosophy, these books are unparalleled, and I recommend them highly.
+
+Acknowledgment: I would like to express my gratitude to Brian Kernighan
+of Bell Labs, the original Software Toolsmith, for reviewing this column.
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl.texi
+
+@node Concept index
+@unnumbered Index
+
+@printindex cp
+
+@bye
+
+@c Local variables:
+@c texinfo-column-for-description: 32
+@c End:
diff --git a/doc/fdl.texi b/doc/fdl.texi
new file mode 100644
index 0000000..eaf3da0
--- /dev/null
+++ b/doc/fdl.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{https://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The ``Document'', below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as ``you''.  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification.  Examples
+of transparent image formats include PNG, XCF and
+JPG@.  Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document).  You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page.  If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on.  These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles.  Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''.  Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''.  You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time.  Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.  See
+@uref{https://www.gnu.org/licenses/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+  Copyright (C)  @var{year}  @var{your name}.
+  Permission is granted to copy, distribute and/or modify this document
+  under the terms of the GNU Free Documentation License, Version 1.3
+  or any later version published by the Free Software Foundation;
+  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+  Texts.  A copy of the license is included in the section entitled ``GNU
+  Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.''@: line with this:
+
+@smallexample
+@group
+    with the Invariant Sections being @var{list their titles}, with
+    the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+    being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
diff --git a/doc/local.mk b/doc/local.mk
new file mode 100644
index 0000000..b5a6c33
--- /dev/null
+++ b/doc/local.mk
@@ -0,0 +1,132 @@
+# Make coreutils documentation.				-*-Makefile-*-
+# This is included by the top-level Makefile.am.
+
+# Copyright (C) 1995-2023 Free Software Foundation, Inc.
+
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+info_TEXINFOS = doc/coreutils.texi
+
+doc_coreutils_TEXINFOS = \
+  doc/perm.texi \
+  doc/parse-datetime.texi \
+  doc/constants.texi \
+  doc/fdl.texi \
+  doc/sort-version.texi
+
+# The customization variable CHECK_NORMAL_MENU_STRUCTURE is necessary with
+# makeinfo versions ≥ 6.8.
+MAKEINFO = @MAKEINFO@ -c CHECK_NORMAL_MENU_STRUCTURE=1
+
+# The following is necessary if the package name is 8 characters or longer.
+# If the info documentation would be split into 10 or more separate files,
+# then this is necessary even if the package name is 7 characters long.
+#
+# Tell makeinfo to put everything in a single info file: <package>.info.
+# Otherwise, it would also generate files with names like <package>.info-[123],
+# and those names all map to one 14-byte name (<package>.info-) on some crufty
+# old systems.
+AM_MAKEINFOFLAGS = --no-split
+
+doc/constants.texi: $(top_srcdir)/src/tail.c $(top_srcdir)/src/shred.c
+	$(AM_V_GEN)LC_ALL=C; export LC_ALL; \
+	$(MKDIR_P) doc && \
+	{ sed -n -e 's/^#define \(DEFAULT_MAX[_A-Z]*\) \(.*\)/@set \1 \2/p' \
+	    $(top_srcdir)/src/tail.c && \
+	  sed -n -e \
+	      's/.*\(DEFAULT_PASSES\)[ =]* \([0-9]*\).*/@set SHRED_\1 \2/p'\
+	    $(top_srcdir)/src/shred.c; } > $@-t \
+	  && { cmp $@-t $@ >/dev/null 2>&1 || mv $@-t $@; rm -f $@-t; }
+
+MAINTAINERCLEANFILES += doc/constants.texi
+
+# Extended regular expressions to match word starts and ends.
+_W = (^|[^A-Za-z0-9_])
+W_ = ([^A-Za-z0-9_]|$$)
+
+syntax_checks =		\
+  sc-avoid-builtin	\
+  sc-avoid-io		\
+  sc-avoid-non-zero	\
+  sc-avoid-path		\
+  sc-avoid-timezone	\
+  sc-avoid-zeroes	\
+  sc-exponent-grouping	\
+  sc-lower-case-var
+
+texi_files = $(srcdir)/doc/*.texi
+
+.PHONY: $(syntax_checks) check-texinfo
+
+# List words/regexps here that should not appear in the texinfo documentation.
+check-texinfo: $(syntax_checks)
+	$(AM_V_GEN)fail=0;						\
+	grep '@url{' $(texi_files) && fail=1;				\
+	grep '\$$@"' $(texi_files) && fail=1;				\
+	grep -n '[^[:punct:]]@footnote' $(texi_files) && fail=1;	\
+	grep -n filename $(texi_files)					\
+	    | $(EGREP) -v 'setfilename|[{]filename[}]'			\
+	  && fail=1;							\
+	exit $$fail
+
+sc-avoid-builtin:
+	$(AM_V_GEN)$(EGREP) -i '$(_W)builtins?$(W_)' $(texi_files)	\
+	  && exit 1 || :
+
+sc-avoid-path:
+	$(AM_V_GEN)fail=0;						\
+	$(EGREP) -i '$(_W)path(name)?s?$(W_)' $(texi_files)		\
+	  | $(EGREP) -v							\
+	  'PATH=|path search|search path|@vindex PATH$$|@env[{]PATH[}]'	\
+	  && fail=1;							\
+	exit $$fail
+
+# Use "time zone", not "timezone".
+sc-avoid-timezone:
+	$(AM_V_GEN)$(EGREP) timezone $(texi_files) && exit 1 || :
+
+# Check for insufficient exponent grouping, e.g.,
+# @math{2^64} should be @math{2^{64}}.
+sc-exponent-grouping:
+	$(AM_V_GEN)$(EGREP) '\{.*\^[0-9][0-9]' $(texi_files) && exit 1 || :
+
+# Say I/O, not IO.
+sc-avoid-io:
+	$(AM_V_GEN)$(EGREP) '$(_W)IO$(W_)' $(texi_files) && exit 1 || :
+
+# I prefer nonzero over non-zero.
+sc-avoid-non-zero:
+	$(AM_V_GEN)$(EGREP) non-zero $(texi_files) && exit 1 || :
+
+# Use "zeros", not "zeroes" (nothing wrong with "zeroes"; just be consistent).
+sc-avoid-zeroes:
+	$(AM_V_GEN)$(EGREP) -i '$(_W)zeroes$(W_)' $(texi_files)	\
+	  && exit 1 || :
+
+# The quantity inside @var{...} should not contain upper case letters.
+# The leading backslash exemption is to permit in-macro uses like
+# @var{\varName\} where the upper case letter is part of a parameter name.
+find_upper_case_var =		\
+  '/\@var\{/ or next;		\
+   while (/\@var\{(.+?)}/g)	\
+     {				\
+       $$v = $$1;		\
+       $$v =~ /[A-Z]/ && $$v !~ /^\\/ and (print "$$ARGV:$$.:$$_"), $$m = 1 \
+     }				\
+   END {$$m and (warn "$@: do not use upper case in \@var{...}\n"), exit 1}'
+sc-lower-case-var:
+	$(AM_V_GEN)$(PERL) -e 1 || { echo $@: skipping test; exit 0; }; \
+	  $(PERL) -lne $(find_upper_case_var) $(texi_files)
+
+check-local: check-texinfo
diff --git a/doc/parse-datetime.texi b/doc/parse-datetime.texi
new file mode 100644
index 0000000..ec0160d
--- /dev/null
+++ b/doc/parse-datetime.texi
@@ -0,0 +1,618 @@
+@c GNU date syntax documentation
+
+@c Copyright (C) 1994--2006, 2009--2023 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
+
+@node Date input formats
+@chapter Date input formats
+
+@cindex date input formats
+@findex parse_datetime
+
+First, a quote:
+
+@quotation
+Our units of temporal measurement, from seconds on up to months, are so
+complicated, asymmetrical and disjunctive so as to make coherent mental
+reckoning in time all but impossible.  Indeed, had some tyrannical god
+contrived to enslave our minds to time, to make it all but impossible
+for us to escape subjection to sodden routines and unpleasant surprises,
+he could hardly have done better than handing down our present system.
+It is like a set of trapezoidal building blocks, with no vertical or
+horizontal surfaces, like a language in which the simplest thought
+demands ornate constructions, useless particles and lengthy
+circumlocutions.  Unlike the more successful patterns of language and
+science, which enable us to face experience boldly or at least
+level-headedly, our system of temporal calculation silently and
+persistently encourages our terror of time.
+
+@dots{}  It is as though architects had to measure length in feet, width
+in meters and height in ells; as though basic instruction manuals
+demanded a knowledge of five different languages.  It is no wonder then
+that we often look into our own immediate past or future, last Tuesday
+or a week from Sunday, with feelings of helpless confusion.  @dots{}
+
+---Robert Grudin, @cite{Time and the Art of Living}.
+@end quotation
+
+This section describes the textual date representations that GNU
+programs accept.  These are the strings you, as a user, can supply as
+arguments to the various programs.  The C interface (via the
+@code{parse_datetime} function) is not described here.
+
+@menu
+* General date syntax::          Common rules
+* Calendar date items::          @samp{14 Nov 2022}
+* Time of day items::            @samp{9:02pm}
+* Time zone items::              @samp{UTC}, @samp{-0700}, @samp{+0900}, @dots{}
+* Combined date and time of day items:: @samp{2022-11-14T21:02:42,000000-0500}
+* Day of week items::            @samp{Monday} and others
+* Relative items in date strings:: @samp{next tuesday, 2 years ago}
+* Pure numbers in date strings:: @samp{20221114}, @samp{2102}
+* Seconds since the Epoch::      @samp{@@1668477762}
+* Specifying time zone rules::   @samp{TZ="America/New_York"}, @samp{TZ="UTC0"}
+* Authors of parse_datetime::    Bellovin, Eggert, Salz, Berets, et al.
+@end menu
+
+
+@node General date syntax
+@section General date syntax
+
+@cindex general date syntax
+
+@cindex items in date strings
+A @dfn{date} is a string, possibly empty, containing many items
+separated by whitespace.  The whitespace may be omitted when no
+ambiguity arises.  The empty string means the beginning of today (i.e.,
+midnight).  Order of the items is immaterial.  A date string may contain
+many flavors of items:
+
+@itemize @bullet
+@item calendar date items
+@item time of day items
+@item time zone items
+@item combined date and time of day items
+@item day of the week items
+@item relative items
+@item pure numbers.
+@end itemize
+
+@noindent We describe each of these item types in turn, below.
+
+@cindex numbers, written-out
+@cindex ordinal numbers
+@findex first @r{in date strings}
+@findex next @r{in date strings}
+@findex last @r{in date strings}
+A few ordinal numbers may be written out in words in some contexts.  This is
+most useful for specifying day of the week items or relative items (see
+below).  Among the most commonly used ordinal numbers, the word
+@samp{last} stands for @math{-1}, @samp{this} stands for 0, and
+@samp{first} and @samp{next} both stand for 1.  Because the word
+@samp{second} stands for the unit of time there is no way to write the
+ordinal number 2, but for convenience @samp{third} stands for 3,
+@samp{fourth} for 4, @samp{fifth} for 5,
+@samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
+@samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
+@samp{twelfth} for 12.
+
+@cindex months, written-out
+When a month is written this way, it is still considered to be written
+numerically, instead of being ``spelled in full''; this changes the
+allowed strings.
+
+@cindex language, in dates
+In the current implementation, only English is supported for words and
+abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
+@samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
+
+@cindex language, in dates
+@cindex time zone item
+The output of the @command{date} command
+is not always acceptable as a date string,
+not only because of the language problem, but also because there is no
+standard meaning for time zone items like @samp{IST}@.  When using
+@command{date} to generate a date string intended to be parsed later,
+specify a date format that is independent of language and that does not
+use time zone items other than @samp{UTC} and @samp{Z}@.  Here are some
+ways to do this:
+
+@example
+$ LC_ALL=C TZ=UTC0 date
+Tue Nov 15 02:02:42 UTC 2022
+$ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
+2022-11-15 02:02:42Z
+$ date --rfc-3339=ns  # --rfc-3339 is a GNU extension.
+2022-11-14 21:02:42.000000000-05:00
+$ date --rfc-email  # a GNU extension
+Mon, 14 Nov 2022 21:02:42 -0500
+$ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
+2022-11-14 21:02:42 -0500
+$ date +'@@%s.%N'  # %s and %N are GNU extensions.
+@@1668477762.692722128
+@end example
+
+@cindex case, ignored in dates
+@cindex comments, in dates
+Alphabetic case is completely ignored in dates.  Comments may be introduced
+between round parentheses, as long as included parentheses are properly
+nested.  Hyphens not followed by a digit are currently ignored.  Leading
+zeros on numbers are ignored.
+
+@cindex leap seconds
+Invalid dates like @samp{2022-02-29} or times like @samp{24:00} are
+rejected.  In the typical case of a host that does not support leap
+seconds, a time like @samp{23:59:60} is rejected even if it
+corresponds to a valid leap second.
+
+
+@node Calendar date items
+@section Calendar date items
+
+@cindex calendar date item
+
+A @dfn{calendar date item} specifies a day of the year.  It is
+specified differently, depending on whether the month is specified
+numerically or literally.  All these strings specify the same calendar date:
+
+@example
+2022-11-14     # ISO 8601.
+22-11-14       # Assume 19xx for 69 through 99,
+               # 20xx for 00 through 68 (not recommended).
+11/14/2022     # Common U.S. writing.
+14 November 2022
+14 Nov 2022    # Three-letter abbreviations always allowed.
+November 14, 2022
+14-nov-2022
+14nov2022
+@end example
+
+The year can also be omitted.  In this case, the last specified year is
+used, or the current year if none.  For example:
+
+@example
+11/14
+nov 14
+@end example
+
+Here are the rules.
+
+@cindex ISO 8601 date format
+@cindex date format, ISO 8601
+For numeric months, the ISO 8601 format
+@samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
+any positive number, @var{month} is a number between 01 and 12, and
+@var{day} is a number between 01 and 31.  A leading zero must be present
+if a number is less than ten.  If @var{year} is 68 or smaller, then 2000
+is added to it; otherwise, if @var{year} is less than 100,
+then 1900 is added to it.  The construct
+@samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
+is accepted.  Also @samp{@var{month}/@var{day}}, omitting the year.
+
+@cindex month names in date strings
+@cindex abbreviations for months
+Literal months may be spelled out in full: @samp{January},
+@samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
+@samp{July}, @samp{August}, @samp{September}, @samp{October},
+@samp{November} or @samp{December}.  Literal months may be abbreviated
+to their first three letters, possibly followed by an abbreviating dot.
+It is also permitted to write @samp{Sept} instead of @samp{September}.
+
+When months are written literally, the calendar date may be given as any
+of the following:
+
+@example
+@var{day} @var{month} @var{year}
+@var{day} @var{month}
+@var{month} @var{day} @var{year}
+@var{day}-@var{month}-@var{year}
+@end example
+
+Or, omitting the year:
+
+@example
+@var{month} @var{day}
+@end example
+
+
+@node Time of day items
+@section Time of day items
+
+@cindex time of day item
+
+A @dfn{time of day item} in date strings specifies the time on a given
+day.  Here are some examples, all of which represent the same time:
+
+@example
+20:02:00.000000
+20:02
+8:02pm
+20:02-0500      # In EST (U.S. Eastern Standard Time).
+@end example
+
+@cindex leap seconds
+More generally, the time of day may be given as
+@samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
+a number between 0 and 23, @var{minute} is a number between 0 and
+59, and @var{second} is a number between 0 and 59 possibly followed by
+@samp{.} or @samp{,} and a fraction containing one or more digits.
+Alternatively,
+@samp{:@var{second}} can be omitted, in which case it is taken to
+be zero.  On the rare hosts that support leap seconds, @var{second}
+may be 60.
+
+@findex am @r{in date strings}
+@findex pm @r{in date strings}
+@findex midnight @r{in date strings}
+@findex noon @r{in date strings}
+If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
+or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
+@samp{:@var{minute}} may be omitted (taken to be zero).  @samp{am}
+indicates the first half of the day, @samp{pm} indicates the second
+half of the day.  In this notation, 12 is the predecessor of 1:
+midnight is @samp{12am} while noon is @samp{12pm}.
+(This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
+as opposed to the old tradition derived from Latin
+which uses @samp{12m} for noon and @samp{12pm} for midnight.)
+
+@cindex time zone correction
+@cindex minutes, time zone correction by
+The time may alternatively be followed by a time zone correction,
+expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
+or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
+of zone minutes.
+The zone minutes term, @var{mm}, may be omitted, in which case
+the one- or two-digit correction is interpreted as a number of hours.
+You can also separate @var{hh} from @var{mm} with a colon.
+When a time zone correction is given this way, it
+forces interpretation of the time relative to
+Coordinated Universal Time (UTC), overriding any previous
+specification for the time zone or the local time zone.  For example,
+@samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
+ahead of UTC (e.g., India).
+This is the best way to
+specify a time zone correction by fractional parts of an hour.
+The maximum zone correction is 24 hours.
+
+Either @samp{am}/@samp{pm} or a time zone correction may be specified,
+but not both.
+
+
+@node Time zone items
+@section Time zone items
+
+@cindex time zone item
+
+A @dfn{time zone item} specifies an international time zone, indicated
+by a small set of letters, e.g., @samp{UTC} or @samp{Z}
+for Coordinated Universal
+Time.  Any included periods are ignored.  By following a
+non-daylight-saving time zone by the string @samp{DST} in a separate
+word (that is, separated by some white space), the corresponding
+daylight saving time zone may be specified.
+Alternatively, a non-daylight-saving time zone can be followed by a
+time zone correction, to add the two values.  This is normally done
+only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
+@samp{+05:30}.
+
+Time zone items other than @samp{UTC} and @samp{Z}
+are obsolescent and are not recommended, because they
+are ambiguous; for example, @samp{EST} has a different meaning in
+Australia than in the United States, and @samp{A} has different
+meaning as a military time zone than as an obsolete
+RFC 822 time zone.  Instead, it's better to use
+unambiguous numeric time zone corrections like @samp{-0500}, as
+described in the previous section.
+
+If neither a time zone item nor a time zone correction is supplied,
+timestamps are interpreted using the rules of the default time zone
+(@pxref{Specifying time zone rules}).
+
+
+@node Combined date and time of day items
+@section Combined date and time of day items
+
+@cindex combined date and time of day item
+@cindex ISO 8601 date and time of day format
+@cindex date and time of day format, ISO 8601
+
+The ISO 8601 date and time of day extended format consists of an ISO
+8601 date, a @samp{T} character separator, and an ISO 8601 time of
+day.  This format is also recognized if the @samp{T} is replaced by a
+space.
+
+In this format, the time of day should use 24-hour notation.
+Fractional seconds are allowed, with either comma or period preceding
+the fraction.  ISO 8601 fractional minutes and hours are not
+supported.  Typically, hosts support nanosecond timestamp resolution;
+excess precision is silently discarded.
+
+Here are some examples:
+
+@example
+2022-09-24T20:02:00.052-05:00
+2022-12-31T23:59:59,999999999+11:00
+1970-01-01 00:00Z
+@end example
+
+@node Day of week items
+@section Day of week items
+
+@cindex day of week item
+
+The explicit mention of a day of the week will forward the date
+(only if necessary) to reach that day of the week in the future.
+
+Days of the week may be spelled out in full: @samp{Sunday},
+@samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
+@samp{Friday} or @samp{Saturday}.  Days may be abbreviated to their
+first three letters, optionally followed by a period.  The special
+abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
+@samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
+also allowed.
+
+@findex next @var{day}
+@findex last @var{day}
+A number may precede a day of the week item to move forward
+supplementary weeks.  It is best used in expression like @samp{third
+monday}.  In this context, @samp{last @var{day}} or @samp{next
+@var{day}} is also acceptable; they move one week before or after
+the day that @var{day} by itself would represent.
+
+A comma following a day of the week item is ignored.
+
+
+@node Relative items in date strings
+@section Relative items in date strings
+
+@cindex relative items in date strings
+@cindex displacement of dates
+
+@dfn{Relative items} adjust a date (or the current date if none) forward
+or backward.  The effects of relative items accumulate.  Here are some
+examples:
+
+@example
+1 year
+1 year ago
+3 years
+2 days
+@end example
+
+@findex year @r{in date strings}
+@findex month @r{in date strings}
+@findex fortnight @r{in date strings}
+@findex week @r{in date strings}
+@findex day @r{in date strings}
+@findex hour @r{in date strings}
+@findex minute @r{in date strings}
+The unit of time displacement may be selected by the string @samp{year}
+or @samp{month} for moving by whole years or months.  These are fuzzy
+units, as years and months are not all of equal duration.  More precise
+units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
+days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
+@samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
+@samp{sec} worth one second.  An @samp{s} suffix on these units is
+accepted and ignored.
+
+@findex ago @r{in date strings}
+The unit of time may be preceded by a multiplier, given as an optionally
+signed number.  Unsigned numbers are taken as positively signed.  No
+number at all implies 1 for a multiplier.  Following a relative item by
+the string @samp{ago} is equivalent to preceding the unit by a
+multiplier with value @math{-1}.
+
+@findex day @r{in date strings}
+@findex tomorrow @r{in date strings}
+@findex yesterday @r{in date strings}
+The string @samp{tomorrow} is worth one day in the future (equivalent
+to @samp{day}), the string @samp{yesterday} is worth
+one day in the past (equivalent to @samp{day ago}).
+
+@findex now @r{in date strings}
+@findex today @r{in date strings}
+@findex this @r{in date strings}
+The strings @samp{now} or @samp{today} are relative items corresponding
+to zero-valued time displacement, these strings come from the fact
+a zero-valued time displacement represents the current time when not
+otherwise changed by previous items.  They may be used to stress other
+items, like in @samp{12:00 today}.  The string @samp{this} also has
+the meaning of a zero-valued time displacement, but is preferred in
+date strings like @samp{this thursday}.
+
+When a relative item causes the resulting date to cross a boundary
+where the clocks were adjusted, typically for daylight saving time,
+the resulting date and time are adjusted accordingly.
+
+The fuzz in units can cause problems with relative items.  For
+example, @samp{2022-12-31 -1 month} might evaluate to 2022-12-01,
+because 2022-11-31 is an invalid date.  To determine the previous
+month more reliably, you can ask for the month before the 15th of the
+current month.  For example:
+
+@example
+$ date -R
+Thu, 31 Dec 2022 13:02:39 -0400
+$ date --date='-1 month' +'Last month was %B?'
+Last month was December?
+$ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
+Last month was November!
+@end example
+
+Also, take care when manipulating dates around clock changes such as
+daylight saving leaps.  In a few cases these have added or subtracted
+as much as 24 hours from the clock, so it is often wise to adopt
+universal time by setting the @env{TZ} environment variable to
+@samp{UTC0} before embarking on calendrical calculations.
+
+@node Pure numbers in date strings
+@section Pure numbers in date strings
+
+@cindex pure numbers in date strings
+
+The precise interpretation of a pure decimal number depends
+on the context in the date string.
+
+If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
+other calendar date item (@pxref{Calendar date items}) appears before it
+in the date string, then @var{yyyy} is read as the year, @var{mm} as the
+month number and @var{dd} as the day of the month, for the specified
+calendar date.
+
+If the decimal number is of the form @var{hh}@var{mm} and no other time
+of day item appears before it in the date string, then @var{hh} is read
+as the hour of the day and @var{mm} as the minute of the hour, for the
+specified time of day.  @var{mm} can also be omitted.
+
+If both a calendar date and a time of day appear to the left of a number
+in the date string, but no relative item, then the number overrides the
+year.
+
+
+@node Seconds since the Epoch
+@section Seconds since the Epoch
+
+If you precede a number with @samp{@@}, it represents an internal
+timestamp as a count of seconds.  The number can contain an internal
+decimal point (either @samp{.} or @samp{,}); any excess precision not
+supported by the internal representation is truncated toward minus
+infinity.  Such a number cannot be combined with any other date
+item, as it specifies a complete timestamp.
+
+@cindex beginning of time, for POSIX
+@cindex Epoch, for POSIX
+Internally, computer times are represented as a count of seconds since
+an Epoch---a well-defined point of time.  On GNU and
+POSIX systems, the Epoch is 1970-01-01 00:00:00 UTC, so
+@samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
+00:00:01 UTC, and so forth.  GNU and most other
+POSIX-compliant systems support such times as an extension
+to POSIX, using negative counts, so that @samp{@@-1}
+represents 1969-12-31 23:59:59 UTC.
+
+Most modern systems count seconds with 64-bit two's-complement integers
+of seconds with nanosecond subcounts, which is a range that includes
+the known lifetime of the universe with nanosecond resolution.
+Some obsolescent systems count seconds with 32-bit two's-complement
+integers and can represent times from 1901-12-13 20:45:52 through
+2038-01-19 03:14:07 UTC@.  A few systems sport other time ranges.
+
+@cindex leap seconds
+On most hosts, these counts ignore the presence of leap seconds.
+For example, on most hosts @samp{@@1483228799} represents 2016-12-31
+23:59:59 UTC, @samp{@@1483228800} represents 2017-01-01 00:00:00
+UTC, and there is no way to represent the intervening leap second
+2016-12-31 23:59:60 UTC.
+
+@node Specifying time zone rules
+@section Specifying time zone rules
+
+@vindex TZ
+Normally, dates are interpreted using the rules of the current time
+zone, which in turn are specified by the @env{TZ} environment
+variable, or by a system default if @env{TZ} is not set.  To specify a
+different set of default time zone rules that apply just to one date,
+start the date with a string of the form @samp{TZ="@var{rule}"}.  The
+two quote characters (@samp{"}) must be present in the date, and any
+quotes or backslashes within @var{rule} must be escaped by a
+backslash.
+
+For example, with the GNU @command{date} command you can
+answer the question ``What time is it in New York when a Paris clock
+shows 6:30am on October 31, 2022?'' by using a date beginning with
+@samp{TZ="Europe/Paris"} as shown in the following shell transcript:
+
+@example
+$ export TZ="America/New_York"
+$ date --date='TZ="Europe/Paris" 2022-10-31 06:30'
+Mon Oct 31 01:30:00 EDT 2022
+@end example
+
+In this example, the @option{--date} operand begins with its own
+@env{TZ} setting, so the rest of that operand is processed according
+to @samp{Europe/Paris} rules, treating the string @samp{2022-11-14
+06:30} as if it were in Paris.  However, since the output of the
+@command{date} command is processed according to the overall time zone
+rules, it uses New York time.  (Paris was normally six hours ahead of
+New York in 2022, but this example refers to a brief Halloween period
+when the gap was five hours.)
+
+A @env{TZ} value is a rule that typically names a location in the
+@uref{https://www.iana.org/time-zones, @samp{tz} database}.
+A recent catalog of location names appears in the
+@uref{https://twiki.org/cgi-bin/xtra/tzdatepick.html, TWiki Date and Time
+Gateway}.  A few non-GNU hosts require a colon before a
+location name in a @env{TZ} setting, e.g.,
+@samp{TZ=":America/New_York"}.
+
+The @samp{tz} database includes a wide variety of locations ranging
+from @samp{Africa/Abidjan} to @samp{Pacific/Tongatapu}, but
+if you are at sea and have your own private time zone, or if you are
+using a non-GNU host that does not support the @samp{tz}
+database, you may need to use a POSIX rule instead.
+The previously-mentioned POSIX rule @samp{UTC0} says that the time zone
+abbreviation is @samp{UTC}, the zone is zero hours away from
+Greenwich, and there is no daylight saving time.
+POSIX rules can also specify nonzero Greenwich offsets.
+For example, the following shell transcript answers the question
+``What time is it five and a half hours east of Greenwich when a clock
+seven hours west of Greenwich shows 9:50pm on July 12, 2022?''
+
+@example
+$ TZ="<+0530>-5:30" date --date='TZ="<-07>+7" 2022-07-12 21:50'
+Wed Jul 13 10:20:00 +0530 2022
+@end example
+
+@noindent
+This example uses the somewhat-confusing POSIX convention for rules.
+@samp{TZ="<-07>+7"} says that the time zone abbreviation is @samp{-07}
+and the time zone is 7 hours west of Greenwich, and
+@samp{TZ="<+0530>-5:30"} says that the time zone abbreviation is @samp{+0530}
+and the time zone is 5 hours 30 minutes east of Greenwich.
+(One should never use a setting like @samp{TZ="UTC-5"}, since
+this would incorrectly imply that local time is five hours east of
+Greenwich and the time zone is called ``UTC''.)
+Although trickier POSIX @env{TZ} settings like
+@samp{TZ="<-05>+5<-04>,M3.2.0/2,M11.1.0/2"} can specify some daylight
+saving regimes, location-based settings like
+@samp{TZ="America/New_York"} are typically simpler and more accurate
+historically.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
+libc, The GNU C Library}.
+
+@node Authors of parse_datetime
+@section Authors of @code{parse_datetime}
+@c the anchor keeps the old node name, to try to avoid breaking links
+@anchor{Authors of get_date}
+
+@cindex authors of @code{parse_datetime}
+
+@cindex Bellovin, Steven M.
+@cindex Salz, Rich
+@cindex Berets, Jim
+@cindex MacKenzie, David
+@cindex Meyering, Jim
+@cindex Eggert, Paul
+@code{parse_datetime} started life as @code{getdate}, as originally
+implemented by Steven M. Bellovin
+(@email{smb@@research.att.com}) while at the University of North Carolina
+at Chapel Hill.  The code was later tweaked by a couple of people on
+Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
+and Jim Berets (@email{jberets@@bbn.com}) in August, 1990.  Various
+revisions for the GNU system were made by David MacKenzie, Jim Meyering,
+Paul Eggert and others, including renaming it to @code{get_date} to
+avoid a conflict with the alternative Posix function @code{getdate},
+and a later rename to @code{parse_datetime}.  The Posix function
+@code{getdate} can parse more locale-specific dates using
+@code{strptime}, but relies on an environment variable and external
+file, and lacks the thread-safety of @code{parse_datetime}.
+
+@cindex Pinard, F.
+@cindex Berry, K.
+This chapter was originally produced by Fran@,{c}ois Pinard
+(@email{pinard@@iro.umontreal.ca}) from the @file{parse_datetime.y} source code,
+and then edited by K. Berry (@email{kb@@cs.umb.edu}).
diff --git a/doc/perm.texi b/doc/perm.texi
new file mode 100644
index 0000000..45ff1d4
--- /dev/null
+++ b/doc/perm.texi
@@ -0,0 +1,641 @@
+@c File mode bits
+
+@c Copyright (C) 1994--2023 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+@c Texts.  A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
+Each file has a set of @dfn{file mode bits} that control the kinds of
+access that users have to that file.  They can be represented either in
+symbolic form or as an octal number.
+
+@menu
+* Mode Structure::              Structure of file mode bits.
+* Symbolic Modes::              Mnemonic representation of file mode bits.
+* Numeric Modes::               File mode bits as octal numbers.
+* Operator Numeric Modes::      ANDing, ORing, and setting modes octally.
+* Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories.
+@end menu
+
+@node Mode Structure
+@section Structure of File Mode Bits
+
+The file mode bits have two parts: the @dfn{file permission bits},
+which control ordinary access to the file, and @dfn{special mode
+bits}, which affect only some files.
+
+There are three kinds of permissions that a user can have for a file:
+
+@enumerate
+@item
+@cindex read permission
+permission to read the file.  For directories, this means permission to
+list the contents of the directory.
+@item
+@cindex write permission
+permission to write to (change) the file.  For directories, this means
+permission to create and remove files in the directory.
+@item
+@cindex execute/search permission
+permission to execute the file (run it as a program).  For directories,
+this means permission to access files in the directory.
+@end enumerate
+
+There are three categories of users who may have different permissions
+to perform any of the above operations on a file:
+
+@enumerate
+@item
+the file's owner;
+@item
+other users who are in the file's group;
+@item
+everyone else.
+@end enumerate
+
+@cindex owner, default
+@cindex group owner, default
+Files are given an owner and group when they are created.  Usually the
+owner is the current user and the group is the group of the directory
+the file is in, but this varies with the operating system, the
+file system the file is created on, and the way the file is created.  You
+can change the owner and group of a file by using the @command{chown} and
+@command{chgrp} commands.
+
+In addition to the three sets of three permissions listed above, the
+file mode bits have three special components, which affect only
+executable files (programs) and, on most systems, directories:
+
+@table @asis
+@item The @dfn{set-user-ID bit} (@dfn{setuid bit}).
+@cindex set-user-ID
+@cindex setuid
+On execution, set the process's effective user ID to that of the file.
+For directories on a few systems, give files created in the directory
+the same owner as the directory, no matter who creates them, and set
+the set-user-ID bit of newly-created subdirectories.
+
+@item The @dfn{set-group-ID bit} (@dfn{setgid bit}).
+@cindex set-group-ID
+@cindex setgid
+On execution, set the process's effective group ID to that of the file.
+For directories on most systems, give files created in the directory
+the same group as the directory, no matter what group the user who
+creates them is in, and set the set-group-ID bit of newly-created
+subdirectories.
+
+@item The @dfn{restricted deletion flag} or @dfn{sticky bit}.
+@cindex sticky
+@cindex swap space, saving text image in
+@cindex text image, saving in swap space
+@cindex restricted deletion flag
+Prevent unprivileged users from removing or renaming a file in a directory
+unless they own the file or the directory; this is commonly
+found on world-writable directories like @file{/tmp}.
+For regular files on some older systems, save the program's text image on the
+swap device so it will load more quickly when run, so that the image
+is ``sticky''.
+@end table
+
+In addition to the file mode bits listed above, there may be file attributes
+specific to the file system, e.g., access control lists (ACLs), whether a
+file is compressed, whether a file can be modified (immutability), and whether
+a file can be dumped.  These are usually set using programs
+specific to the file system.  For example:
+@c should probably say a lot more about ACLs... someday
+
+@table @asis
+@item ext2
+On GNU and GNU/Linux the file attributes specific to
+the ext2 file system are set using @command{chattr}.
+
+@item FFS
+On FreeBSD the file flags specific to the FFS
+file system are set using @command{chflags}.
+@end table
+
+Even if a file's mode bits allow an operation on that file,
+that operation may still fail, because:
+
+@itemize
+@item
+the file-system-specific attributes or flags do not permit it; or
+
+@item
+the file system is mounted as read-only.
+@end itemize
+
+For example, if the immutable attribute is set on a file,
+it cannot be modified, regardless of the fact that you
+may have just run @code{chmod a+w FILE}.
+
+@node Symbolic Modes
+@section Symbolic Modes
+
+@cindex symbolic modes
+@dfn{Symbolic modes} represent changes to files' mode bits as
+operations on single-character symbols.  They allow you to modify either
+all or selected parts of files' mode bits, optionally based on
+their previous values, and perhaps on the current @code{umask} as well
+(@pxref{Umask and Protection}).
+
+The format of symbolic modes is:
+
+@example
+@r{[}ugoa@dots{}@r{][}-+=@r{]}@var{perms}@dots{}@r{[},@dots{}@r{]}
+@end example
+
+@noindent
+where @var{perms} is either zero or more letters from the set
+@samp{rwxXst}, or a single letter from the set @samp{ugo}.
+
+The following sections describe the operators and other details of
+symbolic modes.
+
+@menu
+* Setting Permissions::          Basic operations on permissions.
+* Copying Permissions::          Copying existing permissions.
+* Changing Special Mode Bits::   Special mode bits.
+* Conditional Executability::    Conditionally affecting executability.
+* Multiple Changes::             Making multiple changes.
+* Umask and Protection::              The effect of the umask.
+@end menu
+
+@node Setting Permissions
+@subsection Setting Permissions
+
+The basic symbolic operations on a file's permissions are adding,
+removing, and setting the permission that certain users have to read,
+write, and execute or search the file.  These operations have the following
+format:
+
+@example
+@var{users} @var{operation} @var{permissions}
+@end example
+
+@noindent
+The spaces between the three parts above are shown for readability only;
+symbolic modes cannot contain spaces.
+
+The @var{users} part tells which users' access to the file is changed.
+It consists of one or more of the following letters (or it can be empty;
+@pxref{Umask and Protection}, for a description of what happens then).  When
+more than one of these letters is given, the order that they are in does
+not matter.
+
+@table @code
+@item u
+@cindex owner of file, permissions for
+the user who owns the file;
+@item g
+@cindex group, permissions for
+other users who are in the file's group;
+@item o
+@cindex other permissions
+all other users;
+@item a
+all users; the same as @samp{ugo}.
+@end table
+
+The @var{operation} part tells how to change the affected users' access
+to the file, and is one of the following symbols:
+
+@table @code
+@item +
+@cindex adding permissions
+to add the @var{permissions} to whatever permissions the @var{users}
+already have for the file;
+@item -
+@cindex removing permissions
+@cindex subtracting permissions
+to remove the @var{permissions} from whatever permissions the
+@var{users} already have for the file;
+@item =
+@cindex setting permissions
+to make the @var{permissions} the only permissions that the @var{users}
+have for the file.
+@end table
+
+The @var{permissions} part tells what kind of access to the file should
+be changed; it is normally zero or more of the following letters.  As with the
+@var{users} part, the order does not matter when more than one letter is
+given.  Omitting the @var{permissions} part is useful only with the
+@samp{=} operation, where it gives the specified @var{users} no access
+at all to the file.
+
+@table @code
+@item r
+@cindex read permission, symbolic
+the permission the @var{users} have to read the file;
+@item w
+@cindex write permission, symbolic
+the permission the @var{users} have to write to the file;
+@item x
+@cindex execute/search permission, symbolic
+the permission the @var{users} have to execute the file,
+or search it if it is a directory.
+@end table
+
+For example, to give everyone permission to read and write a regular file,
+but not to execute it, use:
+
+@example
+a=rw
+@end example
+
+To remove write permission for all users other than the file's
+owner, use:
+
+@example
+go-w
+@end example
+
+@noindent
+The above command does not affect the access that the owner of
+the file has to it, nor does it affect whether other users can
+read or execute the file.
+
+To give everyone except a file's owner no permission to do anything with
+that file, use the mode below.  Other users could still remove the file,
+if they have write permission on the directory it is in.
+
+@example
+go=
+@end example
+
+@noindent
+Another way to specify the same thing is:
+
+@example
+og-rwx
+@end example
+
+@node Copying Permissions
+@subsection Copying Existing Permissions
+
+@cindex copying existing permissions
+@cindex permissions, copying existing
+You can base a file's permissions on its existing permissions.  To do
+this, instead of using a series of @samp{r}, @samp{w}, or @samp{x}
+letters after the
+operator, you use the letter @samp{u}, @samp{g}, or @samp{o}.  For
+example, the mode
+
+@example
+o+g
+@end example
+
+@noindent
+adds the permissions for users who are in a file's group to the
+permissions that other users have for the file.  Thus, if the file
+started out as mode 664 (@samp{rw-rw-r--}), the above mode would change
+it to mode 666 (@samp{rw-rw-rw-}).  If the file had started out as mode
+741 (@samp{rwxr----x}), the above mode would change it to mode 745
+(@samp{rwxr--r-x}).  The @samp{-} and @samp{=} operations work
+analogously.
+
+@node Changing Special Mode Bits
+@subsection Changing Special Mode Bits
+
+@cindex changing special mode bits
+In addition to changing a file's read, write, and execute/search permissions,
+you can change its special mode bits.  @xref{Mode Structure}, for a
+summary of these special mode bits.
+
+To change the file mode bits to set the user ID on execution, use
+@samp{u} in the @var{users} part of the symbolic mode and
+@samp{s} in the @var{permissions} part.
+
+To change the file mode bits to set the group ID on execution, use
+@samp{g} in the @var{users} part of the symbolic mode and
+@samp{s} in the @var{permissions} part.
+
+To set both user and group ID on execution, omit the @var{users} part
+of the symbolic mode (or use @samp{a}) and use @samp{s} in the
+@var{permissions} part.
+
+To change the file mode bits to set the restricted deletion flag or sticky bit,
+omit the @var{users} part of the symbolic mode (or use @samp{a}) and use
+@samp{t} in the @var{permissions} part.
+
+For example, to set the set-user-ID mode bit of a program,
+you can use the mode:
+
+@example
+u+s
+@end example
+
+To remove both set-user-ID and set-group-ID mode bits from
+it, you can use the mode:
+
+@example
+a-s
+@end example
+
+To set the restricted deletion flag or sticky bit, you can use
+the mode:
+
+@example
++t
+@end example
+
+The combination @samp{o+s} has no effect.  On GNU systems
+the combinations @samp{u+t} and @samp{g+t} have no effect, and
+@samp{o+t} acts like plain @samp{+t}.
+
+The @samp{=} operator is not very useful with special mode bits.
+For example, the mode:
+
+@example
+o=t
+@end example
+
+@noindent
+does set the restricted deletion flag or sticky bit, but it also
+removes all read, write, and execute/search permissions that users not in the
+file's group might have had for it.
+
+@xref{Directory Setuid and Setgid}, for additional rules concerning
+set-user-ID and set-group-ID bits and directories.
+
+@node Conditional Executability
+@subsection Conditional Executability
+
+@cindex conditional executability
+There is one more special type of symbolic permission: if you use
+@samp{X} instead of @samp{x}, execute/search permission is affected only if the
+file is a directory or already had execute permission.
+
+For example, this mode:
+
+@example
+a+X
+@end example
+
+@noindent
+gives all users permission to search directories, or to execute files if
+anyone could execute them before.
+
+@node Multiple Changes
+@subsection Making Multiple Changes
+
+@cindex multiple changes to permissions
+The format of symbolic modes is actually more complex than described
+above (@pxref{Setting Permissions}).  It provides two ways to make
+multiple changes to files' mode bits.
+
+The first way is to specify multiple @var{operation} and
+@var{permissions} parts after a @var{users} part in the symbolic mode.
+
+For example, the mode:
+
+@example
+og+rX-w
+@end example
+
+@noindent
+gives users other than the owner of the file read permission and, if
+it is a directory or if someone already had execute permission
+to it, gives them execute/search permission; and it also denies them write
+permission to the file.  It does not affect the permission that the
+owner of the file has for it.  The above mode is equivalent to
+the two modes:
+
+@example
+og+rX
+og-w
+@end example
+
+The second way to make multiple changes is to specify more than one
+simple symbolic mode, separated by commas.  For example, the mode:
+
+@example
+a+r,go-w
+@end example
+
+@noindent
+gives everyone permission to read the file and removes write
+permission on it for all users except its owner.  Another example:
+
+@example
+u=rwx,g=rx,o=
+@end example
+
+@noindent
+sets all of the permission bits for the file explicitly.  (It
+gives users who are not in the file's group no permission at all for
+it.)
+
+The two methods can be combined.  The mode:
+
+@example
+a+r,g+x-w
+@end example
+
+@noindent
+gives all users permission to read the file, and gives users who are in
+the file's group permission to execute/search it as well, but not permission
+to write to it.  The above mode could be written in several different
+ways; another is:
+
+@example
+u+r,g+rx,o+r,g-w
+@end example
+
+@node Umask and Protection
+@subsection The Umask and Protection
+
+@cindex umask and modes
+@cindex modes and umask
+If the @var{users} part of a symbolic mode is omitted, it defaults to
+@samp{a} (affect all users), except that any permissions that are
+@emph{set} in the system variable @code{umask} are @emph{not affected}.
+The value of @code{umask} can be set using the
+@code{umask} command.  Its default value varies from system to system.
+
+@cindex giving away permissions
+Omitting the @var{users} part of a symbolic mode is generally not useful
+with operations other than @samp{+}.  It is useful with @samp{+} because
+it allows you to use @code{umask} as an easily customizable protection
+against giving away more permission to files than you intended to.
+
+As an example, if @code{umask} has the value 2, which removes write
+permission for users who are not in the file's group, then the mode:
+
+@example
++w
+@end example
+
+@noindent
+adds permission to write to the file to its owner and to other users who
+are in the file's group, but @emph{not} to other users.  In contrast,
+the mode:
+
+@example
+a+w
+@end example
+
+@noindent
+ignores @code{umask}, and @emph{does} give write permission for
+the file to all users.
+
+@node Numeric Modes
+@section Numeric Modes
+
+@cindex numeric modes
+@cindex file mode bits, numeric
+@cindex octal numbers for file modes
+As an
+alternative to giving a symbolic mode, you can give an octal (base 8)
+number that represents the mode.
+
+The permissions granted to the user,
+to other users in the file's group,
+and to other users not in the file's group each require three
+bits: one bit for read, one for write, and one for execute/search permission.
+These three bits are represented as one octal digit;
+for example, if all three are present, the resulting 111 (in binary)
+is represented as the digit 7 (in octal).  The three special
+mode bits also require one bit each, and they are as a group
+represented as another octal digit.  Here is how the bits are arranged,
+starting with the highest valued bit:
+
+@example
+Value in  Corresponding
+Mode      Mode Bit
+
+          Special mode bits:
+4000      Set user ID
+2000      Set group ID
+1000      Restricted deletion flag or sticky bit
+
+          The file's owner:
+ 400      Read
+ 200      Write
+ 100      Execute/search
+
+          Other users in the file's group:
+  40      Read
+  20      Write
+  10      Execute/search
+
+          Other users not in the file's group:
+   4      Read
+   2      Write
+   1      Execute/search
+@end example
+
+For example, numeric mode @samp{4751} corresponds to symbolic mode
+@samp{u=srwx,g=rx,o=x}, and numeric mode @samp{664} corresponds to symbolic mode
+@samp{ug=rw,o=r}.  Numeric mode @samp{0} corresponds to symbolic mode
+@samp{a=}.
+
+A numeric mode is usually shorter than the corresponding symbolic
+mode, but it is limited in that normally it cannot take into account the
+previous file mode bits; it can only set them absolutely.
+The set-user-ID and set-group-ID bits of directories are an exception
+to this general limitation.  @xref{Directory Setuid and Setgid}.
+Also, operator numeric modes can take previous file mode bits into
+account.  @xref{Operator Numeric Modes}.
+
+Numeric modes are always interpreted in octal; you do not have to add a
+leading @samp{0}, as you do in C@.  Mode @samp{0055} is the same as
+mode @samp{55}.  However, modes of five digits or more, such as
+@samp{00055}, are sometimes special (@pxref{Directory Setuid and Setgid}).
+
+@node Operator Numeric Modes
+@section Operator Numeric Modes
+
+An operator numeric mode is a numeric mode that is prefixed by a
+@samp{-}, @samp{+}, or @samp{=} operator, which has the same
+interpretation as in symbolic modes.  For example, @samp{+440} enables
+read permission for the file's owner and group, @samp{-1} disables
+execute permission for other users, and @samp{=600} clears all
+permissions except for enabling read-write permissions for the file's
+owner.  Operator numeric modes can be combined with symbolic modes by
+separating them with a comma; for example, @samp{=0,u+r} clears all
+permissions except for enabling read permission for the file's owner.
+
+The commands @samp{chmod =755 @var{dir}} and @samp{chmod 755
+@var{dir}} differ in that the former clears the directory @var{dir}'s
+setuid and setgid bits, whereas the latter preserves them.
+@xref{Directory Setuid and Setgid}.
+
+Operator numeric modes are a GNU extension.
+
+@node Directory Setuid and Setgid
+@section Directories and the Set-User-ID and Set-Group-ID Bits
+
+On most systems, if a directory's set-group-ID bit is set, newly
+created subfiles inherit the same group as the directory, and newly
+created subdirectories inherit the set-group-ID bit of the parent
+directory.  On a few systems, a directory's set-user-ID bit has a
+similar effect on the ownership of new subfiles and the set-user-ID
+bits of new subdirectories.  These mechanisms let users share files
+more easily, by lessening the need to use @command{chmod} or
+@command{chown} to share new files.
+
+These convenience mechanisms rely on the set-user-ID and set-group-ID
+bits of directories.  If commands like @command{chmod} and
+@command{mkdir} routinely cleared these bits on directories, the
+mechanisms would be less convenient and it would be harder to share
+files.  Therefore, a command like @command{chmod} does not affect the
+set-user-ID or set-group-ID bits of a directory unless the user
+specifically mentions them in a symbolic mode, or uses an operator
+numeric mode such as @samp{=755}, or sets them in a numeric mode, or
+clears them in a numeric mode that has five or more octal digits.
+For example, on systems that support
+set-group-ID inheritance:
+
+@example
+# These commands leave the set-user-ID and
+# set-group-ID bits of the subdirectories alone,
+# so that they retain their default values.
+mkdir A B C
+chmod 755 A
+chmod 0755 B
+chmod u=rwx,go=rx C
+mkdir -m 755 D
+mkdir -m 0755 E
+mkdir -m u=rwx,go=rx F
+@end example
+
+If you want to try to set these bits, you must mention them
+explicitly in the symbolic or numeric modes, e.g.:
+
+@example
+# These commands try to set the set-user-ID
+# and set-group-ID bits of the subdirectories.
+mkdir G
+chmod 6755 G
+chmod +6000 G
+chmod u=rwx,go=rx,a+s G
+mkdir -m 6755 H
+mkdir -m +6000 I
+mkdir -m u=rwx,go=rx,a+s J
+@end example
+
+If you want to try to clear these bits, you must mention them
+explicitly in a symbolic mode, or use an operator numeric mode, or
+specify a numeric mode with five or more octal digits, e.g.:
+
+@example
+# These commands try to clear the set-user-ID
+# and set-group-ID bits of the directory D.
+chmod a-s D
+chmod -6000 D
+chmod =755 D
+chmod 00755 D
+@end example
+
+This behavior is a GNU extension.  Portable scripts should
+not rely on requests to set or clear these bits on directories, as
+POSIX allows implementations to ignore these requests.
+The GNU behavior with numeric modes of four or fewer digits
+is intended for scripts portable to systems that preserve these bits;
+the behavior with numeric modes of five or more digits is for scripts
+portable to systems that do not preserve the bits.
diff --git a/doc/sort-version.texi b/doc/sort-version.texi
new file mode 100644
index 0000000..de2ddb5
--- /dev/null
+++ b/doc/sort-version.texi
@@ -0,0 +1,909 @@
+@c GNU Version-sort ordering documentation
+
+@c Copyright (C) 2019--2023 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts.  A copy of the license is included in the ``GNU Free
+@c Documentation License'' file as part of this distribution.
+
+@c Written by Assaf Gordon
+
+@node Version sort ordering
+@chapter Version sort ordering
+
+
+
+@node Version sort overview
+@section Version sort overview
+
+@dfn{Version sort} puts items such as file names and lines of
+text in an order that feels natural to people, when the text
+contains a mixture of letters and digits.
+
+Lexicographic sorting usually does not produce the order that one expects
+because comparisons are made on a character-by-character basis.
+
+Compare the sorting of the following items:
+
+@example
+Lexicographic sort:          Version Sort:
+
+a1                           a1
+a120                         a2
+a13                          a13
+a2                           a120
+@end example
+
+Version sort functionality in GNU Coreutils is available in the @samp{ls -v},
+@samp{ls --sort=version}, @samp{sort -V}, and
+@samp{sort --version-sort} commands.
+
+
+
+@node Using version sort in GNU Coreutils
+@subsection Using version sort in GNU Coreutils
+
+Two GNU Coreutils programs use version sort: @command{ls} and @command{sort}.
+
+To list files in version sort order, use @command{ls}
+with the @option{-v} or @option{--sort=version} option:
+
+@example
+default sort:              version sort:
+
+$ ls -1                    $ ls -1 -v
+a1                         a1
+a100                       a1.4
+a1.13                      a1.13
+a1.4                       a1.40
+a1.40                      a2
+a2                         a100
+@end example
+
+To sort text files in version sort order, use @command{sort} with
+the @option{-V} or @option{--version-sort} option:
+
+@example
+$ cat input
+b3
+b11
+b1
+b20
+
+
+lexicographic order:       version sort order:
+
+$ sort input               $ sort -V input
+b1                         b1
+b11                        b3
+b20                        b11
+b3                         b20
+@end example
+
+To sort a specific field in a file, use @option{-k/--key} with
+@samp{V} type sorting, which is often combined with @samp{b} to
+ignore leading blanks in the field:
+
+@example
+$ cat input2
+100   b3   apples
+2000  b11  oranges
+3000  b1   potatoes
+4000  b20  bananas
+$ sort -k 2bV,2 input2
+3000  b1   potatoes
+100   b3   apples
+2000  b11  oranges
+4000  b20  bananas
+@end example
+
+@node Version sort and natural sort
+@subsection Version sort and natural sort
+
+In GNU Coreutils, the name @dfn{version sort} was chosen because it is based
+on Debian GNU/Linux's algorithm of sorting packages' versions.
+
+Its goal is to answer questions like
+``Which package is newer, @file{firefox-60.7.2} or @file{firefox-60.12.3}?''
+
+In Coreutils this algorithm was slightly modified to work on more
+general input such as textual strings and file names
+(see @ref{Differences from Debian version sort}).
+
+In other contexts, such as other programs and other programming
+languages, a similar sorting functionality is called
+@uref{https://en.wikipedia.org/wiki/Natural_sort_order,natural sort}.
+
+
+@node Variations in version sort order
+@subsection Variations in version sort order
+
+Currently there is no standard for version sort.
+
+That is: there is no one correct way or universally agreed-upon way to
+order items. Each program and each programming language can decide its
+own ordering algorithm and call it ``version sort'', ``natural sort'',
+or other names.
+
+See @ref{Other version/natural sort implementations} for many examples of
+differing sorting possibilities, each with its own rules and variations.
+
+If you find a bug in the Coreutils implementation of version-sort, please
+report it.  @xref{Reporting version sort bugs}.
+
+
+@node Version sort implementation
+@section Version sort implementation
+
+GNU Coreutils version sort is based on the ``upstream version''
+part of
+@uref{https://www.debian.org/doc/debian-policy/ch-controlfields.html#version,
+Debian's versioning scheme}.
+
+This section describes the GNU Coreutils sort ordering rules.
+
+The next section (@ref{Differences from Debian version
+sort}) describes some differences between GNU Coreutils
+and Debian version sort.
+
+
+@node Version-sort ordering rules
+@subsection Version-sort ordering rules
+
+The version sort ordering rules are:
+
+@enumerate
+@item
+The strings are compared from left to right.
+
+@item
+First the initial part of each string consisting entirely of non-digit
+bytes is determined.
+
+@enumerate A
+@item
+These two parts (either of which may be empty) are compared lexically.
+If a difference is found it is returned.
+
+@item
+The lexical comparison is a lexicographic comparison of byte strings,
+except that:
+
+@enumerate a
+@item
+ASCII letters sort before other bytes.
+@item
+A tilde sorts before anything, even an empty string.
+@end enumerate
+@end enumerate
+
+@item
+Then the initial part of the remainder of each string that contains
+all the leading digits is determined. The numerical values represented by
+these two parts are compared, and any difference found is returned as
+the result of the comparison.
+
+@enumerate A
+@item
+For these purposes an empty string (which can only occur at the end of
+one or both version strings being compared) counts as zero.
+
+@item
+Because the numerical value is used, non-identical strings can compare
+equal.  For example, @samp{123} compares equal to @samp{00123}, and
+the empty string compares equal to @samp{0}.
+@end enumerate
+
+@item
+These two steps (comparing and removing initial non-digit strings and
+initial digit strings) are repeated until a difference is found or
+both strings are exhausted.
+@end enumerate
+
+Consider the version-sort comparison of two file names:
+@file{foo07.7z} and @file{foo7a.7z}. The two strings will be broken
+down to the following parts, and the parts compared respectively from
+each string:
+
+@example
+foo  @r{vs}  foo   @r{(rule 2, non-digits)}
+07   @r{vs}  7     @r{(rule 3, digits)}
+.    @r{vs}  a.    @r{(rule 2)}
+7    @r{vs}  7     @r{(rule 3)}
+z    @r{vs}  z     @r{(rule 2)}
+@end example
+
+Comparison flow based on above algorithm:
+
+@enumerate
+@item
+The first parts (@samp{foo}) are identical.
+
+@item
+The second parts (@samp{07} and @samp{7}) are compared numerically,
+and compare equal.
+
+@item
+The third parts (@samp{.} vs @samp{a.}) are compared
+lexically by ASCII value (rule 2.B).
+
+@item
+The first byte of the first string (@samp{.}) is compared
+to the first byte of the second string (@samp{a}).
+
+@item
+Rule 2.B.a says letters sorts before non-letters.
+Hence, @samp{a} comes before @samp{.}.
+
+@item
+The returned result is that @file{foo7a.7z} comes before @file{foo07.7z}.
+@end enumerate
+
+Result when using sort:
+
+@example
+$ cat input3
+foo07.7z
+foo7a.7z
+$ sort -V input3
+foo7a.7z
+foo07.7z
+@end example
+
+See @ref{Differences from Debian version sort} for
+additional rules that extend the Debian algorithm in Coreutils.
+
+
+@node Version sort is not the same as numeric sort
+@subsection Version sort is not the same as numeric sort
+
+Consider the following text file:
+
+@example
+$ cat input4
+8.10
+8.5
+8.1
+8.01
+8.010
+8.100
+8.49
+
+Numerical Sort:                   Version Sort:
+
+$ sort -n input4                  $ sort -V input4
+8.01                              8.01
+8.010                             8.1
+8.1                               8.5
+8.10                              8.010
+8.100                             8.10
+8.49                              8.49
+8.5                               8.100
+@end example
+
+Numeric sort (@samp{sort -n}) treats the entire string as a single numeric
+value, and compares it to other values. For example, @samp{8.1}, @samp{8.10} and
+@samp{8.100} are numerically equivalent, and are ordered together. Similarly,
+@samp{8.49} is numerically less than @samp{8.5}, and appears before first.
+
+Version sort (@samp{sort -V}) first breaks down the string into digit and
+non-digit parts, and only then compares each part (see annotated
+example in @ref{Version-sort ordering rules}).
+
+Comparing the string @samp{8.1} to @samp{8.01}, first the
+@samp{8}s are compared (and are identical), then the
+dots (@samp{.}) are compared and are identical, and lastly the
+remaining digits are compared numerically (@samp{1} and @samp{01}) --
+which are numerically equal.  Hence, @samp{8.01} and @samp{8.1}
+are grouped together.
+
+Similarly, comparing @samp{8.5} to @samp{8.49} -- the @samp{8}
+and @samp{.} parts are identical, then the numeric values @samp{5} and
+@samp{49} are compared. The resulting @samp{5} appears before @samp{49}.
+
+This sorting order (where @samp{8.5} comes before @samp{8.49}) is common when
+assigning versions to computer programs (while perhaps not intuitive
+or ``natural'' for people).
+
+@node Version sort punctuation
+@subsection Version sort punctuation
+
+Punctuation is sorted by ASCII order (rule 2.B).
+
+@example
+$ touch 1.0.5_src.tar.gz 1.0_src.tar.gz
+$ ls -v -1
+1.0.5_src.tar.gz
+1.0_src.tar.gz
+@end example
+
+Why is @file{1.0.5_src.tar.gz} listed before @file{1.0_src.tar.gz}?
+
+Based on the version-sort ordering rules, the strings are broken down
+into the following parts:
+
+@example
+          1   @r{vs}  1               @r{(rule 3, all digits)}
+          .   @r{vs}  .               @r{(rule 2, all non-digits)}
+          0   @r{vs}  0               @r{(rule 3)}
+          .   @r{vs}  _src.tar.gz     @r{(rule 2)}
+          5   @r{vs}  empty string    @r{(no more bytes in the file name)}
+_src.tar.gz   @r{vs}  empty string
+@end example
+
+The fourth parts (@samp{.} and @samp{_src.tar.gz}) are compared
+lexically by ASCII order. The @samp{.} (ASCII value 46) is
+less than @samp{_} (ASCII value 95) -- and should be listed before it.
+
+Hence, @file{1.0.5_src.tar.gz} is listed first.
+
+If a different byte appears instead of the underscore (for
+example, percent sign @samp{%} ASCII value 37, which is less
+than dot's ASCII value of 46), that file will be listed first:
+
+@example
+$ touch   1.0.5_src.tar.gz     1.0%zzzzz.gz
+1.0%zzzzz.gz
+1.0.5_src.tar.gz
+@end example
+
+The same reasoning applies to the following example, as @samp{.} with
+ASCII value 46 is less than @samp{/} with ASCII value 47:
+
+@example
+$ cat input5
+3.0/
+3.0.5
+$ sort -V input5
+3.0.5
+3.0/
+@end example
+
+
+@node Punctuation vs letters
+@subsection Punctuation vs letters
+
+Rule 2.B.a says letters sort before non-letters
+(after breaking down a string to digit and non-digit parts).
+
+@example
+$ cat input6
+a%
+az
+$ sort -V input6
+az
+a%
+@end example
+
+The input strings consist entirely of non-digits, and based on the
+above algorithm have only one part, all non-digits
+(@samp{a%} vs @samp{az}).
+
+Each part is then compared lexically,
+byte-by-byte; @samp{a} compares identically in both
+strings.
+
+Rule 2.B.a says a letter like @samp{z} sorts before
+a non-letter like @samp{%} -- hence @samp{az} appears first (despite
+@samp{z} having ASCII value of 122, much larger than @samp{%}
+with ASCII value 37).
+
+@node The tilde @samp{~}
+@subsection The tilde @samp{~}
+
+Rule 2.B.b says the tilde @samp{~} (ASCII 126) sorts
+before other bytes, and before an empty string.
+
+@example
+$ cat input7
+1
+1%
+1.2
+1~
+~
+$ sort -V input7
+~
+1~
+1
+1%
+1.2
+@end example
+
+The sorting algorithm starts by breaking down the string into
+non-digit (rule 2) and digit parts (rule 3).
+
+In the above input file, only the last line in the input file starts
+with a non-digit (@samp{~}). This is the first part. All other lines
+in the input file start with a digit -- their first non-digit part is
+empty.
+
+Based on rule 2.B.b, tilde @samp{~} sorts before other bytes
+and before the empty string -- hence it comes before all other strings,
+and is listed first in the sorted output.
+
+The remaining lines (@samp{1}, @samp{1%}, @samp{1.2}, @samp{1~})
+follow similar logic: The digit part is extracted (1 for all strings)
+and compares equal. The following extracted parts for the remaining
+input lines are: empty part, @samp{%}, @samp{.}, @samp{~}.
+
+Tilde sorts before all others, hence the line @samp{1~} appears next.
+
+The remaining lines (@samp{1}, @samp{1%}, @samp{1.2}) are sorted based
+on previously explained rules.
+
+@node Version sort ignores locale
+@subsection Version sort ignores locale
+
+In version sort, Unicode characters are compared byte-by-byte according
+to their binary representation, ignoring their Unicode value or the
+current locale.
+
+Most commonly, Unicode characters are encoded as UTF-8 bytes; for
+example, GREEK SMALL LETTER ALPHA (U+03B1, @samp{α}) is encoded as the
+UTF-8 sequence @samp{0xCE 0xB1}).  The encoding is compared
+byte-by-byte, e.g., first @samp{0xCE} (decimal value 206) then
+@samp{0xB1} (decimal value 177).
+
+@example
+$ touch aa az "a%" "aα"
+$ ls -1 -v
+aa
+az
+a%
+aα
+@end example
+
+Ignoring the first letter (@samp{a}) which is identical in all
+strings, the compared values are:
+
+@samp{a} and @samp{z} are letters, and sort before
+all other non-digits.
+
+Then, percent sign @samp{%} (ASCII value 37) is compared to the
+first byte of the UTF-8 sequence of @samp{α}, which is 0xCE or 206). The
+value 37 is smaller, hence @samp{a%} is listed before @samp{aα}.
+
+@node Differences from Debian version sort
+@section Differences from Debian version sort
+
+GNU Coreutils version sort differs slightly from the
+official Debian algorithm, in order to accommodate more general usage
+and file name listing.
+
+
+@node Hyphen-minus and colon
+@subsection Hyphen-minus @samp{-} and colon @samp{:}
+
+In Debian's version string syntax the version consists of three parts:
+@example
+[epoch:]upstream_version[-debian_revision]
+@end example
+The @samp{epoch} and @samp{debian_revision} parts are optional.
+
+Example of such version strings:
+
+@example
+60.7.2esr-1~deb9u1
+52.9.0esr-1~deb9u1
+1:2.3.4-1+b2
+327-2
+1:1.0.13-3
+2:1.19.2-1+deb9u5
+@end example
+
+If the @samp{debian_revision part} is not present,
+hyphens @samp{-} are not allowed.
+If epoch is not present, colons @samp{:} are not allowed.
+
+If these parts are present, hyphen and/or colons can appear only once
+in valid Debian version strings.
+
+In GNU Coreutils, such restrictions are not reasonable (a file name can
+have many hyphens, a line of text can have many colons).
+
+As a result, in GNU Coreutils hyphens and colons are treated exactly
+like all other punctuation, i.e., they are sorted after
+letters.  @xref{Version sort punctuation}.
+
+In Debian, these characters are treated differently than in Coreutils:
+a version string with hyphen will sort before similar strings without
+hyphens.
+
+Compare:
+
+@example
+$ touch 1ab-cd 1abb
+$ ls -v -1
+1abb
+1ab-cd
+$ if dpkg --compare-versions 1abb lt 1ab-cd
+> then echo sorted
+> else echo out of order
+> fi
+out of order
+@end example
+
+For further details, see @ref{Comparing two strings using Debian's
+algorithm} and @uref{https://bugs.gnu.org/35939,GNU Bug 35939}.
+
+@node Special priority in GNU Coreutils version sort
+@subsection Special priority in GNU Coreutils version sort
+
+In GNU Coreutils version sort, the following items have
+special priority and sort before all other strings (listed in order):
+
+@enumerate
+@item The empty string
+
+@item The string @samp{.} (a single dot, ASCII 46)
+
+@item The string @samp{..} (two dots)
+
+@item Strings starting with dot (@samp{.}) sort before
+strings starting with any other byte.
+@end enumerate
+
+Example:
+
+@example
+$ printf '%s\n' a "" b "." c  ".."  ".d20" ".d3"  | sort -V
+.
+..
+.d3
+.d20
+a
+b
+c
+@end example
+
+These priorities make perfect sense for @samp{ls -v}: The special
+files dot @samp{.} and dot-dot @samp{..} will be listed
+first, followed by any hidden files (files starting with a dot),
+followed by non-hidden files.
+
+For @samp{sort -V} these priorities might seem arbitrary. However,
+because the sorting code is shared between the @command{ls} and @command{sort}
+program, the ordering rules are the same.
+
+@node Special handling of file extensions
+@subsection Special handling of file extensions
+
+GNU Coreutils version sort implements specialized handling
+of strings that look like file names with extensions.
+This enables slightly more natural ordering of file
+names.
+
+The following additional rules apply when comparing two strings where
+both begin with non-@samp{.}.  They also apply when comparing two
+strings where both begin with @samp{.} but neither is @samp{.} or @samp{..}.
+
+@enumerate
+@item
+A suffix (i.e., a file extension) is defined as: a dot, followed by an
+ASCII letter or tilde, followed by zero or more ASCII letters, digits,
+or tildes; all repeated zero or more times, and ending at string end.
+This is equivalent to matching the extended regular expression
+@code{(\.[A-Za-z~][A-Za-z0-9~]*)*$} in the C locale.
+The longest such match is used, except that a suffix is not
+allowed to match an entire nonempty string.
+
+@item
+The suffixes are temporarily removed, and the strings are compared
+without them, using version sort (see @ref{Version-sort ordering
+rules}) without special priority (see @ref{Special priority in GNU
+Coreutils version sort}).
+
+@item
+If the suffix-less strings do not compare equal, this comparison
+result is used and the suffixes are effectively ignored.
+
+@item
+If the suffix-less strings compare equal, the suffixes are restored
+and the entire strings are compared using version sort.
+@end enumerate
+
+Examples for rule 1:
+
+@itemize
+@item
+@samp{hello-8.txt}: the suffix is @samp{.txt}
+
+@item
+@samp{hello-8.2.txt}: the suffix is @samp{.txt}
+(@samp{.2} is not included because the dot is not followed by a letter)
+
+@item
+@samp{hello-8.0.12.tar.gz}: the suffix is @samp{.tar.gz} (@samp{.0.12}
+is not included)
+
+@item
+@samp{hello-8.2}: no suffix (suffix is an empty string)
+
+@item
+@samp{hello.foobar65}: the suffix is @samp{.foobar65}
+
+@item
+@samp{gcc-c++-10.8.12-0.7rc2.fc9.tar.bz2}: the suffix is
+@samp{.fc9.tar.bz2} (@samp{.7rc2} is not included as it begins with a digit)
+
+@item
+@samp{.autom4te.cfg}: the suffix is the entire string.
+@end itemize
+
+Examples for rule 2:
+
+@itemize
+@item
+Comparing @samp{hello-8.txt} to @samp{hello-8.2.12.txt}, the
+@samp{.txt} suffix is temporarily removed from both strings.
+
+@item
+Comparing @samp{foo-10.3.tar.gz} to @samp{foo-10.tar.xz}, the suffixes
+@samp{.tar.gz} and @samp{.tar.xz} are temporarily removed from the
+strings.
+@end itemize
+
+Example for rule 3:
+
+@itemize
+@item
+Comparing @samp{hello.foobar65} to @samp{hello.foobar4}, the suffixes
+(@samp{.foobar65} and @samp{.foobar4}) are temporarily removed. The
+remaining strings are identical (@samp{hello}). The suffixes are then
+restored, and the entire strings are compared (@samp{hello.foobar4} comes
+first).
+@end itemize
+
+Examples for rule 4:
+
+@itemize
+@item
+When comparing the strings @samp{hello-8.2.txt} and @samp{hello-8.10.txt}, the
+suffixes (@samp{.txt}) are temporarily removed. The remaining strings
+(@samp{hello-8.2} and @samp{hello-8.10}) are compared as previously described
+(@samp{hello-8.2} comes first).
+@slanted{(In this case the suffix removal algorithm
+does not have a noticeable effect on the resulting order.)}
+@end itemize
+
+@b{How does the suffix-removal algorithm effect ordering results?}
+
+Consider the comparison of hello-8.txt and hello-8.2.txt.
+
+Without the suffix-removal algorithm, the strings will be broken down
+to the following parts:
+
+@example
+hello-  @r{vs}  hello-  @r{(rule 2, all non-digits)}
+8       @r{vs}  8       @r{(rule 3, all digits)}
+.txt    @r{vs}  .       @r{(rule 2)}
+empty   @r{vs}  2
+empty   @r{vs}  .txt
+@end example
+
+The comparison of the third parts (@samp{.} vs
+@samp{.txt}) will determine that the shorter string comes first --
+resulting in @file{hello-8.2.txt} appearing first.
+
+Indeed this is the order in which Debian's @command{dpkg} compares the strings.
+
+A more natural result is that @file{hello-8.txt} should come before
+@file{hello-8.2.txt}, and this is where the suffix-removal comes into play:
+
+The suffixes (@samp{.txt}) are removed, and the remaining strings are
+broken down into the following parts:
+
+@example
+hello-  @r{vs}  hello-  @r{(rule 2, all non-digits)}
+8       @r{vs}  8       @r{(rule 3, all digits)}
+empty   @r{vs}  .       @r{(rule 2)}
+empty   @r{vs}  2
+@end example
+
+As empty strings sort before non-empty strings, the result is @samp{hello-8}
+being first.
+
+A real-world example would be listing files such as:
+@file{gcc_10.fc9.tar.gz}
+and @file{gcc_10.8.12.7rc2.fc9.tar.bz2}: Debian's algorithm would list
+@file{gcc_10.8.12.7rc2.fc9.tar.bz2} first, while @samp{ls -v} will list
+@file{gcc_10.fc9.tar.gz} first.
+
+These priorities make sense for @samp{ls -v}:
+Versioned files will be listed in a more natural order.
+
+For @samp{sort -V} these priorities might seem arbitrary. However,
+because the sorting code is shared between the @command{ls} and @command{sort}
+program, the ordering rules are the same.
+
+
+@node Comparing two strings using Debian's algorithm
+@subsection Comparing two strings using Debian's algorithm
+
+The Debian program @command{dpkg} (available on all Debian and Ubuntu
+installations) can compare two strings using the @option{--compare-versions}
+option.
+
+To use it, create a helper shell function (simply copy & paste the
+following snippet to your shell command-prompt):
+
+@example
+compver() @{
+  if dpkg --compare-versions "$1" lt "$2"
+  then printf '%s\n' "$1" "$2"
+  else printf '%s\n' "$2" "$1"
+  fi
+@}
+@end example
+
+Then compare two strings by calling @command{compver}:
+
+@example
+$ compver 8.49 8.5
+8.5
+8.49
+@end example
+
+Note that @command{dpkg} will warn if the strings have invalid syntax:
+
+@example
+$ compver "foo07.7z" "foo7a.7z"
+dpkg: warning: version 'foo07.7z' has bad syntax:
+               version number does not start with digit
+dpkg: warning: version 'foo7a.7z' has bad syntax:
+               version number does not start with digit
+foo7a.7z
+foo07.7z
+$ compver "3.0/" "3.0.5"
+dpkg: warning: version '3.0/' has bad syntax:
+               invalid character in version number
+3.0.5
+3.0/
+@end example
+
+To illustrate the different handling of hyphens between Debian and
+Coreutils algorithms (see
+@ref{Hyphen-minus and colon}):
+
+@example
+$ compver abb ab-cd 2>/dev/null     $ printf 'abb\nab-cd\n' | sort -V
+ab-cd                               abb
+abb                                 ab-cd
+@end example
+
+To illustrate the different handling of file extension: (see @ref{Special
+handling of file extensions}):
+
+@example
+$ compver hello-8.txt hello-8.2.txt 2>/dev/null
+hello-8.2.txt
+hello-8.txt
+$ printf '%s\n' hello-8.txt hello-8.2.txt | sort -V
+hello-8.txt
+hello-8.2.txt
+@end example
+
+
+@node Advanced version sort topics
+@section Advanced Topics
+
+
+@node Reporting version sort bugs
+@subsection Reporting version sort bugs
+
+If you suspect a bug in GNU Coreutils version sort (i.e., in the
+output of @samp{ls -v} or @samp{sort -V}), please first check the following:
+
+@enumerate
+@item
+Is the result consistent with Debian's own ordering (using @command{dpkg}, see
+@ref{Comparing two strings using Debian's algorithm})? If it is, then this
+is not a bug -- please do not report it.
+
+@item
+If the result differs from Debian's, is it explained by one of the
+sections in @ref{Differences from Debian version sort}? If it is,
+then this is not a bug -- please do not report it.
+
+@item
+If you have a question about specific ordering which is not explained
+here, please write to @email{coreutils@@gnu.org}, and provide a
+concise example that will help us diagnose the issue.
+
+@item
+If you still suspect a bug which is not explained by the above, please
+write to @email{bug-coreutils@@gnu.org} with a concrete example of the
+suspected incorrect output, with details on why you think it is
+incorrect.
+
+@end enumerate
+
+@node Other version/natural sort implementations
+@subsection Other version/natural sort implementations
+
+As previously mentioned, there are multiple variations on
+version/natural sort, each with its own rules. Some examples are:
+
+@itemize
+
+@item
+Natural Sorting variants in
+@uref{https://rosettacode.org/wiki/Natural_sorting,Rosetta Code}.
+
+@item
+Python's @uref{https://pypi.org/project/natsort/,natsort package}
+(includes detailed description of their sorting rules:
+@uref{https://natsort.readthedocs.io/en/master/howitworks.html,
+natsort -- how it works}).
+
+@item
+Ruby's @uref{https://github.com/github/version_sorter,version_sorter}.
+
+@item
+Perl has multiple packages for natural and version sorts
+(each likely with its own rules and nuances):
+@uref{https://metacpan.org/pod/Sort::Naturally,Sort::Naturally},
+@uref{https://metacpan.org/pod/Sort::Versions,Sort::Versions},
+@uref{https://metacpan.org/pod/CPAN::Version,CPAN::Version}.
+
+@item
+PHP has a built-in function
+@uref{https://www.php.net/manual/en/function.natsort.php,natsort}.
+
+@item
+NodeJS's @uref{https://www.npmjs.com/package/natural-sort,natural-sort package}.
+
+@item
+In zsh, the
+@uref{http://zsh.sourceforge.net/Doc/Release/Expansion.html#Glob-Qualifiers,
+glob modifier} @samp{*(n)} will expand to files in natural sort order.
+
+@item
+When writing C programs, the GNU libc library (@samp{glibc})
+provides the
+@uref{https://man7.org/linux/man-pages/man3/strverscmp.3.html,
+strverscmp(3)} function to compare two strings, and
+@uref{https://man7.org/linux/man-pages/man3/versionsort.3.html,versionsort(3)}
+function to compare two directory entries (despite the names, they are
+not identical to GNU Coreutils version sort ordering).
+
+@item
+Using Debian's sorting algorithm in:
+
+@itemize
+@item
+python: @uref{https://stackoverflow.com/a/4957741,
+Stack Overflow Example #4957741}.
+
+@item
+NodeJS: @uref{https://www.npmjs.com/package/deb-version-compare,
+deb-version-compare}.
+@end itemize
+
+@end itemize
+
+
+@node Related source code
+@subsection Related source code
+
+@itemize
+
+@item
+Debian's code which splits a version string into
+@code{epoch/upstream_version/debian_revision} parts:
+@uref{https://git.dpkg.org/cgit/dpkg/dpkg.git/tree/lib/dpkg/parsehelp.c#n191,
+parsehelp.c:parseversion()}.
+
+@item
+Debian's code which performs the @code{upstream_version} comparison:
+@uref{https://git.dpkg.org/cgit/dpkg/dpkg.git/tree/lib/dpkg/version.c#n140,
+version.c}.
+
+@item
+Gnulib code (used by GNU Coreutils) which performs the version comparison:
+@uref{https://git.savannah.gnu.org/cgit/gnulib.git/tree/lib/filevercmp.c,
+filevercmp.c}.
+@end itemize
diff --git a/doc/stamp-vti b/doc/stamp-vti
new file mode 100644
index 0000000..a4ec8d7
--- /dev/null
+++ b/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 29 August 2023
+@set UPDATED-MONTH August 2023
+@set EDITION 9.4
+@set VERSION 9.4
diff --git a/doc/version.texi b/doc/version.texi
new file mode 100644
index 0000000..a4ec8d7
--- /dev/null
+++ b/doc/version.texi
@@ -0,0 +1,4 @@
+@set UPDATED 29 August 2023
+@set UPDATED-MONTH August 2023
+@set EDITION 9.4
+@set VERSION 9.4