diff options
Diffstat (limited to 'doc/coreutils.texi')
| -rw-r--r-- | doc/coreutils.texi | 20122 |
1 files changed, 20122 insertions, 0 deletions
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: |