1\input texinfo 2@c %**start of header 3@setfilename coreutils.info 4@include version.texi 5@settitle GNU Coreutils @value{VERSION} 6@documentencoding UTF-8 7@set txicodequoteundirected 8@set txicodequotebacktick 9@allowcodebreaks false 10 11@c %**end of header 12 13@include constants.texi 14 15@c Define new indices. 16@defcodeindex op 17@defcodeindex fl 18 19@c Put everything in one index (arbitrarily chosen to be the concept index). 20@syncodeindex fl cp 21@syncodeindex fn cp 22@syncodeindex ky cp 23@syncodeindex op cp 24@syncodeindex pg cp 25@syncodeindex vr cp 26 27@dircategory Basics 28@direntry 29* Coreutils: (coreutils). Core GNU (file, text, shell) utilities. 30* Common options: (coreutils)Common options. 31* File permissions: (coreutils)File permissions. Access modes. 32* Date input formats: (coreutils)Date input formats. 33@end direntry 34 35@c FIXME: the following need documentation 36@c * [: (coreutils)[ invocation. File/string tests. 37@c * pinky: (coreutils)pinky invocation. FIXME. 38 39@dircategory Individual utilities 40@direntry 41* arch: (coreutils)arch invocation. Print machine hardware name. 42* b2sum: (coreutils)b2sum invocation. Print or check BLAKE2 digests. 43* base32: (coreutils)base32 invocation. Base32 encode/decode data. 44* base64: (coreutils)base64 invocation. Base64 encode/decode data. 45* basename: (coreutils)basename invocation. Strip directory and suffix. 46* basenc: (coreutils)basenc invocation. Encoding/decoding of data. 47* cat: (coreutils)cat invocation. Concatenate and write files. 48* chcon: (coreutils)chcon invocation. Change SELinux CTX of files. 49* chgrp: (coreutils)chgrp invocation. Change file groups. 50* chmod: (coreutils)chmod invocation. Change access permissions. 51* chown: (coreutils)chown invocation. Change file owners and groups. 52* chroot: (coreutils)chroot invocation. Specify the root directory. 53* cksum: (coreutils)cksum invocation. Print POSIX CRC checksum. 54* comm: (coreutils)comm invocation. Compare sorted files by line. 55* cp: (coreutils)cp invocation. Copy files. 56* csplit: (coreutils)csplit invocation. Split by context. 57* cut: (coreutils)cut invocation. Print selected parts of lines. 58* date: (coreutils)date invocation. Print/set system date and time. 59* dd: (coreutils)dd invocation. Copy and convert a file. 60* df: (coreutils)df invocation. Report file system usage. 61* dir: (coreutils)dir invocation. List directories briefly. 62* dircolors: (coreutils)dircolors invocation. Color setup for ls. 63* dirname: (coreutils)dirname invocation. Strip last file name component. 64* du: (coreutils)du invocation. Report file usage. 65* echo: (coreutils)echo invocation. Print a line of text. 66* env: (coreutils)env invocation. Modify the environment. 67* expand: (coreutils)expand invocation. Convert tabs to spaces. 68* expr: (coreutils)expr invocation. Evaluate expressions. 69* factor: (coreutils)factor invocation. Print prime factors 70* false: (coreutils)false invocation. Do nothing, unsuccessfully. 71* fmt: (coreutils)fmt invocation. Reformat paragraph text. 72* fold: (coreutils)fold invocation. Wrap long input lines. 73* groups: (coreutils)groups invocation. Print group names a user is in. 74* head: (coreutils)head invocation. Output the first part of files. 75* hostid: (coreutils)hostid invocation. Print numeric host identifier. 76* hostname: (coreutils)hostname invocation. Print or set system name. 77* id: (coreutils)id invocation. Print user identity. 78* install: (coreutils)install invocation. Copy files and set attributes. 79* join: (coreutils)join invocation. Join lines on a common field. 80* kill: (coreutils)kill invocation. Send a signal to processes. 81* link: (coreutils)link invocation. Make hard links between files. 82* ln: (coreutils)ln invocation. Make links between files. 83* logname: (coreutils)logname invocation. Print current login name. 84* ls: (coreutils)ls invocation. List directory contents. 85* md5sum: (coreutils)md5sum invocation. Print or check MD5 digests. 86* mkdir: (coreutils)mkdir invocation. Create directories. 87* mkfifo: (coreutils)mkfifo invocation. Create FIFOs (named pipes). 88* mknod: (coreutils)mknod invocation. Create special files. 89* mktemp: (coreutils)mktemp invocation. Create temporary files. 90* mv: (coreutils)mv invocation. Rename files. 91* nice: (coreutils)nice invocation. Modify niceness. 92* nl: (coreutils)nl invocation. Number lines and write files. 93* nohup: (coreutils)nohup invocation. Immunize to hangups. 94* nproc: (coreutils)nproc invocation. Print the number of processors. 95* numfmt: (coreutils)numfmt invocation. Reformat numbers. 96* od: (coreutils)od invocation. Dump files in octal, etc. 97* paste: (coreutils)paste invocation. Merge lines of files. 98* pathchk: (coreutils)pathchk invocation. Check file name portability. 99* pr: (coreutils)pr invocation. Paginate or columnate files. 100* printenv: (coreutils)printenv invocation. Print environment variables. 101* printf: (coreutils)printf invocation. Format and print data. 102* ptx: (coreutils)ptx invocation. Produce permuted indexes. 103* pwd: (coreutils)pwd invocation. Print working directory. 104* readlink: (coreutils)readlink invocation. Print referent of a symlink. 105* realpath: (coreutils)realpath invocation. Print resolved file names. 106* rm: (coreutils)rm invocation. Remove files. 107* rmdir: (coreutils)rmdir invocation. Remove empty directories. 108* runcon: (coreutils)runcon invocation. Run in specified SELinux CTX. 109* seq: (coreutils)seq invocation. Print numeric sequences 110* sha1sum: (coreutils)sha1sum invocation. Print or check SHA-1 digests. 111* sha2: (coreutils)sha2 utilities. Print or check SHA-2 digests. 112* shred: (coreutils)shred invocation. Remove files more securely. 113* shuf: (coreutils)shuf invocation. Shuffling text files. 114* sleep: (coreutils)sleep invocation. Delay for a specified time. 115* sort: (coreutils)sort invocation. Sort text files. 116* split: (coreutils)split invocation. Split into pieces. 117* stat: (coreutils)stat invocation. Report file(system) status. 118* stdbuf: (coreutils)stdbuf invocation. Modify stdio buffering. 119* stty: (coreutils)stty invocation. Print/change terminal settings. 120* sum: (coreutils)sum invocation. Print traditional checksum. 121* sync: (coreutils)sync invocation. Sync files to stable storage. 122* tac: (coreutils)tac invocation. Reverse files. 123* tail: (coreutils)tail invocation. Output the last part of files. 124* tee: (coreutils)tee invocation. Redirect to multiple files. 125* test: (coreutils)test invocation. File/string tests. 126* timeout: (coreutils)timeout invocation. Run with time limit. 127* touch: (coreutils)touch invocation. Change file timestamps. 128* tr: (coreutils)tr invocation. Translate characters. 129* true: (coreutils)true invocation. Do nothing, successfully. 130* truncate: (coreutils)truncate invocation. Shrink/extend size of a file. 131* tsort: (coreutils)tsort invocation. Topological sort. 132* tty: (coreutils)tty invocation. Print terminal name. 133* uname: (coreutils)uname invocation. Print system information. 134* unexpand: (coreutils)unexpand invocation. Convert spaces to tabs. 135* uniq: (coreutils)uniq invocation. Uniquify files. 136* unlink: (coreutils)unlink invocation. Removal via unlink(2). 137* uptime: (coreutils)uptime invocation. Print uptime and load. 138* users: (coreutils)users invocation. Print current user names. 139* vdir: (coreutils)vdir invocation. List directories verbosely. 140* wc: (coreutils)wc invocation. Line, word, and byte counts. 141* who: (coreutils)who invocation. Print who is logged in. 142* whoami: (coreutils)whoami invocation. Print effective user ID. 143* yes: (coreutils)yes invocation. Print a string indefinitely. 144@end direntry 145 146@copying 147This manual documents version @value{VERSION} of the GNU core 148utilities, including the standard programs for text and file manipulation. 149 150Copyright @copyright{} 1994--2023 Free Software Foundation, Inc. 151 152@quotation 153Permission is granted to copy, distribute and/or modify this document 154under the terms of the GNU Free Documentation License, Version 1.3 or 155any later version published by the Free Software Foundation; with no 156Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 157Texts. A copy of the license is included in the section entitled ``GNU 158Free Documentation License''. 159@end quotation 160@end copying 161 162@titlepage 163@title GNU @code{Coreutils} 164@subtitle Core GNU utilities 165@subtitle for version @value{VERSION}, @value{UPDATED} 166@author David MacKenzie et al. 167 168@page 169@vskip 0pt plus 1filll 170@insertcopying 171@end titlepage 172@shortcontents 173@contents 174 175@ifnottex 176@node Top 177@top GNU Coreutils 178 179@insertcopying 180@end ifnottex 181 182@cindex core utilities 183@cindex text utilities 184@cindex shell utilities 185@cindex file utilities 186 187@menu 188* Introduction:: Caveats, overview, and authors 189* Common options:: Common options 190* Output of entire files:: cat tac nl od base32 base64 basenc 191* Formatting file contents:: fmt pr fold 192* Output of parts of files:: head tail split csplit 193* Summarizing files:: wc sum cksum b2sum md5sum sha1sum sha2 194* Operating on sorted files:: sort shuf uniq comm ptx tsort 195* Operating on fields:: cut paste join 196* Operating on characters:: tr expand unexpand 197* Directory listing:: ls dir vdir dircolors 198* Basic operations:: cp dd install mv rm shred 199* Special file types:: mkdir rmdir unlink mkfifo mknod ln link readlink 200* Changing file attributes:: chgrp chmod chown touch 201* File space usage:: df du stat sync truncate 202* Printing text:: echo printf yes 203* Conditions:: false true test expr 204* Redirection:: tee 205* File name manipulation:: dirname basename pathchk mktemp realpath 206* Working context:: pwd stty printenv tty 207* User information:: id logname whoami groups users who 208* System context:: date arch nproc uname hostname hostid uptime 209* SELinux context:: chcon runcon 210* Modified command invocation:: chroot env nice nohup stdbuf timeout 211* Process control:: kill 212* Delaying:: sleep 213* Numeric operations:: factor numfmt seq 214* File permissions:: Access modes 215* File timestamps:: File timestamp issues 216* Date input formats:: Specifying date strings 217* Version sort ordering:: Details on version-sort algorithm 218* Opening the software toolbox:: The software tools philosophy 219* GNU Free Documentation License:: Copying and sharing this manual 220* Concept index:: General index 221 222@detailmenu 223 --- The Detailed Node Listing --- 224 225Common Options 226 227* Exit status:: Indicating program success or failure 228* Backup options:: Backup options 229* Block size:: Block size 230* Floating point:: Floating point number representation 231* Signal specifications:: Specifying signals 232* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax 233* Random sources:: Sources of random data 234* Target directory:: Target directory 235* Trailing slashes:: Trailing slashes 236* Traversing symlinks:: Traversing symlinks to directories 237* Treating / specially:: Treating / specially 238* Standards conformance:: Standards conformance 239* Multi-call invocation:: Multi-call program invocation 240 241Output of entire files 242 243* cat invocation:: Concatenate and write files 244* tac invocation:: Concatenate and write files in reverse 245* nl invocation:: Number lines and write files 246* od invocation:: Write files in octal or other formats 247* base32 invocation:: Transform data into printable data 248* base64 invocation:: Transform data into printable data 249* basenc invocation:: Transform data into printable data 250 251Formatting file contents 252 253* fmt invocation:: Reformat paragraph text 254* pr invocation:: Paginate or columnate files for printing 255* fold invocation:: Wrap input lines to fit in specified width 256 257Output of parts of files 258 259* head invocation:: Output the first part of files 260* tail invocation:: Output the last part of files 261* split invocation:: Split a file into fixed-size pieces 262* csplit invocation:: Split a file into context-determined pieces 263 264Summarizing files 265 266* wc invocation:: Print newline, word, and byte counts 267* sum invocation:: Print checksum and block counts 268* cksum invocation:: Print CRC checksum and byte counts 269* md5sum invocation:: Print or check MD5 digests 270* b2sum invocation:: Print or check BLAKE2 digests 271* sha1sum invocation:: Print or check SHA-1 digests 272* sha2 utilities:: Print or check SHA-2 digests 273 274Operating on sorted files 275 276* sort invocation:: Sort text files 277* shuf invocation:: Shuffle text files 278* uniq invocation:: Uniquify files 279* comm invocation:: Compare two sorted files line by line 280* ptx invocation:: Produce a permuted index of file contents 281* tsort invocation:: Topological sort 282 283@command{ptx}: Produce permuted indexes 284 285* General options in ptx:: Options which affect general program behavior 286* Charset selection in ptx:: Underlying character set considerations 287* Input processing in ptx:: Input fields, contexts, and keyword selection 288* Output formatting in ptx:: Types of output format, and sizing the fields 289* Compatibility in ptx:: The GNU extensions to @command{ptx} 290 291Operating on fields 292 293* cut invocation:: Print selected parts of lines 294* paste invocation:: Merge lines of files 295* join invocation:: Join lines on a common field 296 297Operating on characters 298 299* tr invocation:: Translate, squeeze, and/or delete characters 300* expand invocation:: Convert tabs to spaces 301* unexpand invocation:: Convert spaces to tabs 302 303@command{tr}: Translate, squeeze, and/or delete characters 304 305* Character arrays:: Specifying arrays of characters 306* Translating:: Changing one set of characters to another 307* Squeezing and deleting:: Removing characters 308 309Directory listing 310 311* ls invocation:: List directory contents 312* dir invocation:: Briefly list directory contents 313* vdir invocation:: Verbosely list directory contents 314* dircolors invocation:: Color setup for @command{ls} 315 316@command{ls}: List directory contents 317 318* Which files are listed:: Which files are listed 319* What information is listed:: What information is listed 320* Sorting the output:: Sorting the output 321* General output formatting:: General output formatting 322* Formatting the file names:: Formatting the file names 323 324Basic operations 325 326* cp invocation:: Copy files and directories 327* dd invocation:: Convert and copy a file 328* install invocation:: Copy files and set attributes 329* mv invocation:: Move (rename) files 330* rm invocation:: Remove files or directories 331* shred invocation:: Remove files more securely 332 333Special file types 334 335* link invocation:: Make a hard link via the link syscall 336* ln invocation:: Make links between files 337* mkdir invocation:: Make directories 338* mkfifo invocation:: Make FIFOs (named pipes) 339* mknod invocation:: Make block or character special files 340* readlink invocation:: Print value of a symlink or canonical file name 341* rmdir invocation:: Remove empty directories 342* unlink invocation:: Remove files via unlink syscall 343 344Changing file attributes 345 346* chown invocation:: Change file owner and group 347* chgrp invocation:: Change group ownership 348* chmod invocation:: Change access permissions 349* touch invocation:: Change file timestamps 350 351File space usage 352 353* df invocation:: Report file system space usage 354* du invocation:: Estimate file space usage 355* stat invocation:: Report file or file system status 356* sync invocation:: Synchronize cached writes to persistent storage 357* truncate invocation:: Shrink or extend the size of a file 358 359Printing text 360 361* echo invocation:: Print a line of text 362* printf invocation:: Format and print data 363* yes invocation:: Print a string until interrupted 364 365Conditions 366 367* false invocation:: Do nothing, unsuccessfully 368* true invocation:: Do nothing, successfully 369* test invocation:: Check file types and compare values 370* expr invocation:: Evaluate expressions 371 372@command{test}: Check file types and compare values 373 374* File type tests:: File type tests 375* Access permission tests:: Access permission tests 376* File characteristic tests:: File characteristic tests 377* String tests:: String tests 378* Numeric tests:: Numeric tests 379 380@command{expr}: Evaluate expression 381 382* String expressions:: @code{+ : match substr index length} 383* Numeric expressions:: @code{+ - * / %} 384* Relations for expr:: @code{| & < <= = == != >= >} 385* Examples of expr:: Examples of using @command{expr} 386 387Redirection 388 389* tee invocation:: Redirect output to multiple files or processes 390 391File name manipulation 392 393* basename invocation:: Strip directory and suffix from a file name 394* dirname invocation:: Strip last file name component 395* pathchk invocation:: Check file name validity and portability 396* mktemp invocation:: Create temporary file or directory 397* realpath invocation:: Print resolved file names 398 399Working context 400 401* pwd invocation:: Print working directory 402* stty invocation:: Print or change terminal characteristics 403* printenv invocation:: Print all or some environment variables 404* tty invocation:: Print file name of terminal on standard input 405 406@command{stty}: Print or change terminal characteristics 407 408* Control:: Control settings 409* Input:: Input settings 410* Output:: Output settings 411* Local:: Local settings 412* Combination:: Combination settings 413* Characters:: Special characters 414* Special:: Special settings 415 416User information 417 418* id invocation:: Print user identity 419* logname invocation:: Print current login name 420* whoami invocation:: Print effective user ID 421* groups invocation:: Print group names a user is in 422* users invocation:: Print login names of users currently logged in 423* who invocation:: Print who is currently logged in 424 425System context 426 427* arch invocation:: Print machine hardware name 428* date invocation:: Print or set system date and time 429* nproc invocation:: Print the number of processors 430* uname invocation:: Print system information 431* hostname invocation:: Print or set system name 432* hostid invocation:: Print numeric host identifier 433* uptime invocation:: Print system uptime and load 434 435@command{date}: Print or set system date and time 436 437* Time conversion specifiers:: %[HIklMNpPrRsSTXzZ] 438* Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY] 439* Literal conversion specifiers:: %[%nt] 440* Padding and other flags:: Pad with zeros, spaces, etc. 441* Setting the time:: Changing the system clock 442* Options for date:: Instead of the current time 443* Date input formats:: Specifying date strings 444* Examples of date:: Examples 445 446SELinux context 447 448* chcon invocation:: Change SELinux context of file 449* runcon invocation:: Run a command in specified SELinux context 450 451Modified command invocation 452 453* chroot invocation:: Run a command with a different root directory 454* env invocation:: Run a command in a modified environment 455* nice invocation:: Run a command with modified niceness 456* nohup invocation:: Run a command immune to hangups 457* stdbuf invocation:: Run a command with modified I/O buffering 458* timeout invocation:: Run a command with a time limit 459 460Process control 461 462* kill invocation:: Sending a signal to processes. 463 464Delaying 465 466* sleep invocation:: Delay for a specified time 467 468Numeric operations 469 470* factor invocation:: Print prime factors 471* numfmt invocation:: Reformat numbers 472* seq invocation:: Print numeric sequences 473 474 475File timestamps 476 477* File timestamps:: File timestamp issues 478 479File permissions 480 481* Mode Structure:: Structure of file mode bits 482* Symbolic Modes:: Mnemonic representation of file mode bits 483* Numeric Modes:: File mode bits as octal numbers 484* Directory Setuid and Setgid:: Set-user-ID and set-group-ID on directories 485 486Date input formats 487 488* General date syntax:: Common rules 489* Calendar date items:: @samp{14 Nov 2022} 490* Time of day items:: @samp{9:02pm} 491* Time zone items:: @samp{UTC}, @samp{-0700}, @samp{+0900}, @dots{} 492* Combined date and time of day items:: @samp{2022-11-14T21:02:42,000000-0500} 493* Day of week items:: @samp{Monday} and others 494* Relative items in date strings:: @samp{next tuesday, 2 years ago} 495* Pure numbers in date strings:: @samp{20221114}, @samp{2102} 496* Seconds since the Epoch:: @samp{@@1668477762} 497* Specifying time zone rules:: @samp{TZ="America/New_York"}, @samp{TZ="UTC0"} 498* Authors of parse_datetime:: Bellovin, Eggert, Salz, Berets, et al. 499 500Version sorting order 501 502* Version sort overview:: 503* Version sort implementation:: 504* Differences from Debian version sort:: 505* Advanced version sort topics:: 506 507Opening the software toolbox 508 509* Toolbox introduction:: Toolbox introduction 510* I/O redirection:: I/O redirection 511* The who command:: The @command{who} command 512* The cut command:: The @command{cut} command 513* The sort command:: The @command{sort} command 514* The uniq command:: The @command{uniq} command 515* Putting the tools together:: Putting the tools together 516 517Copying This Manual 518 519* GNU Free Documentation License:: Copying and sharing this manual 520 521@end detailmenu 522@end menu 523 524 525@node Introduction 526@chapter Introduction 527 528This manual is a work in progress: many sections make no attempt to explain 529basic concepts in a way suitable for novices. Thus, if you are interested, 530please get involved in improving this manual. The entire GNU community 531will benefit. 532 533@cindex POSIX 534The GNU utilities documented here are mostly compatible with the 535POSIX standard. 536@cindex bugs, reporting 537 538Please report bugs to @email{bug-coreutils@@gnu.org}. 539Include the version number, machine architecture, input files, and 540any other information needed to reproduce the bug: your input, what you 541expected, what you got, and why it is wrong. 542 543If you have a problem with @command{sort} or @command{date}, try using the 544@option{--debug} option, as it can often help find and fix problems without 545having to wait for an answer to a bug report. If the debug output 546does not suffice to fix the problem on your own, please compress and 547attach it to the rest of your bug report. 548 549Although diffs are welcome, 550please include a description of the problem as well, since this is 551sometimes difficult to infer. @xref{Bugs, , , gcc, Using and Porting GNU CC}. 552 553@cindex Berry, K. 554@cindex Paterson, R. 555@cindex Stallman, R. 556@cindex Pinard, F. 557@cindex MacKenzie, D. 558@cindex Meyering, J. 559@cindex Youmans, B. 560This manual was originally derived from the Unix man pages in the 561distributions, which were written by David MacKenzie and updated by Jim 562Meyering. What you are reading now is the authoritative documentation 563for these utilities; the man pages are no longer being maintained. The 564original @command{fmt} man page was written by Ross Paterson. Fran@,{c}ois 565Pinard did the initial conversion to Texinfo format. Karl Berry did the 566indexing, some reorganization, and editing of the results. Brian 567Youmans of the Free Software Foundation office staff combined the 568manuals for textutils, fileutils, and sh-utils to produce the present 569omnibus manual. Richard Stallman contributed his usual invaluable 570insights to the overall process. 571 572@node Common options 573@chapter Common options 574 575@macro optBackup 576@item -b 577@itemx --backup[=@var{method}] 578@opindex -b 579@opindex --backup 580@vindex VERSION_CONTROL 581@cindex backups, making 582@xref{Backup options}. 583Make a backup of each file that would otherwise be overwritten or removed. 584@end macro 585 586@macro optBackupSuffix 587@item -S @var{suffix} 588@itemx --suffix=@var{suffix} 589@opindex -S 590@opindex --suffix 591Append @var{suffix} to each backup file made with @option{-b}. 592@xref{Backup options}. 593@end macro 594 595@macro optTargetDirectory 596@item -t @var{directory} 597@itemx --target-directory=@var{directory} 598@opindex -t 599@opindex --target-directory 600@cindex target directory 601@cindex destination directory 602Specify the destination @var{directory}. 603@xref{Target directory}. 604@end macro 605 606@macro optNoTargetDirectory 607@item -T 608@itemx --no-target-directory 609@opindex -T 610@opindex --no-target-directory 611@cindex target directory 612@cindex destination directory 613Do not treat the last operand specially when it is a directory or a 614symbolic link to a directory. @xref{Target directory}. 615@end macro 616 617@macro outputNUL 618@cindex output NUL-byte-terminated lines 619Output a zero byte (ASCII NUL) at the end of each line, 620rather than a newline. This option enables other programs to parse the 621output even when that output would contain data with embedded newlines. 622@end macro 623 624@macro optNull 625@item -0 626@itemx --null 627@opindex -0 628@opindex --null 629@outputNUL 630@end macro 631 632@macro optZero 633@item -z 634@itemx --zero 635@opindex -z 636@opindex --zero 637@outputNUL 638@end macro 639 640@macro optZeroTerminated 641@item -z 642@itemx --zero-terminated 643@opindex -z 644@opindex --zero-terminated 645@cindex process zero-terminated items 646Delimit items with a zero byte rather than a newline (ASCII LF). 647I.e., treat input as items separated by ASCII NUL 648and terminate output items with ASCII NUL. 649This option can be useful in conjunction with @samp{perl -0} or 650@samp{find -print0} and @samp{xargs -0} which do the same in order to 651reliably handle arbitrary file names (even those containing blanks 652or other special characters). 653@end macro 654 655@macro optSi 656@item --si 657@opindex --si 658@cindex SI output 659Append an SI-style abbreviation to each size, such as @samp{M} for 660megabytes. Powers of 1000 are used, not 1024; @samp{M} stands for 6611,000,000 bytes. This option is equivalent to 662@option{--block-size=si}. Use the @option{-h} or 663@option{--human-readable} option if 664you prefer powers of 1024. 665@end macro 666 667@macro optHumanReadable 668@item -h 669@itemx --human-readable 670@opindex -h 671@opindex --human-readable 672@cindex human-readable output 673Append a size letter to each size, such as @samp{M} for mebibytes. 674Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes. 675This option is equivalent to @option{--block-size=human-readable}. 676Use the @option{--si} option if you prefer powers of 1000. 677@end macro 678 679@macro optStripTrailingSlashes 680@item --strip-trailing-slashes 681@opindex --strip-trailing-slashes 682@cindex stripping trailing slashes 683Remove any trailing slashes from each @var{source} argument. 684@xref{Trailing slashes}. 685@end macro 686 687@macro mayConflictWithShellBuiltIn{cmd} 688@cindex conflicts with shell built-ins 689@cindex built-in shell commands, conflicts with 690Due to shell aliases and built-in @command{\cmd\} functions, using an 691unadorned @command{\cmd\} interactively or in a script may get you 692different functionality than that described here. Invoke it via 693@command{env} (i.e., @code{env \cmd\ @dots{}}) to avoid interference 694from the shell. 695 696@end macro 697 698@macro multiplierSuffixes{varName} 699@var{\varName\} may be, or may be an integer optionally followed by, 700one of the following multiplicative suffixes: 701@example 702@samp{b} => 512 ("blocks") 703@samp{KB} => 1000 (KiloBytes) 704@samp{K} => 1024 (KibiBytes) 705@samp{MB} => 1000*1000 (MegaBytes) 706@samp{M} => 1024*1024 (MebiBytes) 707@samp{GB} => 1000*1000*1000 (GigaBytes) 708@samp{G} => 1024*1024*1024 (GibiBytes) 709@end example 710and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y}, 711@samp{R}, and @samp{Q}. 712Binary prefixes can be used, too: @samp{KiB}=@samp{K}, @samp{MiB}=@samp{M}, 713and so on. 714@end macro 715 716@c FIXME: same as above, but no ``blocks'' line. 717@macro multiplierSuffixesNoBlocks{varName} 718@var{\varName\} may be, or may be an integer optionally followed by, 719one of the following multiplicative suffixes: 720@example 721@samp{KB} => 1000 (KiloBytes) 722@samp{K} => 1024 (KibiBytes) 723@samp{MB} => 1000*1000 (MegaBytes) 724@samp{M} => 1024*1024 (MebiBytes) 725@samp{GB} => 1000*1000*1000 (GigaBytes) 726@samp{G} => 1024*1024*1024 (GibiBytes) 727@end example 728and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y}, 729@samp{R}, and @samp{Q}. 730Binary prefixes can be used, too: @samp{KiB}=@samp{K}, @samp{MiB}=@samp{M}, 731and so on. 732@end macro 733 734@cindex common options 735 736Certain options are available in all of these programs. Rather than 737writing identical descriptions for each of the programs, they are 738described here. (In fact, every GNU program accepts (or should accept) 739these options.) 740 741@vindex POSIXLY_CORRECT 742Normally options and operands can appear in any order, and programs act 743as if all the options appear before any operands. For example, 744@samp{sort -r passwd -t :} acts like @samp{sort -r -t : passwd}, since 745@samp{:} is an option-argument of @option{-t}. However, if the 746@env{POSIXLY_CORRECT} environment variable is set, options must appear 747before operands, unless otherwise specified for a particular command. 748 749A few programs can usefully have trailing operands with leading 750@samp{-}. With such a program, options must precede operands even if 751@env{POSIXLY_CORRECT} is not set, and this fact is noted in the 752program description. For example, the @command{env} command's options 753must appear before its operands, since in some cases the operands 754specify a command that itself contains options. 755 756Most programs that accept long options recognize unambiguous 757abbreviations of those options. For example, @samp{rmdir 758--ignore-fail-on-non-empty} can be invoked as @samp{rmdir 759--ignore-fail} or even @samp{rmdir --i}. Ambiguous options, such as 760@samp{ls --h}, are identified as such. 761 762Some of these programs recognize the @option{--help} and @option{--version} 763options only when one of them is the sole command line argument. For 764these programs, abbreviations of the long options are not always recognized. 765 766@table @samp 767 768@item --help 769@opindex --help 770@cindex help, online 771Print a usage message listing all available options, then exit successfully. 772 773@item --version 774@opindex --version 775@cindex version number, finding 776Print the version number, then exit successfully. 777 778@item -- 779@opindex -- 780@cindex option delimiter 781Delimit the option list. Later arguments, if any, are treated as 782operands even if they begin with @samp{-}. For example, @samp{sort -- 783-r} reads from the file named @file{-r}. 784 785@end table 786 787@cindex standard input 788@cindex standard output 789A single @samp{-} operand is not really an option, though it looks like one. It 790stands for a file operand, and some tools treat it as standard input, or as 791standard output if that is clear from the context. For example, @samp{sort -} 792reads from standard input, and is equivalent to plain @samp{sort}. Unless 793otherwise specified, a @samp{-} can appear as any operand that requires a file 794name. 795 796@menu 797Items shared between some programs: 798 799* Backup options:: @option{-b} @option{-S}. 800* Block size:: BLOCK_SIZE and @option{--block-size}. 801* Signal specifications:: Specifying signals with @option{--signal}. 802* Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax 803* Random sources:: @option{--random-source}. 804* Target directory:: Specifying a target directory. 805* Trailing slashes:: @option{--strip-trailing-slashes}. 806* Traversing symlinks:: @option{-H}, @option{-L}, or @option{-P}. 807* Treating / specially:: @option{--preserve-root} and the converse. 808* Special built-in utilities:: @command{break}, @command{:}, @dots{} 809 810Items applicable to all programs: 811 812* Exit status:: Indicating program success or failure. 813* Floating point:: Floating point number representation. 814* Standards conformance:: Conformance to the POSIX standard. 815* Multi-call invocation:: Multi-call program invocation. 816@end menu 817 818 819@node Backup options 820@section Backup options 821 822@cindex backup options 823 824Some GNU programs (at least @command{cp}, @command{install}, 825@command{ln}, and @command{mv}) optionally make backups of files 826before writing new versions. 827These options control the details of these backups. The options are also 828briefly mentioned in the descriptions of the particular programs. 829 830@table @samp 831 832@item -b 833@itemx --backup[=@var{method}] 834@opindex -b 835@opindex --backup 836@vindex VERSION_CONTROL 837@cindex backups, making 838Make a backup of each file that would otherwise be overwritten or removed. 839Without this option, the original versions are destroyed. 840Use @var{method} to determine the type of backups to make. 841When this option is used but @var{method} is not specified, 842then the value of the @env{VERSION_CONTROL} 843environment variable is used. And if @env{VERSION_CONTROL} is not set, 844the default backup type is @samp{existing}. 845 846Note that the short form of this option, @option{-b} does not accept any 847argument. Using @option{-b} is equivalent to using @option{--backup=existing}. 848 849@vindex version-control @r{Emacs variable} 850This option corresponds to the Emacs variable @samp{version-control}; 851the values for @var{method} are the same as those used in Emacs. 852This option also accepts more descriptive names. 853The valid @var{method}s are (unique abbreviations are accepted): 854 855@table @samp 856@item none 857@itemx off 858@opindex none @r{backup method} 859Never make backups. 860 861@item numbered 862@itemx t 863@opindex numbered @r{backup method} 864Always make numbered backups. 865 866@item existing 867@itemx nil 868@opindex existing @r{backup method} 869Make numbered backups of files that already have them, simple backups 870of the others. 871 872@item simple 873@itemx never 874@opindex simple @r{backup method} 875Always make simple backups. Please note @samp{never} is not to be 876confused with @samp{none}. 877 878@end table 879 880@item -S @var{suffix} 881@itemx --suffix=@var{suffix} 882@opindex -S 883@opindex --suffix 884@cindex backup suffix 885@vindex SIMPLE_BACKUP_SUFFIX 886Append @var{suffix} to each backup file made with @option{-b}. If this 887option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX} 888environment variable is used. And if @env{SIMPLE_BACKUP_SUFFIX} is not 889set, the default is @samp{~}, just as in Emacs. 890 891@end table 892 893@node Block size 894@section Block size 895 896@cindex block size 897 898Some GNU programs (at least @command{df}, @command{du}, and 899@command{ls}) display sizes in ``blocks''. You can adjust the block size 900and method of display to make sizes easier to read. The block size 901used for display is independent of any file system block size. 902Fractional block counts are rounded up to the nearest integer. 903 904@opindex --block-size=@var{size} 905@vindex BLOCKSIZE 906@vindex BLOCK_SIZE 907@vindex DF_BLOCK_SIZE 908@vindex DU_BLOCK_SIZE 909@vindex LS_BLOCK_SIZE 910@vindex POSIXLY_CORRECT@r{, and block size} 911 912The default block size is chosen by examining the following environment 913variables in turn; the first one that is set determines the block size. 914 915@table @code 916 917@item DF_BLOCK_SIZE 918This specifies the default block size for the @command{df} command. 919Similarly, @env{DU_BLOCK_SIZE} specifies the default for @command{du} and 920@env{LS_BLOCK_SIZE} for @command{ls}. 921 922@item BLOCK_SIZE 923This specifies the default block size for all three commands, if the 924above command-specific environment variables are not set. 925 926@item BLOCKSIZE 927This specifies the default block size for all values that are normally 928printed as blocks, if neither @env{BLOCK_SIZE} nor the above 929command-specific environment variables are set. Unlike the other 930environment variables, @env{BLOCKSIZE} does not affect values that are 931normally printed as byte counts, e.g., the file sizes contained in 932@code{ls -l} output. 933 934@item POSIXLY_CORRECT 935If neither @env{@var{command}_BLOCK_SIZE}, nor @env{BLOCK_SIZE}, nor 936@env{BLOCKSIZE} is set, but this variable is set, the block size 937defaults to 512. 938 939@end table 940 941If none of the above environment variables are set, the block size 942currently defaults to 1024 bytes in most contexts, but this number may 943change in the future. For @command{ls} file sizes, the block size 944defaults to 1 byte. 945 946@cindex human-readable output 947@cindex SI output 948 949A block size specification can be a positive integer specifying the number 950of bytes per block, or it can be @code{human-readable} or @code{si} to 951select a human-readable format. Integers may be followed by suffixes 952that are upward compatible with the 953@uref{http://www.bipm.org/en/publications/si-brochure/chapter3.html, 954SI prefixes} 955for decimal multiples and with the 956@uref{https://physics.nist.gov/cuu/Units/binary.html, ISO/IEC 80000-13 957(formerly IEC 60027-2) prefixes} for binary multiples. 958 959With human-readable formats, output sizes are followed by a size letter 960such as @samp{M} for megabytes. @code{BLOCK_SIZE=human-readable} uses 961powers of 1024; @samp{M} stands for 1,048,576 bytes. 962@code{BLOCK_SIZE=si} is similar, but uses powers of 1000 and appends 963@samp{B}; @samp{MB} stands for 1,000,000 bytes. 964 965@vindex LC_NUMERIC 966A block size specification preceded by @samp{'} causes output sizes to 967be displayed with thousands separators. The @env{LC_NUMERIC} locale 968specifies the thousands separator and grouping. For example, in an 969American English locale, @samp{--block-size="'1kB"} would cause a size 970of 1234000 bytes to be displayed as @samp{1,234}. In the default C 971locale, there is no thousands separator so a leading @samp{'} has no 972effect. 973 974An integer block size can be followed by a suffix to specify a 975multiple of that size. A bare size letter, 976or one followed by @samp{iB}, specifies 977a multiple using powers of 1024. A size letter followed by @samp{B} 978specifies powers of 1000 instead. For example, @samp{1M} and 979@samp{1MiB} are equivalent to @samp{1048576}, whereas @samp{1MB} is 980equivalent to @samp{1000000}. 981 982A plain suffix without a preceding integer acts as if @samp{1} were 983prepended, except that it causes a size indication to be appended to 984the output. For example, @samp{--block-size="kB"} displays 3000 as 985@samp{3kB}. 986 987The following suffixes are defined. Large sizes like @code{1Q} 988may be rejected by your computer due to limitations of its arithmetic. 989 990@table @samp 991@item kB 992@cindex kilobyte, definition of 993kilobyte: @math{10^3 = 1000}. 994@item k 995@itemx K 996@itemx KiB 997@cindex kibibyte, definition of 998kibibyte: @math{2^{10} = 1024}. @samp{K} is special: the SI prefix is 999@samp{k} and the ISO/IEC 80000-13 prefix is @samp{Ki}, but tradition and 1000POSIX use @samp{k} to mean @samp{KiB}. 1001@item MB 1002@cindex megabyte, definition of 1003megabyte: @math{10^6 = 1,000,000}. 1004@item M 1005@itemx MiB 1006@cindex mebibyte, definition of 1007mebibyte: @math{2^{20} = 1,048,576}. 1008@item GB 1009@cindex gigabyte, definition of 1010gigabyte: @math{10^9 = 1,000,000,000}. 1011@item G 1012@itemx GiB 1013@cindex gibibyte, definition of 1014gibibyte: @math{2^{30} = 1,073,741,824}. 1015@item TB 1016@cindex terabyte, definition of 1017terabyte: @math{10^{12} = 1,000,000,000,000}. 1018@item T 1019@itemx TiB 1020@cindex tebibyte, definition of 1021tebibyte: @math{2^{40} = 1,099,511,627,776}. 1022@item PB 1023@cindex petabyte, definition of 1024petabyte: @math{10^{15} = 1,000,000,000,000,000}. 1025@item P 1026@itemx PiB 1027@cindex pebibyte, definition of 1028pebibyte: @math{2^{50} = 1,125,899,906,842,624}. 1029@item EB 1030@cindex exabyte, definition of 1031exabyte: @math{10^{18} = 1,000,000,000,000,000,000}. 1032@item E 1033@itemx EiB 1034@cindex exbibyte, definition of 1035exbibyte: @math{2^{60} = 1,152,921,504,606,846,976}. 1036@item ZB 1037@cindex zettabyte, definition of 1038zettabyte: @math{10^{21} = 1,000,000,000,000,000,000,000} 1039@item Z 1040@itemx ZiB 1041zebibyte: @math{2^{70} = 1,180,591,620,717,411,303,424}. 1042@item YB 1043@cindex yottabyte, definition of 1044yottabyte: @math{10^{24} = 1,000,000,000,000,000,000,000,000}. 1045@item Y 1046@itemx YiB 1047yobibyte: @math{2^{80} = 1,208,925,819,614,629,174,706,176}. 1048@item RB 1049@cindex ronnabyte, definition of 1050ronnabyte: @math{10^{27} = 1,000,000,000,000,000,000,000,000,000}. 1051@item R 1052@itemx RiB 1053robibyte: @math{2^{90} = 1,237,940,039,285,380,274,899,124,224}. 1054@item QB 1055@cindex quettabyte, definition of 1056quettabyte: @math{10^{30} = 1,000,000,000,000,000,000,000,000,000,000}. 1057@item Q 1058@itemx QiB 1059quebibyte: @math{2^{100} = 1,267,650,600,228,229,401,496,703,205,376}. 1060@end table 1061 1062@opindex -k 1063@opindex -h 1064@opindex --block-size 1065@opindex --human-readable 1066@opindex --si 1067 1068Block size defaults can be overridden by an explicit 1069@option{--block-size=@var{size}} option. The @option{-k} 1070option is equivalent to @option{--block-size=1K}, which 1071is the default unless the @env{POSIXLY_CORRECT} environment variable is 1072set. The @option{-h} or @option{--human-readable} option is equivalent to 1073@option{--block-size=human-readable}. The @option{--si} option is 1074equivalent to @option{--block-size=si}. Note for @command{ls} 1075the @option{-k} option does not control the display of the 1076apparent file sizes, whereas the @option{--block-size} option does. 1077 1078@node Signal specifications 1079@section Signal specifications 1080@cindex signals, specifying 1081 1082A @var{signal} may be a signal name like @samp{HUP}, or a signal 1083number like @samp{1}, or an exit status of a process terminated by the 1084signal. A signal name can be given in canonical form or prefixed by 1085@samp{SIG}@. The case of the letters is ignored. The following signal names 1086and numbers are supported on all POSIX compliant systems: 1087 1088@table @samp 1089@item HUP 10901. Hangup. 1091@item INT 10922. Terminal interrupt. 1093@item QUIT 10943. Terminal quit. 1095@item ABRT 10966. Process abort. 1097@item KILL 10989. Kill (cannot be caught or ignored). 1099@item ALRM 110014. Alarm Clock. 1101@item TERM 110215. Termination. 1103@end table 1104 1105@noindent 1106Other supported signal names have system-dependent corresponding 1107numbers. All systems conforming to POSIX 1003.1-2001 also 1108support the following signals: 1109 1110@table @samp 1111@item BUS 1112Access to an undefined portion of a memory object. 1113@item CHLD 1114Child process terminated, stopped, or continued. 1115@item CONT 1116Continue executing, if stopped. 1117@item FPE 1118Erroneous arithmetic operation. 1119@item ILL 1120Illegal Instruction. 1121@item PIPE 1122Write on a pipe with no one to read it. 1123@item SEGV 1124Invalid memory reference. 1125@item STOP 1126Stop executing (cannot be caught or ignored). 1127@item TSTP 1128Terminal stop. 1129@item TTIN 1130Background process attempting read. 1131@item TTOU 1132Background process attempting write. 1133@item URG 1134High bandwidth data is available at a socket. 1135@item USR1 1136User-defined signal 1. 1137@item USR2 1138User-defined signal 2. 1139@end table 1140 1141@noindent 1142POSIX 1003.1-2001 systems that support the XSI extension 1143also support the following signals: 1144 1145@table @samp 1146@item POLL 1147Pollable event. 1148@item PROF 1149Profiling timer expired. 1150@item SYS 1151Bad system call. 1152@item TRAP 1153Trace/breakpoint trap. 1154@item VTALRM 1155Virtual timer expired. 1156@item XCPU 1157CPU time limit exceeded. 1158@item XFSZ 1159File size limit exceeded. 1160@end table 1161 1162@noindent 1163POSIX 1003.1-2001 systems that support the XRT extension 1164also support at least eight real-time signals called @samp{RTMIN}, 1165@samp{RTMIN+1}, @dots{}, @samp{RTMAX-1}, @samp{RTMAX}. 1166 1167@node Disambiguating names and IDs 1168@section chown, chgrp, chroot, id: Disambiguating user names and IDs 1169@cindex user names, disambiguating 1170@cindex user IDs, disambiguating 1171@cindex group names, disambiguating 1172@cindex group IDs, disambiguating 1173@cindex disambiguating group names and IDs 1174 1175Since the @var{user} and @var{group} arguments to these commands 1176may be specified as names or numeric IDs, there is an 1177apparent ambiguity. 1178What if a user or group @emph{name} is a string of digits? 1179Should the command interpret it as a user name or as an ID@? 1180(Using a number as a user name is common in some environments.) 1181POSIX requires that these commands 1182first attempt to resolve the specified string as a name, and 1183only once that fails, then try to interpret it as an ID@. 1184This is troublesome when you want to specify a numeric ID, say 42, 1185and it must work even in a pathological situation where 1186@samp{42} is a user name that maps to some other user ID, say 1000. 1187Simply invoking @code{chown 42 F}, will set @file{F}s owner ID to 11881000 -- not what you intended. 1189 1190GNU @command{chown}, @command{chgrp}, @command{chroot}, and @command{id} 1191provide a way to work around this, that at the same time may result in a 1192significant performance improvement by eliminating a database look-up. 1193Simply precede each numeric user ID and/or group ID with a @samp{+}, 1194in order to force its interpretation as an integer: 1195 1196@example 1197chown +42 F 1198chgrp +$numeric_group_id another-file 1199chown +0:+0 / 1200@end example 1201 1202The name look-up process is skipped for each @samp{+}-prefixed string, 1203because a string containing @samp{+} is never a valid user or group name. 1204This syntax is accepted on most common Unix systems, but not on Solaris 10. 1205 1206@node Random sources 1207@section Sources of random data 1208 1209@cindex random sources 1210 1211The @command{shuf}, @command{shred}, and @command{sort} commands 1212sometimes need random data to do their work. For example, @samp{sort 1213-R} must choose a hash function at random, and it needs random data to 1214make this selection. 1215 1216By default these commands use an internal pseudo-random generator 1217initialized by a small amount of entropy, but can be directed to use 1218an external source with the @option{--random-source=@var{file}} option. 1219An error is reported if @var{file} does not contain enough bytes. 1220 1221For example, the device file @file{/dev/urandom} could be used as the 1222source of random data. Typically, this device gathers environmental 1223noise from device drivers and other sources into an entropy pool, and 1224uses the pool to generate random bits. If the pool is short of data, 1225the device reuses the internal pool to produce more bits, using a 1226cryptographically secure pseudo-random number generator. But be aware 1227that this device is not designed for bulk random data generation 1228and is relatively slow. 1229 1230@file{/dev/urandom} suffices for most practical uses, but applications 1231requiring high-value or long-term protection of private data may 1232require an alternate data source like @file{/dev/random} or 1233@file{/dev/arandom}. The set of available sources depends on your 1234operating system. 1235 1236To reproduce the results of an earlier invocation of a command, you 1237can save some random data into a file and then use that file as the 1238random source in earlier and later invocations of the command. 1239@cindex random seed 1240Rather than depending on a file, one can generate a reproducible 1241arbitrary amount of pseudo-random data given a seed value, using 1242for example: 1243 1244@example 1245get_seeded_random() 1246@{ 1247 seed="$1" 1248 openssl enc -aes-256-ctr -pass pass:"$seed" -nosalt \ 1249 </dev/zero 2>/dev/null 1250@} 1251 1252shuf -i1-100 --random-source=<(get_seeded_random 42) 1253@end example 1254 1255@node Target directory 1256@section Target directory 1257 1258@cindex target directory 1259 1260The @command{cp}, @command{install}, @command{ln}, and @command{mv} 1261commands normally treat the last operand specially when it is a 1262directory or a symbolic link to a directory. For example, @samp{cp 1263source dest} is equivalent to @samp{cp source dest/source} if 1264@file{dest} is a directory. Sometimes this behavior is not exactly 1265what is wanted, so these commands support the following options to 1266allow more fine-grained control: 1267 1268@table @samp 1269 1270@item -T 1271@itemx --no-target-directory 1272@opindex --no-target-directory 1273@cindex target directory 1274@cindex destination directory 1275Do not treat the last operand specially when it is a directory or a 1276symbolic link to a directory. This can help avoid race conditions in 1277programs that operate in a shared area. For example, when the command 1278@samp{mv /tmp/source /tmp/dest} succeeds, there is no guarantee that 1279@file{/tmp/source} was renamed to @file{/tmp/dest}: it could have been 1280renamed to @file{/tmp/dest/source} instead, if some other process 1281created @file{/tmp/dest} as a directory. However, if @file{mv 1282-T /tmp/source /tmp/dest} succeeds, there is no 1283question that @file{/tmp/source} was renamed to @file{/tmp/dest}. 1284 1285In the opposite situation, where you want the last operand to be 1286treated as a directory and want a diagnostic otherwise, you can use 1287the @option{--target-directory} (@option{-t}) option. 1288 1289@item -t @var{directory} 1290@itemx --target-directory=@var{directory} 1291@opindex --target-directory 1292@cindex target directory 1293@cindex destination directory 1294Use @var{directory} as the directory component of each destination 1295file name. 1296 1297The interface for most programs is that after processing options and a 1298finite (possibly zero) number of fixed-position arguments, the remaining 1299argument list is either expected to be empty, or is a list of items 1300(usually files) that will all be handled identically. The @command{xargs} 1301program is designed to work well with this convention. 1302 1303The commands in the @command{mv}-family are unusual in that they take 1304a variable number of arguments with a special case at the @emph{end} 1305(namely, the target directory). This makes it nontrivial to perform some 1306operations, e.g., ``move all files from here to ../d/'', because 1307@code{mv * ../d/} might exhaust the argument space, and @code{ls | xargs ...} 1308doesn't have a clean way to specify an extra final argument for each 1309invocation of the subject command. (It can be done by going through a 1310shell command, but that requires more human labor and brain power than 1311it should.) 1312 1313The @option{--target-directory} (@option{-t}) option allows the @command{cp}, 1314@command{install}, @command{ln}, and @command{mv} programs to be used 1315conveniently with @command{xargs}. For example, you can move the files 1316from the current directory to a sibling directory, @code{d} like this: 1317 1318@example 1319ls | xargs mv -t ../d -- 1320@end example 1321 1322However, this doesn't move files whose names begin with @samp{.}. 1323If you use the GNU @command{find} program, you can move those 1324files too, with this command: 1325 1326@example 1327find . -mindepth 1 -maxdepth 1 \ 1328 | xargs mv -t ../d 1329@end example 1330 1331But both of the above approaches fail if there are no files in the 1332current directory, or if any file has a name containing a blank or 1333some other special characters. 1334The following example removes those limitations and requires both 1335GNU @command{find} and GNU @command{xargs}: 1336 1337@example 1338find . -mindepth 1 -maxdepth 1 -print0 \ 1339 | xargs --null --no-run-if-empty \ 1340 mv -t ../d 1341@end example 1342 1343@end table 1344 1345@noindent 1346The @option{--target-directory} (@option{-t}) and 1347@option{--no-target-directory} (@option{-T}) 1348options cannot be combined. 1349 1350@node Trailing slashes 1351@section Trailing slashes 1352 1353@cindex trailing slashes 1354 1355Some GNU programs (at least @command{cp} and @command{mv}) allow you to 1356remove any trailing slashes from each @var{source} argument before 1357operating on it. The @option{--strip-trailing-slashes} option enables 1358this behavior. 1359 1360This is useful when a @var{source} argument may have a trailing slash and 1361@c FIXME: mv's behavior in this case is system-dependent 1362specify a symbolic link to a directory. This scenario is in fact rather 1363common because some shells can automatically append a trailing slash when 1364performing file name completion on such symbolic links. Without this 1365option, @command{mv}, for example, (via the system's rename function) must 1366interpret a trailing slash as a request to dereference the symbolic link 1367and so must rename the indirectly referenced @emph{directory} and not 1368the symbolic link. Although it may seem surprising that such behavior 1369be the default, it is required by POSIX and is consistent with 1370other parts of that standard. 1371 1372@node Traversing symlinks 1373@section Traversing symlinks 1374 1375@cindex symbolic link to directory, controlling traversal of 1376 1377The following options modify how @command{chown} and @command{chgrp} 1378@c FIXME: note that 'du' has these options, too, but they have slightly 1379@c different meaning. 1380traverse a hierarchy when the @option{--recursive} (@option{-R}) 1381option is also specified. 1382If more than one of the following options is specified, only the final 1383one takes effect. 1384These options specify whether processing a symbolic link to a directory 1385entails operating on just the symbolic link or on all files in the 1386hierarchy rooted at that directory. 1387 1388These options are independent of @option{--dereference} and 1389@option{--no-dereference} (@option{-h}), which control whether to modify 1390a symlink or its referent. 1391 1392@table @samp 1393 1394@macro choptH 1395@item -H 1396@opindex -H 1397@cindex symbolic link to directory, traverse if on the command line 1398If @option{--recursive} (@option{-R}) is specified and 1399a command line argument is a symbolic link to a directory, traverse it. 1400@end macro 1401@choptH 1402 1403@macro choptL 1404@item -L 1405@opindex -L 1406@cindex symbolic link to directory, traverse each that is encountered 1407In a recursive traversal, traverse every symbolic link to a directory 1408that is encountered. 1409@end macro 1410 1411@c Append the following warning to -L where appropriate (e.g. chown). 1412@macro warnOptDerefWithRec 1413 1414Combining this dereferencing option with the @option{--recursive} option 1415may create a security risk: 1416During the traversal of the directory tree, an attacker may be able to 1417introduce a symlink to an arbitrary target; when the tool reaches that, 1418the operation will be performed on the target of that symlink, 1419possibly allowing the attacker to escalate privileges. 1420 1421@end macro 1422 1423@choptL 1424 1425@macro choptP 1426@item -P 1427@opindex -P 1428@cindex symbolic link to directory, never traverse 1429Do not traverse any symbolic links. 1430This is the default if none of @option{-H}, @option{-L}, 1431or @option{-P} is specified. 1432@end macro 1433@choptP 1434 1435@end table 1436 1437 1438@node Treating / specially 1439@section Treating @file{/} specially 1440 1441Certain commands can operate destructively on entire hierarchies. 1442For example, if a user with appropriate privileges mistakenly runs 1443@samp{rm -rf / tmp/junk}, that may remove 1444all files on the entire system. Since there are so few 1445legitimate uses for such a command, 1446GNU @command{rm} normally declines to operate on any directory 1447that resolves to @file{/}. If you really want to try to remove all 1448the files on your system, you can use the @option{--no-preserve-root} 1449option, but the default behavior, specified by the 1450@option{--preserve-root} option, is safer for most purposes. 1451 1452The commands @command{chgrp}, @command{chmod} and @command{chown} 1453can also operate destructively on entire hierarchies, so they too 1454support these options. Although, unlike @command{rm}, they don't 1455actually unlink files, these commands are arguably more dangerous 1456when operating recursively on @file{/}, since they often work much 1457more quickly, and hence damage more files before an alert user can 1458interrupt them. Tradition and POSIX require these commands 1459to operate recursively on @file{/}, so they default to 1460@option{--no-preserve-root}, but using the @option{--preserve-root} 1461option makes them safer for most purposes. For convenience you can 1462specify @option{--preserve-root} in an alias or in a shell function. 1463 1464Note that the @option{--preserve-root} option also ensures 1465that @command{chgrp} and @command{chown} do not modify @file{/} 1466even when dereferencing a symlink pointing to @file{/}. 1467 1468@node Special built-in utilities 1469@section Special built-in utilities 1470 1471Some programs like @command{nice} can invoke other programs; for 1472example, the command @samp{nice cat file} invokes the program 1473@command{cat} by executing the command @samp{cat file}. However, 1474@dfn{special built-in utilities} like @command{exit} cannot be invoked 1475this way. For example, the command @samp{nice exit} does not have a 1476well-defined behavior: it may generate an error message instead of 1477exiting. 1478 1479Here is a list of the special built-in utilities that are standardized 1480by POSIX 1003.1-2004. 1481 1482@quotation 1483@t{.@: : break continue eval exec exit export readonly 1484return set shift times trap unset} 1485@end quotation 1486 1487For example, because @samp{.}, @samp{:}, and @samp{exec} are special, 1488the commands @samp{nice . foo.sh}, @samp{nice :}, and @samp{nice exec 1489pwd} do not work as you might expect. 1490 1491Many shells extend this list. For example, Bash has several extra 1492special built-in utilities like @command{history}, and 1493@command{suspend}, and with Bash the command @samp{nice suspend} 1494generates an error message instead of suspending. 1495 1496 1497@node Exit status 1498@section Exit status 1499 1500@macro exitstatus 1501An exit status of zero indicates success, 1502and a nonzero value indicates failure. 1503@end macro 1504 1505Nearly every command invocation yields an integral @dfn{exit status} 1506that can be used to change how other commands work. 1507For the vast majority of commands, an exit status of zero indicates 1508success. Failure is indicated by a nonzero value -- typically 1509@samp{1}, though it may differ on unusual platforms as POSIX 1510requires only that it be nonzero. 1511 1512However, some of the programs documented here do produce 1513other exit status values and a few associate different 1514meanings with the values @samp{0} and @samp{1}. 1515Here are the exceptions: 1516@c You can generate the following list with: 1517@c grep initialize_exit_failure src/*.c | cut -f1 -d: | 1518@c sed -n 's|src/\(.*\)\.c|@command{\1},|p' | sort | fmt 1519@command{chroot}, @command{env}, @command{expr}, @command{ls}, 1520@command{nice}, @command{nohup}, @command{numfmt}, @command{printenv}, 1521@command{runcon}, @command{sort}, @command{stdbuf}, @command{test}, 1522@command{timeout}, @command{tty}. 1523 1524@node Floating point 1525@section Floating point numbers 1526@cindex floating point 1527@cindex IEEE floating point 1528 1529Commands that accept or produce floating point numbers employ the 1530floating point representation of the underlying system, and suffer 1531from rounding error, overflow, and similar floating-point issues. 1532Almost all modern systems use IEEE-754 floating point, and it is 1533typically portable to assume IEEE-754 behavior these days. IEEE-754 1534has positive and negative infinity, distinguishes positive from 1535negative zero, and uses special values called NaNs to represent 1536invalid computations such as dividing zero by itself. For more 1537information, please see David Goldberg's paper 1538@uref{https://@/docs.oracle.com/@/cd/@/E19957-01/@/806-3568/@/ncg_goldberg.html, 1539What Every Computer Scientist Should Know About Floating-Point Arithmetic}. 1540 1541Commands that accept floating point numbers as options, operands or 1542input use the standard C functions @code{strtod} and @code{strtold} to 1543convert from text to floating point numbers. These floating point 1544numbers therefore can use scientific notation like @code{1.0e-34} and 1545@code{-10e100}. Commands that parse floating point also understand 1546case-insensitive @code{inf}, @code{infinity}, and @code{NaN}, although 1547whether such values are useful depends on the command in question. 1548Modern C implementations also accept hexadecimal floating point 1549numbers such as @code{-0x.ep-3}, which stands for @minus{}14/16 times 1550@math{2^-3}, which equals @minus{}0.109375. @xref{Parsing of 1551Floats,,, libc, The GNU C Library Reference Manual}. 1552 1553@vindex LC_NUMERIC 1554Normally the @env{LC_NUMERIC} locale determines the decimal-point 1555character. However, some commands' descriptions specify that they 1556accept numbers in either the current or the C locale; for example, 1557they treat @samp{3.14} like @samp{3,14} if the current locale uses 1558comma as a decimal point. 1559 1560 1561@node Standards conformance 1562@section Standards conformance 1563 1564@vindex POSIXLY_CORRECT 1565In a few cases, the GNU utilities' default behavior is 1566incompatible with the POSIX standard. To suppress these 1567incompatibilities, define the @env{POSIXLY_CORRECT} environment 1568variable. Unless you are checking for POSIX conformance, you 1569probably do not need to define @env{POSIXLY_CORRECT}. 1570 1571Newer versions of POSIX are occasionally incompatible with older 1572versions. For example, older versions of POSIX required the 1573command @samp{sort +1} to sort based on the second and succeeding 1574fields in each input line, but in POSIX 1003.1-2001 1575the same command is required to sort the file named @file{+1}, and you 1576must instead use the command @samp{sort -k 2} to get the field-based 1577sort. To complicate things further, POSIX 1003.1-2008 allows an 1578implementation to have either the old or the new behavior. 1579 1580@vindex _POSIX2_VERSION 1581The GNU utilities normally conform to the version of POSIX 1582that is standard for your system. To cause them to conform to a 1583different version of POSIX, define the @env{_POSIX2_VERSION} 1584environment variable to a value of the form @var{yyyymm} specifying 1585the year and month the standard was adopted. Three values are currently 1586supported for @env{_POSIX2_VERSION}: @samp{199209} stands for 1587POSIX 1003.2-1992, @samp{200112} stands for POSIX 15881003.1-2001, and @samp{200809} stands for POSIX 1003.1-2008. 1589For example, if you have a POSIX 1003.1-2001 system but are running software 1590containing traditional usage like @samp{sort +1} or @samp{tail +10}, 1591you can work around the compatibility problems by setting 1592@samp{_POSIX2_VERSION=200809} in your environment. 1593 1594@c This node is named "Multi-call invocation", not the usual 1595@c "coreutils invocation", so that shell commands like 1596@c 'info coreutils "touch invocation"' work as expected. 1597@node Multi-call invocation 1598@section @command{coreutils}: Multi-call program 1599 1600@pindex multicall 1601@cindex combined 1602@cindex calling combined multi-call program 1603 1604The @command{coreutils} command invokes an individual utility, either 1605implicitly selected by the last component of the name used to invoke 1606@command{coreutils}, or explicitly with the 1607@option{--coreutils-prog} option. Synopsis: 1608 1609@example 1610coreutils @option{--coreutils-prog=PROGRAM} @dots{} 1611@end example 1612 1613The @command{coreutils} command is not installed by default, so 1614portable scripts should not rely on its existence. 1615 1616@node Output of entire files 1617@chapter Output of entire files 1618 1619@cindex output of entire files 1620@cindex entire files, output of 1621 1622These commands read and write entire files, possibly transforming them 1623in some way. 1624 1625@menu 1626* cat invocation:: Concatenate and write files. 1627* tac invocation:: Concatenate and write files in reverse. 1628* nl invocation:: Number lines and write files. 1629* od invocation:: Write files in octal or other formats. 1630* base32 invocation:: Transform data into printable data. 1631* base64 invocation:: Transform data into printable data. 1632* basenc invocation:: Transform data into printable data. 1633@end menu 1634 1635@node cat invocation 1636@section @command{cat}: Concatenate and write files 1637 1638@pindex cat 1639@cindex concatenate and write files 1640@cindex copying files 1641 1642@command{cat} copies each @var{file} (@samp{-} means standard input), or 1643standard input if none are given, to standard output. Synopsis: 1644 1645@example 1646cat [@var{option}] [@var{file}]@dots{} 1647@end example 1648 1649The program accepts the following options. Also see @ref{Common options}. 1650 1651@table @samp 1652 1653@item -A 1654@itemx --show-all 1655@opindex -A 1656@opindex --show-all 1657Equivalent to @option{-vET}. 1658 1659@item -b 1660@itemx --number-nonblank 1661@opindex -b 1662@opindex --number-nonblank 1663Number all nonempty output lines, starting with 1. 1664 1665@item -e 1666@opindex -e 1667Equivalent to @option{-vE}. 1668 1669@item -E 1670@itemx --show-ends 1671@opindex -E 1672@opindex --show-ends 1673Display a @samp{$} after the end of each line. 1674The @code{\r\n} combination is shown as @samp{^M$}. 1675 1676@item -n 1677@itemx --number 1678@opindex -n 1679@opindex --number 1680Number all output lines, starting with 1. This option is ignored 1681if @option{-b} is in effect. 1682 1683@item -s 1684@itemx --squeeze-blank 1685@opindex -s 1686@opindex --squeeze-blank 1687@cindex squeezing empty lines 1688@cindex squeezing blank lines 1689Suppress repeated adjacent blank lines; output just one empty line 1690instead of several. 1691 1692@item -t 1693@opindex -t 1694Equivalent to @option{-vT}. 1695 1696@item -T 1697@itemx --show-tabs 1698@opindex -T 1699@opindex --show-tabs 1700Display TAB characters as @samp{^I}. 1701 1702@item -u 1703@opindex -u 1704Ignored; for POSIX compatibility. 1705 1706@item -v 1707@itemx --show-nonprinting 1708@opindex -v 1709@opindex --show-nonprinting 1710Display control characters except for LFD and TAB using 1711@samp{^} notation and precede characters that have the high bit set with 1712@samp{M-}. 1713 1714@end table 1715 1716On systems like MS-DOS that distinguish between text and binary files, 1717@command{cat} normally reads and writes in binary mode. However, 1718@command{cat} reads in text mode if one of the options 1719@option{-bensAE} is used or if @command{cat} is reading from standard 1720input and standard input is a terminal. Similarly, @command{cat} 1721writes in text mode if one of the options @option{-bensAE} is used or 1722if standard output is a terminal. 1723 1724@exitstatus 1725 1726Examples: 1727 1728@example 1729# Output f's contents, then standard input, then g's contents. 1730cat f - g 1731 1732# Copy standard input to standard output. 1733cat 1734@end example 1735 1736 1737@node tac invocation 1738@section @command{tac}: Concatenate and write files in reverse 1739 1740@pindex tac 1741@cindex reversing files 1742 1743@command{tac} copies each @var{file} (@samp{-} means standard input), or 1744standard input if none are given, to standard output, reversing the 1745records (lines by default) in each separately. Synopsis: 1746 1747@example 1748tac [@var{option}]@dots{} [@var{file}]@dots{} 1749@end example 1750 1751@dfn{Records} are separated by instances of a string (newline by 1752default). By default, this separator string is attached to the end of 1753the record that it follows in the file. 1754 1755The program accepts the following options. Also see @ref{Common options}. 1756 1757@table @samp 1758 1759@item -b 1760@itemx --before 1761@opindex -b 1762@opindex --before 1763The separator is attached to the beginning of the record that it 1764precedes in the file. 1765 1766@item -r 1767@itemx --regex 1768@opindex -r 1769@opindex --regex 1770Treat the separator string as a regular expression. 1771 1772@item -s @var{separator} 1773@itemx --separator=@var{separator} 1774@opindex -s 1775@opindex --separator 1776Use @var{separator} as the record separator, instead of newline. 1777Note an empty @var{separator} is treated as a zero byte. 1778I.e., input and output items are delimited with ASCII NUL. 1779 1780@end table 1781 1782On systems like MS-DOS that distinguish between text and binary files, 1783@command{tac} reads and writes in binary mode. 1784 1785@exitstatus 1786 1787Example: 1788 1789@example 1790# Reverse a file character by character. 1791tac -r -s 'x\|[^x]' 1792@end example 1793 1794 1795@node nl invocation 1796@section @command{nl}: Number lines and write files 1797 1798@pindex nl 1799@cindex numbering lines 1800@cindex line numbering 1801 1802@command{nl} writes each @var{file} (@samp{-} means standard input), or 1803standard input if none are given, to standard output, with line numbers 1804added to some or all of the lines. Synopsis: 1805 1806@example 1807nl [@var{option}]@dots{} [@var{file}]@dots{} 1808@end example 1809 1810@cindex logical pages, numbering on 1811@command{nl} decomposes its input into (logical) page sections; 1812by default, the line number is reset to 1 at each logical page section. 1813@command{nl} treats all of the input files as a single document; 1814it does not reset line numbers or logical pages between files. 1815 1816@cindex headers, numbering 1817@cindex body, numbering 1818@cindex footers, numbering 1819A logical page consists of three sections: header, body, and footer. 1820Any of the sections can be empty. Each can be numbered in a different 1821style from the others. 1822 1823The beginnings of the sections of logical pages are indicated in the 1824input file by a line containing exactly one of these delimiter strings: 1825 1826@table @samp 1827@item \:\:\: 1828start of header; 1829@item \:\: 1830start of body; 1831@item \: 1832start of footer. 1833@end table 1834 1835The characters from which these strings are made can be changed from 1836@samp{\} and @samp{:} via options (see below), but the pattern 1837of each string cannot be changed. 1838 1839A section delimiter is replaced by an empty line on output. Any text 1840that comes before the first section delimiter string in the input file 1841is considered to be part of a body section, so @command{nl} treats a 1842file that contains no section delimiters as a single body section. 1843 1844The program accepts the following options. Also see @ref{Common options}. 1845 1846@table @samp 1847 1848@item -b @var{style} 1849@itemx --body-numbering=@var{style} 1850@opindex -b 1851@opindex --body-numbering 1852Select the numbering style for lines in the body section of each 1853logical page. When a line is not numbered, the current line number 1854is not incremented, but the line number separator character is still 1855prepended to the line. The styles are: 1856 1857@table @samp 1858@item a 1859number all lines, 1860@item t 1861number only nonempty lines (default for body), 1862@item n 1863do not number lines (default for header and footer), 1864@item p@var{bre} 1865number only lines that contain a match for the basic regular 1866expression @var{bre}. 1867@xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}. 1868@end table 1869 1870@item -d @var{cd} 1871@itemx --section-delimiter=@var{cd} 1872@opindex -d 1873@opindex --section-delimiter 1874@cindex section delimiters of pages 1875Set the section delimiter characters to @var{cd}; default is 1876@samp{\:}. If only @var{c} is given, the second remains @samp{:}. 1877As a GNU extension more than two characters can be specified, 1878and also if @var{cd} is empty (@option{-d ''}), then section 1879matching is disabled. 1880(Remember to protect @samp{\} or other metacharacters from shell 1881expansion with quotes or extra backslashes.) 1882 1883@item -f @var{style} 1884@itemx --footer-numbering=@var{style} 1885@opindex -f 1886@opindex --footer-numbering 1887Analogous to @option{--body-numbering}. 1888 1889@item -h @var{style} 1890@itemx --header-numbering=@var{style} 1891@opindex -h 1892@opindex --header-numbering 1893Analogous to @option{--body-numbering}. 1894 1895@item -i @var{number} 1896@itemx --line-increment=@var{number} 1897@opindex -i 1898@opindex --line-increment 1899Increment line numbers by @var{number} (default 1). 1900@var{number} can be negative to decrement. 1901 1902@item -l @var{number} 1903@itemx --join-blank-lines=@var{number} 1904@opindex -l 1905@opindex --join-blank-lines 1906@cindex empty lines, numbering 1907@cindex blank lines, numbering 1908Consider @var{number} (default 1) consecutive empty lines to be one 1909logical line for numbering, and only number the last one. Where fewer 1910than @var{number} consecutive empty lines occur, do not number them. 1911An empty line is one that contains no characters, not even spaces 1912or tabs. 1913 1914@item -n @var{format} 1915@itemx --number-format=@var{format} 1916@opindex -n 1917@opindex --number-format 1918Select the line numbering format (default is @code{rn}): 1919 1920@table @samp 1921@item ln 1922@opindex ln @r{format for @command{nl}} 1923left justified, no leading zeros; 1924@item rn 1925@opindex rn @r{format for @command{nl}} 1926right justified, no leading zeros; 1927@item rz 1928@opindex rz @r{format for @command{nl}} 1929right justified, leading zeros. 1930@end table 1931 1932@item -p 1933@itemx --no-renumber 1934@opindex -p 1935@opindex --no-renumber 1936Do not reset the line number at the start of a logical page. 1937 1938@item -s @var{string} 1939@itemx --number-separator=@var{string} 1940@opindex -s 1941@opindex --number-separator 1942Separate the line number from the text line in the output with 1943@var{string} (default is the TAB character). 1944 1945@item -v @var{number} 1946@itemx --starting-line-number=@var{number} 1947@opindex -v 1948@opindex --starting-line-number 1949Set the initial line number on each logical page to @var{number} (default 1). 1950The starting @var{number} can be negative. 1951 1952@item -w @var{number} 1953@itemx --number-width=@var{number} 1954@opindex -w 1955@opindex --number-width 1956Use @var{number} characters for line numbers (default 6). 1957 1958@end table 1959 1960@exitstatus 1961 1962 1963@node od invocation 1964@section @command{od}: Write files in octal or other formats 1965 1966@pindex od 1967@cindex octal dump of files 1968@cindex hex dump of files 1969@cindex ASCII dump of files 1970@cindex file contents, dumping unambiguously 1971 1972@command{od} writes an unambiguous representation of each @var{file} 1973(@samp{-} means standard input), or standard input if none are given. 1974Synopses: 1975 1976@example 1977od [@var{option}]@dots{} [@var{file}]@dots{} 1978od [-abcdfilosx]@dots{} [@var{file}] [[+]@var{offset}[.][b]] 1979od [@var{option}]@dots{} --traditional [@var{file}]@c 1980 [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]] 1981@end example 1982 1983Each line of output consists of the offset in the input, followed by 1984groups of data from the file. By default, @command{od} prints the offset in 1985octal, and each group of file data is a C @code{short int}'s worth of input 1986printed as a single octal number. 1987 1988If @var{offset} is given, it specifies how many input bytes to skip 1989before formatting and writing. By default, it is interpreted as an 1990octal number, but the optional trailing decimal point causes it to be 1991interpreted as decimal. If no decimal is specified and the offset 1992begins with @samp{0x} or @samp{0X} it is interpreted as a hexadecimal 1993number. If there is a trailing @samp{b}, the number of bytes skipped 1994will be @var{offset} multiplied by 512. 1995 1996If a command is of both the first and second forms, the second form is 1997assumed if the last operand begins with @samp{+} or (if there are two 1998operands) a digit. For example, in @samp{od foo 10} and @samp{od +10} 1999the @samp{10} is an offset, whereas in @samp{od 10} the @samp{10} is a 2000file name. 2001 2002The program accepts the following options. Also see @ref{Common options}. 2003 2004@table @samp 2005 2006@item -A @var{radix} 2007@itemx --address-radix=@var{radix} 2008@opindex -A 2009@opindex --address-radix 2010@cindex radix for file offsets 2011@cindex file offset radix 2012Select the base in which file offsets are printed. @var{radix} can 2013be one of the following: 2014 2015@table @samp 2016@item d 2017decimal; 2018@item o 2019octal; 2020@item x 2021hexadecimal; 2022@item n 2023none (do not print offsets). 2024@end table 2025 2026The default is octal. 2027 2028@item --endian=@var{order} 2029@opindex --endian 2030@cindex byte-swapping 2031@cindex endianness 2032Reorder input bytes, to handle inputs with differing byte orders, 2033or to provide consistent output independent of the endian convention 2034of the current system. Swapping is performed according to the 2035specified @option{--type} size and endian @var{order}, which can be 2036@samp{little} or @samp{big}. 2037 2038@item -j @var{bytes} 2039@itemx --skip-bytes=@var{bytes} 2040@opindex -j 2041@opindex --skip-bytes 2042Skip @var{bytes} input bytes before formatting and writing. If 2043@var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in 2044hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise, 2045in decimal. 2046@multiplierSuffixes{bytes} 2047 2048@item -N @var{bytes} 2049@itemx --read-bytes=@var{bytes} 2050@opindex -N 2051@opindex --read-bytes 2052Output at most @var{bytes} bytes of the input. Prefixes and suffixes on 2053@code{bytes} are interpreted as for the @option{-j} option. 2054 2055@item -S @var{bytes} 2056@itemx --strings[=@var{bytes}] 2057@opindex -S 2058@opindex --strings 2059@cindex string constants, outputting 2060Instead of the normal output, output only @dfn{string constants}: at 2061least @var{bytes} consecutive printable characters, 2062followed by a zero byte (ASCII NUL). 2063Prefixes and suffixes on @var{bytes} are interpreted as for the 2064@option{-j} option. 2065 2066If @var{bytes} is omitted with @option{--strings}, the default is 3. 2067 2068@item -t @var{type} 2069@itemx --format=@var{type} 2070@opindex -t 2071@opindex --format 2072Select the format in which to output the file data. @var{type} is a 2073string of one or more of the below type indicator characters. If you 2074include more than one type indicator character in a single @var{type} 2075string, or use this option more than once, @command{od} writes one copy 2076of each output line using each of the data types that you specified, 2077in the order that you specified. 2078 2079Adding a trailing ``z'' to any type specification appends a display 2080of the single byte character representation of the printable characters 2081to the output line generated by the type specification. 2082 2083@table @samp 2084@item a 2085named character, ignoring high-order bit 2086@item c 2087printable single byte character, C backslash escape 2088or a 3 digit octal sequence 2089@item d 2090signed decimal 2091@item f 2092floating point (@pxref{Floating point}) 2093@item o 2094octal 2095@item u 2096unsigned decimal 2097@item x 2098hexadecimal 2099@end table 2100 2101The type @code{a} outputs things like @samp{sp} for space, @samp{nl} for 2102newline, and @samp{nul} for a zero byte. Only the least significant 2103seven bits of each byte is used; the high-order bit is ignored. 2104Type @code{c} outputs 2105@samp{ }, @samp{\n}, and @code{\0}, respectively. 2106 2107@cindex type size 2108Except for types @samp{a} and @samp{c}, you can specify the number 2109of bytes to use in interpreting each number in the given data type 2110by following the type indicator character with a decimal integer. 2111Alternately, you can specify the size of one of the C compiler's 2112built-in data types by following the type indicator character with 2113one of the following characters. For integers (@samp{d}, @samp{o}, 2114@samp{u}, @samp{x}): 2115 2116@table @samp 2117@item C 2118char 2119@item S 2120short 2121@item I 2122int 2123@item L 2124long 2125@end table 2126 2127For floating point (@code{f}): 2128 2129@table @asis 2130@item F 2131float 2132@item D 2133double 2134@item L 2135long double 2136@end table 2137 2138@item -v 2139@itemx --output-duplicates 2140@opindex -v 2141@opindex --output-duplicates 2142Output consecutive lines that are identical. By default, when two or 2143more consecutive output lines would be identical, @command{od} outputs only 2144the first line, and puts just an asterisk on the following line to 2145indicate the elision. 2146 2147@item -w[@var{n}] 2148@itemx --width[=@var{n}] 2149@opindex -w 2150@opindex --width 2151Dump @code{n} input bytes per output line. This must be a multiple of 2152the least common multiple of the sizes associated with the specified 2153output types. 2154 2155If this option is not given at all, the default is 16. If @var{n} is 2156omitted, the default is 32. 2157 2158@end table 2159 2160The next several options are shorthands for format specifications. 2161GNU @command{od} accepts any combination of shorthands and format 2162specification options. These options accumulate. 2163 2164@table @samp 2165 2166@item -a 2167@opindex -a 2168Output as named characters. Equivalent to @samp{-t a}. 2169 2170@item -b 2171@opindex -b 2172Output as octal bytes. Equivalent to @samp{-t o1}. 2173 2174@item -c 2175@opindex -c 2176Output as printable single byte characters, C backslash escapes 2177or 3 digit octal sequences. Equivalent to @samp{-t c}. 2178 2179@item -d 2180@opindex -d 2181Output as unsigned decimal two-byte units. Equivalent to @samp{-t u2}. 2182 2183@item -f 2184@opindex -f 2185Output as floats. Equivalent to @samp{-t fF}. 2186 2187@item -i 2188@opindex -i 2189Output as decimal ints. Equivalent to @samp{-t dI}. 2190 2191@item -l 2192@opindex -l 2193Output as decimal long ints. Equivalent to @samp{-t dL}. 2194 2195@item -o 2196@opindex -o 2197Output as octal two-byte units. Equivalent to @option{-t o2}. 2198 2199@item -s 2200@opindex -s 2201Output as decimal two-byte units. Equivalent to @option{-t d2}. 2202 2203@item -x 2204@opindex -x 2205Output as hexadecimal two-byte units. Equivalent to @samp{-t x2}. 2206 2207@item --traditional 2208@opindex --traditional 2209Recognize the non-option label argument that traditional @command{od} 2210accepted. The following syntax: 2211 2212@example 2213od --traditional [@var{file}] [[+]@var{offset}[.][b] [[+]@var{label}[.][b]]] 2214@end example 2215 2216@noindent 2217can be used to specify at most one file and optional arguments 2218specifying an offset and a pseudo-start address, @var{label}. 2219The @var{label} argument is interpreted 2220just like @var{offset}, but it specifies an initial pseudo-address. The 2221pseudo-addresses are displayed in parentheses following any normal 2222address. 2223 2224@end table 2225 2226@exitstatus 2227 2228 2229@node base32 invocation 2230@section @command{base32}: Transform data into printable data 2231 2232@pindex base32 2233@cindex base32 encoding 2234 2235@command{base32} transforms data read from a file, or standard input, 2236into (or from) base32 encoded form. The base32 encoded form uses 2237printable ASCII characters to represent binary data. 2238The usage and options of this command are precisely the 2239same as for @command{base64}. @xref{base64 invocation}. 2240For more general encoding functionality see @ref{basenc invocation}. 2241 2242 2243@node base64 invocation 2244@section @command{base64}: Transform data into printable data 2245 2246@pindex base64 2247@cindex base64 encoding 2248 2249@command{base64} transforms data read from a file, or standard input, 2250into (or from) base64 encoded form. The base64 encoded form uses 2251printable ASCII characters to represent binary data. 2252Synopses: 2253 2254@example 2255base64 [@var{option}]@dots{} [@var{file}] 2256base64 --decode [@var{option}]@dots{} [@var{file}] 2257@end example 2258 2259The base64 encoding expands data to roughly 133% of the original. 2260The base32 encoding expands data to roughly 160% of the original. 2261The format conforms to 2262@uref{https://datatracker.ietf.org/doc/rfc4648/, RFC 4648}. 2263 2264For more general encoding functionality see @ref{basenc invocation}. 2265 2266The program accepts the following options. Also see @ref{Common options}. 2267 2268@table @samp 2269 2270@item -w @var{cols} 2271@itemx --wrap=@var{cols} 2272@opindex -w 2273@opindex --wrap 2274@cindex wrap data 2275@cindex column to wrap data after 2276During encoding, wrap lines after @var{cols} characters. This must be 2277a positive number. 2278 2279The default is to wrap after 76 characters. Use the value 0 to 2280disable line wrapping altogether. 2281 2282@item -d 2283@itemx --decode 2284@opindex -d 2285@opindex --decode 2286@cindex Decode base64 data 2287@cindex Base64 decoding 2288Change the mode of operation, from the default of encoding data, to 2289decoding data. Input is expected to be base64 encoded data, and the 2290output will be the original data. 2291 2292@item -i 2293@itemx --ignore-garbage 2294@opindex -i 2295@opindex --ignore-garbage 2296@cindex Ignore garbage in base64 stream 2297When decoding, newlines are always accepted. 2298During decoding, ignore unrecognized bytes, 2299to permit distorted data to be decoded. 2300 2301@end table 2302 2303@exitstatus 2304 2305@node basenc invocation 2306@section @command{basenc}: Transform data into printable data 2307 2308@pindex basenc 2309@cindex base32 encoding 2310 2311@command{basenc} transforms data read from a file, or standard input, 2312into (or from) various common encoding forms. The encoded form uses 2313printable ASCII characters to represent binary data. 2314 2315Synopses: 2316 2317@example 2318basenc @var{encoding} [@var{option}]@dots{} [@var{file}] 2319basenc @var{encoding} --decode [@var{option}]@dots{} [@var{file}] 2320@end example 2321 2322The @var{encoding} argument is required. If @var{file} is omitted, 2323@command{basenc} reads from standard input. 2324The @option{-w/--wrap},@option{-i/--ignore-garbage}, 2325@option{-d/--decode} options of this command are precisely the same as 2326for @command{base64}. @xref{base64 invocation}. 2327 2328 2329Supported @var{encoding}s are: 2330 2331@table @samp 2332 2333@item --base64 2334@opindex --base64 2335Encode into (or decode from with @option{-d/--decode}) base64 form. 2336The format conforms to 2337@uref{https://datatracker.ietf.org/doc/html/rfc4648#section-4, RFC 4648#4}. 2338Equivalent to the @command{base64} command. 2339 2340@item --base64url 2341@opindex --base64url 2342Encode into (or decode from with @option{-d/--decode}) file-and-url-safe 2343base64 form (using @samp{_} and @samp{-} instead of @samp{+} and @samp{/}). 2344The format conforms to 2345@uref{https://datatracker.ietf.org/doc/html/rfc4648#section-5, RFC 4648#5}. 2346 2347@item --base32 2348@opindex --base32 2349Encode into (or decode from with @option{-d/--decode}) base32 form. 2350The encoded data uses the @samp{ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=} characters. 2351The format conforms to 2352@uref{https://datatracker.ietf.org/doc/html/rfc4648#section-6, RFC 4648#6}. 2353Equivalent to the @command{base32} command. 2354 2355@item --base32hex 2356@opindex --base32hex 2357Encode into (or decode from with @option{-d/--decode}) Extended Hex Alphabet 2358base32 form. The encoded data uses the 2359@samp{0123456789ABCDEFGHIJKLMNOPQRSTUV=} characters. The format conforms to 2360@uref{https://datatracker.ietf.org/doc/html/rfc4648#section-7, RFC 4648#7}. 2361 2362@item --base16 2363@opindex --base16 2364Encode into (or decode from with @option{-d/--decode}) base16 (hexadecimal) 2365form. The encoded data uses the @samp{0123456789ABCDEF} characters. The format 2366conforms to 2367@uref{https://datatracker.ietf.org/doc/html/rfc4648#section-8, RFC 4648#8}. 2368 2369@item --base2lsbf 2370@opindex --base2lsbf 2371Encode into (or decode from with @option{-d/--decode}) binary string form 2372(@samp{0} and @samp{1}) with the @emph{least} significant bit of every byte 2373first. 2374 2375@item --base2msbf 2376@opindex --base2msbf 2377Encode into (or decode from with @option{-d/--decode}) binary string form 2378(@samp{0} and @samp{1}) with the @emph{most} significant bit of every byte 2379first. 2380 2381@item --z85 2382@opindex --z85 2383Encode into (or decode from with @option{-d/--decode}) Z85 form 2384(a modified Ascii85 form). The encoded data uses the 2385@samp{0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU@ 2386VWXYZ.-:+=^!/*?&<>()[]@{@}@@%$#}. 2387characters. The format conforms to 2388@uref{https://rfc.zeromq.org/spec:32/Z85/, ZeroMQ spec:32/Z85}. 2389 2390When encoding with @option{--z85}, input length must be a multiple of 4; 2391when decoding with @option{--z85}, input length must be a multiple of 5. 2392 2393@end table 2394 2395 2396 2397Encoding/decoding examples: 2398 2399@example 2400$ printf '\376\117\202' | basenc --base64 2401/k+C 2402 2403$ printf '\376\117\202' | basenc --base64url 2404_k-C 2405 2406$ printf '\376\117\202' | basenc --base32 24077ZHYE=== 2408 2409$ printf '\376\117\202' | basenc --base32hex 2410VP7O4=== 2411 2412$ printf '\376\117\202' | basenc --base16 2413FE4F82 2414 2415$ printf '\376\117\202' | basenc --base2lsbf 2416011111111111001001000001 2417 2418$ printf '\376\117\202' | basenc --base2msbf 2419111111100100111110000010 2420 2421$ printf '\376\117\202\000' | basenc --z85 2422@@.FaC 2423 2424$ printf 01010100 | basenc --base2msbf --decode 2425T 2426 2427$ printf 01010100 | basenc --base2lsbf --decode 2428* 2429@end example 2430 2431 2432 2433@node Formatting file contents 2434@chapter Formatting file contents 2435 2436@cindex formatting file contents 2437 2438These commands reformat the contents of files. 2439 2440@menu 2441* fmt invocation:: Reformat paragraph text. 2442* pr invocation:: Paginate or columnate files for printing. 2443* fold invocation:: Wrap input lines to fit in specified width. 2444@end menu 2445 2446 2447@node fmt invocation 2448@section @command{fmt}: Reformat paragraph text 2449 2450@pindex fmt 2451@cindex reformatting paragraph text 2452@cindex paragraphs, reformatting 2453@cindex text, reformatting 2454 2455@command{fmt} fills and joins lines to produce output lines of (at most) 2456a given number of characters (75 by default). Synopsis: 2457 2458@example 2459fmt [@var{option}]@dots{} [@var{file}]@dots{} 2460@end example 2461 2462@command{fmt} reads from the specified @var{file} arguments (or standard 2463input if none are given), and writes to standard output. 2464 2465By default, blank lines, spaces between words, and indentation are 2466preserved in the output; successive input lines with different 2467indentation are not joined; tabs are expanded on input and introduced on 2468output. 2469 2470@cindex line-breaking 2471@cindex sentences and line-breaking 2472@cindex Knuth, Donald E. 2473@cindex Plass, Michael F. 2474@command{fmt} prefers breaking lines at the end of a sentence, and tries to 2475avoid line breaks after the first word of a sentence or before the last 2476word of a sentence. A @dfn{sentence break} is defined as either the end 2477of a paragraph or a word ending in any of @samp{.?!}, followed by two 2478spaces or end of line, ignoring any intervening parentheses or quotes. 2479Like @TeX{}, @command{fmt} reads entire ``paragraphs'' before choosing line 2480breaks; the algorithm is a variant of that given by Donald E. Knuth 2481and Michael F. Plass in ``Breaking Paragraphs Into Lines'', 2482@cite{Software: Practice & Experience} @b{11}, 11 (November 1981), 24831119--1184. 2484 2485The program accepts the following options. Also see @ref{Common options}. 2486 2487@table @samp 2488 2489@item -c 2490@itemx --crown-margin 2491@opindex -c 2492@opindex --crown-margin 2493@cindex crown margin 2494@dfn{Crown margin} mode: preserve the indentation of the first two 2495lines within a paragraph, and align the left margin of each subsequent 2496line with that of the second line. 2497 2498@item -t 2499@itemx --tagged-paragraph 2500@opindex -t 2501@opindex --tagged-paragraph 2502@cindex tagged paragraphs 2503@dfn{Tagged paragraph} mode: like crown margin mode, except that if 2504indentation of the first line of a paragraph is the same as the 2505indentation of the second, the first line is treated as a one-line 2506paragraph. 2507 2508@item -s 2509@itemx --split-only 2510@opindex -s 2511@opindex --split-only 2512Split lines only. Do not join short lines to form longer ones. This 2513prevents sample lines of code, and other such ``formatted'' text from 2514being unduly combined. 2515 2516@item -u 2517@itemx --uniform-spacing 2518@opindex -u 2519@opindex --uniform-spacing 2520Uniform spacing. Reduce spacing between words to one space, and spacing 2521between sentences to two spaces. 2522 2523@item -@var{width} 2524@itemx -w @var{width} 2525@itemx --width=@var{width} 2526@opindex -@var{width} 2527@opindex -w 2528@opindex --width 2529Fill output lines up to @var{width} characters (default 75 or @var{goal} 2530plus 10, if @var{goal} is provided). 2531 2532@item -g @var{goal} 2533@itemx --goal=@var{goal} 2534@opindex -g 2535@opindex --goal 2536@command{fmt} initially tries to make lines @var{goal} characters wide. 2537By default, this is 7% shorter than @var{width}. 2538 2539@item -p @var{prefix} 2540@itemx --prefix=@var{prefix} 2541Only lines beginning with @var{prefix} (possibly preceded by whitespace) 2542are subject to formatting. The prefix and any preceding whitespace are 2543stripped for the formatting and then re-attached to each formatted output 2544line. One use is to format certain kinds of program comments, while 2545leaving the code unchanged. 2546 2547@end table 2548 2549@exitstatus 2550 2551@node pr invocation 2552@section @command{pr}: Paginate or columnate files for printing 2553 2554@pindex pr 2555@cindex printing, preparing files for 2556@cindex multicolumn output, generating 2557@cindex merging files in parallel 2558 2559@command{pr} writes each @var{file} (@samp{-} means standard input), or 2560standard input if none are given, to standard output, paginating and 2561optionally outputting in multicolumn format; optionally merges all 2562@var{file}s, printing all in parallel, one per column. Synopsis: 2563 2564@example 2565pr [@var{option}]@dots{} [@var{file}]@dots{} 2566@end example 2567 2568@vindex LC_MESSAGES 2569By default, a 5-line header is printed at each page: two blank lines; 2570a line with the date, the file name, and the page count; and two more 2571blank lines. A footer of five blank lines is also printed. 2572The default @var{page_length} is 66 2573lines. The default number of text lines is therefore 56. 2574The text line of the header takes the form 2575@samp{@var{date} @var{string} @var{page}}, with spaces inserted around 2576@var{string} so that the line takes up the full @var{page_width}. Here, 2577@var{date} is the date (see the @option{-D} or @option{--date-format} 2578option for details), @var{string} is the centered header string, and 2579@var{page} identifies the page number. The @env{LC_MESSAGES} locale 2580category affects the spelling of @var{page}; in the default C locale, it 2581is @samp{Page @var{number}} where @var{number} is the decimal page 2582number. 2583 2584Form feeds in the input cause page breaks in the output. Multiple form 2585feeds produce empty pages. 2586 2587Columns are of equal width, separated by an optional string (default 2588is @samp{space}). For multicolumn output, lines will always be truncated to 2589@var{page_width} (default 72), unless you use the @option{-J} option. 2590For single 2591column output no line truncation occurs by default. Use @option{-W} option to 2592truncate lines in that case. 2593 2594The program accepts the following options. Also see @ref{Common options}. 2595 2596@table @samp 2597 2598@item +@var{first_page}[:@var{last_page}] 2599@itemx --pages=@var{first_page}[:@var{last_page}] 2600@c The two following @opindex lines evoke warnings because they contain ':' 2601@c The 'info' spec does not permit that. If we use those lines, we end 2602@c up with truncated index entries that don't work. 2603@c @opindex +@var{first_page}[:@var{last_page}] 2604@c @opindex --pages=@var{first_page}[:@var{last_page}] 2605@opindex +@var{page_range} 2606@opindex --pages=@var{page_range} 2607Begin printing with page @var{first_page} and stop with @var{last_page}. 2608Missing @samp{:@var{last_page}} implies end of file. While estimating 2609the number of skipped pages each form feed in the input file results 2610in a new page. Page counting with and without @samp{+@var{first_page}} 2611is identical. By default, counting starts with the first page of input 2612file (not first page printed). Line numbering may be altered by @option{-N} 2613option. 2614 2615@item -@var{column} 2616@itemx --columns=@var{column} 2617@opindex -@var{column} 2618@opindex --columns 2619@cindex down columns 2620With each single @var{file}, produce @var{column} columns of output 2621(default is 1) and print columns down, unless @option{-a} is used. The 2622column width is automatically decreased as @var{column} increases; unless 2623you use the @option{-W/-w} option to increase @var{page_width} as well. 2624This option might well cause some lines to be truncated. The number of 2625lines in the columns on each page are balanced. The options @option{-e} 2626and @option{-i} are on for multiple text-column output. Together with 2627@option{-J} option column alignment and line truncation is turned off. 2628Lines of full length are joined in a free field format and @option{-S} 2629option may set field separators. @option{-@var{column}} may not be used 2630with @option{-m} option. 2631 2632@item -a 2633@itemx --across 2634@opindex -a 2635@opindex --across 2636@cindex across columns 2637With each single @var{file}, print columns across rather than down. The 2638@option{-@var{column}} option must be given with @var{column} greater than one. 2639If a line is too long to fit in a column, it is truncated. 2640 2641@item -c 2642@itemx --show-control-chars 2643@opindex -c 2644@opindex --show-control-chars 2645Print control characters using hat notation (e.g., @samp{^G}); print 2646other nonprinting characters in octal backslash notation. By default, 2647nonprinting characters are not changed. 2648 2649@item -d 2650@itemx --double-space 2651@opindex -d 2652@opindex --double-space 2653@cindex double spacing 2654Double space the output. 2655 2656@item -D @var{format} 2657@itemx --date-format=@var{format} 2658@cindex time formats 2659@cindex formatting times 2660Format header dates using @var{format}, using the same conventions as 2661for the command @samp{date +@var{format}}. @xref{date invocation}. 2662Except for directives, which start with 2663@samp{%}, characters in @var{format} are printed unchanged. You can use 2664this option to specify an arbitrary string in place of the header date, 2665e.g., @option{--date-format="Monday morning"}. 2666 2667@vindex POSIXLY_CORRECT 2668@vindex LC_TIME 2669The default date format is @samp{%Y-%m-%d %H:%M} (for example, 2670@samp{2020-07-09 23:59}); 2671but if the @env{POSIXLY_CORRECT} environment variable is set 2672and the @env{LC_TIME} locale category specifies the POSIX 2673locale, the default is @samp{%b %e %H:%M %Y} (for example, 2674@samp{Jul@ @ 9 23:59 2020}. 2675 2676@vindex TZ 2677Timestamps are listed according to the time zone rules specified by 2678the @env{TZ} environment variable, or by the system default rules if 2679@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone 2680with @env{TZ}, libc, The GNU C Library Reference Manual}. 2681 2682@item -e[@var{in-tabchar}[@var{in-tabwidth}]] 2683@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]] 2684@opindex -e 2685@opindex --expand-tabs 2686@cindex input tabs 2687Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is 2688the input tab character (default is the TAB character). Second optional 2689argument @var{in-tabwidth} is the input tab character's width (default 2690is 8). 2691 2692@item -f 2693@itemx -F 2694@itemx --form-feed 2695@opindex -F 2696@opindex -f 2697@opindex --form-feed 2698Use a form feed instead of newlines to separate output pages. This does 2699not alter the default page length of 66 lines. 2700 2701@item -h @var{header} 2702@itemx --header=@var{header} 2703@opindex -h 2704@opindex --header 2705Replace the file name in the header with the centered string @var{header}. 2706When using the shell, @var{header} should be quoted and should be 2707separated from @option{-h} by a space. 2708 2709@item -i[@var{out-tabchar}[@var{out-tabwidth}]] 2710@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]] 2711@opindex -i 2712@opindex --output-tabs 2713@cindex output tabs 2714Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar} 2715is the output tab character (default is the TAB character). Second optional 2716argument @var{out-tabwidth} is the output tab character's width (default 2717is 8). 2718 2719@item -J 2720@itemx --join-lines 2721@opindex -J 2722@opindex --join-lines 2723Merge lines of full length. Used together with the column options 2724@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off 2725@option{-W/-w} line truncation; 2726no column alignment used; may be used with 2727@option{--sep-string[=@var{string}]}. @option{-J} has been introduced 2728(together with @option{-W} and @option{--sep-string}) 2729to disentangle the old (POSIX-compliant) options @option{-w} and 2730@option{-s} along with the three column options. 2731 2732 2733@item -l @var{page_length} 2734@itemx --length=@var{page_length} 2735@opindex -l 2736@opindex --length 2737Set the page length to @var{page_length} (default 66) lines, including 2738the lines of the header [and the footer]. If @var{page_length} is less 2739than or equal to 10, the header and footer are omitted, as if the 2740@option{-t} option had been given. 2741 2742@item -m 2743@itemx --merge 2744@opindex -m 2745@opindex --merge 2746Merge and print all @var{file}s in parallel, one in each column. If a 2747line is too long to fit in a column, it is truncated, unless the @option{-J} 2748option is used. @option{--sep-string[=@var{string}]} may be used. 2749Empty pages in 2750some @var{file}s (form feeds set) produce empty columns, still marked 2751by @var{string}. The result is a continuous line numbering and column 2752marking throughout the whole merged file. Completely empty merged pages 2753show no separators or line numbers. The default header becomes 2754@samp{@var{date} @var{page}} with spaces inserted in the middle; this 2755may be used with the @option{-h} or @option{--header} option to fill up 2756the middle blank part. 2757 2758@item -n[@var{number-separator}[@var{digits}]] 2759@itemx --number-lines[=@var{number-separator}[@var{digits}]] 2760@opindex -n 2761@opindex --number-lines 2762Provide @var{digits} digit line numbering (default for @var{digits} is 27635). With multicolumn output the number occupies the first @var{digits} 2764column positions of each text column or only each line of @option{-m} 2765output. With single column output the number precedes each line just as 2766@option{-m} does. Default counting of the line numbers starts with the 2767first line of the input file (not the first line printed, compare the 2768@option{--page} option and @option{-N} option). 2769Optional argument @var{number-separator} is the character appended to 2770the line number to separate it from the text followed. The default 2771separator is the TAB character. In a strict sense a TAB is always 2772printed with single column output only. The TAB width varies 2773with the TAB position, e.g., with the left @var{margin} specified 2774by @option{-o} option. With multicolumn output priority is given to 2775@samp{equal width of output columns} (a POSIX specification). 2776The TAB width is fixed to the value of the first column and does 2777not change with different values of left @var{margin}. That means a 2778fixed number of spaces is always printed in the place of the 2779@var{number-separator} TAB@. The tabification depends upon the output 2780position. 2781 2782@item -N @var{line_number} 2783@itemx --first-line-number=@var{line_number} 2784@opindex -N 2785@opindex --first-line-number 2786Start line counting with the number @var{line_number} at first line of 2787first page printed (in most cases not the first line of the input file). 2788 2789@item -o @var{margin} 2790@itemx --indent=@var{margin} 2791@opindex -o 2792@opindex --indent 2793@cindex indenting lines 2794@cindex left margin 2795Indent each line with a margin @var{margin} spaces wide (default is zero). 2796The total page width is the size of the margin plus the @var{page_width} 2797set with the @option{-W/-w} option. A limited overflow may occur with 2798numbered single column output (compare @option{-n} option). 2799 2800@item -r 2801@itemx --no-file-warnings 2802@opindex -r 2803@opindex --no-file-warnings 2804Do not print a warning message when an argument @var{file} cannot be 2805opened. (The exit status will still be nonzero, however.) 2806 2807@item -s[@var{char}] 2808@itemx --separator[=@var{char}] 2809@opindex -s 2810@opindex --separator 2811Separate columns by a single character @var{char}. The default for 2812@var{char} is the TAB character without @option{-w} and @samp{no 2813character} with @option{-w}. Without @option{-s} the default separator 2814@samp{space} is set. @option{-s[char]} turns off line truncation of all 2815three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless 2816@option{-w} is set. This is a POSIX-compliant formulation. 2817 2818 2819@item -S[@var{string}] 2820@itemx --sep-string[=@var{string}] 2821@opindex -S 2822@opindex --sep-string 2823Use @var{string} to separate output columns. The @option{-S} option doesn't 2824affect the @option{-W/-w} option, unlike the @option{-s} option which does. It 2825does not affect line truncation or column alignment. 2826Without @option{-S}, and with @option{-J}, @command{pr} uses the default output 2827separator, TAB@. 2828Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space} 2829(same as @option{-S"@w{ }"}). 2830If no @samp{@var{string}} argument is specified, @samp{""} is assumed. 2831 2832@item -t 2833@itemx --omit-header 2834@opindex -t 2835@opindex --omit-header 2836Do not print the usual header [and footer] on each page, and do not fill 2837out the bottom of pages (with blank lines or a form feed). No page 2838structure is produced, but form feeds set in the input files are retained. 2839The predefined pagination is not changed. @option{-t} or @option{-T} may be 2840useful together with other options; e.g.: @option{-t -e4}, expand TAB characters 2841in the input file to 4 spaces but don't make any other changes. Use of 2842@option{-t} overrides @option{-h}. 2843 2844@item -T 2845@itemx --omit-pagination 2846@opindex -T 2847@opindex --omit-pagination 2848Do not print header [and footer]. In addition eliminate all form feeds 2849set in the input files. 2850 2851@item -v 2852@itemx --show-nonprinting 2853@opindex -v 2854@opindex --show-nonprinting 2855Print nonprinting characters in octal backslash notation. 2856 2857@item -w @var{page_width} 2858@itemx --width=@var{page_width} 2859@opindex -w 2860@opindex --width 2861Set page width to @var{page_width} characters for multiple text-column 2862output only (default for @var{page_width} is 72). The specified 2863@var{page_width} is rounded down so that columns have equal width. 2864@option{-s[CHAR]} turns off the default page width and any line truncation 2865and column alignment. 2866Lines of full length are merged, regardless of the column options 2867set. No @var{page_width} setting is possible with single column output. 2868A POSIX-compliant formulation. 2869 2870@item -W @var{page_width} 2871@itemx --page_width=@var{page_width} 2872@opindex -W 2873@opindex --page_width 2874Set the page width to @var{page_width} characters, honored with and 2875without a column option. With a column option, the specified @var{page_width} 2876is rounded down so that columns have equal width. Text lines are truncated, 2877unless @option{-J} is used. Together with one of the three column options 2878(@option{-@var{column}}, @option{-a -@var{column}} or @option{-m}) column 2879alignment is always used. The separator options @option{-S} or @option{-s} 2880don't disable the @option{-W} option. Default is 72 characters. Without 2881@option{-W @var{page_width}} and without any of the column options NO line 2882truncation is used (defined to keep downward compatibility and to meet 2883most frequent tasks). That's equivalent to @option{-W 72 -J}@. The header 2884line is never truncated. 2885 2886@end table 2887 2888@exitstatus 2889 2890 2891@node fold invocation 2892@section @command{fold}: Wrap input lines to fit in specified width 2893 2894@pindex fold 2895@cindex wrapping long input lines 2896@cindex folding long input lines 2897 2898@command{fold} writes each @var{file} (@option{-} means standard input), or 2899standard input if none are given, to standard output, breaking long 2900lines. Synopsis: 2901 2902@example 2903fold [@var{option}]@dots{} [@var{file}]@dots{} 2904@end example 2905 2906By default, @command{fold} breaks lines wider than 80 columns. The output 2907is split into as many lines as necessary. 2908 2909@cindex screen columns 2910@command{fold} counts screen columns by default; thus, a tab may count more 2911than one column, backspace decreases the column count, and carriage 2912return sets the column to zero. 2913 2914The program accepts the following options. Also see @ref{Common options}. 2915 2916@table @samp 2917 2918@item -b 2919@itemx --bytes 2920@opindex -b 2921@opindex --bytes 2922Count bytes rather than columns, so that tabs, backspaces, and carriage 2923returns are each counted as taking up one column, just like other 2924characters. 2925 2926@item -s 2927@itemx --spaces 2928@opindex -s 2929@opindex --spaces 2930Break at word boundaries: the line is broken after the last blank before 2931the maximum line length. If the line contains no such blanks, the line 2932is broken at the maximum line length as usual. 2933 2934@item -w @var{width} 2935@itemx --width=@var{width} 2936@opindex -w 2937@opindex --width 2938Use a maximum line length of @var{width} columns instead of 80. 2939 2940For compatibility @command{fold} supports an obsolete option syntax 2941@option{-@var{width}}. New scripts should use @option{-w @var{width}} 2942instead. 2943 2944@end table 2945 2946@exitstatus 2947 2948 2949@node Output of parts of files 2950@chapter Output of parts of files 2951 2952@cindex output of parts of files 2953@cindex parts of files, output of 2954 2955These commands output pieces of the input. 2956 2957@menu 2958* head invocation:: Output the first part of files. 2959* tail invocation:: Output the last part of files. 2960* split invocation:: Split a file into pieces. 2961* csplit invocation:: Split a file into context-determined pieces. 2962@end menu 2963 2964@node head invocation 2965@section @command{head}: Output the first part of files 2966 2967@pindex head 2968@cindex initial part of files, outputting 2969@cindex first part of files, outputting 2970 2971@command{head} prints the first part (10 lines by default) of each 2972@var{file}; it reads from standard input if no files are given or 2973when given a @var{file} of @option{-}. Synopsis: 2974 2975@example 2976head [@var{option}]@dots{} [@var{file}]@dots{} 2977@end example 2978 2979If more than one @var{file} is specified, @command{head} prints a 2980one-line header consisting of: 2981 2982@example 2983==> @var{file name} <== 2984@end example 2985 2986@noindent 2987before the output for each @var{file}. 2988 2989The program accepts the following options. Also see @ref{Common options}. 2990 2991@table @samp 2992 2993@item -c [-]@var{num} 2994@itemx --bytes=[-]@var{num} 2995@opindex -c 2996@opindex --bytes 2997Print the first @var{num} bytes, instead of initial lines. 2998However, if @var{num} is prefixed with a @samp{-}, 2999print all but the last @var{num} bytes of each file. 3000@multiplierSuffixes{num} 3001 3002@item -n [-]@var{num} 3003@itemx --lines=[-]@var{num} 3004@opindex -n 3005@opindex --lines 3006Output the first @var{num} lines. 3007However, if @var{num} is prefixed with a @samp{-}, 3008print all but the last @var{num} lines of each file. 3009Size multiplier suffixes are the same as with the @option{-c} option. 3010 3011@item -q 3012@itemx --quiet 3013@itemx --silent 3014@opindex -q 3015@opindex --quiet 3016@opindex --silent 3017Never print file name headers. 3018 3019@item -v 3020@itemx --verbose 3021@opindex -v 3022@opindex --verbose 3023Always print file name headers. 3024 3025@optZeroTerminated 3026 3027@end table 3028 3029For compatibility @command{head} also supports an obsolete option syntax 3030@option{-[@var{num}][bkm][cqv]}, which is recognized only if it is 3031specified first. @var{num} is a decimal number optionally followed 3032by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or 3033@samp{l} to mean count by lines, or other option letters (@samp{cqv}). 3034Scripts intended for standard hosts should use @option{-c @var{num}} 3035or @option{-n @var{num}} instead. If your script must also run on 3036hosts that support only the obsolete syntax, it is usually simpler to 3037avoid @command{head}, e.g., by using @samp{sed 5q} instead of 3038@samp{head -5}. 3039 3040@exitstatus 3041 3042 3043@node tail invocation 3044@section @command{tail}: Output the last part of files 3045 3046@pindex tail 3047@cindex last part of files, outputting 3048 3049@command{tail} prints the last part (10 lines by default) of each 3050@var{file}; it reads from standard input if no files are given or 3051when given a @var{file} of @samp{-}. Synopsis: 3052 3053@example 3054tail [@var{option}]@dots{} [@var{file}]@dots{} 3055@end example 3056 3057If more than one @var{file} is specified, @command{tail} prints a 3058one-line header before the output for each @var{file}, consisting of: 3059 3060@example 3061==> @var{file name} <== 3062@end example 3063 3064For further processing of tail output, it can be useful to convert the 3065file headers to line prefixes, which can be done like: 3066 3067@example 3068tail @dots{} | 3069awk ' 3070 /^==> .* <==$/ @{prefix=substr($0,5,length-8)":"; next@} 3071 @{print prefix$0@} 3072' | @dots{} 3073@end example 3074 3075@cindex BSD @command{tail} 3076GNU @command{tail} can output any amount of data (some other versions of 3077@command{tail} cannot). It also has no @option{-r} option (print in 3078reverse), since reversing a file is really a different job from printing 3079the end of a file; BSD @command{tail} (which is the one with @option{-r}) can 3080only reverse files that are at most as large as its buffer, which is 3081typically 32 KiB@. A more reliable and versatile way to reverse files is 3082the GNU @command{tac} command. 3083 3084The program accepts the following options. Also see @ref{Common options}. 3085 3086@table @samp 3087 3088@item -c [+]@var{num} 3089@itemx --bytes=[+]@var{num} 3090@opindex -c 3091@opindex --bytes 3092Output the last @var{num} bytes, instead of final lines. 3093If @var{num} is prefixed with a @samp{+}, start printing with 3094byte @var{num} from the start of each file. For example to skip the first byte 3095use @code{tail -c +2}, while to skip all but the last byte use @code{tail -c 1}. 3096@multiplierSuffixes{num} 3097 3098@item -f 3099@itemx --follow[=@var{how}] 3100@opindex -f 3101@opindex --follow 3102@cindex growing files 3103@vindex name @r{follow option} 3104@vindex descriptor @r{follow option} 3105Loop forever trying to read more characters at the end of the file, 3106presumably because the file is growing. 3107If more than one file is given, @command{tail} prints a header whenever it 3108gets output from a different file, to indicate which file that output is 3109from. 3110 3111There are two ways to specify how you'd like to track files with this option, 3112but that difference is noticeable only when a followed file is removed or 3113renamed. 3114If you'd like to continue to track the end of a growing file even after 3115it has been unlinked, use @option{--follow=descriptor}. This is the default 3116behavior, but it is not useful if you're tracking a log file that may be 3117rotated (removed or renamed, then reopened). In that case, use 3118@option{--follow=name} to track the named file, perhaps by reopening it 3119periodically to see if it has been removed and recreated by some other program. 3120Note that the inotify-based implementation handles this case without 3121the need for any periodic reopening. 3122 3123No matter which method you use, if the tracked file is determined to have 3124shrunk, @command{tail} prints a message saying the file has been truncated 3125and resumes tracking from the start of the file, assuming it has been 3126truncated to 0, which is the usual truncation operation for log files. 3127 3128When a file is removed, @command{tail}'s behavior depends on whether it is 3129following the name or the descriptor. When following by name, tail can 3130detect that a file has been removed and gives a message to that effect, 3131and if @option{--retry} has been specified it will continue checking 3132periodically to see if the file reappears. 3133When following a descriptor, tail does not detect that the file has 3134been unlinked or renamed and issues no message; even though the file 3135may no longer be accessible via its original name, it may still be 3136growing. 3137 3138The option values @samp{descriptor} and @samp{name} may be specified only 3139with the long form of the option, not with @option{-f}. 3140 3141The @option{-f} option is ignored if 3142no @var{file} operand is specified and standard input is a FIFO or a pipe. 3143Likewise, the @option{-f} option has no effect for any 3144operand specified as @samp{-}, when standard input is a FIFO or a pipe. 3145 3146With kernel inotify support, output is triggered by file changes 3147and is generally very prompt. 3148Otherwise, @command{tail} sleeps for one second between checks -- 3149use @option{--sleep-interval=@var{n}} to change that default -- which can 3150make the output appear slightly less responsive or bursty. 3151When using tail without inotify support, you can make it more responsive 3152by using a sub-second sleep interval, e.g., via an alias like this: 3153 3154@example 3155alias tail='tail -s.1' 3156@end example 3157 3158@item -F 3159@opindex -F 3160This option is the same as @option{--follow=name --retry}. That is, tail 3161will attempt to reopen a file when it is removed. Should this fail, tail 3162will keep trying until it becomes accessible again. 3163 3164@item --max-unchanged-stats=@var{n} 3165@opindex --max-unchanged-stats 3166When tailing a file by name, if there have been @var{n} (default 3167n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive 3168iterations for which the file has not changed, then 3169@code{open}/@code{fstat} the file to determine if that file name is 3170still associated with the same device/inode-number pair as before. 3171When following a log file that is rotated, this is approximately the 3172number of seconds between when tail prints the last pre-rotation lines 3173and when it prints the lines that have accumulated in the new log file. 3174This option is meaningful only when polling (i.e., without inotify) 3175and when following by name. 3176 3177@item -n [+]@var{num} 3178@itemx --lines=[+]@var{} 3179@opindex -n 3180@opindex --lines 3181Output the last @var{num} lines. 3182If @var{num} is prefixed with a @samp{+}, start printing with 3183line @var{num} from the start of each file. For example to skip the first line 3184use @code{tail -n +2}, while to skip all but the last line use @code{tail -n 1}. 3185Size multiplier suffixes are the same as with the @option{-c} option. 3186 3187@item --pid=@var{pid} 3188@opindex --pid 3189When following by name or by descriptor, you may specify the process ID, 3190@var{pid}, of one or more (by repeating @option{--pid}) writers of the 3191@var{file} arguments. Then, shortly after all the identified 3192processes terminate, tail will also terminate. This will 3193work properly only if the writers and the tailing process are running on 3194the same machine. For example, to save the output of a build in a file 3195and to watch the file grow, if you invoke @command{make} and @command{tail} 3196like this then the tail process will stop when your build completes. 3197Without this option, you would have had to kill the @code{tail -f} 3198process yourself. 3199 3200@example 3201$ make >& makerr & tail --pid=$! -f makerr 3202@end example 3203 3204If you specify a @var{pid} that is not in use or that does not correspond 3205to the process that is writing to the tailed files, then @command{tail} 3206may terminate long before any @var{file}s stop growing or it may not 3207terminate until long after the real writer has terminated. 3208Note that @option{--pid} cannot be supported on some systems; @command{tail} 3209will print a warning if this is the case. 3210 3211@item -q 3212@itemx --quiet 3213@itemx --silent 3214@opindex -q 3215@opindex --quiet 3216@opindex --silent 3217Never print file name headers. 3218 3219@item --retry 3220@opindex --retry 3221Indefinitely try to open the specified file. 3222This option is useful mainly when following (and otherwise issues a warning). 3223 3224When following by file descriptor (i.e., with @option{--follow=descriptor}), 3225this option only affects the initial open of the file, as after a successful 3226open, @command{tail} will start following the file descriptor. 3227 3228When following by name (i.e., with @option{--follow=name}), @command{tail} 3229infinitely retries to re-open the given files until killed. 3230 3231Without this option, when @command{tail} encounters a file that doesn't 3232exist or is otherwise inaccessible, it reports that fact and 3233never checks it again. 3234 3235@item -s @var{number} 3236@itemx --sleep-interval=@var{number} 3237@opindex -s 3238@opindex --sleep-interval 3239Change the number of seconds to wait between iterations (the default is 1.0). 3240During one iteration, every specified file is checked to see if it has 3241changed size. 3242When @command{tail} uses inotify, this polling-related option 3243is usually ignored. However, if you also specify @option{--pid=@var{p}}, 3244@command{tail} checks whether process @var{p} is alive at least 3245every @var{number} seconds. 3246The @var{number} must be non-negative and can be a floating-point number 3247in either the current or the C locale. @xref{Floating point}. 3248 3249@item -v 3250@itemx --verbose 3251@opindex -v 3252@opindex --verbose 3253Always print file name headers. 3254 3255@optZeroTerminated 3256 3257@end table 3258 3259For compatibility @command{tail} also supports an obsolete usage 3260@samp{tail -[@var{num}][bcl][f] [@var{file}]}, which is recognized 3261only if it does not conflict with the usage described 3262above. This obsolete form uses exactly one option and at most one 3263file. In the option, @var{num} is an optional decimal number optionally 3264followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count 3265by 512-byte blocks, bytes, or lines, optionally followed by @samp{f} 3266which has the same meaning as @option{-f}. 3267 3268@vindex _POSIX2_VERSION 3269On systems not conforming to POSIX 1003.1-2001, the leading @samp{-} 3270can be replaced by @samp{+} in the traditional option syntax with the 3271same meaning as in counts, and on obsolete systems predating POSIX 32721003.1-2001 traditional usage overrides normal usage when the two 3273conflict. This behavior can be controlled with the 3274@env{_POSIX2_VERSION} environment variable (@pxref{Standards 3275conformance}). 3276 3277Scripts intended for use on standard hosts should avoid traditional 3278syntax and should use @option{-c @var{num}[b]}, @option{-n 3279@var{num}}, and/or @option{-f} instead. If your script must also 3280run on hosts that support only the traditional syntax, you can often 3281rewrite it to avoid problematic usages, e.g., by using @samp{sed -n 3282'$p'} rather than @samp{tail -1}. If that's not possible, the script 3283can use a test like @samp{if tail -c +1 </dev/null >/dev/null 2>&1; 3284then @dots{}} to decide which syntax to use. 3285 3286Even if your script assumes the standard behavior, you should still 3287beware usages whose behaviors differ depending on the POSIX 3288version. For example, avoid @samp{tail - main.c}, since it might be 3289interpreted as either @samp{tail main.c} or as @samp{tail -- - 3290main.c}; avoid @samp{tail -c 4}, since it might mean either @samp{tail 3291-c4} or @samp{tail -c 10 4}; and avoid @samp{tail +4}, since it might 3292mean either @samp{tail ./+4} or @samp{tail -n +4}. 3293 3294@exitstatus 3295 3296 3297@node split invocation 3298@section @command{split}: Split a file into pieces. 3299 3300@pindex split 3301@cindex splitting a file into pieces 3302@cindex pieces, splitting a file into 3303 3304@command{split} creates output files containing consecutive or interleaved 3305sections of @var{input} (standard input if none is given or @var{input} 3306is @samp{-}). Synopsis: 3307 3308@example 3309split [@var{option}] [@var{input} [@var{prefix}]] 3310@end example 3311 3312By default, @command{split} puts 1000 lines of @var{input} (or whatever is 3313left over for the last section), into each output file. 3314 3315@cindex output file name prefix 3316The output files' names consist of @var{prefix} (@samp{x} by default) 3317followed by a group of characters (@samp{aa}, @samp{ab}, @dots{} by 3318default), such that concatenating the output files in traditional 3319sorted order by file name produces the original input file (except 3320@option{-nr/@var{n}}). By default split will initially create files 3321with two generated suffix characters, and will increase this width by two 3322when the next most significant position reaches the last character. 3323(@samp{yz}, @samp{zaaa}, @samp{zaab}, @dots{}). In this way an arbitrary 3324number of output files are supported, which sort as described above, 3325even in the presence of an @option{--additional-suffix} option. 3326If the @option{-a} option is specified and the output file names are 3327exhausted, @command{split} reports an error without deleting the 3328output files that it did create. 3329 3330The program accepts the following options. Also see @ref{Common options}. 3331 3332@table @samp 3333 3334@item -l @var{lines} 3335@itemx --lines=@var{lines} 3336@opindex -l 3337@opindex --lines 3338Put @var{lines} lines of @var{input} into each output file. 3339If @option{--separator} is specified, then @var{lines} determines 3340the number of records. 3341 3342For compatibility @command{split} also supports an obsolete 3343option syntax @option{-@var{lines}}. New scripts should use 3344@option{-l @var{lines}} instead. 3345 3346@item -b @var{size} 3347@itemx --bytes=@var{size} 3348@opindex -b 3349@opindex --bytes 3350Put @var{size} bytes of @var{input} into each output file. 3351@multiplierSuffixes{size} 3352 3353@item -C @var{size} 3354@itemx --line-bytes=@var{size} 3355@opindex -C 3356@opindex --line-bytes 3357Put into each output file as many complete lines of @var{input} as 3358possible without exceeding @var{size} bytes. Individual lines or records 3359longer than @var{size} bytes are broken into multiple files. 3360@var{size} has the same format as for the @option{--bytes} option. 3361If @option{--separator} is specified, then @var{lines} determines 3362the number of records. 3363 3364@item --filter=@var{command} 3365@opindex --filter 3366With this option, rather than simply writing to each output file, 3367write through a pipe to the specified shell @var{command} for each output file. 3368@var{command} should use the $FILE environment variable, which is set 3369to a different output file name for each invocation of the command. 3370For example, imagine that you have a 1TiB compressed file 3371that, if uncompressed, would be too large to reside on secondary storage, 3372yet you must split it into individually-compressed pieces 3373of a more manageable size. 3374To do that, you might run this command: 3375 3376@example 3377xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big- 3378@end example 3379 3380Assuming a 10:1 compression ratio, that would create about fifty 20GiB files 3381with names @file{big-aa.xz}, @file{big-ab.xz}, @file{big-ac.xz}, etc. 3382 3383@item -n @var{chunks} 3384@itemx --number=@var{chunks} 3385@opindex -n 3386@opindex --number 3387 3388Split @var{input} to @var{chunks} output files where @var{chunks} may be: 3389 3390@example 3391@var{n} generate @var{n} files based on current size of @var{input} 3392@var{k}/@var{n} output only @var{k}th of @var{n} to standard output 3393l/@var{n} generate @var{n} files without splitting lines or records 3394l/@var{k}/@var{n} likewise but output only @var{k}th of @var{n} to stdout 3395r/@var{n} like @samp{l} but use round robin distribution 3396r/@var{k}/@var{n} likewise but output only @var{k}th of @var{n} to stdout 3397@end example 3398 3399If the input size is not a multiple of @var{n}, early output files are 3400one byte longer than later output files, to make up the difference. 3401Any excess bytes appearing after the initial calculation are discarded 3402(except when using @samp{r} mode). 3403 3404All @var{n} files are created even if there are fewer than @var{n} lines, 3405or the @var{input} is truncated. 3406 3407For @samp{l} mode, chunks are approximately @var{input} size / @var{n}. 3408Although the @var{input} is still partitioned as before into @var{n} regions 3409of approximately equal size, if a line @emph{starts} within a partition 3410it is written completely to the corresponding file. Since lines or records 3411are not split even if they overlap a partition, the files written 3412can be larger or smaller than the partition size, and even empty 3413if a line/record is so long as to completely overlap the partition. 3414 3415When the input is a pipe or some other special file where the size 3416cannot easily be determined, there is no trouble for @samp{r} mode 3417because the size of the input is irrelevant. For other modes, such an 3418input is first copied to a temporary to determine its size. 3419 3420@item -a @var{length} 3421@itemx --suffix-length=@var{length} 3422@opindex -a 3423@opindex --suffix-length 3424Use suffixes of length @var{length}. If a @var{length} of 0 is specified, 3425this is the same as if (any previous) @option{-a} was not specified, and 3426thus enables the default behavior, which starts the suffix length at 2, 3427and unless @option{-n} or @option{--numeric-suffixes=@var{from}} is 3428specified, will auto increase the length by 2 as required. 3429 3430@item -d 3431@itemx --numeric-suffixes[=@var{from}] 3432@opindex -d 3433@opindex --numeric-suffixes 3434Use digits in suffixes rather than lower-case letters. The numerical 3435suffix counts from @var{from} if specified, 0 otherwise. 3436 3437@var{from} is supported with the long form option, and is used to either set the 3438initial suffix for a single run, or to set the suffix offset for independently 3439split inputs, and consequently the auto suffix length expansion described above 3440is disabled. Therefore you may also want to use option @option{-a} to allow 3441suffixes beyond @samp{99}. Note if option @option{--number} is specified and 3442the number of files is less than @var{from}, a single run is assumed and the 3443minimum suffix length required is automatically determined. 3444 3445@item -x 3446@itemx --hex-suffixes[=@var{from}] 3447@opindex -x 3448@opindex --hex-suffixes 3449Like @option{--numeric-suffixes}, but use hexadecimal numbers (in lower case). 3450 3451@item --additional-suffix=@var{suffix} 3452@opindex --additional-suffix 3453Append an additional @var{suffix} to output file names. @var{suffix} 3454must not contain slash. 3455 3456@item -e 3457@itemx --elide-empty-files 3458@opindex -e 3459@opindex --elide-empty-files 3460Suppress the generation of zero-length output files. This can happen 3461with the @option{--number} option if a file is (truncated to be) shorter 3462than the number requested, or if a line is so long as to completely 3463span a chunk. The output file sequence numbers, always run consecutively 3464even when this option is specified. 3465 3466@item -t @var{separator} 3467@itemx --separator=@var{separator} 3468@opindex -t 3469@opindex --separator 3470@cindex line separator character 3471@cindex record separator character 3472Use character @var{separator} as the record separator instead of the default 3473newline character (ASCII LF). 3474To specify ASCII NUL as the separator, use the two-character string @samp{\0}, 3475e.g., @samp{split -t '\0'}. 3476 3477@item -u 3478@itemx --unbuffered 3479@opindex -u 3480@opindex --unbuffered 3481Immediately copy input to output in @option{--number r/@dots{}} mode, 3482which is a much slower mode of operation. 3483 3484@item --verbose 3485@opindex --verbose 3486Write a diagnostic just before each output file is opened. 3487 3488@end table 3489 3490@exitstatus 3491 3492Here are a few examples to illustrate how the 3493@option{--number} (@option{-n}) option works: 3494 3495Notice how, by default, one line may be split onto two or more: 3496 3497@example 3498$ seq -w 6 10 > k; split -n3 k; head xa? 3499==> xaa <== 350006 350107 3502==> xab <== 3503 350408 35050 3506==> xac <== 35079 350810 3509@end example 3510 3511Use the "l/" modifier to suppress that: 3512 3513@example 3514$ seq -w 6 10 > k; split -nl/3 k; head xa? 3515==> xaa <== 351606 351707 3518 3519==> xab <== 352008 352109 3522 3523==> xac <== 352410 3525@end example 3526 3527Use the "r/" modifier to distribute lines in a round-robin fashion: 3528 3529@example 3530$ seq -w 6 10 > k; split -nr/3 k; head xa? 3531==> xaa <== 353206 353309 3534 3535==> xab <== 353607 353710 3538 3539==> xac <== 354008 3541@end example 3542 3543You can also extract just the Kth chunk. 3544This extracts and prints just the 7th "chunk" of 33: 3545 3546@example 3547$ seq 100 > k; split -nl/7/33 k 354820 354921 355022 3551@end example 3552 3553 3554@node csplit invocation 3555@section @command{csplit}: Split a file into context-determined pieces 3556 3557@pindex csplit 3558@cindex context splitting 3559@cindex splitting a file into pieces by context 3560 3561@command{csplit} creates zero or more output files containing sections of 3562@var{input} (standard input if @var{input} is @samp{-}). Synopsis: 3563 3564@example 3565csplit [@var{option}]@dots{} @var{input} @var{pattern}@dots{} 3566@end example 3567 3568The contents of the output files are determined by the @var{pattern} 3569arguments, as detailed below. An error occurs if a @var{pattern} 3570argument refers to a nonexistent line of the input file (e.g., if no 3571remaining line matches a given regular expression). After every 3572@var{pattern} has been matched, any remaining input is copied into one 3573last output file. 3574 3575By default, @command{csplit} prints the number of bytes written to each 3576output file after it has been created. 3577 3578The types of pattern arguments are: 3579 3580@table @samp 3581 3582@item @var{n} 3583Create an output file containing the input up to but not including line 3584@var{n} (a positive integer). If followed by a repeat count, also 3585create an output file containing the next @var{n} lines of the input 3586file once for each repeat. 3587 3588@item /@var{regexp}/[@var{offset}] 3589Create an output file containing the current line up to (but not 3590including) the next line of the input file that contains a match for 3591@var{regexp}. The optional @var{offset} is an integer, that can 3592be preceded by @samp{+} or @samp{-}. 3593If it is given, the input up to (but not including) the 3594matching line plus or minus @var{offset} is put into the output file, 3595and the line after that begins the next section of input. 3596Note lines within a negative offset of a regexp pattern 3597are not matched in subsequent regexp patterns. 3598 3599@item %@var{regexp}%[@var{offset}] 3600Like the previous type, except that it does not create an output 3601file, so that section of the input file is effectively ignored. 3602 3603@item @{@var{repeat-count}@} 3604Repeat the previous pattern @var{repeat-count} additional 3605times. The @var{repeat-count} can either be a positive integer or an 3606asterisk, meaning repeat as many times as necessary until the input is 3607exhausted. 3608 3609@end table 3610 3611The output files' names consist of a prefix (@samp{xx} by default) 3612followed by a suffix. By default, the suffix is an ascending sequence 3613of two-digit decimal numbers from @samp{00} to @samp{99}. In any case, 3614concatenating the output files in sorted order by file name produces the 3615original input file, excluding portions skipped with a %@var{regexp}% 3616pattern or the @option{--suppress-matched} option. 3617 3618By default, if @command{csplit} encounters an error or receives a hangup, 3619interrupt, quit, or terminate signal, it removes any output files 3620that it has created so far before it exits. 3621 3622The program accepts the following options. Also see @ref{Common options}. 3623 3624@table @samp 3625 3626@item -f @var{prefix} 3627@itemx --prefix=@var{prefix} 3628@opindex -f 3629@opindex --prefix 3630@cindex output file name prefix 3631Use @var{prefix} as the output file name prefix. 3632 3633@item -b @var{format} 3634@itemx --suffix-format=@var{format} 3635@opindex -b 3636@opindex --suffix-format 3637@cindex output file name suffix 3638Use @var{format} as the output file name suffix. When this option is 3639specified, the suffix string must include exactly one 3640@code{printf(3)}-style conversion specification, possibly including 3641format specification flags, a field width, a precision specification, 3642or all of these kinds of modifiers. The format letter must convert a 3643binary unsigned integer argument to readable form. The format letters 3644@samp{d} and @samp{i} are aliases for @samp{u}, and the 3645@samp{u}, @samp{o}, @samp{x}, and @samp{X} conversions are allowed. The 3646entire @var{format} is given (with the current output file number) to 3647@code{sprintf(3)} to form the file name suffixes for each of the 3648individual output files in turn. If this option is used, the 3649@option{--digits} option is ignored. 3650 3651@item -n @var{digits} 3652@itemx --digits=@var{digits} 3653@opindex -n 3654@opindex --digits 3655Use output file names containing numbers that are @var{digits} digits 3656long instead of the default 2. 3657 3658@item -k 3659@itemx --keep-files 3660@opindex -k 3661@opindex --keep-files 3662Do not remove output files when errors are encountered. 3663 3664@item --suppress-matched 3665@opindex --suppress-matched 3666Do not output lines matching the specified @var{pattern}. 3667I.e., suppress the boundary line from the start of the second 3668and subsequent splits. 3669 3670@item -z 3671@itemx --elide-empty-files 3672@opindex -z 3673@opindex --elide-empty-files 3674Suppress the generation of zero-length output files. (In cases where 3675the section delimiters of the input file are supposed to mark the first 3676lines of each of the sections, the first output file will generally be a 3677zero-length file unless you use this option.) The output file sequence 3678numbers always run consecutively starting from 0, even when this option 3679is specified. 3680 3681@item -s 3682@itemx -q 3683@itemx --silent 3684@itemx --quiet 3685@opindex -s 3686@opindex -q 3687@opindex --silent 3688@opindex --quiet 3689Do not print counts of output file sizes. 3690 3691@end table 3692 3693@exitstatus 3694 3695Here is an example of its usage. 3696First, create an empty directory for the exercise, 3697and cd into it: 3698 3699@example 3700$ mkdir d && cd d 3701@end example 3702 3703Now, split the sequence of 1..14 on lines that end with 0 or 5: 3704 3705@example 3706$ seq 14 | csplit - '/[05]$/' '@{*@}' 37078 370810 370915 3710@end example 3711 3712Each number printed above is the size of an output 3713file that csplit has just created. 3714List the names of those output files: 3715 3716@example 3717$ ls 3718xx00 xx01 xx02 3719@end example 3720 3721Use @command{head} to show their contents: 3722 3723@example 3724$ head xx* 3725==> xx00 <== 37261 37272 37283 37294 3730 3731==> xx01 <== 37325 37336 37347 37358 37369 3737 3738==> xx02 <== 373910 374011 374112 374213 374314 3744@end example 3745 3746Example of splitting input by empty lines: 3747 3748@example 3749$ csplit --suppress-matched @var{input.txt} '/^$/' '@{*@}' 3750@end example 3751 3752@c 3753@c TODO: "uniq" already supports "--group". 3754@c when it gets the "--key" option, uncomment this example. 3755@c 3756@c Example of splitting input file, based on the value of column 2: 3757@c 3758@c @example 3759@c $ cat @var{input.txt} | 3760@c sort -k2,2 | 3761@c uniq --group -k2,2 | 3762@c csplit -m '/^$/' '@{*@}' 3763@c @end example 3764 3765@node Summarizing files 3766@chapter Summarizing files 3767 3768@cindex summarizing files 3769 3770These commands generate just a few numbers representing entire 3771contents of files. 3772 3773@menu 3774* wc invocation:: Print newline, word, and byte counts. 3775* sum invocation:: Print checksum and block counts. 3776* cksum invocation:: Print CRC checksum and byte counts. 3777* md5sum invocation:: Print or check MD5 digests. 3778* b2sum invocation:: Print or check BLAKE2 digests. 3779* sha1sum invocation:: Print or check SHA-1 digests. 3780* sha2 utilities:: Print or check SHA-2 digests. 3781@end menu 3782 3783 3784@node wc invocation 3785@section @command{wc}: Print newline, word, and byte counts 3786 3787@pindex wc 3788@cindex byte count 3789@cindex character count 3790@cindex word count 3791@cindex line count 3792 3793@command{wc} counts the number of bytes, characters, words, and newlines 3794in each given @var{file}, or standard input if none are given 3795or for a @var{file} of @samp{-}. A word is a nonempty sequence of non white 3796space delimited by white space characters or by start or end of input. 3797Synopsis: 3798 3799@example 3800wc [@var{option}]@dots{} [@var{file}]@dots{} 3801@end example 3802 3803@cindex total counts 3804@command{wc} prints one line of counts for each file, and if the file was 3805given as an argument, it prints the file name following the counts. By default 3806if more than one @var{file} is given, @command{wc} prints a final line 3807containing the cumulative counts, with the file name @file{total}. 3808This @samp{total} line can be controlled with the @option{--total} option, 3809which is a GNU extension. 3810The counts are printed in this order: newlines, words, characters, bytes, 3811maximum line length. 3812Each count is printed right-justified in a field with at least one 3813space between fields so that the numbers and file names normally line 3814up nicely in columns. The width of the count fields varies depending 3815on the inputs, so you should not depend on a particular field width. 3816However, as a GNU extension, if only one count is printed, 3817it is guaranteed to be printed without leading spaces. 3818 3819By default, @command{wc} prints three counts: the newline, words, and byte 3820counts. Options can specify that only certain counts be printed. 3821Options do not undo others previously given, so 3822 3823@example 3824wc --bytes --words 3825@end example 3826 3827@noindent 3828prints both the byte counts and the word counts. 3829 3830With the @option{--max-line-length} option, @command{wc} prints the length 3831of the longest line per file, and if there is more than one file it 3832prints the maximum (not the sum) of those lengths. The line lengths here 3833are measured in screen columns, according to the current locale and 3834assuming tab positions in every 8th column. 3835 3836The program accepts the following options. Also see @ref{Common options}. 3837 3838@table @samp 3839 3840@item -c 3841@itemx --bytes 3842@opindex -c 3843@opindex --bytes 3844Print only the byte counts. 3845 3846@item -m 3847@itemx --chars 3848@opindex -m 3849@opindex --chars 3850Print only the character counts, as per the current locale. 3851Encoding errors are not counted. 3852 3853@item -w 3854@itemx --words 3855@opindex -w 3856@opindex --words 3857Print only the word counts. A word is a nonempty sequence of non white 3858space delimited by white space characters or by start or end of input. 3859The current locale determines which characters are white space. 3860GNU @command{wc} treats encoding errors as non white space. 3861 3862@vindex POSIXLY_CORRECT 3863Unless the environment variable @env{POSIXLY_CORRECT} is set, 3864GNU @command{wc} treats the following Unicode characters as white 3865space even if the current locale does not: U+00A0 NO-BREAK SPACE, 3866U+2007 FIGURE SPACE, U+202F NARROW NO-BREAK SPACE, and U+2060 WORD 3867JOINER. 3868 3869@item -l 3870@itemx --lines 3871@opindex -l 3872@opindex --lines 3873Print only the newline character counts. 3874Note a file without a trailing newline character, 3875will not have that last portion included in the line count. 3876 3877@item -L 3878@itemx --max-line-length 3879@opindex -L 3880@opindex --max-line-length 3881Print only the maximum display widths. 3882Tabs are set at every 8th column. 3883Display widths of wide characters are considered. 3884Non-printable characters are given 0 width. 3885 3886@item --total=@var{when} 3887@opindex --total=@var{when} 3888Control when and how the final line with cumulative counts is printed. 3889@var{when} is one of: 3890@itemize @bullet 3891@item auto 3892@vindex auto @r{total option} 3893- This is the default mode of @command{wc} when no @option{--total} 3894option is specified. Output a total line if more than one @var{file} 3895is specified. 3896@item always 3897@vindex always @r{total option} 3898- Always output a total line, irrespective of the number of files processed. 3899@item only 3900@vindex only @r{total option} 3901- Only output total counts. I.e., don't print individual file counts, 3902suppress any leading spaces, and don't print the @samp{total} word itself, 3903to simplify subsequent processing. 3904@item never 3905@vindex none @r{total option} 3906- Never output a total line. 3907@end itemize 3908 3909@macro filesZeroFromOption{cmd,withTotalOption,subListOutput} 3910@item --files0-from=@var{file} 3911@opindex --files0-from=@var{file} 3912@c This is commented out to avoid a texi2dvi failure. 3913@c texi2dvi (GNU Texinfo 4.11) 1.104 3914@c @cindex including files from @command{\cmd\} 3915Disallow processing files named on the command line, and instead process 3916those named in file @var{file}; each name being terminated by a zero byte 3917(ASCII NUL). 3918This is useful \withTotalOption\ 3919when the list of file names is so long that it may exceed a command line 3920length limitation. 3921In such cases, running @command{\cmd\} via @command{xargs} is undesirable 3922because it splits the list into pieces and makes @command{\cmd\} print 3923\subListOutput\ for each sublist rather than for the entire list. 3924One way to produce a list of ASCII NUL terminated file 3925names is with GNU 3926@command{find}, using its @option{-print0} predicate. 3927If @var{file} is @samp{-} then the ASCII NUL terminated 3928file names are read from standard input. 3929@end macro 3930@filesZeroFromOption{wc,,a total} 3931 3932For example, to find the length of the longest line in any @file{.c} or 3933@file{.h} file in the current hierarchy, do this: 3934 3935@example 3936find . -name '*.[ch]' -print0 | 3937 wc -L --files0-from=- | tail -n1 3938@end example 3939 3940@end table 3941 3942@exitstatus 3943 3944 3945@node sum invocation 3946@section @command{sum}: Print checksum and block counts 3947 3948@pindex sum 3949@cindex 16-bit checksum 3950@cindex checksum, 16-bit 3951 3952@command{sum} computes a 16-bit checksum for each given @var{file}, or 3953standard input if none are given or for a @var{file} of @samp{-}. Synopsis: 3954 3955@example 3956sum [@var{option}]@dots{} [@var{file}]@dots{} 3957@end example 3958 3959@command{sum} prints the checksum for each @var{file} followed by the 3960number of blocks in the file (rounded up). If at least one @var{file} 3961is given, file names are also printed. 3962 3963By default, GNU @command{sum} computes checksums using an algorithm 3964compatible with BSD @command{sum} and prints file sizes in units of 39651024-byte blocks. 3966 3967The program accepts the following options. Also see @ref{Common options}. 3968 3969@table @samp 3970 3971@item -r 3972@opindex -r 3973@cindex BSD @command{sum} 3974Use the default (BSD compatible) algorithm. This option is included for 3975compatibility with the System V @command{sum}. Unless @option{-s} was also 3976given, it has no effect. 3977 3978@item -s 3979@itemx --sysv 3980@opindex -s 3981@opindex --sysv 3982@cindex System V @command{sum} 3983Compute checksums using an algorithm compatible with System V 3984@command{sum}'s default, and print file sizes in units of 512-byte blocks. 3985 3986@end table 3987 3988@command{sum} is provided for compatibility; the @command{cksum} program (see 3989next section) is preferable in new applications. 3990 3991@exitstatus 3992 3993 3994@node cksum invocation 3995@section @command{cksum}: Print and verify file checksums 3996 3997@pindex cksum 3998@cindex cyclic redundancy check 3999@cindex CRC checksum 4000@cindex 32-bit checksum 4001@cindex checksum, 32-bit 4002@cindex digest 4003 4004@command{cksum} by default computes a 32-bit cyclic redundancy check (CRC) 4005checksum for each given @var{file}, or standard input if none are given or for 4006a @var{file} of @samp{-}. 4007 4008cksum also supports the @option{-a/--algorithm} option to select the 4009digest algorithm to use. @command{cksum} is the preferred interface 4010to these digests, subsuming the other standalone checksumming utilities, 4011which can be emulated using @code{cksum -a md5 --untagged "$@@"} etc. 4012Synopsis: 4013 4014@example 4015cksum [@var{option}]@dots{} [@var{file}]@dots{} 4016@end example 4017 4018@command{cksum} is typically used to ensure that files have not been corrupted, 4019by comparing the @command{cksum} output for the received files with the 4020@command{cksum} output for the original files (typically given in the 4021distribution). 4022 4023@menu 4024* cksum output modes:: Legacy and non Legacy output formats 4025* cksum general options:: Options supported only by cksum 4026* cksum common options:: Options supported also by standalone utilities 4027@end menu 4028 4029@node cksum output modes 4030@subsection cksum output modes 4031 4032@table @asis 4033 4034@item Legacy output format 4035@command{cksum} by default prints the POSIX standard CRC checksum 4036for each file along with the number of bytes in the file, 4037and the file name unless no arguments were given. 4038The 32-bit CRC used is based on the polynomial used 4039for CRC error checking in the ISO/IEC 8802-3:1996 standard (Ethernet). 4040Similar output formats are used for the other legacy checksums 4041selectable with @option{--algorithm=sysv} or @option{--algorithm=bsd}, 4042detailed at @ref{sum invocation}. 4043 4044@item Tagged output format 4045With the @option{--algorithm} option selecting non legacy checksums, 4046the @command{cksum} command defaults to output of the form: 4047@example 4048@var{digest_name} (@var{file name}) = @var{digest} 4049@end example 4050Note the standalone checksum utilities can select this output 4051mode by using the @option{--tag} option. 4052 4053@item Untagged output format 4054With the @option{--untagged} option and the @option{--algorithm} option 4055selecting non legacy checksums, the following output format is used. 4056Note this is the default output format of the standalone checksum utilities. 4057For each @var{file}, we print the checksum, a space, a flag indicating 4058binary or text input mode, and the file name. 4059Binary mode is indicated with @samp{*}, text mode with @samp{ } (space). 4060Binary mode is the default on systems where it's significant, 4061otherwise text mode is the default. 4062 4063@end table 4064 4065Note without @option{--zero}, and with non legacy output formats, 4066if @var{file} contains a backslash, newline, or carriage return, 4067the line is started with a backslash, and each problematic character 4068in the file name is escaped with a backslash, making the output unambiguous 4069even in the presence of arbitrary file names. 4070Since the backslash character itself is escaped, any other backslash 4071escape sequences are reserved for future use. 4072 4073@node cksum general options 4074@subsection cksum general options 4075 4076@table @samp 4077 4078@item -a 4079@itemx --algorithm 4080@opindex -a 4081@opindex --algorithm 4082@cindex digest algorithm 4083Compute checksums using the specified digest algorithm. 4084 4085Supported legacy checksums (which are not supported by @option{--check}): 4086@example 4087@samp{sysv} equivalent to @command{sum -s} 4088@samp{bsd} equivalent to @command{sum -r} 4089@samp{crc} equivalent to @command{cksum} (the default) 4090@end example 4091 4092Supported more modern digest algorithms are: 4093@example 4094@samp{md5} equivalent to @command{md5sum} 4095@samp{sha1} equivalent to @command{sha1sum} 4096@samp{sha224} equivalent to @command{sha224sum} 4097@samp{sha256} equivalent to @command{sha256sum} 4098@samp{sha384} equivalent to @command{sha384sum} 4099@samp{sha512} equivalent to @command{sha512sum} 4100@samp{blake2b} equivalent to @command{b2sum} 4101@samp{sm3} only available through @command{cksum} 4102@end example 4103 4104@item --base64 4105@opindex --base64 4106@cindex base64 checksum encoding 4107Print base64-encoded digests not hexadecimal. 4108This option is ignored with @option{--check}. 4109The format conforms to 4110@uref{https://datatracker.ietf.org/doc/html/rfc4648#section-4, RFC 4648#4}. 4111 4112Note that each base64-encoded digest has zero, one or two trailing padding 4113(@samp{=}) bytes. The length of that padding is the checksum-bit-length 4114modulo 3, and the @option{--check} parser requires precisely the same 4115input digest string as what is output. I.e., removing or adding any 4116@samp{=} padding renders a digest non-matching. 4117 4118@item --debug 4119@opindex --debug 4120Output extra information to stderr, like the checksum implementation being used. 4121 4122@macro cksumLengthOption 4123@item -l 4124@itemx --length 4125@opindex -l 4126@opindex --length 4127@cindex BLAKE2 hash length 4128Change (shorten) the default digest length. 4129This is specified in bits and thus must be a multiple of 8. 4130This option is ignored when @option{--check} is specified, 4131as the length is automatically determined when checking. 4132@end macro 4133@cksumLengthOption 4134 4135@item --raw 4136@opindex --raw 4137@cindex raw binary checksum 4138Print only the unencoded raw binary digest for a single input. 4139Do not output the file name or anything else. 4140Use network byte order (big endian) where applicable: 4141for @samp{bsd}, @samp{crc}, and @samp{sysv}. 4142This option works only with a single input. 4143Unlike other output formats, @command{cksum} provides no way to 4144@option{--check} a @option{--raw} checksum. 4145 4146@item --untagged 4147@opindex --untagged 4148Output using the original Coreutils format used by the other 4149standalone checksum utilities like @command{md5sum} for example. 4150This format has the checksum at the start of the line, and may be 4151more amenable to further processing by other utilities, 4152especially in combination with the @option{--zero} option. 4153Note this does not identify the digest algorithm used for the checksum. 4154@xref{cksum output modes} for details of this format. 4155@end table 4156 4157@node cksum common options 4158@subsection cksum common options 4159 4160@table @samp 4161 4162@item -b 4163@itemx --binary 4164@opindex -b 4165@opindex --binary 4166@cindex binary input files 4167Note this option is not supported by the @command{cksum} command, 4168as it operates in binary mode exclusively. 4169Treat each input file as binary, by reading it in binary mode and 4170outputting a @samp{*} flag. This is the inverse of @option{--text}. 4171On systems like GNU that do not distinguish between binary 4172and text files, this option merely flags each input mode as binary: 4173the checksum is unaffected. This option is the default on systems 4174like MS-DOS that distinguish between binary and text files, except 4175for reading standard input when standard input is a terminal. 4176 4177@item -c 4178@itemx --check 4179Read file names and checksum information (not data) from each 4180@var{file} (or from standard input if no @var{file} was specified) and report 4181whether the checksums match the contents of the named files. 4182The input to this mode is usually the output of 4183a prior, checksum-generating run of the command. 4184 4185Three input formats are supported. Either the default output 4186format described above, the @option{--tag} output format, 4187or the BSD reversed mode format which is similar to the default mode, 4188but doesn't use a character to distinguish binary and text modes. 4189 4190For the @command{cksum} command, the @option{--check} option 4191supports auto-detecting the digest algorithm to use, 4192when presented with checksum information in the @option{--tag} output format. 4193 4194Also for the @command{cksum} command, the @option{--check} option 4195auto-detects the digest encoding, accepting both standard hexadecimal 4196checksums and those generated via @command{cksum} with its 4197@option{--base64} option. 4198 4199Output with @option{--zero} enabled is not supported by @option{--check}. 4200@sp 1 4201For each such line, @command{cksum} reads the named file and computes its 4202checksum. Then, if the computed message digest does not match the 4203one on the line with the file name, the file is noted as having 4204failed the test. Otherwise, the file passes the test. 4205By default, for each valid line, one line is written to standard 4206output indicating whether the named file passed the test. 4207After all checks have been performed, if there were any failures, 4208a warning is issued to standard error. 4209Use the @option{--status} option to inhibit that output. 4210If any listed file cannot be opened or read, if any valid line has 4211a checksum inconsistent with the associated file, or if no valid 4212line is found, @command{cksum} exits with nonzero status. Otherwise, 4213it exits successfully. 4214Note the @command{cksum} command doesn't support @option{--check} 4215with the older @samp{sysv}, @samp{bsd}, or @samp{crc} algorithms. 4216 4217@item --ignore-missing 4218@opindex --ignore-missing 4219@cindex verifying checksums 4220This option is useful only when verifying checksums. 4221When verifying checksums, don't fail or report any status 4222for missing files. This is useful when verifying a subset 4223of downloaded files given a larger list of checksums. 4224 4225@item --quiet 4226@opindex --quiet 4227@cindex verifying checksums 4228This option is useful only when verifying checksums. 4229When verifying checksums, don't generate an 'OK' message per successfully 4230checked file. Files that fail the verification are reported in the 4231default one-line-per-file format. If there is any checksum mismatch, 4232print a warning summarizing the failures to standard error. 4233 4234@item --status 4235@opindex --status 4236@cindex verifying checksums 4237This option is useful only when verifying checksums. 4238When verifying checksums, don't generate the default one-line-per-file 4239diagnostic and don't output the warning summarizing any failures. 4240Failures to open or read a file still evoke individual diagnostics to 4241standard error. 4242If all listed files are readable and are consistent with the associated 4243checksums, exit successfully. Otherwise exit with a status code 4244indicating there was a failure. 4245 4246@item --tag 4247@opindex --tag 4248@cindex BSD output 4249Output BSD style checksums, which indicate the checksum algorithm used. 4250As a GNU extension, if @option{--zero} is not used, file names with problematic 4251characters are escaped as described above, using the same escaping indicator of 4252@samp{\} at the start of the line, as used with the other output format. 4253The @option{--tag} option implies binary mode, and is disallowed with 4254@option{--text} mode as supporting that would unnecessarily complicate 4255the output format, while providing little benefit. 4256@xref{cksum output modes} for details of this format. 4257The @command{cksum} command, uses @option{--tag} as its default output format. 4258 4259@item -t 4260@itemx --text 4261@opindex -t 4262@opindex --text 4263@cindex text input files 4264Note this option is not supported by the @command{cksum} command. 4265Treat each input file as text, by reading it in text mode and 4266outputting a @samp{ } flag. This is the inverse of @option{--binary}. 4267This option is the default on systems like GNU that do not 4268distinguish between binary and text files. On other systems, it is 4269the default for reading standard input when standard input is a 4270terminal. This mode is never defaulted to if @option{--tag} is used. 4271 4272@item -w 4273@itemx --warn 4274@opindex -w 4275@opindex --warn 4276@cindex verifying checksums 4277When verifying checksums, warn about improperly formatted checksum lines. 4278This option is useful only if all but a few lines in the checked input 4279are valid. 4280 4281@item --strict 4282@opindex --strict 4283@cindex verifying checksums 4284When verifying checksums, 4285if one or more input line is invalid, 4286exit nonzero after all warnings have been issued. 4287 4288@optZero 4289Also file name escaping is not used. 4290@end table 4291 4292@node md5sum invocation 4293@section @command{md5sum}: Print or check MD5 digests 4294 4295@pindex md5sum 4296@cindex MD5 4297@cindex 128-bit checksum 4298@cindex checksum, 128-bit 4299@cindex fingerprint, 128-bit 4300@cindex message-digest, 128-bit 4301 4302@command{md5sum} computes a 128-bit checksum (or @dfn{fingerprint} or 4303@dfn{message-digest}) for each specified @var{file}. 4304 4305@macro weakHash{hash} 4306Note: The \hash\ digest is more reliable than a simple CRC (provided by 4307the @command{cksum} command) for detecting accidental file corruption, 4308as the chances of accidentally having two files with identical \hash\ 4309are vanishingly small. However, it should not be considered secure 4310against malicious tampering: although finding a file with a given \hash\ 4311fingerprint is considered infeasible at the moment, it is known how 4312to modify certain files, including digital certificates, so that they 4313appear valid when signed with an \hash\ digest. For more secure hashes, 4314consider using SHA-2, or the newer @command{b2sum} command. 4315@xref{sha2 utilities}. @xref{b2sum invocation}. 4316@end macro 4317@weakHash{MD5} 4318 4319@macro checksumUsage{command} 4320If a @var{file} is specified as @samp{-} or if no files are given 4321@command{\command\} computes the checksum for the standard input. 4322@command{\command\} can also determine whether a file and checksum are 4323consistent. Synopsis: 4324 4325@example 4326\command\ [@var{option}]@dots{} [@var{file}]@dots{} 4327@end example 4328 4329@command{\command\} uses the @samp{Untagged output format} 4330for each specified file, as described at @ref{cksum output modes}. 4331 4332The program accepts @ref{cksum common options}. Also see @ref{Common options}. 4333@end macro 4334@checksumUsage{md5sum} 4335 4336@exitstatus 4337 4338 4339@node b2sum invocation 4340@section @command{b2sum}: Print or check BLAKE2 digests 4341 4342@pindex b2sum 4343@cindex BLAKE2 4344@cindex 512-bit checksum 4345@cindex checksum, 512-bit 4346@cindex fingerprint, 512-bit 4347@cindex message-digest, 512-bit 4348 4349@command{b2sum} computes a 512-bit checksum for each specified 4350@var{file}. 4351 4352@checksumUsage{b2sum} 4353 4354In addition @command{b2sum} supports the following options. 4355 4356@table @samp 4357@cksumLengthOption 4358@end table 4359 4360 4361@node sha1sum invocation 4362@section @command{sha1sum}: Print or check SHA-1 digests 4363 4364@pindex sha1sum 4365@cindex SHA-1 4366@cindex 160-bit checksum 4367@cindex checksum, 160-bit 4368@cindex fingerprint, 160-bit 4369@cindex message-digest, 160-bit 4370 4371@command{sha1sum} computes a 160-bit checksum for each specified @var{file}. 4372 4373@weakHash{SHA-1} 4374 4375@checksumUsage{sha1sum} 4376 4377@node sha2 utilities 4378@section sha2 utilities: Print or check SHA-2 digests 4379 4380@pindex sha224sum 4381@pindex sha256sum 4382@pindex sha384sum 4383@pindex sha512sum 4384@cindex SHA-2 4385@cindex 224-bit checksum 4386@cindex 256-bit checksum 4387@cindex 384-bit checksum 4388@cindex 512-bit checksum 4389@cindex checksum, 224-bit 4390@cindex checksum, 256-bit 4391@cindex checksum, 384-bit 4392@cindex checksum, 512-bit 4393@cindex fingerprint, 224-bit 4394@cindex fingerprint, 256-bit 4395@cindex fingerprint, 384-bit 4396@cindex fingerprint, 512-bit 4397@cindex message-digest, 224-bit 4398@cindex message-digest, 256-bit 4399@cindex message-digest, 384-bit 4400@cindex message-digest, 512-bit 4401 4402The commands @command{sha224sum}, @command{sha256sum}, 4403@command{sha384sum} and @command{sha512sum} compute checksums of 4404various lengths (respectively 224, 256, 384 and 512 bits), 4405collectively known as the SHA-2 hashes. 4406 4407@checksumUsage{sha???sum} 4408 4409 4410@node Operating on sorted files 4411@chapter Operating on sorted files 4412 4413@cindex operating on sorted files 4414@cindex sorted files, operations on 4415 4416These commands work with (or produce) sorted files. 4417 4418@menu 4419* sort invocation:: Sort text files. 4420* shuf invocation:: Shuffle text files. 4421* uniq invocation:: Uniquify files. 4422* comm invocation:: Compare two sorted files line by line. 4423* ptx invocation:: Produce a permuted index of file contents. 4424* tsort invocation:: Topological sort. 4425@end menu 4426 4427 4428@node sort invocation 4429@section @command{sort}: Sort text files 4430 4431@pindex sort 4432@cindex sorting files 4433 4434@command{sort} sorts, merges, or compares all the lines from the given 4435files, or standard input if none are given or for a @var{file} of 4436@samp{-}. By default, @command{sort} writes the results to standard 4437output. Synopsis: 4438 4439@example 4440sort [@var{option}]@dots{} [@var{file}]@dots{} 4441@end example 4442 4443@cindex sort stability 4444@cindex sort's last-resort comparison 4445Many options affect how @command{sort} compares lines; if the results 4446are unexpected, try the @option{--debug} option to see what happened. 4447A pair of lines is compared as follows: 4448@command{sort} compares each pair of fields (see @option{--key}), in the 4449order specified on the command line, according to the associated 4450ordering options, until a difference is found or no fields are left. 4451If no key fields are specified, @command{sort} uses a default key of 4452the entire line. Finally, as a last resort when all keys compare 4453equal, @command{sort} compares entire lines as if no ordering options 4454other than @option{--reverse} (@option{-r}) were specified. The 4455@option{--stable} (@option{-s}) option disables this @dfn{last-resort 4456comparison} so that lines in which all fields compare equal are left 4457in their original relative order. The @option{--unique} 4458(@option{-u}) option also disables the last-resort comparison. 4459@vindex LC_ALL 4460@vindex LC_COLLATE 4461 4462Unless otherwise specified, all comparisons use the character collating 4463sequence specified by the @env{LC_COLLATE} locale.@footnote{If you 4464use a non-POSIX locale (e.g., by setting @env{LC_ALL} 4465to @samp{en_US}), then @command{sort} may produce output that is sorted 4466differently than you're accustomed to. In that case, set the @env{LC_ALL} 4467environment variable to @samp{C}@. Note that setting only @env{LC_COLLATE} 4468has two problems. First, it is ineffective if @env{LC_ALL} is also set. 4469Second, it has undefined behavior if @env{LC_CTYPE} (or @env{LANG}, if 4470@env{LC_CTYPE} is unset) is set to an incompatible value. For example, 4471you get undefined behavior if @env{LC_CTYPE} is @code{ja_JP.PCK} but 4472@env{LC_COLLATE} is @code{en_US.UTF-8}.} 4473A line's trailing newline is not part of the line for comparison 4474purposes. If the final byte of an input file is not a newline, GNU 4475@command{sort} silently supplies one. GNU @command{sort} (as 4476specified for all GNU utilities) has no limit on input line length or 4477restrictions on bytes allowed within lines. 4478 4479@command{sort} has three modes of operation: sort (the default), merge, 4480and check for order. The following options change the operation 4481mode: 4482 4483@table @samp 4484 4485@item -c 4486@itemx --check 4487@itemx --check=diagnose-first 4488@opindex -c 4489@opindex --check 4490@cindex checking whether a file is sorted 4491Check whether the given file is already sorted: if it is not all 4492sorted, print a diagnostic containing the first out-of-order line and 4493exit with a status of 1. 4494Otherwise, exit successfully. 4495At most one input file can be given. 4496 4497@item -C 4498@itemx --check=quiet 4499@itemx --check=silent 4500@opindex -c 4501@opindex --check 4502@cindex checking whether a file is sorted 4503Exit successfully if the given file is already sorted, and 4504exit with status 1 otherwise. 4505At most one input file can be given. 4506This is like @option{-c}, except it does not print a diagnostic. 4507 4508@item -m 4509@itemx --merge 4510@opindex -m 4511@opindex --merge 4512@cindex merging sorted files 4513Merge the given files by sorting them as a group. Each input file must 4514always be individually sorted. It always works to sort instead of 4515merge; merging is provided because it is faster, in the case where it 4516works. 4517 4518@end table 4519 4520@cindex exit status of @command{sort} 4521Exit status: 4522 4523@display 45240 if no error occurred 45251 if invoked with @option{-c} or @option{-C} and the input is not sorted 45262 if an error occurred 4527@end display 4528 4529@vindex TMPDIR 4530If the environment variable @env{TMPDIR} is set, @command{sort} uses its 4531value as the directory for temporary files instead of @file{/tmp}. The 4532@option{--temporary-directory} (@option{-T}) option in turn overrides 4533the environment variable. 4534 4535The following options affect the ordering of output lines. They may be 4536specified globally or as part of a specific key field. If no key 4537fields are specified, global options apply to comparison of entire 4538lines; otherwise the global options are inherited by key fields that do 4539not specify any special options of their own. In pre-POSIX 4540versions of @command{sort}, global options affect only later key fields, 4541so portable shell scripts should specify global options first. 4542 4543@table @samp 4544 4545@item -b 4546@itemx --ignore-leading-blanks 4547@opindex -b 4548@opindex --ignore-leading-blanks 4549@cindex blanks, ignoring leading 4550@vindex LC_CTYPE 4551Ignore leading blanks when finding sort keys in each line. 4552By default a blank is a space or a tab, but the @env{LC_CTYPE} locale 4553can change this. Note blanks may be ignored by your locale's collating 4554rules, but without this option they will be significant for character 4555positions specified in keys with the @option{-k} option. 4556 4557@item -d 4558@itemx --dictionary-order 4559@opindex -d 4560@opindex --dictionary-order 4561@cindex dictionary order 4562@cindex phone directory order 4563@cindex telephone directory order 4564@vindex LC_CTYPE 4565Sort in @dfn{phone directory} order: ignore all characters except 4566letters, digits and blanks when sorting. 4567By default letters and digits are those of ASCII and a blank 4568is a space or a tab, but the @env{LC_CTYPE} locale can change this. 4569 4570@item -f 4571@itemx --ignore-case 4572@opindex -f 4573@opindex --ignore-case 4574@cindex ignoring case 4575@cindex case folding 4576@vindex LC_CTYPE 4577Fold lowercase characters into the equivalent uppercase characters when 4578comparing so that, for example, @samp{b} and @samp{B} sort as equal. 4579The @env{LC_CTYPE} locale determines character types. 4580When used with @option{--unique} those lower case equivalent lines are 4581thrown away. (There is currently no way to throw away the upper case 4582equivalent instead. (Any @option{--reverse} given would only affect 4583the final result, after the throwing away.)) 4584 4585@item -g 4586@itemx --general-numeric-sort 4587@itemx --sort=general-numeric 4588@opindex -g 4589@opindex --general-numeric-sort 4590@opindex --sort 4591@cindex general numeric sort 4592@vindex LC_NUMERIC 4593Sort numerically, converting a prefix of each line to a long 4594double-precision floating point number. @xref{Floating point}. 4595Do not report overflow, underflow, or conversion errors. 4596Use the following collating sequence: 4597 4598@itemize @bullet 4599@item 4600Lines that do not start with numbers (all considered to be equal). 4601@item 4602NaNs (``Not a Number'' values, in IEEE floating point arithmetic) 4603in a consistent but machine-dependent order. 4604@item 4605Minus infinity. 4606@item 4607Finite numbers in ascending numeric order (with @math{-0} and @math{+0} equal). 4608@item 4609Plus infinity. 4610@end itemize 4611 4612Use this option only if there is no alternative; it is much slower than 4613@option{--numeric-sort} (@option{-n}) and it can lose information when 4614converting to floating point. 4615 4616You can use this option to sort hexadecimal numbers prefixed with 4617@samp{0x} or @samp{0X}, where those numbers are not fixed width, 4618or of varying case. However for hex numbers of consistent case, 4619and left padded with @samp{0} to a consistent width, a standard 4620lexicographic sort will be faster. 4621 4622@item -h 4623@itemx --human-numeric-sort 4624@itemx --sort=human-numeric 4625@opindex -h 4626@opindex --human-numeric-sort 4627@opindex --sort 4628@cindex human numeric sort 4629@vindex LC_NUMERIC 4630Sort numerically, first by numeric sign (negative, zero, or positive); 4631then by SI suffix (either empty, or @samp{k} or @samp{K}, or 4632one of @samp{MGTPEZYRQ}, in that order; @pxref{Block size}); and finally 4633by numeric value. For example, @samp{1023M} sorts before @samp{1G} 4634because @samp{M} (mega) precedes @samp{G} (giga) as an SI 4635suffix. This option sorts values that are consistently scaled to the 4636nearest suffix, regardless of whether suffixes denote powers of 1000 4637or 1024, and it therefore sorts the output of any single invocation of 4638the @command{df}, @command{du}, or @command{ls} commands that are 4639invoked with their @option{--human-readable} or @option{--si} options. 4640The syntax for numbers is the same as for the @option{--numeric-sort} 4641option; the SI suffix must immediately follow the number. 4642Note also the @command{numfmt} command, which can be used to reformat 4643numbers to human format @emph{after} the sort, thus often allowing 4644sort to operate on more accurate numbers. 4645 4646@item -i 4647@itemx --ignore-nonprinting 4648@opindex -i 4649@opindex --ignore-nonprinting 4650@cindex nonprinting characters, ignoring 4651@cindex unprintable characters, ignoring 4652@vindex LC_CTYPE 4653Ignore nonprinting characters. 4654The @env{LC_CTYPE} locale determines character types. 4655This option has no effect if the stronger @option{--dictionary-order} 4656(@option{-d}) option is also given. 4657 4658@item -M 4659@itemx --month-sort 4660@itemx --sort=month 4661@opindex -M 4662@opindex --month-sort 4663@opindex --sort 4664@cindex months, sorting by 4665@vindex LC_TIME 4666An initial string, consisting of any amount of blanks, followed 4667by a month name abbreviation, is folded to UPPER case and 4668compared in the order @samp{JAN} < @samp{FEB} < @dots{} < @samp{DEC}@. 4669Invalid names compare low to valid names. The @env{LC_TIME} locale 4670category determines the month spellings. 4671By default a blank is a space or a tab, but the @env{LC_CTYPE} locale 4672can change this. 4673 4674@item -n 4675@itemx --numeric-sort 4676@itemx --sort=numeric 4677@opindex -n 4678@opindex --numeric-sort 4679@opindex --sort 4680@cindex numeric sort 4681@vindex LC_CTYPE 4682@vindex LC_NUMERIC 4683Sort numerically. The number begins each line and consists 4684of optional blanks, an optional @samp{-} sign, and zero or more 4685digits possibly separated by thousands separators, optionally followed 4686by a decimal-point character and zero or more digits. An empty 4687number is treated as @samp{0}. Signs on zeros and leading zeros do 4688not affect ordering. 4689 4690Comparison is exact; there is no rounding error. 4691 4692The @env{LC_CTYPE} locale specifies which characters are blanks and 4693the @env{LC_NUMERIC} locale specifies the thousands separator and 4694decimal-point character. In the C locale, spaces and tabs are blanks, 4695there is no thousands separator, and @samp{.} is the decimal point. 4696 4697Neither a leading @samp{+} nor exponential notation is recognized. 4698To compare such strings numerically, use the 4699@option{--general-numeric-sort} (@option{-g}) option. 4700 4701@item -V 4702@itemx --version-sort 4703@opindex -V 4704@opindex --version-sort 4705@cindex version number sort 4706Sort by version name and number. It behaves like a standard sort, 4707except that each sequence of decimal digits is treated numerically 4708as an index/version number. (@xref{Version sort ordering}.) 4709 4710@item -r 4711@itemx --reverse 4712@opindex -r 4713@opindex --reverse 4714@cindex reverse sorting 4715Reverse the result of comparison, so that lines with greater key values 4716appear earlier in the output instead of later. 4717 4718@item -R 4719@itemx --random-sort 4720@itemx --sort=random 4721@opindex -R 4722@opindex --random-sort 4723@opindex --sort 4724@cindex random sort 4725Sort by hashing the input keys and then sorting the hash values. 4726Choose the hash function at random, ensuring that it is free of 4727collisions so that differing keys have differing hash values. This is 4728like a random permutation of the inputs (@pxref{shuf invocation}), 4729except that keys with the same value sort together. 4730 4731If multiple random sort fields are specified, the same random hash 4732function is used for all fields. To use different random hash 4733functions for different fields, you can invoke @command{sort} more 4734than once. 4735 4736The choice of hash function is affected by the 4737@option{--random-source} option. 4738 4739@end table 4740 4741Other options are: 4742 4743@table @samp 4744 4745@item --compress-program=@var{prog} 4746Compress any temporary files with the program @var{prog}. 4747 4748With no arguments, @var{prog} must compress standard input to standard 4749output, and when given the @option{-d} option it must decompress 4750standard input to standard output. 4751 4752Terminate with an error if @var{prog} exits with nonzero status. 4753 4754White space and the backslash character should not appear in 4755@var{prog}; they are reserved for future use. 4756 4757@filesZeroFromOption{sort,,sorted output} 4758 4759@item -k @var{pos1}[,@var{pos2}] 4760@itemx --key=@var{pos1}[,@var{pos2}] 4761@opindex -k 4762@opindex --key 4763@cindex sort field 4764Specify a sort field that consists of the part of the line between 4765@var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is 4766omitted), @emph{inclusive}. 4767 4768In its simplest form @var{pos} specifies a field number (starting with 1), 4769with fields being separated by runs of blank characters, and by default 4770those blanks being included in the comparison at the start of each field. 4771To adjust the handling of blank characters see the @option{-b} and 4772@option{-t} options. 4773 4774More generally, 4775each @var{pos} has the form @samp{@var{f}[.@var{c}][@var{opts}]}, 4776where @var{f} is the number of the field to use, and @var{c} is the number 4777of the first character from the beginning of the field. Fields and character 4778positions are numbered starting with 1; a character position of zero in 4779@var{pos2} indicates the field's last character. If @samp{.@var{c}} is 4780omitted from @var{pos1}, it defaults to 1 (the beginning of the field); 4781if omitted from @var{pos2}, it defaults to 0 (the end of the field). 4782@var{opts} are ordering options, allowing individual keys to be sorted 4783according to different rules; see below for details. Keys can span 4784multiple fields. 4785 4786Example: To sort on the second field, use @option{--key=2,2} 4787(@option{-k 2,2}). See below for more notes on keys and more examples. 4788See also the @option{--debug} option to help determine the part 4789of the line being used in the sort. 4790 4791@item --debug 4792Highlight the portion of each line used for sorting. 4793Also issue warnings about questionable usage to standard error. 4794 4795@item --batch-size=@var{nmerge} 4796@opindex --batch-size 4797@cindex number of inputs to merge, nmerge 4798Merge at most @var{nmerge} inputs at once. 4799 4800When @command{sort} has to merge more than @var{nmerge} inputs, 4801it merges them in groups of @var{nmerge}, saving the result in 4802a temporary file, which is then used as an input in a subsequent merge. 4803 4804A large value of @var{nmerge} may improve merge performance and decrease 4805temporary storage utilization at the expense of increased memory usage 4806and I/O@. Conversely a small value of @var{nmerge} may reduce memory 4807requirements and I/O at the expense of temporary storage consumption and 4808merge performance. 4809 4810The value of @var{nmerge} must be at least 2. The default value is 4811currently 16, but this is implementation-dependent and may change in 4812the future. 4813 4814The value of @var{nmerge} may be bounded by a resource limit for open 4815file descriptors. The commands @samp{ulimit -n} or @samp{getconf 4816OPEN_MAX} may display limits for your systems; these limits may be 4817modified further if your program already has some files open, or if 4818the operating system has other limits on the number of open files. If 4819the value of @var{nmerge} exceeds the resource limit, @command{sort} 4820silently uses a smaller value. 4821 4822@item -o @var{output-file} 4823@itemx --output=@var{output-file} 4824@opindex -o 4825@opindex --output 4826@cindex overwriting of input, allowed 4827Write output to @var{output-file} instead of standard output. 4828Normally, @command{sort} reads all input before opening 4829@var{output-file}, so you can sort a file in place by using 4830commands like @code{sort -o F F} and @code{cat F | sort -o F}@. 4831However, it is often safer to output to an otherwise-unused file, as 4832data may be lost if the system crashes or @command{sort} encounters 4833an I/O or other serious error while a file is being sorted in place. 4834Also, @command{sort} with @option{--merge} (@option{-m}) can open 4835the output file before reading all input, so a command like @code{cat 4836F | sort -m -o F - G} is not safe as @command{sort} might start 4837writing @file{F} before @command{cat} is done reading it. 4838 4839@vindex POSIXLY_CORRECT 4840On newer systems, @option{-o} cannot appear after an input file if 4841@env{POSIXLY_CORRECT} is set, e.g., @samp{sort F -o F}@. Portable 4842scripts should specify @option{-o @var{output-file}} before any input 4843files. 4844 4845@item --random-source=@var{file} 4846@opindex --random-source 4847@cindex random source for sorting 4848Use @var{file} as a source of random data used to determine which 4849random hash function to use with the @option{-R} option. @xref{Random 4850sources}. 4851 4852@item -s 4853@itemx --stable 4854@opindex -s 4855@opindex --stable 4856@cindex sort stability 4857@cindex sort's last-resort comparison 4858 4859Make @command{sort} stable by disabling its last-resort comparison. 4860This option has no effect if no fields or global ordering options 4861other than @option{--reverse} (@option{-r}) are specified. 4862 4863@item -S @var{size} 4864@itemx --buffer-size=@var{size} 4865@opindex -S 4866@opindex --buffer-size 4867@cindex size for main memory sorting 4868Use a main-memory sort buffer of the given @var{size}. By default, 4869@var{size} is in units of 1024 bytes. Appending @samp{%} causes 4870@var{size} to be interpreted as a percentage of physical memory. 4871Appending @samp{K} multiplies @var{size} by 1024 (the default), 4872@samp{M} by 1,048,576, @samp{G} by 1,073,741,824, and so on for 4873@samp{T}, @samp{P}, @samp{E}, @samp{Z}, @samp{Y}, @samp{R}, and @samp{Q}@. 4874Appending 4875@samp{b} causes @var{size} to be interpreted as a byte count, with no 4876multiplication. 4877 4878This option can improve the performance of @command{sort} by causing it 4879to start with a larger or smaller sort buffer than the default. 4880However, this option affects only the initial buffer size. The buffer 4881grows beyond @var{size} if @command{sort} encounters input lines larger 4882than @var{size}. 4883 4884@item -t @var{separator} 4885@itemx --field-separator=@var{separator} 4886@opindex -t 4887@opindex --field-separator 4888@cindex field separator character 4889Use character @var{separator} as the field separator when finding the 4890sort keys in each line. By default, fields are separated by the empty 4891string between a non-blank character and a blank character. 4892By default a blank is a space or a tab, but the @env{LC_CTYPE} locale 4893can change this. 4894 4895That is, given the input line @w{@samp{ foo bar}}, @command{sort} breaks it 4896into fields @w{@samp{ foo}} and @w{@samp{ bar}}. The field separator is 4897not considered to be part of either the field preceding or the field 4898following, so with @samp{sort @w{-t " "}} the same input line has 4899three fields: an empty field, @samp{foo}, and @samp{bar}. 4900However, fields that extend to the end of the line, 4901as @option{-k 2}, or fields consisting of a range, as @option{-k 2,3}, 4902retain the field separators present between the endpoints of the range. 4903 4904To specify ASCII NUL as the field separator, 4905use the two-character string @samp{\0}, e.g., @samp{sort -t '\0'}. 4906 4907@item -T @var{tempdir} 4908@itemx --temporary-directory=@var{tempdir} 4909@opindex -T 4910@opindex --temporary-directory 4911@cindex temporary directory 4912@vindex TMPDIR 4913Use directory @var{tempdir} to store temporary files, overriding the 4914@env{TMPDIR} environment variable. If this option is given more than 4915once, temporary files are stored in all the directories given. If you 4916have a large sort or merge that is I/O-bound, you can often improve 4917performance by using this option to specify directories on different 4918file systems. 4919 4920@item --parallel=@var{n} 4921@opindex --parallel 4922@cindex multithreaded sort 4923Set the number of sorts run in parallel to @var{n}. By default, 4924@var{n} is set to the number of available processors, but limited 4925to 8, as there are diminishing performance gains after that. 4926Note also that using @var{n} threads increases the memory usage by 4927a factor of log @var{n}. Also see @ref{nproc invocation}. 4928 4929@item -u 4930@itemx --unique 4931@opindex -u 4932@opindex --unique 4933@cindex uniquifying output 4934 4935Normally, output only the first of a sequence of lines that compare 4936equal. For the @option{--check} (@option{-c} or @option{-C}) option, 4937check that no pair of consecutive lines compares equal. 4938 4939This option also disables the default last-resort comparison. 4940 4941The commands @code{sort -u} and @code{sort | uniq} are equivalent, but 4942this equivalence does not extend to arbitrary @command{sort} options. 4943For example, @code{sort -n -u} inspects only the value of the initial 4944numeric string when checking for uniqueness, whereas @code{sort -n | 4945uniq} inspects the entire line. @xref{uniq invocation}. 4946 4947@optZeroTerminated 4948@macro newlineFieldSeparator 4949Note with @option{-z} the newline character is treated as a field separator. 4950@end macro 4951 4952@end table 4953 4954Historical (BSD and System V) implementations of @command{sort} have 4955differed in their interpretation of some options, particularly 4956@option{-b}, @option{-f}, and @option{-n}. 4957GNU sort follows the POSIX 4958behavior, which is usually (but not always!) like the System V behavior. 4959According to POSIX, @option{-n} no longer implies @option{-b}. For 4960consistency, @option{-M} has been changed in the same way. This may 4961affect the meaning of character positions in field specifications in 4962obscure cases. The only fix is to add an explicit @option{-b}. 4963 4964A position in a sort field specified with @option{-k} may have any 4965of the option letters @samp{MbdfghinRrV} appended to it, in which case no 4966global ordering options are inherited by that particular field. The 4967@option{-b} option may be independently attached to either or both of 4968the start and end positions of a field specification, and if it is 4969inherited from the global options it will be attached to both. 4970If input lines can contain leading or adjacent blanks and @option{-t} 4971is not used, then @option{-k} is typically combined with @option{-b} or 4972an option that implicitly ignores leading blanks (@samp{Mghn}) as otherwise 4973the varying numbers of leading blanks in fields can cause confusing results. 4974 4975If the start position in a sort field specifier falls after the end of 4976the line or after the end field, the field is empty. If the @option{-b} 4977option was specified, the @samp{.@var{c}} part of a field specification 4978is counted from the first nonblank character of the field. 4979 4980@vindex _POSIX2_VERSION 4981@vindex POSIXLY_CORRECT 4982On systems not conforming to POSIX 1003.1-2001, 4983@command{sort} supports a traditional origin-zero 4984syntax @samp{+@var{pos1} [-@var{pos2}]} for specifying sort keys. 4985The traditional command @samp{sort +@var{a}.@var{x} -@var{b}.@var{y}} 4986is equivalent to @samp{sort -k @var{a+1}.@var{x+1},@var{b}} if @var{y} 4987is @samp{0} or absent, otherwise it is equivalent to @samp{sort -k 4988@var{a+1}.@var{x+1},@var{b+1}.@var{y}}. 4989 4990This traditional behavior can be controlled with the 4991@env{_POSIX2_VERSION} environment variable (@pxref{Standards 4992conformance}); it can also be enabled when @env{POSIXLY_CORRECT} is 4993not set by using the traditional syntax with @samp{-@var{pos2}} present. 4994 4995Scripts intended for use on standard hosts should avoid traditional 4996syntax and should use @option{-k} instead. For example, avoid 4997@samp{sort +2}, since it might be interpreted as either @samp{sort 4998./+2} or @samp{sort -k 3}. If your script must also run on hosts that 4999support only the traditional syntax, it can use a test like @samp{if sort 5000-k 1 </dev/null >/dev/null 2>&1; then @dots{}} to decide which syntax 5001to use. 5002 5003Here are some examples to illustrate various combinations of options. 5004 5005@itemize @bullet 5006 5007@item 5008Sort in descending (reverse) numeric order. 5009 5010@example 5011sort -n -r 5012@end example 5013 5014@item 5015Run no more than 4 sorts concurrently, using a buffer size of 10M. 5016 5017@example 5018sort --parallel=4 -S 10M 5019@end example 5020 5021@item 5022Sort alphabetically, omitting the first and second fields 5023and the blanks at the start of the third field. 5024This uses a single key composed of the characters beginning 5025at the start of the first nonblank character in field three 5026and extending to the end of each line. 5027 5028@example 5029sort -k 3b 5030@end example 5031 5032@item 5033Sort numerically on the second field and resolve ties by sorting 5034alphabetically on the third and fourth characters of field five. 5035Use @samp{:} as the field delimiter. 5036 5037@example 5038sort -t : -k 2,2n -k 5.3,5.4 5039@end example 5040 5041Note that if you had written @option{-k 2n} instead of @option{-k 2,2n} 5042@command{sort} would have used all characters beginning in the second field 5043and extending to the end of the line as the primary @emph{numeric} 5044key. For the large majority of applications, treating keys spanning 5045more than one field as numeric will not do what you expect. 5046 5047Also note that the @samp{n} modifier was applied to the field-end 5048specifier for the first key. It would have been equivalent to 5049specify @option{-k 2n,2} or @option{-k 2n,2n}. All modifiers except 5050@samp{b} apply to the associated @emph{field}, regardless of whether 5051the modifier character is attached to the field-start and/or the 5052field-end part of the key specifier. 5053 5054@item 5055Sort the password file on the fifth field and ignore any 5056leading blanks. Sort lines with equal values in field five 5057on the numeric user ID in field three. Fields are separated 5058by @samp{:}. 5059 5060@example 5061sort -t : -k 5b,5 -k 3,3n /etc/passwd 5062sort -t : -n -k 5b,5 -k 3,3 /etc/passwd 5063sort -t : -b -k 5,5 -k 3,3n /etc/passwd 5064@end example 5065 5066These three commands have equivalent effect. The first specifies that 5067the first key's start position ignores leading blanks and the second 5068key is sorted numerically. The other two commands rely on global 5069options being inherited by sort keys that lack modifiers. The inheritance 5070works in this case because @option{-k 5b,5b} and @option{-k 5b,5} are 5071equivalent, as the location of a field-end lacking a @samp{.@var{c}} 5072character position is not affected by whether initial blanks are 5073skipped. 5074 5075@item 5076Sort a set of log files, primarily by IPv4 address and secondarily by 5077timestamp. If two lines' primary and secondary keys are identical, 5078output the lines in the same order that they were input. The log 5079files contain lines that look like this: 5080 5081@example 50824.150.156.3 - - [01/Apr/2020:06:31:51 +0000] message 1 5083211.24.3.231 - - [24/Apr/2020:20:17:39 +0000] message 2 5084@end example 5085 5086Fields are separated by exactly one space. Sort IPv4 addresses 5087lexicographically, e.g., 212.61.52.2 sorts before 212.129.233.201 5088because 61 is less than 129. 5089 5090@example 5091sort -s -t ' ' -k 4.9n -k 4.5M -k 4.2n -k 4.14,4.21 file*.log | 5092sort -s -t '.' -k 1,1n -k 2,2n -k 3,3n -k 4,4n 5093@end example 5094 5095This example cannot be done with a single POSIX @command{sort} invocation, 5096since IPv4 address components are separated by @samp{.} while dates 5097come just after a space. So it is broken down into two invocations of 5098@command{sort}: the first sorts by timestamp and the second by IPv4 5099address. The timestamp is sorted by year, then month, then day, and 5100finally by hour-minute-second field, using @option{-k} to isolate each 5101field. Except for hour-minute-second there's no need to specify the 5102end of each key field, since the @samp{n} and @samp{M} modifiers sort 5103based on leading prefixes that cannot cross field boundaries. The 5104IPv4 addresses are sorted lexicographically. The second sort uses 5105@samp{-s} so that ties in the primary key are broken by the secondary 5106key; the first sort uses @samp{-s} so that the combination of the two 5107sorts is stable. Note as a GNU extension, the above example could 5108be achieved in a single @command{sort} invocation by sorting the 5109IPv4 address field using a @samp{V} version type, like @samp{-k1,1V}. 5110 5111@item 5112Generate a tags file in case-insensitive sorted order. 5113 5114@example 5115find src -type f -print0 | sort -z -f | xargs -0 etags --append 5116@end example 5117 5118The use of @option{-print0}, @option{-z}, and @option{-0} in this case means 5119that file names that contain blanks or other special characters are 5120not broken up 5121by the sort operation. 5122 5123@c This example is a bit contrived and needs more explanation. 5124@c @item 5125@c Sort records separated by an arbitrary string by using a pipe to convert 5126@c each record delimiter string to @samp{\0}, 5127@c then using sort's @option{-z} option, 5128@c and converting each @samp{\0} back to the original record delimiter. 5129@c 5130@c @example 5131@c printf 'c\n\nb\n\na\n' | 5132@c perl -0pe 's/\n\n/\n\0/g' | 5133@c sort -z | 5134@c perl -0pe 's/\0/\n/g' 5135@c @end example 5136 5137@item 5138Use the common DSU, Decorate Sort Undecorate idiom to 5139sort lines according to their length. 5140 5141@example 5142awk '@{print length, $0@}' /etc/passwd | sort -n | cut -f2- -d' ' 5143@end example 5144 5145In general this technique can be used to sort data that the @command{sort} 5146command does not support, or is inefficient at, sorting directly. 5147 5148@item 5149Shuffle a list of directories, but preserve the order of files within 5150each directory. For instance, one could use this to generate a music 5151playlist in which albums are shuffled but the songs of each album are 5152played in order. 5153 5154@example 5155ls */* | sort -t / -k 1,1R -k 2,2 5156@end example 5157 5158@end itemize 5159 5160 5161@node shuf invocation 5162@section @command{shuf}: Shuffling text 5163 5164@pindex shuf 5165@cindex shuffling files 5166 5167@command{shuf} shuffles its input by outputting a random permutation 5168of its input lines. Each output permutation is equally likely. 5169Synopses: 5170 5171@example 5172shuf [@var{option}]@dots{} [@var{file}] 5173shuf -e [@var{option}]@dots{} [@var{arg}]@dots{} 5174shuf -i @var{lo}-@var{hi} [@var{option}]@dots{} 5175@end example 5176 5177@command{shuf} has three modes of operation that affect where it 5178obtains its input lines. By default, it reads lines from standard 5179input. The following options change the operation mode: 5180 5181@table @samp 5182 5183@item -e 5184@itemx --echo 5185@opindex -c 5186@opindex --echo 5187@cindex command-line operands to shuffle 5188Treat each command-line operand as an input line. 5189 5190@item -i @var{lo}-@var{hi} 5191@itemx --input-range=@var{lo}-@var{hi} 5192@opindex -i 5193@opindex --input-range 5194@cindex input range to shuffle 5195Act as if input came from a file containing the range of unsigned 5196decimal integers @var{lo}@dots{}@var{hi}, one per line. 5197 5198@end table 5199 5200@command{shuf}'s other options can affect its behavior in all 5201operation modes: 5202 5203@table @samp 5204 5205@item -n @var{count} 5206@itemx --head-count=@var{count} 5207@opindex -n 5208@opindex --head-count 5209@cindex head of output 5210Output at most @var{count} lines. By default, all input lines are 5211output. 5212 5213@item -o @var{output-file} 5214@itemx --output=@var{output-file} 5215@opindex -o 5216@opindex --output 5217@cindex overwriting of input, allowed 5218Write output to @var{output-file} instead of standard output. 5219@command{shuf} reads all input before opening 5220@var{output-file}, so you can safely shuffle a file in place by using 5221commands like @code{shuf -o F <F} and @code{cat F | shuf -o F}. 5222 5223@item --random-source=@var{file} 5224@opindex --random-source 5225@cindex random source for shuffling 5226Use @var{file} as a source of random data used to determine which 5227permutation to generate. @xref{Random sources}. 5228 5229@item -r 5230@itemx --repeat 5231@opindex -r 5232@opindex --repeat 5233@cindex repeat output values 5234Repeat output values, that is, select with replacement. With this 5235option the output is not a permutation of the input; instead, each 5236output line is randomly chosen from all the inputs. This option is 5237typically combined with @option{--head-count}; if 5238@option{--head-count} is not given, @command{shuf} repeats 5239indefinitely. 5240 5241@optZeroTerminated 5242 5243@end table 5244 5245For example: 5246 5247@example 5248shuf <<EOF 5249A man, 5250a plan, 5251a canal: 5252Panama! 5253EOF 5254@end example 5255 5256@noindent 5257might produce the output 5258 5259@example 5260Panama! 5261A man, 5262a canal: 5263a plan, 5264@end example 5265 5266@noindent 5267Similarly, the command: 5268 5269@example 5270shuf -e clubs hearts diamonds spades 5271@end example 5272 5273@noindent 5274might output: 5275 5276@example 5277clubs 5278diamonds 5279spades 5280hearts 5281@end example 5282 5283@noindent 5284and the command @samp{shuf -i 1-4} might output: 5285 5286@example 52874 52882 52891 52903 5291@end example 5292 5293@noindent 5294The above examples all have four input lines, so @command{shuf} might 5295produce any of the twenty-four possible permutations of the input. In 5296general, if there are @var{n} input lines, there are @var{n}! (i.e., 5297@var{n} factorial, or @var{n} * (@var{n} - 1) * @dots{} * 1) possible 5298output permutations. 5299 5300@noindent 5301To output 50 random numbers each in the range 0 through 9, use: 5302 5303@example 5304shuf -r -n 50 -i 0-9 5305@end example 5306 5307@noindent 5308To simulate 100 coin flips, use: 5309 5310@example 5311shuf -r -n 100 -e Head Tail 5312@end example 5313 5314@exitstatus 5315 5316 5317@node uniq invocation 5318@section @command{uniq}: Uniquify files 5319 5320@pindex uniq 5321@cindex uniquify files 5322 5323@command{uniq} writes the unique lines in the given @file{input}, or 5324standard input if nothing is given or for an @var{input} name of 5325@samp{-}. Synopsis: 5326 5327@example 5328uniq [@var{option}]@dots{} [@var{input} [@var{output}]] 5329@end example 5330 5331By default, @command{uniq} prints its input lines, except that 5332it discards all but the first of adjacent repeated lines, so that 5333no output lines are repeated. Optionally, it can instead discard 5334lines that are not repeated, or all repeated lines. 5335 5336The input need not be sorted, but repeated input lines are detected 5337only if they are adjacent. If you want to discard non-adjacent 5338duplicate lines, perhaps you want to use @code{sort -u}. 5339@xref{sort invocation}. 5340 5341@vindex LC_COLLATE 5342Comparisons honor the rules specified by the @env{LC_COLLATE} 5343locale category. 5344 5345If no @var{output} file is specified, @command{uniq} writes to standard 5346output. 5347 5348The program accepts the following options. Also see @ref{Common options}. 5349 5350@table @samp 5351 5352@item -f @var{n} 5353@itemx --skip-fields=@var{n} 5354@opindex -f 5355@opindex --skip-fields 5356Skip @var{n} fields on each line before checking for uniqueness. Use 5357a null string for comparison if a line has fewer than @var{n} fields. 5358Fields are a sequence of blank characters followed by non-blank characters. 5359Field numbers are one based, i.e., @option{-f 1} will skip the first 5360field (which may optionally have leading blanks). 5361 5362For compatibility @command{uniq} supports a traditional option syntax 5363@option{-@var{n}}. New scripts should use @option{-f @var{n}} instead. 5364 5365@item -s @var{n} 5366@itemx --skip-chars=@var{n} 5367@opindex -s 5368@opindex --skip-chars 5369Skip @var{n} characters before checking for uniqueness. Use a null string 5370for comparison if a line has fewer than @var{n} characters. If you use both 5371the field and character skipping options, fields are skipped over first. 5372 5373@vindex _POSIX2_VERSION 5374On systems not conforming to POSIX 1003.1-2001, 5375@command{uniq} supports a traditional option syntax 5376@option{+@var{n}}. 5377Although this traditional behavior can be controlled with the 5378@env{_POSIX2_VERSION} environment variable (@pxref{Standards 5379conformance}), portable scripts should avoid commands whose 5380behavior depends on this variable. 5381For example, use @samp{uniq ./+10} or @samp{uniq -s 10} rather than 5382the ambiguous @samp{uniq +10}. 5383 5384@item -c 5385@itemx --count 5386@opindex -c 5387@opindex --count 5388Print the number of times each line occurred along with the line. 5389 5390@item -i 5391@itemx --ignore-case 5392@opindex -i 5393@opindex --ignore-case 5394Ignore differences in case when comparing lines. 5395 5396@item -d 5397@itemx --repeated 5398@opindex -d 5399@opindex --repeated 5400@cindex repeated lines, outputting 5401Discard lines that are not repeated. When used by itself, this option 5402causes @command{uniq} to print the first copy of each repeated line, 5403and nothing else. 5404 5405@item -D 5406@itemx --all-repeated[=@var{delimit-method}] 5407@opindex -D 5408@opindex --all-repeated 5409@cindex all repeated lines, outputting 5410Do not discard the second and subsequent repeated input lines, 5411but discard lines that are not repeated. 5412This option is useful mainly in conjunction with other options e.g., 5413to ignore case or to compare only selected fields. 5414The optional @var{delimit-method}, supported with the long form option, 5415specifies how to delimit groups of repeated lines, and must be one of the 5416following: 5417 5418@table @samp 5419 5420@item none 5421Do not delimit groups of repeated lines. 5422This is equivalent to @option{--all-repeated} (@option{-D}). 5423 5424@item prepend 5425Output a newline before each group of repeated lines. 5426@macro nulOutputNote 5427With @option{--zero-terminated} (@option{-z}), use a zero 5428byte (ASCII NUL) instead of a newline as the delimiter. 5429@end macro 5430@nulOutputNote 5431 5432@item separate 5433Separate groups of repeated lines with a single newline. 5434This is the same as using @samp{prepend}, except that 5435no delimiter is inserted before the first group, and hence 5436may be better suited for output direct to users. 5437@nulOutputNote 5438@end table 5439 5440@macro ambiguousGroupNote 5441Note that when groups are delimited and the input stream contains 5442blank lines, then the output is ambiguous. 5443To avoid that, filter the input through @samp{tr -s '\\n'} to 5444remove blank lines. 5445@end macro 5446@ambiguousGroupNote 5447 5448This is a GNU extension. 5449@c FIXME: give an example showing *how* it's useful 5450 5451@item --group[=@var{delimit-method}] 5452@opindex --group 5453@cindex all lines, grouping 5454Output all lines, and delimit each unique group. 5455@nulOutputNote 5456The optional @var{delimit-method} specifies how to delimit 5457groups, and must be one of the following: 5458 5459@table @samp 5460 5461@item separate 5462Separate unique groups with a single delimiter. 5463This is the default delimiting method if none is specified, 5464and better suited for output direct to users. 5465 5466@item prepend 5467Output a delimiter before each group of unique items. 5468 5469@item append 5470Output a delimiter after each group of unique items. 5471 5472@item both 5473Output a delimiter around each group of unique items. 5474@end table 5475 5476@ambiguousGroupNote 5477 5478This is a GNU extension. 5479 5480@item -u 5481@itemx --unique 5482@opindex -u 5483@opindex --unique 5484@cindex unique lines, outputting 5485Discard the last line that would be output for a repeated input group. 5486When used by itself, this option causes @command{uniq} to print unique 5487lines, and nothing else. 5488 5489@item -w @var{n} 5490@itemx --check-chars=@var{n} 5491@opindex -w 5492@opindex --check-chars 5493Compare at most @var{n} characters on each line (after skipping any specified 5494fields and characters). By default the entire rest of the lines are 5495compared. 5496 5497@optZeroTerminated 5498@newlineFieldSeparator 5499 5500@end table 5501 5502@exitstatus 5503 5504 5505@node comm invocation 5506@section @command{comm}: Compare two sorted files line by line 5507 5508@pindex comm 5509@cindex line-by-line comparison 5510@cindex comparing sorted files 5511 5512@command{comm} writes to standard output lines that are common, and lines 5513that are unique, to two input files; a file name of @samp{-} means 5514standard input. Synopsis: 5515 5516@example 5517comm [@var{option}]@dots{} @var{file1} @var{file2} 5518@end example 5519 5520@vindex LC_COLLATE 5521Before @command{comm} can be used, the input files must be sorted using the 5522collating sequence specified by the @env{LC_COLLATE} locale. 5523If an input file ends in a non-newline 5524character, a newline is silently appended. The @command{sort} command with 5525no options always outputs a file that is suitable input to @command{comm}. 5526 5527@cindex differing lines 5528@cindex common lines 5529With no options, @command{comm} produces three-column output. Column one 5530contains lines unique to @var{file1}, column two contains lines unique 5531to @var{file2}, and column three contains lines common to both files. 5532Columns are separated by a single TAB character. 5533@c FIXME: when there's an option to supply an alternative separator 5534@c string, append "by default" to the above sentence. 5535 5536@opindex -1 5537@opindex -2 5538@opindex -3 5539The options @option{-1}, @option{-2}, and @option{-3} suppress printing of 5540the corresponding columns (and separators). Also see @ref{Common options}. 5541 5542Unlike some other comparison utilities, @command{comm} has an exit 5543status that does not depend on the result of the comparison. 5544Upon normal completion @command{comm} produces an exit code of zero. 5545If there is an error it exits with nonzero status. 5546 5547@macro checkOrderOption{cmd} 5548If the @option{--check-order} option is given, unsorted inputs will 5549cause a fatal error message. If the option @option{--nocheck-order} 5550is given, unsorted inputs will never cause an error message. If neither 5551of these options is given, wrongly sorted inputs are diagnosed 5552only if an input file is found to contain unpairable 5553@ifset JOIN_COMMAND 5554lines, and when both input files are non empty. 5555@end ifset 5556@ifclear JOIN_COMMAND 5557lines. 5558@end ifclear 5559If an input file is diagnosed as being unsorted, the @command{\cmd\} 5560command will exit with a nonzero status (and the output should not be used). 5561 5562Forcing @command{\cmd\} to process wrongly sorted input files 5563containing unpairable lines by specifying @option{--nocheck-order} is 5564not guaranteed to produce any particular output. The output will 5565probably not correspond with whatever you hoped it would be. 5566@end macro 5567@checkOrderOption{comm} 5568 5569@table @samp 5570 5571@item --check-order 5572Fail with an error message if either input file is wrongly ordered. 5573 5574@item --nocheck-order 5575Do not check that both input files are in sorted order. 5576 5577Other options are: 5578 5579@item --output-delimiter=@var{str} 5580Print @var{str} between adjacent output columns, 5581rather than the default of a single TAB character. 5582 5583The delimiter @var{str} may be empty, in which case 5584the ASCII NUL character is used to delimit output columns. 5585 5586@item --total 5587Output a summary at the end. 5588 5589Similar to the regular output, 5590column one contains the total number of lines unique to @var{file1}, 5591column two contains the total number of lines unique to @var{file2}, and 5592column three contains the total number of lines common to both files, 5593followed by the word @samp{total} in the additional column four. 5594 5595In the following example, @command{comm} omits the regular output 5596(@option{-123}), thus just printing the summary: 5597 5598@example 5599$ printf '%s\n' a b c d e > file1 5600$ printf '%s\n' b c d e f g > file2 5601$ comm --total -123 file1 file2 56021 2 4 total 5603@end example 5604 5605This option is a GNU extension. Portable scripts should use @command{wc} to 5606get the totals, e.g. for the above example files: 5607 5608@example 5609$ comm -23 file1 file2 | wc -l # number of lines only in file1 56101 5611$ comm -13 file1 file2 | wc -l # number of lines only in file2 56122 5613$ comm -12 file1 file2 | wc -l # number of lines common to both files 56144 5615@end example 5616 5617@optZeroTerminated 5618 5619@end table 5620 5621@node ptx invocation 5622@section @command{ptx}: Produce permuted indexes 5623 5624@pindex ptx 5625 5626@command{ptx} reads a text file and essentially produces a permuted index, with 5627each keyword in its context. The calling sketch is either one of: 5628 5629@example 5630ptx [@var{option} @dots{}] [@var{file} @dots{}] 5631ptx -G [@var{option} @dots{}] [@var{input} [@var{output}]] 5632@end example 5633 5634The @option{-G} (or its equivalent: @option{--traditional}) option disables 5635all GNU extensions and reverts to traditional mode, thus introducing some 5636limitations and changing several of the program's default option values. 5637When @option{-G} is not specified, GNU extensions are always enabled. 5638GNU extensions to @command{ptx} are documented wherever appropriate in this 5639document. @xref{Compatibility in ptx}, for the full list. 5640 5641Individual options are explained in the following sections. 5642 5643When GNU extensions are enabled, there may be zero, one or several 5644@var{file}s after the options. If there is no @var{file}, the program 5645reads the standard input. If there is one or several @var{file}s, they 5646give the name of input files which are all read in turn, as if all the 5647input files were concatenated. However, there is a full contextual 5648break between each file and, when automatic referencing is requested, 5649file names and line numbers refer to individual text input files. In 5650all cases, the program outputs the permuted index to the standard 5651output. 5652 5653When GNU extensions are @emph{not} enabled, that is, when the program 5654operates in traditional mode, there may be zero, one or two parameters 5655besides the options. If there are no parameters, the program reads the 5656standard input and outputs the permuted index to the standard output. 5657If there is only one parameter, it names the text @var{input} to be read 5658instead of the standard input. If two parameters are given, they give 5659respectively the name of the @var{input} file to read and the name of 5660the @var{output} file to produce. @emph{Be very careful} to note that, 5661in this case, the contents of file given by the second parameter is 5662destroyed. This behavior is dictated by System V @command{ptx} 5663compatibility; GNU Standards normally discourage output parameters not 5664introduced by an option. 5665 5666Note that for @emph{any} file named as the value of an option or as an 5667input text file, a single dash @samp{-} may be used, in which case 5668standard input is assumed. However, it would not make sense to use this 5669convention more than once per program invocation. 5670 5671@menu 5672* General options in ptx:: Options which affect general program behavior. 5673* Charset selection in ptx:: Underlying character set considerations. 5674* Input processing in ptx:: Input fields, contexts, and keyword selection. 5675* Output formatting in ptx:: Types of output format, and sizing the fields. 5676* Compatibility in ptx:: 5677@end menu 5678 5679 5680@node General options in ptx 5681@subsection General options 5682 5683@table @samp 5684 5685@item -G 5686@itemx --traditional 5687As already explained, this option disables all GNU extensions to 5688@command{ptx} and switches to traditional mode. 5689 5690@item --help 5691Print a short help on standard output, then exit without further 5692processing. 5693 5694@item --version 5695Print the program version on standard output, then exit without further 5696processing. 5697 5698@end table 5699 5700@exitstatus 5701 5702 5703@node Charset selection in ptx 5704@subsection Charset selection 5705 5706As it is set up now, @command{ptx} assumes that the input file is coded 5707using 8-bit characters, and it may not work well in multibyte locales. 5708In a single-byte locale, the default regular expression 5709for a keyword allows foreign or diacriticized letters. Keyword sorting, 5710however, is still crude; it obeys the underlying character set ordering 5711quite blindly. 5712 5713The output of @command{ptx} assumes the locale's character encoding. 5714For example, with @command{ptx}'s @option{-T} option, if the locale 5715uses the Latin-1 encoding you may need a LaTeX directive like 5716@samp{\usepackage[latin1]@{inputenc@}} to render non-ASCII characters 5717correctly. 5718 5719@table @samp 5720 5721@item -f 5722@itemx --ignore-case 5723@opindex -f 5724@opindex --ignore-case 5725Fold lower case letters to upper case for sorting. 5726 5727@end table 5728 5729 5730@node Input processing in ptx 5731@subsection Word selection and input processing 5732 5733@table @samp 5734 5735@item -b @var{file} 5736@itemx --break-file=@var{file} 5737@opindex -b 5738@opindex --break-file 5739 5740This option provides an alternative (to @option{-W}) method of describing 5741which characters make up words. It introduces the name of a 5742file which contains a list of characters which can@emph{not} be part of 5743one word; this file is called the @dfn{Break file}. Any character which 5744is not part of the Break file is a word constituent. If both options 5745@option{-b} and @option{-W} are specified, then @option{-W} has precedence and 5746@option{-b} is ignored. 5747 5748When GNU extensions are enabled, the only way to avoid newline as a 5749break character is to write all the break characters in the file with no 5750newline at all, not even at the end of the file. When GNU extensions 5751are disabled, spaces, tabs and newlines are always considered as break 5752characters even if not included in the Break file. 5753 5754@item -i @var{file} 5755@itemx --ignore-file=@var{file} 5756@opindex -i 5757@opindex --ignore-file 5758 5759The file associated with this option contains a list of words which will 5760never be taken as keywords in concordance output. It is called the 5761@dfn{Ignore file}. The file contains exactly one word in each line; the 5762end of line separation of words is not subject to the value of the 5763@option{-S} option. 5764 5765@item -o @var{file} 5766@itemx --only-file=@var{file} 5767@opindex -o 5768@opindex --only-file 5769 5770The file associated with this option contains a list of words which will 5771be retained in concordance output; any word not mentioned in this file 5772is ignored. The file is called the @dfn{Only file}. The file contains 5773exactly one word in each line; the end of line separation of words is 5774not subject to the value of the @option{-S} option. 5775 5776There is no default for the Only file. When both an Only file and an 5777Ignore file are specified, a word is considered a keyword only 5778if it is listed in the Only file and not in the Ignore file. 5779 5780@item -r 5781@itemx --references 5782@opindex -r 5783@opindex --references 5784 5785On each input line, the leading sequence of non-white space characters will be 5786taken to be a reference that has the purpose of identifying this input 5787line in the resulting permuted index. 5788@xref{Output formatting in ptx}, 5789for more information about reference production. 5790Using this option changes the default value for option @option{-S}. 5791 5792Using this option, the program does not try very hard to remove 5793references from contexts in output, but it succeeds in doing so 5794@emph{when} the context ends exactly at the newline. If option 5795@option{-r} is used with @option{-S} default value, or when GNU extensions 5796are disabled, this condition is always met and references are completely 5797excluded from the output contexts. 5798 5799@item -S @var{regexp} 5800@itemx --sentence-regexp=@var{regexp} 5801@opindex -S 5802@opindex --sentence-regexp 5803 5804This option selects which regular expression will describe the end of a 5805line or the end of a sentence. In fact, this regular expression is not 5806the only distinction between end of lines or end of sentences, and input 5807line boundaries have no special significance outside this option. By 5808default, when GNU extensions are enabled and if @option{-r} option is not 5809used, end of sentences are used. In this case, this @var{regex} is 5810imported from GNU Emacs: 5811 5812@example 5813[.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]* 5814@end example 5815 5816Whenever GNU extensions are disabled or if @option{-r} option is used, end 5817of lines are used; in this case, the default @var{regexp} is just: 5818 5819@example 5820\n 5821@end example 5822 5823Using an empty @var{regexp} is equivalent to completely disabling end of 5824line or end of sentence recognition. In this case, the whole file is 5825considered to be a single big line or sentence. The user might want to 5826disallow all truncation flag generation as well, through option @option{-F 5827""}. @xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs 5828Manual}. 5829 5830When the keywords happen to be near the beginning of the input line or 5831sentence, this often creates an unused area at the beginning of the 5832output context line; when the keywords happen to be near the end of the 5833input line or sentence, this often creates an unused area at the end of 5834the output context line. The program tries to fill those unused areas 5835by wrapping around context in them; the tail of the input line or 5836sentence is used to fill the unused area on the left of the output line; 5837the head of the input line or sentence is used to fill the unused area 5838on the right of the output line. 5839 5840As a matter of convenience to the user, many usual backslashed escape 5841sequences from the C language are recognized and converted to the 5842corresponding characters by @command{ptx} itself. 5843 5844@item -W @var{regexp} 5845@itemx --word-regexp=@var{regexp} 5846@opindex -W 5847@opindex --word-regexp 5848 5849This option selects which regular expression will describe each keyword. 5850By default, if GNU extensions are enabled, a word is a sequence of 5851letters; the @var{regexp} used is @samp{\w+}. When GNU extensions are 5852disabled, a word is by default anything which ends with a space, a tab 5853or a newline; the @var{regexp} used is @samp{[^ \t\n]+}. 5854 5855An empty @var{regexp} is equivalent to not using this option. 5856@xref{Regexps, , Syntax of Regular Expressions, emacs, The GNU Emacs 5857Manual}. 5858 5859As a matter of convenience to the user, many usual backslashed escape 5860sequences, as found in the C language, are recognized and converted to 5861the corresponding characters by @command{ptx} itself. 5862 5863@end table 5864 5865 5866@node Output formatting in ptx 5867@subsection Output formatting 5868 5869Output format is mainly controlled by the @option{-O} and @option{-T} options 5870described in the table below. When neither @option{-O} nor @option{-T} are 5871selected, and if GNU extensions are enabled, the program chooses an 5872output format suitable for a dumb terminal. Each keyword occurrence is 5873output to the center of one line, surrounded by its left and right 5874contexts. Each field is properly justified, so the concordance output 5875can be readily observed. As a special feature, if automatic 5876references are selected by option @option{-A} and are output before the 5877left context, that is, if option @option{-R} is @emph{not} selected, then 5878a colon is added after the reference; this nicely interfaces with GNU 5879Emacs @code{next-error} processing. In this default output format, each 5880white space character, like newline and tab, is merely changed to 5881exactly one space, with no special attempt to compress consecutive 5882spaces. This might change in the future. Except for those white space 5883characters, every other character of the underlying set of 256 5884characters is transmitted verbatim. 5885 5886Output format is further controlled by the following options. 5887 5888@table @samp 5889 5890@item -g @var{number} 5891@itemx --gap-size=@var{number} 5892@opindex -g 5893@opindex --gap-size 5894 5895Select the size of the minimum white space gap between the fields on the 5896output line. 5897 5898@item -w @var{number} 5899@itemx --width=@var{number} 5900@opindex -w 5901@opindex --width 5902 5903Select the maximum output width of each final line. If references are 5904used, they are included or excluded from the maximum output width 5905depending on the value of option @option{-R}@. If this option is not 5906selected, that is, when references are output before the left context, 5907the maximum output width takes into account the maximum length of all 5908references. If this option is selected, that is, when references are 5909output after the right context, the maximum output width does not take 5910into account the space taken by references, nor the gap that precedes 5911them. 5912 5913@item -A 5914@itemx --auto-reference 5915@opindex -A 5916@opindex --auto-reference 5917 5918Select automatic references. Each input line will have an automatic 5919reference made up of the file name and the line ordinal, with a single 5920colon between them. However, the file name will be empty when standard 5921input is being read. If both @option{-A} and @option{-r} are selected, then 5922the input reference is still read and skipped, but the automatic 5923reference is used at output time, overriding the input reference. 5924 5925@item -R 5926@itemx --right-side-refs 5927@opindex -R 5928@opindex --right-side-refs 5929 5930In the default output format, when option @option{-R} is not used, any 5931references produced by the effect of options @option{-r} or @option{-A} are 5932placed to the far right of output lines, after the right context. With 5933default output format, when the @option{-R} option is specified, references 5934are rather placed at the beginning of each output line, before the left 5935context. For any other output format, option @option{-R} is 5936ignored, with one exception: with @option{-R} the width of references 5937is @emph{not} taken into account in total output width given by @option{-w}. 5938 5939This option is automatically selected whenever GNU extensions are 5940disabled. 5941 5942@item -F @var{string} 5943@itemx --flag-truncation=@var{string} 5944@opindex -F 5945@opindex --flag-truncation 5946 5947This option will request that any truncation in the output be reported 5948using the string @var{string}. Most output fields theoretically extend 5949towards the beginning or the end of the current line, or current 5950sentence, as selected with option @option{-S}@. But there is a maximum 5951allowed output line width, changeable through option @option{-w}, which is 5952further divided into space for various output fields. When a field has 5953to be truncated because it cannot extend beyond the beginning or the end of 5954the current line to fit in, then a truncation occurs. By default, 5955the string used is a single slash, as in @option{-F /}. 5956 5957@var{string} may have more than one character, as in @option{-F @dots{}}. 5958Also, in the particular case when @var{string} is empty (@option{-F ""}), 5959truncation flagging is disabled, and no truncation marks are appended in 5960this case. 5961 5962As a matter of convenience to the user, many usual backslashed escape 5963sequences, as found in the C language, are recognized and converted to 5964the corresponding characters by @command{ptx} itself. 5965 5966@item -M @var{string} 5967@itemx --macro-name=@var{string} 5968@opindex -M 5969@opindex --macro-name 5970 5971Select another @var{string} to be used instead of @samp{xx}, while 5972generating output suitable for @command{nroff}, @command{troff} or @TeX{}. 5973 5974@item -O 5975@itemx --format=roff 5976@opindex -O 5977@opindex --format=roff 5978 5979Choose an output format suitable for @command{nroff} or @command{troff} 5980processing. Each output line will look like: 5981 5982@example 5983.xx "@var{tail}" "@var{before}" "@var{keyword_and_after}"@c 5984 "@var{head}" "@var{ref}" 5985@end example 5986 5987so it will be possible to write a @samp{.xx} roff macro to take care of 5988the output typesetting. This is the default output format when GNU 5989extensions are disabled. Option @option{-M} can be used to change 5990@samp{xx} to another macro name. 5991 5992In this output format, each non-graphical character, like newline and 5993tab, is merely changed to exactly one space, with no special attempt to 5994compress consecutive spaces. Each quote character @samp{"} is doubled 5995so it will be correctly processed by @command{nroff} or @command{troff}. 5996 5997@item -T 5998@itemx --format=tex 5999@opindex -T 6000@opindex --format=tex 6001 6002Choose an output format suitable for @TeX{} processing. Each output 6003line will look like: 6004 6005@example 6006\xx @{@var{tail}@}@{@var{before}@}@{@var{keyword}@}@c 6007@{@var{after}@}@{@var{head}@}@{@var{ref}@} 6008@end example 6009 6010@noindent 6011so it will be possible to write a @code{\xx} definition to take care of 6012the output typesetting. Note that when references are not being 6013produced, that is, neither option @option{-A} nor option @option{-r} is 6014selected, the last parameter of each @code{\xx} call is inhibited. 6015Option @option{-M} can be used to change @samp{xx} to another macro 6016name. 6017 6018In this output format, some special characters, like @samp{$}, @samp{%}, 6019@samp{&}, @samp{#} and @samp{_} are automatically protected with a 6020backslash. Curly brackets @samp{@{}, @samp{@}} are protected with a 6021backslash and a pair of dollar signs (to force mathematical mode). The 6022backslash itself produces the sequence @code{\backslash@{@}}. 6023Circumflex and tilde diacritical marks produce the sequence @code{^\@{ @}} and 6024@code{~\@{ @}} respectively. Other diacriticized characters of the 6025underlying character set produce an appropriate @TeX{} sequence as far 6026as possible. The other non-graphical characters, like newline and tab, 6027and all other characters which are not part of ASCII, are merely 6028changed to exactly one space, with no special attempt to compress 6029consecutive spaces. Let me know how to improve this special character 6030processing for @TeX{}. 6031 6032@end table 6033 6034 6035@node Compatibility in ptx 6036@subsection The GNU extensions to @command{ptx} 6037 6038This version of @command{ptx} contains a few features which do not exist in 6039System V @command{ptx}. These extra features are suppressed by using the 6040@option{-G} command line option, unless overridden by other command line 6041options. Some GNU extensions cannot be recovered by overriding, so the 6042simple rule is to avoid @option{-G} if you care about GNU extensions. 6043Here are the differences between this program and System V @command{ptx}. 6044 6045@itemize @bullet 6046 6047@item 6048This program can read many input files at once, it always writes the 6049resulting concordance on standard output. On the other hand, System V 6050@command{ptx} reads only one file and sends the result to standard output 6051or, if a second @var{file} parameter is given on the command, to that 6052@var{file}. 6053 6054Having output parameters not introduced by options is a dangerous 6055practice which GNU avoids as far as possible. So, for using @command{ptx} 6056portably between GNU and System V, you should always use it with a 6057single input file, and always expect the result on standard output. You 6058might also want to automatically configure in a @option{-G} option to 6059@command{ptx} calls in products using @command{ptx}, if the configurator finds 6060that the installed @command{ptx} accepts @option{-G}. 6061 6062@item 6063The only options available in System V @command{ptx} are options @option{-b}, 6064@option{-f}, @option{-g}, @option{-i}, @option{-o}, @option{-r}, @option{-t} and 6065@option{-w}. All other options are GNU extensions and are not repeated in 6066this enumeration. Moreover, some options have a slightly different 6067meaning when GNU extensions are enabled, as explained below. 6068 6069@item 6070By default, concordance output is not formatted for @command{troff} or 6071@command{nroff}. It is rather formatted for a dumb terminal. @command{troff} 6072or @command{nroff} output may still be selected through option @option{-O}. 6073 6074@item 6075Unless @option{-R} option is used, the maximum reference width is 6076subtracted from the total output line width. With GNU extensions 6077disabled, width of references is not taken into account in the output 6078line width computations. 6079 6080@item 6081All 256 bytes, even ASCII NUL bytes, are always read and 6082processed from input file with no adverse effect, even if GNU extensions 6083are disabled. However, System V @command{ptx} does not accept 8-bit 6084characters, a few control characters are rejected, and the tilde 6085@samp{~} is also rejected. 6086 6087@item 6088Input line length is only limited by available memory, even if GNU 6089extensions are disabled. However, System V @command{ptx} processes only 6090the first 200 characters in each line. 6091 6092@item 6093The break (non-word) characters default to be every character except all 6094letters of the underlying character set, diacriticized or not. When GNU 6095extensions are disabled, the break characters default to space, tab and 6096newline only. 6097 6098@item 6099The program makes better use of output line width. If GNU extensions 6100are disabled, the program rather tries to imitate System V @command{ptx}, 6101but still, there are some slight disposition glitches this program does 6102not completely reproduce. 6103 6104@item 6105The user can specify both an Ignore file and an Only file. This is not 6106allowed with System V @command{ptx}. 6107 6108@end itemize 6109 6110 6111@node tsort invocation 6112@section @command{tsort}: Topological sort 6113 6114@pindex tsort 6115@cindex topological sort 6116 6117@command{tsort} performs a topological sort on the given @var{file}, or 6118standard input if no input file is given or for a @var{file} of 6119@samp{-}. For more details and some history, see @ref{tsort background}. 6120Synopsis: 6121 6122@example 6123tsort [@var{option}] [@var{file}] 6124@end example 6125 6126@command{tsort} reads its input as pairs of strings, separated by blanks, 6127indicating a partial ordering. The output is a total ordering that 6128corresponds to the given partial ordering. 6129 6130For example 6131 6132@example 6133tsort <<EOF 6134a b c 6135d 6136e f 6137b c d e 6138EOF 6139@end example 6140 6141@noindent 6142will produce the output 6143 6144@example 6145a 6146b 6147c 6148d 6149e 6150f 6151@end example 6152 6153Consider a more realistic example. 6154You have a large set of functions all in one file, and they may all be 6155declared static except one. Currently that one (say @code{main}) is the 6156first function defined in the file, and the ones it calls directly follow 6157it, followed by those they call, etc. Let's say that you are determined 6158to take advantage of prototypes, so you have to choose between declaring 6159all of those functions (which means duplicating a lot of information from 6160the definitions) and rearranging the functions so that as many as possible 6161are defined before they are used. One way to automate the latter process 6162is to get a list for each function of the functions it calls directly. 6163Many programs can generate such lists. They describe a call graph. 6164Consider the following list, in which a given line indicates that the 6165function on the left calls the one on the right directly. 6166 6167@example 6168main parse_options 6169main tail_file 6170main tail_forever 6171tail_file pretty_name 6172tail_file write_header 6173tail_file tail 6174tail_forever recheck 6175tail_forever pretty_name 6176tail_forever write_header 6177tail_forever dump_remainder 6178tail tail_lines 6179tail tail_bytes 6180tail_lines start_lines 6181tail_lines dump_remainder 6182tail_lines file_lines 6183tail_lines pipe_lines 6184tail_bytes xlseek 6185tail_bytes start_bytes 6186tail_bytes dump_remainder 6187tail_bytes pipe_bytes 6188file_lines dump_remainder 6189recheck pretty_name 6190@end example 6191 6192then you can use @command{tsort} to produce an ordering of those 6193functions that satisfies your requirement. 6194 6195@example 6196example$ tsort call-graph | tac 6197dump_remainder 6198start_lines 6199file_lines 6200pipe_lines 6201xlseek 6202start_bytes 6203pipe_bytes 6204tail_lines 6205tail_bytes 6206pretty_name 6207write_header 6208tail 6209recheck 6210parse_options 6211tail_file 6212tail_forever 6213main 6214@end example 6215 6216@command{tsort} detects any cycles in the input and writes the first cycle 6217encountered to standard error. 6218 6219Note that for a given partial ordering, generally there is no unique 6220total ordering. In the context of the call graph above, the function 6221@code{parse_options} may be placed anywhere in the list as long as it 6222precedes @code{main}. 6223 6224The only options are @option{--help} and @option{--version}. @xref{Common 6225options}. 6226 6227@exitstatus 6228 6229@menu 6230* tsort background:: Where tsort came from. 6231@end menu 6232 6233@node tsort background 6234@subsection @command{tsort}: Background 6235 6236@command{tsort} exists because very early versions of the Unix linker processed 6237an archive file exactly once, and in order. As @command{ld} read each object 6238in the archive, it decided whether it was needed in the program based on 6239whether it defined any symbols which were undefined at that point in 6240the link. 6241 6242This meant that dependencies within the archive had to be handled 6243specially. For example, @code{scanf} probably calls @code{read}. That means 6244that in a single pass through an archive, it was important for @code{scanf.o} 6245to appear before read.o, because otherwise a program which calls 6246@code{scanf} but not @code{read} might end up with an unexpected unresolved 6247reference to @code{read}. 6248 6249The way to address this problem was to first generate a set of 6250dependencies of one object file on another. This was done by a shell 6251script called @command{lorder}. The GNU tools don't provide a version of 6252lorder, as far as I know, but you can still find it in BSD 6253distributions. 6254 6255Then you ran @command{tsort} over the @command{lorder} output, and you used the 6256resulting sort to define the order in which you added objects to the archive. 6257 6258This whole procedure has been obsolete since about 1980, because 6259Unix archives now contain a symbol table (traditionally built by 6260@command{ranlib}, now generally built by @command{ar} itself), and the Unix 6261linker uses the symbol table to effectively make multiple passes over 6262an archive file. 6263 6264Anyhow, that's where tsort came from. To solve an old problem with 6265the way the linker handled archive files, which has since been solved 6266in different ways. 6267 6268 6269@node Operating on fields 6270@chapter Operating on fields 6271 6272@menu 6273* cut invocation:: Print selected parts of lines. 6274* paste invocation:: Merge lines of files. 6275* join invocation:: Join lines on a common field. 6276@end menu 6277 6278 6279@node cut invocation 6280@section @command{cut}: Print selected parts of lines 6281 6282@pindex cut 6283@command{cut} writes to standard output selected parts of each line of each 6284input file, or standard input if no files are given or for a file name of 6285@samp{-}. Synopsis: 6286 6287@example 6288cut @var{option}@dots{} [@var{file}]@dots{} 6289@end example 6290 6291In the table which follows, the @var{byte-list}, @var{character-list}, 6292and @var{field-list} are one or more numbers or ranges (two numbers 6293separated by a dash) separated by commas. Bytes, characters, and 6294fields are numbered starting at 1. Incomplete ranges may be 6295given: @option{-@var{m}} means @samp{1-@var{m}}; @samp{@var{n}-} means 6296@samp{@var{n}} through end of line or last field. The list elements 6297can be repeated, can overlap, and can be specified in any order; but 6298the selected input is written in the same order that it is read, and 6299is written exactly once. 6300 6301The program accepts the following options. Also see @ref{Common 6302options}. 6303 6304@table @samp 6305 6306@item -b @var{byte-list} 6307@itemx --bytes=@var{byte-list} 6308@opindex -b 6309@opindex --bytes 6310Select for printing only the bytes in positions listed in 6311@var{byte-list}. Tabs and backspaces are treated like any other 6312character; they take up 1 byte. If an output delimiter is specified, 6313(see the description of @option{--output-delimiter}), then output that 6314string between ranges of selected bytes. 6315 6316@item -c @var{character-list} 6317@itemx --characters=@var{character-list} 6318@opindex -c 6319@opindex --characters 6320Select for printing only the characters in positions listed in 6321@var{character-list}. The same as @option{-b} for now, but 6322internationalization will change that. Tabs and backspaces are 6323treated like any other character; they take up 1 character. If an 6324output delimiter is specified, (see the description of 6325@option{--output-delimiter}), then output that string between ranges 6326of selected bytes. 6327 6328@item -f @var{field-list} 6329@itemx --fields=@var{field-list} 6330@opindex -f 6331@opindex --fields 6332Select for printing only the fields listed in @var{field-list}. 6333Fields are separated by a TAB character by default. Also print any 6334line that contains no delimiter character, unless the 6335@option{--only-delimited} (@option{-s}) option is specified. 6336 6337Note @command{awk} supports more sophisticated field processing, 6338like reordering fields, and handling fields aligned with blank characters. 6339By default @command{awk} uses (and discards) runs of blank characters 6340to separate fields, and ignores leading and trailing blanks. 6341@example 6342@verbatim 6343awk '{print $2}' # print the second field 6344awk '{print $(NF-1)}' # print the penultimate field 6345awk '{print $2,$1}' # reorder the first two fields 6346@end verbatim 6347@end example 6348Note while @command{cut} accepts field specifications in 6349arbitrary order, output is always in the order encountered in the file. 6350 6351In the unlikely event that @command{awk} is unavailable, 6352one can use the @command{join} command, to process blank 6353characters as @command{awk} does above. 6354@example 6355@verbatim 6356join -a1 -o 1.2 - /dev/null # print the second field 6357join -a1 -o 1.2,1.1 - /dev/null # reorder the first two fields 6358@end verbatim 6359@end example 6360 6361@item -d @var{input_delim_byte} 6362@itemx --delimiter=@var{input_delim_byte} 6363@opindex -d 6364@opindex --delimiter 6365With @option{-f}, use the first byte of @var{input_delim_byte} as 6366the input fields separator (default is TAB). 6367 6368@item -n 6369@opindex -n 6370Do not split multi-byte characters (no-op for now). 6371 6372@item -s 6373@itemx --only-delimited 6374@opindex -s 6375@opindex --only-delimited 6376For @option{-f}, do not print lines that do not contain the field separator 6377character. Normally, any line without a field separator is printed verbatim. 6378 6379@item --output-delimiter=@var{output_delim_string} 6380@opindex --output-delimiter 6381With @option{-f}, output fields are separated by @var{output_delim_string}. 6382The default with @option{-f} is to use the input delimiter. 6383When using @option{-b} or @option{-c} to select ranges of byte or 6384character offsets (as opposed to ranges of fields), 6385output @var{output_delim_string} between non-overlapping 6386ranges of selected bytes. 6387 6388@item --complement 6389@opindex --complement 6390This option is a GNU extension. 6391Select for printing the complement of the bytes, characters or fields 6392selected with the @option{-b}, @option{-c} or @option{-f} options. 6393In other words, do @emph{not} print the bytes, characters or fields 6394specified via those options. This option is useful when you have 6395many fields and want to print all but a few of them. 6396 6397@optZeroTerminated 6398 6399@end table 6400 6401@exitstatus 6402 6403 6404@node paste invocation 6405@section @command{paste}: Merge lines of files 6406 6407@pindex paste 6408@cindex merging files 6409 6410@command{paste} writes to standard output lines consisting of sequentially 6411corresponding lines of each given file, separated by a TAB character. 6412Standard input is used for a file name of @samp{-} or if no input files 6413are given. 6414 6415Synopsis: 6416 6417@example 6418paste [@var{option}]@dots{} [@var{file}]@dots{} 6419@end example 6420 6421For example, with: 6422@example 6423$ cat num2 64241 64252 6426$ cat let3 6427a 6428b 6429c 6430@end example 6431 6432Take lines sequentially from each file: 6433@example 6434$ paste num2 let3 64351 a 64362 b 6437 @ c 6438@end example 6439 6440Duplicate lines from a file: 6441@example 6442$ paste num2 let3 num2 64431 a 1 64442 b 2 6445 @ c 6446@end example 6447 6448Intermix lines from standard input: 6449@example 6450$ paste - let3 - < num2 64511 a 2 6452 @ b 6453 @ c 6454@end example 6455 6456Join consecutive lines with a space: 6457@example 6458$ seq 4 | paste -d ' ' - - 64591 2 64603 4 6461@end example 6462 6463The program accepts the following options. Also see @ref{Common options}. 6464 6465@table @samp 6466 6467@item -s 6468@itemx --serial 6469@opindex -s 6470@opindex --serial 6471Paste the lines of one file at a time rather than one line from each 6472file. Using the above example data: 6473 6474@example 6475$ paste -s num2 let3 64761 2 6477a b c 6478@end example 6479 6480@item -d @var{delim-list} 6481@itemx --delimiters=@var{delim-list} 6482@opindex -d 6483@opindex --delimiters 6484Consecutively use the characters in @var{delim-list} instead of 6485TAB to separate merged lines. When @var{delim-list} is 6486exhausted, start again at its beginning. Using the above example data: 6487 6488@example 6489$ paste -d '%_' num2 let3 num2 64901%a_1 64912%b_2 6492%c_ 6493@end example 6494 6495@optZeroTerminated 6496 6497@end table 6498 6499@exitstatus 6500 6501 6502@node join invocation 6503@section @command{join}: Join lines on a common field 6504 6505@pindex join 6506@cindex common field, joining on 6507 6508@command{join} writes to standard output a line for each pair of input 6509lines that have identical join fields. Synopsis: 6510 6511@example 6512join [@var{option}]@dots{} @var{file1} @var{file2} 6513@end example 6514 6515Either @var{file1} or @var{file2} (but not both) can be @samp{-}, 6516meaning standard input. @var{file1} and @var{file2} should be 6517sorted on the join fields. 6518 6519@example 6520@group 6521$ cat file1 6522a 1 6523b 2 6524e 5 6525 6526$ cat file2 6527a X 6528e Y 6529f Z 6530 6531$ join file1 file2 6532a 1 X 6533e 5 Y 6534@end group 6535@end example 6536 6537 6538@noindent 6539@command{join}'s default behavior (when no options are given): 6540@itemize 6541@item the join field is the first field in each line; 6542@item fields in the input are separated by one or more blanks, with leading 6543blanks on the line ignored; 6544@item fields in the output are separated by a space; 6545@item each output line consists of the join field, the remaining 6546fields from @var{file1}, then the remaining fields from @var{file2}. 6547@end itemize 6548 6549 6550@menu 6551* General options in join:: Options which affect general program behavior. 6552* Sorting files for join:: Using @command{sort} before @command{join}. 6553* Working with fields:: Joining on different fields. 6554* Paired and unpaired lines:: Controlling @command{join}'s field matching. 6555* Header lines:: Working with header lines in files. 6556* Set operations:: Union, Intersection and Difference of files. 6557@end menu 6558 6559@node General options in join 6560@subsection General options 6561The program accepts the following options. Also see @ref{Common options}. 6562 6563@table @samp 6564 6565@item -a @var{file-number} 6566@opindex -a 6567Print a line for each unpairable line in file @var{file-number} (either 6568@samp{1} or @samp{2}), in addition to the normal output. 6569 6570@item --check-order 6571Fail with an error message if either input file is wrongly ordered. 6572 6573@item --nocheck-order 6574Do not check that both input files are in sorted order. This is the default. 6575 6576@item -e @var{string} 6577@opindex -e 6578Replace those output fields that are missing in the input with @var{string}. 6579I.e., missing fields specified with the @option{-12jo} options. 6580 6581@item --header 6582@opindex --header 6583Treat the first line of each input file as a header line. The header lines 6584will be joined and printed as the first output line. If @option{-o} is used to 6585specify output format, the header line will be printed according to the 6586specified format. The header lines will not be checked for ordering even if 6587@option{--check-order} is specified. Also if the header lines from each file 6588do not match, the heading fields from the first file will be used. 6589 6590@item -i 6591@itemx --ignore-case 6592@opindex -i 6593@opindex --ignore-case 6594Ignore differences in case when comparing keys. 6595With this option, the lines of the input files must be ordered in the same way. 6596Use @samp{sort -f} to produce this ordering. 6597 6598@item -1 @var{field} 6599@opindex -1 6600Join on field @var{field} (a positive integer) of file 1. 6601 6602@item -2 @var{field} 6603@opindex -2 6604Join on field @var{field} (a positive integer) of file 2. 6605 6606@item -j @var{field} 6607Equivalent to @option{-1 @var{field} -2 @var{field}}. 6608 6609@item -o @var{field-list} 6610@itemx -o auto 6611If the keyword @samp{auto} is specified, infer the output format from 6612the first line in each file. This is the same as the default output format 6613but also ensures the same number of fields are output for each line. 6614Missing fields are replaced with the @option{-e} option and extra fields 6615are discarded. 6616 6617Otherwise, construct each output line according to the format in 6618@var{field-list}. Each element in @var{field-list} is either the single 6619character @samp{0} or has the form @var{m.n} where the file number, @var{m}, 6620is @samp{1} or @samp{2} and @var{n} is a positive field number. 6621 6622A field specification of @samp{0} denotes the join field. 6623In most cases, the functionality of the @samp{0} field spec 6624may be reproduced using the explicit @var{m.n} that corresponds 6625to the join field. However, when printing unpairable lines 6626(using either of the @option{-a} or @option{-v} options), there is no way 6627to specify the join field using @var{m.n} in @var{field-list} 6628if there are unpairable lines in both files. 6629To give @command{join} that functionality, POSIX invented the @samp{0} 6630field specification notation. 6631 6632The elements in @var{field-list} 6633are separated by commas or blanks. 6634Blank separators typically need to be quoted for the shell. For 6635example, the commands @samp{join -o 1.2,2.2} and @samp{join -o '1.2 66362.2'} are equivalent. 6637 6638All output lines -- including those printed because of any @option{-a} 6639or @option{-v} option -- are subject to the specified @var{field-list}. 6640 6641@item -t @var{char} 6642Use character @var{char} as the input and output field separator. 6643Treat as significant each occurrence of @var{char} in the input file. 6644Use @samp{sort -t @var{char}}, without the @option{-b} option of 6645@samp{sort}, to produce this ordering. If @samp{join -t ''} is specified, 6646the whole line is considered, matching the default operation of sort. 6647If @samp{-t '\0'} is specified then the ASCII NUL 6648character is used to delimit the fields. 6649 6650@item -v @var{file-number} 6651Print a line for each unpairable line in file @var{file-number} 6652(either @samp{1} or @samp{2}), instead of the normal output. 6653 6654@optZeroTerminated 6655@newlineFieldSeparator 6656 6657@end table 6658 6659@exitstatus 6660 6661@set JOIN_COMMAND 6662@checkOrderOption{join} 6663@clear JOIN_COMMAND 6664 6665 6666 6667@node Sorting files for join 6668@subsection Pre-sorting 6669 6670@command{join} requires sorted input files. Each input file should be 6671sorted according to the key (=field/column number) used in 6672@command{join}. The recommended sorting option is @samp{sort -k 1b,1} 6673(assuming the desired key is in the first column). 6674 6675@noindent Typical usage: 6676@example 6677@group 6678$ sort -k 1b,1 file1 > file1.sorted 6679$ sort -k 1b,1 file2 > file2.sorted 6680$ join file1.sorted file2.sorted > file3 6681@end group 6682@end example 6683 6684@vindex LC_COLLATE 6685Normally, the sort order is that of the 6686collating sequence specified by the @env{LC_COLLATE} locale. Unless 6687the @option{-t} option is given, the sort comparison ignores blanks at 6688the start of the join field, as in @code{sort -b}. If the 6689@option{--ignore-case} option is given, the sort comparison ignores 6690the case of characters in the join field, as in @code{sort -f}: 6691 6692@example 6693@group 6694$ sort -k 1bf,1 file1 > file1.sorted 6695$ sort -k 1bf,1 file2 > file2.sorted 6696$ join --ignore-case file1.sorted file2.sorted > file3 6697@end group 6698@end example 6699 6700The @command{sort} and @command{join} commands should use consistent 6701locales and options if the output of @command{sort} is fed to 6702@command{join}. You can use a command like @samp{sort -k 1b,1} to 6703sort a file on its default join field, but if you select a non-default 6704locale, join field, separator, or comparison options, then you should 6705do so consistently between @command{join} and @command{sort}. 6706 6707@noindent To avoid any locale-related issues, it is recommended to use the 6708@samp{C} locale for both commands: 6709 6710@example 6711@group 6712$ LC_ALL=C sort -k 1b,1 file1 > file1.sorted 6713$ LC_ALL=C sort -k 1b,1 file2 > file2.sorted 6714$ LC_ALL=C join file1.sorted file2.sorted > file3 6715@end group 6716@end example 6717 6718 6719@node Working with fields 6720@subsection Working with fields 6721 6722Use @option{-1},@option{-2} to set the key fields for each of the input files. 6723Ensure the preceding @command{sort} commands operated on the same fields. 6724 6725@noindent 6726The following example joins two files, using the values from seventh field 6727of the first file and the third field of the second file: 6728 6729@example 6730@group 6731$ sort -k 7b,7 file1 > file1.sorted 6732$ sort -k 3b,3 file2 > file2.sorted 6733$ join -1 7 -2 3 file1.sorted file2.sorted > file3 6734@end group 6735@end example 6736 6737@noindent 6738If the field number is the same for both files, use @option{-j}: 6739 6740@example 6741@group 6742$ sort -k4b,4 file1 > file1.sorted 6743$ sort -k4b,4 file2 > file2.sorted 6744$ join -j4 file1.sorted file2.sorted > file3 6745@end group 6746@end example 6747 6748@noindent 6749Both @command{sort} and @command{join} operate of whitespace-delimited 6750fields. To specify a different delimiter, use @option{-t} in @emph{both}: 6751 6752@example 6753@group 6754$ sort -t, -k3b,3 file1 > file1.sorted 6755$ sort -t, -k3b,3 file2 > file2.sorted 6756$ join -t, -j3 file1.sorted file2.sorted > file3 6757@end group 6758@end example 6759 6760@noindent 6761To specify a tab (@sc{ascii} 0x09) character instead of whitespace, 6762use:@footnote{the @code{$'\t'} is supported in most modern shells. 6763For older shells, use a literal tab.} 6764 6765@example 6766@group 6767$ sort -t$'\t' -k3b,3 file1 > file1.sorted 6768$ sort -t$'\t' -k3b,3 file2 > file2.sorted 6769$ join -t$'\t' -j3 file1.sorted file2.sorted > file3 6770@end group 6771@end example 6772 6773 6774@noindent 6775If @samp{join -t ''} is specified then the whole line is considered which 6776matches the default operation of sort: 6777 6778@example 6779@group 6780$ sort file1 > file1.sorted 6781$ sort file2 > file2.sorted 6782$ join -t '' file1.sorted file2.sorted > file3 6783@end group 6784@end example 6785 6786 6787@node Paired and unpaired lines 6788@subsection Controlling @command{join}'s field matching 6789 6790In this section the @command{sort} commands are omitted for brevity. 6791Sorting the files before joining is still required. 6792 6793@command{join}'s default behavior is to print only lines common to 6794both input files. Use @option{-a} and @option{-v} to print unpairable lines 6795from one or both files. 6796 6797@noindent 6798All examples below use the following two (pre-sorted) input files: 6799 6800@multitable @columnfractions .5 .5 6801@item 6802@example 6803$ cat file1 6804a 1 6805b 2 6806@end example 6807 6808@tab 6809@example 6810$ cat file2 6811a A 6812c C 6813@end example 6814@end multitable 6815 6816 6817@c TODO: Find better column widths that work for both HTML and PDF 6818@c and disable indentation of @example. 6819@multitable @columnfractions 0.5 0.5 6820 6821@headitem Command @tab Outcome 6822 6823 6824@item 6825@example 6826$ join file1 file2 6827a 1 A 6828@end example 6829@tab 6830common lines 6831(@emph{intersection}) 6832 6833 6834 6835@item 6836@example 6837$ join -a 1 file1 file2 6838a 1 A 6839b 2 6840@end example 6841@tab 6842common lines @emph{and} unpaired 6843lines from the first file 6844 6845 6846@item 6847@example 6848$ join -a 2 file1 file2 6849a 1 A 6850c C 6851@end example 6852@tab 6853common lines @emph{and} unpaired lines from the second file 6854 6855 6856@item 6857@example 6858$ join -a 1 -a 2 file1 file2 6859a 1 A 6860b 2 6861c C 6862@end example 6863@tab 6864all lines (paired and unpaired) from both files 6865(@emph{union}). 6866@* 6867see note below regarding @code{-o auto}. 6868 6869 6870@item 6871@example 6872$ join -v 1 file1 file2 6873b 2 6874@end example 6875@tab 6876unpaired lines from the first file 6877(@emph{difference}) 6878 6879 6880@item 6881@example 6882$ join -v 2 file1 file2 6883c C 6884@end example 6885@tab 6886unpaired lines from the second file 6887(@emph{difference}) 6888 6889 6890@item 6891@example 6892$ join -v 1 -v 2 file1 file2 6893b 2 6894c C 6895@end example 6896@tab 6897unpaired lines from both files, omitting common lines 6898(@emph{symmetric difference}). 6899 6900 6901@end multitable 6902 6903@noindent 6904The @option{-o auto -e X} options are useful when dealing with unpaired lines. 6905The following example prints all lines (common and unpaired) from both files. 6906Without @option{-o auto} it is not easy to discern which fields originate from 6907which file: 6908 6909@example 6910$ join -a 1 -a 2 file1 file2 6911a 1 A 6912b 2 6913c C 6914 6915$ join -o auto -e X -a 1 -a 2 file1 file2 6916a 1 A 6917b 2 X 6918c X C 6919@end example 6920 6921 6922If the input has no unpairable lines, a GNU extension is 6923available; the sort order can be any order that considers two fields 6924to be equal if and only if the sort comparison described above 6925considers them to be equal. For example: 6926 6927@example 6928@group 6929$ cat file1 6930a a1 6931c c1 6932b b1 6933 6934$ cat file2 6935a a2 6936c c2 6937b b2 6938 6939$ join file1 file2 6940a a1 a2 6941c c1 c2 6942b b1 b2 6943@end group 6944@end example 6945 6946 6947@node Header lines 6948@subsection Header lines 6949 6950The @option{--header} option can be used when the files to join 6951have a header line which is not sorted: 6952 6953@example 6954@group 6955$ cat file1 6956Name Age 6957Alice 25 6958Charlie 34 6959 6960$ cat file2 6961Name Country 6962Alice France 6963Bob Spain 6964 6965$ join --header -o auto -e NA -a1 -a2 file1 file2 6966Name Age Country 6967Alice 25 France 6968Bob NA Spain 6969Charlie 34 NA 6970@end group 6971@end example 6972 6973 6974To sort a file with a header line, use GNU @command{sed -u}. 6975The following example sort the files but keeps the first line of each 6976file in place: 6977 6978@example 6979@group 6980$ ( sed -u 1q ; sort -k2b,2 ) < file1 > file1.sorted 6981$ ( sed -u 1q ; sort -k2b,2 ) < file2 > file2.sorted 6982$ join --header -o auto -e NA -a1 -a2 file1.sorted file2.sorted > file3 6983@end group 6984@end example 6985 6986@node Set operations 6987@subsection Union, Intersection and Difference of files 6988 6989Combine @command{sort}, @command{uniq} and @command{join} to 6990perform the equivalent of set operations on files: 6991 6992@c From https://www.pixelbeat.org/cmdline.html#sets 6993@multitable @columnfractions 0.5 0.5 6994@headitem Command @tab outcome 6995@item @code{sort -u file1 file2} 6996@tab Union of unsorted files 6997 6998@item @code{sort file1 file2 | uniq -d} 6999@tab Intersection of unsorted files 7000 7001@item @code{sort file1 file1 file2 | uniq -u} 7002@tab Difference of unsorted files 7003 7004@item @code{sort file1 file2 | uniq -u} 7005@tab Symmetric Difference of unsorted files 7006 7007@item @code{join -t '' -a1 -a2 file1 file2} 7008@tab Union of sorted files 7009 7010@item @code{join -t '' file1 file2} 7011@tab Intersection of sorted files 7012 7013@item @code{join -t '' -v2 file1 file2} 7014@tab Difference of sorted files 7015 7016@item @code{join -t '' -v1 -v2 file1 file2} 7017@tab Symmetric Difference of sorted files 7018 7019@end multitable 7020 7021All examples above operate on entire lines and not on specific fields: 7022@command{sort} without @option{-k} and @command{join -t ''} both consider 7023entire lines as the key. 7024 7025 7026@node Operating on characters 7027@chapter Operating on characters 7028 7029@cindex operating on characters 7030 7031These commands operate on individual characters. 7032 7033@menu 7034* tr invocation:: Translate, squeeze, and/or delete characters. 7035* expand invocation:: Convert tabs to spaces. 7036* unexpand invocation:: Convert spaces to tabs. 7037@end menu 7038 7039 7040@node tr invocation 7041@section @command{tr}: Translate, squeeze, and/or delete characters 7042 7043@pindex tr 7044 7045Synopsis: 7046 7047@example 7048tr [@var{option}]@dots{} @var{string1} [@var{string2}] 7049@end example 7050 7051@command{tr} copies standard input to standard output, performing 7052one of the following operations: 7053 7054@itemize @bullet 7055@item 7056translate, and optionally squeeze repeated characters in the result, 7057@item 7058squeeze repeated characters, 7059@item 7060delete characters, 7061@item 7062delete characters, then squeeze repeated characters from the result. 7063@end itemize 7064 7065The @var{string1} and @var{string2} operands define arrays of 7066characters @var{array1} and @var{array2}. By default @var{array1} 7067lists input characters that @command{tr} operates on, and @var{array2} 7068lists corresponding translations. In some cases the second operand is 7069omitted. 7070 7071The program accepts the following options. Also see @ref{Common options}. 7072Options must precede operands. 7073 7074@table @samp 7075 7076@item -c 7077@itemx -C 7078@itemx --complement 7079@opindex -c 7080@opindex -C 7081@opindex --complement 7082Instead of @var{array1}, use its complement (all characters not 7083specified by @var{string1}), in ascending order. Use this option with 7084caution in multibyte locales where its meaning is not always clear 7085or portable; see @ref{Character arrays}. 7086 7087@item -d 7088@itemx --delete 7089@opindex -d 7090@opindex --delete 7091Delete characters in @var{array1}; do not translate. 7092 7093@item -s 7094@itemx --squeeze-repeats 7095@opindex -s 7096@opindex --squeeze-repeats 7097Replace each sequence of a repeated character that is listed in 7098the last specified @var{array}, with a single occurrence of that character. 7099 7100@item -t 7101@itemx --truncate-set1 7102@opindex -t 7103@opindex --truncate-set1 7104Truncate @var{array1} to the length of @var{array2}. 7105 7106@end table 7107 7108 7109@exitstatus 7110 7111@menu 7112* Character arrays:: Specifying arrays of characters. 7113* Translating:: Changing characters to other characters. 7114* Squeezing and deleting:: Removing characters. 7115@end menu 7116 7117 7118@node Character arrays 7119@subsection Specifying arrays of characters 7120 7121@cindex arrays of characters in @command{tr} 7122 7123The @var{string1} and @var{string2} operands are not regular 7124expressions, even though they may look similar. Instead, they 7125merely represent arrays of characters. As a GNU extension to POSIX, 7126an empty string operand represents an empty array of characters. 7127 7128The interpretation of @var{string1} and @var{string2} depends on locale. 7129GNU @command{tr} fully supports only safe single-byte locales, 7130where each possible input byte represents a single character. 7131Unfortunately, this means GNU @command{tr} will not handle commands 7132like @samp{tr @"o @L{}} the way you might expect, 7133since (assuming a UTF-8 encoding) this is equivalent to 7134@samp{tr '\303\266' '\305\201'} and GNU @command{tr} will 7135simply transliterate all @samp{\303} bytes to @samp{\305} bytes, etc. 7136POSIX does not clearly specify the behavior of @command{tr} in locales 7137where characters are represented by byte sequences instead of by 7138individual bytes, or where data might contain invalid bytes that are 7139encoding errors. To avoid problems in this area, you can run 7140@command{tr} in a safe single-byte locale by using a shell command 7141like @samp{LC_ALL=C tr} instead of plain @command{tr}. 7142 7143Although most characters simply represent themselves in @var{string1} 7144and @var{string2}, the strings can contain shorthands listed below, 7145for convenience. Some shorthands can be used only in @var{string1} or 7146@var{string2}, as noted below. 7147 7148@table @asis 7149 7150@item Backslash escapes 7151@cindex backslash escapes 7152 7153The following backslash escape sequences are recognized: 7154 7155@table @samp 7156@item \a 7157Bell (BEL, Control-G). 7158@item \b 7159Backspace (BS, Control-H). 7160@item \f 7161Form feed (FF, Control-L). 7162@item \n 7163Newline (LF, Control-J). 7164@item \r 7165Carriage return (CR, Control-M). 7166@item \t 7167Tab (HT, Control-I). 7168@item \v 7169Vertical tab (VT, Control-K). 7170@item \@var{ooo} 7171The eight-bit byte with the value given by @var{ooo}, which is the longest 7172sequence of one to three octal digits following the backslash. 7173For portability, @var{ooo} should represent a value that fits in eight bits. 7174As a GNU extension to POSIX, if the value would not fit, then only the 7175first two digits of @var{ooo} are used, e.g., @samp{\400} 7176is equivalent to @samp{\0400} and represents a two-byte sequence. 7177@item \\ 7178A backslash. 7179@end table 7180 7181It is an error if no character follows an unescaped backslash. 7182As a GNU extension, a backslash followed by a character not listed 7183above is interpreted as that character, removing any special 7184significance; this can be used to escape the characters 7185@samp{[} and @samp{-} when they would otherwise be special. 7186 7187@item Ranges 7188@cindex ranges 7189 7190The notation @samp{@var{m}-@var{n}} expands to the characters 7191from @var{m} through @var{n}, in ascending order. @var{m} should 7192not collate after @var{n}; if it does, an error results. As an example, 7193@samp{0-9} is the same as @samp{0123456789}. 7194 7195GNU @command{tr} does not support the System V syntax that uses square 7196brackets to enclose ranges. Translations specified in that format 7197sometimes work as expected, since the brackets are often transliterated 7198to themselves. However, they should be avoided because they sometimes 7199behave unexpectedly. For example, @samp{tr -d '[0-9]'} deletes brackets 7200as well as digits. 7201 7202Many historically common and even accepted uses of ranges are not fully 7203portable. For example, on EBCDIC hosts using the @samp{A-Z} 7204range will not do what most would expect because @samp{A} through @samp{Z} 7205are not contiguous as they are in ASCII@. 7206One way to work around this is to use character classes (see below). 7207Otherwise, it is most portable (and most ugly) to enumerate the members 7208of the ranges. 7209 7210@item Repeated characters 7211@cindex repeated characters 7212 7213The notation @samp{[@var{c}*@var{n}]} in @var{string2} expands to @var{n} 7214copies of character @var{c}. Thus, @samp{[y*6]} is the same as 7215@samp{yyyyyy}. The notation @samp{[@var{c}*]} in @var{string2} expands 7216to as many copies of @var{c} as are needed to make @var{array2} as long as 7217@var{array1}. If @var{n} begins with @samp{0}, it is interpreted in 7218octal, otherwise in decimal. A zero-valued @var{n} is treated as if 7219it were absent. 7220 7221@item Character classes 7222@cindex character classes 7223 7224The notation @samp{[:@var{class}:]} expands to all characters in 7225the (predefined) class @var{class}. When the @option{--delete} (@option{-d}) 7226and @option{--squeeze-repeats} (@option{-s}) options are both given, any 7227character class can be used in @var{string2}. Otherwise, only the 7228character classes @code{lower} and @code{upper} are accepted in 7229@var{string2}, and then only if the corresponding character class 7230(@code{upper} and @code{lower}, respectively) is specified in the same 7231relative position in @var{string1}. Doing this specifies case conversion. 7232Except for case conversion, a class's characters appear in no particular order. 7233The class names are given below; an error results when an invalid class 7234name is given. 7235 7236@table @code 7237@item alnum 7238@opindex alnum 7239Letters and digits. 7240@item alpha 7241@opindex alpha 7242Letters. 7243@item blank 7244@opindex blank 7245Horizontal whitespace. 7246@item cntrl 7247@opindex cntrl 7248Control characters. 7249@item digit 7250@opindex digit 7251Digits. 7252@item graph 7253@opindex graph 7254Printable characters, not including space. 7255@item lower 7256@opindex lower 7257Lowercase letters. 7258@item print 7259@opindex print 7260Printable characters, including space. 7261@item punct 7262@opindex punct 7263Punctuation characters. 7264@item space 7265@opindex space 7266Horizontal or vertical whitespace. 7267@item upper 7268@opindex upper 7269Uppercase letters. 7270@item xdigit 7271@opindex xdigit 7272Hexadecimal digits. 7273@end table 7274 7275@item Equivalence classes 7276@cindex equivalence classes 7277 7278The syntax @samp{[=@var{c}=]} expands to all characters equivalent to 7279@var{c}, in no particular order. These equivalence classes are 7280allowed in @var{string2} only when @option{--delete} (@option{-d}) and 7281@option{--squeeze-repeats} @option{-s} are both given. 7282 7283Although equivalence classes are intended to support non-English alphabets, 7284there seems to be no standard way to define them or determine their 7285contents. Therefore, they are not fully implemented in GNU @command{tr}; 7286each character's equivalence class consists only of that character, 7287which is of no particular use. 7288 7289@end table 7290 7291 7292@node Translating 7293@subsection Translating 7294 7295@cindex translating characters 7296 7297@command{tr} performs translation when @var{string1} and @var{string2} are 7298both given and the @option{--delete} (@option{-d}) option is not given. 7299@command{tr} translates each character of its input that is in @var{array1} 7300to the corresponding character in @var{array2}. Characters not in 7301@var{array1} are passed through unchanged. 7302 7303As a GNU extension to POSIX, when a character appears more than once 7304in @var{array1}, only the final instance is used. For example, these 7305two commands are equivalent: 7306 7307@example 7308tr aaa xyz 7309tr a z 7310@end example 7311 7312A common use of @command{tr} is to convert lowercase characters to 7313uppercase. This can be done in many ways. Here are three of them: 7314 7315@example 7316tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 7317tr a-z A-Z 7318tr '[:lower:]' '[:upper:]' 7319@end example 7320 7321@noindent 7322However, ranges like @code{a-z} are not portable outside the C locale. 7323 7324When @command{tr} is performing translation, @var{array1} and @var{array2} 7325typically have the same length. If @var{array1} is shorter than 7326@var{array2}, the extra characters at the end of @var{array2} are ignored. 7327 7328On the other hand, making @var{array1} longer than @var{array2} is not 7329portable; POSIX says that the result is undefined. In this situation, 7330BSD @command{tr} pads @var{array2} to the length of @var{array1} by repeating 7331the last character of @var{array2} as many times as necessary. System V 7332@command{tr} truncates @var{array1} to the length of @var{array2}. 7333 7334By default, GNU @command{tr} handles this case like BSD @command{tr}. 7335When the @option{--truncate-set1} (@option{-t}) option is given, 7336GNU @command{tr} handles this case like the System V @command{tr} 7337instead. This option is ignored for operations other than translation. 7338 7339Acting like System V @command{tr} in this case breaks the relatively common 7340BSD idiom: 7341 7342@example 7343tr -cs A-Za-z0-9 '\012' 7344@end example 7345 7346@noindent 7347because it converts only zero bytes (the first element in the 7348complement of @var{array1}), rather than all non-alphanumerics, to 7349newlines. 7350 7351@noindent 7352By the way, the above idiom is not portable because it uses ranges, and 7353it assumes that the octal code for newline is 012. Here is a better 7354way to write it: 7355 7356@example 7357tr -cs '[:alnum:]' '[\n*]' 7358@end example 7359 7360 7361@node Squeezing and deleting 7362@subsection Squeezing repeats and deleting 7363 7364@cindex squeezing repeat characters 7365@cindex deleting characters 7366@cindex removing characters 7367 7368When given just the @option{--delete} (@option{-d}) option, @command{tr} 7369removes any input characters that are in @var{array1}. 7370 7371When given just the @option{--squeeze-repeats} (@option{-s}) option 7372and not translating, @command{tr} replaces each input sequence of a 7373repeated character that is in @var{array1} with a single occurrence of 7374that character. 7375 7376When given both @option{--delete} and @option{--squeeze-repeats}, @command{tr} 7377first performs any deletions using @var{array1}, then squeezes repeats 7378from any remaining characters using @var{array2}. 7379 7380The @option{--squeeze-repeats} option may also be used when translating, 7381in which case @command{tr} first performs translation, then squeezes 7382repeats from any remaining characters using @var{array2}. 7383 7384Here are some examples to illustrate various combinations of options: 7385 7386@itemize @bullet 7387 7388@item 7389Remove all zero bytes: 7390 7391@example 7392tr -d '\0' 7393@end example 7394 7395@item 7396Put all words on lines by themselves. This converts all 7397non-alphanumeric characters to newlines, then squeezes each string 7398of repeated newlines into a single newline: 7399 7400@example 7401tr -cs '[:alnum:]' '[\n*]' 7402@end example 7403 7404@item 7405Convert each sequence of repeated newlines to a single newline. 7406I.e., delete empty lines: 7407 7408@example 7409tr -s '\n' 7410@end example 7411 7412@item 7413Find doubled occurrences of words in a document. 7414@c Separate the following two "the"s, so typo checkers don't complain. 7415For example, people often write ``the @w{}the'' with the repeated words 7416separated by a newline. The Bourne shell script below works first 7417by converting each sequence of punctuation and blank characters to a 7418single newline. That puts each ``word'' on a line by itself. 7419Next it maps all uppercase characters to lower case, and finally it 7420runs @command{uniq} with the @option{-d} option to print out only the words 7421that were repeated. 7422 7423@example 7424#!/bin/sh 7425cat -- "$@@" \ 7426 | tr -s '[:punct:][:blank:]' '[\n*]' \ 7427 | tr '[:upper:]' '[:lower:]' \ 7428 | uniq -d 7429@end example 7430 7431@item 7432Deleting a small set of characters is usually straightforward. For example, 7433to remove all @samp{a}s, @samp{x}s, and @samp{M}s you would do this: 7434 7435@example 7436tr -d axM 7437@end example 7438 7439However, when @samp{-} is one of those characters, it can be tricky because 7440@samp{-} has special meanings. Performing the same task as above but also 7441removing all @samp{-} characters, we might try @code{tr -d -axM}, but 7442that would fail because @command{tr} would try to interpret @option{-a} as 7443a command-line option. Alternatively, we could try putting the hyphen 7444inside the string, @code{tr -d a-xM}, but that wouldn't work either because 7445it would make @command{tr} interpret @code{a-x} as the range of characters 7446@samp{a}@dots{}@samp{x} rather than the three. 7447One way to solve the problem is to put the hyphen at the end of the list 7448of characters: 7449 7450@example 7451tr -d axM- 7452@end example 7453 7454Or you can use @samp{--} to terminate option processing: 7455 7456@example 7457tr -d -- -axM 7458@end example 7459 7460@end itemize 7461 7462 7463@node expand invocation 7464@section @command{expand}: Convert tabs to spaces 7465 7466@pindex expand 7467@cindex tabs to spaces, converting 7468@cindex converting tabs to spaces 7469 7470@command{expand} writes the contents of each given @var{file}, or standard 7471input if none are given or for a @var{file} of @samp{-}, to standard 7472output, with tab characters converted to the appropriate number of 7473spaces. Synopsis: 7474 7475@example 7476expand [@var{option}]@dots{} [@var{file}]@dots{} 7477@end example 7478 7479By default, @command{expand} converts all tabs to spaces. It preserves 7480backspace characters in the output; they decrement the column count for 7481tab calculations. The default action is equivalent to @option{-t 8} (set 7482tabs every 8 columns). 7483 7484The program accepts the following options. Also see @ref{Common options}. 7485 7486@table @samp 7487 7488@item -t @var{tab1}[,@var{tab2}]@dots{} 7489@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{} 7490@opindex -t 7491@opindex --tabs 7492@cindex tab stops, setting 7493If only one tab stop is given, set the tabs @var{tab1} spaces apart 7494(default is 8). Otherwise, set the tabs at columns @var{tab1}, 7495@var{tab2}, @dots{} (numbered from 0), and replace any tabs beyond the 7496last tab stop given with single spaces. 7497@macro gnuExpandTabs 7498Tab stops can be separated by blanks as well as by commas. 7499 7500As a GNU extension the last @var{tab} specified can be prefixed 7501with a @samp{/} to indicate a tab size to use for remaining positions. 7502For example, @option{--tabs=2,4,/8} will set tab stops at position 2 and 4, 7503and every multiple of 8 after that. 7504 7505Also the last @var{tab} specified can be prefixed with a @samp{+} to indicate 7506a tab size to use for remaining positions, offset from the final explicitly 7507specified tab stop. 7508For example, to ignore the 1 character gutter present in diff output, 7509one can specify a 1 character offset using @option{--tabs=1,+8}, 7510which will set tab stops at positions 1,9,17,@dots{} 7511@end macro 7512@gnuExpandTabs 7513 7514 7515For compatibility, GNU @command{expand} also accepts the obsolete 7516option syntax, @option{-@var{t1}[,@var{t2}]@dots{}}. New scripts 7517should use @option{-t @var{t1}[,@var{t2}]@dots{}} instead. 7518 7519@item -i 7520@itemx --initial 7521@opindex -i 7522@opindex --initial 7523@cindex initial tabs, converting 7524Only convert initial tabs (those that precede all non-space or non-tab 7525characters) on each line to spaces. 7526 7527@end table 7528 7529@exitstatus 7530 7531 7532@node unexpand invocation 7533@section @command{unexpand}: Convert spaces to tabs 7534 7535@pindex unexpand 7536 7537@command{unexpand} writes the contents of each given @var{file}, or 7538standard input if none are given or for a @var{file} of @samp{-}, to 7539standard output, converting blanks at the beginning of each line into 7540as many tab characters as needed. In the default POSIX 7541locale, a @dfn{blank} is a space or a tab; other locales may specify 7542additional blank characters. Synopsis: 7543 7544@example 7545unexpand [@var{option}]@dots{} [@var{file}]@dots{} 7546@end example 7547 7548By default, @command{unexpand} converts only initial blanks (those 7549that precede all non-blank characters) on each line. It 7550preserves backspace characters in the output; they decrement the column 7551count for tab calculations. By default, tabs are set at every 8th 7552column. 7553 7554The program accepts the following options. Also see @ref{Common options}. 7555 7556@table @samp 7557 7558@item -t @var{tab1}[,@var{tab2}]@dots{} 7559@itemx --tabs=@var{tab1}[,@var{tab2}]@dots{} 7560@opindex -t 7561@opindex --tabs 7562If only one tab stop is given, set the tabs @var{tab1} columns apart 7563instead of the default 8. Otherwise, set the tabs at columns 7564@var{tab1}, @var{tab2}, @dots{} (numbered from 0), and leave blanks 7565beyond the tab stops given unchanged. 7566@gnuExpandTabs 7567 7568This option implies the @option{-a} option. 7569 7570For compatibility, GNU @command{unexpand} supports the obsolete option syntax, 7571@option{-@var{tab1}[,@var{tab2}]@dots{}}, where tab stops must be 7572separated by commas. (Unlike @option{-t}, this obsolete option does 7573not imply @option{-a}.) New scripts should use @option{--first-only -t 7574@var{tab1}[,@var{tab2}]@dots{}} instead. 7575 7576@item -a 7577@itemx --all 7578@opindex -a 7579@opindex --all 7580Also convert all sequences of two or more blanks just before a tab stop, 7581even if they occur after non-blank characters in a line. 7582 7583@end table 7584 7585@exitstatus 7586 7587 7588@node Directory listing 7589@chapter Directory listing 7590 7591This chapter describes the @command{ls} command and its variants @command{dir} 7592and @command{vdir}, which list information about files. 7593 7594@menu 7595* ls invocation:: List directory contents. 7596* dir invocation:: Briefly ls. 7597* vdir invocation:: Verbosely ls. 7598* dircolors invocation:: Color setup for ls, etc. 7599@end menu 7600 7601 7602@node ls invocation 7603@section @command{ls}: List directory contents 7604 7605@pindex ls 7606@cindex directory listing 7607 7608The @command{ls} program lists information about files (of any type, 7609including directories). Options and file arguments can be intermixed 7610arbitrarily, as usual. Later options override earlier options that 7611are incompatible. 7612 7613For non-option command-line arguments that are directories, by default 7614@command{ls} lists the contents of directories, not recursively, and 7615omitting files with names beginning with @samp{.}. For other non-option 7616arguments, by default @command{ls} lists just the file name. If no 7617non-option argument is specified, @command{ls} operates on the current 7618directory, acting as if it had been invoked with a single argument of @samp{.}. 7619 7620@vindex LC_ALL 7621By default, the output is sorted alphabetically, according to the locale 7622settings in effect.@footnote{If you use a non-POSIX 7623locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may 7624produce output that is sorted differently than you're accustomed to. 7625In that case, set the @env{LC_ALL} environment variable to @samp{C}.} 7626If standard output is 7627a terminal, the output is in columns (sorted vertically) and control 7628characters are output as question marks; otherwise, the output is listed 7629one per line and control characters are output as-is. 7630 7631Because @command{ls} is such a fundamental program, it has accumulated many 7632options over the years. They are described in the subsections below; 7633within each section, options are listed alphabetically (ignoring case). 7634The division of options into the subsections is not absolute, since some 7635options affect more than one aspect of @command{ls}'s operation. 7636 7637@cindex exit status of @command{ls} 7638Exit status: 7639 7640@display 76410 success 76421 minor problems (e.g., failure to access a file or directory not 7643 specified as a command line argument. This happens when listing a 7644 directory in which entries are actively being removed or renamed.) 76452 serious trouble (e.g., memory exhausted, invalid option, failure 7646 to access a file or directory specified as a command line argument 7647 or a directory loop) 7648@end display 7649 7650Also see @ref{Common options}. 7651 7652@menu 7653* Which files are listed:: 7654* What information is listed:: 7655* Sorting the output:: 7656* General output formatting:: 7657* Formatting file timestamps:: 7658* Formatting the file names:: 7659@end menu 7660 7661 7662@node Which files are listed 7663@subsection Which files are listed 7664 7665These options determine which files @command{ls} lists information for. 7666By default, @command{ls} lists files and the contents of any 7667directories on the command line, except that in directories it ignores 7668files whose names start with @samp{.}. 7669 7670@table @samp 7671 7672@item -a 7673@itemx --all 7674@opindex -a 7675@opindex --all 7676In directories, do not ignore file names that start with @samp{.}. 7677 7678@item -A 7679@itemx --almost-all 7680@opindex -A 7681@opindex --almost-all 7682In directories, do not ignore all file names that start with @samp{.}; 7683ignore only @file{.} and @file{..}. The @option{--all} (@option{-a}) 7684option overrides this option. 7685 7686@item -B 7687@itemx --ignore-backups 7688@opindex -B 7689@opindex --ignore-backups 7690@cindex backup files, ignoring 7691In directories, ignore files that end with @samp{~}. This option is 7692equivalent to @samp{--ignore='*~' --ignore='.*~'}. 7693 7694@item -d 7695@itemx --directory 7696@opindex -d 7697@opindex --directory 7698List just the names of directories, as with other types of files, rather 7699than listing their contents. 7700@c The following sentence is the same as the one for -F. 7701Do not follow symbolic links listed on the 7702command line unless the @option{--dereference-command-line} (@option{-H}), 7703@option{--dereference} (@option{-L}), or 7704@option{--dereference-command-line-symlink-to-dir} options are specified. 7705 7706@item -H 7707@itemx --dereference-command-line 7708@opindex -H 7709@opindex --dereference-command-line 7710@cindex symbolic links, dereferencing 7711If a command line argument specifies a symbolic link, show information 7712for the file the link references rather than for the link itself. 7713 7714@item --dereference-command-line-symlink-to-dir 7715@opindex --dereference-command-line-symlink-to-dir 7716@cindex symbolic links, dereferencing 7717Do not dereference symbolic links, with one exception: 7718if a command line argument specifies a symbolic link that refers to 7719a directory, show information for that directory rather than for the 7720link itself. 7721This is the default behavior unless long format is being used 7722or any of the following options is in effect: 7723@option{--classify} (@option{-F}), 7724@option{--directory} (@option{-d}), 7725@option{--dereference} (@option{-L}), or 7726@option{--dereference-command-line} (@option{-H})). 7727 7728@item --group-directories-first 7729@opindex --group-directories-first 7730Group all the directories before the files and then sort the 7731directories and the files separately using the selected sort key 7732(see @option{--sort} option). 7733That is, this option specifies a primary sort key, 7734and the @option{--sort} option specifies a secondary key. 7735However, any use of @option{--sort=none} 7736(@option{-U}) disables this option altogether. 7737 7738@item --hide=PATTERN 7739@opindex --hide=@var{pattern} 7740In directories, ignore files whose names match the shell pattern 7741@var{pattern}, unless the @option{--all} (@option{-a}) or 7742@option{--almost-all} (@option{-A}) is also given. This 7743option acts like @option{--ignore=@var{pattern}} except that it has no 7744effect if @option{--all} (@option{-a}) or @option{--almost-all} 7745(@option{-A}) is also given. 7746 7747This option can be useful in shell aliases. For example, if 7748@command{lx} is an alias for @samp{ls --hide='*~'} and @command{ly} is 7749an alias for @samp{ls --ignore='*~'}, then the command @samp{lx -A} 7750lists the file @file{README~} even though @samp{ly -A} would not. 7751 7752@item -I @var{pattern} 7753@itemx --ignore=@var{pattern} 7754@opindex -I 7755@opindex --ignore=@var{pattern} 7756In directories, ignore files whose names match the shell pattern 7757(not regular expression) @var{pattern}. As 7758in the shell, an initial @samp{.} in a file name does not match a 7759wildcard at the start of @var{pattern}. Sometimes it is useful 7760to give this option several times. For example, 7761 7762@example 7763$ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*' 7764@end example 7765 7766The first option ignores names of length 3 or more that start with @samp{.}, 7767the second ignores all two-character names that start with @samp{.} 7768except @samp{..}, and the third ignores names that start with @samp{#}. 7769 7770@item -L 7771@itemx --dereference 7772@opindex -L 7773@opindex --dereference 7774@cindex symbolic links, dereferencing 7775When showing file information for a symbolic link, show information 7776for the file the link references rather than the link itself. 7777However, even with this option, @command{ls} still prints the name 7778of the link itself, not the name of the file that the link points to. 7779 7780@item -R 7781@itemx --recursive 7782@opindex -R 7783@opindex --recursive 7784@cindex recursive directory listing 7785@cindex directory listing, recursive 7786List the contents of all directories recursively. 7787 7788@end table 7789 7790 7791@node What information is listed 7792@subsection What information is listed 7793 7794These options affect the information that @command{ls} displays. By 7795default, only file names are shown. 7796 7797@table @samp 7798 7799@item --author 7800@opindex --author 7801@cindex hurd, author, printing 7802In long format, list each file's author. 7803In GNU/Hurd, file authors can differ from their owners, but in other 7804operating systems the two are the same. 7805 7806@item -D 7807@itemx --dired 7808@opindex -D 7809@opindex --dired 7810@cindex dired Emacs mode support 7811Print an additional line after the main output: 7812 7813@example 7814//DIRED// @var{beg1} @var{end1} @var{beg2} @var{end2} @dots{} 7815@end example 7816 7817@noindent 7818The @var{begn} and @var{endn} are unsigned integers that record the 7819byte position of the beginning and end of each file name in the output. 7820This makes it easy for Emacs to find the names, even when they contain 7821unusual characters such as space or newline, without fancy searching. 7822 7823If directories are being listed recursively via 7824@option{--recursive} (@option{-R}), output a similar 7825line with offsets for each subdirectory name: 7826 7827@example 7828//SUBDIRED// @var{beg1} @var{end1} @dots{} 7829@end example 7830 7831Finally, output a line of the form: 7832 7833@example 7834//DIRED-OPTIONS// --quoting-style=@var{word} 7835@end example 7836 7837@noindent 7838where @var{word} is the quoting style (@pxref{Formatting the file names}). 7839 7840Here is an actual example: 7841 7842@example 7843$ mkdir -p a/sub/deeper a/sub2 7844$ touch a/f1 a/f2 7845$ touch a/sub/deeper/file 7846$ ls -gloRF --dired a 7847 a: 7848 total 8 7849 -rw-r--r-- 1 0 Jun 10 12:27 f1 7850 -rw-r--r-- 1 0 Jun 10 12:27 f2 7851 drwxr-xr-x 3 4096 Jun 10 12:27 sub/ 7852 drwxr-xr-x 2 4096 Jun 10 12:27 sub2/ 7853 7854 a/sub: 7855 total 4 7856 drwxr-xr-x 2 4096 Jun 10 12:27 deeper/ 7857 7858 a/sub/deeper: 7859 total 0 7860 -rw-r--r-- 1 0 Jun 10 12:27 file 7861 7862 a/sub2: 7863 total 0 7864//DIRED// 48 50 84 86 120 123 158 162 217 223 282 286 7865//SUBDIRED// 2 3 167 172 228 240 290 296 7866//DIRED-OPTIONS// --quoting-style=literal 7867@end example 7868 7869The pairs of offsets on the @samp{//DIRED//} line above delimit 7870these names: @file{f1}, @file{f2}, @file{sub}, @file{sub2}, @file{deeper}, 7871@file{file}. 7872The offsets on the @samp{//SUBDIRED//} line delimit the following 7873directory names: @file{a}, @file{a/sub}, @file{a/sub/deeper}, @file{a/sub2}. 7874 7875Here is an example of how to extract the fifth entry name, @samp{deeper}, 7876corresponding to the pair of offsets, 222 and 228: 7877 7878@example 7879$ ls -gloRF --dired a > out 7880$ dd bs=1 skip=222 count=6 < out 2>/dev/null; echo 7881deeper 7882@end example 7883 7884Although the listing above includes a trailing slash 7885for the @samp{deeper} entry, the offsets select the name without 7886the trailing slash. However, if you invoke @command{ls} with @option{--dired} 7887(@option{-D}) along with an option like 7888@option{--escape} (@option{-b}) and operate 7889on a file whose name contains special characters, the backslash 7890@emph{is} included: 7891 7892@example 7893$ touch 'a b' 7894$ ls -blog --dired 'a b' 7895 -rw-r--r-- 1 0 Jun 10 12:28 a\ b 7896//DIRED// 30 34 7897//DIRED-OPTIONS// --quoting-style=escape 7898@end example 7899 7900If you use a quoting style like @option{--quoting-style=c} (@option{-Q}) 7901that adds quote marks, then the offsets include the quote marks. 7902So beware that the user may select the quoting style via the environment 7903variable @env{QUOTING_STYLE}@. Hence, applications using @option{--dired} 7904should either specify an explicit @option{--quoting-style=literal} 7905(@option{-N}) option on the command line, or else be 7906prepared to parse the escaped names. 7907 7908The @option{--dired} (@option{-D}) option implies long format output 7909with hyperlinks disabled, and takes precedence over previously specified 7910output formats or hyperlink mode. 7911 7912@item --full-time 7913@opindex --full-time 7914Produce long format, and list times in full. It is 7915equivalent to using @option{--format=long} (@option{-l}) with 7916@option{--time-style=full-iso} (@pxref{Formatting file timestamps}). 7917 7918@item -g 7919@opindex -g 7920Produce long format, but omit owner information. 7921 7922@item -G 7923@itemx --no-group 7924@opindex -G 7925@opindex --no-group 7926Inhibit display of group information in long format. 7927(This is the default in some non-GNU versions of @command{ls}, so we 7928provide this option for compatibility.) 7929 7930@optHumanReadable 7931 7932@item -i 7933@itemx --inode 7934@opindex -i 7935@opindex --inode 7936@cindex inode number, printing 7937Print the inode number (also called the file serial number and index 7938number) of each file to the left of the file name. (This number 7939uniquely identifies each file within a particular file system.) 7940 7941@item -l 7942@itemx --format=long 7943@itemx --format=verbose 7944@opindex -l 7945@opindex --format 7946@opindex long ls @r{format} 7947@opindex verbose ls @r{format} 7948Produce long format. 7949In addition to the name of each file, print the file type, file mode bits, 7950number of hard links, owner name, group name, size, and 7951timestamp (@pxref{Formatting file timestamps}), normally 7952the modification timestamp (the mtime, @pxref{File timestamps}). 7953If the owner or group name cannot be determined, print 7954the owner or group ID instead, right-justified as a cue 7955that it is a number rather than a textual name. 7956Print question marks for other information that 7957cannot be determined. 7958 7959Normally the size is printed as a byte count without punctuation, but 7960this can be overridden (@pxref{Block size}). 7961For example, @option{--human-readable} (@option{-h}) 7962prints an abbreviated, human-readable count, and 7963@samp{--block-size="'1"} prints a byte count with the thousands 7964separator of the current locale. 7965 7966For each directory that is listed, preface the files with a line 7967@samp{total @var{blocks}}, where @var{blocks} is the file system allocation 7968for all files in that directory. The block size currently defaults to 1024 7969bytes, but this can be overridden (@pxref{Block size}). 7970The @var{blocks} computed counts each hard link separately; 7971this is arguably a deficiency. 7972 7973The file type is one of the following characters: 7974 7975@c The commented-out entries are ones we're not sure about. 7976 7977@table @samp 7978@item - 7979regular file 7980@item b 7981block special file 7982@item c 7983character special file 7984@item C 7985high performance (``contiguous data'') file 7986@item d 7987directory 7988@item D 7989door (Solaris) 7990@c @item F 7991@c semaphore, if this is a distinct file type 7992@item l 7993symbolic link 7994@c @item m 7995@c multiplexed file (7th edition Unix; obsolete) 7996@item M 7997off-line (``migrated'') file (Cray DMF) 7998@item n 7999network special file (HP-UX) 8000@item p 8001FIFO (named pipe) 8002@item P 8003port (Solaris) 8004@c @item Q 8005@c message queue, if this is a distinct file type 8006@item s 8007socket 8008@c @item S 8009@c shared memory object, if this is a distinct file type 8010@c @item T 8011@c typed memory object, if this is a distinct file type 8012@c @item w 8013@c whiteout (4.4BSD; not implemented) 8014@item ? 8015some other file type 8016@end table 8017 8018@cindex permissions, output by @command{ls} 8019The file mode bits listed are similar to symbolic mode specifications 8020(@pxref{Symbolic Modes}). But @command{ls} combines multiple bits into the 8021third character of each set of permissions as follows: 8022 8023@table @samp 8024@item s 8025If the set-user-ID or set-group-ID bit and the corresponding executable bit 8026are both set. 8027 8028@item S 8029If the set-user-ID or set-group-ID bit is set but the corresponding 8030executable bit is not set. 8031 8032@item t 8033If the restricted deletion flag or sticky bit, and the 8034other-executable bit, are both set. The restricted deletion flag is 8035another name for the sticky bit. @xref{Mode Structure}. 8036 8037@item T 8038If the restricted deletion flag or sticky bit is set but the 8039other-executable bit is not set. 8040 8041@item x 8042If the executable bit is set and none of the above apply. 8043 8044@item - 8045Otherwise. 8046@end table 8047 8048Following the file mode bits is a single character that specifies 8049whether an alternate access method such as an access control list 8050applies to the file. When the character following the file mode bits is a 8051space, there is no alternate access method. When it is a printing 8052character, then there is such a method. 8053 8054GNU @command{ls} uses a @samp{.} character to indicate a file 8055with a security context, but no other alternate access method. 8056 8057A file with any other combination of alternate access methods 8058is marked with a @samp{+} character. 8059 8060@item -n 8061@itemx --numeric-uid-gid 8062@opindex -n 8063@opindex --numeric-uid-gid 8064@cindex numeric uid and gid 8065@cindex numeric user and group IDs 8066Produce long format, but 8067display right-justified numeric user and group IDs 8068instead of left-justified owner and group names. 8069 8070@item -o 8071@opindex -o 8072Produce long format, but omit group information. 8073It is equivalent to using @option{--format=long} (@option{-l}) 8074with @option{--no-group} (@option{-G}). 8075 8076@item -s 8077@itemx --size 8078@opindex -s 8079@opindex --size 8080@cindex file system allocation 8081@cindex size of files, reporting 8082Print the file system allocation of each file to the left of the file name. 8083This is the amount of file system space used by the file, which is usually a 8084bit more than the file's size, but it can be less if the file has holes. 8085 8086Normally the allocation is printed in units of 80871024 bytes, but this can be overridden (@pxref{Block size}). 8088 8089@cindex NFS mounts from BSD to HP-UX 8090For files that are NFS-mounted from an HP-UX system to a BSD system, 8091this option reports sizes that are half the correct values. On HP-UX 8092systems, it reports sizes that are twice the correct values for files 8093that are NFS-mounted from BSD systems. This is due to a flaw in HP-UX; 8094it also affects the HP-UX @command{ls} program. 8095 8096@optSi 8097 8098@item -Z 8099@itemx --context 8100@opindex -Z 8101@opindex --context 8102@cindex SELinux 8103@cindex security context 8104Display the SELinux security context or @samp{?} if none is found. 8105In long format, print the security context to the left of the size column. 8106 8107@end table 8108 8109 8110@node Sorting the output 8111@subsection Sorting the output 8112 8113@cindex sorting @command{ls} output 8114These options change the order in which @command{ls} sorts the information 8115it outputs. By default, sorting is done by character code 8116(e.g., ASCII order). 8117 8118@table @samp 8119 8120@item -c 8121@itemx --time=ctime 8122@itemx --time=status 8123@opindex -c 8124@opindex --time 8125@opindex ctime@r{, printing or sorting by} 8126@opindex status time@r{, printing or sorting by} 8127@opindex use time@r{, printing or sorting files by} 8128In long format, 8129print the status change timestamp (the ctime) instead of the mtime. 8130When sorting by time or when not using long format, 8131sort according to the ctime. @xref{File timestamps}. 8132 8133@item -f 8134@opindex -f 8135@cindex unsorted directory listing 8136@cindex directory order, listing by 8137Produce an unsorted directory listing. 8138This is equivalent to the combination of @option{--all} (@option{-a}), 8139@option{--sort=none} (@option{-U}), @option{-1}, 8140@option{--color=none}, and @option{--hyperlink=none}, 8141while also disabling any previous use of @option{--size} (@option{-s}). 8142 8143@item -r 8144@itemx --reverse 8145@opindex -r 8146@opindex --reverse 8147@cindex reverse sorting 8148Reverse whatever the sorting method is -- e.g., list files in reverse 8149alphabetical order, youngest first, smallest first, or whatever. 8150This option has no effect when @option{--sort=none} (@option{-U}) 8151is in effect. 8152 8153@item -S 8154@itemx --sort=size 8155@opindex -S 8156@opindex --sort 8157@opindex size of files@r{, sorting files by} 8158Sort by file size, largest first. 8159 8160@item -t 8161@itemx --sort=time 8162@opindex -t 8163@opindex --sort 8164@opindex modification timestamp@r{, sorting files by} 8165Sort by modification timestamp (mtime) by default, newest first. 8166The timestamp to order by can be changed with the @option{--time} option. 8167@xref{File timestamps}. 8168 8169@item -u 8170@itemx --time=atime 8171@itemx --time=access 8172@itemx --time=use 8173@opindex -u 8174@opindex --time 8175@opindex use time@r{, printing or sorting files by} 8176@opindex atime@r{, printing or sorting files by} 8177@opindex access timestamp@r{, printing or sorting files by} 8178In long format, print the last access timestamp (the atime). 8179When sorting by time or when not using long format, 8180sort according to the atime. 8181@xref{File timestamps}. 8182 8183@item --time=mtime 8184@itemx --time=modification 8185@opindex --time 8186@opindex data modification time@r{, printing or sorting files by} 8187@opindex mtime@r{, printing or sorting files by} 8188This is the default timestamp display and sorting mode. 8189In long format, print the last data modification timestamp (the mtime). 8190When sorting by time or when not using long format, 8191sort according to the mtime. 8192@xref{File timestamps}. 8193 8194@item --time=birth 8195@itemx --time=creation 8196@opindex --time 8197@opindex birth time@r{, printing or sorting files by} 8198@opindex creation timestamp@r{, printing or sorting files by} 8199In long format, print the file creation timestamp if available, 8200falling back to the file modification timestamp (mtime) if not. 8201When sorting by time or when not using long format, 8202sort according to the birth time. 8203@xref{File timestamps}. 8204 8205@item -U 8206@itemx --sort=none 8207@opindex -U 8208@opindex --sort 8209@opindex none@r{, sorting option for @command{ls}} 8210Do not sort; list the files in whatever order they are 8211stored in the directory. (Do not do any of the other unrelated things 8212that @option{-f} does.) This can be useful when listing large 8213directories, where sorting can take some time. 8214 8215@item -v 8216@itemx --sort=version 8217@opindex -v 8218@opindex --sort 8219@opindex version@r{, sorting option for @command{ls}} 8220Sort by version name and number, lowest first. It behaves like a default 8221sort, except that each sequence of decimal digits is treated numerically 8222as an index/version number. @xref{Version sort ordering}. 8223 8224@item --sort=width 8225@opindex --sort 8226@opindex width@r{, sorting option for @command{ls}} 8227Sort by printed width of file names. 8228This can be useful with the @option{--format=vertical} (@option{-C}) 8229output format, to most densely display the listed files. 8230 8231@item -X 8232@itemx --sort=extension 8233@opindex -X 8234@opindex --sort 8235@opindex extension@r{, sorting files by} 8236Sort directory contents alphabetically by file extension (characters 8237after the last @samp{.}); files with no extension are sorted first. 8238 8239@end table 8240 8241 8242@node General output formatting 8243@subsection General output formatting 8244 8245These options affect the appearance of the overall output. 8246 8247@table @samp 8248 8249@item --format=single-column 8250@opindex --format 8251@opindex single-column @r{output of files} 8252List one file name per line, with no other information. 8253This is the default for @command{ls} when standard 8254output is not a terminal. See also the @option{--escape} (@option{-b}), 8255@option{--hide-control-chars} (@option{-q}), and @option{--zero} options 8256to disambiguate output of file names containing newline characters. 8257 8258@item -1 8259@opindex -1 8260List one file per line. This is like @option{--format=single-column} 8261except that it has no effect if long format is also in effect. 8262 8263@item -C 8264@itemx --format=vertical 8265@opindex -C 8266@opindex --format 8267@opindex vertical @r{sorted files in columns} 8268List files in columns, sorted vertically, with no other information. 8269This is the default for @command{ls} if standard output is a terminal. 8270It is always the default for the @command{dir} program. 8271GNU @command{ls} uses variable width columns to display as many files as 8272possible in the fewest lines. 8273 8274@item --color [=@var{when}] 8275@opindex --color 8276@cindex color, distinguishing file types with 8277Specify whether to use color for distinguishing file types; @var{when} 8278may be omitted, or one of: 8279@itemize @bullet 8280@item none 8281@vindex none @r{color option} 8282- Do not use color at all. This is the default. 8283@item auto 8284@vindex auto @r{color option} 8285@cindex terminal, using color iff 8286- Only use color if standard output is a terminal. 8287@item always 8288@vindex always @r{color option} 8289- Always use color. 8290@end itemize 8291Specifying @option{--color} and no @var{when} is equivalent to 8292@option{--color=always}. 8293If piping a colored listing through a pager like @command{less}, 8294use the pager's @option{-R} option to pass the color codes to the terminal. 8295 8296@vindex LS_COLORS 8297@vindex SHELL @r{environment variable, and color} 8298Using the @option{--color} option may incur a noticeable 8299performance penalty when run in a large directory, 8300because the default settings require that @command{ls} @code{stat} every 8301single file it lists. 8302However, if you would like most of the file-type coloring 8303but can live without the other coloring options (e.g., 8304executable, orphan, sticky, other-writable, capability), use 8305@command{dircolors} to set the @env{LS_COLORS} environment variable like this, 8306@example 8307eval $(dircolors -p | perl -pe \ 8308 's/^((CAP|S[ET]|O[TR]|M|E)\w+).*/$1 00/' | dircolors -) 8309@end example 8310and on a @code{dirent.d_type}-capable file system, @command{ls} 8311will perform only one @code{stat} call per command line argument. 8312 8313@item -F 8314@itemx --classify [=@var{when}] 8315@itemx --indicator-style=classify 8316@opindex -F 8317@opindex --classify 8318@opindex --indicator-style 8319@cindex file type and executables, marking 8320@cindex executables and file type, marking 8321Append a character to each file name indicating the file type. Also, 8322for regular files that are executable, append @samp{*}. The file type 8323indicators are @samp{/} for directories, @samp{@@} for symbolic links, 8324@samp{|} for FIFOs, @samp{=} for sockets, @samp{>} for doors, 8325and nothing for regular files. 8326@var{when} may be omitted, or one of: 8327@itemize @bullet 8328@item none 8329@vindex none @r{classify option} 8330- Do not classify. This is the default. 8331@item auto 8332@vindex auto @r{classify option} 8333@cindex terminal, using classify iff 8334- Only classify if standard output is a terminal. 8335@item always 8336@vindex always @r{classify option} 8337- Always classify. 8338@end itemize 8339Specifying @option{--classify} and no @var{when} is equivalent to 8340@option{--classify=always}. 8341@c The following sentence is the same as the one for -d. 8342Do not follow symbolic links listed on the 8343command line unless the @option{--dereference-command-line} (@option{-H}), 8344@option{--dereference} (@option{-L}), or 8345@option{--dereference-command-line-symlink-to-dir} options are specified. 8346 8347@item --file-type 8348@itemx --indicator-style=file-type 8349@opindex --file-type 8350@opindex --indicator-style 8351@cindex file type, marking 8352Append a character to each file name indicating the file type. This is 8353like @option{--classify} (@option{-F}, except that executables are not marked. 8354 8355@item --hyperlink [=@var{when}] 8356@opindex --hyperlink 8357@cindex hyperlink, linking to files 8358Output codes recognized by some terminals to link 8359to files using the @samp{file://} URI format. 8360@var{when} may be omitted, or one of: 8361@itemize @bullet 8362@item none 8363@vindex none @r{hyperlink option} 8364- Do not use hyperlinks at all. This is the default. 8365@item auto 8366@vindex auto @r{hyperlink option} 8367@cindex terminal, using hyperlink iff 8368- Only use hyperlinks if standard output is a terminal. 8369@item always 8370@vindex always @r{hyperlink option} 8371- Always use hyperlinks. 8372@end itemize 8373Specifying @option{--hyperlink} and no @var{when} is equivalent to 8374@option{--hyperlink=always}. 8375 8376@item --indicator-style=@var{word} 8377@opindex --indicator-style 8378Append a character indicator with style @var{word} to entry names, 8379as follows: 8380 8381@table @samp 8382@item none 8383Do not append any character indicator; this is the default. 8384@item slash 8385Append @samp{/} for directories. This is the same as the @option{-p} 8386option. 8387@item file-type 8388Append @samp{/} for directories, @samp{@@} for symbolic links, @samp{|} 8389for FIFOs, @samp{=} for sockets, and nothing for regular files. This is 8390the same as the @option{--file-type} option. 8391@item classify 8392Append @samp{*} for executable regular files, otherwise behave as for 8393@samp{file-type}. This is the same as the @option{--classify} 8394(@option{-F}) option. 8395@end table 8396 8397@item -k 8398@itemx --kibibytes 8399@opindex -k 8400@opindex --kibibytes 8401Set the default block size to its normal value of 1024 bytes, 8402overriding any contrary specification in environment variables 8403(@pxref{Block size}). If @option{--block-size}, 8404@option{--human-readable} (@option{-h}), or @option{--si} options are used, 8405they take precedence even if @option{--kibibytes} (@option{-k}) is placed after 8406 8407The @option{--kibibytes} (@option{-k}) option affects the 8408per-directory block count written in long format, 8409and the file system allocation written by the @option{--size} (@option{-s}) 8410option. It does not affect the file size in bytes that is written in 8411long format. 8412 8413@item -m 8414@itemx --format=commas 8415@opindex -m 8416@opindex --format 8417@opindex commas@r{, outputting between files} 8418List files horizontally, with as many as will fit on each line, 8419separated by @samp{, } (a comma and a space), 8420and with no other information. 8421 8422@item -p 8423@itemx --indicator-style=slash 8424@opindex -p 8425@opindex --indicator-style 8426@cindex file type, marking 8427Append a @samp{/} to directory names. 8428 8429@item -x 8430@itemx --format=across 8431@itemx --format=horizontal 8432@opindex -x 8433@opindex --format 8434@opindex across@r{, listing files} 8435@opindex horizontal@r{, listing files} 8436List the files in columns, sorted horizontally. 8437 8438@item -T @var{cols} 8439@itemx --tabsize=@var{cols} 8440@opindex -T 8441@opindex --tabsize 8442Assume that each tab stop is @var{cols} columns wide. The default is 8. 8443@command{ls} uses tabs where possible in the output, for efficiency. If 8444@var{cols} is zero, do not use tabs at all. 8445 8446Some terminal emulators might not properly align columns to the right of a 8447TAB following a non-ASCII byte. You can avoid that issue by using the 8448@option{-T0} option or put @code{TABSIZE=0} in your environment, to tell 8449@command{ls} to align using spaces, not tabs. 8450 8451If you set a terminal's hardware tabs to anything other than the default, 8452you should also use a @command{--tabsize} option or @env{TABSIZE} 8453environment variable either to match the hardware tabs, or to disable 8454the use of hardware tabs. Otherwise, the output of @command{ls} may 8455not line up. For example, if you run the shell command @samp{tabs -4} 8456to set hardware tabs to every four columns, you should also run 8457@samp{export TABSIZE=4} or @samp{export TABSIZE=0}, or use the 8458corresponding @option{--tabsize} options. 8459 8460@item -w @var{cols} 8461@itemx --width=@var{cols} 8462@opindex -w 8463@opindex --width 8464@vindex COLUMNS 8465Assume the screen is @var{cols} columns wide. The default is taken 8466from the terminal settings if possible; otherwise the environment 8467variable @env{COLUMNS} is used if it is set; otherwise the default 8468is 80. With a @var{cols} value of @samp{0}, there is no limit on 8469the length of the output line, and that single output line will 8470be delimited with spaces, not tabs. 8471 8472@item --zero 8473@opindex --zero 8474@outputNUL 8475This option is incompatible with the @option{--dired} (@option{-D}) option. 8476This option also implies the options @option{--show-control-chars}, 8477@option{-1}, @option{--color=none}, and 8478@option{--quoting-style=literal} (@option{-N}). 8479 8480@end table 8481 8482 8483@node Formatting file timestamps 8484@subsection Formatting file timestamps 8485 8486By default, file timestamps are listed in abbreviated form, using 8487a date like @samp{Mar 30@ @ 2020} for non-recent timestamps, and a 8488date-without-year and time like @samp{Mar 30 23:45} for recent timestamps. 8489This format can change depending on the current locale as detailed below. 8490 8491@cindex clock skew 8492A timestamp is considered to be @dfn{recent} if it is less than six 8493months old, and is not dated in the future. If a timestamp dated 8494today is not listed in recent form, the timestamp is in the future, 8495which means you probably have clock skew problems which may break 8496programs like @command{make} that rely on file timestamps. 8497@xref{File timestamps}. 8498 8499@vindex TZ 8500Timestamps are listed according to the time zone rules specified by 8501the @env{TZ} environment variable, or by the system default rules if 8502@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone 8503with @env{TZ}, libc, The GNU C Library Reference Manual}. 8504 8505The following option changes how file timestamps are printed. 8506 8507@table @samp 8508@item --time-style=@var{style} 8509@opindex --time-style 8510@cindex time style 8511List timestamps in style @var{style}. The @var{style} should 8512be one of the following: 8513 8514@table @samp 8515@item +@var{format} 8516@vindex LC_TIME 8517List timestamps using @var{format}, where @var{format} is interpreted 8518like the format argument of @command{date} (@pxref{date invocation}). 8519For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes 8520@command{ls} to list timestamps like @samp{2020-03-30 23:45:56}. As 8521with @command{date}, @var{format}'s interpretation is affected by the 8522@env{LC_TIME} locale category. 8523 8524If @var{format} contains two format strings separated by a newline, 8525the former is used for non-recent files and the latter for recent 8526files; if you want output columns to line up, you may need to insert 8527spaces in one of the two formats. 8528 8529@item full-iso 8530List timestamps in full using ISO 8601-like date, time, and time zone 8531components with nanosecond precision, e.g., @samp{2020-07-21 853223:45:56.477817180 -0400}. This style is equivalent to 8533@samp{+%Y-%m-%d %H:%M:%S.%N %z}. 8534 8535This is useful because the time output includes all the information that 8536is available from the operating system. For example, this can help 8537explain @command{make}'s behavior, since GNU @command{make} 8538uses the full timestamp to determine whether a file is out of date. 8539 8540@item long-iso 8541List ISO 8601 date and time components with minute precision, e.g., 8542@samp{2020-03-30 23:45}. These timestamps are shorter than 8543@samp{full-iso} timestamps, and are usually good enough for everyday 8544work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}. 8545 8546@item iso 8547List ISO 8601 dates for non-recent timestamps (e.g., 8548@samp{2020-03-30@ }), and ISO 8601-like month, day, hour, and 8549minute for recent timestamps (e.g., @samp{03-30 23:45}). These 8550timestamps are uglier than @samp{long-iso} timestamps, but they carry 8551nearly the same information in a smaller space and their brevity helps 8552@command{ls} output fit within traditional 80-column output lines. 8553The following two @command{ls} invocations are equivalent: 8554 8555@example 8556newline=' 8557' 8558ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M" 8559ls -l --time-style="iso" 8560@end example 8561 8562@item locale 8563@vindex LC_TIME 8564List timestamps in a locale-dependent form. For example, a French 8565locale might list non-recent timestamps like @samp{30 mars@ @ @ 2020} 8566and recent timestamps like @samp{30 mars@ @ 23:45}. Locale-dependent 8567timestamps typically consume more space than @samp{iso} timestamps and 8568are harder for programs to parse because locale conventions vary so 8569widely, but they are easier for many people to read. 8570 8571The @env{LC_TIME} locale category specifies the timestamp format. The 8572default POSIX locale uses timestamps like @samp{Mar 30@ 8573@ 2020} and @samp{Mar 30 23:45}; in this locale, the following two 8574@command{ls} invocations are equivalent: 8575 8576@example 8577newline=' 8578' 8579ls -l --time-style="+%b %e %Y$newline%b %e %H:%M" 8580ls -l --time-style="locale" 8581@end example 8582 8583Other locales behave differently. For example, in a German locale, 8584@option{--time-style="locale"} might be equivalent to 8585@option{--time-style="+%e. %b %Y $newline%e. %b %H:%M"} 8586and might generate timestamps like @samp{30. M@"ar 2020@ } and 8587@samp{30. M@"ar 23:45}. 8588 8589@item posix-@var{style} 8590@vindex LC_TIME 8591List POSIX-locale timestamps if the @env{LC_TIME} locale 8592category is POSIX, @var{style} timestamps otherwise. For 8593example, the @samp{posix-long-iso} style lists 8594timestamps like @samp{Mar 30@ @ 2020} and @samp{Mar 30 23:45} when in 8595the POSIX locale, and like @samp{2020-03-30 23:45} otherwise. 8596@end table 8597@end table 8598 8599@vindex TIME_STYLE 8600You can specify the default value of the @option{--time-style} option 8601with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set 8602the default style is @samp{locale}. GNU Emacs 21.3 and 8603later use the @option{--dired} option and therefore can parse any date 8604format, but if you are using Emacs 21.1 or 21.2 and specify a 8605non-POSIX locale you may need to set 8606@samp{TIME_STYLE="posix-long-iso"}. 8607 8608To avoid certain denial-of-service attacks, timestamps that would be 8609longer than 1000 bytes may be treated as errors. 8610 8611 8612@node Formatting the file names 8613@subsection Formatting the file names 8614 8615These options change how file names themselves are printed. 8616 8617@table @samp 8618 8619@item -b 8620@itemx --escape 8621@itemx --quoting-style=escape 8622@opindex -b 8623@opindex --escape 8624@opindex --quoting-style 8625@cindex backslash sequences for file names 8626Quote nongraphic characters in file names using alphabetic and octal 8627backslash sequences like those used in C. 8628 8629@item -N 8630@itemx --literal 8631@itemx --quoting-style=literal 8632@opindex -N 8633@opindex --literal 8634@opindex --quoting-style 8635Do not quote file names. However, with @command{ls} nongraphic 8636characters are still printed as question marks if the output is a 8637terminal and you do not specify the @option{--show-control-chars} 8638option. 8639 8640@item -q 8641@itemx --hide-control-chars 8642@opindex -q 8643@opindex --hide-control-chars 8644Print question marks instead of nongraphic characters in file names. 8645This is the default if the output is a terminal and the program is 8646@command{ls}. 8647 8648@item -Q 8649@itemx --quote-name 8650@itemx --quoting-style=c 8651@opindex -Q 8652@opindex --quote-name 8653@opindex --quoting-style 8654Enclose file names in double quotes and quote nongraphic characters as 8655in C. 8656 8657@item --quoting-style=@var{word} 8658@opindex --quoting-style 8659@cindex quoting style 8660Use style @var{word} to quote file names and other strings that may 8661contain arbitrary characters. The @var{word} should 8662be one of the following: 8663 8664@macro quotingStyles 8665@table @samp 8666@item literal 8667Output strings as-is; this is the same as the @option{--literal} (@option{-N}) 8668option. 8669@item shell 8670Quote strings for the shell if they contain shell metacharacters or would 8671cause ambiguous output. 8672The quoting is suitable for POSIX-compatible shells like 8673@command{bash}, but it does not always work for incompatible shells 8674like @command{csh}. 8675@item shell-always 8676Quote strings for the shell, even if they would normally not require quoting. 8677@item shell-escape 8678Like @samp{shell}, but also quoting non-printable characters using the POSIX 8679proposed @samp{$''} syntax suitable for most shells. 8680@item shell-escape-always 8681Like @samp{shell-escape}, but quote strings even if they would 8682normally not require quoting. 8683@item c 8684Quote strings as for C character string literals, including the 8685surrounding double-quote characters; this is the same as the 8686@option{--quote-name} (@option{-Q}) option. 8687@item escape 8688Quote strings as for C character string literals, except omit the 8689surrounding double-quote 8690characters; this is the same as the @option{--escape} (@option{-b}) option. 8691@item clocale 8692Quote strings as for C character string literals, except use 8693surrounding quotation marks appropriate for the 8694locale. 8695@item locale 8696@c Use @t instead of @samp to avoid duplicate quoting in some output styles. 8697Quote strings as for C character string literals, except use 8698surrounding quotation marks appropriate for the locale, and quote 8699@t{'like this'} instead of @t{"like 8700this"} in the default C locale. This looks nicer on many displays. 8701@end table 8702@end macro 8703@quotingStyles 8704 8705You can specify the default value of the @option{--quoting-style} option 8706with the environment variable @env{QUOTING_STYLE}@. If that environment 8707variable is not set, the default value is @samp{shell-escape} when the 8708output is a terminal, and @samp{literal} otherwise. 8709 8710@item --show-control-chars 8711@opindex --show-control-chars 8712Print nongraphic characters as-is in file names. 8713This is the default unless the output is a terminal and the program is 8714@command{ls}. 8715 8716@end table 8717 8718 8719@node dir invocation 8720@section @command{dir}: Briefly list directory contents 8721 8722@pindex dir 8723@cindex directory listing, brief 8724 8725@command{dir} is equivalent to @code{ls -C 8726-b}; that is, by default files are listed in columns, sorted vertically, 8727and special characters are represented by backslash escape sequences. 8728 8729@xref{ls invocation, @command{ls}}. 8730 8731 8732@node vdir invocation 8733@section @command{vdir}: Verbosely list directory contents 8734 8735@pindex vdir 8736@cindex directory listing, verbose 8737 8738@command{vdir} is equivalent to @code{ls -l 8739-b}; that is, by default files are listed in long format and special 8740characters are represented by backslash escape sequences. 8741 8742@xref{ls invocation, @command{ls}}. 8743 8744@node dircolors invocation 8745@section @command{dircolors}: Color setup for @command{ls} 8746 8747@pindex dircolors 8748@cindex color setup 8749@cindex setup for color 8750 8751@command{dircolors} outputs a sequence of shell commands to set up the 8752terminal for color output from @command{ls} (and @command{dir}, etc.). 8753Typical usage: 8754 8755@example 8756eval "$(dircolors [@var{option}]@dots{} [@var{file}])" 8757@end example 8758 8759If @var{file} is specified, @command{dircolors} reads it to determine which 8760colors to use for which file types and extensions. Otherwise, a 8761precompiled database is used. For details on the format of these files, 8762run @samp{dircolors --print-database}. 8763 8764To make @command{dircolors} read a @file{~/.dircolors} file if it 8765exists, you can put the following lines in your @file{~/.bashrc} (or 8766adapt them to your favorite shell): 8767 8768@example 8769d=.dircolors 8770test -r $d && eval "$(dircolors $d)" 8771@end example 8772 8773@vindex LS_COLORS 8774@vindex SHELL @r{environment variable, and color} 8775The output is a shell command to set the @env{LS_COLORS} environment 8776variable. You can specify the shell syntax to use on the command line, 8777or @command{dircolors} will guess it from the value of the @env{SHELL} 8778environment variable. 8779 8780The program accepts the following options. Also see @ref{Common options}. 8781 8782@table @samp 8783@item -b 8784@itemx --sh 8785@itemx --bourne-shell 8786@opindex -b 8787@opindex --sh 8788@opindex --bourne-shell 8789@cindex Bourne shell syntax for color setup 8790@cindex @command{sh} syntax for color setup 8791Output Bourne shell commands. This is the default if the @env{SHELL} 8792environment variable is set and does not end with @samp{csh} or 8793@samp{tcsh}. 8794 8795@item -c 8796@itemx --csh 8797@itemx --c-shell 8798@opindex -c 8799@opindex --csh 8800@opindex --c-shell 8801@cindex C shell syntax for color setup 8802@cindex @command{csh} syntax for color setup 8803Output C shell commands. This is the default if @code{SHELL} ends with 8804@command{csh} or @command{tcsh}. 8805 8806@item -p 8807@itemx --print-database 8808@opindex -p 8809@opindex --print-database 8810@cindex color database, printing 8811@cindex database for color setup, printing 8812@cindex printing color database 8813Print the (compiled-in) default color configuration database. This 8814output is itself a valid configuration file, and is fairly descriptive 8815of the possibilities. 8816 8817@item --print-ls-colors 8818@opindex --print-ls-colors 8819@cindex printing ls colors 8820Print the LS_COLORS entries on separate lines, 8821each colored as per the color they represent. 8822 8823@end table 8824 8825@exitstatus 8826 8827 8828@node Basic operations 8829@chapter Basic operations 8830 8831@cindex manipulating files 8832 8833This chapter describes the commands for basic file manipulation: 8834copying, moving (renaming), and deleting (removing). 8835 8836@menu 8837* cp invocation:: Copy files. 8838* dd invocation:: Convert and copy a file. 8839* install invocation:: Copy files and set attributes. 8840* mv invocation:: Move (rename) files. 8841* rm invocation:: Remove files or directories. 8842* shred invocation:: Remove files more securely. 8843@end menu 8844 8845 8846@node cp invocation 8847@section @command{cp}: Copy files and directories 8848 8849@pindex cp 8850@cindex copying files and directories 8851@cindex files, copying 8852@cindex directories, copying 8853 8854@command{cp} copies files (or, optionally, directories). The copy is 8855completely independent of the original. You can either copy one file to 8856another, or copy arbitrarily many files to a destination directory. 8857Synopses: 8858 8859@example 8860cp [@var{option}]@dots{} [-T] @var{source} @var{dest} 8861cp [@var{option}]@dots{} @var{source}@dots{} @var{directory} 8862cp [@var{option}]@dots{} -t @var{directory} @var{source}@dots{} 8863@end example 8864 8865@itemize @bullet 8866@item 8867If two file names are given, @command{cp} copies the first file to the 8868second. 8869 8870@item 8871If the @option{--target-directory} (@option{-t}) option is given, or 8872failing that if the last file is a directory and the 8873@option{--no-target-directory} (@option{-T}) option is not given, 8874@command{cp} copies each @var{source} file to the specified directory, 8875using the @var{source}s' names. 8876@end itemize 8877 8878Generally, files are written just as they are read. For exceptions, 8879see the @option{--sparse} option below. 8880 8881By default, @command{cp} does not copy directories. However, the 8882@option{-R}, @option{-a}, and @option{-r} options cause @command{cp} to 8883copy recursively by descending into source directories and copying files 8884to corresponding destination directories. 8885 8886When copying from a symbolic link, @command{cp} normally follows the 8887link only when not copying recursively or when @option{--link} 8888(@option{-l}) is used. This default can be overridden with the 8889@option{--archive} (@option{-a}), @option{-d}, @option{--dereference} 8890(@option{-L}), @option{--no-dereference} (@option{-P}), and 8891@option{-H} options. If more than one of these options is specified, 8892the last one silently overrides the others. 8893 8894When copying to a symbolic link, @command{cp} follows the 8895link only when it refers to an existing regular file. 8896However, when copying to a dangling symbolic link, @command{cp} 8897refuses by default, and fails with a diagnostic, since the operation 8898is inherently dangerous. This behavior is contrary to historical 8899practice and to POSIX@. 8900Set @env{POSIXLY_CORRECT} to make @command{cp} attempt to create 8901the target of a dangling destination symlink, in spite of the possible risk. 8902Also, when an option like 8903@option{--backup} or @option{--link} acts to rename or remove the 8904destination before copying, @command{cp} renames or removes the 8905symbolic link rather than the file it points to. 8906 8907By default, @command{cp} copies the contents of special files only 8908when not copying recursively. This default can be overridden with the 8909@option{--copy-contents} option. 8910 8911@cindex self-backups 8912@cindex backups, making only 8913@command{cp} generally refuses to copy a file onto itself, with the 8914following exception: if @option{--force --backup} is specified with 8915@var{source} and @var{dest} identical, and referring to a regular file, 8916@command{cp} will make a backup file, either regular or numbered, as 8917specified in the usual ways (@pxref{Backup options}). This is useful when 8918you simply want to make a backup of an existing file before changing it. 8919 8920The program accepts the following options. Also see @ref{Common options}. 8921 8922@table @samp 8923@item -a 8924@itemx --archive 8925@opindex -a 8926@opindex --archive 8927Preserve as much as possible of the structure and attributes of the 8928original files in the copy (but do not attempt to preserve internal 8929directory structure; i.e., @samp{ls -U} may list the entries in a copied 8930directory in a different order). 8931Try to preserve SELinux security context and extended attributes (xattr), 8932but ignore any failure to do that and print no corresponding diagnostic. 8933Equivalent to @option{-dR --preserve=all} with the reduced diagnostics. 8934 8935@item --attributes-only 8936@opindex --attributes-only 8937Copy only the specified attributes of the source file to the destination. 8938If the destination already exists, do not alter its contents. 8939See the @option{--preserve} option for controlling which attributes to copy. 8940 8941@item -b 8942@itemx --backup[=@var{method}] 8943@opindex -b 8944@opindex --backup 8945@vindex VERSION_CONTROL 8946@cindex backups, making 8947@xref{Backup options}. 8948Make a backup of each file that would otherwise be overwritten or removed. 8949As a special case, @command{cp} makes a backup of @var{source} when the force 8950and backup options are given and @var{source} and @var{dest} are the same 8951name for an existing, regular file. One useful application of this 8952combination of options is this tiny Bourne shell script: 8953 8954@example 8955#!/bin/sh 8956# Usage: backup FILE... 8957# Create a GNU-style backup of each listed FILE. 8958fail=0 8959for i; do 8960 cp --backup --force --preserve=all -- "$i" "$i" || fail=1 8961done 8962exit $fail 8963@end example 8964 8965@item --copy-contents 8966@cindex directories, copying recursively 8967@cindex copying directories recursively 8968@cindex recursively copying directories 8969@cindex non-directories, copying as special files 8970If copying recursively, copy the contents of any special files (e.g., 8971FIFOs and device files) as if they were regular files. This means 8972trying to read the data in each source file and writing it to the 8973destination. It is usually a mistake to use this option, as it 8974normally has undesirable effects on special files like FIFOs and the 8975ones typically found in the @file{/dev} directory. In most cases, 8976@code{cp -R --copy-contents} will hang indefinitely trying to read 8977from FIFOs and special files like @file{/dev/console}, and it will 8978fill up your destination file system if you use it to copy @file{/dev/zero}. 8979This option has no effect unless copying recursively, and it does not 8980affect the copying of symbolic links. 8981 8982@item -d 8983@opindex -d 8984@cindex symbolic links, copying 8985@cindex hard links, preserving 8986Copy symbolic links as symbolic links rather than copying the files that 8987they point to, and preserve hard links between source files in the copies. 8988Equivalent to @option{--no-dereference --preserve=links}. 8989 8990@macro optDebugCopy 8991@item --debug 8992@opindex --debug 8993@cindex debugging, copying 8994Print extra information to stdout, explaining how files are copied. 8995This option implies the @option{--verbose} option. 8996@end macro 8997@optDebugCopy 8998 8999@item -f 9000@itemx --force 9001@opindex -f 9002@opindex --force 9003When copying without this option and an existing destination file cannot 9004be opened for writing, the copy fails. However, with @option{--force}, 9005when a destination file cannot be opened, @command{cp} then 9006tries to recreate the file by first removing it. Note @option{--force} 9007alone will not remove dangling symlinks. 9008When this option is combined with 9009@option{--link} (@option{-l}) or @option{--symbolic-link} 9010(@option{-s}), the destination link is replaced, and unless 9011@option{--backup} (@option{-b}) is also given there is no brief 9012moment when the destination does not exist. Also see the 9013description of @option{--remove-destination}. 9014 9015This option is independent of the @option{--interactive} or 9016@option{-i} option: neither cancels the effect of the other. 9017 9018This option is ignored when the @option{--no-clobber} or @option{-n} option 9019is also used. 9020 9021@item -H 9022@opindex -H 9023If a command line argument specifies a symbolic link, then copy the 9024file it points to rather than the symbolic link itself. However, 9025copy (preserving its nature) any symbolic link that is encountered 9026via recursive traversal. 9027 9028@item -i 9029@itemx --interactive 9030@opindex -i 9031@opindex --interactive 9032When copying a file other than a directory, prompt whether to 9033overwrite an existing destination file, and fail if the response 9034is not affirmative. The @option{-i} option overrides 9035a previous @option{-n} option. 9036 9037@item -l 9038@itemx --link 9039@opindex -l 9040@opindex --link 9041Make hard links instead of copies of non-directories. 9042 9043@item -L 9044@itemx --dereference 9045@opindex -L 9046@opindex --dereference 9047Follow symbolic links when copying from them. 9048With this option, @command{cp} cannot create a symbolic link. 9049For example, a symlink (to regular file) in the source tree will be copied to 9050a regular file in the destination tree. 9051 9052@item -n 9053@itemx --no-clobber 9054@opindex -n 9055@opindex --no-clobber 9056Do not overwrite an existing file; silently fail instead. 9057This option overrides a previous 9058@option{-i} option. This option is mutually exclusive with @option{-b} or 9059@option{--backup} option. 9060 9061@item -P 9062@itemx --no-dereference 9063@opindex -P 9064@opindex --no-dereference 9065@cindex symbolic links, copying 9066Copy symbolic links as symbolic links rather than copying the files that 9067they point to. This option affects only symbolic links in the source; 9068symbolic links in the destination are always followed if possible. 9069 9070@item -p 9071@itemx --preserve[=@var{attribute_list}] 9072@opindex -p 9073@opindex --preserve 9074@cindex file information, preserving, extended attributes, xattr 9075Preserve the specified attributes of the original files. 9076If specified, the @var{attribute_list} must be a comma-separated list 9077of one or more of the following strings: 9078 9079@table @samp 9080@item mode 9081@cindex access control lists (ACLs) 9082Preserve attributes relevant to access permissions, 9083including file mode bits and (if possible) access control lists (ACLs). 9084ACL preservation is system-dependent, and ACLs are not necessarily 9085translated when the source and destination are on file systems with 9086different ACL formats (e.g., NFSv4 versus POSIX formats). 9087 9088@item ownership 9089Preserve the owner and group. On most modern systems, 9090only users with appropriate privileges may change the owner of a file, 9091and ordinary users 9092may preserve the group ownership of a file only if they happen to be 9093a member of the desired group. 9094@item timestamps 9095Preserve the times of last access and last modification, when possible. 9096On older systems, it is not possible to preserve these attributes 9097when the affected file is a symbolic link. 9098However, many systems now provide the @code{utimensat} function, 9099which makes it possible even for symbolic links. 9100@item links 9101Preserve in the destination files 9102any links between corresponding source files. 9103Note that with @option{-L} or @option{-H}, this option can convert 9104symbolic links to hard links. For example, 9105@example 9106$ mkdir c; : > a; ln -s a b; cp -aH a b c; ls -i1 c 910774161745 a 910874161745 b 9109@end example 9110@noindent 9111Note the inputs: @file{b} is a symlink to regular file @file{a}, 9112yet the files in destination directory, @file{c/}, are hard-linked. 9113Since @option{-a} implies @option{--no-dereference} it would copy the symlink, 9114but the later @option{-H} tells @command{cp} to dereference the command line 9115arguments where it then sees two files with the same inode number. 9116Then the @option{--preserve=links} option also implied by @option{-a} 9117will preserve the perceived hard link. 9118 9119Here is a similar example that exercises @command{cp}'s @option{-L} option: 9120@example 9121$ mkdir b c; (cd b; : > a; ln -s a b); cp -aL b c; ls -i1 c/b 912274163295 a 912374163295 b 9124@end example 9125 9126@item context 9127Preserve SELinux security context of the file, or fail with full diagnostics. 9128@item xattr 9129@cindex access control lists (ACLs) 9130Preserve extended attributes of the file, or fail with full diagnostics. 9131If @command{cp} is built without xattr support, ignore this option. 9132If SELinux context, ACLs or Capabilities are implemented using xattrs, 9133they are preserved implicitly by this option as well, i.e., even without 9134specifying @option{--preserve=mode} or @option{--preserve=context}. 9135@item all 9136Preserve all file attributes. 9137Equivalent to specifying all of the above, but with the difference 9138that failure to preserve SELinux security context or extended attributes 9139does not change @command{cp}'s exit status. In contrast to @option{-a}, 9140all but @samp{Operation not supported} warnings are output. 9141@end table 9142 9143Using @option{--preserve} with no @var{attribute_list} is equivalent 9144to @option{--preserve=mode,ownership,timestamps}. 9145 9146In the absence of this option, the permissions of existing destination 9147files are unchanged. Each new file is created with the mode of the 9148corresponding source file minus the set-user-ID, set-group-ID, and 9149sticky bits as the create mode; the operating system then applies either 9150the umask or a default ACL, possibly resulting in a more restrictive 9151file mode. 9152@xref{File permissions}. 9153 9154@item --no-preserve=@var{attribute_list} 9155@cindex file information, preserving 9156Do not preserve the specified attributes. The @var{attribute_list} 9157has the same form as for @option{--preserve}. 9158 9159@item --parents 9160@opindex --parents 9161@cindex parent directories and @command{cp} 9162Form the name of each destination file by appending to the target 9163directory a slash and the specified name of the source file. The last 9164argument given to @command{cp} must be the name of an existing directory. 9165For example, the command: 9166 9167@example 9168cp --parents a/b/c existing_dir 9169@end example 9170 9171@noindent 9172copies the file @file{a/b/c} to @file{existing_dir/a/b/c}, creating 9173any missing intermediate directories. 9174 9175@item -R 9176@itemx -r 9177@itemx --recursive 9178@opindex -R 9179@opindex -r 9180@opindex --recursive 9181@cindex directories, copying recursively 9182@cindex copying directories recursively 9183@cindex recursively copying directories 9184@cindex non-directories, copying as special files 9185Copy directories recursively. By default, do not follow symbolic 9186links in the source unless used together with the @option{--link} 9187(@option{-l}) option; see the @option{--archive} (@option{-a}), @option{-d}, 9188@option{--dereference} (@option{-L}), @option{--no-dereference} 9189(@option{-P}), and @option{-H} options. Special files are copied by 9190creating a destination file of the same type as the source; see the 9191@option{--copy-contents} option. It is not portable to use 9192@option{-r} to copy symbolic links or special files. On some 9193non-GNU systems, @option{-r} implies the equivalent of 9194@option{-L} and @option{--copy-contents} for historical reasons. 9195Also, it is not portable to use @option{-R} to copy symbolic links 9196unless you also specify @option{-P}, as POSIX allows 9197implementations that dereference symbolic links by default. 9198 9199@item --reflink[=@var{when}] 9200@opindex --reflink[=@var{when}] 9201@cindex COW 9202@cindex clone 9203@cindex copy on write 9204Perform a lightweight, copy-on-write (COW) copy, if supported by the 9205file system. Once it has succeeded, beware that the source and destination 9206files share the same data blocks as long as they remain unmodified. 9207Thus, if an I/O error affects data blocks of one of the files, 9208the other suffers the same fate. 9209 9210The @var{when} value can be one of the following: 9211 9212@table @samp 9213@item always 9214If the copy-on-write operation is not supported 9215then report the failure for each file and exit with a failure status. 9216Plain @option{--reflink} is equivalent to @option{--reflink=always}. 9217 9218@item auto 9219If the copy-on-write operation is not supported then fall back 9220to the standard copy behavior. 9221This is the default if no @option{--reflink} option is given. 9222 9223@item never 9224Disable copy-on-write operation and use the standard copy behavior. 9225@end table 9226 9227This option is overridden by the @option{--link}, @option{--symbolic-link} 9228and @option{--attributes-only} options, thus allowing it to be used 9229to configure the default data copying behavior for @command{cp}. 9230 9231@item --remove-destination 9232@opindex --remove-destination 9233Remove each existing destination file before attempting to open it 9234(contrast with @option{-f} above). 9235 9236@item --sparse=@var{when} 9237@opindex --sparse=@var{when} 9238@cindex sparse files, copying 9239@cindex holes, copying files with 9240@findex read @r{system call, and holes} 9241A @dfn{sparse file} contains @dfn{holes} -- a sequence of zero bytes that 9242does not occupy any file system blocks; the @samp{read} system call 9243reads these as zeros. This can both save considerable space and 9244increase speed, since many binary files contain lots of consecutive zero 9245bytes. By default, @command{cp} detects holes in input source files via a crude 9246heuristic and makes the corresponding output file sparse as well. 9247Only regular files may be sparse. 9248 9249The @var{when} value can be one of the following: 9250 9251@table @samp 9252@item auto 9253The default behavior: if the input file is sparse, attempt to make 9254the output file sparse, too. However, if an output file exists but 9255refers to a non-regular file, then do not attempt to make it sparse. 9256 9257@item always 9258For each sufficiently long sequence of zero bytes in the input file, 9259attempt to create a corresponding hole in the output file, even if the 9260input file does not appear to be sparse. 9261This is useful when the input file resides on a file system 9262that does not support sparse files 9263(for example, @samp{efs} file systems in SGI IRIX 5.3 and earlier), 9264but the output file is on a type of file system that does support them. 9265Holes may be created only in regular files, so if the destination file 9266is of some other type, @command{cp} does not even try to make it sparse. 9267 9268@item never 9269Never make the output file sparse. 9270This is useful in creating a file for use with the @command{mkswap} command, 9271since such a file must not have any holes. 9272@end table 9273 9274For example, with the following alias, @command{cp} will use the 9275minimum amount of space supported by the file system. 9276(Older versions of @command{cp} can also benefit from 9277@option{--reflink=auto} here.) 9278 9279@example 9280alias cp='cp --sparse=always' 9281@end example 9282 9283@optStripTrailingSlashes 9284 9285@item -s 9286@itemx --symbolic-link 9287@opindex -s 9288@opindex --symbolic-link 9289@cindex symbolic links, copying with 9290Make symbolic links instead of copies of non-directories. All source 9291file names must be absolute (starting with @samp{/}) unless the 9292destination files are in the current directory. This option merely 9293results in an error message on systems that do not support symbolic links. 9294 9295@optBackupSuffix 9296 9297@optTargetDirectory 9298 9299@optNoTargetDirectory 9300 9301@item -u 9302@itemx --update[=@var{which}] 9303@opindex -u 9304@opindex --update[=@var{which}] 9305@cindex newer files, copying only 9306Do not copy a non-directory that has an existing destination with the 9307same or newer modification timestamp; instead, silently skip the file 9308without failing. If timestamps are being preserved, 9309the comparison is to the source timestamp truncated to the 9310resolutions of the destination file system and of the system calls 9311used to update timestamps; this avoids duplicate work if several 9312@samp{cp -pu} commands are executed with the same source and destination. 9313This option is ignored if the @option{-n} or @option{--no-clobber} 9314option is also specified. 9315Also, if @option{--preserve=links} is also specified (like with @samp{cp -au} 9316for example), that will take precedence; consequently, depending on the 9317order that files are processed from the source, newer files in the destination 9318may be replaced, to mirror hard links in the source. 9319 9320@macro whichUpdate 9321@var{which} gives more control over which existing files in the 9322destination are replaced, and its value can be one of the following: 9323 9324@table @samp 9325@item all 9326This is the default operation when an @option{--update} option is not specified, 9327and results in all existing files in the destination being replaced. 9328 9329@item none 9330This is similar to the @option{--no-clobber} option, in that no files in the 9331destination are replaced, but also skipping a file does not induce a failure. 9332 9333@item older 9334This is the default operation when @option{--update} is specified, and results 9335in files being replaced if they're older than the corresponding source file. 9336@end table 9337@end macro 9338@whichUpdate 9339 9340@item -v 9341@itemx --verbose 9342@opindex -v 9343@opindex --verbose 9344Print the name of each file before copying it. 9345 9346@item -x 9347@itemx --one-file-system 9348@opindex -x 9349@opindex --one-file-system 9350@cindex file systems, omitting copying to different 9351Skip subdirectories that are on different file systems from the one that 9352the copy started on. 9353However, mount point directories @emph{are} copied. 9354 9355@macro optContext 9356@item -Z 9357@itemx --context[=@var{context}] 9358@opindex -Z 9359@opindex --context 9360@cindex SELinux, setting/restoring security context 9361@cindex security context 9362Without a specified @var{context}, adjust the SELinux security context according 9363to the system default type for destination files, similarly to the 9364@command{restorecon} command. 9365The long form of this option with a specific context specified, 9366will set the context for newly created files only. 9367With a specified context, if both SELinux and SMACK are disabled, a warning is 9368issued. 9369@end macro 9370@optContext 9371This option is mutually exclusive with the @option{--preserve=context} 9372option, and overrides the @option{--preserve=all} and @option{-a} options. 9373 9374@end table 9375 9376@exitstatus 9377 9378 9379@node dd invocation 9380@section @command{dd}: Convert and copy a file 9381 9382@pindex dd 9383@cindex converting while copying a file 9384 9385@command{dd} copies input to output with a changeable I/O block size, 9386while optionally performing conversions on the data. Synopses: 9387 9388@example 9389dd [@var{operand}]@dots{} 9390dd @var{option} 9391@end example 9392 9393The only options are @option{--help} and @option{--version}. 9394@xref{Common options}. 9395 9396By default, @command{dd} copies standard input to standard output. 9397To copy, @command{dd} repeatedly does the following steps in order: 9398 9399@enumerate 9400@item 9401Read an input block. 9402 9403@item 9404If converting via @samp{sync}, pad as needed to meet the input block size. 9405Pad with spaces if converting via @samp{block} or @samp{unblock}, NUL 9406bytes otherwise. 9407 9408@item 9409If @samp{bs=} is given and no conversion mentioned in steps (4) or (5) 9410is given, output the data as a single block and skip all remaining steps. 9411 9412@item 9413If the @samp{swab} conversion is given, swap each pair of input bytes. 9414If the input data length is odd, preserve the last input byte 9415(since there is nothing to swap it with). 9416 9417@item 9418If any of the conversions @samp{swab}, @samp{block}, @samp{unblock}, 9419@samp{lcase}, @samp{ucase}, @samp{ascii}, @samp{ebcdic} and @samp{ibm} 9420are given, do these conversions. These conversions operate 9421independently of input blocking, and might deal with records that span 9422block boundaries. 9423 9424@item 9425Aggregate the resulting data into output blocks of the specified size, 9426and output each output block in turn. Do not pad the last output block; 9427it can be shorter than usual. 9428@end enumerate 9429 9430@command{dd} accepts the following operands, 9431whose syntax was inspired by the DD (data definition) statement of 9432OS/360 JCL. 9433 9434@table @samp 9435 9436@item if=@var{file} 9437@opindex if 9438Read from @var{file} instead of standard input. 9439 9440@item of=@var{file} 9441@opindex of 9442Write to @var{file} instead of standard output. Unless 9443@samp{conv=notrunc} is given, truncate @var{file} before writing it. 9444 9445@item ibs=@var{bytes} 9446@opindex ibs 9447@cindex block size of input 9448@cindex input block size 9449Set the input block size to @var{bytes}. 9450This makes @command{dd} read @var{bytes} per block. 9451The default is 512 bytes. 9452 9453@item obs=@var{bytes} 9454@opindex obs 9455@cindex block size of output 9456@cindex output block size 9457Set the output block size to @var{bytes}. 9458This makes @command{dd} write @var{bytes} per block. 9459The default is 512 bytes. 9460 9461@item bs=@var{bytes} 9462@opindex bs 9463@cindex block size 9464Set both input and output block sizes to @var{bytes}. 9465This makes @command{dd} read and write @var{bytes} per block, 9466overriding any @samp{ibs} and @samp{obs} settings. 9467In addition, if no data-transforming @option{conv} operand is specified, 9468input is copied to the output as soon as it's read, 9469even if it is smaller than the block size. 9470 9471@item cbs=@var{bytes} 9472@opindex cbs 9473@cindex block size of conversion 9474@cindex conversion block size 9475@cindex fixed-length records, converting to variable-length 9476@cindex variable-length records, converting to fixed-length 9477Set the conversion block size to @var{bytes}. 9478When converting variable-length records to fixed-length ones 9479(@option{conv=block}) or the reverse (@option{conv=unblock}), 9480use @var{bytes} as the fixed record length. 9481 9482@item skip=@var{n} 9483@itemx iseek=@var{n} 9484@opindex skip 9485@opindex iseek 9486Skip @var{n} @samp{ibs}-byte blocks in the input file before copying. 9487If @var{n} ends in the letter @samp{B}, interpret @var{n} 9488as a byte count rather than a block count. 9489(@samp{B} and the @samp{iseek=} spelling are GNU extensions to POSIX.) 9490 9491@item seek=@var{n} 9492@itemx oseek=@var{n} 9493@opindex seek 9494@opindex oseek 9495Skip @var{n} @samp{obs}-byte blocks in the output file before 9496truncating or copying. 9497If @var{n} ends in the letter @samp{B}, interpret @var{n} 9498as a byte count rather than a block count. 9499(@samp{B} and the @samp{oseek=} spelling are GNU extensions to POSIX.) 9500 9501@item count=@var{n} 9502@opindex count 9503Copy @var{n} @samp{ibs}-byte blocks from the input file, instead 9504of everything until the end of the file. 9505If @var{n} ends in the letter @samp{B}, 9506interpret @var{n} as a byte count rather than a block count; 9507this is a GNU extension to POSIX. 9508If short reads occur, as could be the case 9509when reading from a pipe for example, @samp{iflag=fullblock} 9510ensures that @samp{count=} counts complete input blocks 9511rather than input read operations. 9512As an extension to POSIX, @samp{count=0} copies zero blocks 9513instead of copying all blocks. 9514 9515@item status=@var{level} 9516@opindex status 9517Specify the amount of information printed. 9518If this operand is given multiple times, the last one takes precedence. 9519The @var{level} value can be one of the following: 9520 9521@table @samp 9522 9523@item none 9524@opindex none @r{dd status=} 9525Do not print any informational or warning messages to standard error. 9526Error messages are output as normal. 9527 9528@item noxfer 9529@opindex noxfer @r{dd status=} 9530Do not print the final transfer rate and volume statistics 9531that normally make up the last status line. 9532 9533@item progress 9534@opindex progress @r{dd status=} 9535Print the transfer rate and volume statistics on standard error, 9536when processing each input block. Statistics are output 9537on a single line at most once every second, but updates 9538can be delayed when waiting on I/O. 9539 9540@end table 9541 9542Transfer information is normally output to standard error upon 9543receipt of the @samp{INFO} signal or when @command{dd} exits, 9544and defaults to the following form in the C locale: 9545 9546@example 95477287+1 records in 9548116608+0 records out 954959703296 bytes (60 MB, 57 MiB) copied, 0.0427974 s, 1.4 GB/s 9550@end example 9551 9552The notation @samp{@var{w}+@var{p}} stands for @var{w} whole blocks 9553and @var{p} partial blocks. A partial block occurs when a read or 9554write operation succeeds but transfers less data than the block size. 9555An additional line like @samp{1 truncated record} or @samp{10 9556truncated records} is output after the @samp{records out} line if 9557@samp{conv=block} processing truncated one or more input records. 9558 9559The @samp{status=} operand is a GNU extension to POSIX. 9560 9561@item conv=@var{conversion}[,@var{conversion}]@dots{} 9562@opindex conv 9563Convert the file as specified by the @var{conversion} argument(s). 9564(No spaces around any comma(s).) 9565 9566Conversions: 9567 9568@table @samp 9569 9570@item ascii 9571@opindex ascii@r{, converting to} 9572Convert EBCDIC to ASCII, 9573using the conversion table specified by POSIX@. 9574This provides a 1:1 translation for all 256 bytes. 9575This implies @samp{conv=unblock}; input is converted to 9576ASCII before trailing spaces are deleted. 9577 9578@item ebcdic 9579@opindex ebcdic@r{, converting to} 9580Convert ASCII to EBCDIC@. 9581This is the inverse of the @samp{ascii} conversion. 9582This implies @samp{conv=block}; trailing spaces are added 9583before being converted to EBCDIC@. 9584 9585@item ibm 9586@opindex alternate ebcdic@r{, converting to} 9587This acts like @samp{conv=ebcdic}, except it 9588uses the alternate conversion table specified by POSIX@. 9589This is not a 1:1 translation, but reflects common historical practice 9590for @samp{~}, @samp{[}, and @samp{]}. 9591 9592The @samp{ascii}, @samp{ebcdic}, and @samp{ibm} conversions are 9593mutually exclusive. If you use any of these conversions, you should also 9594use the @samp{cbs=} operand. 9595 9596@item block 9597@opindex block @r{(space-padding)} 9598For each line in the input, output @samp{cbs} bytes, replacing the 9599input newline with a space and truncating or padding input lines with 9600spaces as necessary. 9601 9602@item unblock 9603@opindex unblock 9604Remove any trailing spaces in each @samp{cbs}-sized input block, 9605and append a newline. 9606 9607The @samp{block} and @samp{unblock} conversions are mutually exclusive. 9608If you use either of these conversions, you should also use the 9609@samp{cbs=} operand. 9610 9611@item lcase 9612@opindex lcase@r{, converting to} 9613Change uppercase letters to lowercase. 9614 9615@item ucase 9616@opindex ucase@r{, converting to} 9617Change lowercase letters to uppercase. 9618 9619The @samp{lcase} and @samp{ucase} conversions are mutually exclusive. 9620 9621@item sparse 9622@opindex sparse 9623Try to seek rather than write NUL output blocks. 9624On a file system that supports sparse files, this will create 9625sparse output when extending the output file. 9626Be careful when using this conversion in conjunction with 9627@samp{conv=notrunc} or @samp{oflag=append}. 9628With @samp{conv=notrunc}, existing data in the output file 9629corresponding to NUL blocks from the input, will be untouched. 9630With @samp{oflag=append} the seeks performed will be ineffective. 9631Similarly, when the output is a device rather than a file, 9632NUL input blocks are not copied, and therefore this conversion 9633is most useful with virtual or pre zeroed devices. 9634 9635The @samp{sparse} conversion is a GNU extension to POSIX. 9636 9637@item swab 9638@opindex swab @r{(byte-swapping)} 9639@cindex byte-swapping 9640Swap every pair of input bytes. 9641 9642@item sync 9643@opindex sync @r{(padding with ASCII NULs)} 9644Pad every input block to size of @samp{ibs} with trailing zero bytes. 9645When used with @samp{block} or @samp{unblock}, pad with spaces instead of 9646zero bytes. 9647 9648@end table 9649 9650The following ``conversions'' are really file flags 9651and don't affect internal processing: 9652 9653@table @samp 9654@item excl 9655@opindex excl 9656@cindex creating output file, requiring 9657Fail if the output file already exists; @command{dd} must create the 9658output file itself. 9659 9660@item nocreat 9661@opindex nocreat 9662@cindex creating output file, avoiding 9663Do not create the output file; the output file must already exist. 9664 9665The @samp{excl} and @samp{nocreat} conversions are mutually exclusive, 9666and are GNU extensions to POSIX. 9667 9668@item notrunc 9669@opindex notrunc 9670@cindex truncating output file, avoiding 9671Do not truncate the output file. 9672 9673@item noerror 9674@opindex noerror 9675@cindex read errors, ignoring 9676Continue after read errors. 9677 9678@item fdatasync 9679@opindex fdatasync 9680@cindex synchronized data writes, before finishing 9681Synchronize output data just before finishing, 9682even if there were write errors. 9683This forces a physical write of output data, 9684so that even if power is lost the output data will be preserved. 9685If neither this nor @samp{fsync} are specified, output is treated as 9686usual with file systems, i.e., output data and metadata may be cached 9687in primary memory for some time before the operating system physically 9688writes it, and thus output data and metadata may be lost if power is lost. 9689@xref{sync invocation}. 9690This conversion is a GNU extension to POSIX. 9691 9692@item fsync 9693@opindex fsync 9694@cindex synchronized data and metadata writes, before finishing 9695Synchronize output data and metadata just before finishing, 9696even if there were write errors. 9697This acts like @samp{fdatasync} except it also preserves output metadata, 9698such as the last-modified time of the output file; for this reason it 9699may be a bit slower than @samp{fdatasync} although the performance 9700difference is typically insignificant for @command{dd}. 9701This conversion is a GNU extension to POSIX. 9702 9703@end table 9704 9705@item iflag=@var{flag}[,@var{flag}]@dots{} 9706@opindex iflag 9707Access the input file using the flags specified by the @var{flag} 9708argument(s). (No spaces around any comma(s).) 9709 9710@item oflag=@var{flag}[,@var{flag}]@dots{} 9711@opindex oflag 9712Access the output file using the flags specified by the @var{flag} 9713argument(s). (No spaces around any comma(s).) 9714 9715Here are the flags. 9716 9717@table @samp 9718 9719@item append 9720@opindex append 9721@cindex appending to the output file 9722Write in append mode, so that even if some other process is writing to 9723this file, every @command{dd} write will append to the current 9724contents of the file. This flag makes sense only for output. 9725If you combine this flag with the @samp{of=@var{file}} operand, 9726you should also specify @samp{conv=notrunc} unless you want the 9727output file to be truncated before being appended to. 9728 9729@item cio 9730@opindex cio 9731@cindex concurrent I/O 9732Use concurrent I/O mode for data. This mode performs direct I/O 9733and drops the POSIX requirement to serialize all I/O to the same file. 9734A file cannot be opened in CIO mode and with a standard open at the 9735same time. 9736 9737@item direct 9738@opindex direct 9739@cindex direct I/O 9740Use direct I/O for data, avoiding the buffer cache. 9741Note that the kernel may impose restrictions on read or write buffer sizes. 9742For example, with an ext4 destination file system and a Linux-based kernel, 9743using @samp{oflag=direct} will cause writes to fail with @code{EINVAL} if the 9744output buffer size is not a multiple of 512. 9745 9746@item directory 9747@opindex directory 9748@cindex directory I/O 9749 9750Fail unless the file is a directory. Most operating systems do not 9751allow I/O to a directory, so this flag has limited utility. 9752 9753@item dsync 9754@opindex dsync 9755@cindex synchronized data reads 9756Use synchronized I/O for data. For the output file, this forces a 9757physical write of output data on each write. For the input file, 9758this flag can matter when reading from a remote file that has been 9759written to synchronously by some other process. Metadata (e.g., 9760last-access and last-modified time) is not necessarily synchronized. 9761 9762@item sync 9763@opindex sync 9764@cindex synchronized data and metadata I/O 9765Use synchronized I/O for both data and metadata. 9766 9767@item nocache 9768@opindex nocache 9769@cindex discarding file cache 9770Request to discard the system data cache for a file. 9771When count=0 all cached data for the file is specified, 9772otherwise the cache is dropped for the processed 9773portion of the file. Also when count=0, 9774failure to discard the cache is diagnosed 9775and reflected in the exit status. 9776 9777Note data that is not already persisted to storage will not 9778be discarded from cache, so note the use of the @samp{sync} conversions 9779in the examples below, which are used to maximize the 9780effectiveness of the @samp{nocache} flag. 9781 9782Here are some usage examples: 9783 9784@example 9785# Advise to drop cache for whole file 9786dd if=ifile iflag=nocache count=0 9787 9788# Ensure drop cache for the whole file 9789dd of=ofile oflag=nocache conv=notrunc,fdatasync count=0 9790 9791# Advise to drop cache for part of file 9792# Note the kernel will only consider complete and 9793# already persisted pages. 9794dd if=ifile iflag=nocache skip=10 count=10 of=/dev/null 9795 9796# Stream data using just the read-ahead cache. 9797# See also the @samp{direct} flag. 9798dd if=ifile of=ofile iflag=nocache oflag=nocache,sync 9799@end example 9800 9801@item nonblock 9802@opindex nonblock 9803@cindex nonblocking I/O 9804Use non-blocking I/O. 9805 9806@item noatime 9807@opindex noatime 9808@cindex access timestamp 9809Do not update the file's access timestamp. 9810@xref{File timestamps}. 9811Some older file systems silently ignore this flag, so it is a good 9812idea to test it on your files before relying on it. 9813 9814@item noctty 9815@opindex noctty 9816@cindex controlling terminal 9817Do not assign the file to be a controlling terminal for @command{dd}. 9818This has no effect when the file is not a terminal. 9819On many hosts (e.g., GNU/Linux hosts), this flag has no effect 9820at all. 9821 9822@item nofollow 9823@opindex nofollow 9824@cindex symbolic links, following 9825Do not follow symbolic links. 9826 9827@item nolinks 9828@opindex nolinks 9829@cindex hard links 9830Fail if the file has multiple hard links. 9831 9832@item binary 9833@opindex binary 9834@cindex binary I/O 9835Use binary I/O@. This flag has an effect only on nonstandard 9836platforms that distinguish binary from text I/O. 9837 9838@item text 9839@opindex text 9840@cindex text I/O 9841Use text I/O@. Like @samp{binary}, this flag has no effect on 9842standard platforms. 9843 9844@item fullblock 9845@opindex fullblock 9846Accumulate full blocks from input. The @code{read} system call 9847may return early if a full block is not available. 9848When that happens, continue calling @code{read} to fill the remainder 9849of the block. 9850This flag can be used only with @code{iflag}. 9851This flag is useful with pipes for example 9852as they may return short reads. In that case, 9853this flag is needed to ensure that a @samp{count=} argument is 9854interpreted as a block count rather than a count of read operations. 9855 9856@end table 9857 9858These flags are all GNU extensions to POSIX. 9859They are not supported on all systems, and @samp{dd} rejects 9860attempts to use them when they are not supported. When reading from 9861standard input or writing to standard output, the @samp{nofollow} and 9862@samp{noctty} flags should not be specified, and the other flags 9863(e.g., @samp{nonblock}) can affect how other processes behave with the 9864affected file descriptors, even after @command{dd} exits. 9865 9866@end table 9867 9868The behavior of @command{dd} is unspecified if operands other than 9869@samp{conv=}, @samp{iflag=}, @samp{oflag=}, and @samp{status=} are 9870specified more than once. 9871 9872@cindex multipliers after numbers 9873The numeric-valued strings above (@var{n} and @var{bytes}) 9874are unsigned decimal integers that 9875can be followed by a multiplier: @samp{b}=512, @samp{c}=1, 9876@samp{w}=2, @samp{x@var{m}}=@var{m}, or any of the 9877standard block size suffixes like @samp{k}=1024 (@pxref{Block size}). 9878These multipliers are GNU extensions to POSIX, except that 9879POSIX allows @var{bytes} to be followed by @samp{k}, @samp{b}, and 9880@samp{x@var{m}}. Note @samp{x@var{m}} can be used more than once in a number. 9881Block sizes (i.e., specified by @var{bytes} strings) must be nonzero. 9882 9883Any block size you specify via @samp{bs=}, @samp{ibs=}, @samp{obs=}, @samp{cbs=} 9884should not be too large -- values larger than a few megabytes 9885are generally wasteful or (as in the gigabyte..exabyte case) downright 9886counterproductive or error-inducing. 9887 9888To process data with offset or size that is not a multiple of the I/O 9889block size, you can use a numeric string @var{n} that ends in the 9890letter @samp{B}. 9891For example, the following shell commands copy data 9892in 1 MiB blocks between a flash drive and a tape, but do not save 9893or restore a 512-byte area at the start of the flash drive: 9894 9895@example 9896flash=/dev/sda 9897tape=/dev/st0 9898 9899# Copy all but the initial 512 bytes from flash to tape. 9900dd if=$flash iseek=512B bs=1MiB of=$tape 9901 9902# Copy from tape back to flash, leaving initial 512 bytes alone. 9903dd if=$tape bs=1MiB of=$flash oseek=512B 9904@end example 9905 9906@cindex ddrescue 9907@cindex storage devices, failing 9908For failing storage devices, other tools come with a great variety of extra 9909functionality to ease the saving of as much data as possible before the 9910device finally dies, e.g. 9911@uref{https://www.gnu.org/software/ddrescue/, GNU @command{ddrescue}}. 9912However, in some cases such a tool is not available or the administrator 9913feels more comfortable with the handling of @command{dd}. 9914As a simple rescue method, call @command{dd} as shown in the following 9915example: the operand @samp{conv=noerror,sync} is used to continue 9916after read errors and to pad out bad reads with NULs, while 9917@samp{iflag=fullblock} caters for short reads (which traditionally never 9918occur on flash or similar devices): 9919 9920@example 9921# Rescue data from an (unmounted!) partition of a failing device. 9922dd conv=noerror,sync iflag=fullblock </dev/sda1 > /mnt/rescue.img 9923@end example 9924 9925Sending an @samp{INFO} signal (or @samp{USR1} signal where that is unavailable) 9926to a running @command{dd} process makes it print I/O statistics to 9927standard error and then resume copying. In the example below, 9928@command{dd} is run in the background to copy 5GB of data. 9929The @command{kill} command makes it output intermediate I/O statistics, 9930and when @command{dd} completes normally or is killed by the 9931@code{SIGINT} signal, it outputs the final statistics. 9932 9933@example 9934# Ignore the signal so we never inadvertently terminate the dd child. 9935# Note this is not needed when SIGINFO is available. 9936trap '' USR1 9937 9938# Run dd with the fullblock iflag to avoid short reads 9939# which can be triggered by reception of signals. 9940dd iflag=fullblock if=/dev/zero of=/dev/null count=5000000 bs=1000 & pid=$! 9941 9942# Output stats every second. 9943while kill -s USR1 $pid 2>/dev/null; do sleep 1; done 9944@end example 9945 9946The above script will output in the following format: 9947 9948@example 99493441325+0 records in 99503441325+0 records out 99513441325000 bytes (3.4 GB, 3.2 GiB) copied, 1.00036 s, 3.4 GB/s 99525000000+0 records in 99535000000+0 records out 99545000000000 bytes (5.0 GB, 4.7 GiB) copied, 1.44433 s, 3.5 GB/s 9955@end example 9956 9957The @samp{status=progress} operand periodically updates the last line 9958of the transfer statistics above. 9959 9960@vindex POSIXLY_CORRECT 9961On systems lacking the @samp{INFO} signal @command{dd} responds to the 9962@samp{USR1} signal instead, unless the @env{POSIXLY_CORRECT} 9963environment variable is set. 9964 9965@exitstatus 9966 9967 9968@node install invocation 9969@section @command{install}: Copy files and set attributes 9970 9971@pindex install 9972@cindex copying files and setting attributes 9973 9974@command{install} copies files while setting their file mode bits and, if 9975possible, their owner and group. Synopses: 9976 9977@example 9978install [@var{option}]@dots{} [-T] @var{source} @var{dest} 9979install [@var{option}]@dots{} @var{source}@dots{} @var{directory} 9980install [@var{option}]@dots{} -t @var{directory} @var{source}@dots{} 9981install [@var{option}]@dots{} -d @var{directory}@dots{} 9982@end example 9983 9984@itemize @bullet 9985@item 9986If two file names are given, @command{install} copies the first file to the 9987second. 9988 9989@item 9990If the @option{--target-directory} (@option{-t}) option is given, or 9991failing that if the last file is a directory and the 9992@option{--no-target-directory} (@option{-T}) option is not given, 9993@command{install} copies each @var{source} file to the specified 9994directory, using the @var{source}s' names. 9995 9996@item 9997If the @option{--directory} (@option{-d}) option is given, 9998@command{install} creates each @var{directory} and any missing parent 9999directories. Parent directories are created with mode 10000@samp{u=rwx,go=rx} (755), regardless of the @option{-m} option or the 10001current umask. @xref{Directory Setuid and Setgid}, for how the 10002set-user-ID and set-group-ID bits of parent directories are inherited. 10003@end itemize 10004 10005@cindex Makefiles, installing programs in 10006@command{install} is similar to @command{cp}, but allows you to control the 10007attributes of destination files. It is typically used in Makefiles to 10008copy programs into their destination directories. It refuses to copy 10009files onto themselves. 10010 10011@cindex extended attributes, xattr 10012@command{install} never preserves extended attributes (xattr). 10013 10014The program accepts the following options. Also see @ref{Common options}. 10015 10016@table @samp 10017 10018@optBackup 10019 10020@item -C 10021@itemx --compare 10022@opindex -C 10023@opindex --compare 10024Compare content of source and destination files, and if there would be no 10025change to the destination content, owner, group, permissions, and possibly 10026SELinux context, then do not modify the destination at all. 10027Note this option is best used in conjunction with @option{--user}, 10028@option{--group} and @option{--mode} options, lest @command{install} 10029incorrectly determines the default attributes that installed files would have 10030(as it doesn't consider setgid directories and POSIX default ACLs for example). 10031This could result in redundant copies or attributes that are not reset to the 10032correct defaults. 10033 10034@item -c 10035@opindex -c 10036Ignored; for compatibility with old Unix versions of @command{install}. 10037 10038@item -D 10039@opindex -D 10040Create any missing parent directories of @var{dest}, 10041then copy @var{source} to @var{dest}. 10042Explicitly specifying the @option{--target-directory=@var{dir}} will similarly 10043ensure the presence of that hierarchy before copying @var{source} arguments. 10044 10045@item -d 10046@itemx --directory 10047@opindex -d 10048@opindex --directory 10049@cindex directories, creating with given attributes 10050@cindex parent directories, creating missing 10051@cindex leading directories, creating missing 10052Create any missing parent directories, giving them the default 10053attributes. Then create each given directory, setting their owner, 10054group and mode as given on the command line or to the defaults. 10055 10056@optDebugCopy 10057 10058@item -g @var{group} 10059@itemx --group=@var{group} 10060@opindex -g 10061@opindex --group 10062@cindex group ownership of installed files, setting 10063Set the group ownership of installed files or directories to 10064@var{group}. The default is the process's current group. @var{group} 10065may be either a group name or a numeric group ID. 10066 10067@item -m @var{mode} 10068@itemx --mode=@var{mode} 10069@opindex -m 10070@opindex --mode 10071@cindex permissions of installed files, setting 10072Set the file mode bits for the installed file or directory to @var{mode}, 10073which can be either an octal number, or a symbolic mode as in 10074@command{chmod}, with @samp{a=} (no access allowed to anyone) as the 10075point of departure (@pxref{File permissions}). 10076The default mode is @samp{u=rwx,go=rx,a-s} -- read, write, and 10077execute for the owner, read and execute for group and other, and with 10078set-user-ID and set-group-ID disabled. 10079This default is not quite the same as @samp{755}, since it disables 10080instead of preserving set-user-ID and set-group-ID on directories. 10081@xref{Directory Setuid and Setgid}. 10082 10083@item -o @var{owner} 10084@itemx --owner=@var{owner} 10085@opindex -o 10086@opindex --owner 10087@cindex ownership of installed files, setting 10088@cindex appropriate privileges 10089@vindex root @r{as default owner} 10090If @command{install} has appropriate privileges (is run as root), set the 10091ownership of installed files or directories to @var{owner}. The default 10092is @code{root}. @var{owner} may be either a user name or a numeric user 10093ID. 10094 10095@item --preserve-context 10096@opindex --preserve-context 10097@cindex SELinux 10098@cindex security context 10099Preserve the SELinux security context of files and directories. 10100Failure to preserve the context in all of the files or directories 10101will result in an exit status of 1. If SELinux is disabled then 10102print a warning and ignore the option. 10103 10104@item -p 10105@itemx --preserve-timestamps 10106@opindex -p 10107@opindex --preserve-timestamps 10108@cindex timestamps of installed files, preserving 10109Set the time of last access and the time of last modification of each 10110installed file to match those of each corresponding original file. 10111When a file is installed without this option, its last access and 10112last modification timestamps are both set to the time of installation. 10113This option is useful if you want to use the last modification timestamps 10114of installed files to keep track of when they were last built as opposed 10115to when they were last installed. 10116 10117@item -s 10118@itemx --strip 10119@opindex -s 10120@opindex --strip 10121@cindex symbol table information, stripping 10122@cindex stripping symbol table information 10123Strip the symbol tables from installed binary executables. 10124 10125@item --strip-program=@var{program} 10126@opindex --strip-program 10127@cindex symbol table information, stripping, program 10128Program used to strip binaries. 10129 10130@optBackupSuffix 10131 10132@optTargetDirectory 10133Also specifying the @option{-D} option will ensure the directory is present. 10134 10135@optNoTargetDirectory 10136 10137@item -v 10138@itemx --verbose 10139@opindex -v 10140@opindex --verbose 10141Print the name of each file before copying it. 10142 10143@optContext 10144This option is mutually exclusive with the @option{--preserve-context} option. 10145 10146 10147@end table 10148 10149@exitstatus 10150 10151 10152@node mv invocation 10153@section @command{mv}: Move (rename) files 10154 10155@pindex mv 10156 10157@command{mv} moves or renames files (or directories). Synopses: 10158 10159@example 10160mv [@var{option}]@dots{} [-T] @var{source} @var{dest} 10161mv [@var{option}]@dots{} @var{source}@dots{} @var{directory} 10162mv [@var{option}]@dots{} -t @var{directory} @var{source}@dots{} 10163@end example 10164 10165@itemize @bullet 10166@item 10167If two file names are given, @command{mv} moves the first file to the 10168second. 10169 10170@item 10171If the @option{--target-directory} (@option{-t}) option is given, or 10172failing that if the last file is a directory and the 10173@option{--no-target-directory} (@option{-T}) option is not given, 10174@command{mv} moves each @var{source} file to the specified 10175directory, using the @var{source}s' names. 10176@end itemize 10177 10178To move a file, @command{mv} ordinarily simply renames it. 10179However, if renaming does not work because the destination's file 10180system differs, @command{mv} falls back on copying as if by @code{cp -a}, 10181then (assuming the copy succeeded) it removes the original. 10182If the copy fails, then @command{mv} removes any partially created 10183copy in the destination. If you were to copy three directories from 10184one file system to another and the copy of the first 10185directory succeeded, but the second didn't, the first would be left on 10186the destination file system and the second and third would be left on the 10187original file system. 10188 10189@cindex extended attributes, xattr 10190@command{mv} always tries to copy extended attributes (xattr), which may 10191include SELinux context, ACLs or Capabilities. 10192Upon failure all but @samp{Operation not supported} warnings are output. 10193 10194@cindex prompting, and @command{mv} 10195If a destination file exists but is normally unwritable, standard input 10196is a terminal, and the @option{-f} or @option{--force} option is not given, 10197@command{mv} prompts the user for whether to replace the file. (You might 10198own the file, or have write permission on its directory.) If the 10199response is not affirmative, the file is skipped. 10200 10201@emph{Warning}: Avoid specifying a source name with a trailing slash, 10202when it might be a symlink to a directory. 10203Otherwise, @command{mv} may do something very surprising, since 10204its behavior depends on the underlying rename system call. 10205On a system with a modern Linux-based kernel, it fails with 10206@code{errno=ENOTDIR}@. 10207However, on other systems (at least FreeBSD 6.1 and Solaris 10) it silently 10208renames not the symlink but rather the directory referenced by the symlink. 10209@xref{Trailing slashes}. 10210 10211@emph{Note}: @command{mv} will only replace empty directories in the 10212destination. Conflicting populated directories are skipped with a diagnostic. 10213 10214The program accepts the following options. Also see @ref{Common options}. 10215 10216@table @samp 10217 10218@optBackup 10219 10220@optDebugCopy 10221 10222@item -f 10223@itemx --force 10224@opindex -f 10225@opindex --force 10226@cindex prompts, omitting 10227Do not prompt the user before removing a destination file. 10228@macro mvOptsIfn 10229If you specify more than one of the @option{-i}, @option{-f}, @option{-n} 10230options, only the final one takes effect. 10231@end macro 10232@mvOptsIfn 10233 10234@item -i 10235@itemx --interactive 10236@opindex -i 10237@opindex --interactive 10238@cindex prompts, forcing 10239Prompt whether to overwrite each existing destination file, regardless 10240of its permissions, and fail if the response is not affirmative. 10241@mvOptsIfn 10242 10243@item -n 10244@itemx --no-clobber 10245@opindex -n 10246@opindex --no-clobber 10247@cindex prompts, omitting 10248Do not overwrite an existing file; silently fail instead. 10249@mvOptsIfn 10250This option is mutually exclusive with @option{-b} or @option{--backup} option. 10251See also the @option{--update=none} option which will 10252skip existing files but not fail. 10253 10254@item --no-copy 10255@opindex --no-copy 10256@cindex renaming files without copying them 10257If a file cannot be renamed because the destination file system differs, 10258fail with a diagnostic instead of copying and then removing the file. 10259 10260@item -u 10261@itemx --update 10262@opindex -u 10263@opindex --update 10264@cindex newer files, moving only 10265Do not move a non-directory that has an existing destination with the 10266same or newer modification timestamp; 10267instead, silently skip the file without failing. 10268If the move is across file system boundaries, the comparison is to the 10269source timestamp truncated to the resolutions of the destination file 10270system and of the system calls used to update timestamps; this avoids 10271duplicate work if several @samp{mv -u} commands are executed with the 10272same source and destination. 10273This option is ignored if the @option{-n} or @option{--no-clobber} 10274option is also specified. 10275 10276@whichUpdate 10277 10278@item -v 10279@itemx --verbose 10280@opindex -v 10281@opindex --verbose 10282Print the name of each file before moving it. 10283 10284@optStripTrailingSlashes 10285 10286@optBackupSuffix 10287 10288@optTargetDirectory 10289 10290@optNoTargetDirectory 10291 10292@item -Z 10293@itemx --context 10294@opindex -Z 10295@opindex --context 10296@cindex SELinux, restoring security context 10297@cindex security context 10298This option functions similarly to the @command{restorecon} command, 10299by adjusting the SELinux security context according 10300to the system default type for destination files and each created directory. 10301 10302@end table 10303 10304@exitstatus 10305 10306 10307@node rm invocation 10308@section @command{rm}: Remove files or directories 10309 10310@pindex rm 10311@cindex removing files or directories 10312 10313@command{rm} removes each given @var{file}. By default, it does not remove 10314directories. Synopsis: 10315 10316@example 10317rm [@var{option}]@dots{} [@var{file}]@dots{} 10318@end example 10319 10320@cindex prompting, and @command{rm} 10321If the @option{-I} or @option{--interactive=once} option is given, 10322and there are more than three files or the @option{-r}, @option{-R}, 10323or @option{--recursive} are given, then @command{rm} prompts the user 10324for whether to proceed with the entire operation. If the response is 10325not affirmative, the entire command is aborted. 10326 10327Otherwise, if a file is unwritable, standard input is a terminal, and 10328the @option{-f} or @option{--force} option is not given, or the 10329@option{-i} or @option{--interactive=always} option @emph{is} given, 10330@command{rm} prompts the user for whether to remove the file. 10331If the response is not affirmative, the file is skipped. 10332 10333Any attempt to remove a file whose last file name component is 10334@file{.} or @file{..} is rejected without any prompting, as mandated 10335by POSIX. 10336 10337@emph{Warning}: If you use @command{rm} to remove a file, it is usually 10338possible to recover the contents of that file. If you want more assurance 10339that the contents are unrecoverable, consider using @command{shred}. 10340 10341The program accepts the following options. Also see @ref{Common options}. 10342 10343@table @samp 10344 10345@item -d 10346@itemx --dir 10347@opindex -d 10348@opindex --dir 10349@cindex directories, removing 10350Remove the listed directories if they are empty. 10351 10352@item -f 10353@itemx --force 10354@opindex -f 10355@opindex --force 10356Ignore nonexistent files and missing operands, and never prompt the user. 10357Ignore any previous @option{--interactive} (@option{-i}) option. 10358 10359@item -i 10360@opindex -i 10361Prompt whether to remove each file. 10362If the response is not affirmative, silently skip the file without failing. 10363Ignore any previous @option{--force} (@option{-f}) option. 10364Equivalent to @option{--interactive=always}. 10365 10366@item -I 10367@opindex -I 10368Prompt once whether to proceed with the command, if more than three 10369files are named or if a recursive removal is requested. Ignore any 10370previous @option{--force} (@option{-f}) option. Equivalent to 10371@option{--interactive=once}. 10372 10373@item --interactive [=@var{when}] 10374@opindex --interactive 10375Specify when to issue an interactive prompt. @var{when} may be 10376omitted, or one of: 10377@itemize @bullet 10378@item never 10379@vindex never @r{interactive option} 10380- Do not prompt at all. 10381@item once 10382@vindex once @r{interactive option} 10383- Prompt once if more than three files are named or if a recursive 10384removal is requested. Equivalent to @option{-I}. 10385@item always 10386@vindex always @r{interactive option} 10387- Prompt for every file being removed. Equivalent to @option{-i}. 10388@end itemize 10389@option{--interactive} with no @var{when} is equivalent to 10390@option{--interactive=always}. 10391 10392@item --one-file-system 10393@opindex --one-file-system 10394@cindex one file system, restricting @command{rm} to 10395When removing a hierarchy recursively, do not remove any directory that is on a 10396file system different from that of the corresponding command line argument. 10397@cindex bind mount 10398This option is useful when removing a build ``chroot'' hierarchy, 10399which normally contains no valuable data. However, it is not uncommon 10400to bind-mount @file{/home} into such a hierarchy, to make it easier to 10401use one's start-up file. The catch is that it's easy to forget to 10402unmount @file{/home}. Then, when you use @command{rm -rf} to remove 10403your normally throw-away chroot, that command will remove everything 10404under @file{/home}, too. 10405Use the @option{--one-file-system} option, and it will 10406diagnose and skip directories on other file systems. 10407Of course, this will not save your @file{/home} if it and your 10408chroot happen to be on the same file system. 10409See also @option{--preserve-root=all} to protect command line arguments 10410themselves. 10411 10412@item --preserve-root [=all] 10413@opindex --preserve-root 10414@cindex root directory, disallow recursive destruction 10415Fail upon any attempt to remove the root directory, @file{/}, 10416when used with the @option{--recursive} option. 10417This is the default behavior. 10418@xref{Treating / specially}. 10419When @samp{all} is specified, reject any command line argument 10420that is not on the same file system as its parent. 10421 10422@item --no-preserve-root 10423@opindex --no-preserve-root 10424@cindex root directory, allow recursive destruction 10425Do not treat @file{/} specially when removing recursively. 10426This option is not recommended unless you really want to 10427remove all the files on your computer. 10428@xref{Treating / specially}. 10429 10430@item -r 10431@itemx -R 10432@itemx --recursive 10433@opindex -r 10434@opindex -R 10435@opindex --recursive 10436@cindex directories, removing (recursively) 10437Remove the listed directories and their contents recursively. 10438 10439@item -v 10440@itemx --verbose 10441@opindex -v 10442@opindex --verbose 10443Print the name of each file before removing it. 10444 10445@end table 10446 10447@cindex files beginning with @samp{-}, removing 10448@cindex @samp{-}, removing files beginning with 10449One common question is how to remove files whose names begin with a 10450@samp{-}. GNU @command{rm}, like every program that uses the @code{getopt} 10451function to parse its arguments, lets you use the @samp{--} option to 10452indicate that all following arguments are non-options. To remove a file 10453called @file{-f} in the current directory, you could type either: 10454 10455@example 10456rm -- -f 10457@end example 10458 10459@noindent 10460or: 10461 10462@example 10463rm ./-f 10464@end example 10465 10466@opindex - @r{and Unix @command{rm}} 10467The Unix @command{rm} program's use of a single @samp{-} for this purpose 10468predates the development of the @code{getopt} standard syntax. 10469 10470@exitstatus 10471 10472 10473@node shred invocation 10474@section @command{shred}: Remove files more securely 10475 10476@pindex shred 10477@cindex data, erasing 10478@cindex erasing data 10479 10480@command{shred} overwrites devices or files, to help prevent even 10481extensive forensics from recovering the data. 10482 10483Ordinarily when you remove a file (@pxref{rm invocation}), its data 10484and metadata are not actually destroyed. Only the file's directory 10485entry is removed, and the file's storage is reclaimed only when no 10486process has the file open and no other directory entry links to the 10487file. And even if file's data and metadata's storage space is freed 10488for further reuse, there are undelete utilities that will attempt to 10489reconstruct the file from the data in freed storage, and that can 10490bring the file back if the storage was not rewritten. 10491 10492On a busy system with a nearly-full device, space can get reused in a few 10493seconds. But there is no way to know for sure. And although the 10494undelete utilities and already-existing processes require insider or 10495superuser access, you may be wary of the superuser, 10496of processes running on your behalf, or of attackers 10497that can physically access the storage device. So if you have sensitive 10498data, you may want to be sure that recovery is not possible 10499by plausible attacks like these. 10500 10501The best way to remove something irretrievably is to destroy the media 10502it's on with acid, melt it down, or the like. For cheap removable media 10503this is often the preferred method. However, some storage devices 10504are expensive or are harder to destroy, so the @command{shred} utility tries 10505to achieve a similar effect non-destructively, by overwriting the file 10506with non-sensitive data. 10507 10508@strong{Please note} that @command{shred} relies on a crucial 10509assumption: that the file system and hardware overwrite data in place. 10510Although this is common and is the traditional 10511way to do things, many modern file system designs do not satisfy this 10512assumption. Exceptions include: 10513 10514@itemize @bullet 10515 10516@item 10517Log-structured or journaled file systems, such as ext3/ext4 (in 10518@code{data=journal} mode), Btrfs, NTFS, ReiserFS, XFS, ZFS, file 10519systems supplied with AIX and Solaris, etc., when they are configured to 10520journal data. 10521 10522@item 10523File systems that write redundant data and carry on even if some writes 10524fail, such as RAID-based file systems. 10525 10526@item 10527File systems that make snapshots, such as Network Appliance's NFS server. 10528 10529@item 10530File systems that cache in temporary locations, such as NFS version 3 10531clients. 10532 10533@item 10534Compressed file systems. 10535@end itemize 10536 10537For ext3 and ext4 file systems, @command{shred} is less effective 10538when the file system is in @code{data=journal} 10539mode, which journals file data in addition to just metadata. In both 10540the @code{data=ordered} (default) and @code{data=writeback} modes, 10541@command{shred} works as usual. The ext3/ext4 journaling modes can be changed 10542by adding the @code{data=something} option to the mount options for a 10543particular file system in the @file{/etc/fstab} file, as documented in 10544the @command{mount} man page (@samp{man mount}). Alternatively, if 10545you know how large the journal is, you can shred the journal by 10546shredding enough file data so that the journal cycles around and fills 10547up with shredded data. 10548 10549If you are not sure how your file system operates, then you should assume 10550that it does not overwrite data in place, which means @command{shred} cannot 10551reliably operate on regular files in your file system. 10552 10553Generally speaking, it is more reliable to shred a device than a file, 10554since this bypasses file system design issues mentioned above. 10555However, devices are also problematic for shredding, for reasons 10556such as the following: 10557 10558@itemize @bullet 10559 10560@item 10561Solid-state storage devices (SSDs) typically do wear leveling to 10562prolong service life, and this means writes are distributed to other 10563blocks by the hardware, so ``overwritten'' data blocks are still 10564present in the underlying device. 10565 10566@item 10567Most storage devices map out bad blocks invisibly to 10568the application; if the bad blocks contain sensitive data, 10569@command{shred} won't be able to destroy it. 10570 10571@item 10572With some obsolete storage technologies, 10573it may be possible to take (say) a floppy disk back 10574to a laboratory and use a lot of sensitive (and expensive) equipment 10575to look for the faint ``echoes'' of the original data underneath the 10576overwritten data. With these older technologies, if the file has been 10577overwritten only once, it's reputedly not even that hard. Luckily, 10578this kind of data recovery has become difficult, and there is no 10579public evidence that today's higher-density storage devices can be 10580analyzed in this way. 10581 10582The @command{shred} command can use many overwrite passes, 10583with data patterns chosen to 10584maximize the damage they do to the old data. 10585By default the patterns are designed for best effect on hard drives using 10586now-obsolete technology; for newer devices, a single pass should suffice. 10587For more details, see the source code and Peter Gutmann's paper 10588@uref{https://www.cs.auckland.ac.nz/~pgut001/pubs/secure_del.html, 10589@cite{Secure Deletion of Data from Magnetic and Solid-State Memory}}, 10590from the proceedings of the Sixth USENIX Security Symposium (San Jose, 10591California, July 22--25, 1996). 10592@end itemize 10593 10594@command{shred} makes no attempt to detect or report these problems, just as 10595it makes no attempt to do anything about backups. However, since it is 10596more reliable to shred devices than files, @command{shred} by default does 10597not deallocate or remove the output file. This default is more suitable 10598for devices, which typically cannot be deallocated and should not be 10599removed. 10600 10601Finally, consider the risk of backups and mirrors. 10602File system backups and remote mirrors may contain copies of the 10603file that cannot be removed, and that will allow a shredded file 10604to be recovered later. So if you keep any data you may later want 10605to destroy using @command{shred}, be sure that it is not backed up or mirrored. 10606 10607@example 10608shred [@var{option}]@dots{} @var{file}[@dots{}] 10609@end example 10610 10611The program accepts the following options. Also see @ref{Common options}. 10612 10613@table @samp 10614 10615@item -f 10616@itemx --force 10617@opindex -f 10618@opindex --force 10619@cindex force deletion 10620Override file permissions if necessary to allow overwriting. 10621 10622@item -n @var{number} 10623@itemx --iterations=@var{number} 10624@opindex -n @var{number} 10625@opindex --iterations=@var{number} 10626@cindex iterations, selecting the number of 10627By default, @command{shred} uses @value{SHRED_DEFAULT_PASSES} passes of 10628overwrite. You can reduce this to save time, or increase it if you think it's 10629appropriate. After 25 passes all of the internal overwrite patterns will have 10630been used at least once. 10631 10632@item --random-source=@var{file} 10633@opindex --random-source 10634@cindex random source for shredding 10635Use @var{file} as a source of random data used to overwrite and to 10636choose pass ordering. @xref{Random sources}. 10637 10638@item -s @var{bytes} 10639@itemx --size=@var{bytes} 10640@opindex -s @var{bytes} 10641@opindex --size=@var{bytes} 10642@cindex size of file to shred 10643Shred the first @var{bytes} bytes of the file. The default is to shred 10644the whole file. @var{bytes} can be followed by a size specification like 10645@samp{K}, @samp{M}, or @samp{G} to specify a multiple. @xref{Block size}. 10646 10647@item -u 10648@itemx --remove[=@var{how}] 10649@opindex -u 10650@opindex --remove 10651@opindex --remove=unlink 10652@opindex --remove=wipe 10653@opindex --remove=wipesync 10654@cindex removing files after shredding 10655After shredding a file, deallocate it (if possible) and then remove it. 10656If a file has multiple links, only the named links will be removed. 10657Often the file name is less sensitive than the file data, in which case 10658the optional @var{how} parameter, supported with the long form option, 10659gives control of how to more efficiently remove each directory entry. 10660The @samp{unlink} parameter will just use a standard unlink call, 10661@samp{wipe} will also first obfuscate bytes in the name, and 10662@samp{wipesync} will also sync each obfuscated byte in the name to 10663the file system. 10664Note @samp{wipesync} is the default method, but can be expensive, 10665requiring a sync for every character in every file. This can become 10666significant with many files, or is redundant if your file system provides 10667synchronous metadata updates. 10668 10669@item -v 10670@itemx --verbose 10671@opindex -v 10672@opindex --verbose 10673Display to standard error all status updates as sterilization proceeds. 10674 10675@item -x 10676@itemx --exact 10677@opindex -x 10678@opindex --exact 10679By default, @command{shred} rounds the size of a regular file up to the next 10680multiple of the file system block size to fully erase the slack space in 10681the last block of the file. This space may contain portions of the current 10682system memory on some systems for example. 10683Use @option{--exact} to suppress that behavior. 10684Thus, by default if you shred a 10-byte regular file on a system with 512-byte 10685blocks, the resulting file will be 512 bytes long. With this option, 10686shred does not increase the apparent size of the file. 10687 10688@item -z 10689@itemx --zero 10690@opindex -z 10691@opindex --zero 10692Normally, the last pass that @command{shred} writes is made up of 10693random data. If this would be conspicuous on your storage device (for 10694example, because it looks like encrypted data), or you just think 10695it's tidier, the @option{--zero} option adds an additional overwrite pass with 10696all zero bits. This is in addition to the number of passes specified 10697by the @option{--iterations} option. 10698 10699@end table 10700 10701You might use the following command to erase the file system you 10702created on a USB flash drive. This command typically takes several 10703minutes, depending on the drive's size and write speed. On modern 10704storage devices a single pass should be adequate, and will take one 10705third the time of the default three-pass approach. 10706 10707@example 10708shred -v -n 1 /dev/sdd1 10709@end example 10710 10711Similarly, to erase all data on a selected partition of 10712your device, you could give a command like the following. 10713 10714@example 10715# 1 pass, write pseudo-random data; 3x faster than the default 10716shred -v -n1 /dev/sda5 10717@end example 10718 10719To be on the safe side, use at least one pass that overwrites using 10720pseudo-random data. I.e., don't be tempted to use @samp{-n0 --zero}, 10721in case some device controller optimizes the process of writing blocks 10722of all zeros, and thereby does not clear all bytes in a block. 10723Some SSDs may do just that. 10724 10725A @var{file} of @samp{-} denotes standard output. 10726The intended use of this is to shred a removed temporary file. 10727For example: 10728 10729@example 10730i=$(mktemp) 10731exec 3<>"$i" 10732rm -- "$i" 10733echo "Hello, world" >&3 10734shred - >&3 10735exec 3>- 10736@end example 10737 10738However, the command @samp{shred - >file} does not shred the contents 10739of @var{file}, since the shell truncates @var{file} before invoking 10740@command{shred}. Use the command @samp{shred file} or (if using a 10741Bourne-compatible shell) the command @samp{shred - 1<>file} instead. 10742 10743@exitstatus 10744 10745 10746@node Special file types 10747@chapter Special file types 10748 10749@cindex special file types 10750@cindex file types, special 10751 10752This chapter describes commands which create special types of files (and 10753@command{rmdir}, which removes directories, one special file type). 10754 10755@cindex special file types 10756@cindex file types 10757Although Unix-like operating systems have markedly fewer special file 10758types than others, not @emph{everything} can be treated only as the 10759undifferentiated byte stream of @dfn{normal files}. For example, when a 10760file is created or removed, the system must record this information, 10761which it does in a @dfn{directory} -- a special type of file. Although 10762you can read directories as normal files, if you're curious, in order 10763for the system to do its job it must impose a structure, a certain 10764order, on the bytes of the file. Thus it is a ``special'' type of file. 10765 10766Besides directories, other special file types include named pipes 10767(FIFOs), symbolic links, sockets, and so-called @dfn{special files}. 10768 10769@menu 10770* link invocation:: Make a hard link via the link syscall 10771* ln invocation:: Make links between files. 10772* mkdir invocation:: Make directories. 10773* mkfifo invocation:: Make FIFOs (named pipes). 10774* mknod invocation:: Make block or character special files. 10775* readlink invocation:: Print value of a symlink or canonical file name. 10776* rmdir invocation:: Remove empty directories. 10777* unlink invocation:: Remove files via the unlink syscall 10778@end menu 10779 10780 10781@node link invocation 10782@section @command{link}: Make a hard link via the link syscall 10783 10784@pindex link 10785@cindex links, creating 10786@cindex hard links, creating 10787@cindex creating links (hard only) 10788 10789@command{link} creates a single hard link at a time. 10790It is a minimalist interface to the system-provided 10791@code{link} function. @xref{Hard Links, , , libc, 10792The GNU C Library Reference Manual}. 10793It avoids the bells and whistles of the more commonly-used 10794@command{ln} command (@pxref{ln invocation}). 10795Synopsis: 10796 10797@example 10798link @var{filename} @var{linkname} 10799@end example 10800 10801@var{filename} must specify an existing file, and @var{linkname} 10802must specify a nonexistent entry in an existing directory. 10803@command{link} simply calls @code{link (@var{filename}, @var{linkname})} 10804to create the link. 10805 10806On a GNU system, this command acts like @samp{ln --directory 10807--no-target-directory @var{filename} @var{linkname}}. However, the 10808@option{--directory} and @option{--no-target-directory} options are 10809not specified by POSIX, and the @command{link} command is 10810more portable in practice. 10811 10812If @var{filename} is a symbolic link, it is unspecified whether 10813@var{linkname} will be a hard link to the symbolic link or to the 10814target of the symbolic link. Use @command{ln -P} or @command{ln -L} 10815to specify which behavior is desired. 10816 10817@exitstatus 10818 10819 10820@node ln invocation 10821@section @command{ln}: Make links between files 10822 10823@pindex ln 10824@cindex links, creating 10825@cindex hard links, creating 10826@cindex symbolic (soft) links, creating 10827@cindex creating links (hard or soft) 10828 10829@cindex file systems and hard links 10830@command{ln} makes links between files. By default, it makes hard links; 10831with the @option{-s} option, it makes symbolic (or @dfn{soft}) links. 10832Synopses: 10833 10834@example 10835ln [@var{option}]@dots{} [-T] @var{target} @var{linkname} 10836ln [@var{option}]@dots{} @var{target} 10837ln [@var{option}]@dots{} @var{target}@dots{} @var{directory} 10838ln [@var{option}]@dots{} -t @var{directory} @var{target}@dots{} 10839@end example 10840 10841@itemize @bullet 10842 10843@item 10844If two file names are given, @command{ln} creates a link to the first 10845file from the second. 10846 10847@item 10848If one @var{target} is given, @command{ln} creates a link to that file 10849in the current directory. 10850 10851@item 10852If the @option{--target-directory} (@option{-t}) option is given, or 10853failing that if the last file is a directory and the 10854@option{--no-target-directory} (@option{-T}) option is not given, 10855@command{ln} creates a link to each @var{target} file in the specified 10856directory, using the @var{target}s' names. 10857 10858@end itemize 10859 10860Normally @command{ln} does not replace existing files. Use the 10861@option{--force} (@option{-f}) option to replace them unconditionally, 10862the @option{--interactive} (@option{-i}) option to replace them 10863conditionally, and the @option{--backup} (@option{-b}) option to 10864rename them. Unless the @option{--backup} (@option{-b}) option is 10865used there is no brief moment when the destination does not exist; 10866this is an extension to POSIX. 10867 10868@cindex hard link, defined 10869@cindex inode, and hard links 10870A @dfn{hard link} is another name for an existing file; the link and the 10871original are indistinguishable. Technically speaking, they share the 10872same inode, and the inode contains all the information about a 10873file -- indeed, it is not incorrect to say that the inode @emph{is} the 10874file. Most systems prohibit making a hard link to 10875a directory; on those where it is allowed, only the super-user can do 10876so (and with caution, since creating a cycle will cause problems to many 10877other utilities). Hard links cannot cross file system boundaries. (These 10878restrictions are not mandated by POSIX, however.) 10879 10880@cindex dereferencing symbolic links 10881@cindex symbolic link, defined 10882@dfn{Symbolic links} (@dfn{symlinks} for short), on the other hand, are 10883a special file type (which not all kernels support: System V release 3 10884(and older) systems lack symlinks) in which the link file actually 10885refers to a different file, by name. When most operations (opening, 10886reading, writing, and so on) are passed the symbolic link file, the 10887kernel automatically @dfn{dereferences} the link and operates on the 10888target of the link. But some operations (e.g., removing) work on the 10889link file itself, rather than on its target. The owner and group of a 10890symlink are not significant to file access performed through 10891the link, but do have implications on deleting a symbolic link from a 10892directory with the restricted deletion bit set. On the GNU system, 10893the mode of a symlink has no significance and cannot be changed, but 10894on some BSD systems, the mode can be changed and will affect whether 10895the symlink will be traversed in file name resolution. @xref{Symbolic Links,,, 10896libc, The GNU C Library Reference Manual}. 10897 10898Symbolic links can contain arbitrary strings; a @dfn{dangling symlink} 10899occurs when the string in the symlink does not resolve to a file. 10900There are no restrictions against creating dangling symbolic links. 10901There are trade-offs to using absolute or relative symlinks. An 10902absolute symlink always points to the same file, even if the directory 10903containing the link is moved. However, if the symlink is visible from 10904more than one machine (such as on a networked file system), the file 10905pointed to might not always be the same. A relative symbolic link is 10906resolved in relation to the directory that contains the link, and is 10907often useful in referring to files on the same device without regards 10908to what name that device is mounted on when accessed via networked 10909machines. 10910 10911When creating a relative symlink in a different location than the 10912current directory, the resolution of the symlink will be different 10913than the resolution of the same string from the current directory. 10914Therefore, many users prefer to first change directories to the 10915location where the relative symlink will be created, so that 10916tab-completion or other file resolution will find the same target as 10917what will be placed in the symlink. 10918 10919The program accepts the following options. Also see @ref{Common options}. 10920 10921@table @samp 10922 10923@optBackup 10924 10925@item -d 10926@itemx -F 10927@itemx --directory 10928@opindex -d 10929@opindex -F 10930@opindex --directory 10931@cindex hard links to directories 10932Allow users with appropriate privileges to attempt to make hard links 10933to directories. 10934However, note that this will probably fail due to 10935system restrictions, even for the super-user. 10936 10937@item -f 10938@itemx --force 10939@opindex -f 10940@opindex --force 10941Remove existing destination files. 10942 10943@item -i 10944@itemx --interactive 10945@opindex -i 10946@opindex --interactive 10947@cindex prompting, and @command{ln} 10948Prompt whether to remove existing destination files, 10949and fail if the response is not affirmative. 10950 10951@item -L 10952@itemx --logical 10953@opindex -L 10954@opindex --logical 10955If @option{-s} is not in effect, and the source file is a symbolic 10956link, create the hard link to the file referred to by the symbolic 10957link, rather than the symbolic link itself. 10958 10959@item -n 10960@itemx --no-dereference 10961@opindex -n 10962@opindex --no-dereference 10963Do not treat the last operand specially when it is a symbolic link to 10964a directory. Instead, treat it as if it were a normal file. 10965 10966When the destination is an actual directory (not a symlink to one), 10967there is no ambiguity. The link is created in that directory. 10968But when the specified destination is a symlink to a directory, 10969there are two ways to treat the user's request. @command{ln} can 10970treat the destination just as it would a normal directory and create 10971the link in it. On the other hand, the destination can be viewed as a 10972non-directory -- as the symlink itself. In that case, @command{ln} 10973must delete or backup that symlink before creating the new link. 10974The default is to treat a destination that is a symlink to a directory 10975just like a directory. 10976 10977This option is weaker than the @option{--no-target-directory} 10978(@option{-T}) option, so it has no effect if both options are given. 10979 10980@item -P 10981@itemx --physical 10982@opindex -P 10983@opindex --physical 10984If @option{-s} is not in effect, and the source file is a symbolic 10985link, create the hard link to the symbolic link itself. On platforms 10986where this is not supported by the kernel, this option creates a 10987symbolic link with identical contents; since symbolic link contents 10988cannot be edited, any file name resolution performed through either 10989link will be the same as if a hard link had been created. 10990 10991@item -r 10992@itemx --relative 10993@opindex -r 10994@opindex --relative 10995Make symbolic links relative to the link location. 10996This option is only valid with the @option{--symbolic} option. 10997 10998Example: 10999 11000@example 11001ln -srv /a/file /tmp 11002'/tmp/file' -> '../a/file' 11003@end example 11004 11005Relative symbolic links are generated based on their canonicalized 11006containing directory, and canonicalized targets. I.e., all symbolic 11007links in these file names will be resolved. 11008@xref{realpath invocation}, which gives greater control 11009over relative file name generation, as demonstrated in the following example: 11010 11011@example 11012@verbatim 11013ln--relative() { 11014 test "$1" = --no-symlinks && { nosym=$1; shift; } 11015 target="$1"; 11016 test -d "$2" && link="$2/." || link="$2" 11017 rtarget="$(realpath $nosym -m "$target" \ 11018 --relative-to "$(dirname "$link")")" 11019 ln -s -v "$rtarget" "$link" 11020} 11021@end verbatim 11022@end example 11023 11024@item -s 11025@itemx --symbolic 11026@opindex -s 11027@opindex --symbolic 11028Make symbolic links instead of hard links. This option merely produces 11029an error message on systems that do not support symbolic links. 11030 11031@optBackupSuffix 11032 11033@optTargetDirectory 11034 11035@optNoTargetDirectory 11036 11037@item -v 11038@itemx --verbose 11039@opindex -v 11040@opindex --verbose 11041Print the name of each file after linking it successfully. 11042 11043@end table 11044 11045@cindex hard links to symbolic links 11046@cindex symbolic links and @command{ln} 11047If @option{-L} and @option{-P} are both given, the last one takes 11048precedence. If @option{-s} is also given, @option{-L} and @option{-P} 11049are silently ignored. If neither option is given, then this 11050implementation defaults to @option{-P} if the system @code{link} supports 11051hard links to symbolic links (such as the GNU system), and @option{-L} 11052if @code{link} follows symbolic links (such as on BSD). 11053 11054@exitstatus 11055 11056Examples: 11057 11058@example 11059Bad Example: 11060 11061# Create link ../a pointing to a in that directory. 11062# Not really useful because it points to itself. 11063ln -s a .. 11064 11065Better Example: 11066 11067# Change to the target before creating symlinks to avoid being confused. 11068cd .. 11069ln -s adir/a . 11070 11071Bad Example: 11072 11073# Hard coded file names don't move well. 11074ln -s $(pwd)/a /some/dir/ 11075 11076Better Example: 11077 11078# Relative file names survive directory moves and also 11079# work across networked file systems. 11080ln -s afile anotherfile 11081ln -s ../adir/afile yetanotherfile 11082@end example 11083 11084 11085@node mkdir invocation 11086@section @command{mkdir}: Make directories 11087 11088@pindex mkdir 11089@cindex directories, creating 11090@cindex creating directories 11091 11092@command{mkdir} creates directories with the specified names. Synopsis: 11093 11094@example 11095mkdir [@var{option}]@dots{} @var{name}@dots{} 11096@end example 11097 11098@command{mkdir} creates each directory @var{name} in the order given. 11099It reports an error if @var{name} already exists, unless the 11100@option{-p} option is given and @var{name} is a directory. 11101 11102The program accepts the following options. Also see @ref{Common options}. 11103 11104@table @samp 11105 11106@item -m @var{mode} 11107@itemx --mode=@var{mode} 11108@opindex -m 11109@opindex --mode 11110@cindex modes of created directories, setting 11111Set the file permission bits of created directories to @var{mode}, 11112which uses the same syntax as 11113in @command{chmod} and uses @samp{a=rwx} (read, write and execute allowed for 11114everyone) for the point of the departure. @xref{File permissions}. 11115This option affects only directories given on the command line; 11116it does not affect any parents that may be created via the @option{-p} option. 11117 11118Normally the directory has the desired file mode bits at the moment it 11119is created. As a GNU extension, @var{mode} may also mention 11120special mode bits, but in this case there may be a temporary window 11121during which the directory exists but its special mode bits are 11122incorrect. @xref{Directory Setuid and Setgid}, for how the 11123set-user-ID and set-group-ID bits of directories are inherited unless 11124overridden in this way. 11125 11126@item -p 11127@itemx --parents 11128@opindex -p 11129@opindex --parents 11130@cindex parent directories, creating 11131Make any missing parent directories for each argument, setting their 11132file permission bits to @samp{=rwx,u+wx}, 11133that is, with the umask modified by @samp{u+wx}. Ignore 11134existing parent directories, and do not change their file permission 11135bits. 11136 11137If the @option{-m} option is also given, it does not affect 11138file permission bits of any newly-created parent directories. 11139To control these bits, set the 11140umask before invoking @command{mkdir}. For example, if the shell 11141command @samp{(umask u=rwx,go=rx; mkdir -p P/Q)} creates the parent 11142@file{P} it sets the parent's file permission bits to @samp{u=rwx,go=rx}. 11143(The umask must include @samp{u=wx} for this method to work.) 11144To set a parent's special mode bits as well, you can invoke 11145@command{chmod} after @command{mkdir}. @xref{Directory Setuid and 11146Setgid}, for how the set-user-ID and set-group-ID bits of 11147newly-created parent directories are inherited. 11148 11149@item -v 11150@itemx --verbose 11151@opindex -v 11152@opindex --verbose 11153Print a message for each created directory. This is most useful with 11154@option{--parents}. 11155 11156@optContext 11157 11158@end table 11159 11160@exitstatus 11161 11162 11163@node mkfifo invocation 11164@section @command{mkfifo}: Make FIFOs (named pipes) 11165 11166@pindex mkfifo 11167@cindex FIFOs, creating 11168@cindex named pipes, creating 11169@cindex creating FIFOs (named pipes) 11170 11171@command{mkfifo} creates FIFOs (also called @dfn{named pipes}) with the 11172specified names. Synopsis: 11173 11174@example 11175mkfifo [@var{option}] @var{name}@dots{} 11176@end example 11177 11178A @dfn{FIFO} is a special file type that permits independent processes 11179to communicate. One process opens the FIFO file for writing, and 11180another for reading, after which data can flow as with the usual 11181anonymous pipe in shells or elsewhere. 11182 11183The program accepts the following options. Also see @ref{Common options}. 11184 11185@table @samp 11186 11187@item -m @var{mode} 11188@itemx --mode=@var{mode} 11189@opindex -m 11190@opindex --mode 11191@cindex modes of created FIFOs, setting 11192Set the mode of created FIFOs to @var{mode}, which is symbolic as in 11193@command{chmod} and uses @samp{a=rw} (read and write allowed for everyone) 11194for the point of departure. @var{mode} should specify only file 11195permission bits. @xref{File permissions}. 11196 11197@optContext 11198 11199@end table 11200 11201@exitstatus 11202 11203 11204@node mknod invocation 11205@section @command{mknod}: Make block or character special files 11206 11207@pindex mknod 11208@cindex block special files, creating 11209@cindex character special files, creating 11210 11211@command{mknod} creates a FIFO, character special file, or block special 11212file with the specified name. Synopsis: 11213 11214@example 11215mknod [@var{option}]@dots{} @var{name} @var{type} [@var{major} @var{minor}] 11216@end example 11217 11218@cindex special files 11219@cindex block special files 11220@cindex character special files 11221Unlike the phrase ``special file type'' above, the term @dfn{special 11222file} has a technical meaning on Unix: something that can generate or 11223receive data. Usually this corresponds to a physical piece of hardware, 11224e.g., a printer or a flash drive. (These files are typically created at 11225system-configuration time.) The @command{mknod} command is what creates 11226files of this type. Such devices can be read either a character at a 11227time or a ``block'' (many characters) at a time, hence we say there are 11228@dfn{block special} files and @dfn{character special} files. 11229 11230@c mknod is a shell built-in at least with OpenBSD's /bin/sh 11231@mayConflictWithShellBuiltIn{mknod} 11232 11233The arguments after @var{name} specify the type of file to make: 11234 11235@table @samp 11236 11237@item p 11238@opindex p @r{for FIFO file} 11239for a FIFO 11240 11241@item b 11242@opindex b @r{for block special file} 11243for a block special file 11244 11245@item c 11246@c Don't document the 'u' option -- it's just a synonym for 'c'. 11247@c Do *any* versions of mknod still use it? 11248@c @itemx u 11249@opindex c @r{for character special file} 11250@c @opindex u @r{for character special file} 11251for a character special file 11252 11253@end table 11254 11255When making a block or character special file, the major and minor 11256device numbers must be given after the file type. 11257If a major or minor device number begins with @samp{0x} or @samp{0X}, 11258it is interpreted as hexadecimal; otherwise, if it begins with @samp{0}, 11259as octal; otherwise, as decimal. 11260 11261The program accepts the following options. Also see @ref{Common options}. 11262 11263@table @samp 11264 11265@item -m @var{mode} 11266@itemx --mode=@var{mode} 11267@opindex -m 11268@opindex --mode 11269Set the mode of created files to @var{mode}, which is symbolic as in 11270@command{chmod} and uses @samp{a=rw} as the point of departure. 11271@var{mode} should specify only file permission bits. 11272@xref{File permissions}. 11273 11274@optContext 11275 11276@end table 11277 11278@exitstatus 11279 11280 11281@node readlink invocation 11282@section @command{readlink}: Print value of a symlink or canonical file name 11283 11284@pindex readlink 11285@cindex displaying value of a symbolic link 11286@cindex canonical file name 11287@cindex canonicalize a file name 11288@cindex realpath 11289 11290@command{readlink} may work in one of two supported modes: 11291 11292@table @samp 11293 11294@item Readlink mode 11295 11296@command{readlink} outputs the value of the given symbolic links. 11297If @command{readlink} is invoked with an argument other than the name 11298of a symbolic link, it produces no output and exits with a nonzero exit code. 11299 11300@item Canonicalize mode 11301 11302@command{readlink} outputs the absolute name of the given files which contain 11303no @file{.}, @file{..} components nor any repeated separators 11304(@file{/}) or symbolic links. Note the @command{realpath} command is the 11305preferred command to use for canonicalization. @xref{realpath invocation}. 11306 11307@end table 11308 11309@example 11310readlink [@var{option}]@dots{} @var{file}@dots{} 11311@end example 11312 11313By default, @command{readlink} operates in readlink mode. 11314 11315The program accepts the following options. Also see @ref{Common options}. 11316 11317@table @samp 11318 11319@item -f 11320@itemx --canonicalize 11321@opindex -f 11322@opindex --canonicalize 11323Activate canonicalize mode. 11324If any component of the file name except the last one is missing or unavailable, 11325@command{readlink} produces no output and exits with a nonzero exit 11326code. A trailing slash is ignored. 11327 11328@item -e 11329@itemx --canonicalize-existing 11330@opindex -e 11331@opindex --canonicalize-existing 11332Activate canonicalize mode. 11333If any component is missing or unavailable, @command{readlink} produces 11334no output and exits with a nonzero exit code. A trailing slash 11335requires that the name resolve to a directory. 11336 11337@item -m 11338@itemx --canonicalize-missing 11339@opindex -m 11340@opindex --canonicalize-missing 11341Activate canonicalize mode. 11342If any component is missing or unavailable, @command{readlink} treats it 11343as a directory. 11344 11345@item -n 11346@itemx --no-newline 11347@opindex -n 11348@opindex --no-newline 11349Do not print the output delimiter, when a single @var{file} is specified. 11350Print a warning if specified along with multiple @var{file}s. 11351 11352@item -s 11353@itemx -q 11354@itemx --silent 11355@itemx --quiet 11356@opindex -s 11357@opindex -q 11358@opindex --silent 11359@opindex --quiet 11360Suppress most error messages. On by default. 11361 11362@item -v 11363@itemx --verbose 11364@opindex -v 11365@opindex --verbose 11366Report error messages. 11367 11368@optZero 11369 11370@end table 11371 11372The @command{readlink} utility first appeared in OpenBSD 2.1. 11373 11374The @command{realpath} command without options, operates like 11375@command{readlink} in canonicalize mode. 11376 11377@exitstatus 11378 11379 11380@node rmdir invocation 11381@section @command{rmdir}: Remove empty directories 11382 11383@pindex rmdir 11384@cindex removing empty directories 11385@cindex directories, removing empty 11386 11387@command{rmdir} removes empty directories. Synopsis: 11388 11389@example 11390rmdir [@var{option}]@dots{} @var{directory}@dots{} 11391@end example 11392 11393If any @var{directory} argument does not refer to an existing empty 11394directory, it is an error. 11395 11396The program accepts the following options. Also see @ref{Common options}. 11397 11398@table @samp 11399 11400@item --ignore-fail-on-non-empty 11401@opindex --ignore-fail-on-non-empty 11402@cindex directory deletion, ignoring failures 11403Ignore each failure to remove a directory that is non-empty. 11404 11405@item -p 11406@itemx --parents 11407@opindex -p 11408@opindex --parents 11409@cindex parent directories, removing 11410Remove @var{directory}, then try to remove each component of @var{directory}. 11411So, for example, @samp{rmdir -p a/b/c} is similar to @samp{rmdir a/b/c a/b a}. 11412As such, it fails if any of those directories turns out not to be empty. 11413Use the @option{--ignore-fail-on-non-empty} option to make it so such 11414a failure does not evoke a diagnostic and does not cause @command{rmdir} to 11415exit unsuccessfully. 11416 11417@item -v 11418@itemx --verbose 11419@opindex -v 11420@opindex --verbose 11421@cindex directory deletion, reporting 11422Give a diagnostic for each successful removal. 11423@var{directory} is removed. 11424 11425@end table 11426 11427@xref{rm invocation}, for how to remove non-empty directories recursively. 11428 11429To remove all empty directories under @var{dirname}, including 11430directories that become empty because other directories are removed, 11431you can use either of the following commands: 11432 11433@example 11434# This uses GNU extensions. 11435find @var{dirname} -type d -empty -delete 11436 11437# This runs on any POSIX platform. 11438find @var{dirname} -depth -type d -exec rmdir @{@} + 11439@end example 11440 11441@exitstatus 11442 11443 11444@node unlink invocation 11445@section @command{unlink}: Remove files via the unlink syscall 11446 11447@pindex unlink 11448@cindex removing files or directories (via the unlink syscall) 11449 11450@command{unlink} deletes a single specified file name. 11451It is a minimalist interface to the system-provided 11452@code{unlink} function. @xref{Deleting Files, , , libc, 11453The GNU C Library Reference Manual}. Synopsis: 11454It avoids the bells and whistles of the more commonly-used 11455@command{rm} command (@pxref{rm invocation}). 11456 11457@example 11458unlink @var{filename} 11459@end example 11460 11461On some systems @code{unlink} can be used to delete the name of a 11462directory. On others, it can be used that way only by a privileged user. 11463In the GNU system @code{unlink} can never delete the name of a directory. 11464 11465The @command{unlink} command honors the @option{--help} and 11466@option{--version} options. To remove a file whose name begins with 11467@samp{-}, prefix the name with @samp{./}, e.g., @samp{unlink ./--help}. 11468 11469@exitstatus 11470 11471 11472@node Changing file attributes 11473@chapter Changing file attributes 11474 11475@cindex changing file attributes 11476@cindex file attributes, changing 11477@cindex attributes, file 11478 11479A file is not merely its contents, a name, and a file type 11480(@pxref{Special file types}). A file also has an owner (a user ID), a 11481group (a group ID), permissions (what the owner can do with the file, 11482what people in the group can do, and what everyone else can do), various 11483timestamps, and other information. Collectively, we call these a file's 11484@dfn{attributes}. 11485 11486These commands change file attributes. 11487 11488@menu 11489* chown invocation:: Change file owners and groups. 11490* chgrp invocation:: Change file groups. 11491* chmod invocation:: Change access permissions. 11492* touch invocation:: Change file timestamps. 11493@end menu 11494 11495 11496@node chown invocation 11497@section @command{chown}: Change file owner and group 11498 11499@pindex chown 11500@cindex file ownership, changing 11501@cindex group ownership, changing 11502@cindex changing file ownership 11503@cindex changing group ownership 11504 11505@command{chown} changes the user and/or group ownership of each given @var{file} 11506to @var{new-owner} or to the user and group of an existing reference file. 11507Synopsis: 11508 11509@example 11510chown [@var{option}]@dots{} @{@var{new-owner} | --reference=@var{ref_file}@}@c 11511 @var{file}@dots{} 11512@end example 11513 11514If used, @var{new-owner} specifies the new owner and/or group as follows 11515(with no embedded white space): 11516 11517@example 11518[@var{owner}] [ : [@var{group}] ] 11519@end example 11520 11521Specifically: 11522 11523@table @var 11524@item owner 11525If only an @var{owner} (a user name or numeric user ID) is given, that 11526user is made the owner of each given file, and the files' group is not 11527changed. 11528 11529@item owner@samp{:}group 11530If the @var{owner} is followed by a colon and a @var{group} (a 11531group name or numeric group ID), with no spaces between them, the group 11532ownership of the files is changed as well (to @var{group}). 11533 11534@item owner@samp{:} 11535If a colon but no group name follows @var{owner}, that user is 11536made the owner of the files and the group of the files is changed to 11537@var{owner}'s login group. 11538 11539@item @samp{:}group 11540If the colon and following @var{group} are given, but the owner 11541is omitted, only the group of the files is changed; in this case, 11542@command{chown} performs the same function as @command{chgrp}. 11543 11544@item @samp{:} 11545If only a colon is given, or if @var{new-owner} is empty, neither the 11546owner nor the group is changed. 11547 11548@end table 11549 11550If @var{owner} or @var{group} is intended to represent a numeric user 11551or group ID, then you may specify it with a leading @samp{+}. 11552@xref{Disambiguating names and IDs}. 11553 11554Some older scripts may still use @samp{.} in place of the @samp{:} separator. 11555POSIX 1003.1-2001 (@pxref{Standards conformance}) does not 11556require support for that, but for backward compatibility GNU 11557@command{chown} supports @samp{.} so long as no ambiguity results, 11558although it issues a warning and support may be removed in future versions. 11559New scripts should avoid the use of @samp{.} because it is not 11560portable, and because it has undesirable results if the entire 11561@var{owner@samp{.}group} happens to identify a user whose name 11562contains @samp{.}. 11563 11564@macro chownGroupRestrictions 11565It is system dependent whether a user can change the group to an arbitrary one, 11566or the more portable behavior of being restricted to setting a group of 11567which the user is a member. 11568@end macro 11569@chownGroupRestrictions 11570 11571The @command{chown} command sometimes clears the set-user-ID or 11572set-group-ID permission bits. This behavior depends on the policy and 11573functionality of the underlying @code{chown} system call, which may 11574make system-dependent file mode modifications outside the control of 11575the @command{chown} command. For example, the @command{chown} command 11576might not affect those bits when invoked by a user with appropriate 11577privileges, or when the 11578bits signify some function other than executable permission (e.g., 11579mandatory locking). 11580When in doubt, check the underlying system behavior. 11581 11582The program accepts the following options. Also see @ref{Common options}. 11583 11584@table @samp 11585 11586@item -c 11587@itemx --changes 11588@opindex -c 11589@opindex --changes 11590@cindex changed owners, verbosely describing 11591Verbosely describe the action for each @var{file} whose ownership 11592actually changes. 11593 11594@item -f 11595@itemx --silent 11596@itemx --quiet 11597@opindex -f 11598@opindex --silent 11599@opindex --quiet 11600@cindex error messages, omitting 11601Do not print error messages about files whose ownership cannot be 11602changed. 11603 11604@item --from=@var{old-owner} 11605@opindex --from 11606@cindex symbolic links, changing owner 11607Change a @var{file}'s ownership only if it has current attributes specified 11608by @var{old-owner}. @var{old-owner} has the same form as @var{new-owner} 11609described above. 11610This option is useful primarily from a security standpoint in that 11611it narrows considerably the window of potential abuse. 11612For example, to reflect a user ID numbering change for one user's files 11613without an option like this, @code{root} might run 11614 11615@example 11616find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER 11617@end example 11618 11619But that is dangerous because the interval between when the @command{find} 11620tests the existing file's owner and when the @command{chown} is actually run 11621may be quite large. 11622One way to narrow the gap would be to invoke chown for each file 11623as it is found: 11624 11625@example 11626find / -owner OLDUSER -exec chown -h NEWUSER @{@} \; 11627@end example 11628 11629But that is very slow if there are many affected files. 11630With this option, it is safer (the gap is narrower still) 11631though still not perfect: 11632 11633@example 11634chown -h -R --from=OLDUSER NEWUSER / 11635@end example 11636 11637@item --dereference 11638@opindex --dereference 11639@cindex symbolic links, changing owner 11640@findex lchown 11641Do not act on symbolic links themselves but rather on what they point to. 11642This is the default when not operating recursively. 11643@warnOptDerefWithRec 11644 11645@item -h 11646@itemx --no-dereference 11647@opindex -h 11648@opindex --no-dereference 11649@cindex symbolic links, changing owner 11650@findex lchown 11651Act on symbolic links themselves instead of what they point to. 11652This mode relies on the @code{lchown} system call. 11653On systems that do not provide the @code{lchown} system call, 11654@command{chown} fails when a file specified on the command line 11655is a symbolic link. 11656By default, no diagnostic is issued for symbolic links encountered 11657during a recursive traversal, but see @option{--verbose}. 11658 11659@item --preserve-root 11660@opindex --preserve-root 11661@cindex root directory, disallow recursive modification 11662Fail upon any attempt to recursively change the root directory, @file{/}. 11663Without @option{--recursive}, this option has no effect. 11664@xref{Treating / specially}. 11665 11666@item --no-preserve-root 11667@opindex --no-preserve-root 11668@cindex root directory, allow recursive modification 11669Cancel the effect of any preceding @option{--preserve-root} option. 11670@xref{Treating / specially}. 11671 11672@item --reference=@var{ref_file} 11673@opindex --reference 11674Change the user and group of each @var{file} to be the same as those of 11675@var{ref_file}. If @var{ref_file} is a symbolic link, do not use the 11676user and group of the symbolic link, but rather those of the file it 11677refers to. 11678 11679@item -v 11680@itemx --verbose 11681@opindex -v 11682@opindex --verbose 11683Output a diagnostic for every file processed. 11684If a symbolic link is encountered during a recursive traversal 11685on a system without the @code{lchown} system call, and @option{--no-dereference} 11686is in effect, then issue a diagnostic saying neither the symbolic link nor 11687its referent is being changed. 11688 11689@item -R 11690@itemx --recursive 11691@opindex -R 11692@opindex --recursive 11693@cindex recursively changing file ownership 11694Recursively change ownership of directories and their contents. 11695 11696@choptH 11697@xref{Traversing symlinks}. 11698 11699@choptL 11700@warnOptDerefWithRec 11701@xref{Traversing symlinks}. 11702 11703@choptP 11704@xref{Traversing symlinks}. 11705 11706@end table 11707 11708@exitstatus 11709 11710Examples: 11711 11712@example 11713# Change the owner of /u to "root". 11714chown root /u 11715 11716# Likewise, but also change its group to "staff". 11717chown root:staff /u 11718 11719# Change the owner of /u and subfiles to "root". 11720chown -hR root /u 11721@end example 11722 11723 11724@node chgrp invocation 11725@section @command{chgrp}: Change group ownership 11726 11727@pindex chgrp 11728@cindex group ownership, changing 11729@cindex changing group ownership 11730 11731@command{chgrp} changes the group ownership of each given @var{file} 11732to @var{group} (which can be either a group name or a numeric group ID) 11733or to the group of an existing reference file. @xref{chown invocation}. 11734Synopsis: 11735 11736@example 11737chgrp [@var{option}]@dots{} @{@var{group} | --reference=@var{ref_file}@}@c 11738 @var{file}@dots{} 11739@end example 11740 11741If @var{group} is intended to represent a 11742numeric group ID, then you may specify it with a leading @samp{+}. 11743@xref{Disambiguating names and IDs}. 11744 11745@chownGroupRestrictions 11746 11747The program accepts the following options. Also see @ref{Common options}. 11748 11749@table @samp 11750 11751@item -c 11752@itemx --changes 11753@opindex -c 11754@opindex --changes 11755@cindex changed files, verbosely describing 11756Verbosely describe the action for each @var{file} whose group actually 11757changes. 11758 11759@item -f 11760@itemx --silent 11761@itemx --quiet 11762@opindex -f 11763@opindex --silent 11764@opindex --quiet 11765@cindex error messages, omitting 11766Do not print error messages about files whose group cannot be 11767changed. 11768 11769@item --dereference 11770@opindex --dereference 11771@cindex symbolic links, changing owner 11772@findex lchown 11773Do not act on symbolic links themselves but rather on what they point to. 11774This is the default when not operating recursively. 11775@warnOptDerefWithRec 11776 11777@item -h 11778@itemx --no-dereference 11779@opindex -h 11780@opindex --no-dereference 11781@cindex symbolic links, changing group 11782@findex lchown 11783Act on symbolic links themselves instead of what they point to. 11784This mode relies on the @code{lchown} system call. 11785On systems that do not provide the @code{lchown} system call, 11786@command{chgrp} fails when a file specified on the command line 11787is a symbolic link. 11788By default, no diagnostic is issued for symbolic links encountered 11789during a recursive traversal, but see @option{--verbose}. 11790 11791@item --preserve-root 11792@opindex --preserve-root 11793@cindex root directory, disallow recursive modification 11794Fail upon any attempt to recursively change the root directory, @file{/}. 11795Without @option{--recursive}, this option has no effect. 11796@xref{Treating / specially}. 11797 11798@item --no-preserve-root 11799@opindex --no-preserve-root 11800@cindex root directory, allow recursive modification 11801Cancel the effect of any preceding @option{--preserve-root} option. 11802@xref{Treating / specially}. 11803 11804@item --reference=@var{ref_file} 11805@opindex --reference 11806Change the group of each @var{file} to be the same as that of 11807@var{ref_file}. If @var{ref_file} is a symbolic link, do not use the 11808group of the symbolic link, but rather that of the file it refers to. 11809 11810@item -v 11811@itemx --verbose 11812@opindex -v 11813@opindex --verbose 11814Output a diagnostic for every file processed. 11815If a symbolic link is encountered during a recursive traversal 11816on a system without the @code{lchown} system call, and @option{--no-dereference} 11817is in effect, then issue a diagnostic saying neither the symbolic link nor 11818its referent is being changed. 11819 11820@item -R 11821@itemx --recursive 11822@opindex -R 11823@opindex --recursive 11824@cindex recursively changing group ownership 11825Recursively change the group ownership of directories and their contents. 11826 11827@choptH 11828@xref{Traversing symlinks}. 11829 11830@choptL 11831@warnOptDerefWithRec 11832@xref{Traversing symlinks}. 11833 11834@choptP 11835@xref{Traversing symlinks}. 11836 11837@end table 11838 11839@exitstatus 11840 11841Examples: 11842 11843@example 11844# Change the group of /u to "staff". 11845chgrp staff /u 11846 11847# Change the group of /u and subfiles to "staff". 11848chgrp -hR staff /u 11849@end example 11850 11851 11852@node chmod invocation 11853@section @command{chmod}: Change access permissions 11854 11855@pindex chmod 11856@cindex changing access permissions 11857@cindex access permissions, changing 11858@cindex permissions, changing access 11859 11860@command{chmod} changes the access permissions of the named files. Synopsis: 11861 11862@example 11863chmod [@var{option}]@dots{} @{@var{mode} | --reference=@var{ref_file}@}@c 11864 @var{file}@dots{} 11865@end example 11866 11867@cindex symbolic links, permissions of 11868@command{chmod} never changes the permissions of symbolic links, since 11869the @command{chmod} system call cannot change their permissions. 11870This is not a problem since the permissions of symbolic links are 11871never used. However, for each symbolic link listed on the command 11872line, @command{chmod} changes the permissions of the pointed-to file. 11873In contrast, @command{chmod} ignores symbolic links encountered during 11874recursive directory traversals. 11875 11876Only a process whose effective user ID matches the user ID of the file, 11877or a process with appropriate privileges, is permitted to change the 11878file mode bits of a file. 11879 11880A successful use of @command{chmod} clears the set-group-ID bit of a 11881regular file if the file's group ID does not match the user's 11882effective group ID or one of the user's supplementary group IDs, 11883unless the user has appropriate privileges. Additional restrictions 11884may cause the set-user-ID and set-group-ID bits of @var{mode} or 11885@var{ref_file} to be ignored. This behavior depends on the policy and 11886functionality of the underlying @code{chmod} system call. When in 11887doubt, check the underlying system behavior. 11888 11889If used, @var{mode} specifies the new file mode bits. 11890For details, see the section on @ref{File permissions}. 11891If you really want @var{mode} to have a leading @samp{-}, you should 11892use @option{--} first, e.g., @samp{chmod -- -w file}. Typically, 11893though, @samp{chmod a-w file} is preferable, and @command{chmod -w 11894file} (without the @option{--}) complains if it behaves differently 11895from what @samp{chmod a-w file} would do. 11896 11897The program accepts the following options. Also see @ref{Common options}. 11898 11899@table @samp 11900 11901@item -c 11902@itemx --changes 11903@opindex -c 11904@opindex --changes 11905Verbosely describe the action for each @var{file} whose permissions 11906actually change. 11907 11908@item -f 11909@itemx --silent 11910@itemx --quiet 11911@opindex -f 11912@opindex --silent 11913@opindex --quiet 11914@cindex error messages, omitting 11915Do not print error messages about files whose permissions cannot be 11916changed. 11917 11918@item --preserve-root 11919@opindex --preserve-root 11920@cindex root directory, disallow recursive modification 11921Fail upon any attempt to recursively change the root directory, @file{/}. 11922Without @option{--recursive}, this option has no effect. 11923@xref{Treating / specially}. 11924 11925@item --no-preserve-root 11926@opindex --no-preserve-root 11927@cindex root directory, allow recursive modification 11928Cancel the effect of any preceding @option{--preserve-root} option. 11929@xref{Treating / specially}. 11930 11931@item -v 11932@itemx --verbose 11933@opindex -v 11934@opindex --verbose 11935Verbosely describe the action or non-action taken for every @var{file}. 11936 11937@item --reference=@var{ref_file} 11938@opindex --reference 11939Change the mode of each @var{file} to be the same as that of @var{ref_file}. 11940@xref{File permissions}. 11941If @var{ref_file} is a symbolic link, do not use the mode 11942of the symbolic link, but rather that of the file it refers to. 11943 11944@item -R 11945@itemx --recursive 11946@opindex -R 11947@opindex --recursive 11948@cindex recursively changing access permissions 11949Recursively change permissions of directories and their contents. 11950 11951@end table 11952 11953@exitstatus 11954 11955Examples: 11956 11957@smallexample 11958# Change file permissions of FOO to be world readable 11959# and user writable, with no other permissions. 11960chmod 644 foo 11961chmod a=r,u+w foo 11962 11963# Add user and group execute permissions to FOO. 11964chmod +110 file 11965chmod ug+x file 11966 11967# Set file permissions of DIR and subsidiary files to 11968# be the umask default, assuming execute permissions for 11969# directories and for files already executable. 11970chmod -R a=,+rwX dir 11971@end smallexample 11972 11973 11974@node touch invocation 11975@section @command{touch}: Change file timestamps 11976 11977@pindex touch 11978@cindex changing file timestamps 11979@cindex file timestamps, changing 11980@cindex timestamps, changing file 11981 11982@command{touch} changes the access and/or modification timestamps of the 11983specified files. Synopsis: 11984 11985@example 11986touch [@var{option}]@dots{} @var{file}@dots{} 11987@end example 11988 11989@cindex empty files, creating 11990Any @var{file} argument that does not exist is created empty, unless 11991option @option{--no-create} (@option{-c}) or @option{--no-dereference} 11992(@option{-h}) was in effect. 11993 11994A @var{file} argument string of @samp{-} is handled specially and 11995causes @command{touch} to change the times of the file associated with 11996standard output. 11997 11998By default, @command{touch} sets file timestamps to the current time. 11999Because @command{touch} acts on its operands left to right, the 12000resulting timestamps of earlier and later operands may disagree. 12001 12002@cindex permissions, for changing file timestamps 12003When setting file timestamps to the current time, @command{touch} can 12004change the timestamps for files that the user does not own but has 12005write permission for. Otherwise, the user must own the files. Some 12006older systems have a further restriction: the user must own the files 12007unless both the access and modification timestamps are being set to the 12008current time. 12009 12010The @command{touch} command cannot set a file's status change timestamp to 12011a user-specified value, and cannot change the file's birth time (if 12012supported) at all. Also, @command{touch} has issues similar to those 12013affecting all programs that update file timestamps. For example, 12014@command{touch} may set a file's timestamp to a value that differs 12015slightly from the requested time. @xref{File timestamps}. 12016 12017@vindex TZ 12018Timestamps assume the time zone rules specified by the @env{TZ} 12019environment variable, or by the system default rules if @env{TZ} is 12020not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, 12021libc, The GNU C Library Reference Manual}. 12022You can avoid ambiguities during 12023daylight saving transitions by using UTC timestamps. 12024 12025The program accepts the following options. Also see @ref{Common options}. 12026 12027@table @samp 12028 12029@item -a 12030@itemx --time=atime 12031@itemx --time=access 12032@itemx --time=use 12033@opindex -a 12034@opindex --time 12035@opindex atime@r{, changing} 12036@opindex access @r{time, changing} 12037@opindex use @r{time, changing} 12038Change the access timestamp only. @xref{File timestamps}. 12039 12040@item -c 12041@itemx --no-create 12042@opindex -c 12043@opindex --no-create 12044Do not warn about or create files that do not exist. 12045 12046@item -d @var{time} 12047@itemx --date=@var{time} 12048@opindex -d 12049@opindex --date 12050@opindex time 12051Use @var{time} instead of the current time. It can contain month names, 12052time zones, @samp{am} and @samp{pm}, @samp{yesterday}, etc. For 12053example, @option{--date="2020-07-21 14:19:13.489392193 +0530"} 12054specifies the instant of time that is 489,392,193 nanoseconds after 12055July 21, 2020 at 2:19:13 PM in a time zone that is 5 hours and 30 12056minutes east of UTC@. @xref{Date input formats}. 12057File systems that do not support high-resolution timestamps 12058silently ignore any excess precision here. 12059 12060@item -f 12061@opindex -f 12062@cindex BSD @command{touch} compatibility 12063Ignored; for compatibility with BSD versions of @command{touch}. 12064 12065@item -h 12066@itemx --no-dereference 12067@opindex -h 12068@opindex --no-dereference 12069@cindex symbolic links, changing time 12070@findex lutimes 12071Attempt to change the timestamps of a symbolic link, rather than what 12072the link refers to. When using this option, empty files are not 12073created, but option @option{-c} must also be used to avoid warning 12074about files that do not exist. Not all systems support changing the 12075timestamps of symlinks, since underlying system support for this 12076action was not required until POSIX 2008. Also, on some 12077systems, the mere act of examining a symbolic link changes the access 12078timestamp, such that only changes to the modification timestamp will persist 12079long enough to be observable. When coupled with option @option{-r}, a 12080reference timestamp is taken from a symbolic link rather than the file 12081it refers to. 12082 12083@item -m 12084@itemx --time=mtime 12085@itemx --time=modify 12086@opindex -m 12087@opindex --time 12088@opindex mtime@r{, changing} 12089@opindex modify @r{time, changing} 12090Change the modification timestamp only. 12091 12092@item -r @var{file} 12093@itemx --reference=@var{file} 12094@opindex -r 12095@opindex --reference 12096Use the times of the reference @var{file} instead of the current time. 12097If this option is combined with the @option{--date=@var{time}} 12098(@option{-d @var{time}}) option, the reference @var{file}'s time is 12099the origin for any relative @var{time}s given, but is otherwise ignored. 12100For example, @samp{-r foo -d '-5 seconds'} specifies a timestamp 12101equal to five seconds before the corresponding timestamp for @file{foo}. 12102If @var{file} is a symbolic link, the reference timestamp is taken 12103from the target of the symlink, unless @option{-h} was also in effect. 12104 12105@item -t [[@var{cc}]@var{yy}]@var{mmddhhmm}[.@var{ss}] 12106@cindex leap seconds 12107Use the argument (optional four-digit or two-digit years, months, 12108days, hours, minutes, optional seconds) instead of the current time. 12109If the year is specified with only two digits, then @var{cc} 12110is 20 for years in the range 0 @dots{} 68, and 19 for years in 1211169 @dots{} 99. If no digits of the year are specified, 12112the argument is interpreted as a date in the current year. 12113On the atypical systems that support leap seconds, @var{ss} may be 12114@samp{60}. 12115 12116@end table 12117 12118@vindex _POSIX2_VERSION 12119On systems predating POSIX 1003.1-2001, 12120@command{touch} supports an obsolete syntax, as follows. 12121If no timestamp is given with any of the @option{-d}, @option{-r}, or 12122@option{-t} options, and if there are two or more @var{file}s and the 12123first @var{file} is of the form @samp{@var{mmddhhmm}[@var{yy}]} and this 12124would be a valid argument to the @option{-t} option (if the @var{yy}, if 12125any, were moved to the front), and if the represented year 12126is in the range 1969--1999, that argument is interpreted as the time 12127for the other files instead of as a file name. 12128Although this obsolete behavior can be controlled with the 12129@env{_POSIX2_VERSION} environment variable (@pxref{Standards 12130conformance}), portable scripts should avoid commands whose 12131behavior depends on this variable. 12132For example, use @samp{touch ./12312359 main.c} or @samp{touch -t 1213312312359 main.c} rather than the ambiguous @samp{touch 12312359 main.c}. 12134 12135@exitstatus 12136 12137 12138@node File space usage 12139@chapter File space usage 12140 12141@cindex File space usage 12142@cindex disk usage 12143 12144No file system can hold an infinite amount of data. These commands report 12145how much storage is in use or available, report other file and 12146file status information, and write buffers to file systems. 12147 12148@menu 12149* df invocation:: Report file system space usage. 12150* du invocation:: Estimate file space usage. 12151* stat invocation:: Report file or file system status. 12152* sync invocation:: Synchronize cached writes to persistent storage. 12153* truncate invocation:: Shrink or extend the size of a file. 12154@end menu 12155 12156 12157@node df invocation 12158@section @command{df}: Report file system space usage 12159 12160@pindex df 12161@cindex file system usage 12162@cindex disk usage by file system 12163 12164@command{df} reports the amount of space used and available on 12165file systems. Synopsis: 12166 12167@example 12168df [@var{option}]@dots{} [@var{file}]@dots{} 12169@end example 12170 12171With no arguments, @command{df} reports the space used and available on all 12172currently mounted file systems (of all types). Otherwise, @command{df} 12173reports on the file system containing each argument @var{file}. 12174 12175Normally the space is printed in units of 121761024 bytes, but this can be overridden (@pxref{Block size}). 12177Non-integer quantities are rounded up to the next higher unit. 12178 12179For bind mounts and without arguments, @command{df} only outputs the statistics 12180for that device with the shortest mount point name in the list of file systems 12181(@var{mtab}), i.e., it hides duplicate entries, unless the @option{-a} option is 12182specified. 12183 12184With the same logic, @command{df} elides a mount entry of a dummy pseudo device 12185if there is another mount entry of a real block device for that mount point with 12186the same device number, e.g. the early-boot pseudo file system @samp{rootfs} is 12187not shown per default when already the real root device has been mounted. 12188 12189@cindex disk device file 12190@cindex device file 12191If an argument @var{file} resolves to a special file containing 12192a mounted file system, @command{df} shows the space available on that 12193file system rather than on the file system containing the device node. 12194GNU @command{df} does not attempt to determine the usage 12195on unmounted file systems, because on most kinds of systems doing so 12196requires extremely non-portable intimate knowledge of file system structures. 12197 12198The program accepts the following options. Also see @ref{Common options}. 12199 12200@table @samp 12201 12202@item -a 12203@itemx --all 12204@opindex -a 12205@opindex --all 12206@cindex ignore file systems 12207Include in the listing dummy, duplicate, or inaccessible file systems, which 12208are omitted by default. Dummy file systems are typically special purpose 12209pseudo file systems such as @samp{/proc}, with no associated storage. 12210Duplicate file systems are local or remote file systems that are mounted 12211at separate locations in the local file hierarchy, or bind mounted locations. 12212Inaccessible file systems are those which are mounted but subsequently 12213over-mounted by another file system at that point, or otherwise inaccessible 12214due to permissions of the mount point etc. 12215 12216@item -B @var{size} 12217@itemx --block-size=@var{size} 12218@opindex -B 12219@opindex --block-size 12220@cindex file system sizes 12221Scale sizes by @var{size} before printing them (@pxref{Block size}). 12222For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes. 12223 12224@optHumanReadable 12225 12226@item -H 12227@opindex -H 12228Equivalent to @option{--si}. 12229 12230@item -i 12231@itemx --inodes 12232@opindex -i 12233@opindex --inodes 12234@cindex inode usage 12235List inode usage information instead of block usage. An inode (short 12236for index node) contains information about a file such as its owner, 12237permissions, timestamps, and location on the file system. 12238 12239@item -k 12240@opindex -k 12241@cindex kibibytes for file system sizes 12242Print sizes in 1024-byte blocks, overriding the default block size 12243(@pxref{Block size}). 12244This option is equivalent to @option{--block-size=1K}. 12245 12246@item -l 12247@itemx --local 12248@opindex -l 12249@opindex --local 12250@cindex file system types, limiting output to certain 12251Limit the listing to local file systems. By default, remote file systems 12252are also listed. 12253 12254@item --no-sync 12255@opindex --no-sync 12256@cindex file system space, retrieving old data more quickly 12257Do not invoke the @code{sync} system call before getting any usage data. 12258This may make @command{df} run significantly faster on systems with many 12259file systems, but on some systems (notably Solaris) the results may be slightly 12260out of date. This is the default. 12261 12262@item --output 12263@itemx --output[=@var{field_list}] 12264@opindex --output 12265Use the output format defined by @var{field_list}, or print all fields if 12266@var{field_list} is omitted. In the latter case, the order of the columns 12267conforms to the order of the field descriptions below. 12268 12269The use of the @option{--output} together with each of the options @option{-i}, 12270@option{-P}, and @option{-T} is mutually exclusive. 12271 12272FIELD_LIST is a comma-separated list of columns to be included in @command{df}'s 12273output and therefore effectively controls the order of output columns. 12274Each field can thus be used at the place of choice, but yet must only be 12275used once. 12276 12277Valid field names in the @var{field_list} are: 12278@table @samp 12279@item source 12280The source of the mount point, usually a device. 12281@item fstype 12282File system type. 12283 12284@item itotal 12285Total number of inodes. 12286@item iused 12287Number of used inodes. 12288@item iavail 12289Number of available inodes. 12290@item ipcent 12291Percentage of @var{iused} divided by @var{itotal}. 12292 12293@item size 12294Total number of blocks. 12295@item used 12296Number of used blocks. 12297@item avail 12298Number of available blocks. 12299@item pcent 12300Percentage of @var{used} divided by @var{size}. 12301 12302@item file 12303The file name if specified on the command line. 12304@item target 12305The mount point. 12306@end table 12307 12308The fields for block and inodes statistics are affected by the scaling 12309options like @option{-h} as usual. 12310 12311The definition of the @var{field_list} can even be split among several 12312@option{--output} uses. 12313 12314@example 12315#!/bin/sh 12316# Print the TARGET (i.e., the mount point) along with their percentage 12317# statistic regarding the blocks and the inodes. 12318df --out=target --output=pcent,ipcent 12319 12320# Print all available fields. 12321df --o 12322@end example 12323 12324 12325@item -P 12326@itemx --portability 12327@opindex -P 12328@opindex --portability 12329@cindex one-line output format 12330@cindex POSIX output format 12331@cindex portable output format 12332@cindex output format, portable 12333Use the POSIX output format. This is like the default format except 12334for the following: 12335 12336@enumerate 12337@item 12338The information about each file system is always printed on exactly 12339one line; a mount device is never put on a line by itself. This means 12340that if the mount device name is more than 20 characters long (e.g., for 12341some network mounts), the columns are misaligned. 12342 12343@item 12344The labels in the header output line are changed to conform to POSIX. 12345 12346@item 12347The default block size and output format are unaffected by the 12348@env{DF_BLOCK_SIZE}, @env{BLOCK_SIZE} and @env{BLOCKSIZE} environment 12349variables. However, the default block size is still affected by 12350@env{POSIXLY_CORRECT}: it is 512 if @env{POSIXLY_CORRECT} is set, 1024 12351otherwise. @xref{Block size}. 12352@end enumerate 12353 12354@optSi 12355 12356@item --sync 12357@opindex --sync 12358@cindex file system space, retrieving current data more slowly 12359Invoke the @code{sync} system call before getting any usage data. On 12360some systems (notably Solaris), doing this yields more up to date results, 12361but in general this option makes @command{df} much slower, especially when 12362there are many or very busy file systems. 12363 12364@item --total 12365@opindex --total 12366@cindex grand total of file system size, usage and available space 12367Print a grand total of all arguments after all arguments have 12368been processed. This can be used to find out the total size, usage 12369and available space of all listed devices. If no arguments are specified 12370df will try harder to elide file systems insignificant to the total 12371available space, by suppressing duplicate remote file systems. 12372 12373For the grand total line, @command{df} prints @samp{"total"} into the 12374@var{source} column, and @samp{"-"} into the @var{target} column. 12375If there is no @var{source} column (see @option{--output}), then 12376@command{df} prints @samp{"total"} into the @var{target} column, 12377if present. 12378 12379@item -t @var{fstype} 12380@itemx --type=@var{fstype} 12381@opindex -t 12382@opindex --type 12383@cindex file system types, limiting output to certain 12384Limit the listing to file systems of type @var{fstype}. Multiple 12385file system types can be specified by giving multiple @option{-t} options. 12386By default, nothing is omitted. 12387 12388@item -T 12389@itemx --print-type 12390@opindex -T 12391@opindex --print-type 12392@cindex file system types, printing 12393Print each file system's type. The types printed here are the same ones 12394you can include or exclude with @option{-t} and @option{-x}. The particular 12395types printed are whatever is supported by the system. Here are some of 12396the common names (this list is certainly not exhaustive): 12397 12398@table @samp 12399 12400@item nfs 12401@cindex NFS file system type 12402An NFS file system, i.e., one mounted over a network from another 12403machine. This is the one type name which seems to be used uniformly by 12404all systems. 12405 12406@item ext2@r{, }ext3@r{, }ext4@r{, }xfs@r{, }btrfs@dots{} 12407@cindex Linux file system types 12408@cindex local file system types 12409@opindex ext2 @r{file system type} 12410@opindex ext3 @r{file system type} 12411@opindex ext4 @r{file system type} 12412@opindex xfs @r{file system type} 12413@opindex btrfs @r{file system type} 12414A file system on a locally-mounted device. (The system might even 12415support more than one type here; GNU/Linux does.) 12416 12417@item iso9660@r{, }cdfs 12418@cindex CD-ROM file system type 12419@cindex DVD file system type 12420@cindex ISO9660 file system type 12421@opindex iso9660 @r{file system type} 12422@opindex cdfs @r{file system type} 12423A file system on a CD or DVD drive. HP-UX uses @samp{cdfs}, most other 12424systems use @samp{iso9660}. 12425 12426@item ntfs@r{,}fat 12427@cindex NTFS file system 12428@cindex DOS file system 12429@cindex MS-DOS file system 12430@cindex MS-Windows file system 12431@opindex ntfs @r{file system file} 12432@opindex fat @r{file system file} 12433File systems used by MS-Windows / MS-DOS. 12434 12435@end table 12436 12437@item -x @var{fstype} 12438@itemx --exclude-type=@var{fstype} 12439@opindex -x 12440@opindex --exclude-type 12441Limit the listing to file systems not of type @var{fstype}. 12442Multiple file system types can be eliminated by giving multiple 12443@option{-x} options. By default, no file system types are omitted. 12444 12445@item -v 12446Ignored; for compatibility with System V versions of @command{df}. 12447 12448@end table 12449 12450@command{df} is installed only on systems that have usable mount tables, 12451so portable scripts should not rely on its existence. 12452 12453@exitstatus 12454Failure includes the case where no output is generated, so you can 12455inspect the exit status of a command like @samp{df -t ext3 -t reiserfs 12456@var{dir}} to test whether @var{dir} is on a file system of type 12457@samp{ext3} or @samp{reiserfs}. 12458 12459Since the list of file systems (@var{mtab}) is needed to determine the 12460file system type, failure includes the cases when that list cannot 12461be read and one or more of the options @option{-a}, @option{-l}, @option{-t} 12462or @option{-x} is used together with a file name argument. 12463 12464 12465@node du invocation 12466@section @command{du}: Estimate file space usage 12467 12468@pindex du 12469@cindex file space usage 12470@cindex disk usage for files 12471 12472@command{du} reports the space needed to represent a set of files. 12473Synopsis: 12474 12475@example 12476du [@var{option}]@dots{} [@var{file}]@dots{} 12477@end example 12478 12479With no arguments, @command{du} reports the space needed to represent 12480the files at or under the current directory. 12481Normally the space is printed in units of 124821024 bytes, but this can be overridden (@pxref{Block size}). 12483Non-integer quantities are rounded up to the next higher unit. 12484 12485If two or more hard links point to the same file, only one of the hard 12486links is counted. The @var{file} argument order affects which links 12487are counted, and changing the argument order may change the numbers 12488and entries that @command{du} outputs. 12489 12490The program accepts the following options. Also see @ref{Common options}. 12491 12492@table @samp 12493 12494@optNull 12495 12496@item -a 12497@itemx --all 12498@opindex -a 12499@opindex --all 12500Show counts for all files, not just directories. 12501 12502@item --apparent-size 12503@opindex --apparent-size 12504Print apparent sizes, rather than file system usage. The apparent size of a 12505file is the number of bytes reported by @code{wc -c} on regular files, 12506or more generally, @code{ls -l --block-size=1} or @code{stat --format=%s}. 12507For example, a file containing the word @samp{zoo} with no newline would, 12508of course, have an apparent size of 3. Such a small file may require 12509anywhere from 0 to 16 KiB or more of file system space, depending on 12510the type and configuration of the file system on which the file resides. 12511However, a sparse file created with this command: 12512 12513@example 12514dd bs=1 seek=2GiB if=/dev/null of=big 12515@end example 12516 12517@noindent 12518has an apparent size of 2 GiB, yet on most modern 12519file systems, it actually uses almost no space. 12520 12521Apparent sizes are meaningful only for regular files and symbolic links. 12522Other file types do not contribute to apparent size. 12523 12524@item -B @var{size} 12525@itemx --block-size=@var{size} 12526@opindex -B 12527@opindex --block-size 12528@cindex file sizes 12529Scale sizes by @var{size} before printing them (@pxref{Block size}). 12530For example, @option{-BG} prints sizes in units of 1,073,741,824 bytes. 12531 12532@item -b 12533@itemx --bytes 12534@opindex -b 12535@opindex --bytes 12536Equivalent to @code{--apparent-size --block-size=1}. 12537 12538@item -c 12539@itemx --total 12540@opindex -c 12541@opindex --total 12542@cindex grand total of file system space 12543Print a grand total of all arguments after all arguments have 12544been processed. This can be used to find out the total file system usage of 12545a given set of files or directories. 12546 12547@item -D 12548@itemx --dereference-args 12549@opindex -D 12550@opindex --dereference-args 12551Dereference symbolic links that are command line arguments. 12552Does not affect other symbolic links. This is helpful for finding 12553out the file system usage of directories, such as @file{/usr/tmp}, which 12554are often symbolic links. 12555 12556@item -d @var{depth} 12557@itemx --max-depth=@var{depth} 12558@opindex -d @var{depth} 12559@opindex --max-depth=@var{depth} 12560@cindex limiting output of @command{du} 12561Show the total for each directory (and file if @option{--all}) that is at 12562most MAX_DEPTH levels down from the root of the hierarchy. The root 12563is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}. 12564 12565@c --files0-from=FILE 12566@filesZeroFromOption{du,, with the @option{--total} (@option{-c}) option} 12567 12568@item -H 12569@opindex -H 12570Equivalent to @option{--dereference-args} (@option{-D}). 12571 12572@optHumanReadable 12573 12574@item --inodes 12575@opindex --inodes 12576@cindex inode usage, dereferencing in @command{du} 12577List inode usage information instead of block usage. 12578This option is useful for finding directories which contain many files, and 12579therefore eat up most of the inodes space of a file system (see @command{df}, 12580option @option{--inodes}). 12581It can well be combined with the options @option{-a}, @option{-c}, 12582@option{-h}, @option{-l}, @option{-s}, @option{-S}, @option{-t} and 12583@option{-x}; however, passing other options regarding the block size, for 12584example @option{-b}, @option{-m} and @option{--apparent-size}, is ignored. 12585 12586@item -k 12587@opindex -k 12588@cindex kibibytes for file sizes 12589Print sizes in 1024-byte blocks, overriding the default block size 12590(@pxref{Block size}). 12591This option is equivalent to @option{--block-size=1K}. 12592 12593@item -L 12594@itemx --dereference 12595@opindex -L 12596@opindex --dereference 12597@cindex symbolic links, dereferencing in @command{du} 12598Dereference symbolic links (show the file system space used by the file 12599or directory that the link points to instead of the space used by 12600the link). 12601 12602@item -l 12603@itemx --count-links 12604@opindex -l 12605@opindex --count-links 12606@cindex hard links, counting in @command{du} 12607Count the size of all files, even if they have appeared already (as a 12608hard link). 12609 12610@item -m 12611@opindex -m 12612@cindex mebibytes for file sizes 12613Print sizes in 1,048,576-byte blocks, overriding the default block size 12614(@pxref{Block size}). 12615This option is equivalent to @option{--block-size=1M}. 12616 12617@item -P 12618@itemx --no-dereference 12619@opindex -P 12620@opindex --no-dereference 12621@cindex symbolic links, dereferencing in @command{du} 12622For each symbolic link encountered by @command{du}, 12623consider the file system space used by the symbolic link itself. 12624 12625@item -S 12626@itemx --separate-dirs 12627@opindex -S 12628@opindex --separate-dirs 12629Normally, in the output of @command{du} (when not using @option{--summarize}), 12630the size listed next to a directory name, @var{d}, represents the sum 12631of sizes of all entries beneath @var{d} as well as the size of @var{d} itself. 12632With @option{--separate-dirs}, the size reported for a directory name, 12633@var{d}, will exclude the size of any subdirectories. 12634 12635@optSi 12636 12637@item -s 12638@itemx --summarize 12639@opindex -s 12640@opindex --summarize 12641Display only a total for each argument. 12642 12643@item -t @var{size} 12644@itemx --threshold=@var{size} 12645@opindex -t 12646@opindex --threshold 12647Exclude entries based on a given @var{size}. The @var{size} refers to used 12648blocks in normal mode (@pxref{Block size}), or inodes count in conjunction 12649with the @option{--inodes} option. 12650 12651If @var{size} is positive, then @command{du} will only print entries with a size 12652greater than or equal to that. 12653 12654If @var{size} is negative, then @command{du} will only print entries with a size 12655smaller than or equal to that. 12656 12657Although GNU @command{find} can be used to find files of a certain size, 12658@command{du}'s @option{--threshold} option can be used to also filter 12659directories based on a given size. 12660 12661When combined with the @option{--apparent-size} option, the 12662@option{--threshold} option elides entries based on apparent size. 12663When combined with the @option{--inodes} option, it elides entries 12664based on inode counts. 12665 12666Here's how you would use @option{--threshold} to find directories with a size 12667greater than or equal to 200 megabytes: 12668 12669@example 12670du --threshold=200MB 12671@end example 12672 12673Here's how you would use @option{--threshold} to find directories and 12674files -- note the @option{-a} -- with an apparent size smaller than or 12675equal to 500 bytes: 12676 12677@example 12678du -a -t -500 --apparent-size 12679@end example 12680 12681Here's how you would use @option{--threshold} to find directories on the root 12682file system with more than 20000 inodes used in the directory tree below: 12683 12684@example 12685du --inodes -x --threshold=20000 / 12686@end example 12687 12688 12689@item --time 12690@opindex --time 12691@cindex last modified dates, displaying in @command{du} 12692Show the most recent modification timestamp (mtime) of any file in the 12693directory, or any of its subdirectories. @xref{File timestamps}. 12694 12695@item --time=ctime 12696@itemx --time=status 12697@itemx --time=use 12698@opindex --time 12699@opindex ctime@r{, show the most recent} 12700@opindex status time@r{, show the most recent} 12701@opindex use time@r{, show the most recent} 12702Show the most recent status change timestamp (ctime) of any file in 12703the directory, or any of its subdirectories. @xref{File timestamps}. 12704 12705@item --time=atime 12706@itemx --time=access 12707@opindex --time 12708@opindex atime@r{, show the most recent} 12709@opindex access timestamp@r{, show the most recent} 12710Show the most recent access timestamp (atime) of any file in the 12711directory, or any of its subdirectories. @xref{File timestamps}. 12712 12713@item --time-style=@var{style} 12714@opindex --time-style 12715@cindex time style 12716List timestamps in style @var{style}. This option has an effect only if 12717the @option{--time} option is also specified. The @var{style} should 12718be one of the following: 12719 12720@table @samp 12721@item +@var{format} 12722@vindex LC_TIME 12723List timestamps using @var{format}, where @var{format} is interpreted 12724like the format argument of @command{date} (@pxref{date invocation}). 12725For example, @option{--time-style="+%Y-%m-%d %H:%M:%S"} causes 12726@command{du} to list timestamps like @samp{2020-07-21 23:45:56}. As 12727with @command{date}, @var{format}'s interpretation is affected by the 12728@env{LC_TIME} locale category. 12729 12730@item full-iso 12731List timestamps in full using ISO 8601-like date, time, and time zone 12732components with nanosecond precision, e.g., @samp{2020-07-21 1273323:45:56.477817180 -0400}. This style is equivalent to 12734@samp{+%Y-%m-%d %H:%M:%S.%N %z}. 12735 12736@item long-iso 12737List ISO 8601 date and time components with minute precision, e.g., 12738@samp{2020-07-21 23:45}. These timestamps are shorter than 12739@samp{full-iso} timestamps, and are usually good enough for everyday 12740work. This style is equivalent to @samp{+%Y-%m-%d %H:%M}. 12741 12742@item iso 12743List ISO 8601 dates for timestamps, e.g., @samp{2020-07-21}. 12744This style is equivalent to @samp{+%Y-%m-%d}. 12745@end table 12746 12747@vindex TIME_STYLE 12748You can specify the default value of the @option{--time-style} option 12749with the environment variable @env{TIME_STYLE}; if @env{TIME_STYLE} is not set 12750the default style is @samp{long-iso}. For compatibility with @command{ls}, 12751if @env{TIME_STYLE} begins with @samp{+} and contains a newline, 12752the newline and any later characters are ignored; if @env{TIME_STYLE} 12753begins with @samp{posix-} the @samp{posix-} is ignored; and if 12754@env{TIME_STYLE} is @samp{locale} it is ignored. 12755 12756@item -X @var{file} 12757@itemx --exclude-from=@var{file} 12758@opindex -X @var{file} 12759@opindex --exclude-from=@var{file} 12760@cindex excluding files from @command{du} 12761Like @option{--exclude}, except take the patterns to exclude from @var{file}, 12762one per line. If @var{file} is @samp{-}, take the patterns from standard 12763input. 12764 12765@item --exclude=@var{pattern} 12766@opindex --exclude=@var{pattern} 12767@cindex excluding files from @command{du} 12768When recursing, skip subdirectories or files matching @var{pattern}. 12769For example, @code{du --exclude='*.o'} excludes files whose names 12770end in @samp{.o}. 12771 12772@item -x 12773@itemx --one-file-system 12774@opindex -x 12775@opindex --one-file-system 12776@cindex one file system, restricting @command{du} to 12777Skip directories that are on different file systems from the one that 12778the argument being processed is on. 12779 12780@end table 12781 12782Since @command{du} relies on information reported by the operating 12783system, its output might not reflect the space consumed in the 12784underlying devices. For example; 12785 12786@itemize @bullet 12787@item 12788Operating systems normally do not report device space consumed by 12789duplicate or backup blocks, error correction bits, and so forth. 12790This causes @command{du} to underestimate the device space actually used. 12791 12792@item 12793@cindex copy-on-write and @command{du} 12794In file systems that use copy-on-write, if two distinct files share 12795space the output of @command{du} typically counts the space that would 12796be consumed if all files' non-holes were rewritten, not the space 12797currently consumed. 12798 12799@item 12800@cindex compression and @command{du} 12801In file systems that use compression, the operating system might 12802report the uncompressed space. (If it does report the compressed space, 12803that report might change after one merely overwrites existing file data.) 12804 12805@item 12806@cindex networked file systems and @command{du} 12807Networked file systems historically have had difficulty communicating 12808accurate file system information from server to client. 12809@end itemize 12810 12811@noindent 12812For these reasons @command{du} might better be thought of as an 12813estimate of the size of a @command{tar} or other conventional backup 12814for a set of files, rather than as a measure of space consumed in the 12815underlying devices. 12816 12817@exitstatus 12818 12819 12820@node stat invocation 12821@section @command{stat}: Report file or file system status 12822 12823@pindex stat 12824@cindex file status 12825@cindex file system status 12826 12827@command{stat} displays information about the specified file(s). Synopsis: 12828 12829@example 12830stat [@var{option}]@dots{} [@var{file}]@dots{} 12831@end example 12832 12833With no option, @command{stat} reports all information about the given files. 12834But it also can be used to report the information of the file systems the 12835given files are located on. If the files are links, @command{stat} can 12836also give information about the files the links point to. 12837 12838@mayConflictWithShellBuiltIn{stat} 12839 12840@table @samp 12841 12842@item -L 12843@itemx --dereference 12844@opindex -L 12845@opindex --dereference 12846@cindex symbolic links, dereferencing in @command{stat} 12847Change how @command{stat} treats symbolic links. 12848With this option, @command{stat} acts on the file referenced 12849by each symbolic link argument. 12850Without it, @command{stat} acts on any symbolic link argument directly. 12851 12852@item -f 12853@itemx --file-system 12854@opindex -f 12855@opindex --file-system 12856@cindex file systems 12857Report information about the file systems where the given files are located 12858instead of information about the files themselves. 12859This option implies the @option{-L} option. 12860 12861@item --cached=@var{mode} 12862@opindex --cached=@var{mode} 12863@cindex attribute caching 12864Control how attributes are read from the file system; 12865if supported by the system. This allows one to 12866control the trade-off between freshness and efficiency 12867of attribute access, especially useful with remote file systems. 12868@var{mode} can be: 12869 12870@table @samp 12871@item always 12872Always read the already cached attributes if available. 12873 12874@item never 12875Always synchronize with the latest file system attributes. 12876This also mounts automounted files. 12877 12878@item default 12879Leave the caching behavior to the underlying file system. 12880 12881@end table 12882 12883@item -c 12884@itemx --format=@var{format} 12885@opindex -c 12886@opindex --format=@var{format} 12887@cindex output format 12888Use @var{format} rather than the default format. 12889@var{format} is automatically newline-terminated, so 12890running a command like the following with two or more @var{file} 12891operands produces a line of output for each operand: 12892@example 12893$ stat --format=%d:%i / /usr 128942050:2 128952057:2 12896@end example 12897 12898@item --printf=@var{format} 12899@opindex --printf=@var{format} 12900@cindex output format 12901Use @var{format} rather than the default format. 12902Like @option{--format}, but interpret backslash escapes, 12903and do not output a mandatory trailing newline. 12904If you want a newline, include @samp{\n} in the @var{format}. 12905Here's how you would use @option{--printf} to print the device 12906and inode numbers of @file{/} and @file{/usr}: 12907@example 12908$ stat --printf='%d:%i\n' / /usr 129092050:2 129102057:2 12911@end example 12912 12913@item -t 12914@itemx --terse 12915@opindex -t 12916@opindex --terse 12917@cindex terse output 12918Print the information in terse form, suitable for parsing by other programs. 12919 12920The output of the following commands are identical and the @option{--format} 12921also identifies the items printed (in fuller form) in the default format. 12922Note the format string would include another @samp{%C} at the end with an 12923active SELinux security context. 12924@example 12925$ stat --format="%n %s %b %f %u %g %D %i %h %t %T %X %Y %Z %W %o" ... 12926$ stat --terse ... 12927@end example 12928 12929The same illustrating terse output in @option{--file-system} mode: 12930@example 12931$ stat -f --format="%n %i %l %t %s %S %b %f %a %c %d" ... 12932$ stat -f --terse ... 12933@end example 12934@end table 12935 12936The valid @var{format} directives for files with @option{--format} and 12937@option{--printf} are: 12938 12939@itemize @bullet 12940@item %a -- Permission bits in octal (note @samp{#} and @samp{0} printf flags) 12941@item %A -- Permission bits in symbolic form (similar to @command{ls -ld}) 12942@item %b -- Number of blocks allocated (see @samp{%B}) 12943@item %B -- The size in bytes of each block reported by @samp{%b} 12944@item %C -- The SELinux security context of a file, if available 12945@item %d -- Device number in decimal (st_dev) 12946@item %D -- Device number in hex (st_dev) 12947@item %Hd -- Major device number in decimal 12948@item %Ld -- Minor device number in decimal 12949@item %f -- Raw mode in hex 12950@item %F -- File type 12951@item %g -- Group ID of owner 12952@item %G -- Group name of owner 12953@item %h -- Number of hard links 12954@item %i -- Inode number 12955@item %m -- Mount point (See note below) 12956@item %n -- File name 12957@item %N -- Quoted file name with dereference if symbolic link (see below) 12958@item %o -- Optimal I/O transfer size hint 12959@item %s -- Total size, in bytes 12960@item %r -- Device type in decimal (st_rdev) 12961@item %R -- Device type in hex (st_rdev) 12962@item %Hr -- Major device type in decimal (see below) 12963@item %Lr -- Minor device type in decimal (see below) 12964@item %t -- Major device type in hex (see below) 12965@item %T -- Minor device type in hex (see below) 12966@item %u -- User ID of owner 12967@item %U -- User name of owner 12968@item %w -- Time of file birth, or @samp{-} if unknown 12969@item %W -- Time of file birth as seconds since Epoch, or @samp{0} 12970@item %x -- Time of last access 12971@item %X -- Time of last access as seconds since Epoch 12972@item %y -- Time of last data modification 12973@item %Y -- Time of last data modification as seconds since Epoch 12974@item %z -- Time of last status change 12975@item %Z -- Time of last status change as seconds since Epoch 12976@end itemize 12977 12978The @samp{%a} format prints the octal mode, and so it is useful 12979to control the zero padding of the output with the @samp{#} and @samp{0} 12980printf flags. For example to pad to at least 3 wide while making larger 12981numbers unambiguously octal, you can use @samp{%#03a}. 12982 12983The @samp{%N} format can be set with the environment variable 12984@env{QUOTING_STYLE}@. If that environment variable is not set, 12985the default value is @samp{shell-escape-always}. Valid quoting styles are: 12986@quotingStyles 12987 12988The @samp{r}, @samp{R}, @samp{%t}, and @samp{%T} formats operate on the st_rdev 12989member of the stat(2) structure, i.e., the represented device rather than 12990the containing device, and so are only defined for character and block 12991special files. On some systems or file types, st_rdev may be used to 12992represent other quantities. 12993 12994The @samp{%W}, @samp{%X}, @samp{%Y}, and @samp{%Z} formats accept a 12995precision preceded by a period to specify the number of digits to 12996print after the decimal point. For example, @samp{%.3X} outputs the 12997access timestamp to millisecond precision. If a period is given but no 12998precision, @command{stat} uses 9 digits, so @samp{%.X} is equivalent to 12999@samp{%.9X}@. When discarding excess precision, timestamps are truncated 13000toward minus infinity. 13001 13002@example 13003zero pad: 13004 $ stat -c '[%015Y]' /usr 13005 [000001288929712] 13006space align: 13007 $ stat -c '[%15Y]' /usr 13008 [ 1288929712] 13009 $ stat -c '[%-15Y]' /usr 13010 [1288929712 ] 13011precision: 13012 $ stat -c '[%.3Y]' /usr 13013 [1288929712.114] 13014 $ stat -c '[%.Y]' /usr 13015 [1288929712.114951834] 13016@end example 13017 13018The mount point printed by @samp{%m} is similar to that output 13019by @command{df}, except that: 13020@itemize @bullet 13021@item 13022stat does not dereference symlinks by default 13023(unless @option{-L} is specified) 13024@item 13025stat does not search for specified device nodes in the 13026file system list, instead operating on them directly 13027@item 13028@cindex bind mount 13029stat outputs the alias for a bind mounted file, rather than 13030the initial mount point of its backing device. 13031One can recursively call stat until there is no change in output, 13032to get the current base mount point 13033@end itemize 13034 13035When listing file system information (@option{--file-system} (@option{-f})), 13036you must use a different set of @var{format} directives: 13037 13038@itemize @bullet 13039@item %a -- Free blocks available to non-super-user 13040@item %b -- Total data blocks in file system 13041@item %c -- Total file nodes in file system 13042@item %d -- Free file nodes in file system 13043@item %f -- Free blocks in file system 13044@item %i -- File System ID in hex 13045@item %l -- Maximum length of file names 13046@item %n -- File name 13047@item %s -- Block size (for faster transfers) 13048@item %S -- Fundamental block size (for block counts) 13049@item %t -- Type in hex 13050@item %T -- Type in human readable form 13051@end itemize 13052 13053@vindex TZ 13054Timestamps are listed according to the time zone rules specified by 13055the @env{TZ} environment variable, or by the system default rules if 13056@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone 13057with @env{TZ}, libc, The GNU C Library Reference Manual}. 13058 13059@exitstatus 13060 13061 13062@node sync invocation 13063@section @command{sync}: Synchronize cached writes to persistent storage 13064 13065@pindex sync 13066@cindex synchronize file system and memory 13067@cindex Synchronize cached writes to persistent storage 13068 13069@command{sync} synchronizes in memory files or file systems to persistent 13070storage. Synopsis: 13071 13072@example 13073sync [@var{option}] [@var{file}]@dots{} 13074@end example 13075 13076@cindex superblock, writing 13077@cindex inodes, written buffered 13078@command{sync} writes any data buffered in memory out to the storage device. 13079This can 13080include (but is not limited to) modified superblocks, modified inodes, 13081and delayed reads and writes. This must be implemented by the kernel; 13082The @command{sync} program does nothing but exercise the @code{sync}, 13083@code{syncfs}, @code{fsync}, and @code{fdatasync} system calls. 13084 13085@cindex crashes and corruption 13086The kernel keeps data in memory to avoid doing (relatively slow) device 13087reads and writes. This improves performance, but if the computer 13088crashes, data may be lost or the file system corrupted as a 13089result. The @command{sync} command instructs the kernel to write 13090data in memory to persistent storage. 13091 13092If any argument is specified then only those files will be 13093synchronized using the fsync(2) syscall by default. 13094 13095If at least one file is specified, it is possible to change the 13096synchronization method with the following options. Also see 13097@ref{Common options}. 13098 13099@table @samp 13100@item -d 13101@itemx --data 13102@opindex --data 13103Use fdatasync(2) to sync only the data for the file, 13104and any metadata required to maintain file system consistency. 13105 13106@item -f 13107@itemx --file-system 13108@opindex --file-system 13109Synchronize all the I/O waiting for the file systems that contain the file, 13110using the syscall syncfs(2). Note you would usually @emph{not} specify 13111this option if passing a device node like @samp{/dev/sda} for example, 13112as that would sync the containing file system rather than the referenced one. 13113Note also that depending on the system, passing individual device nodes or files 13114may have different sync characteristics than using no arguments. 13115I.e., arguments passed to fsync(2) may provide greater guarantees through 13116write barriers, than a global sync(2) used when no arguments are provided. 13117@end table 13118 13119@exitstatus 13120 13121 13122@node truncate invocation 13123@section @command{truncate}: Shrink or extend the size of a file 13124 13125@pindex truncate 13126@cindex truncating, file sizes 13127 13128@command{truncate} shrinks or extends the size of each @var{file} to the 13129specified size. Synopsis: 13130 13131@example 13132truncate @var{option}@dots{} @var{file}@dots{} 13133@end example 13134 13135@cindex files, creating 13136Any @var{file} that does not exist is created. 13137 13138@cindex sparse files, creating 13139@cindex holes, creating files with 13140If a @var{file} is larger than the specified size, the extra data is lost. 13141If a @var{file} is shorter, it is extended and the sparse extended part 13142(or hole) reads as zero bytes. 13143 13144The program accepts the following options. Also see @ref{Common options}. 13145 13146@table @samp 13147 13148@item -c 13149@itemx --no-create 13150@opindex -c 13151@opindex --no-create 13152Do not create files that do not exist. 13153 13154@item -o 13155@itemx --io-blocks 13156@opindex -o 13157@opindex --io-blocks 13158Treat @var{size} as number of I/O blocks of the @var{file} rather than bytes. 13159 13160@item -r @var{rfile} 13161@itemx --reference=@var{rfile} 13162@opindex -r 13163@opindex --reference 13164Base the size of each @var{file} on the size of @var{rfile}. 13165 13166@item -s @var{size} 13167@itemx --size=@var{size} 13168@opindex -s 13169@opindex --size 13170Set or adjust the size of each @var{file} according to @var{size}. 13171@var{size} is in bytes unless @option{--io-blocks} is specified. 13172@multiplierSuffixesNoBlocks{size} 13173 13174@var{size} may also be prefixed by one of the following to adjust 13175the size of each @var{file} based on its current size: 13176@example 13177@samp{+} => extend by 13178@samp{-} => reduce by 13179@samp{<} => at most 13180@samp{>} => at least 13181@samp{/} => round down to multiple of 13182@samp{%} => round up to multiple of 13183@end example 13184 13185@end table 13186 13187@exitstatus 13188 13189 13190@node Printing text 13191@chapter Printing text 13192 13193@cindex printing text, commands for 13194@cindex commands for printing text 13195 13196This section describes commands that display text strings. 13197 13198@menu 13199* echo invocation:: Print a line of text. 13200* printf invocation:: Format and print data. 13201* yes invocation:: Print a string until interrupted. 13202@end menu 13203 13204 13205@node echo invocation 13206@section @command{echo}: Print a line of text 13207 13208@pindex echo 13209@cindex displaying text 13210@cindex printing text 13211@cindex text, displaying 13212@cindex arbitrary text, displaying 13213 13214@command{echo} writes each given @var{string} to standard output, with a 13215space between each and a newline after the last one. Synopsis: 13216 13217@example 13218echo [@var{option}]@dots{} [@var{string}]@dots{} 13219@end example 13220 13221@mayConflictWithShellBuiltIn{echo} 13222 13223Due to historical and backwards compatibility reasons, certain bare option-like 13224strings cannot be passed to @command{echo} as non-option arguments. 13225It is therefore not advisable to use @command{echo} for printing unknown or 13226variable arguments. The @command{printf} command is recommended as a more 13227portable and flexible replacement for tasks historically performed by 13228@command{echo}. @xref{printf invocation}. 13229 13230The program accepts the following options. Also see @ref{Common options}. 13231Options must precede operands, and the normally-special argument 13232@samp{--} has no special meaning and is treated like any other 13233@var{string}. 13234 13235@table @samp 13236@item -n 13237@opindex -n 13238Do not output the trailing newline. 13239 13240@item -e 13241@opindex -e 13242@cindex backslash escapes 13243Enable interpretation of the following backslash-escaped characters in 13244each @var{string}: 13245 13246@table @samp 13247@item \a 13248alert (bell) 13249@item \b 13250backspace 13251@item \c 13252produce no further output 13253@item \e 13254escape 13255@item \f 13256form feed 13257@item \n 13258newline 13259@item \r 13260carriage return 13261@item \t 13262horizontal tab 13263@item \v 13264vertical tab 13265@item \\ 13266backslash 13267@item \0@var{nnn} 13268the eight-bit value that is the octal number @var{nnn} 13269(zero to three octal digits), if @var{nnn} is 13270a nine-bit value, the ninth bit is ignored 13271@item \@var{nnn} 13272the eight-bit value that is the octal number @var{nnn} 13273(one to three octal digits), if @var{nnn} is 13274a nine-bit value, the ninth bit is ignored 13275@item \x@var{hh} 13276the eight-bit value that is the hexadecimal number @var{hh} 13277(one or two hexadecimal digits) 13278@end table 13279 13280@item -E 13281@opindex -E 13282@cindex backslash escapes 13283Disable interpretation of backslash escapes in each @var{string}. 13284This is the default. If @option{-e} and @option{-E} are both 13285specified, the last one given takes effect. 13286 13287@end table 13288 13289@vindex POSIXLY_CORRECT 13290If the @env{POSIXLY_CORRECT} environment variable is set, then when 13291@command{echo}'s first argument is not @option{-n} it outputs 13292option-like arguments instead of treating them as options. For 13293example, @code{echo -ne hello} outputs @samp{-ne hello} instead of 13294plain @samp{hello}. Also backslash escapes are always enabled. 13295Note to echo the string @samp{-n}, one of the characters 13296can be escaped in either octal or hexadecimal representation. 13297For example, @code{echo -e '\x2dn'}. 13298 13299POSIX does not require support for any options, and says 13300that the behavior of @command{echo} is implementation-defined if any 13301@var{string} contains a backslash or if the first argument is @option{-n}. 13302Portable programs should use the @command{printf} command instead. 13303@xref{printf invocation}. 13304 13305@exitstatus 13306 13307 13308@node printf invocation 13309@section @command{printf}: Format and print data 13310 13311@pindex printf 13312@command{printf} does formatted printing of text. Synopsis: 13313 13314@example 13315printf @var{format} [@var{argument}]@dots{} 13316@end example 13317 13318@command{printf} prints the @var{format} string, interpreting @samp{%} 13319directives and @samp{\} escapes to format numeric and string arguments 13320in a way that is mostly similar to the C @samp{printf} function. 13321@xref{Output Conversion Syntax,, @command{printf} format directives, 13322libc, The GNU C Library Reference Manual}, for details. 13323The differences are listed below. 13324 13325@mayConflictWithShellBuiltIn{printf} 13326 13327@itemize @bullet 13328 13329@item 13330The @var{format} argument is reused as necessary to convert all the 13331given @var{argument}s. For example, the command @samp{printf %s a b} 13332outputs @samp{ab}. 13333 13334@item 13335Missing @var{argument}s are treated as null strings or as zeros, 13336depending on whether the context expects a string or a number. For 13337example, the command @samp{printf %sx%d} prints @samp{x0}. 13338 13339@item 13340@kindex \c 13341An additional escape, @samp{\c}, causes @command{printf} to produce no 13342further output. For example, the command @samp{printf 'A%sC\cD%sF' B 13343E} prints @samp{ABC}. 13344 13345@item 13346The hexadecimal escape sequence @samp{\x@var{hh}} has at most two 13347digits, as opposed to C where it can have an unlimited number of 13348digits. For example, the command @samp{printf '\x07e'} prints two 13349bytes, whereas the C statement @samp{printf ("\x07e")} prints just 13350one. 13351 13352@item 13353@kindex %b 13354An additional directive @samp{%b}, prints its 13355argument string with @samp{\} escapes interpreted in the same way as in 13356the @var{format} string, except that octal escapes are of the form 13357@samp{\0@var{ooo}} where @var{ooo} is 0 to 3 octal digits. If 13358@samp{\@var{ooo}} is nine-bit value, ignore the ninth bit. 13359If a precision is also given, it limits the number of bytes printed 13360from the converted string. 13361 13362@item 13363@kindex %q 13364An additional directive @samp{%q}, prints its argument string 13365in a format that can be reused as input by most shells. 13366Non-printable characters are escaped with the POSIX proposed @samp{$''} syntax, 13367and shell metacharacters are quoted appropriately. 13368This is an equivalent format to @command{ls --quoting=shell-escape} output. 13369 13370@item 13371Numeric arguments must be single C constants, possibly with leading 13372@samp{+} or @samp{-}. For example, @samp{printf %.4d -3} outputs 13373@samp{-0003}. 13374 13375@item 13376@vindex POSIXLY_CORRECT 13377If the leading character of a numeric argument is @samp{"} or @samp{'} 13378then its value is the numeric value of the immediately following 13379character. Any remaining characters are silently ignored if the 13380@env{POSIXLY_CORRECT} environment variable is set; otherwise, a 13381warning is printed. For example, @samp{printf "%d" "'a"} outputs 13382@samp{97} on hosts that use the ASCII character set, since 13383@samp{a} has the numeric value 97 in ASCII. 13384 13385@end itemize 13386 13387@vindex LC_NUMERIC 13388A floating point argument is interpreted according to 13389the @env{LC_NUMERIC} category of either the current or the C locale, 13390and is printed according to the current locale. 13391For example, in a locale whose decimal point character is a comma, 13392the command @samp{printf '%g %g' 2,5 2.5} outputs @samp{2,5 2,5}. 13393@xref{Floating point}. 13394 13395@kindex \@var{ooo} 13396@kindex \x@var{hh} 13397@command{printf} interprets @samp{\@var{ooo}} in @var{format} as an octal number 13398(if @var{ooo} is 1 to 3 octal digits) specifying a byte to print, 13399and @samp{\x@var{hh}} as a hexadecimal number (if @var{hh} is 1 to 2 hex 13400digits) specifying a character to print. 13401Note however that when @samp{\@var{ooo}} specifies a number larger than 255, 13402@command{printf} ignores the ninth bit. 13403For example, @samp{printf '\400'} is equivalent to @samp{printf '\0'}. 13404 13405@kindex \uhhhh 13406@kindex \Uhhhhhhhh 13407@cindex Unicode 13408@cindex ISO/IEC 10646 13409@vindex LC_CTYPE 13410@command{printf} interprets two syntax forms for specifying Unicode 13411(ISO/IEC 10646) characters. 13412@samp{\u} for 16-bit Unicode characters, specified as 13413four hexadecimal digits @var{hhhh}, and @samp{\U} for 32-bit Unicode 13414characters, specified as eight hexadecimal digits @var{hhhhhhhh}. 13415@command{printf} outputs the Unicode characters 13416according to the @env{LC_CTYPE} locale. Unicode characters in the range 13417U+D800@dots{}U+DFFF cannot be specified by this syntax. 13418This syntax fully supports the universal character subset 13419introduced in ISO C 99. 13420 13421The processing of @samp{\u} and @samp{\U} requires a full-featured 13422@code{iconv} facility. It is activated on systems with glibc 2.2 (or newer), 13423or when @code{libiconv} is installed prior to this package. Otherwise 13424@samp{\u} and @samp{\U} will print as-is. 13425 13426Unicode character syntax is useful for writing strings in a locale 13427independent way. For example, a string containing the Euro currency symbol 13428 13429@example 13430$ env printf '\u20AC 14.95' 13431@end example 13432 13433@noindent 13434will be output correctly in all locales supporting the Euro symbol 13435(ISO-8859-15, UTF-8, and others). Similarly, a Chinese string 13436 13437@example 13438$ env printf '\u4e2d\u6587' 13439@end example 13440 13441@noindent 13442will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8, etc). 13443 13444Note that in these examples, the @command{printf} command has been 13445invoked via @command{env} to ensure that we run the program found via 13446your shell's search path, and not a shell alias or a built-in function. 13447 13448For larger strings, you don't need to look up the hexadecimal code 13449values of each character one by one. ASCII characters mixed with \u 13450escape sequences is also known as the JAVA source file encoding. You can 13451use GNU recode 3.5c (or newer) to convert strings to this encoding. Here 13452is how to convert a piece of text into a shell script which will output 13453this text in a locale-independent way: 13454 13455@example 13456$ LC_CTYPE=zh_TW.big5 env printf \ 13457 '\u4e2d\u6587\n' > sample.txt 13458$ recode BIG5..JAVA < sample.txt \ 13459 | sed -e "s|^|env printf '|" -e "s|%|%%|g" -e "s|$|\\\\n'|" \ 13460 > sample.sh 13461@end example 13462 13463The only options are a lone @option{--help} or 13464@option{--version}. @xref{Common options}. 13465Options must precede operands. 13466 13467@exitstatus 13468 13469 13470@node yes invocation 13471@section @command{yes}: Print a string until interrupted 13472 13473@pindex yes 13474@cindex repeated output of a string 13475 13476@command{yes} prints the command line arguments, separated by spaces and 13477followed by a newline, forever until it is killed. If no arguments are 13478given, it prints @samp{y} followed by a newline forever until killed. 13479 13480Upon a write error, @command{yes} exits with status @samp{1}. 13481 13482The only options are a lone @option{--help} or @option{--version}. 13483To output an argument that begins with 13484@samp{-}, precede it with @option{--}, e.g., @samp{yes -- --help}. 13485@xref{Common options}. 13486 13487 13488@node Conditions 13489@chapter Conditions 13490 13491@cindex conditions 13492@cindex commands for exit status 13493@cindex exit status commands 13494 13495This section describes commands that are primarily useful for their exit 13496status, rather than their output. Thus, they are often used as the 13497condition of shell @code{if} statements, or as the last command in a 13498pipeline. 13499 13500@menu 13501* false invocation:: Do nothing, unsuccessfully. 13502* true invocation:: Do nothing, successfully. 13503* test invocation:: Check file types and compare values. 13504* expr invocation:: Evaluate expressions. 13505@end menu 13506 13507 13508@node false invocation 13509@section @command{false}: Do nothing, unsuccessfully 13510 13511@pindex false 13512@cindex do nothing, unsuccessfully 13513@cindex failure exit status 13514@cindex exit status of @command{false} 13515 13516@command{false} does nothing except return an exit status of 1, meaning 13517@dfn{failure}. It can be used as a place holder in shell scripts 13518where an unsuccessful command is needed. 13519In most modern shells, @command{false} is a built-in command, so when 13520you use @samp{false} in a script, you're probably using the built-in 13521command, not the one documented here. 13522 13523@command{false} honors the @option{--help} and @option{--version} options. 13524 13525This version of @command{false} is implemented as a C program, and is thus 13526more secure and faster than a shell script implementation, and may safely 13527be used as a dummy shell for the purpose of disabling accounts. 13528 13529Note that @command{false} (unlike all other programs documented herein) 13530exits unsuccessfully, even when invoked with 13531@option{--help} or @option{--version}. 13532 13533Portable programs should not assume that the exit status of 13534@command{false} is 1, as it is greater than 1 on some 13535non-GNU hosts. 13536 13537 13538@node true invocation 13539@section @command{true}: Do nothing, successfully 13540 13541@pindex true 13542@cindex do nothing, successfully 13543@cindex no-op 13544@cindex successful exit 13545@cindex exit status of @command{true} 13546 13547@command{true} does nothing except return an exit status of 0, meaning 13548@dfn{success}. It can be used as a place holder in shell scripts 13549where a successful command is needed, although the shell built-in 13550command @code{:} (colon) may do the same thing faster. 13551In most modern shells, @command{true} is a built-in command, so when 13552you use @samp{true} in a script, you're probably using the built-in 13553command, not the one documented here. 13554 13555@command{true} honors the @option{--help} and @option{--version} options. 13556 13557Note, however, that it is possible to cause @command{true} 13558to exit with nonzero status: with the @option{--help} or @option{--version} 13559option, and with standard 13560output already closed or redirected to a file that evokes an I/O error. 13561For example, using a Bourne-compatible shell: 13562 13563@example 13564$ ./true --version >&- 13565./true: write error: Bad file number 13566$ ./true --version > /dev/full 13567./true: write error: No space left on device 13568@end example 13569 13570This version of @command{true} is implemented as a C program, and is thus 13571more secure and faster than a shell script implementation, and may safely 13572be used as a dummy shell for the purpose of disabling accounts. 13573 13574@node test invocation 13575@section @command{test}: Check file types and compare values 13576 13577@pindex test 13578@cindex check file types 13579@cindex compare values 13580@cindex expression evaluation 13581 13582@command{test} returns a status of 0 (true) or 1 (false) depending on the 13583evaluation of the conditional expression @var{expr}. Each part of the 13584expression must be a separate argument. 13585 13586@command{test} has file status checks, string operators, and numeric 13587comparison operators. 13588 13589@command{test} has an alternate form that uses opening and closing 13590square brackets instead a leading @samp{test}. For example, instead 13591of @samp{test -d /}, you can write @samp{[ -d / ]}. The square 13592brackets must be separate arguments; for example, @samp{[-d /]} does 13593not have the desired effect. Since @samp{test @var{expr}} and @samp{[ 13594@var{expr} ]} have the same meaning, only the former form is discussed 13595below. 13596 13597Synopses: 13598 13599@example 13600test @var{expression} 13601test 13602[ @var{expression} ] 13603[ ] 13604[ @var{option} 13605@end example 13606 13607@mayConflictWithShellBuiltIn{test} 13608 13609If @var{expression} is omitted, @command{test} returns false. 13610If @var{expression} is a single argument, 13611@command{test} returns false if the argument is null and true 13612otherwise. The argument 13613can be any string, including strings like @samp{-d}, @samp{-1}, 13614@samp{--}, @samp{--help}, and @samp{--version} that most other 13615programs would treat as options. To get help and version information, 13616invoke the commands @samp{[ --help} and @samp{[ --version}, without 13617the usual closing brackets. @xref{Common options}. 13618 13619@cindex exit status of @command{test} 13620Exit status: 13621 13622@display 136230 if the expression is true, 136241 if the expression is false, 136252 if an error occurred. 13626@end display 13627 13628@menu 13629* File type tests:: @code{-[bcdfhLpSt]} 13630* Access permission tests:: @code{-[gkruwxOG]} 13631* File characteristic tests:: @code{-e -s -nt -ot -ef} 13632* String tests:: @code{-z -n = == !=} 13633* Numeric tests:: @code{-eq -ne -lt -le -gt -ge} 13634* Connectives for test:: @code{! -a -o} 13635@end menu 13636 13637 13638@node File type tests 13639@subsection File type tests 13640 13641@cindex file type tests 13642 13643These options test for particular types of files. (Everything's a file, 13644but not all files are the same!) 13645 13646@table @samp 13647 13648@item -b @var{file} 13649@opindex -b 13650@cindex block special check 13651True if @var{file} exists and is a block special device. 13652 13653@item -c @var{file} 13654@opindex -c 13655@cindex character special check 13656True if @var{file} exists and is a character special device. 13657 13658@item -d @var{file} 13659@opindex -d 13660@cindex directory check 13661True if @var{file} exists and is a directory. 13662 13663@item -f @var{file} 13664@opindex -f 13665@cindex regular file check 13666True if @var{file} exists and is a regular file. 13667 13668@item -h @var{file} 13669@itemx -L @var{file} 13670@opindex -L 13671@opindex -h 13672@cindex symbolic link check 13673True if @var{file} exists and is a symbolic link. 13674Unlike all other file-related tests, this test does not dereference 13675@var{file} if it is a symbolic link. 13676 13677@item -p @var{file} 13678@opindex -p 13679@cindex named pipe check 13680True if @var{file} exists and is a named pipe. 13681 13682@item -S @var{file} 13683@opindex -S 13684@cindex socket check 13685True if @var{file} exists and is a socket. 13686 13687@item -t @var{fd} 13688@opindex -t 13689@cindex terminal check 13690True if @var{fd} is a file descriptor that is associated with a 13691terminal. 13692 13693@end table 13694 13695 13696@node Access permission tests 13697@subsection Access permission tests 13698 13699@cindex access permission tests 13700@cindex permission tests 13701 13702These options test for particular access permissions. 13703 13704@table @samp 13705 13706@item -g @var{file} 13707@opindex -g 13708@cindex set-group-ID check 13709True if @var{file} exists and has its set-group-ID bit set. 13710 13711@item -k @var{file} 13712@opindex -k 13713@cindex sticky bit check 13714True if @var{file} exists and has its @dfn{sticky} bit set. 13715 13716@item -r @var{file} 13717@opindex -r 13718@cindex readable file check 13719True if @var{file} exists and the user has read access. 13720 13721@item -u @var{file} 13722@opindex -u 13723@cindex set-user-ID check 13724True if @var{file} exists and has its set-user-ID bit set. 13725 13726@item -w @var{file} 13727@opindex -w 13728@cindex writable file check 13729True if @var{file} exists and the user has write access. 13730 13731@item -x @var{file} 13732@opindex -x 13733@cindex executable file check 13734True if @var{file} exists and the user has execute access 13735(or search permission, if it is a directory). 13736 13737@item -O @var{file} 13738@opindex -O 13739@cindex owned by effective user ID check 13740True if @var{file} exists and is owned by the current effective user ID. 13741 13742@item -G @var{file} 13743@opindex -G 13744@cindex owned by effective group ID check 13745True if @var{file} exists and is owned by the current effective group ID. 13746 13747@end table 13748 13749@node File characteristic tests 13750@subsection File characteristic tests 13751 13752@cindex file characteristic tests 13753 13754These options test other file characteristics. 13755 13756@table @samp 13757 13758@item -e @var{file} 13759@opindex -e 13760@cindex existence-of-file check 13761True if @var{file} exists. 13762 13763@item -s @var{file} 13764@opindex -s 13765@cindex nonempty file check 13766True if @var{file} exists and has a size greater than zero. 13767 13768@item @var{file1} -nt @var{file2} 13769@opindex -nt 13770@cindex newer-than file check 13771True if @var{file1} is newer (according to modification date) than 13772@var{file2}, or if @var{file1} exists and @var{file2} does not. 13773 13774@item @var{file1} -ot @var{file2} 13775@opindex -ot 13776@cindex older-than file check 13777True if @var{file1} is older (according to modification date) than 13778@var{file2}, or if @var{file2} exists and @var{file1} does not. 13779 13780@item @var{file1} -ef @var{file2} 13781@opindex -ef 13782@cindex same file check 13783@cindex hard link check 13784True if @var{file1} and @var{file2} have the same device and inode 13785numbers, i.e., if they are hard links to each other. 13786 13787@item -N @var{file} 13788@opindex -N 13789@cindex mtime-greater-atime file check 13790True if @var{file} exists and has been modified (mtime) since it was 13791last read (atime). 13792 13793@end table 13794 13795 13796@node String tests 13797@subsection String tests 13798 13799@cindex string tests 13800 13801These options test string characteristics. You may need to quote 13802@var{string} arguments for the shell. For example: 13803 13804@example 13805test -n "$V" 13806@end example 13807 13808The quotes here prevent the wrong arguments from being passed to 13809@command{test} if @samp{$V} is empty or contains special characters. 13810 13811@table @samp 13812 13813@item -z @var{string} 13814@opindex -z 13815@cindex zero-length string check 13816True if the length of @var{string} is zero. 13817 13818@item -n @var{string} 13819@itemx @var{string} 13820@opindex -n 13821@cindex nonzero-length string check 13822True if the length of @var{string} is nonzero. 13823 13824@item @var{string1} = @var{string2} 13825@opindex = 13826@cindex equal string check 13827True if the strings are equal. 13828 13829@item @var{string1} == @var{string2} 13830@opindex == 13831@cindex equal string check 13832True if the strings are equal (synonym for =). 13833Note this form is not as portable to other 13834shells and systems. 13835 13836@item @var{string1} != @var{string2} 13837@opindex != 13838@cindex not-equal string check 13839True if the strings are not equal. 13840 13841@end table 13842 13843 13844@node Numeric tests 13845@subsection Numeric tests 13846 13847@cindex numeric tests 13848@cindex arithmetic tests 13849 13850Numeric relational operators. The arguments must be entirely numeric 13851(possibly negative), or the special expression @w{@code{-l @var{string}}}, 13852which evaluates to the length of @var{string}. 13853 13854@table @samp 13855 13856@item @var{arg1} -eq @var{arg2} 13857@itemx @var{arg1} -ne @var{arg2} 13858@itemx @var{arg1} -lt @var{arg2} 13859@itemx @var{arg1} -le @var{arg2} 13860@itemx @var{arg1} -gt @var{arg2} 13861@itemx @var{arg1} -ge @var{arg2} 13862@opindex -eq 13863@opindex -ne 13864@opindex -lt 13865@opindex -le 13866@opindex -gt 13867@opindex -ge 13868These arithmetic binary operators return true if @var{arg1} is equal, 13869not-equal, less-than, less-than-or-equal, greater-than, or 13870greater-than-or-equal than @var{arg2}, respectively. 13871 13872@end table 13873 13874For example: 13875 13876@example 13877test -1 -gt -2 && echo yes 13878@result{} yes 13879test -l abc -gt 1 && echo yes 13880@result{} yes 13881test 0x100 -eq 1 13882@error{} test: integer expression expected before -eq 13883@end example 13884 13885 13886@node Connectives for test 13887@subsection Connectives for @command{test} 13888 13889@cindex logical connectives 13890@cindex connectives, logical 13891 13892Note it's preferred to use shell logical primitives 13893rather than these logical connectives internal to @command{test}, 13894because an expression may become ambiguous 13895depending on the expansion of its parameters. 13896 13897For example, this becomes ambiguous when @samp{$1} 13898is set to @samp{'!'} and @samp{$2} to the empty string @samp{''}: 13899 13900@example 13901test "$1" -a "$2" 13902@end example 13903 13904and should be written as: 13905 13906@example 13907test "$1" && test "$2" 13908@end example 13909 13910Note the shell logical primitives also benefit from 13911short circuit operation, which can be significant 13912for file attribute tests. 13913 13914@table @samp 13915 13916@item ! @var{expr} 13917@opindex ! 13918True if @var{expr} is false. 13919@samp{!} has lower precedence than all parts of @var{expr}. 13920Note @samp{!} needs to be specified to the left 13921of a binary expression, I.e., @samp{'!' 1 -gt 2} 13922rather than @samp{1 '!' -gt 2}. 13923Also @samp{!} is often a shell special character 13924and is best used quoted. 13925 13926 13927@item @var{expr1} -a @var{expr2} 13928@opindex -a 13929@cindex logical and operator 13930@cindex and operator 13931True if both @var{expr1} and @var{expr2} are true. 13932@samp{-a} is left associative, 13933and has a higher precedence than @samp{-o}. 13934 13935@item @var{expr1} -o @var{expr2} 13936@opindex -o 13937@cindex logical or operator 13938@cindex or operator 13939True if either @var{expr1} or @var{expr2} is true. 13940@samp{-o} is left associative. 13941 13942@end table 13943 13944 13945@node expr invocation 13946@section @command{expr}: Evaluate expressions 13947 13948@pindex expr 13949@cindex expression evaluation 13950@cindex evaluation of expressions 13951 13952@command{expr} evaluates an expression and writes the result on standard 13953output. Each token of the expression must be a separate argument. 13954 13955Operands are either integers or strings. Integers consist of one or 13956more decimal digits, with an optional leading @samp{-}. 13957@command{expr} converts 13958anything appearing in an operand position to an integer or a string 13959depending on the operation being applied to it. 13960 13961Strings are not quoted for @command{expr} itself, though you may need to 13962quote them to protect characters with special meaning to the shell, 13963e.g., spaces. However, regardless of whether it is quoted, a string 13964operand should not be a parenthesis or any of @command{expr}'s 13965operators like @code{+}, so you cannot safely pass an arbitrary string 13966@code{$str} to expr merely by quoting it to the shell. One way to 13967work around this is to use the GNU extension @code{+}, 13968(e.g., @code{+ "$str" = foo}); a more portable way is to use 13969@code{@w{" $str"}} and to adjust the rest of the expression to take 13970the leading space into account (e.g., @code{@w{" $str" = " foo"}}). 13971 13972You should not pass a negative integer or a string with leading 13973@samp{-} as @command{expr}'s first argument, as it might be 13974misinterpreted as an option; this can be avoided by parenthesization. 13975Also, portable scripts should not use a string operand that happens to 13976take the form of an integer; this can be worked around by inserting 13977leading spaces as mentioned above. 13978 13979@cindex parentheses for grouping 13980Operators may be given as infix symbols or prefix keywords. Parentheses 13981may be used for grouping in the usual manner. You must quote 13982parentheses and many operators to avoid the shell evaluating them, 13983however. 13984 13985Because @command{expr} uses multiple-precision arithmetic, it works 13986with integers wider than those of machine registers. 13987 13988The only options are @option{--help} and @option{--version}. @xref{Common 13989options}. Options must precede operands. 13990 13991@cindex exit status of @command{expr} 13992Exit status: 13993 13994@display 139950 if the expression is neither null nor 0, 139961 if the expression is null or 0, 139972 if the expression is invalid, 139983 if an internal error occurred (e.g., arithmetic overflow). 13999@end display 14000 14001@menu 14002* String expressions:: @code{+ : match substr index length} 14003* Numeric expressions:: @code{+ - * / %} 14004* Relations for expr:: @code{| & < <= = == != >= >} 14005* Examples of expr:: Examples. 14006@end menu 14007 14008 14009@node String expressions 14010@subsection String expressions 14011 14012@cindex string expressions 14013@cindex expressions, string 14014 14015@command{expr} supports pattern matching and other string operators. These 14016have higher precedence than both the numeric and relational operators (in 14017the next sections). 14018 14019@table @samp 14020 14021@item @var{string} : @var{regex} 14022@cindex pattern matching 14023@cindex regular expression matching 14024@cindex matching patterns 14025Perform pattern matching. The arguments are converted to strings and the 14026second is considered to be a (basic, a la GNU @code{grep}) regular 14027expression, with a @code{^} implicitly prepended. The first argument is 14028then matched against this regular expression. 14029 14030If @var{regex} does not use @samp{\(} and @samp{\)}, the @code{:} 14031expression returns the number of characters matched, or 0 if the match 14032fails. 14033 14034If @var{regex} uses @samp{\(} and @samp{\)}, the @code{:} expression 14035returns the part of @var{string} that matched the subexpression, or 14036the null string if the match failed or the subexpression did not 14037contribute to the match. 14038 14039@kindex \( @r{regexp operator} 14040Only the first @samp{\( @dots{} \)} pair is relevant to the return 14041value; additional pairs are meaningful only for grouping the regular 14042expression operators. 14043 14044@kindex \+ @r{regexp operator} 14045@kindex \? @r{regexp operator} 14046@kindex \| @r{regexp operator} 14047In the regular expression, @code{\+}, @code{\?}, and @code{\|} are 14048operators which respectively match one or more, zero or one, or separate 14049alternatives. These operators are GNU extensions. @xref{Regular Expressions,, 14050Regular Expressions, grep, The GNU Grep Manual}, for details of 14051regular expression syntax. Some examples are in @ref{Examples of expr}. 14052 14053@item match @var{string} @var{regex} 14054@findex match 14055An alternative way to do pattern matching. This is the same as 14056@w{@samp{@var{string} : @var{regex}}}. 14057 14058@item substr @var{string} @var{position} @var{length} 14059@findex substr 14060Returns the substring of @var{string} beginning at @var{position} 14061with length at most @var{length}. If either @var{position} or 14062@var{length} is negative, zero, or non-numeric, returns the null string. 14063 14064@item index @var{string} @var{charset} 14065@findex index 14066Returns the first position in @var{string} where the first character in 14067@var{charset} was found. If no character in @var{charset} is found in 14068@var{string}, return 0. 14069 14070@item length @var{string} 14071@findex length 14072Returns the length of @var{string}. 14073 14074@item + @var{token} 14075@kindex + 14076Interpret @var{token} as a string, even if it is a keyword like @var{match} 14077or an operator like @code{/}. 14078This makes it possible to test @code{expr length + "$x"} or 14079@code{expr + "$x" : '.*/\(.\)'} and have it do the right thing even if 14080the value of @var{$x} happens to be (for example) @code{/} or @code{index}. 14081This operator is a GNU extension. Portable shell scripts should use 14082@code{@w{" $token"} : @w{' \(.*\)'}} instead of @code{+ "$token"}. 14083 14084@end table 14085 14086To make @command{expr} interpret keywords as strings, you must use the 14087@code{quote} operator. 14088 14089 14090@node Numeric expressions 14091@subsection Numeric expressions 14092 14093@cindex numeric expressions 14094@cindex expressions, numeric 14095 14096@command{expr} supports the usual numeric operators, in order of increasing 14097precedence. These numeric operators have lower precedence than the 14098string operators described in the previous section, and higher precedence 14099than the connectives (next section). 14100 14101@table @samp 14102 14103@item + - 14104@kindex + 14105@kindex - 14106@cindex addition 14107@cindex subtraction 14108Addition and subtraction. Both arguments are converted to integers; 14109an error occurs if this cannot be done. 14110 14111@item * / % 14112@kindex * 14113@kindex / 14114@kindex % 14115@cindex multiplication 14116@cindex division 14117@cindex remainder 14118Multiplication, division, remainder. Both arguments are converted to 14119integers; an error occurs if this cannot be done. 14120 14121@end table 14122 14123 14124@node Relations for expr 14125@subsection Relations for @command{expr} 14126 14127@cindex connectives, logical 14128@cindex logical connectives 14129@cindex relations, numeric or string 14130 14131@command{expr} supports the usual logical connectives and relations. These 14132have lower precedence than the string and numeric operators 14133(previous sections). Here is the list, lowest-precedence operator first. 14134 14135@table @samp 14136 14137@item | 14138@kindex | 14139@cindex logical or operator 14140@cindex or operator 14141Returns its first argument if that is neither null nor zero, otherwise 14142its second argument if it is neither null nor zero, otherwise 0. It 14143does not evaluate its second argument if its first argument is neither 14144null nor zero. 14145 14146@item & 14147@kindex & 14148@cindex logical and operator 14149@cindex and operator 14150Return its first argument if neither argument is null or zero, otherwise 141510. It does not evaluate its second argument if its first argument is 14152null or zero. 14153 14154@item < <= = == != >= > 14155@kindex < 14156@kindex <= 14157@kindex = 14158@kindex == 14159@kindex > 14160@kindex >= 14161@cindex comparison operators 14162@vindex LC_COLLATE 14163Compare the arguments and return 1 if the relation is true, 0 otherwise. 14164@code{==} is a synonym for @code{=}. @command{expr} first tries to convert 14165both arguments to integers and do a numeric comparison; if either 14166conversion fails, it does a lexicographic comparison using the character 14167collating sequence specified by the @env{LC_COLLATE} locale. 14168 14169@end table 14170 14171 14172@node Examples of expr 14173@subsection Examples of using @command{expr} 14174 14175@cindex examples of @command{expr} 14176Here are a few examples, including quoting for shell metacharacters. 14177 14178To add 1 to the shell variable @code{foo}, in Bourne-compatible shells: 14179 14180@example 14181foo=$(expr $foo + 1) 14182@end example 14183 14184To print the non-directory part of the file name stored in 14185@code{$fname}, which need not contain a @code{/}: 14186 14187@example 14188expr $fname : '.*/\(.*\)' '|' $fname 14189@end example 14190 14191An example showing that @code{\+} is an operator: 14192 14193@example 14194expr aaa : 'a\+' 14195@result{} 3 14196@end example 14197 14198@example 14199expr abc : 'a\(.\)c' 14200@result{} b 14201expr index abcdef cz 14202@result{} 3 14203expr index index a 14204@error{} expr: syntax error 14205expr index + index a 14206@result{} 0 14207@end example 14208 14209 14210@node Redirection 14211@chapter Redirection 14212 14213@cindex redirection 14214@cindex commands for redirection 14215 14216Unix shells commonly provide several forms of @dfn{redirection} -- ways 14217to change the input source or output destination of a command. But one 14218useful redirection is performed by a separate command, not by the shell; 14219it's described here. 14220 14221@menu 14222* tee invocation:: Redirect output to multiple files or processes. 14223@end menu 14224 14225 14226@node tee invocation 14227@section @command{tee}: Redirect output to multiple files or processes 14228 14229@pindex tee 14230@cindex pipe fitting 14231@cindex destinations, multiple output 14232@cindex read from standard input and write to standard output and files 14233 14234The @command{tee} command copies standard input to standard output and also 14235to any files given as arguments. This is useful when you want not only 14236to send some data down a pipe, but also to save a copy. Synopsis: 14237 14238@example 14239tee [@var{option}]@dots{} [@var{file}]@dots{} 14240@end example 14241 14242If a file being written to does not already exist, it is created. If a 14243file being written to already exists, the data it previously contained 14244is overwritten unless the @option{-a} option is used. 14245 14246In previous versions of GNU Coreutils (5.3.0--8.23), 14247a @var{file} of @samp{-} 14248caused @command{tee} to send another copy of input to standard output. 14249However, as the interleaved output was not very useful, @command{tee} now 14250conforms to POSIX and treats @samp{-} as a file name. 14251 14252The program accepts the following options. Also see @ref{Common options}. 14253 14254@table @samp 14255@item -a 14256@itemx --append 14257@opindex -a 14258@opindex --append 14259Append standard input to the given files rather than overwriting 14260them. 14261 14262@item -i 14263@itemx --ignore-interrupts 14264@opindex -i 14265@opindex --ignore-interrupts 14266Ignore interrupt signals. 14267 14268@item -p 14269@itemx --output-error[=@var{mode}] 14270@opindex -p 14271@opindex --output-error 14272Adjust the behavior with errors on the outputs. 14273In summary @option{-p} allows @command{tee} to operate in a more 14274appropriate manner with pipes, and to continue to process data 14275to any remaining outputs, if any pipe outputs exit early. 14276The default operation when @option{--output-error} is @emph{not} 14277specified is to exit immediately on error writing to a pipe, 14278and diagnose errors writing to a non-pipe. 14279The long form @option{--output-error} option supports selection 14280between the following @var{mode}s: 14281 14282@table @samp 14283@item warn 14284Warn on error opening or writing any output, including pipes. 14285Writing is continued to still open files/pipes. 14286Exit status indicates failure if any output has an error. 14287 14288@item warn-nopipe 14289This is the default @var{mode} when not specified, 14290or when the short form @option{-p} is used. 14291Warn on error opening or writing any output, except pipes. 14292Writing is continued to still open files/pipes. 14293Exit immediately if all remaining outputs become broken pipes. 14294Exit status indicates failure if any non pipe output had an error. 14295 14296@item exit 14297Exit on error opening or writing any output, including pipes. 14298 14299@item exit-nopipe 14300Exit on error opening or writing any output, except pipes. 14301Exit immediately if all remaining outputs become broken pipes. 14302@end table 14303 14304@end table 14305 14306The @command{tee} command is useful when you happen to be transferring a large 14307amount of data and also want to summarize that data without reading 14308it a second time. For example, when you are downloading a DVD image, 14309you often want to verify its signature or checksum right away. 14310The inefficient way to do it is simply: 14311 14312@example 14313wget https://example.com/some.iso && sha1sum some.iso 14314@end example 14315 14316One problem with the above is that it makes you wait for the 14317download to complete before starting the time-consuming SHA1 computation. 14318Perhaps even more importantly, the above requires reading 14319the DVD image a second time (the first was from the network). 14320 14321The efficient way to do it is to interleave the download 14322and SHA1 computation. Then, you'll get the checksum for 14323free, because the entire process parallelizes so well: 14324 14325@example 14326# slightly contrived, to demonstrate process substitution 14327wget -O - https://example.com/dvd.iso \ 14328 | tee >(sha1sum > dvd.sha1) > dvd.iso 14329@end example 14330 14331That makes @command{tee} write not just to the expected output file, 14332but also to a pipe running @command{sha1sum} and saving the final 14333checksum in a file named @file{dvd.sha1}. 14334 14335Note, however, that this example relies on a feature of modern shells 14336called @dfn{process substitution} 14337(the @samp{>(command)} syntax, above; 14338@xref{Process Substitution,,Process Substitution, bash, 14339The Bash Reference Manual}.), 14340so it works with @command{zsh}, @command{bash}, and @command{ksh}, 14341but not with @command{/bin/sh}. So if you write code like this 14342in a shell script, be sure to start the script with @samp{#!/bin/bash}. 14343 14344Note also that if any of the process substitutions (or piped standard output) 14345might exit early without consuming all the data, the @option{-p} option 14346is needed to allow @command{tee} to continue to process the input 14347to any remaining outputs. 14348 14349Since the above example writes to one file and one process, 14350a more conventional and portable use of @command{tee} is even better: 14351 14352@example 14353wget -O - https://example.com/dvd.iso \ 14354 | tee dvd.iso | sha1sum > dvd.sha1 14355@end example 14356 14357You can extend this example to make @command{tee} write to two processes, 14358computing MD5 and SHA1 checksums in parallel. In this case, 14359process substitution is required: 14360 14361@example 14362wget -O - https://example.com/dvd.iso \ 14363 | tee >(sha1sum > dvd.sha1) \ 14364 >(md5sum > dvd.md5) \ 14365 > dvd.iso 14366@end example 14367 14368This technique is also useful when you want to make a @emph{compressed} 14369copy of the contents of a pipe. 14370Consider a tool to graphically summarize file system usage data from 14371@samp{du -ak}. 14372For a large hierarchy, @samp{du -ak} can run for a long time, 14373and can easily produce terabytes of data, so you won't want to 14374rerun the command unnecessarily. Nor will you want to save 14375the uncompressed output. 14376 14377Doing it the inefficient way, you can't even start the GUI 14378until after you've compressed all of the @command{du} output: 14379 14380@example 14381du -ak | gzip -9 > /tmp/du.gz 14382gzip -d /tmp/du.gz | checkspace -a 14383@end example 14384 14385With @command{tee} and process substitution, you start the GUI 14386right away and eliminate the decompression completely: 14387 14388@example 14389du -ak | tee >(gzip -9 > /tmp/du.gz) | checkspace -a 14390@end example 14391 14392Finally, if you regularly create more than one type of 14393compressed tarball at once, for example when @code{make dist} creates 14394both @command{gzip}-compressed and @command{bzip2}-compressed tarballs, 14395there may be a better way. 14396Typical @command{automake}-generated @file{Makefile} rules create 14397the two compressed tar archives with commands in sequence, like this 14398(slightly simplified): 14399 14400@example 14401tardir=your-pkg-M.N 14402tar chof - "$tardir" | gzip -9 -c > your-pkg-M.N.tar.gz 14403tar chof - "$tardir" | bzip2 -9 -c > your-pkg-M.N.tar.bz2 14404@end example 14405 14406However, if the hierarchy you are archiving and compressing is larger 14407than a couple megabytes, and especially if you are using a multi-processor 14408system with plenty of memory, then you can do much better by reading the 14409directory contents only once and running the compression programs in parallel: 14410 14411@example 14412tardir=your-pkg-M.N 14413tar chof - "$tardir" \ 14414 | tee >(gzip -9 -c > your-pkg-M.N.tar.gz) \ 14415 | bzip2 -9 -c > your-pkg-M.N.tar.bz2 14416@end example 14417 14418If you want to further process the output from process substitutions, 14419and those processes write atomically (i.e., write less than the system's 14420PIPE_BUF size at a time), that's possible with a construct like: 14421 14422@example 14423tardir=your-pkg-M.N 14424tar chof - "$tardir" \ 14425 | tee >(md5sum --tag) > >(sha256sum --tag) \ 14426 | sort | gpg --clearsign > your-pkg-M.N.tar.sig 14427@end example 14428 14429@exitstatus 14430 14431 14432@node File name manipulation 14433@chapter File name manipulation 14434 14435@cindex file name manipulation 14436@cindex manipulation of file names 14437@cindex commands for file name manipulation 14438 14439This section describes commands that manipulate file names. 14440 14441@menu 14442* basename invocation:: Strip directory and suffix from a file name. 14443* dirname invocation:: Strip last file name component. 14444* pathchk invocation:: Check file name validity and portability. 14445* mktemp invocation:: Create temporary file or directory. 14446* realpath invocation:: Print resolved file names. 14447@end menu 14448 14449 14450@node basename invocation 14451@section @command{basename}: Strip directory and suffix from a file name 14452 14453@pindex basename 14454@cindex strip directory and suffix from file names 14455@cindex directory, stripping from file names 14456@cindex suffix, stripping from file names 14457@cindex file names, stripping directory and suffix 14458@cindex leading directory components, stripping 14459 14460@command{basename} removes any leading directory components from 14461@var{name}. Synopsis: 14462 14463@example 14464basename @var{name} [@var{suffix}] 14465basename @var{option}@dots{} @var{name}@dots{} 14466@end example 14467 14468If @var{suffix} is specified and is identical to the end of @var{name}, 14469it is removed from @var{name} as well. Note that since trailing slashes 14470are removed prior to suffix matching, @var{suffix} will do nothing if it 14471contains slashes. @command{basename} prints the result on standard 14472output. 14473 14474@c This test is used both here and in the section on dirname. 14475@macro basenameAndDirname 14476Together, @command{basename} and @command{dirname} are designed such 14477that if @samp{ls "$name"} succeeds, then the command sequence @samp{cd 14478"$(dirname "$name")"; ls "$(basename "$name")"} will, too. This works 14479for everything except file names containing a trailing newline. 14480@end macro 14481@basenameAndDirname 14482 14483POSIX allows the implementation to define the results if 14484@var{name} is empty or @samp{//}. In the former case, GNU 14485@command{basename} returns the empty string. In the latter case, the 14486result is @samp{//} on platforms where @var{//} is distinct from 14487@var{/}, and @samp{/} on platforms where there is no difference. 14488 14489The program accepts the following options. Also see @ref{Common options}. 14490Options must precede operands. 14491 14492@table @samp 14493 14494@item -a 14495@itemx --multiple 14496@opindex -a 14497@opindex --multiple 14498Support more than one argument. Treat every argument as a @var{name}. 14499With this, an optional @var{suffix} must be specified using the 14500@option{-s} option. 14501 14502@item -s @var{suffix} 14503@itemx --suffix=@var{suffix} 14504@opindex -s 14505@opindex --suffix 14506Remove a trailing @var{suffix}. 14507This option implies the @option{-a} option. 14508 14509@optZero 14510 14511@end table 14512 14513@exitstatus 14514 14515Examples: 14516 14517@example 14518# Output "sort". 14519basename /usr/bin/sort 14520 14521# Output "stdio". 14522basename include/stdio.h .h 14523 14524# Output "stdio". 14525basename -s .h include/stdio.h 14526 14527# Output "stdio" followed by "stdlib" 14528basename -a -s .h include/stdio.h include/stdlib.h 14529@end example 14530 14531 14532@node dirname invocation 14533@section @command{dirname}: Strip last file name component 14534 14535@pindex dirname 14536@cindex directory components, printing 14537@cindex stripping non-directory suffix 14538@cindex non-directory suffix, stripping 14539 14540@command{dirname} prints all but the final slash-delimited component 14541of each @var{name}. Slashes on either side of the final component are 14542also removed. If the string contains no slash, @command{dirname} 14543prints @samp{.} (meaning the current directory). Synopsis: 14544 14545@example 14546dirname [@var{option}] @var{name}@dots{} 14547@end example 14548 14549@var{name} need not be a file name, but if it is, this operation 14550effectively lists the directory that contains the final component, 14551including the case when the final component is itself a directory. 14552 14553@basenameAndDirname 14554 14555POSIX allows the implementation to define the results if 14556@var{name} is @samp{//}. With GNU @command{dirname}, the 14557result is @samp{//} on platforms where @var{//} is distinct from 14558@var{/}, and @samp{/} on platforms where there is no difference. 14559 14560The program accepts the following option. Also see @ref{Common options}. 14561 14562@table @samp 14563 14564@optZero 14565 14566@end table 14567 14568@exitstatus 14569 14570Examples: 14571 14572@example 14573# Output "/usr/bin". 14574dirname /usr/bin/sort 14575dirname /usr/bin//.// 14576 14577# Output "dir1" followed by "dir2" 14578dirname dir1/str dir2/str 14579 14580# Output ".". 14581dirname stdio.h 14582@end example 14583 14584 14585@node pathchk invocation 14586@section @command{pathchk}: Check file name validity and portability 14587 14588@pindex pathchk 14589@cindex file names, checking validity and portability 14590@cindex valid file names, checking for 14591@cindex portable file names, checking for 14592 14593@command{pathchk} checks validity and portability of file names. Synopsis: 14594 14595@example 14596pathchk [@var{option}]@dots{} @var{name}@dots{} 14597@end example 14598 14599For each @var{name}, @command{pathchk} prints an error message if any of 14600these conditions is true: 14601 14602@enumerate 14603@item 14604One of the existing directories in @var{name} does not have search 14605(execute) permission, 14606@item 14607The length of @var{name} is larger than the maximum supported by the 14608operating system. 14609@item 14610The length of one component of @var{name} is longer than 14611its file system's maximum. 14612@end enumerate 14613 14614A nonexistent @var{name} is not an error, so long as a file with that 14615name could be created under the above conditions. 14616 14617The program accepts the following options. Also see @ref{Common options}. 14618Options must precede operands. 14619 14620@table @samp 14621 14622@item -p 14623@opindex -p 14624Instead of performing checks based on the underlying file system, 14625print an error message if any of these conditions is true: 14626 14627@enumerate 14628@item 14629A file name is empty. 14630 14631@item 14632A file name contains a character outside the POSIX portable file 14633name character set, namely, the ASCII letters and digits, @samp{.}, 14634@samp{_}, @samp{-}, and @samp{/}. 14635 14636@item 14637The length of a file name or one of its components exceeds the 14638POSIX minimum limits for portability. 14639@end enumerate 14640 14641@item -P 14642@opindex -P 14643Print an error message if a file name is empty, or if it contains a component 14644that begins with @samp{-}. 14645 14646@item --portability 14647@opindex --portability 14648Print an error message if a file name is not portable to all POSIX 14649hosts. This option is equivalent to @samp{-p -P}. 14650 14651@end table 14652 14653@cindex exit status of @command{pathchk} 14654Exit status: 14655 14656@display 146570 if all specified file names passed all checks, 146581 otherwise. 14659@end display 14660 14661@node mktemp invocation 14662@section @command{mktemp}: Create temporary file or directory 14663 14664@pindex mktemp 14665@cindex file names, creating temporary 14666@cindex directory, creating temporary 14667@cindex temporary files and directories 14668 14669@command{mktemp} manages the creation of temporary files and 14670directories. Synopsis: 14671 14672@example 14673mktemp [@var{option}]@dots{} [@var{template}] 14674@end example 14675 14676Safely create a temporary file or directory based on @var{template}, 14677and print its name. If given, @var{template} must include at least 14678three consecutive @samp{X}s in the last component. If omitted, the template 14679@samp{tmp.XXXXXXXXXX} is used, and option @option{--tmpdir} is 14680implied. The final run of @samp{X}s in the @var{template} will be replaced 14681by alpha-numeric characters; thus, on a case-sensitive file system, 14682and with a @var{template} including a run of @var{n} instances of @samp{X}, 14683there are @samp{62**@var{n}} potential file names. 14684 14685Older scripts used to create temporary files by simply joining the 14686name of the program with the process id (@samp{$$}) as a suffix. 14687However, that naming scheme is easily predictable, and suffers from a 14688race condition where the attacker can create an appropriately named 14689symbolic link, such that when the script then opens a handle to what 14690it thought was an unused file, it is instead modifying an existing 14691file. Using the same scheme to create a directory is slightly safer, 14692since the @command{mkdir} will fail if the target already exists, but 14693it is still inferior because it allows for denial of service attacks. 14694Therefore, modern scripts should use the @command{mktemp} command to 14695guarantee that the generated name will be unpredictable, and that 14696knowledge of the temporary file name implies that the file was created 14697by the current script and cannot be modified by other users. 14698 14699When creating a file, the resulting file has read and write 14700permissions for the current user, but no permissions for the group or 14701others; these permissions are reduced if the current umask is more 14702restrictive. 14703 14704Here are some examples (although note that if you repeat them, you 14705will most likely get different file names): 14706 14707@itemize @bullet 14708 14709@item 14710Create a temporary file in the current directory. 14711@example 14712$ mktemp file.XXXX 14713file.H47c 14714@end example 14715 14716@item 14717Create a temporary file with a known suffix. 14718@example 14719$ mktemp --suffix=.txt file-XXXX 14720file-H08W.txt 14721$ mktemp file-XXXX-XXXX.txt 14722file-XXXX-eI9L.txt 14723@end example 14724 14725@item 14726Create a secure fifo relative to the user's choice of @env{TMPDIR}, 14727but falling back to the current directory rather than @file{/tmp}. 14728Note that @command{mktemp} does not create fifos, but can create a 14729secure directory in which the fifo can live. Exit the shell if the 14730directory or fifo could not be created. 14731@example 14732$ dir=$(mktemp -p "$@{TMPDIR:-.@}" -d dir-XXXX) || exit 1 14733$ fifo=$dir/fifo 14734$ mkfifo "$fifo" || @{ rmdir "$dir"; exit 1; @} 14735@end example 14736 14737@item 14738Create and use a temporary file if possible, but ignore failure. The 14739file will reside in the directory named by @env{TMPDIR}, if specified, 14740or else in @file{/tmp}. 14741@example 14742$ file=$(mktemp -q) && @{ 14743> # Safe to use $file only within this block. Use quotes, 14744> # since $TMPDIR, and thus $file, may contain whitespace. 14745> echo ... > "$file" 14746> rm "$file" 14747> @} 14748@end example 14749 14750@item 14751Act as a semi-random character generator (it is not fully random, 14752since it is impacted by the contents of the current directory). To 14753avoid security holes, do not use the resulting names to create a file. 14754@example 14755$ mktemp -u XXX 14756Gb9 14757$ mktemp -u XXX 14758nzC 14759@end example 14760 14761@end itemize 14762 14763The program accepts the following options. Also see @ref{Common options}. 14764 14765@table @samp 14766 14767@item -d 14768@itemx --directory 14769@opindex -d 14770@opindex --directory 14771Create a directory rather than a file. The directory will have read, 14772write, and search permissions for the current user, but no permissions 14773for the group or others; these permissions are reduced if the current 14774umask is more restrictive. 14775 14776@item -q 14777@itemx --quiet 14778@opindex -q 14779@opindex --quiet 14780Suppress diagnostics about failure to create a file or directory. The 14781exit status will still reflect whether a file was created. 14782 14783@item -u 14784@itemx --dry-run 14785@opindex -u 14786@opindex --dry-run 14787Generate a temporary name that does not name an existing file, without 14788changing the file system contents. Using the output of this command 14789to create a new file is inherently unsafe, as there is a window of 14790time between generating the name and using it where another process 14791can create an object by the same name. 14792 14793@item -p @var{dir} 14794@itemx --tmpdir[=@var{dir}] 14795@opindex -p 14796@opindex --tmpdir 14797Treat @var{template} relative to the directory @var{dir}. If 14798@var{dir} is not specified (only possible with the long option 14799@option{--tmpdir}) or is the empty string, use the value of 14800@env{TMPDIR} if available, otherwise use @samp{/tmp}. If this is 14801specified, @var{template} must not be absolute. However, 14802@var{template} can still contain slashes, although intermediate 14803directories must already exist. 14804 14805@item --suffix=@var{suffix} 14806@opindex --suffix 14807Append @var{suffix} to the @var{template}. @var{suffix} must not 14808contain slash. If @option{--suffix} is specified, @var{template} must 14809end in @samp{X}; if it is not specified, then an appropriate 14810@option{--suffix} is inferred by finding the last @samp{X} in 14811@var{template}. This option exists for use with the default 14812@var{template} and for the creation of a @var{suffix} that starts with 14813@samp{X}. 14814 14815@item -t 14816@opindex -t 14817Treat @var{template} as a single file relative to the value of 14818@env{TMPDIR} if available, or to the directory specified by 14819@option{-p}, otherwise to @samp{/tmp}. @var{template} must not 14820contain slashes. This option is deprecated; the use of @option{-p} 14821without @option{-t} offers better defaults (by favoring the command 14822line over @env{TMPDIR}) and more flexibility (by allowing intermediate 14823directories). 14824 14825@end table 14826 14827@cindex exit status of @command{mktemp} 14828Exit status: 14829 14830@display 148310 if the file was created, 148321 otherwise. 14833@end display 14834 14835 14836@node realpath invocation 14837@section @command{realpath}: Print the resolved file name. 14838 14839@pindex realpath 14840@cindex file names, canonicalization 14841@cindex symlinks, resolution 14842@cindex canonical file name 14843@cindex canonicalize a file name 14844@pindex realpath 14845@findex realpath 14846 14847@command{realpath} expands all symbolic links and resolves references to 14848@samp{/./}, @samp{/../} and extra @samp{/} characters. By default, 14849all but the last component of the specified files must exist. Synopsis: 14850 14851@example 14852realpath [@var{option}]@dots{} @var{file}@dots{} 14853@end example 14854 14855The file name canonicalization functionality overlaps with that of the 14856@command{readlink} command. This is the preferred command for 14857canonicalization as it's a more suitable and standard name. In addition 14858this command supports relative file name processing functionality. 14859 14860The program accepts the following options. Also see @ref{Common options}. 14861 14862@table @samp 14863 14864@item -e 14865@itemx --canonicalize-existing 14866@opindex -e 14867@opindex --canonicalize-existing 14868Ensure that all components of the specified file names exist. 14869If any component is missing or unavailable, @command{realpath} will output 14870a diagnostic unless the @option{-q} option is specified, and exit with a 14871nonzero exit code. A trailing slash requires that the name resolve to a 14872directory. 14873 14874@item -m 14875@itemx --canonicalize-missing 14876@opindex -m 14877@opindex --canonicalize-missing 14878If any component of a specified file name is missing or unavailable, 14879treat it as a directory. 14880 14881@item -L 14882@itemx --logical 14883@opindex -L 14884@opindex --logical 14885Symbolic links are resolved in the specified file names, 14886but they are resolved after any subsequent @samp{..} components are processed. 14887 14888@item -P 14889@itemx --physical 14890@opindex -P 14891@opindex --physical 14892Symbolic links are resolved in the specified file names, 14893and they are resolved before any subsequent @samp{..} components are processed. 14894This is the default mode of operation. 14895 14896@item -q 14897@itemx --quiet 14898@opindex -q 14899@opindex --quiet 14900Suppress diagnostic messages for specified file names. 14901 14902@item --relative-to=@var{dir} 14903@opindex --relative-to 14904@cindex relpath 14905Print the resolved file names relative to the specified directory. 14906Note this option honors the @option{-m} and @option{-e} options 14907pertaining to file existence. 14908 14909@item --relative-base=@var{dir} 14910@opindex --relative-base 14911Print the resolved file names as relative @emph{if} the files 14912are descendants of @var{dir}. 14913Otherwise, print the resolved file names as absolute. 14914Note this option honors the @option{-m} and @option{-e} options 14915pertaining to file existence. 14916For details about combining @option{--relative-to} and @option{--relative-base}, 14917@pxref{Realpath usage examples}. 14918 14919@item -s 14920@itemx --strip 14921@itemx --no-symlinks 14922@opindex -s 14923@opindex --strip 14924@opindex --no-symlinks 14925Do not resolve symbolic links. Only resolve references to 14926@samp{/./}, @samp{/../} and remove extra @samp{/} characters. 14927When combined with the @option{-m} option, realpath operates 14928only on the file name, and does not touch any actual file. 14929 14930@optZero 14931 14932@end table 14933 14934@cindex exit status of @command{realpath} 14935Exit status: 14936 14937@display 149380 if all file names were printed without issue. 149391 otherwise. 14940@end display 14941 14942@menu 14943* Realpath usage examples:: Realpath usage examples. 14944@end menu 14945 14946 14947@node Realpath usage examples 14948@subsection Realpath usage examples 14949 14950@opindex --relative-to 14951@opindex --relative-base 14952 14953By default, @command{realpath} prints the absolute file name of given files 14954(symlinks are resolved, @file{words} is resolved to @file{american-english}): 14955 14956@example 14957@group 14958cd /home/user 14959realpath /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt 14960@result{} /usr/bin/sort 14961@result{} /tmp/foo 14962@result{} /usr/share/dict/american-english 14963@result{} /home/user/1.txt 14964@end group 14965@end example 14966 14967With @option{--relative-to}, file names are printed relative to 14968the given directory: 14969 14970@example 14971@group 14972realpath --relative-to=/usr/bin \ 14973 /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt 14974@result{} sort 14975@result{} ../../tmp/foo 14976@result{} ../share/dict/american-english 14977@result{} ../../home/user/1.txt 14978@end group 14979@end example 14980 14981With @option{--relative-base}, relative file names are printed @emph{if} 14982the resolved file name is below the given base directory. For files outside the 14983base directory absolute file names are printed: 14984 14985@example 14986@group 14987realpath --relative-base=/usr \ 14988 /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt 14989@result{} bin/sort 14990@result{} /tmp/foo 14991@result{} share/dict/american-english 14992@result{} /home/user/1.txt 14993@end group 14994@end example 14995 14996When both @option{--relative-to=DIR1} and @option{--relative-base=DIR2} 14997are used, file names are printed relative to @var{dir1} @emph{if} they are 14998located below @var{dir2}. If the files are not below @var{dir2}, they are 14999printed as absolute file names: 15000 15001@example 15002@group 15003realpath --relative-to=/usr/bin --relative-base=/usr \ 15004 /usr/bin/sort /tmp/foo /usr/share/dict/words 1.txt 15005@result{} sort 15006@result{} /tmp/foo 15007@result{} ../share/dict/american-english 15008@result{} /home/user/1.txt 15009@end group 15010@end example 15011 15012When both @option{--relative-to=DIR1} and @option{--relative-base=DIR2} 15013are used, @var{dir1} @emph{must} be a subdirectory of @var{dir2}. Otherwise, 15014@command{realpath} prints absolutes file names. 15015 15016 15017@node Working context 15018@chapter Working context 15019 15020@cindex working context 15021@cindex commands for printing the working context 15022 15023This section describes commands that display or alter the context in 15024which you are working: the current directory, the terminal settings, and 15025so forth. See also the user-related commands in the next section. 15026 15027@menu 15028* pwd invocation:: Print working directory. 15029* stty invocation:: Print or change terminal characteristics. 15030* printenv invocation:: Print environment variables. 15031* tty invocation:: Print file name of terminal on standard input. 15032@end menu 15033 15034 15035@node pwd invocation 15036@section @command{pwd}: Print working directory 15037 15038@pindex pwd 15039@cindex print name of current directory 15040@cindex current working directory, printing 15041@cindex working directory, printing 15042 15043 15044@command{pwd} prints the name of the current directory. Synopsis: 15045 15046@example 15047pwd [@var{option}]@dots{} 15048@end example 15049 15050The program accepts the following options. Also see @ref{Common options}. 15051 15052@table @samp 15053@item -L 15054@itemx --logical 15055@opindex -L 15056@opindex --logical 15057If the contents of the environment variable @env{PWD} provide an 15058absolute name of the current directory with no @samp{.} or @samp{..} 15059components, but possibly with symbolic links, then output those 15060contents. Otherwise, fall back to default @option{-P} handling. 15061 15062@item -P 15063@itemx --physical 15064@opindex -P 15065@opindex --physical 15066Print a fully resolved name for the current directory. That is, all 15067components of the printed name will be actual directory names -- none 15068will be symbolic links. 15069@end table 15070 15071@cindex symbolic links and @command{pwd} 15072If @option{-L} and @option{-P} are both given, the last one takes 15073precedence. If neither option is given, then this implementation uses 15074@option{-P} as the default unless the @env{POSIXLY_CORRECT} 15075environment variable is set. 15076 15077@mayConflictWithShellBuiltIn{pwd} 15078 15079@exitstatus 15080 15081 15082@node stty invocation 15083@section @command{stty}: Print or change terminal characteristics 15084 15085@pindex stty 15086@cindex change or print terminal settings 15087@cindex terminal settings 15088@cindex line settings of terminal 15089 15090@command{stty} prints or changes terminal characteristics, such as baud rate. 15091Synopses: 15092 15093@example 15094stty [@var{option}] [@var{setting}]@dots{} 15095stty [@var{option}] 15096@end example 15097 15098If given no line settings, @command{stty} prints the baud rate, line 15099discipline number (on systems that support it), and line settings 15100that have been changed from the values set by @samp{stty sane}. 15101By default, mode reading and setting are performed on the tty line 15102connected to standard input, although this can be modified by the 15103@option{--file} option. 15104 15105@command{stty} accepts many non-option arguments that change aspects of 15106the terminal line operation, as described below. 15107 15108The program accepts the following options. Also see @ref{Common options}. 15109 15110@table @samp 15111@item -a 15112@itemx --all 15113@opindex -a 15114@opindex --all 15115Print all current settings in human-readable form. This option may not 15116be used in combination with any line settings. 15117 15118@item -F @var{device} 15119@itemx --file=@var{device} 15120@opindex -F 15121@opindex --file 15122Set the line opened by the file name specified in @var{device} instead of 15123the tty line connected to standard input. This option is necessary 15124because opening a POSIX tty requires use of the 15125@code{O_NONDELAY} flag to prevent a POSIX tty from blocking 15126until the carrier detect line is high if 15127the @code{clocal} flag is not set. Hence, it is not always possible 15128to allow the shell to open the device in the traditional manner. 15129 15130@item -g 15131@itemx --save 15132@opindex -g 15133@opindex --save 15134@cindex machine-readable @command{stty} output 15135Print all current settings in a form that can be used as an argument to 15136another @command{stty} command to restore the current settings. This option 15137may not be used in combination with any line settings. 15138 15139@end table 15140 15141Many settings can be turned off by preceding them with a @samp{-}. 15142Such arguments are marked below with ``May be negated'' in their 15143description. The descriptions themselves refer to the positive 15144case, that is, when @emph{not} negated (unless stated otherwise, 15145of course). 15146 15147Some settings are not available on all POSIX systems, since they use 15148extensions. Such arguments are marked below with 15149``Non-POSIX'' in their description. On non-POSIX 15150systems, those or other settings also may not 15151be available, but it's not feasible to document all the variations: just 15152try it and see. 15153 15154@command{stty} is installed only on platforms with the POSIX terminal 15155interface, so portable scripts should not rely on its existence on 15156non-POSIX platforms. 15157 15158@exitstatus 15159 15160@menu 15161* Control:: Control settings 15162* Input:: Input settings 15163* Output:: Output settings 15164* Local:: Local settings 15165* Combination:: Combination settings 15166* Characters:: Special characters 15167* Special:: Special settings 15168@end menu 15169 15170 15171@node Control 15172@subsection Control settings 15173 15174@cindex control settings 15175Control settings: 15176 15177@table @samp 15178@item parenb 15179@opindex parenb 15180@cindex two-way parity 15181Generate parity bit in output and expect parity bit in input. 15182May be negated. 15183 15184@item parodd 15185@opindex parodd 15186@cindex odd parity 15187@cindex even parity 15188Set odd parity (even if negated). May be negated. 15189 15190@item cmspar 15191@opindex cmspar 15192@cindex constant parity 15193@cindex stick parity 15194@cindex mark parity 15195@cindex space parity 15196Use "stick" (mark/space) parity. If parodd is set, the parity bit is 15197always 1; if parodd is not set, the parity bit is always zero. 15198Non-POSIX@. May be negated. 15199 15200@item cs5 15201@itemx cs6 15202@itemx cs7 15203@itemx cs8 15204@opindex cs@var{n} 15205@cindex character size 15206@cindex eight-bit characters 15207Set character size to 5, 6, 7, or 8 bits. 15208 15209@item hup 15210@itemx hupcl 15211@opindex hup[cl] 15212Send a hangup signal when the last process closes the tty. May be 15213negated. 15214 15215@item cstopb 15216@opindex cstopb 15217@cindex stop bits 15218Use two stop bits per character (one if negated). May be negated. 15219 15220@item cread 15221@opindex cread 15222Allow input to be received. May be negated. 15223 15224@item clocal 15225@opindex clocal 15226@cindex modem control 15227Disable modem control signals. May be negated. 15228 15229@item crtscts 15230@opindex crtscts 15231@cindex hardware flow control 15232@cindex flow control, hardware 15233@cindex RTS/CTS flow control 15234Enable RTS/CTS flow control. Non-POSIX@. May be negated. 15235 15236@item cdtrdsr 15237@opindex cdtrdsr 15238@cindex hardware flow control 15239@cindex flow control, hardware 15240@cindex DTR/DSR flow control 15241Enable DTR/DSR flow control. Non-POSIX@. May be negated. 15242@end table 15243 15244 15245@node Input 15246@subsection Input settings 15247 15248@cindex input settings 15249These settings control operations on data received from the terminal. 15250 15251@table @samp 15252@item ignbrk 15253@opindex ignbrk 15254@cindex breaks, ignoring 15255Ignore break characters. May be negated. 15256 15257@item brkint 15258@opindex brkint 15259@cindex breaks, cause interrupts 15260Make breaks cause an interrupt signal. May be negated. 15261 15262@item ignpar 15263@opindex ignpar 15264@cindex parity, ignoring 15265Ignore characters with parity errors. May be negated. 15266 15267@item parmrk 15268@opindex parmrk 15269@cindex parity errors, marking 15270Mark parity errors (with a 255-0-character sequence). May be negated. 15271 15272@item inpck 15273@opindex inpck 15274Enable input parity checking. May be negated. 15275 15276@item istrip 15277@opindex istrip 15278@cindex eight-bit input 15279Clear high (8th) bit of input characters. May be negated. 15280 15281@item inlcr 15282@opindex inlcr 15283@cindex newline, translating to return 15284Translate newline to carriage return. May be negated. 15285 15286@item igncr 15287@opindex igncr 15288@cindex return, ignoring 15289Ignore carriage return. May be negated. 15290 15291@item icrnl 15292@opindex icrnl 15293@cindex return, translating to newline 15294Translate carriage return to newline. May be negated. 15295 15296@item iutf8 15297@opindex iutf8 15298@cindex input encoding, UTF-8 15299Assume input characters are UTF-8 encoded. May be negated. 15300 15301@item ixon 15302@opindex ixon 15303@kindex C-s/C-q flow control 15304@cindex XON/XOFF flow control 15305Enable XON/XOFF flow control (that is, @kbd{Ctrl-S}/@kbd{Ctrl-Q}). May 15306be negated. 15307 15308@item ixoff 15309@itemx tandem 15310@opindex ixoff 15311@opindex tandem 15312@cindex software flow control 15313@cindex flow control, software 15314Enable sending of @code{stop} character when the system input buffer 15315is almost full, and @code{start} character when it becomes almost 15316empty again. May be negated. 15317 15318@item iuclc 15319@opindex iuclc 15320@cindex uppercase, translating to lowercase 15321Translate uppercase characters to lowercase. Non-POSIX@. May be 15322negated. Note ilcuc is not implemented, as one would not be able to issue 15323almost any (lowercase) Unix command, after invoking it. 15324 15325@item ixany 15326@opindex ixany 15327Allow any character to restart output (only the start character 15328if negated). Non-POSIX@. May be negated. 15329 15330@item imaxbel 15331@opindex imaxbel 15332@cindex beeping at input buffer full 15333Enable beeping and not flushing input buffer if a character arrives 15334when the input buffer is full. Non-POSIX@. May be negated. 15335@end table 15336 15337 15338@node Output 15339@subsection Output settings 15340 15341@cindex output settings 15342These settings control operations on data sent to the terminal. 15343 15344@table @samp 15345@item opost 15346@opindex opost 15347Postprocess output. May be negated. 15348 15349@item olcuc 15350@opindex olcuc 15351@cindex lowercase, translating to output 15352Translate lowercase characters to uppercase. Non-POSIX@. May be 15353negated. (Note ouclc is not currently implemented.) 15354 15355@item ocrnl 15356@opindex ocrnl 15357@cindex return, translating to newline 15358Translate carriage return to newline. Non-POSIX@. May be negated. 15359 15360@item onlcr 15361@opindex onlcr 15362@cindex newline, translating to crlf 15363Translate newline to carriage return-newline. Non-POSIX@. May be 15364negated. 15365 15366@item onocr 15367@opindex onocr 15368Do not print carriage returns in the first column. Non-POSIX@. 15369May be negated. 15370 15371@item onlret 15372@opindex onlret 15373Newline performs a carriage return. Non-POSIX@. May be negated. 15374 15375@item ofill 15376@opindex ofill 15377@cindex pad instead of timing for delaying 15378Use fill (padding) characters instead of timing for delays. 15379Non-POSIX@. 15380May be negated. 15381 15382@item ofdel 15383@opindex ofdel 15384@cindex pad character 15385Use ASCII DEL characters for fill instead of 15386ASCII NUL characters. Non-POSIX@. 15387May be negated. 15388 15389@item nl1 15390@itemx nl0 15391@opindex nl@var{n} 15392Newline delay style. Non-POSIX. 15393 15394@item cr3 15395@itemx cr2 15396@itemx cr1 15397@itemx cr0 15398@opindex cr@var{n} 15399Carriage return delay style. Non-POSIX. 15400 15401@item tab3 15402@itemx tab2 15403@itemx tab1 15404@itemx tab0 15405@opindex tab@var{n} 15406Horizontal tab delay style. Non-POSIX. 15407 15408@item bs1 15409@itemx bs0 15410@opindex bs@var{n} 15411Backspace delay style. Non-POSIX. 15412 15413@item vt1 15414@itemx vt0 15415@opindex vt@var{n} 15416Vertical tab delay style. Non-POSIX. 15417 15418@item ff1 15419@itemx ff0 15420@opindex ff@var{n} 15421Form feed delay style. Non-POSIX. 15422@end table 15423 15424 15425@node Local 15426@subsection Local settings 15427 15428@cindex local settings 15429 15430@table @samp 15431@item isig 15432@opindex isig 15433Enable @code{interrupt}, @code{quit}, and @code{suspend} special 15434characters. May be negated. 15435 15436@item icanon 15437@opindex icanon 15438Enable @code{erase}, @code{kill}, @code{werase}, and @code{rprnt} 15439special characters. May be negated. 15440 15441@item iexten 15442@opindex iexten 15443Enable non-POSIX special characters. May be negated. 15444 15445@item echo 15446@opindex echo 15447Echo input characters. May be negated. 15448 15449@item echoe 15450@itemx crterase 15451@opindex echoe 15452@opindex crterase 15453Echo @code{erase} characters as backspace-space-backspace. May be 15454negated. 15455 15456@item echok 15457@opindex echok 15458@cindex newline echoing after @code{kill} 15459Echo a newline after a @code{kill} character. May be negated. 15460 15461@item echonl 15462@opindex echonl 15463@cindex newline, echoing 15464Echo newline even if not echoing other characters. May be negated. 15465 15466@item noflsh 15467@opindex noflsh 15468@cindex flushing, disabling 15469Disable flushing after @code{interrupt} and @code{quit} special 15470characters. May be negated. 15471 15472@item xcase 15473@opindex xcase 15474@cindex case translation 15475Enable input and output of uppercase characters by preceding their 15476lowercase equivalents with @samp{\}, when @code{icanon} is set. 15477Non-POSIX@. May be negated. 15478 15479@item tostop 15480@opindex tostop 15481@cindex background jobs, stopping at terminal write 15482Stop background jobs that try to write to the terminal. Non-POSIX@. 15483May be negated. 15484 15485@item echoprt 15486@itemx prterase 15487@opindex echoprt 15488@opindex prterase 15489Echo erased characters backward, between @samp{\} and @samp{/}. 15490Non-POSIX@. May be negated. 15491 15492@item echoctl 15493@itemx ctlecho 15494@opindex echoctl 15495@opindex ctlecho 15496@cindex control characters, using @samp{^@var{c}} 15497@cindex hat notation for control characters 15498Echo control characters in hat notation (@samp{^@var{c}}) instead 15499of literally. Non-POSIX@. May be negated. 15500 15501@item echoke 15502@itemx crtkill 15503@opindex echoke 15504@opindex crtkill 15505Echo the @code{kill} special character by erasing each character on 15506the line as indicated by the @code{echoprt} and @code{echoe} settings, 15507instead of by the @code{echoctl} and @code{echok} settings. 15508Non-POSIX@. 15509May be negated. 15510 15511@item extproc 15512@opindex extproc 15513Enable @samp{LINEMODE}, which is used to avoid echoing 15514each character over high latency links. See also 15515@uref{https://datatracker.ietf.org/doc/rfc1116/, Internet RFC 1116}. 15516Non-POSIX@. 15517May be negated. 15518 15519@item flusho 15520@opindex flusho 15521Discard output. 15522Note this setting is currently ignored on GNU/Linux systems. 15523Non-POSIX@. 15524May be negated. 15525@end table 15526 15527 15528@node Combination 15529@subsection Combination settings 15530 15531@cindex combination settings 15532Combination settings: 15533 15534@table @samp 15535@item evenp 15536@opindex evenp 15537@itemx parity 15538@opindex parity 15539Same as @code{parenb -parodd cs7}. May be negated. If negated, same 15540as @code{-parenb cs8}. 15541 15542@item oddp 15543@opindex oddp 15544Same as @code{parenb parodd cs7}. May be negated. If negated, same 15545as @code{-parenb cs8}. 15546 15547@item nl 15548@opindex nl 15549Same as @code{-icrnl -onlcr}. May be negated. If negated, same as 15550@code{icrnl -inlcr -igncr onlcr -ocrnl -onlret}. 15551 15552@item ek 15553@opindex ek 15554Reset the @code{erase} and @code{kill} special characters to their default 15555values. 15556 15557@item sane 15558@opindex sane 15559Same as: 15560 15561@c This is too long to write inline. 15562@example 15563cread -ignbrk brkint -inlcr -igncr icrnl 15564icanon iexten echo echoe echok -echonl -noflsh 15565-ixoff -iutf8 -iuclc -ixany imaxbel -xcase -olcuc -ocrnl 15566opost -ofill onlcr -onocr -onlret nl0 cr0 tab0 bs0 vt0 ff0 15567isig -tostop -ofdel -echoprt echoctl echoke -extproc 15568@end example 15569 15570@noindent 15571and also sets all special characters to their default values. 15572 15573@item cooked 15574@opindex cooked 15575Same as @code{brkint ignpar istrip icrnl ixon opost isig icanon}, plus 15576sets the @code{eof} and @code{eol} characters to their default values 15577if they are the same as the @code{min} and @code{time} characters. 15578May be negated. If negated, same as @code{raw}. 15579 15580@item raw 15581@opindex raw 15582Same as: 15583 15584@example 15585-ignbrk -brkint -ignpar -parmrk -inpck -istrip 15586-inlcr -igncr -icrnl -ixon -ixoff -icanon -opost 15587-isig -iuclc -ixany -imaxbel -xcase min 1 time 0 15588@end example 15589 15590@noindent 15591May be negated. If negated, same as @code{cooked}. 15592 15593@item cbreak 15594@opindex cbreak 15595Same as @option{-icanon}. May be negated. If negated, same as 15596@code{icanon}. 15597 15598@item pass8 15599@opindex pass8 15600@cindex eight-bit characters 15601Same as @code{-parenb -istrip cs8}. May be negated. If negated, 15602same as @code{parenb istrip cs7}. 15603 15604@item litout 15605@opindex litout 15606Same as @option{-parenb -istrip -opost cs8}. May be negated. 15607If negated, same as @code{parenb istrip opost cs7}. 15608 15609@item decctlq 15610@opindex decctlq 15611Same as @option{-ixany}. Non-POSIX@. May be negated. 15612 15613@item tabs 15614@opindex tabs 15615Same as @code{tab0}. Non-POSIX@. May be negated. If negated, same 15616as @code{tab3}. 15617 15618@item lcase 15619@itemx LCASE 15620@opindex lcase 15621@opindex LCASE 15622Same as @code{xcase iuclc olcuc}. Non-POSIX@. May be negated. 15623(Used for terminals with uppercase characters only.) 15624 15625@item crt 15626@opindex crt 15627Same as @code{echoe echoctl echoke}. 15628 15629@item dec 15630@opindex dec 15631Same as @code{echoe echoctl echoke -ixany intr ^C erase ^? kill C-u}. 15632@end table 15633 15634 15635@node Characters 15636@subsection Special characters 15637 15638@cindex special characters 15639@cindex characters, special 15640 15641The special characters' default values vary from system to system. 15642They are set with the syntax @samp{name value}, where the names are 15643listed below and the value can be given either literally, in hat 15644notation (@samp{^@var{c}}), or as an integer which may start with 15645@samp{0x} to indicate hexadecimal, @samp{0} to indicate octal, or 15646any other digit to indicate decimal. 15647 15648@cindex disabling special characters 15649@kindex u@r{, and disabling special characters} 15650For GNU stty, giving a value of @code{^-} or @code{undef} disables that 15651special character. (This is incompatible with Ultrix @command{stty}, 15652which uses a value of @samp{u} to disable a special character. GNU 15653@command{stty} treats a value @samp{u} like any other, namely to set that 15654special character to @key{U}.) 15655 15656@table @samp 15657 15658@item intr 15659@opindex intr 15660Send an interrupt signal. 15661 15662@item quit 15663@opindex quit 15664Send a quit signal. 15665 15666@item erase 15667@opindex erase 15668Erase the last character typed. 15669 15670@item kill 15671@opindex kill 15672Erase the current line. 15673 15674@item eof 15675@opindex eof 15676Send an end of file (terminate the input). 15677 15678@item eol 15679@opindex eol 15680End the line. 15681 15682@item eol2 15683@opindex eol2 15684Alternate character to end the line. Non-POSIX. 15685 15686@item discard 15687@opindex discard 15688@opindex flush 15689Alternate character to toggle discarding of output. Non-POSIX. 15690 15691@item swtch 15692@opindex swtch 15693Switch to a different shell layer. Non-POSIX. 15694 15695@item status 15696@opindex status 15697Send an info signal. Not currently supported on GNU/Linux. Non-POSIX. 15698 15699@item start 15700@opindex start 15701Restart the output after stopping it. 15702 15703@item stop 15704@opindex stop 15705Stop the output. 15706 15707@item susp 15708@opindex susp 15709Send a terminal stop signal. 15710 15711@item dsusp 15712@opindex dsusp 15713Send a terminal stop signal after flushing the input. Non-POSIX. 15714 15715@item rprnt 15716@opindex rprnt 15717Redraw the current line. Non-POSIX. 15718 15719@item werase 15720@opindex werase 15721Erase the last word typed. Non-POSIX. 15722 15723@item lnext 15724@opindex lnext 15725Enter the next character typed literally, even if it is a special 15726character. Non-POSIX. 15727@end table 15728 15729 15730@node Special 15731@subsection Special settings 15732 15733@cindex special settings 15734 15735@table @samp 15736@item min @var{n} 15737@opindex min 15738Set the minimum number of characters that will satisfy a read until 15739the time value has expired, when @option{-icanon} is set. 15740 15741@item time @var{n} 15742@opindex time 15743Set the number of tenths of a second before reads time out if the minimum 15744number of characters have not been read, when @option{-icanon} is set. 15745 15746@item ispeed @var{n} 15747@opindex ispeed 15748Set the input speed to @var{n}. 15749 15750@item ospeed @var{n} 15751@opindex ospeed 15752Set the output speed to @var{n}. 15753 15754@item rows @var{n} 15755@opindex rows 15756Tell the tty kernel driver that the terminal has @var{n} rows. 15757Non-POSIX. 15758 15759@item cols @var{n} 15760@itemx columns @var{n} 15761@opindex cols 15762@opindex columns 15763Tell the kernel that the terminal has @var{n} columns. Non-POSIX. 15764 15765@item drain 15766@opindex drain 15767@cindex nonblocking @command{stty} setting 15768Apply settings after first waiting for pending output to be transmitted. 15769This is enabled by default for GNU @command{stty}. 15770Note this is treated as an option rather than a line setting, 15771and will follow the option processing rules described in the summary above. 15772It is useful to disable this option 15773in cases where the system may be in a state where serial transmission 15774is not possible. 15775For example, if the system has received the @samp{DC3} character 15776with @code{ixon} (software flow control) enabled, then @command{stty} would 15777block without @code{-drain} being specified. 15778May be negated. Non-POSIX. 15779 15780@item size 15781@opindex size 15782@vindex LINES 15783@vindex COLUMNS 15784Print the number of rows and columns that the kernel thinks the 15785terminal has. (Systems that don't support rows and columns in the kernel 15786typically use the environment variables @env{LINES} and @env{COLUMNS} 15787instead; however, GNU @command{stty} does not know anything about them.) 15788Non-POSIX. 15789 15790@item line @var{n} 15791@opindex line 15792Use line discipline @var{n}. Non-POSIX. 15793 15794@item speed 15795@opindex speed 15796Print the terminal speed. 15797 15798@item @var{n} 15799@cindex baud rate, setting 15800Set the input and output speeds to @var{n}. @var{n} can be one of: 0 1580150 75 110 134 134.5 150 200 300 600 1200 1800 2400 4800 9600 19200 1580238400 @code{exta} @code{extb}. @code{exta} is the same as 19200; 15803@code{extb} is the same as 38400. Many systems, including GNU/Linux, 15804support higher speeds. The @command{stty} command includes support 15805for speeds of 1580657600, 15807115200, 15808230400, 15809460800, 15810500000, 15811576000, 15812921600, 158131000000, 158141152000, 158151500000, 158162000000, 158172500000, 158183000000, 158193500000, 15820or 158214000000 where the system supports these. 158220 hangs up the line if @option{-clocal} is set. 15823@end table 15824 15825 15826@node printenv invocation 15827@section @command{printenv}: Print all or some environment variables 15828 15829@pindex printenv 15830@cindex printing all or some environment variables 15831@cindex environment variables, printing 15832 15833@command{printenv} prints environment variable values. Synopsis: 15834 15835@example 15836printenv [@var{option}] [@var{variable}]@dots{} 15837@end example 15838 15839If no @var{variable}s are specified, @command{printenv} prints the value of 15840every environment variable. Otherwise, it prints the value of each 15841@var{variable} that is set, and nothing for those that are not set. 15842 15843The program accepts the following option. Also see @ref{Common options}. 15844 15845@table @samp 15846 15847@optNull 15848 15849@end table 15850 15851@cindex exit status of @command{printenv} 15852Exit status: 15853 15854@display 158550 if all variables specified were found 158561 if at least one specified variable was not found 158572 if a write error occurred 15858@end display 15859 15860 15861@node tty invocation 15862@section @command{tty}: Print file name of terminal on standard input 15863 15864@pindex tty 15865@cindex print terminal file name 15866@cindex terminal file name, printing 15867 15868@command{tty} prints the file name of the terminal connected to its standard 15869input. It prints @samp{not a tty} if standard input is not a terminal. 15870Synopsis: 15871 15872@example 15873tty [@var{option}]@dots{} 15874@end example 15875 15876The program accepts the following option. Also see @ref{Common options}. 15877 15878@table @samp 15879 15880@item -s 15881@itemx --silent 15882@itemx --quiet 15883@opindex -s 15884@opindex --silent 15885@opindex --quiet 15886Print nothing; only return an exit status. 15887 15888@end table 15889 15890@cindex exit status of @command{tty} 15891Exit status: 15892 15893@display 158940 if standard input is a terminal 158951 if standard input is a non-terminal file 158962 if given incorrect arguments 158973 if a write error occurs 15898@end display 15899 15900 15901@node User information 15902@chapter User information 15903 15904@cindex user information, commands for 15905@cindex commands for printing user information 15906 15907This section describes commands that print user-related information: 15908logins, groups, and so forth. 15909 15910@menu 15911* id invocation:: Print user identity. 15912* logname invocation:: Print current login name. 15913* whoami invocation:: Print effective user ID. 15914* groups invocation:: Print group names a user is in. 15915* users invocation:: Print login names of users currently logged in. 15916* who invocation:: Print who is currently logged in. 15917@end menu 15918 15919 15920@node id invocation 15921@section @command{id}: Print user identity 15922 15923@pindex id 15924@cindex real user and group IDs, printing 15925@cindex effective user and group IDs, printing 15926@cindex printing real and effective user and group IDs 15927 15928@command{id} prints information about the given user, or the process 15929running it if no user is specified. Synopsis: 15930 15931@example 15932id [@var{option}]@dots{} [@var{user}]@dots{} 15933@end example 15934 15935@var{user} can be either a user ID or a name, with name look-up 15936taking precedence unless the ID is specified with a leading @samp{+}. 15937@xref{Disambiguating names and IDs}. 15938 15939@vindex POSIXLY_CORRECT 15940By default, it prints the real user ID, real group ID, effective user ID 15941if different from the real user ID, effective group ID if different from 15942the real group ID, and supplemental group IDs. 15943In addition, if SELinux 15944is enabled and the @env{POSIXLY_CORRECT} environment variable is not set, 15945then print @samp{context=@var{c}}, where @var{c} is the security context. 15946 15947Each of these numeric values is preceded by an identifying string and 15948followed by the corresponding user or group name in parentheses. 15949 15950The options cause @command{id} to print only part of the above information. 15951Also see @ref{Common options}. 15952 15953@table @samp 15954@item -g 15955@itemx --group 15956@opindex -g 15957@opindex --group 15958Print only the group ID. 15959 15960@item -G 15961@itemx --groups 15962@opindex -G 15963@opindex --groups 15964Print only the group ID and the supplementary groups. 15965 15966@item -n 15967@itemx --name 15968@opindex -n 15969@opindex --name 15970Print the user or group name instead of the ID number. Requires 15971@option{-u}, @option{-g}, or @option{-G}. 15972 15973@item -r 15974@itemx --real 15975@opindex -r 15976@opindex --real 15977Print the real, instead of effective, user or group ID@. Requires 15978@option{-u}, @option{-g}, or @option{-G}. 15979 15980@item -u 15981@itemx --user 15982@opindex -u 15983@opindex --user 15984Print only the user ID. 15985 15986@item -Z 15987@itemx --context 15988@opindex -Z 15989@opindex --context 15990@cindex SELinux 15991@cindex security context 15992Print only the security context of the process, which is generally 15993the user's security context inherited from the parent process. 15994If neither SELinux or SMACK is enabled then print a warning and 15995set the exit status to 1. 15996 15997@item -z 15998@itemx --zero 15999@opindex -z 16000@opindex --zero 16001Delimit output items with ASCII NUL characters. 16002This option is not permitted when using the default format. 16003When multiple users are specified, and the @option{--groups} option 16004is also in effect, groups are delimited with a single NUL character, 16005while users are delimited with two NUL characters. 16006 16007Example: 16008@example 16009$ id -Gn --zero 16010users <NUL> devs <NUL> 16011@end example 16012 16013@end table 16014 16015@macro primaryAndSupplementaryGroups{cmd,arg} 16016Primary and supplementary groups for a process are normally inherited 16017from its parent and are usually unchanged since login. This means 16018that if you change the group database after logging in, @command{\cmd\} 16019will not reflect your changes within your existing login session. 16020Running @command{\cmd\} with a \arg\ causes the user and group 16021database to be consulted afresh, and so will give a different result. 16022@end macro 16023@primaryAndSupplementaryGroups{id,user argument} 16024 16025@exitstatus 16026 16027@node logname invocation 16028@section @command{logname}: Print current login name 16029 16030@pindex logname 16031@cindex printing user's login name 16032@cindex login name, printing 16033@cindex user name, printing 16034 16035@flindex utmp 16036@command{logname} prints the calling user's name, as found in a 16037system-maintained file (often @file{/var/run/utmp} or 16038@file{/etc/utmp}), and exits with a status of 0. If there is no entry 16039for the calling process, @command{logname} prints 16040an error message and exits with a status of 1. 16041 16042The only options are @option{--help} and @option{--version}. @xref{Common 16043options}. 16044 16045@exitstatus 16046 16047 16048@node whoami invocation 16049@section @command{whoami}: Print effective user name 16050 16051@pindex whoami 16052@cindex effective user name, printing 16053@cindex printing the effective user ID 16054 16055@command{whoami} prints the user name associated with the current 16056effective user ID@. It is equivalent to the command @samp{id -un}. 16057 16058The only options are @option{--help} and @option{--version}. @xref{Common 16059options}. 16060 16061@exitstatus 16062 16063 16064@node groups invocation 16065@section @command{groups}: Print group names a user is in 16066 16067@pindex groups 16068@cindex printing groups a user is in 16069@cindex supplementary groups, printing 16070 16071@command{groups} prints the names of the primary and any supplementary 16072groups for each given @var{username}, or the current process if no names 16073are given. If more than one name is given, the name of each user is 16074printed before 16075the list of that user's groups and the user name is separated from the 16076group list by a colon. Synopsis: 16077 16078@example 16079groups [@var{username}]@dots{} 16080@end example 16081 16082The group lists are equivalent to the output of the command @samp{id -Gn}. 16083 16084The only options are @option{--help} and @option{--version}. @xref{Common 16085options}. 16086 16087@primaryAndSupplementaryGroups{groups,list of users} 16088 16089@exitstatus 16090 16091@node users invocation 16092@section @command{users}: Print login names of users currently logged in 16093 16094@pindex users 16095@cindex printing current usernames 16096@cindex usernames, printing current 16097 16098@cindex login sessions, printing users with 16099@command{users} prints on a single line a blank-separated list of user 16100names of users currently logged in to the current host. Each user name 16101corresponds to a login session, so if a user has more than one login 16102session, that user's name will appear the same number of times in the 16103output. Synopsis: 16104 16105@example 16106users [@var{file}] 16107@end example 16108 16109@flindex utmp 16110@flindex wtmp 16111With no @var{file} argument, @command{users} extracts its information from 16112a system-maintained file (often @file{/var/run/utmp} or 16113@file{/etc/utmp}). If a file argument is given, @command{users} uses 16114that file instead. A common choice is @file{/var/log/wtmp}. 16115 16116The only options are @option{--help} and @option{--version}. @xref{Common 16117options}. 16118 16119The @command{users} command is installed only on platforms with the 16120POSIX @code{<utmpx.h>} include file or equivalent, so portable scripts 16121should not rely on its existence on non-POSIX platforms. 16122 16123@exitstatus 16124 16125 16126@node who invocation 16127@section @command{who}: Print who is currently logged in 16128 16129@pindex who 16130@cindex printing current user information 16131@cindex information, about current users 16132 16133@command{who} prints information about users who are currently logged on. 16134Synopsis: 16135 16136@example 16137@command{who} [@var{option}] [@var{file}] [am i] 16138@end example 16139 16140@cindex terminal lines, currently used 16141@cindex login time 16142@cindex remote hostname 16143If given no non-option arguments, @command{who} prints the following 16144information for each user currently logged on: login name, terminal 16145line, login time, and remote hostname or X display. 16146 16147@flindex utmp 16148@flindex wtmp 16149If given one non-option argument, @command{who} uses that instead of 16150a default system-maintained file (often @file{/var/run/utmp} or 16151@file{/etc/utmp}) as the name of the file containing the record of 16152users logged on. @file{/var/log/wtmp} is commonly given as an argument 16153to @command{who} to look at who has previously logged on. 16154 16155@opindex am i 16156@opindex who am i 16157If given two non-option arguments, @command{who} prints only the entry 16158for the user running it (determined from its standard input), preceded 16159by the hostname. Traditionally, the two arguments given are @samp{am 16160i}, as in @samp{who am i}. 16161 16162@vindex TZ 16163Timestamps are listed according to the time zone rules specified by 16164the @env{TZ} environment variable, or by the system default rules if 16165@env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone 16166with @env{TZ}, libc, The GNU C Library Reference Manual}. 16167 16168The program accepts the following options. Also see @ref{Common options}. 16169 16170@table @samp 16171 16172@item -a 16173@itemx --all 16174@opindex -a 16175@opindex --all 16176Same as @samp{-b -d --login -p -r -t -T -u}. 16177 16178@item -b 16179@itemx --boot 16180@opindex -b 16181@opindex --boot 16182Print the date and time of last system boot. 16183 16184@item -d 16185@itemx --dead 16186@opindex -d 16187@opindex --dead 16188Print information corresponding to dead processes. 16189 16190@item -H 16191@itemx --heading 16192@opindex -H 16193@opindex --heading 16194Print a line of column headings. 16195 16196@item -l 16197@itemx --login 16198@opindex -l 16199@opindex --login 16200List only the entries that correspond to processes via which the 16201system is waiting for a user to login. The user name is always @samp{LOGIN}. 16202 16203@item --lookup 16204@opindex --lookup 16205Attempt to canonicalize hostnames found in utmp through a DNS lookup. This 16206is not the default because it can cause significant delays on systems with 16207automatic dial-up internet access. 16208 16209@item -m 16210@opindex -m 16211Same as @samp{who am i}. 16212 16213@item -p 16214@itemx --process 16215@opindex -p 16216@opindex --process 16217List active processes spawned by init. 16218 16219@item -q 16220@itemx --count 16221@opindex -q 16222@opindex --count 16223Print only the login names and the number of users logged on. 16224Overrides all other options. 16225 16226@item -r 16227@itemx --runlevel 16228@opindex -r 16229@opindex --runlevel 16230Print the current (and maybe previous) run-level of the init process. 16231 16232@item -s 16233@opindex -s 16234Ignored; for compatibility with other versions of @command{who}. 16235 16236@item -t 16237@itemx --time 16238@opindex -t 16239@opindex --time 16240Print last system clock change. 16241 16242@item -u 16243@opindex -u 16244@cindex idle time 16245After the login time, print the number of hours and minutes that the 16246user has been idle. @samp{.} means the user was active in the last minute. 16247@samp{old} means the user has been idle for more than 24 hours. 16248 16249@item -w 16250@itemx -T 16251@itemx --mesg 16252@itemx --message 16253@itemx --writable 16254@opindex -w 16255@opindex -T 16256@opindex --mesg 16257@opindex --message 16258@opindex --writable 16259@cindex message status 16260@pindex write@r{, allowed} 16261After each login name print a character indicating the user's message status: 16262 16263@display 16264@samp{+} allowing @code{write} messages 16265@samp{-} disallowing @code{write} messages 16266@samp{?} cannot find terminal device 16267@end display 16268 16269@end table 16270 16271The @command{who} command is installed only on platforms with the 16272POSIX @code{<utmpx.h>} include file or equivalent, so portable scripts 16273should not rely on its existence on non-POSIX platforms. 16274 16275@exitstatus 16276 16277 16278@node System context 16279@chapter System context 16280 16281@cindex system context 16282@cindex context, system 16283@cindex commands for system context 16284 16285This section describes commands that print or change system-wide 16286information. 16287 16288@menu 16289* date invocation:: Print or set system date and time. 16290* arch invocation:: Print machine hardware name. 16291* nproc invocation:: Print the number of processors. 16292* uname invocation:: Print system information. 16293* hostname invocation:: Print or set system name. 16294* hostid invocation:: Print numeric host identifier. 16295* uptime invocation:: Print system uptime and load. 16296@end menu 16297 16298@node date invocation 16299@section @command{date}: Print or set system date and time 16300 16301@pindex date 16302@cindex time, printing or setting 16303@cindex printing the current time 16304 16305Synopses: 16306 16307@example 16308date [@var{option}]@dots{} [+@var{format}] 16309date [-u|--utc|--universal] @c this avoids a newline in the output 16310[ MMDDhhmm[[CC]YY][.ss] ] 16311@end example 16312 16313The @command{date} command displays the date and time. 16314With the @option{--set} (@option{-s}) option, or with 16315@samp{MMDDhhmm[[CC]YY][.ss]}, 16316it sets the date and time. 16317 16318@vindex LC_TIME 16319Invoking @command{date} with no @var{format} argument is equivalent to invoking 16320it with a default format that depends on the @env{LC_TIME} locale category. 16321In the default C locale, this format is @samp{'+%a %b %e %H:%M:%S %Z %Y'}, 16322so the output looks like @samp{Thu Jul @ 9 17:00:00 EDT 2020}. 16323 16324@vindex TZ 16325Normally, @command{date} uses the time zone rules indicated by the 16326@env{TZ} environment variable, or the system default rules if @env{TZ} 16327is not set. @xref{TZ Variable,, Specifying the Time Zone with 16328@env{TZ}, libc, The GNU C Library Reference Manual}. 16329 16330@exitstatus 16331 16332@menu 16333* Date format specifiers:: Used in @samp{date '+...'} 16334* Setting the time:: Changing the system clock. 16335* Options for date:: Instead of the current time. 16336@detailmenu 16337* Date input formats:: Specifying date strings. 16338@end detailmenu 16339* Examples of date:: Examples. 16340@end menu 16341 16342@node Date format specifiers 16343@subsection Specifying the format of @command{date} output 16344 16345@findex strftime @r{and @command{date}} 16346@cindex time formats 16347@cindex formatting times 16348If given an argument that starts with a @samp{+}, @command{date} prints the 16349current date and time (or the date and time specified by the 16350@option{--date} option, see below) in the format defined by that argument, 16351which is similar to that of the @code{strftime} function. Except for 16352conversion specifiers, which start with @samp{%}, characters in the 16353format string are printed unchanged. The conversion specifiers are 16354described below. 16355 16356@menu 16357* Time conversion specifiers:: %[HIklMNpPrRsSTXzZ] 16358* Date conversion specifiers:: %[aAbBcCdDeFgGhjmuUVwWxyY] 16359* Literal conversion specifiers:: %[%nt] 16360* Padding and other flags:: Pad with zeros, spaces, etc. 16361@end menu 16362 16363@node Time conversion specifiers 16364@subsubsection Time conversion specifiers 16365 16366@cindex time conversion specifiers 16367@cindex conversion specifiers, time 16368 16369@command{date} conversion specifiers related to times. 16370 16371@table @samp 16372@item %H 16373hour (@samp{00}@dots{}@samp{23}) 16374@item %I 16375hour (@samp{01}@dots{}@samp{12}) 16376@item %k 16377hour, space padded (@samp{ 0}@dots{}@samp{23}); equivalent to @samp{%_H}@. 16378This is a GNU extension. 16379@item %l 16380hour, space padded (@samp{ 1}@dots{}@samp{12}); equivalent to @samp{%_I}@. 16381This is a GNU extension. 16382@item %M 16383minute (@samp{00}@dots{}@samp{59}) 16384@item %N 16385nanoseconds (@samp{000000000}@dots{}@samp{999999999}). 16386This is a GNU extension. 16387@item %p 16388locale's equivalent of either @samp{AM} or @samp{PM}; 16389blank in many locales. 16390Noon is treated as @samp{PM} and midnight as @samp{AM}. 16391@item %P 16392like @samp{%p}, except lower case. 16393This is a GNU extension. 16394@item %r 16395locale's 12-hour clock time (e.g., @samp{11:11:04 PM}) 16396@item %R 1639724-hour hour and minute. Same as @samp{%H:%M}. 16398@item %s 16399@cindex Epoch, seconds since 16400@cindex seconds since the Epoch 16401@cindex beginning of time 16402@cindex leap seconds 16403seconds since the Epoch, i.e., since 1970-01-01 00:00 UTC@. 16404Leap seconds are not counted unless leap second support is available. 16405@xref{%s-examples}, for examples. 16406This is a GNU extension. 16407@item %S 16408@cindex leap seconds 16409second (@samp{00}@dots{}@samp{60}). 16410This may be @samp{60} if leap seconds are supported. 16411@item %T 1641224-hour hour, minute, and second. Same as @samp{%H:%M:%S}. 16413@item %X 16414locale's time representation (e.g., @samp{23:13:48}) 16415@item %z 16416Four-digit numeric time zone, e.g., @samp{-0600} or @samp{+0530}, or 16417@samp{-0000} if no 16418time zone is determinable. This value reflects the numeric time zone 16419appropriate for the current time, using the time zone rules specified 16420by the @env{TZ} environment variable. A time zone is not determinable if 16421its numeric offset is zero and its abbreviation begins with @samp{-}. 16422The time (and optionally, the time zone rules) can be overridden 16423by the @option{--date} option. 16424@item %:z 16425Numeric time zone with @samp{:}, e.g., @samp{-06:00} or 16426@samp{+05:30}), or @samp{-00:00} if no time zone is determinable. 16427This is a GNU extension. 16428@item %::z 16429Numeric time zone to the nearest second with @samp{:} (e.g., 16430@samp{-06:00:00} or @samp{+05:30:00}), or @samp{-00:00:00} if no time zone is 16431determinable. 16432This is a GNU extension. 16433@item %:::z 16434Numeric time zone with @samp{:} using the minimum necessary precision 16435(e.g., @samp{-06}, @samp{+05:30}, or @samp{-04:56:02}), or @samp{-00} if 16436no time zone is determinable. 16437This is a GNU extension. 16438@item %Z 16439alphabetic time zone abbreviation (e.g., @samp{EDT}), or nothing if no 16440time zone is determinable. See @samp{%z} for how it is determined. 16441@end table 16442 16443 16444@node Date conversion specifiers 16445@subsubsection Date conversion specifiers 16446 16447@cindex date conversion specifiers 16448@cindex conversion specifiers, date 16449 16450@command{date} conversion specifiers related to dates. 16451 16452@table @samp 16453@item %a 16454locale's abbreviated weekday name (e.g., @samp{Sun}) 16455@item %A 16456locale's full weekday name, variable length (e.g., @samp{Sunday}) 16457@item %b 16458locale's abbreviated month name (e.g., @samp{Jan}) 16459@item %B 16460locale's full month name, variable length (e.g., @samp{January}) 16461@item %c 16462locale's date and time (e.g., @samp{Thu Mar @ 3 23:05:25 2020}) 16463@item %C 16464century. This is like @samp{%Y}, except the last two digits are omitted. 16465For example, it is @samp{20} if @samp{%Y} is @samp{2019}, 16466and is @samp{-0} if @samp{%Y} is @samp{-001}. 16467It is normally at least two characters, but it may be more. 16468@item %d 16469day of month (e.g., @samp{01}) 16470@item %D 16471date; same as @samp{%m/%d/%y} 16472@item %e 16473day of month, space padded; same as @samp{%_d} 16474@item %F 16475full date in ISO 8601 format; like @samp{%+4Y-%m-%d} 16476except that any flags or field width override the @samp{+} 16477and (after subtracting 6) the @samp{4}. 16478This is a good choice for a date format, as it is standard and 16479is easy to sort in the usual case where years are in the range 164800000@dots{}9999. 16481@item %g 16482year corresponding to the ISO week number, but without the century 16483(range @samp{00} through @samp{99}). This has the same format and value 16484as @samp{%y}, except that if the ISO week number (see 16485@samp{%V}) belongs 16486to the previous or next year, that year is used instead. 16487@item %G 16488year corresponding to the ISO week number. This has the 16489same format and value as @samp{%Y}, except that if the ISO 16490week number (see 16491@samp{%V}) belongs to the previous or next year, that year is used 16492instead. 16493It is normally useful only if @samp{%V} is also used; 16494for example, the format @samp{%G-%m-%d} is probably a mistake, 16495since it combines the ISO week number year with the conventional month and day. 16496@item %h 16497same as @samp{%b} 16498@item %j 16499day of year (@samp{001}@dots{}@samp{366}) 16500@item %m 16501month (@samp{01}@dots{}@samp{12}) 16502@item %q 16503quarter of year (@samp{1}@dots{}@samp{4}) 16504@item %u 16505day of week (@samp{1}@dots{}@samp{7}) with @samp{1} corresponding to Monday 16506@item %U 16507week number of year, with Sunday as the first day of the week 16508(@samp{00}@dots{}@samp{53}). 16509Days in a new year preceding the first Sunday are in week zero. 16510@item %V 16511ISO week number, that is, the 16512week number of year, with Monday as the first day of the week 16513(@samp{01}@dots{}@samp{53}). 16514If the week containing January 1 has four or more days in 16515the new year, then it is considered week 1; otherwise, it is week 53 of 16516the previous year, and the next week is week 1. (See the ISO 8601 16517standard.) 16518@item %w 16519day of week (@samp{0}@dots{}@samp{6}) with 0 corresponding to Sunday 16520@item %W 16521week number of year, with Monday as first day of week 16522(@samp{00}@dots{}@samp{53}). 16523Days in a new year preceding the first Monday are in week zero. 16524@item %x 16525locale's date representation (e.g., @samp{12/31/99}) 16526@item %y 16527last two digits of year (@samp{00}@dots{}@samp{99}) 16528@item %Y 16529year. This is normally at least four characters, but it may be more. 16530Year @samp{0000} precedes year @samp{0001}, and year @samp{-001} 16531precedes year @samp{0000}. 16532@end table 16533 16534 16535@node Literal conversion specifiers 16536@subsubsection Literal conversion specifiers 16537 16538@cindex literal conversion specifiers 16539@cindex conversion specifiers, literal 16540 16541@command{date} conversion specifiers that produce literal strings. 16542 16543@table @samp 16544@item %% 16545a literal % 16546@item %n 16547a newline 16548@item %t 16549a horizontal tab 16550@end table 16551 16552 16553@node Padding and other flags 16554@subsubsection Padding and other flags 16555 16556@cindex numeric field padding 16557@cindex padding of numeric fields 16558@cindex fields, padding numeric 16559 16560Unless otherwise specified, @command{date} normally pads numeric fields 16561with zeros, so that, for 16562example, numeric months are always output as two digits. 16563Most numeric fields are padded on the left. 16564However, nanoseconds are padded on the right since they are commonly 16565used after decimal points in formats like @samp{%s.%-N}. 16566Also, seconds since the Epoch are not padded 16567since there is no natural width for them. 16568 16569The following optional flags can appear after the @samp{%}: 16570 16571@table @samp 16572@item - 16573(hyphen) Do not pad the field; useful if the output is intended for 16574human consumption. 16575This is a GNU extension. 16576As a special case, @samp{%-N} outputs only enough trailing digits to 16577not lose information, assuming that the timestamp's resolution is the 16578same as the current hardware clock. For example, if the hardware 16579clock resolution is 1 microsecond, @samp{%s.%-N} outputs something 16580like @samp{1640890100.395710}. 16581 16582@item _ 16583(underscore) Pad with spaces; useful if you need a fixed 16584number of characters in the output, but zeros are too distracting. 16585This is a GNU extension. 16586@item 0 16587(zero) Pad with zeros even if the conversion specifier 16588would normally pad with spaces. 16589@item + 16590Pad with zeros, like @samp{0}. In addition, precede any year number 16591with @samp{+} if it exceeds 9999 or if its field width exceeds 4; 16592similarly, precede any century number with @samp{+} if it exceeds 99 16593or if its field width exceeds 2. This supports ISO 8601 formats 16594for dates far in the future; for example, the command @code{date 16595--date=12019-02-25 +%+13F} outputs the string @samp{+012019-02-25}. 16596@item ^ 16597Use upper case characters if possible. 16598This is a GNU extension. 16599@item # 16600Use opposite case characters if possible. 16601A field that is normally upper case becomes lower case, and vice versa. 16602This is a GNU extension. 16603@end table 16604 16605@noindent 16606Here are some examples of padding: 16607 16608@example 16609date +%d/%m -d "Feb 1" 16610@result{} 01/02 16611date +%-d/%-m -d "Feb 1" 16612@result{} 1/2 16613date +%_d/%_m -d "Feb 1" 16614@result{} 1/ 2 16615@end example 16616 16617You can optionally specify the field width 16618(after any flag, if present) as a decimal number. If the natural size of the 16619output of the field has less than the specified number of characters, 16620the result is normally written right adjusted and padded to the given 16621size. For example, @samp{%9B} prints the right adjusted month name in 16622a field of width 9. Nanoseconds are left adjusted, and are truncated 16623or padded to the field width. 16624 16625An optional modifier can follow the optional flag and width 16626specification. The modifiers are: 16627 16628@table @samp 16629@item E 16630Use the locale's alternate representation for date and time. This 16631modifier applies to the @samp{%c}, @samp{%C}, @samp{%x}, @samp{%X}, 16632@samp{%y} and @samp{%Y} conversion specifiers. In a Japanese locale, for 16633example, @samp{%Ex} might yield a date format based on the Japanese 16634Emperors' reigns. 16635 16636@item O 16637Use the locale's alternate numeric symbols for numbers. This modifier 16638applies only to numeric conversion specifiers. 16639@end table 16640 16641If the format supports the modifier but no alternate representation 16642is available, it is ignored. 16643 16644POSIX specifies the behavior of flags and field widths only for 16645@samp{%C}, @samp{%F}, @samp{%G}, and @samp{%Y} (all without 16646modifiers), and requires a flag to be present if and only if a field 16647width is also present. Other combinations of flags, field widths and 16648modifiers are GNU extensions. 16649 16650 16651@node Setting the time 16652@subsection Setting the time 16653 16654@cindex setting the time 16655@cindex time setting 16656@cindex appropriate privileges 16657 16658You must have appropriate privileges to set the 16659system clock. For changes to persist across a reboot, the 16660hardware clock may need to be updated from the system clock, which 16661might not happen automatically on your system. 16662 16663To set the clock, you can use the @option{--set} (@option{-s}) option 16664(@pxref{Options for date}). To set the clock without using GNU 16665extensions, you can give @command{date} an argument of the form 16666@samp{MMDDhhmm[[CC]YY][.ss]} where each two-letter 16667component stands for two digits with the following meanings: 16668 16669@table @var 16670@item MM 16671month 16672@item DD 16673day within month 16674@item hh 16675hour 16676@item mm 16677minute 16678@item CC 16679first two digits of year (optional) 16680@item YY 16681last two digits of year (optional) 16682@item ss 16683second (optional) 16684@end table 16685 16686Note, the @option{--date} and @option{--set} options may not be used with an 16687argument in the above format. The @option{--universal} option may be used 16688with such an argument to indicate that the specified date and time are 16689relative to Universal Time rather than to the local time zone. 16690 16691 16692@node Options for date 16693@subsection Options for @command{date} 16694 16695@cindex @command{date} options 16696@cindex options for @command{date} 16697 16698The program accepts the following options. Also see @ref{Common options}. 16699Except for @option{-u}, these options are all GNU extensions to POSIX. 16700 16701All options that specify the date to display are mutually exclusive. 16702I.e.: @option{--date}, @option{--file}, @option{--reference}, 16703@option{--resolution}. 16704 16705@table @samp 16706 16707@item -d @var{datestr} 16708@itemx --date=@var{datestr} 16709@opindex -d 16710@opindex --date 16711@cindex parsing date strings 16712@cindex date strings, parsing 16713@cindex arbitrary date strings, parsing 16714@opindex yesterday 16715@opindex tomorrow 16716@opindex next @var{day} 16717@opindex last @var{day} 16718Display the date and time specified in @var{datestr} instead of the 16719current date and time. @var{datestr} can be in almost any common 16720format. It can contain month names, time zones, @samp{am} and @samp{pm}, 16721@samp{yesterday}, etc. For example, @option{--date="2020-07-21 1672214:19:13.489392193 +0530"} specifies the instant of time that is 16723489,392,193 nanoseconds after July 21, 2020 at 2:19:13 PM in a 16724time zone that is 5 hours and 30 minutes east of UTC.@* 16725Note: input currently must be in locale independent format. E.g., the 16726LC_TIME=C below is needed to print back the correct date in many locales: 16727@example 16728date -d "$(LC_TIME=C date)" 16729@end example 16730@xref{Date input formats}. 16731 16732@item --debug 16733@opindex --debug 16734@cindex debugging date strings 16735@cindex date strings, debugging 16736@cindex arbitrary date strings, debugging 16737Annotate the parsed date, display the effective time zone, and warn about 16738potential misuse. 16739 16740@item -f @var{datefile} 16741@itemx --file=@var{datefile} 16742@opindex -f 16743@opindex --file 16744Parse each line in @var{datefile} as with @option{-d} and display the 16745resulting date and time. If @var{datefile} is @samp{-}, use standard 16746input. This is useful when you have many dates to process, because the 16747system overhead of starting up the @command{date} executable many times can 16748be considerable. 16749 16750@item -I[@var{timespec}] 16751@itemx --iso-8601[=@var{timespec}] 16752@opindex -I[@var{timespec}] 16753@opindex --iso-8601[=@var{timespec}] 16754Display the date using an ISO 8601 format, @samp{%Y-%m-%d}. 16755 16756The argument @var{timespec} specifies the number of additional 16757terms of the time to include. It can be one of the following: 16758@table @samp 16759@item auto 16760Print just the date. This is the default if @var{timespec} is omitted. 16761This is like the format @code{%Y-%m-%d}. 16762 16763@item hours 16764Also print hours and time zone. 16765This is like the format @code{%Y-%m-%dT%H%:z}. 16766 16767@item minutes 16768Also print minutes. 16769This is like the format @code{%Y-%m-%dT%H:%M%:z}. 16770 16771@item seconds 16772Also print seconds. 16773This is like the format @code{%Y-%m-%dT%H:%M:%S%:z}. 16774 16775@item ns 16776Also print nanoseconds. 16777This is like the format @code{%Y-%m-%dT%H:%M:%S,%N%:z}. 16778@end table 16779 16780@macro dateParseNote 16781This format is always suitable as input 16782for the @option{--date} (@option{-d}) and @option{--file} 16783(@option{-f}) options, regardless of the current locale. 16784@end macro 16785@dateParseNote 16786 16787@item -r @var{file} 16788@itemx --reference=@var{file} 16789@opindex -r 16790@opindex --reference 16791Display the date and time of the last modification of @var{file}, 16792instead of the current date and time. 16793 16794@item --resolution 16795@opindex --resolution 16796Display the timestamp resolution instead of the time. 16797Current clock timestamps that are output by @command{date} 16798are integer multiples of the timestamp resolution. 16799With this option, the format defaults to @samp{%s.%N}. 16800For example, if the clock resolution is 1 millisecond, 16801the output is: 16802 16803@example 168040.001000000 16805@end example 16806 16807@item -R 16808@itemx --rfc-email 16809@opindex -R 16810@opindex --rfc-email 16811Display the date and time using the format @samp{%a, %d %b %Y %H:%M:%S 16812%z}, evaluated in the C locale so abbreviations are always in English. 16813For example: 16814 16815@example 16816Mon, 09 Jul 2020 17:00:00 -0400 16817@end example 16818 16819@opindex --rfc-822 16820@opindex --rfc-2822 16821This format conforms to Internet RFCs 16822@uref{https://datatracker.ietf.org/doc/rfc5322/, 5322}, 16823@uref{https://datatracker.ietf.org/doc/rfc2822/, 2822} and 16824@uref{https://datatracker.ietf.org/doc/rfc822/, 822}, the 16825current and previous standards for Internet email. 16826For compatibility with older versions of @command{date}, 16827@option{--rfc-2822} and @option{--rfc-822} are aliases for 16828@option{--rfc-email}. 16829 16830@item --rfc-3339=@var{timespec} 16831@opindex --rfc-3339=@var{timespec} 16832Display the date using a format specified by 16833@uref{https://datatracker.ietf.org/doc/rfc3339/, Internet 16834RFC 3339}. This is like @option{--iso-8601}, except that a space rather 16835than a @samp{T} separates dates from times, and a period rather than 16836a comma separates seconds from subseconds. 16837@dateParseNote 16838 16839The argument @var{timespec} specifies how much of the time to include. 16840It can be one of the following: 16841 16842@table @samp 16843@item date 16844Print just the full-date, e.g., @samp{2020-07-21}. 16845This is like the format @samp{%Y-%m-%d}. 16846 16847@item seconds 16848Print the full-date and full-time separated by a space, e.g., 16849@samp{2020-07-21 04:30:37+05:30}. The output ends with a numeric 16850time-offset; here the @samp{+05:30} means that local time is five 16851hours and thirty minutes east of UTC@. This is like 16852the format @samp{%Y-%m-%d %H:%M:%S%:z}. 16853 16854@item ns 16855Like @samp{seconds}, but also print nanoseconds, e.g., 16856@samp{2020-07-21 04:30:37.998458565+05:30}. 16857This is like the format @samp{%Y-%m-%d %H:%M:%S.%N%:z}. 16858 16859@end table 16860 16861@item -s @var{datestr} 16862@itemx --set=@var{datestr} 16863@opindex -s 16864@opindex --set 16865Set the date and time to @var{datestr}. See @option{-d} above. 16866See also @ref{Setting the time}. 16867 16868@item -u 16869@itemx --utc 16870@itemx --universal 16871@opindex -u 16872@opindex --utc 16873@opindex --universal 16874@cindex Coordinated Universal Time 16875@cindex UTC 16876@cindex Greenwich Mean Time 16877@cindex GMT 16878@cindex leap seconds 16879@vindex TZ 16880@cindex Universal Time 16881Use Universal Time by operating as if the 16882@env{TZ} environment variable were set to the string @samp{UTC0}. 16883UTC stands for Coordinated Universal Time, established in 1960. 16884Universal Time is often called ``Greenwich Mean Time'' (GMT) for 16885historical reasons. 16886Typically, systems ignore leap seconds and thus implement an 16887approximation to UTC rather than true UTC. 16888@end table 16889 16890 16891@node Examples of date 16892@subsection Examples of @command{date} 16893 16894@cindex examples of @command{date} 16895 16896Here are a few examples. Also see the documentation for the @option{-d} 16897option in the previous section. 16898 16899@itemize @bullet 16900 16901@item 16902To print the date of the day before yesterday: 16903 16904@example 16905date --date='2 days ago' 16906@end example 16907 16908@item 16909To print the date of the day three months and one day hence: 16910 16911@example 16912date --date='3 months 1 day' 16913@end example 16914 16915@item 16916To print the day of year of Christmas in the current year: 16917 16918@example 16919date --date='25 Dec' +%j 16920@end example 16921 16922@item 16923To print the current full month name and the day of the month: 16924 16925@example 16926date '+%B %d' 16927@end example 16928 16929But this may not be what you want because for the first nine days of 16930the month, the @samp{%d} expands to a zero-padded two-digit field, 16931for example @samp{date -d 1may '+%B %d'} will print @samp{May 01}. 16932 16933@item 16934To print a date without the leading zero for one-digit days 16935of the month, you can use the (GNU extension) 16936@samp{-} flag to suppress 16937the padding altogether: 16938 16939@example 16940date -d 1may '+%B %-d' 16941@end example 16942 16943@item 16944To print the current date and time in the format required by many 16945non-GNU versions of @command{date} when setting the system clock: 16946 16947@example 16948date +%m%d%H%M%Y.%S 16949@end example 16950 16951@item 16952To set the system clock forward by two minutes: 16953 16954@example 16955date --set='+2 minutes' 16956@end example 16957 16958@item 16959To print the date in Internet RFC 5322 format, 16960use @samp{date --rfc-email}. Here is some example output: 16961 16962@example 16963Tue, 09 Jul 2020 19:00:37 -0400 16964@end example 16965 16966@anchor{%s-examples} 16967@item 16968To convert a date string to the number of seconds since the Epoch 16969(which is 1970-01-01 00:00 UTC), use the @option{--date} option with 16970the @samp{%s} format. That can be useful in sorting and/or graphing 16971and/or comparing data by date. The following command outputs the 16972number of the seconds since the Epoch for the time two minutes after the 16973Epoch: 16974 16975@example 16976date --date='1970-01-01 00:02:00 +0000' +%s 16977120 16978@end example 16979 16980To convert a date string from one time zone @var{from} to another @var{to}, 16981specify @samp{TZ="@var{from}"} in the environment and @samp{TZ="@var{to}"} 16982in the @option{--date} option. @xref{Specifying time zone rules}. 16983For example: 16984 16985@smallexample 16986TZ="Asia/Tokyo" date --date='TZ="America/New_York" 2023-05-07 12:23' 16987Mon May @ 8 01:23:00 JST 2023 16988@end smallexample 16989 16990If you do not specify time zone information in the date string, 16991@command{date} uses your computer's idea of the time zone when 16992interpreting the string. For example, if your computer's time zone is 16993that of Cambridge, Massachusetts, which was then 5 hours (i.e., 18,000 16994seconds) behind UTC: 16995 16996@example 16997# local time zone used 16998date --date='1970-01-01 00:02:00' +%s 1699918120 17000@end example 17001 17002@item 17003If you're sorting or graphing dated data, your raw date values may be 17004represented as seconds since the Epoch. But few people can look at 17005the date @samp{1577836800} and casually note ``Oh, that's the first 17006second of the year 2020 in Greenwich, England.'' 17007 17008@example 17009date --date='2020-01-01 UTC' +%s 170101577836800 17011@end example 17012 17013An alternative is to use the @option{--utc} (@option{-u}) option. 17014Then you may omit @samp{UTC} from the date string. Although this 17015produces the same result for @samp{%s} and many other format sequences, 17016with a time zone offset different from zero, it would give a different 17017result for zone-dependent formats like @samp{%z}. 17018 17019@example 17020date -u --date=2020-07-21 +%s 170211595289600 17022@end example 17023 17024To convert such an unwieldy number of seconds back to 17025a more readable form, use a command like this: 17026 17027@example 17028date -d @@1595289600 +"%F %T %z" 170292020-07-20 20:00:00 -0400 17030@end example 17031 17032Often it is better to output UTC-relative date and time: 17033 17034@example 17035date -u -d @@1595289600 +"%F %T %z" 170362020-07-21 00:00:00 +0000 17037@end example 17038 17039@item 17040@cindex leap seconds 17041Typically the seconds count omits leap seconds, but some systems are 17042exceptions. Because leap seconds are not predictable, the mapping 17043between the seconds count and a future timestamp is not reliable on 17044the atypical systems that include leap seconds in their counts. 17045 17046Here is how the two kinds of systems handle the leap second at 17047the end of the year 2016: 17048 17049@example 17050# Typical systems ignore leap seconds: 17051date --date='2016-12-31 23:59:59 +0000' +%s 170521483228799 17053date --date='2016-12-31 23:59:60 +0000' +%s 17054date: invalid date '2016-12-31 23:59:60 +0000' 17055date --date='2017-01-01 00:00:00 +0000' +%s 170561483228800 17057@end example 17058 17059@example 17060# Atypical systems count leap seconds: 17061date --date='2016-12-31 23:59:59 +0000' +%s 170621483228825 17063date --date='2016-12-31 23:59:60 +0000' +%s 170641483228826 17065date --date='2017-01-01 00:00:00 +0000' +%s 170661483228827 17067@end example 17068 17069@end itemize 17070 17071 17072@node arch invocation 17073@section @command{arch}: Print machine hardware name 17074 17075@pindex arch 17076@cindex print machine hardware name 17077@cindex system information, printing 17078 17079@command{arch} prints the machine hardware name, 17080and is equivalent to @samp{uname -m}. 17081Synopsis: 17082 17083@example 17084arch [@var{option}] 17085@end example 17086 17087The program accepts the @ref{Common options} only. 17088 17089@command{arch} is not installed by default, so portable scripts should 17090not rely on its existence. 17091 17092@exitstatus 17093 17094 17095@node nproc invocation 17096@section @command{nproc}: Print the number of available processors 17097 17098@pindex nproc 17099@cindex Print the number of processors 17100@cindex system information, printing 17101 17102Print the number of processing units available to the current process, 17103which may be less than the number of online processors. 17104If this information is not accessible, then print the number of 17105processors installed. If the @env{OMP_NUM_THREADS} or @env{OMP_THREAD_LIMIT} 17106environment variables are set, then they will determine the minimum 17107and maximum returned value respectively. The result is guaranteed to be 17108greater than zero. Synopsis: 17109 17110@example 17111nproc [@var{option}] 17112@end example 17113 17114The program accepts the following options. Also see @ref{Common options}. 17115 17116@table @samp 17117 17118@item --all 17119@opindex --all 17120Print the number of installed processors on the system, which may 17121be greater than the number online or available to the current process. 17122The @env{OMP_NUM_THREADS} or @env{OMP_THREAD_LIMIT} environment variables 17123are not honored in this case. 17124 17125@item --ignore=@var{number} 17126@opindex --ignore 17127If possible, exclude this @var{number} of processing units. 17128 17129@end table 17130 17131@exitstatus 17132 17133 17134@node uname invocation 17135@section @command{uname}: Print system information 17136 17137@pindex uname 17138@cindex print system information 17139@cindex system information, printing 17140 17141@command{uname} prints information about the machine and operating system 17142it is run on. If no options are given, @command{uname} acts as if the 17143@option{-s} option were given. Synopsis: 17144 17145@example 17146uname [@var{option}]@dots{} 17147@end example 17148 17149If multiple options or @option{-a} are given, the selected information is 17150printed in this order: 17151 17152@example 17153@var{kernel-name} @var{nodename} @var{kernel-release} @var{kernel-version} 17154@var{machine} @var{processor} @var{hardware-platform} @var{operating-system} 17155@end example 17156 17157The information may contain internal spaces, so such output cannot be 17158parsed reliably. In the following example, @var{kernel-version} is 17159@samp{#1 SMP Fri Jul 17 17:18:38 UTC 2020}: 17160 17161@example 17162uname -a 17163@result{} Linux dumdum.example.org 5.9.16-200.fc33.x86_64@c 17164 #1 SMP Mon Dec 21 14:08:22 UTC 2020 x86_64 x86_64 x86_64 GNU/Linux 17165@end example 17166 17167 17168The program accepts the following options. Also see @ref{Common options}. 17169 17170@table @samp 17171 17172@item -a 17173@itemx --all 17174@opindex -a 17175@opindex --all 17176Print all of the below information, except omit the processor type 17177and the hardware platform name if they are unknown. 17178 17179@item -i 17180@itemx --hardware-platform 17181@opindex -i 17182@opindex --hardware-platform 17183@cindex implementation, hardware 17184@cindex hardware platform 17185@cindex platform, hardware 17186Print the hardware platform name 17187(sometimes called the hardware implementation). 17188Print @samp{unknown} if this information is not available. 17189Note this is non-portable (even across GNU/Linux distributions). 17190 17191@item -m 17192@itemx --machine 17193@opindex -m 17194@opindex --machine 17195@cindex machine type 17196@cindex hardware class 17197@cindex hardware type 17198Print the machine hardware name (sometimes called the hardware class 17199or hardware type). 17200 17201@item -n 17202@itemx --nodename 17203@opindex -n 17204@opindex --nodename 17205@cindex hostname 17206@cindex node name 17207@cindex network node name 17208Print the network node hostname. 17209 17210@item -p 17211@itemx --processor 17212@opindex -p 17213@opindex --processor 17214@cindex host processor type 17215Print the processor type (sometimes called the instruction set 17216architecture or ISA). 17217Print @samp{unknown} if this information is not available. 17218Note this is non-portable (even across GNU/Linux distributions). 17219 17220@item -o 17221@itemx --operating-system 17222@opindex -o 17223@opindex --operating-system 17224@cindex operating system name 17225Print the name of the operating system. 17226 17227@item -r 17228@itemx --kernel-release 17229@opindex -r 17230@opindex --kernel-release 17231@cindex kernel release 17232@cindex release of kernel 17233Print the kernel release. 17234 17235@item -s 17236@itemx --kernel-name 17237@opindex -s 17238@opindex --kernel-name 17239@cindex kernel name 17240@cindex name of kernel 17241Print the kernel name. 17242POSIX 1003.1-2001 (@pxref{Standards conformance}) calls this 17243``the implementation of the operating system'', because the 17244POSIX specification itself has no notion of ``kernel''. 17245The kernel name might be the same as the operating system name printed 17246by the @option{-o} or @option{--operating-system} option, but it might 17247differ. Some operating systems (e.g., FreeBSD, HP-UX) have the same 17248name as their underlying kernels; others (e.g., GNU/Linux, Solaris) 17249do not. 17250 17251@item -v 17252@itemx --kernel-version 17253@opindex -v 17254@opindex --kernel-version 17255@cindex kernel version 17256@cindex version of kernel 17257Print the kernel version. 17258 17259@end table 17260 17261@exitstatus 17262 17263 17264@node hostname invocation 17265@section @command{hostname}: Print or set system name 17266 17267@pindex hostname 17268@cindex setting the hostname 17269@cindex printing the hostname 17270@cindex system name, printing 17271@cindex appropriate privileges 17272 17273With no arguments, @command{hostname} prints the name of the current host 17274system. With one argument, it sets the current host name to the 17275specified string. You must have appropriate privileges to set the host 17276name. Synopsis: 17277 17278@example 17279hostname [@var{name}] 17280@end example 17281 17282The only options are @option{--help} and @option{--version}. @xref{Common 17283options}. 17284 17285@command{hostname} is not installed by default, and other packages 17286also supply a @command{hostname} command, so portable scripts should 17287not rely on its existence or on the exact behavior documented above. 17288 17289@exitstatus 17290 17291 17292@node hostid invocation 17293@section @command{hostid}: Print numeric host identifier 17294 17295@pindex hostid 17296@cindex printing the host identifier 17297 17298@command{hostid} prints the numeric identifier of the current host 17299in hexadecimal. This command accepts no arguments. 17300The only options are @option{--help} and @option{--version}. 17301@xref{Common options}. 17302 17303For example, here's what it prints on one system I use: 17304 17305@example 17306$ hostid 173071bac013d 17308@end example 17309 17310On that system, the 32-bit quantity happens to be closely 17311related to the system's Internet address, but that isn't always 17312the case. 17313 17314@command{hostid} is installed only on systems that have the 17315@code{gethostid} function, so portable scripts should not rely on its 17316existence. 17317 17318@exitstatus 17319 17320@node uptime invocation 17321@section @command{uptime}: Print system uptime and load 17322 17323@pindex uptime 17324@cindex printing the system uptime and load 17325 17326@command{uptime} prints the current time, the system's uptime, the 17327number of logged-in users and the current load average. 17328 17329If an argument is specified, it is used as the file to be read 17330to discover how many users are logged in. If no argument is 17331specified, a system default is used (@command{uptime --help} indicates 17332the default setting). 17333 17334The only options are @option{--help} and @option{--version}. 17335@xref{Common options}. 17336 17337For example, here's what it prints right now on one system I use: 17338 17339@example 17340$ uptime 17341 14:07 up 3:35, 3 users, load average: 1.39, 1.15, 1.04 17342@end example 17343 17344The precise method of calculation of load average varies somewhat 17345between systems. Some systems calculate it as the average number of 17346runnable processes over the last 1, 5 and 15 minutes, but some systems 17347also include processes in the uninterruptible sleep state (that is, 17348those processes which are waiting for device I/O). The Linux kernel 17349includes uninterruptible processes. 17350 17351@command{uptime} is installed only on platforms with infrastructure 17352for obtaining the boot time, and other packages also supply an 17353@command{uptime} command, so portable scripts should not rely on its 17354existence or on the exact behavior documented above. 17355 17356@exitstatus 17357 17358@node SELinux context 17359@chapter SELinux context 17360 17361@cindex SELinux context 17362@cindex SELinux, context 17363@cindex commands for SELinux context 17364 17365This section describes commands for operations with SELinux 17366contexts. 17367 17368@menu 17369* chcon invocation:: Change SELinux context of file 17370* runcon invocation:: Run a command in specified SELinux context 17371@end menu 17372 17373@node chcon invocation 17374@section @command{chcon}: Change SELinux context of file 17375 17376@pindex chcon 17377@cindex changing security context 17378@cindex change SELinux context 17379 17380@command{chcon} changes the SELinux security context of the selected files. 17381Synopses: 17382 17383@example 17384chcon [@var{option}]@dots{} @var{context} @var{file}@dots{} 17385chcon [@var{option}]@dots{} [-u @var{user}] [-r @var{role}] [-l @var{range}]@c 17386 [-t @var{type}] @var{file}@dots{} 17387chcon [@var{option}]@dots{} --reference=@var{rfile} @var{file}@dots{} 17388@end example 17389 17390Change the SELinux security context of each @var{file} to @var{context}. 17391With @option{--reference}, change the security context of each @var{file} 17392to that of @var{rfile}. 17393 17394The program accepts the following options. Also see @ref{Common options}. 17395 17396@table @samp 17397 17398@item --dereference 17399@opindex --dereference 17400Do not affect symbolic links but what they refer to; this is the default. 17401 17402@item -h 17403@itemx --no-dereference 17404@opindex -h 17405@opindex --no-dereference 17406@cindex no dereference 17407Affect the symbolic links themselves instead of any referenced file. 17408 17409@item --reference=@var{rfile} 17410@opindex --reference 17411@cindex reference file 17412Use @var{rfile}'s security context rather than specifying a @var{context} value. 17413 17414@item -R 17415@itemx --recursive 17416@opindex -R 17417@opindex --recursive 17418Operate on files and directories recursively. 17419 17420@item --preserve-root 17421@opindex --preserve-root 17422Refuse to operate recursively on the root directory, @file{/}, 17423when used together with the @option{--recursive} option. 17424@xref{Treating / specially}. 17425 17426@item --no-preserve-root 17427@opindex --no-preserve-root 17428Do not treat the root directory, @file{/}, specially when operating 17429recursively; this is the default. 17430@xref{Treating / specially}. 17431 17432@choptH 17433@xref{Traversing symlinks}. 17434 17435@choptL 17436@xref{Traversing symlinks}. 17437 17438@choptP 17439@xref{Traversing symlinks}. 17440 17441@item -v 17442@itemx --verbose 17443@opindex -v 17444@opindex --verbose 17445@cindex diagnostic 17446Output a diagnostic for every file processed. 17447 17448@item -u @var{user} 17449@itemx --user=@var{user} 17450@opindex -u 17451@opindex --user 17452Set user @var{user} in the target security context. 17453 17454@item -r @var{role} 17455@itemx --role=@var{role} 17456@opindex -r 17457@opindex --role 17458Set role @var{role} in the target security context. 17459 17460@item -t @var{type} 17461@itemx --type=@var{type} 17462@opindex -t 17463@opindex --type 17464Set type @var{type} in the target security context. 17465 17466@item -l @var{range} 17467@itemx --range=@var{range} 17468@opindex -l 17469@opindex --range 17470Set range @var{range} in the target security context. 17471 17472@end table 17473 17474@exitstatus 17475 17476@node runcon invocation 17477@section @command{runcon}: Run a command in specified SELinux context 17478 17479@pindex runcon 17480@cindex run with security context 17481 17482 17483@command{runcon} runs file in specified SELinux security context. 17484 17485Synopses: 17486@example 17487runcon @var{context} @var{command} [@var{args}] 17488runcon [ -c ] [-u @var{user}] [-r @var{role}] [-t @var{type}]@c 17489 [-l @var{range}] @var{command} [@var{args}] 17490@end example 17491 17492Run @var{command} with completely-specified @var{context}, or with 17493current or transitioned security context modified by one or more of @var{level}, 17494@var{role}, @var{type} and @var{user}. 17495 17496If none of @option{-c}, @option{-t}, @option{-u}, @option{-r}, or @option{-l} 17497is specified, the first argument is used as the complete context. 17498Any additional arguments after @var{command} 17499are interpreted as arguments to the command. 17500 17501With neither @var{context} nor @var{command}, print the current 17502security context. 17503 17504@cindex restricted security context 17505@cindex NO_NEW_PRIVS 17506Note also the @command{setpriv} command which can be used to set the 17507NO_NEW_PRIVS bit using @command{setpriv --no-new-privs runcon ...}, 17508thus disallowing usage of a security context with more privileges 17509than the process would normally have. 17510 17511@command{runcon} accepts the following options. Also see @ref{Common options}. 17512 17513@table @samp 17514 17515@item -c 17516@itemx --compute 17517@opindex -c 17518@opindex --compute 17519Compute process transition context before modifying. 17520 17521@item -u @var{user} 17522@itemx --user=@var{user} 17523@opindex -u 17524@opindex --user 17525Set user @var{user} in the target security context. 17526 17527@item -r @var{role} 17528@itemx --role=@var{role} 17529@opindex -r 17530@opindex --role 17531Set role @var{role} in the target security context. 17532 17533@item -t @var{type} 17534@itemx --type=@var{type} 17535@opindex -t 17536@opindex --type 17537Set type @var{type} in the target security context. 17538 17539@item -l @var{range} 17540@itemx --range=@var{range} 17541@opindex -l 17542@opindex --range 17543Set range @var{range} in the target security context. 17544 17545@end table 17546 17547@cindex exit status of @command{runcon} 17548Exit status: 17549 17550@display 17551125 if @command{runcon} itself fails 17552126 if @var{command} is found but cannot be invoked 17553127 if @var{command} cannot be found 17554the exit status of @var{command} otherwise 17555@end display 17556 17557@node Modified command invocation 17558@chapter Modified command invocation 17559 17560@cindex modified command invocation 17561@cindex invocation of commands, modified 17562@cindex commands for invoking other commands 17563 17564This section describes commands that run other commands in some context 17565different than the current one: a modified environment, as a different 17566user, etc. 17567 17568@menu 17569* chroot invocation:: Modify the root directory. 17570* env invocation:: Modify environment variables. 17571* nice invocation:: Modify niceness. 17572* nohup invocation:: Immunize to hangups. 17573* stdbuf invocation:: Modify buffering of standard streams. 17574* timeout invocation:: Run with time limit. 17575@end menu 17576 17577 17578@node chroot invocation 17579@section @command{chroot}: Run a command with a different root directory 17580 17581@pindex chroot 17582@cindex running a program in a specified root directory 17583@cindex root directory, running a program in a specified 17584 17585@command{chroot} runs a command with a specified root directory. 17586On many systems, only the super-user can do this.@footnote{However, 17587some systems (e.g., FreeBSD) can be configured to allow certain regular 17588users to use the @code{chroot} system call, and hence to run this program. 17589Also, on Cygwin, anyone can run the @command{chroot} command, because the 17590underlying function is non-privileged due to lack of support in MS-Windows. 17591Furthermore, the @command{chroot} command avoids the @code{chroot} system call 17592when @var{newroot} is identical to the old @file{/} directory for consistency 17593with systems where this is allowed for non-privileged users.}. 17594Synopses: 17595 17596@example 17597chroot @var{option} @var{newroot} [@var{command} [@var{args}]@dots{}] 17598chroot @var{option} 17599@end example 17600 17601Ordinarily, file names are looked up starting at the root of the 17602directory structure, i.e., @file{/}. @command{chroot} changes the root to 17603the directory @var{newroot} (which must exist), then changes the working 17604directory to @file{/}, and finally runs @var{command} with optional @var{args}. 17605If @var{command} is not specified, the default is the value of the @env{SHELL} 17606environment variable or @command{/bin/sh} if not set, invoked with the 17607@option{-i} option. 17608@var{command} must not be a special built-in utility 17609(@pxref{Special built-in utilities}). 17610 17611The program accepts the following options. Also see @ref{Common options}. 17612Options must precede operands. 17613 17614@table @samp 17615 17616@item --groups=@var{groups} 17617@opindex --groups 17618Use this option to override the supplementary @var{groups} to be 17619used by the new process. 17620The items in the list (names or numeric IDs) must be separated by commas. 17621Use @samp{--groups=''} to disable the supplementary group look-up 17622implicit in the @option{--userspec} option. 17623 17624@item --userspec=@var{user}[:@var{group}] 17625@opindex --userspec 17626By default, @var{command} is run with the same credentials 17627as the invoking process. 17628Use this option to run it as a different @var{user} and/or with a 17629different primary @var{group}. 17630If a @var{user} is specified then the supplementary groups 17631are set according to the system defined list for that user, 17632unless overridden with the @option{--groups} option. 17633 17634@item --skip-chdir 17635@opindex --skip-chdir 17636Use this option to not change the working directory to @file{/} after changing 17637the root directory to @var{newroot}, i.e., inside the chroot. 17638This option is only permitted when @var{newroot} is the old @file{/} directory, 17639and therefore is mostly useful together with the @option{--groups} and 17640@option{--userspec} options to retain the previous working directory. 17641 17642@end table 17643 17644The user and group name look-up performed by the @option{--userspec} 17645and @option{--groups} options, is done both outside and inside 17646the chroot, with successful look-ups inside the chroot taking precedence. 17647If the specified user or group items are intended to represent a numeric ID, 17648then a name to ID resolving step is avoided by specifying a leading @samp{+}. 17649@xref{Disambiguating names and IDs}. 17650 17651Here are a few tips to help avoid common problems in using chroot. 17652To start with a simple example, make @var{command} refer to a statically 17653linked binary. If you were to use a dynamically linked executable, then 17654you'd have to arrange to have the shared libraries in the right place under 17655your new root directory. 17656 17657For example, if you create a statically linked @command{ls} executable, 17658and put it in @file{/tmp/empty}, you can run this command as root: 17659 17660@example 17661$ chroot /tmp/empty /ls -Rl / 17662@end example 17663 17664Then you'll see output like this: 17665 17666@example 17667/: 17668total 1023 17669-rwxr-xr-x 1 0 0 1041745 Aug 16 11:17 ls 17670@end example 17671 17672If you want to use a dynamically linked executable, say @command{bash}, 17673then first run @samp{ldd bash} to see what shared objects it needs. 17674Then, in addition to copying the actual binary, also copy the listed 17675files to the required positions under your intended new root directory. 17676Finally, if the executable requires any other files (e.g., data, state, 17677device files), copy them into place, too. 17678 17679@command{chroot} is installed only on systems that have the 17680@code{chroot} function, so portable scripts should not rely on its 17681existence. 17682 17683@cindex exit status of @command{chroot} 17684Exit status: 17685 17686@display 17687125 if @command{chroot} itself fails 17688126 if @var{command} is found but cannot be invoked 17689127 if @var{command} cannot be found 17690the exit status of @var{command} otherwise 17691@end display 17692 17693 17694@node env invocation 17695@section @command{env}: Run a command in a modified environment 17696 17697@pindex env 17698@cindex environment, running a program in a modified 17699@cindex modified environment, running a program in a 17700@cindex running a program in a modified environment 17701 17702@command{env} runs a command with a modified environment. Synopses: 17703 17704@example 17705env [@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c 17706[@var{command} [@var{args}]@dots{}] 17707env -[v]S'[@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c 17708[@var{command} [@var{args}]@dots{}]' 17709env 17710@end example 17711 17712@command{env} is commonly used on first line of scripts (shebang line): 17713@example 17714#!/usr/bin/env @var{command} 17715#!/usr/bin/env -[v]S[@var{option}]@dots{} [@var{name}=@var{value}]@dots{} @c 17716@var{command} [@var{args}]@dots{} 17717@end example 17718 17719Operands of the form @samp{@var{variable}=@var{value}} set 17720the environment variable @var{variable} to value @var{value}. 17721@var{value} may be empty (@samp{@var{variable}=}). Setting a variable 17722to an empty value is different from unsetting it. 17723These operands are evaluated left-to-right, so if two operands 17724mention the same variable the earlier is ignored. 17725 17726Environment variable names can be empty, and can contain any 17727characters other than @samp{=} and ASCII NUL. 17728However, it is wise to limit yourself to names that 17729consist solely of underscores, digits, and ASCII letters, 17730and that begin with a non-digit, as applications like the shell do not 17731work well with other names. 17732 17733@vindex PATH 17734The first operand that does not contain the character @samp{=} 17735specifies the program to invoke; it is 17736searched for according to the @env{PATH} environment variable. Any 17737remaining arguments are passed as arguments to that program. 17738The program should not be a special built-in utility 17739(@pxref{Special built-in utilities}). 17740 17741Modifications to @env{PATH} take effect prior to searching for 17742@var{command}. Use caution when reducing @env{PATH}; behavior is 17743not portable when @env{PATH} is undefined or omits key directories 17744such as @file{/bin}. 17745 17746In the rare case that a utility contains a @samp{=} in the name, the 17747only way to disambiguate it from a variable assignment is to use an 17748intermediate command for @var{command}, and pass the problematic 17749program name via @var{args}. For example, if @file{./prog=} is an 17750executable in the current @env{PATH}: 17751 17752@example 17753env prog= true # runs 'true', with prog= in environment 17754env ./prog= true # runs 'true', with ./prog= in environment 17755env -- prog= true # runs 'true', with prog= in environment 17756env sh -c '\prog= true' # runs 'prog=' with argument 'true' 17757env sh -c 'exec "$@@"' sh prog= true # also runs 'prog=' 17758@end example 17759 17760@cindex environment, printing 17761 17762If no command name is specified following the environment 17763specifications, the resulting environment is printed. This is like 17764specifying the @command{printenv} program. 17765 17766For some examples, suppose the environment passed to @command{env} 17767contains @samp{LOGNAME=rms}, @samp{EDITOR=emacs}, and 17768@samp{PATH=.:/gnubin:/hacks}: 17769 17770@itemize @bullet 17771 17772@item 17773Output the current environment. 17774@example 17775$ env | LC_ALL=C sort 17776EDITOR=emacs 17777LOGNAME=rms 17778PATH=.:/gnubin:/hacks 17779@end example 17780 17781@item 17782Run @command{foo} with a reduced environment, preserving only the 17783original @env{PATH} to avoid problems in locating @command{foo}. 17784@example 17785env - PATH="$PATH" foo 17786@end example 17787 17788@item 17789Run @command{foo} with the environment containing @samp{LOGNAME=rms}, 17790@samp{EDITOR=emacs}, and @samp{PATH=.:/gnubin:/hacks}, and guarantees 17791that @command{foo} was found in the file system rather than as a shell 17792built-in. 17793@example 17794env foo 17795@end example 17796 17797@item 17798Run @command{nemacs} with the environment containing @samp{LOGNAME=foo}, 17799@samp{EDITOR=emacs}, @samp{PATH=.:/gnubin:/hacks}, and 17800@samp{DISPLAY=gnu:0}. 17801@example 17802env DISPLAY=gnu:0 LOGNAME=foo nemacs 17803@end example 17804 17805@item 17806Attempt to run the program @command{/energy/--} (as that is the only 17807possible path search result); if the command exists, the environment 17808will contain @samp{LOGNAME=rms} and @samp{PATH=/energy}, and the 17809arguments will be @samp{e=mc2}, @samp{bar}, and @samp{baz}. 17810@example 17811env -u EDITOR PATH=/energy -- e=mc2 bar baz 17812@end example 17813 17814@end itemize 17815 17816 17817@subsection General options 17818 17819The program accepts the following options. Also see @ref{Common options}. 17820Options must precede operands. 17821 17822@table @samp 17823 17824@optNull 17825 17826@item -u @var{name} 17827@itemx --unset=@var{name} 17828@opindex -u 17829@opindex --unset 17830Remove variable @var{name} from the environment, if it was in the 17831environment. 17832 17833@item - 17834@itemx -i 17835@itemx --ignore-environment 17836@opindex - 17837@opindex -i 17838@opindex --ignore-environment 17839Start with an empty environment, ignoring the inherited environment. 17840 17841@item -C @var{dir} 17842@itemx --chdir=@var{dir} 17843@opindex -C 17844@opindex --chdir 17845Change the working directory to @var{dir} before invoking @var{command}. 17846This differs from the shell built-in @command{cd} in that it starts 17847@var{command} as a subprocess rather than altering the shell's own working 17848directory; this allows it to be chained with other commands that run commands 17849in a different context. For example: 17850 17851@example 17852# Run 'true' with /chroot as its root directory and /srv as its working 17853# directory. 17854chroot /chroot env --chdir=/srv true 17855# Run 'true' with /build as its working directory, FOO=bar in its 17856# environment, and a time limit of five seconds. 17857env --chdir=/build FOO=bar timeout 5 true 17858@end example 17859 17860@item --default-signal[=@var{sig}] 17861Unblock and reset signal @var{sig} to its default signal handler. 17862Without @var{sig} all known signals are unblocked and reset to their defaults. 17863Multiple signals can be comma-separated. An empty @var{sig} argument is a no-op. 17864The following command runs @command{seq} with SIGINT and SIGPIPE set to their 17865default (which is to terminate the program): 17866 17867@example 17868env --default-signal=PIPE,INT seq 1000 | head -n1 17869@end example 17870 17871In the following example, we see how this is not 17872possible to do with traditional shells. 17873Here the first trap command sets SIGPIPE to ignore. 17874The second trap command ostensibly sets it back to its default, 17875but POSIX mandates that the shell must not change inherited 17876state of the signal -- so it is a no-op. 17877 17878@example 17879trap '' PIPE && sh -c 'trap - PIPE ; seq inf | head -n1' 17880@end example 17881 17882Using @option{--default-signal=PIPE} we can 17883ensure the signal handling is set to its default behavior: 17884 17885@example 17886trap '' PIPE && sh -c 'env --default-signal=PIPE seq inf | head -n1' 17887@end example 17888 17889 17890@item --ignore-signal[=@var{sig}] 17891Ignore signal @var{sig} when running a program. Without @var{sig} all 17892known signals are set to ignore. Multiple signals can be comma-separated. 17893An empty @var{sig} argument is a no-op. The following command runs @command{seq} 17894with SIGINT set to be ignored -- pressing @kbd{Ctrl-C} will not terminate it: 17895 17896@example 17897env --ignore-signal=INT seq inf > /dev/null 17898@end example 17899 17900@samp{SIGCHLD} is special, in that @option{--ignore-signal=CHLD} might have 17901no effect (POSIX says it's unspecified). 17902 17903Most operating systems do not allow ignoring @samp{SIGKILL}, @samp{SIGSTOP} 17904(and possibly other signals). Attempting to ignore these signals will fail. 17905 17906Multiple (and contradictory) @option{--default-signal=SIG} and 17907@option{--ignore-signal=SIG} options are processed left-to-right, 17908with the latter taking precedence. In the following example, @samp{SIGPIPE} is 17909set to default while @samp{SIGINT} is ignored: 17910 17911@example 17912env --default-signal=INT,PIPE --ignore-signal=INT 17913@end example 17914 17915@item --block-signal[=@var{sig}] 17916Block signal(s) @var{sig} from being delivered. Without @var{sig} all 17917known signals are set to blocked. Multiple signals can be comma-separated. 17918An empty @var{sig} argument is a no-op. 17919 17920@item --list-signal-handling 17921List blocked or ignored signals to standard error, before executing a command. 17922 17923@item -v 17924@itemx --debug 17925@opindex -v 17926@opindex --debug 17927Show verbose information for each processing step. 17928 17929@example 17930$ env -v -uTERM A=B uname -s 17931unset: TERM 17932setenv: A=B 17933executing: uname 17934 arg[0]= 'uname' 17935 arg[1]= '-s' 17936Linux 17937@end example 17938 17939When combined with @option{-S} it is recommended to list @option{-v} 17940first, e.g. @command{env -vS'string'}. 17941 17942@item -S @var{string} 17943@itemx --split-string=@var{string} 17944@opindex -S 17945@opindex --split-string 17946@cindex shebang arguments 17947@cindex scripts arguments 17948@cindex env in scripts 17949process and split @var{string} into separate arguments used to pass 17950multiple arguments on shebang lines. @command{env} supports FreeBSD's 17951syntax of several escape sequences and environment variable 17952expansions. See below for details and examples. 17953 17954@end table 17955 17956@cindex exit status of @command{env} 17957Exit status: 17958 17959@display 179600 if no @var{command} is specified and the environment is output 17961125 if @command{env} itself fails 17962126 if @var{command} is found but cannot be invoked 17963127 if @var{command} cannot be found 17964the exit status of @var{command} otherwise 17965@end display 17966 17967@subsection @option{-S}/@option{--split-string} usage in scripts 17968 17969The @option{-S}/@option{--split-string} option enables use of multiple 17970arguments on the first line of scripts (the shebang line, @samp{#!}). 17971 17972When a script's interpreter is in a known location, scripts typically 17973contain the absolute file name in their first line: 17974 17975@multitable {Python Script:} {#!/usr/bin/python3} 17976@item Shell script: 17977@tab 17978@example 17979#!/bin/sh 17980echo hello 17981@end example 17982 17983@item Perl script: 17984@tab 17985@example 17986#!/usr/bin/perl 17987print "hello\n"; 17988@end example 17989 17990@item Python script: 17991@tab 17992@example 17993#!/usr/bin/python3 17994print("hello") 17995@end example 17996 17997@end multitable 17998 17999When a script's interpreter is in a non-standard location 18000in the @env{PATH} environment variable, it is recommended 18001to use @command{env} on the first line of the script to 18002find the executable and run it: 18003 18004@multitable {Python Script:} {#!/usr/bin/env python3} 18005@item Shell script: 18006@tab 18007@example 18008#!/usr/bin/env bash 18009echo hello 18010@end example 18011 18012@item Perl script: 18013@tab 18014@example 18015#!/usr/bin/env perl 18016print "hello\n"; 18017@end example 18018 18019@item Python script: 18020@tab 18021@example 18022#!/usr/bin/env python3 18023print("hello") 18024@end example 18025 18026@end multitable 18027 18028Most operating systems (e.g. GNU/Linux, BSDs) treat all text after the 18029first space as a single argument. When using @command{env} in a script 18030it is thus not possible to specify multiple arguments. 18031 18032In the following example: 18033@example 18034#!/usr/bin/env perl -T -w 18035print "hello\n"; 18036@end example 18037 18038The operating system treats @samp{perl -T -w} as one argument (the 18039program's name), and executing the script fails with: 18040 18041@example 18042/usr/bin/env: 'perl -T -w': No such file or directory 18043@end example 18044 18045The @option{-S} option instructs @command{env} to split the single string 18046into multiple arguments. The following example works as expected: 18047 18048@example 18049$ cat hello.pl 18050#!/usr/bin/env -S perl -T -w 18051print "hello\n"; 18052 18053$ chmod a+x hello.pl 18054$ ./hello.pl 18055hello 18056@end example 18057 18058And is equivalent to running @command{perl -T -w hello.pl} on the command line 18059prompt. 18060 18061@unnumberedsubsubsec Testing and troubleshooting 18062 18063@cindex single quotes, and @command{env -S} 18064@cindex @command{env -S}, and single quotes 18065@cindex @option{-S}, env and single quotes 18066To test @command{env -S} on the command line, use single quotes for the 18067@option{-S} string to emulate a single parameter. Single quotes are not 18068needed when using @command{env -S} in a shebang line on the first line of a 18069script (the operating system already treats it as one argument). 18070 18071The following command is equivalent to the @file{hello.pl} script above: 18072 18073@example 18074$ env -S'perl -T -w' hello.pl 18075@end example 18076 18077@cindex @command{env -S}, debugging 18078@cindex debugging, @command{env -S} 18079 18080To troubleshoot @option{-S} usage add the @option{-v} as the first 18081argument (before @option{-S}). 18082 18083Using @option{-vS} on a shebang line in a script: 18084 18085@example 18086$ cat hello-debug.pl 18087#!/usr/bin/env -vS perl -T -w 18088print "hello\n"; 18089 18090$ chmod a+x hello-debug.pl 18091$ ./hello-debug.pl 18092split -S: 'perl -T -w' 18093 into: 'perl' 18094 & '-T' 18095 & '-w' 18096executing: perl 18097 arg[0]= 'perl' 18098 arg[1]= '-T' 18099 arg[2]= '-w' 18100 arg[3]= './hello-debug.pl' 18101hello 18102@end example 18103 18104Using @option{-vS} on the command line prompt (adding single quotes): 18105 18106@example 18107$ env -vS'perl -T -w' hello-debug.pl 18108split -S: 'perl -T -w' 18109 into: 'perl' 18110 & '-T' 18111 & '-w' 18112executing: perl 18113 arg[0]= 'perl' 18114 arg[1]= '-T' 18115 arg[2]= '-w' 18116 arg[3]= 'hello-debug.pl' 18117hello 18118@end example 18119 18120@subsection @option{-S}/@option{--split-string} syntax 18121 18122@unnumberedsubsubsec Splitting arguments by whitespace 18123 18124Running @command{env -Sstring} splits the @var{string} into 18125arguments based on unquoted spaces or tab characters. 18126(Newlines, carriage returns, vertical tabs and form feeds are treated 18127like spaces and tabs.) 18128 18129In the following contrived example the @command{awk} variable 18130@samp{OFS} will be @code{<space>xyz<space>} as these spaces are inside 18131double quotes. The other space characters are used as argument separators: 18132 18133@example 18134$ cat one.awk 18135#!/usr/bin/env -S awk -v OFS=" xyz " -f 18136BEGIN @{print 1,2,3@} 18137 18138$ chmod a+x one.awk 18139$ ./one.awk 181401 xyz 2 xyz 3 18141@end example 18142 18143When using @option{-S} on the command line prompt, remember to add 18144single quotes around the entire string: 18145 18146@example 18147$ env -S'awk -v OFS=" xyz " -f' one.awk 181481 xyz 2 xyz 3 18149@end example 18150 18151@unnumberedsubsubsec Escape sequences 18152 18153@command{env} supports several escape sequences. These sequences 18154are processed when unquoted or inside double quotes (unless otherwise noted). 18155Single quotes disable escape sequences except @samp{\'} and @samp{\\}. 18156 18157@multitable @columnfractions .10 .90 18158 18159@item @code{\c} 18160@tab Ignore the remaining characters in the string. 18161Cannot be used inside double quotes. 18162 18163@item @code{\f} 18164@tab form-feed character (ASCII 0x0C) 18165 18166@item @code{\n} 18167@tab new-line character (ASCII 0x0A) 18168 18169@item @code{\r} 18170@tab carriage-return character (ASCII 0x0D) 18171 18172@item @code{\t} 18173@tab tab character (ASCII 0x09) 18174 18175@item @code{\v} 18176@tab vertical tab character (ASCII 0x0B) 18177 18178@item @code{\#} 18179@tab A hash @samp{#} character. Used when a @samp{#} character 18180is needed as the first character of an argument (see 'comments' section 18181below). 18182 18183@item @code{\$} 18184@tab A dollar-sign character @samp{$}. Unescaped @samp{$} characters 18185are used to expand environment variables (see 'variables' section below). 18186 18187@item @code{\_} 18188@tab Inside double-quotes, replaced with a single space character. 18189Outside quotes, treated as an argument separator. @samp{\_} can be used 18190to avoid space characters in a shebang line (see examples below). 18191 18192@item @code{\"} 18193@tab A double-quote character. 18194 18195@item @code{\'} 18196@tab A single-quote character. 18197This escape sequence works inside single-quoted strings. 18198 18199@item @code{\\} 18200@tab A backslash character. 18201This escape sequence works inside single-quoted strings. 18202 18203@end multitable 18204 18205The following @command{awk} script will use tab character as input and output 18206field separator (instead of spaces and tabs): 18207 18208@example 18209$ cat tabs.awk 18210#!/usr/bin/env -S awk -v FS="\t" -v OFS="\t" -f 18211... 18212@end example 18213 18214@unnumberedsubsubsec Comments 18215 18216The escape sequence @samp{\c} (used outside single/double quotes) 18217causes @command{env} to ignore the rest of the string. 18218 18219The @samp{#} character causes @command{env} to ignore the rest of 18220the string when it appears as the first character of an argument. 18221Use @samp{\#} to reverse this behavior. 18222 18223@example 18224$ env -S'printf %s\n A B C' 18225A 18226B 18227C 18228 18229$ env -S'printf %s\n A# B C' 18230A# 18231B 18232C 18233 18234$ env -S'printf %s\n A #B C' 18235A 18236 18237$ env -S'printf %s\n A \#B C' 18238A 18239#B 18240C 18241 18242$ env -S'printf %s\n A\cB C' 18243A 18244@end example 18245 18246NOTE: The above examples use single quotes as they are executed 18247on the command-line. 18248 18249 18250 18251@unnumberedsubsubsec Environment variable expansion 18252 18253The pattern @samp{$@{VARNAME@}} is used to substitute a value from 18254the environment variable. The pattern must include the curly braces 18255(@samp{@{},@samp{@}}). Without them @command{env} will reject the string. 18256Special shell variables (such as @samp{$@@}, @samp{$*}, @samp{$$}) are 18257not supported. 18258 18259If the environment variable is empty or not set, the pattern will be replaced 18260by an empty string. The value of @samp{$@{VARNAME@}} will be that of 18261the executed @command{env}, before any modifications using 18262@option{-i}/@option{--ignore-environment}/@option{-u}/@option{--unset} or 18263setting new values using @samp{VAR=VALUE}. 18264 18265The following python script prepends @file{/opt/custom/modules} to the python 18266module search path environment variable (@samp{PYTHONPATH}): 18267 18268@example 18269$ cat custom.py 18270#!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$@{PYTHONPATH@} python 18271print "hello" 18272... 18273@end example 18274 18275The expansion of @samp{$@{PYTHONPATH@}} is performed by @command{env}, 18276not by a shell. If the curly braces are omitted, @command{env} will fail: 18277 18278@example 18279$ cat custom.py 18280#!/usr/bin/env -S PYTHONPATH=/opt/custom/modules/:$PYTHONPATH python 18281print "hello" 18282... 18283 18284$ chmod a+x custom.py 18285$ custom.py 18286/usr/bin/env: only $@{VARNAME@} expansion is supported, error at: $PYTHONPATH @c 18287python 18288@end example 18289 18290Environment variable expansion happens before clearing the environment 18291(with @option{-i}) or unsetting specific variables (with @option{-u}): 18292 18293@example 18294$ env -S'-i OLDUSER=$@{USER@} env' 18295OLDUSER=gordon 18296@end example 18297 18298Use @option{-v} to diagnose the operations step-by-step: 18299 18300@example 18301$ env -vS'-i OLDUSER=$@{USER@} env' 18302expanding $@{USER@} into 'gordon' 18303split -S: '-i OLDUSER=$@{USER@} env' 18304 into: '-i' 18305 & 'OLDUSER=gordon' 18306 & 'env' 18307cleaning environ 18308setenv: OLDUSER=gordon 18309executing: env 18310 arg[0]= 'env' 18311OLDUSER=gordon 18312@end example 18313 18314 18315 18316@node nice invocation 18317@section @command{nice}: Run a command with modified niceness 18318 18319@pindex nice 18320@cindex niceness 18321@cindex scheduling, affecting 18322@cindex appropriate privileges 18323 18324@command{nice} prints a process's @dfn{niceness}, or runs 18325a command with modified niceness. @dfn{niceness} affects how 18326favorably the process is scheduled in the system. 18327Synopsis: 18328 18329@example 18330nice [@var{option}]@dots{} [@var{command} [@var{arg}]@dots{}] 18331@end example 18332 18333If no arguments are given, @command{nice} prints the current niceness. 18334Otherwise, @command{nice} runs the given @var{command} with its 18335niceness adjusted. By default, its niceness is incremented by 10. 18336 18337Niceness values range at least from @minus{}20 (process has high priority 18338and gets more resources, thus slowing down other processes) through 19 18339(process has lower priority and runs slowly itself, but has less impact 18340on the speed of other running processes). Some systems 18341may have a wider range of niceness values; conversely, other systems may 18342enforce more restrictive limits. An attempt to set the niceness 18343outside the supported range is treated as an attempt to use the 18344minimum or maximum supported value. 18345 18346A niceness should not be confused with a scheduling priority, which 18347lets applications determine the order in which threads are scheduled 18348to run. Unlike a priority, a niceness is merely advice to the 18349scheduler, which the scheduler is free to ignore. Also, as a point of 18350terminology, POSIX defines the behavior of @command{nice} in 18351terms of a @dfn{nice value}, which is the non-negative difference 18352between a niceness and the minimum niceness. Though @command{nice} 18353conforms to POSIX, its documentation and diagnostics use the 18354term ``niceness'' for compatibility with historical practice. 18355 18356@var{command} must not be a special built-in utility (@pxref{Special 18357built-in utilities}). 18358 18359@mayConflictWithShellBuiltIn{nice} 18360 18361Note to change the @dfn{niceness} of an existing process, 18362one needs to use the @command{renice} command. 18363 18364The program accepts the following option. Also see @ref{Common options}. 18365Options must precede operands. 18366 18367@table @samp 18368@item -n @var{adjustment} 18369@itemx --adjustment=@var{adjustment} 18370@opindex -n 18371@opindex --adjustment 18372Add @var{adjustment} instead of 10 to the command's niceness. If 18373@var{adjustment} is negative and you lack appropriate privileges, 18374@command{nice} issues a warning but otherwise acts as if you specified 18375a zero adjustment. 18376 18377For compatibility @command{nice} also supports an obsolete 18378option syntax @option{-@var{adjustment}}. New scripts should use 18379@option{-n @var{adjustment}} instead. 18380 18381@end table 18382 18383@command{nice} is installed only on systems that have the POSIX 18384@code{setpriority} function, so portable scripts should not rely on 18385its existence on non-POSIX platforms. 18386 18387@cindex exit status of @command{nice} 18388Exit status: 18389 18390@display 183910 if no @var{command} is specified and the niceness is output 18392125 if @command{nice} itself fails 18393126 if @var{command} is found but cannot be invoked 18394127 if @var{command} cannot be found 18395the exit status of @var{command} otherwise 18396@end display 18397 18398It is sometimes useful to run a non-interactive program with reduced niceness. 18399 18400@example 18401$ nice factor 4611686018427387903 18402@end example 18403 18404Since @command{nice} prints the current niceness, 18405you can invoke it through itself to demonstrate how it works. 18406 18407The default behavior is to increase the niceness by @samp{10}: 18408 18409@example 18410$ nice 184110 18412$ nice nice 1841310 18414$ nice -n 10 nice 1841510 18416@end example 18417 18418The @var{adjustment} is relative to the current niceness. In the 18419next example, the first @command{nice} invocation runs the second one 18420with niceness 10, and it in turn runs the final one with a niceness 18421that is 3 more: 18422 18423@example 18424$ nice nice -n 3 nice 1842513 18426@end example 18427 18428Specifying a niceness larger than the supported range 18429is the same as specifying the maximum supported value: 18430 18431@example 18432$ nice -n 10000000000 nice 1843319 18434@end example 18435 18436Only a privileged user may run a process with lower niceness: 18437 18438@example 18439$ nice -n -1 nice 18440nice: cannot set niceness: Permission denied 184410 18442$ sudo nice -n -1 nice 18443-1 18444@end example 18445 18446 18447@node nohup invocation 18448@section @command{nohup}: Run a command immune to hangups 18449 18450@pindex nohup 18451@cindex hangups, immunity to 18452@cindex immunity to hangups 18453@cindex logging out and continuing to run 18454 18455@flindex nohup.out 18456@command{nohup} runs the given @var{command} with hangup signals ignored, 18457so that the command can continue running in the background after you log 18458out. Synopsis: 18459 18460@example 18461nohup @var{command} [@var{arg}]@dots{} 18462@end example 18463 18464If standard input is a terminal, redirect it so that terminal sessions 18465do not mistakenly consider the terminal to be used by the command. 18466Make the substitute file descriptor unreadable, so that commands that 18467mistakenly attempt to read from standard input can report an error. 18468This redirection is a GNU extension; programs intended to be portable 18469to non-GNU hosts can use @samp{nohup @var{command} [@var{arg}]@dots{} 184700>/dev/null} instead. 18471 18472@flindex nohup.out 18473If standard output is a terminal, the command's standard output is appended 18474to the file @file{nohup.out}; if that cannot be written to, it is appended 18475to the file @file{$HOME/nohup.out}; and if that cannot be written to, the 18476command is not run. 18477Any @file{nohup.out} or @file{$HOME/nohup.out} file created by 18478@command{nohup} is made readable and writable only to the user, 18479regardless of the current umask settings. 18480 18481If standard error is a terminal, it is normally redirected to the same file 18482descriptor as the (possibly-redirected) standard output. 18483However, if standard output is closed, standard error terminal output 18484is instead appended to the file @file{nohup.out} or 18485@file{$HOME/nohup.out} as above. 18486 18487To capture the command's output to a file other than @file{nohup.out} 18488you can redirect it. For example, to capture the output of 18489@command{make}: 18490 18491@example 18492nohup make > make.log 18493@end example 18494 18495@command{nohup} does not automatically put the command it runs in the 18496background; you must do that explicitly, by ending the command line 18497with an @samp{&}. Also, @command{nohup} does not alter the 18498niceness of @var{command}; use @command{nice} for that, 18499e.g., @samp{nohup nice @var{command}}. 18500 18501@var{command} must not be a special built-in utility (@pxref{Special 18502built-in utilities}). 18503 18504The only options are @option{--help} and @option{--version}. @xref{Common 18505options}. Options must precede operands. 18506 18507@cindex exit status of @command{nohup} 18508Exit status: 18509 18510@display 18511125 if @command{nohup} itself fails, and @env{POSIXLY_CORRECT} is not set 18512126 if @var{command} is found but cannot be invoked 18513127 if @var{command} cannot be found 18514the exit status of @var{command} otherwise 18515@end display 18516 18517If @env{POSIXLY_CORRECT} is set, internal failures give status 127 18518instead of 125. 18519 18520 18521@node stdbuf invocation 18522@section @command{stdbuf}: Run a command with modified I/O stream buffering 18523 18524@pindex stdbuf 18525@cindex standard streams, buffering 18526@cindex line buffered 18527 18528@command{stdbuf} allows one to modify the buffering operations of the 18529three standard I/O streams associated with a program. Synopsis: 18530 18531@example 18532stdbuf @var{option}@dots{} @var{command} 18533@end example 18534 18535@var{command} must start with the name of a program that 18536@enumerate 18537@item 18538uses the ISO C @code{FILE} streams for input/output (note the 18539programs @command{dd} and @command{cat} don't do that), 18540 18541@item 18542does not adjust the buffering of its standard streams (note the 18543program @command{tee} is not in this category). 18544@end enumerate 18545 18546Any additional @var{arg}s are passed as additional arguments to the 18547@var{command}. 18548 18549The program accepts the following options. Also see @ref{Common options}. 18550 18551@table @samp 18552 18553@item -i @var{mode} 18554@itemx --input=@var{mode} 18555@opindex -i 18556@opindex --input 18557Adjust the standard input stream buffering. 18558 18559@item -o @var{mode} 18560@itemx --output=@var{mode} 18561@opindex -o 18562@opindex --output 18563Adjust the standard output stream buffering. 18564 18565@item -e @var{mode} 18566@itemx --error=@var{mode} 18567@opindex -e 18568@opindex --error 18569Adjust the standard error stream buffering. 18570 18571@end table 18572 18573The @var{mode} can be specified as follows: 18574 18575@table @samp 18576 18577@item L 18578Set the stream to line buffered mode. 18579In this mode data is coalesced until a newline is output or 18580input is read from any stream attached to a terminal device. 18581This option is invalid with standard input. 18582 18583@item 0 18584Disable buffering of the selected stream. 18585In this mode, data is output immediately and only the 18586amount of data requested is read from input. 18587Note the difference in function for input and output. 18588Disabling buffering for input will not influence the responsiveness 18589or blocking behavior of the stream input functions. 18590For example @code{fread} will still block until @code{EOF} or error, 18591even if the underlying @code{read} returns less data than requested. 18592 18593@item @var{size} 18594Specify the size of the buffer to use in fully buffered mode. 18595@multiplierSuffixesNoBlocks{size} 18596 18597@end table 18598 18599@command{stdbuf} is installed only on platforms that use the 18600Executable and Linkable Format (ELF) and support the 18601@code{constructor} attribute, so portable scripts should not rely on 18602its existence. 18603 18604@cindex exit status of @command{stdbuf} 18605Exit status: 18606 18607@display 18608125 if @command{stdbuf} itself fails 18609126 if @var{command} is found but cannot be invoked 18610127 if @var{command} cannot be found 18611the exit status of @var{command} otherwise 18612@end display 18613 18614 18615@node timeout invocation 18616@section @command{timeout}: Run a command with a time limit 18617 18618@pindex timeout 18619@cindex time limit 18620@cindex run commands with bounded time 18621 18622@command{timeout} runs the given @var{command} and kills it if it is 18623still running after the specified time interval. Synopsis: 18624 18625@example 18626timeout [@var{option}] @var{duration} @var{command} [@var{arg}]@dots{} 18627@end example 18628 18629@var{command} must not be a special built-in utility (@pxref{Special 18630built-in utilities}). 18631 18632The program accepts the following options. Also see @ref{Common options}. 18633Options must precede operands. 18634 18635@table @samp 18636@item --preserve-status 18637@opindex --preserve-status 18638Return the exit status of the managed @var{command} on timeout, rather than 18639a specific exit status indicating a timeout. This is useful if the 18640managed @var{command} supports running for an indeterminate amount of time. 18641 18642@item --foreground 18643@opindex --foreground 18644Don't create a separate background program group, so that 18645the managed @var{command} can use the foreground TTY normally. 18646This is needed to support two situations when timing out commands, 18647when not invoking @command{timeout} from an interactive shell. 18648@enumerate 18649@item 18650@var{command} is interactive and needs to read from the terminal for example 18651@item 18652the user wants to support sending signals directly to @var{command} 18653from the terminal (like Ctrl-C for example) 18654@end enumerate 18655 18656Note in this mode of operation, any children of @var{command} 18657will not be timed out. Also SIGCONT will not be sent to @var{command}, 18658as it's generally not needed with foreground processes, and can 18659cause intermittent signal delivery issues with programs that are monitors 18660themselves (like GDB for example). 18661 18662@item -k @var{duration} 18663@itemx --kill-after=@var{duration} 18664@opindex -k 18665@opindex --kill-after 18666Ensure the monitored @var{command} is killed by also sending a @samp{KILL} 18667signal. 18668 18669The specified @var{duration} starts from the point in time when 18670@command{timeout} sends the initial signal to @var{command}, i.e., 18671not from the beginning when the @var{command} is started. 18672 18673This option has no effect if either the main @var{duration} 18674of the @command{timeout} command, or the @var{duration} specified 18675to this option, is 0. 18676 18677This option may be useful if the selected signal did not kill the @var{command}, 18678either because the signal was blocked or ignored, or if the @var{command} takes 18679too long (e.g. for cleanup work) to terminate itself within a certain amount 18680of time. 18681 18682@item -s @var{signal} 18683@itemx --signal=@var{signal} 18684@opindex -s 18685@opindex --signal 18686Send this @var{signal} to @var{command} on timeout, rather than the 18687default @samp{TERM} signal. @var{signal} may be a name like @samp{HUP} 18688or a number. @xref{Signal specifications}. 18689 18690@item -v 18691@itemx --verbose 18692@opindex -v 18693@opindex --verbose 18694Diagnose to standard error, any signal sent upon timeout. 18695@end table 18696 18697@cindex time units 18698@var{duration} is a floating point number in either the current or the 18699C locale (@pxref{Floating point}) followed by an optional unit: 18700@display 18701@samp{s} for seconds (the default) 18702@samp{m} for minutes 18703@samp{h} for hours 18704@samp{d} for days 18705@end display 18706A duration of 0 disables the associated timeout. 18707Note that the actual timeout duration is dependent on system conditions, 18708which should be especially considered when specifying sub-second timeouts. 18709 18710@cindex exit status of @command{timeout} 18711Exit status: 18712 18713@display 18714124 if @var{command} times out, and @option{--preserve-status} is not specified 18715125 if @command{timeout} itself fails 18716126 if @var{command} is found but cannot be invoked 18717127 if @var{command} cannot be found 18718137 if @var{command} or @command{timeout} is sent the KILL(9) signal (128+9) 18719the exit status of @var{command} otherwise 18720@end display 18721 18722In the case of the @samp{KILL(9)} signal, @command{timeout} returns with 18723exit status 137, regardless of whether that signal is sent to @var{command} 18724or to @command{timeout} itself, i.e., these cases cannot be distinguished. 18725In the latter case, the @var{command} process may still be alive after 18726@command{timeout} has forcefully been terminated. 18727 18728Examples: 18729 18730@example 18731# Send the default TERM signal after 20s to a short-living 'sleep 1'. 18732# As that terminates long before the given duration, 'timeout' returns 18733# with the same exit status as the command, 0 in this case. 18734timeout 20 sleep 1 18735 18736# Send the INT signal after 5s to the 'sleep' command. Returns after 18737# 5 seconds with exit status 124 to indicate the sending of the signal. 18738timeout -s INT 5 sleep 20 18739 18740# Likewise, but the command ignoring the INT signal due to being started 18741# via 'env --ignore-signal'. Thus, 'sleep' terminates regularly after 18742# the full 20 seconds, still 'timeout' returns with exit status 124. 18743timeout -s INT 5s env --ignore-signal=INT sleep 20 18744 18745# Likewise, but sending the KILL signal 3 seconds after the initial 18746# INT signal. Hence, 'sleep' is forcefully terminated after about 18747# 8 seconds (5+3), and 'timeout' returns with an exit status of 137. 18748timeout -s INT -k 3s 5s env --ignore-signal=INT sleep 20 18749@end example 18750 18751@node Process control 18752@chapter Process control 18753 18754@cindex processes, commands for controlling 18755@cindex commands for controlling processes 18756 18757@menu 18758* kill invocation:: Sending a signal to processes. 18759@end menu 18760 18761 18762@node kill invocation 18763@section @command{kill}: Send a signal to processes 18764 18765@pindex kill 18766@cindex send a signal to processes 18767 18768The @command{kill} command sends a signal to processes, causing them 18769to terminate or otherwise act upon receiving the signal in some way. 18770Alternatively, it lists information about signals. Synopses: 18771 18772@example 18773kill [-s @var{signal} | --signal @var{signal} | -@var{signal}] @var{pid}@dots{} 18774kill [-l | --list | -t | --table] [@var{signal}]@dots{} 18775@end example 18776 18777@mayConflictWithShellBuiltIn{kill} 18778 18779The first form of the @command{kill} command sends a signal to all 18780@var{pid} arguments. The default signal to send if none is specified 18781is @samp{TERM}@. The special signal number @samp{0} does not denote a 18782valid signal, but can be used to test whether the @var{pid} arguments 18783specify processes to which a signal could be sent. 18784 18785If @var{pid} is positive, the signal is sent to the process with the 18786process ID @var{pid}. If @var{pid} is zero, the signal is sent to all 18787processes in the process group of the current process. If @var{pid} 18788is @minus{}1, the signal is sent to all processes for which the user has 18789permission to send a signal. If @var{pid} is less than @minus{}1, the signal 18790is sent to all processes in the process group that equals the absolute 18791value of @var{pid}. 18792 18793If @var{pid} is not positive, a system-dependent set of system 18794processes is excluded from the list of processes to which the signal 18795is sent. 18796 18797If a negative @var{pid} argument is desired as the first one, it 18798should be preceded by @option{--}. However, as a common extension to 18799POSIX, @option{--} is not required with @samp{kill 18800-@var{signal} -@var{pid}}. The following commands are equivalent: 18801 18802@example 18803kill -15 -1 18804kill -TERM -1 18805kill -s TERM -- -1 18806kill -- -1 18807@end example 18808 18809The first form of the @command{kill} command succeeds if every @var{pid} 18810argument specifies at least one process that the signal was sent to. 18811 18812The second form of the @command{kill} command lists signal information. 18813Either the @option{-l} or @option{--list} option, or the @option{-t} 18814or @option{--table} option must be specified. Without any 18815@var{signal} argument, all supported signals are listed. The output 18816of @option{-l} or @option{--list} is a list of the signal names, one 18817per line; if @var{signal} is already a name, the signal number is 18818printed instead. The output of @option{-t} or @option{--table} is a 18819table of signal numbers, names, and descriptions. This form of the 18820@command{kill} command succeeds if all @var{signal} arguments are valid 18821and if there is no output error. 18822 18823The @command{kill} command also supports the @option{--help} and 18824@option{--version} options. @xref{Common options}. 18825 18826A @var{signal} may be a signal name like @samp{HUP}, or a signal 18827number like @samp{1}, or an exit status of a process terminated by the 18828signal. A signal name can be given in canonical form or prefixed by 18829@samp{SIG}@. The case of the letters is ignored, except for the 18830@option{-@var{signal}} option which must use upper case to avoid 18831ambiguity with lower case option letters. 18832@xref{Signal specifications}, for a list of supported 18833signal names and numbers. 18834 18835@node Delaying 18836@chapter Delaying 18837 18838@cindex delaying commands 18839@cindex commands for delaying 18840 18841@c Perhaps @command{wait} or other commands should be described here also? 18842 18843@menu 18844* sleep invocation:: Delay for a specified time. 18845@end menu 18846 18847 18848@node sleep invocation 18849@section @command{sleep}: Delay for a specified time 18850 18851@pindex sleep 18852@cindex delay for a specified time 18853 18854@command{sleep} pauses for an amount of time specified by the sum of 18855the values of the command line arguments. 18856Synopsis: 18857 18858@example 18859sleep @var{number}[smhd]@dots{} 18860@end example 18861 18862@cindex time units 18863Each argument is a non-negative number followed by an optional unit; the default 18864is seconds. The units are: 18865 18866@table @samp 18867@item s 18868seconds 18869@item m 18870minutes 18871@item h 18872hours 18873@item d 18874days 18875@end table 18876 18877Although portable POSIX scripts must give @command{sleep} a single 18878non-negative integer argument without a suffix, GNU @command{sleep} 18879also accepts two or more arguments, unit suffixes, and floating-point 18880numbers in either the current or the C locale. @xref{Floating point}. 18881 18882For instance, the following could be used to @command{sleep} for 188831 second, 234 milli-, 567 micro- and 890 nanoseconds: 18884 18885@example 18886sleep 1234e-3 567.89e-6 18887@end example 18888 18889Also one could sleep indefinitely like: 18890 18891@example 18892sleep inf 18893@end example 18894 18895The only options are @option{--help} and @option{--version}. @xref{Common 18896options}. 18897 18898@c sleep is a shell built-in at least with Solaris 11's /bin/sh 18899@mayConflictWithShellBuiltIn{sleep} 18900 18901@exitstatus 18902 18903 18904@node Numeric operations 18905@chapter Numeric operations 18906 18907@cindex numeric operations 18908These programs do numerically-related operations. 18909 18910@menu 18911* factor invocation:: Show factors of numbers. 18912* numfmt invocation:: Reformat numbers. 18913* seq invocation:: Print sequences of numbers. 18914@end menu 18915 18916 18917@node factor invocation 18918@section @command{factor}: Print prime factors 18919 18920@pindex factor 18921@cindex prime factors 18922 18923@command{factor} prints prime factors. Synopsis: 18924 18925@example 18926factor [@var{option}]@dots{} [@var{number}]@dots{} 18927@end example 18928 18929If no @var{number} is specified on the command line, @command{factor} reads 18930numbers from standard input, delimited by newlines, tabs, or spaces. 18931 18932The program accepts the following options. Also see @ref{Common options}. 18933 18934@table @samp 18935@item -h 18936@itemx --exponents 18937@opindex -h 18938@opindex --exponents 18939print factors in the form @math{p^e}, rather than repeating 18940the prime @samp{p}, @samp{e} times. If the exponent @samp{e} is 1, 18941then it is omitted. 18942 18943@example 18944$ factor --exponents 3000 189453000: 2^3 3 5^3 18946@end example 18947@end table 18948 18949If the number to be factored is small (less than @math{2^{127}} on 18950typical machines), @command{factor} uses a faster algorithm. 18951For example, on a circa-2017 Intel Xeon Silver 4116, factoring the 18952product of the eighth and ninth Mersenne primes (approximately 18953@math{2^{92}}) takes about 4 ms of CPU time: 18954 18955@example 18956$ M8=$(echo 2^31-1 | bc) 18957$ M9=$(echo 2^61-1 | bc) 18958$ n=$(echo "$M8 * $M9" | bc) 18959$ bash -c "time factor $n" 189604951760154835678088235319297: 2147483647 2305843009213693951 18961 18962real 0m0.004s 18963user 0m0.004s 18964sys 0m0.000s 18965@end example 18966 18967For larger numbers, @command{factor} uses a slower algorithm. On the 18968same platform, factoring the eighth Fermat number @math{2^{256} + 1} 18969takes about 14 seconds, and the slower algorithm would have taken 18970about 750 ms to factor @math{2^{127} - 3} instead of the 50 ms needed by 18971the faster algorithm. 18972 18973Factoring large numbers is, in general, hard. The Pollard-Brent rho 18974algorithm used by @command{factor} is particularly effective for 18975numbers with relatively small factors. If you wish to factor large 18976numbers which do not have small factors (for example, numbers which 18977are the product of two large primes), other methods are far better. 18978 18979@exitstatus 18980 18981 18982@node numfmt invocation 18983@section @command{numfmt}: Reformat numbers 18984 18985@pindex numfmt 18986 18987@command{numfmt} reads numbers in various representations and reformats them 18988as requested. The most common usage is converting numbers to/from @emph{human} 18989representation (e.g. @samp{4G} @expansion{} @samp{4,000,000,000}). 18990 18991@example 18992numfmt [@var{option}]@dots{} [@var{number}] 18993@end example 18994 18995@command{numfmt} converts each @var{number} on the command-line according to the 18996specified options (see below). If no @var{number}s are given, it reads numbers 18997from standard input. @command{numfmt} can optionally extract numbers from 18998specific columns, maintaining proper line padding and alignment. 18999 19000@exitstatus 19001 19002See @option{--invalid} for additional information regarding exit status. 19003 19004@subsection General options 19005 19006The program accepts the following options. Also see @ref{Common options}. 19007 19008@table @samp 19009 19010@item --debug 19011@opindex --debug 19012Print (to standard error) warning messages about possible erroneous usage. 19013 19014@item -d @var{d} 19015@itemx --delimiter=@var{d} 19016@opindex -d 19017@opindex --delimiter 19018Use the character @var{d} as input field separator (default: whitespace). 19019@emph{Note}: Using non-default delimiter turns off automatic padding. 19020 19021@item --field=@var{fields} 19022@opindex --field 19023Convert the number in input field @var{fields} (default: 1). 19024@var{fields} supports @command{cut} style field ranges: 19025 19026@example 19027N N'th field, counted from 1 19028N- from N'th field, to end of line 19029N-M from N'th to M'th field (inclusive) 19030-M from first to M'th field (inclusive) 19031- all fields 19032@end example 19033 19034 19035@item --format=@var{format} 19036@opindex --format 19037Use printf-style floating FORMAT string. The @var{format} string must contain 19038one @samp{%f} directive, optionally with @samp{'}, @samp{-}, @samp{0}, width 19039or precision modifiers. The @samp{'} modifier will enable @option{--grouping}, 19040the @samp{-} modifier will enable left-aligned @option{--padding} and the width 19041modifier will enable right-aligned @option{--padding}. The @samp{0} width 19042modifier (without the @samp{-} modifier) will generate leading zeros on the 19043number, up to the specified width. A precision specification like @samp{%.1f} 19044will override the precision determined from the input data or set due to 19045@option{--to} option auto scaling. 19046 19047@item --from=@var{unit} 19048@opindex --from 19049Auto-scales input numbers according to @var{unit}. See UNITS below. 19050The default is no scaling, meaning suffixes (e.g. @samp{M}, @samp{G}) will 19051trigger an error. 19052 19053@item --from-unit=@var{n} 19054@opindex --from-unit 19055Specify the input unit size (instead of the default 1). Use this option when 19056the input numbers represent other units (e.g. if the input number @samp{10} 19057represents 10 units of 512 bytes, use @samp{--from-unit=512}). 19058Suffixes are handled as with @samp{--from=auto}. 19059 19060@item --grouping 19061@opindex --grouping 19062Group digits in output numbers according to the current locale's grouping rules 19063(e.g @emph{Thousands Separator} character, commonly @samp{.} (dot) or @samp{,} 19064comma). This option has no effect in @samp{POSIX/C} locale. 19065 19066@item --header[=@var{n}] 19067@opindex --header 19068@opindex --header=N 19069Print the first @var{n} (default: 1) lines without any conversion. 19070 19071@item --invalid=@var{mode} 19072@opindex --invalid 19073The default action on input errors is to exit immediately with status code 2. 19074@option{--invalid=@samp{abort}} explicitly specifies this default mode. 19075With a @var{mode} of @samp{fail}, print a warning for @emph{each} conversion 19076error, and exit with status 2. With a @var{mode} of @samp{warn}, exit with 19077status 0, even in the presence of conversion errors, and with a @var{mode} of 19078@samp{ignore} do not even print diagnostics. 19079 19080@item --padding=@var{n} 19081@opindex --padding 19082Pad the output numbers to @var{n} characters, by adding spaces. If @var{n} is 19083a positive number, numbers will be right-aligned. If @var{n} is a negative 19084number, numbers will be left-aligned. By default, numbers are automatically 19085aligned based on the input line's width (only with the default delimiter). 19086 19087@item --round=@var{method} 19088@opindex --round 19089@opindex --round=up 19090@opindex --round=down 19091@opindex --round=from-zero 19092@opindex --round=towards-zero 19093@opindex --round=nearest 19094When converting number representations, round the number according to 19095@var{method}, which can be @samp{up}, @samp{down}, 19096@samp{from-zero} (the default), @samp{towards-zero}, @samp{nearest}. 19097 19098@item --suffix=@var{suffix} 19099@opindex --suffix 19100Add @samp{SUFFIX} to the output numbers, and accept optional @samp{SUFFIX} in 19101input numbers. 19102 19103@item --to=@var{unit} 19104@opindex --to 19105Auto-scales output numbers according to @var{unit}. See @emph{Units} below. 19106The default is no scaling, meaning all the digits of the number are printed. 19107 19108@item --to-unit=@var{n} 19109@opindex --to-unit 19110Specify the output unit size (instead of the default 1). Use this option when 19111the output numbers represent other units (e.g. to represent @samp{4,000,000} 19112bytes in blocks of 1KB, use @samp{--to=si --to-unit=1000}). 19113Suffixes are handled as with @samp{--from=auto}. 19114 19115@optZeroTerminated 19116@newlineFieldSeparator 19117 19118@end table 19119 19120@subsection Possible @var{unit}s: 19121 19122The following are the possible @var{unit} options with @option{--from=UNITS} and 19123@option{--to=UNITS}: 19124 19125@table @var 19126 19127@item none 19128No scaling is performed. For input numbers, no suffixes are accepted, and any 19129trailing characters following the number will trigger an error. For output 19130numbers, all digits of the numbers will be printed. 19131 19132@item si 19133Auto-scale numbers according to the @emph{International System of Units (SI)} 19134standard. 19135For input numbers, accept one of the following suffixes. 19136For output numbers, values larger than 1000 will be rounded, and printed with 19137one of the following suffixes: 19138 19139@example 19140@samp{K} => @math{1000^1 = 10^3} (Kilo) 19141@samp{M} => @math{1000^2 = 10^6} (Mega) 19142@samp{G} => @math{1000^3 = 10^9} (Giga) 19143@samp{T} => @math{1000^4 = 10^{12}} (Tera) 19144@samp{P} => @math{1000^5 = 10^{15}} (Peta) 19145@samp{E} => @math{1000^6 = 10^{18}} (Exa) 19146@samp{Z} => @math{1000^7 = 10^{21}} (Zetta) 19147@samp{Y} => @math{1000^8 = 10^{24}} (Yotta) 19148@samp{R} => @math{1000^9 = 10^{27}} (Ronna) 19149@samp{Q} => @math{1000^{10} = 10^{30}} (Quetta) 19150@end example 19151 19152@item iec 19153Auto-scale numbers according to the @emph{International Electrotechnical 19154Commission (IEC)} standard. 19155For input numbers, accept one of the following suffixes. 19156For output numbers, values larger than 1024 will be rounded, and printed with 19157one of the following suffixes: 19158 19159@example 19160@samp{K} => @math{1024^1 = 2^{10}} (Kibi) 19161@samp{M} => @math{1024^2 = 2^{20}} (Mebi) 19162@samp{G} => @math{1024^3 = 2^{30}} (Gibi) 19163@samp{T} => @math{1024^4 = 2^{40}} (Tebi) 19164@samp{P} => @math{1024^5 = 2^{50}} (Pebi) 19165@samp{E} => @math{1024^6 = 2^{60}} (Exbi) 19166@samp{Z} => @math{1024^7 = 2^{70}} (Zebi) 19167@samp{Y} => @math{1024^8 = 2^{80}} (Yobi) 19168@samp{R} => @math{1024^9 = 2^{90}} (Robi) 19169@samp{Q} => @math{1024^{10} = 2^{100}} (Quebi) 19170@end example 19171 19172The @option{iec} option uses a single letter suffix (e.g. @samp{G}), which is 19173not fully standard, as the @emph{iec} standard recommends a two-letter symbol 19174(e.g @samp{Gi}) -- but in practice, this method is common. Compare with 19175the @option{iec-i} option. 19176 19177@item iec-i 19178Auto-scale numbers according to the @emph{International Electrotechnical 19179Commission (IEC)} standard. 19180For input numbers, accept one of the following suffixes. 19181For output numbers, values larger than 1024 will be rounded, and printed with 19182one of the following suffixes: 19183 19184@example 19185@samp{Ki} => @math{1024^1 = 2^{10}} (Kibi) 19186@samp{Mi} => @math{1024^2 = 2^{20}} (Mebi) 19187@samp{Gi} => @math{1024^3 = 2^{30}} (Gibi) 19188@samp{Ti} => @math{1024^4 = 2^{40}} (Tebi) 19189@samp{Pi} => @math{1024^5 = 2^{50}} (Pebi) 19190@samp{Ei} => @math{1024^6 = 2^{60}} (Exbi) 19191@samp{Zi} => @math{1024^7 = 2^{70}} (Zebi) 19192@samp{Yi} => @math{1024^8 = 2^{80}} (Yobi) 19193@samp{Ri} => @math{1024^9 = 2^{90}} (Robi) 19194@samp{Qi} => @math{1024^{10} = 2^{100}} (Quebi) 19195@end example 19196 19197The @option{iec-i} option uses a two-letter suffix symbol (e.g. @samp{Gi}), 19198as the @emph{iec} standard recommends, but this is not always common in 19199practice. Compare with the @option{iec} option. 19200 19201@item auto 19202@samp{auto} can only be used with @option{--from}. With this method, numbers 19203with single-letter suffixes like @samp{K} 19204suffixes are interpreted as @emph{SI} values, and numbers with 19205two-letter suffixes like @samp{Ki} 19206are interpreted as @emph{IEC} values. 19207 19208@end table 19209 19210@subsection Examples of using @command{numfmt} 19211 19212Converting a single number from/to @emph{human} representation: 19213@example 19214$ numfmt --to=si 500000 19215500K 19216 19217$ numfmt --to=iec 500000 19218489K 19219 19220$ numfmt --to=iec-i 500000 19221489Ki 19222 19223$ numfmt --from=si 1M 192241000000 19225 19226$ numfmt --from=iec 1M 192271048576 19228 19229# with '--from=auto', M=Mega, Mi=Mebi 19230$ numfmt --from=auto 1M 192311000000 19232$ numfmt --from=auto 1Mi 192331048576 19234@end example 19235 19236Converting from @samp{SI} to @samp{IEC} scales (e.g. when a drive's capacity is 19237advertised as @samp{1TB}, while checking the drive's capacity gives lower 19238values): 19239 19240@example 19241$ numfmt --from=si --to=iec 1T 19242932G 19243@end example 19244 19245With both input and output scales specified, 19246the largest defined prefixes are supported: 19247 19248@example 19249$ numfmt --from=si --to=iec-i 2000R 192501.6Qi 19251@end example 19252 19253Converting a single field from an input file / piped input (these contrived 19254examples are for demonstration purposes only, as both @command{ls} and 19255@command{df} support the @option{--human-readable} option to 19256output sizes in human-readable format): 19257 19258@example 19259# Third field (file size) will be shown in SI representation 19260$ ls -log | numfmt --field 3 --header --to=si | head -n4 19261-rw-r--r-- 1 94K Aug 23 2011 ABOUT-NLS 19262-rw-r--r-- 1 3.7K Jan 7 16:15 AUTHORS 19263-rw-r--r-- 1 36K Jun 1 2011 COPYING 19264-rw-r--r-- 1 0 Jan 7 15:15 ChangeLog 19265 19266# Second field (size) will be shown in IEC representation 19267$ df --block-size=1 | numfmt --field 2 --header --to=iec | head -n4 19268File system 1B-blocks Used Available Use% Mounted on 19269rootfs 132G 104741408 26554036 80% / 19270tmpfs 794M 7580 804960 1% /run/shm 19271/dev/sdb1 694G 651424756 46074696 94% /home 19272@end example 19273 19274 19275Output can be tweaked using @option{--padding} or @option{--format}: 19276 19277@example 19278# Pad to 10 characters, right-aligned 19279$ du -s * | numfmt --to=si --padding=10 19280 2.5K config.log 19281 108 config.status 19282 1.7K configure 19283 20 configure.ac 19284 19285# Pad to 10 characters, left-aligned 19286$ du -s * | numfmt --to=si --padding=-10 192872.5K config.log 19288108 config.status 192891.7K configure 1929020 configure.ac 19291 19292# Pad to 10 characters, left-aligned, using 'format' 19293$ du -s * | numfmt --to=si --format="%10f" 19294 2.5K config.log 19295 108 config.status 19296 1.7K configure 19297 20 configure.ac 19298 19299# Pad to 10 characters, left-aligned, using 'format' 19300$ du -s * | numfmt --to=si --padding="%-10f" 193012.5K config.log 19302108 config.status 193031.7K configure 1930420 configure.ac 19305@end example 19306 19307With locales that support grouping digits, using @option{--grouping} or 19308@option{--format} enables grouping. In @samp{POSIX} locale, grouping is 19309silently ignored: 19310 19311@example 19312$ LC_ALL=C numfmt --from=iec --grouping 2G 193132147483648 19314 19315$ LC_ALL=en_US.utf8 numfmt --from=iec --grouping 2G 193162,147,483,648 19317 19318$ LC_ALL=ta_IN numfmt --from=iec --grouping 2G 193192,14,74,83,648 19320 19321$ LC_ALL=C numfmt --from=iec --format="==%'15f==" 2G 19322== 2147483648== 19323 19324$ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'15f==" 2G 19325== 2,147,483,648== 19326 19327$ LC_ALL=en_US.utf8 numfmt --from=iec --format="==%'-15f==" 2G 19328==2,147,483,648 == 19329 19330$ LC_ALL=ta_IN numfmt --from=iec --format="==%'15f==" 2G 19331== 2,14,74,83,648== 19332@end example 19333 19334 19335@node seq invocation 19336@section @command{seq}: Print numeric sequences 19337 19338@pindex seq 19339@cindex numeric sequences 19340@cindex sequence of numbers 19341 19342@command{seq} prints a sequence of numbers to standard output. Synopses: 19343 19344@example 19345seq [@var{option}]@dots{} @var{last} 19346seq [@var{option}]@dots{} @var{first} @var{last} 19347seq [@var{option}]@dots{} @var{first} @var{increment} @var{last} 19348@end example 19349 19350@command{seq} prints the numbers from @var{first} to @var{last} by 19351@var{increment}. By default, each number is printed on a separate line. 19352When @var{increment} is not specified, it defaults to @samp{1}, 19353even when @var{first} is larger than @var{last}. 19354@var{first} also defaults to @samp{1}. So @code{seq 1} prints 19355@samp{1}, but @code{seq 0} and @code{seq 10 5} produce no output. 19356The sequence of numbers ends when the sum of the current number and 19357@var{increment} would become greater than @var{last}, 19358so @code{seq 1 10 10} only produces @samp{1}. 19359@var{increment} must not be @samp{0}; use the tool @command{yes} to get 19360repeated output of a constant number. 19361@var{first}, @var{increment} and @var{last} must not be @code{NaN}, 19362but @code{inf} is supported. 19363Floating-point numbers may be specified in either the current or 19364the C locale. @xref{Floating point}. 19365 19366The program accepts the following options. Also see @ref{Common options}. 19367Options must precede operands. 19368 19369@table @samp 19370@item -f @var{format} 19371@itemx --format=@var{format} 19372@opindex -f 19373@opindex --format 19374@cindex formatting of numbers in @command{seq} 19375Print all numbers using @var{format}. 19376@var{format} must contain exactly one of the @samp{printf}-style 19377floating point conversion specifications @samp{%a}, @samp{%e}, 19378@samp{%f}, @samp{%g}, @samp{%A}, @samp{%E}, @samp{%F}, @samp{%G}@. 19379The @samp{%} may be followed by zero or more flags taken from the set 19380@samp{-+#0 '}, then an optional width containing one or more digits, 19381then an optional precision consisting of a @samp{.} followed by zero 19382or more digits. @var{format} may also contain any number of @samp{%%} 19383conversion specifications. All conversion specifications have the 19384same meaning as with @samp{printf}. 19385 19386The default format is derived from @var{first}, @var{step}, and 19387@var{last}. If these all use a fixed point decimal representation, 19388the default format is @samp{%.@var{p}f}, where @var{p} is the minimum 19389precision that can represent the output numbers exactly. Otherwise, 19390the default format is @samp{%g}. 19391 19392@item -s @var{string} 19393@itemx --separator=@var{string} 19394@opindex -s 19395@opindex --separator 19396@cindex separator for numbers in @command{seq} 19397Separate numbers with @var{string}; default is a newline. 19398The output always terminates with a newline. 19399 19400@item -w 19401@itemx --equal-width 19402@opindex -w 19403@opindex --equal-width 19404Print all numbers with the same width, by padding with leading zeros. 19405@var{first}, @var{step}, and @var{last} should all use a fixed point 19406decimal representation. 19407(To have other kinds of padding, use @option{--format}). 19408 19409@end table 19410 19411You can get finer-grained control over output with @option{-f}: 19412 19413@example 19414$ seq -f '(%9.2E)' -9e5 1.1e6 1.3e6 19415(-9.00E+05) 19416( 2.00E+05) 19417( 1.30E+06) 19418@end example 19419 19420If you want hexadecimal integer output, you can use @command{printf} 19421to perform the conversion: 19422 19423@example 19424$ printf '%x\n' $(seq 1048575 1024 1050623) 19425fffff 194261003ff 194271007ff 19428@end example 19429 19430For very long lists of numbers, use xargs to avoid 19431system limitations on the length of an argument list: 19432 19433@example 19434$ seq 1000000 | xargs printf '%x\n' | tail -n 3 19435f423e 19436f423f 19437f4240 19438@end example 19439 19440To generate octal output, use the printf @code{%o} format instead 19441of @code{%x}. 19442 19443On most systems, seq can produce whole-number output for values up to 19444at least @math{2^{53}}. Larger integers are approximated. The details 19445differ depending on your floating-point implementation. 19446@xref{Floating point}. A common 19447case is that @command{seq} works with integers through @math{2^{64}}, 19448and larger integers may not be numerically correct: 19449 19450@example 19451$ seq 50000000000000000000 2 50000000000000000004 1945250000000000000000000 1945350000000000000000000 1945450000000000000000004 19455@end example 19456 19457However, note that when limited to non-negative whole numbers, 19458an increment of less than 200, and no format-specifying option, 19459seq can print arbitrarily large numbers. 19460Therefore @command{seq inf} can be used to 19461generate an infinite sequence of numbers. 19462 19463Be careful when using @command{seq} with outlandish values: otherwise 19464you may see surprising results, as @command{seq} uses floating point 19465internally. For example, on the x86 platform, where the internal 19466representation uses a 64-bit fraction, the command: 19467 19468@example 19469seq 1 0.0000000000000000001 1.0000000000000000009 19470@end example 19471 19472outputs 1.0000000000000000007 twice and skips 1.0000000000000000008. 19473 19474@exitstatus 19475 19476 19477@node File permissions 19478@chapter File permissions 19479@include perm.texi 19480 19481 19482@node File timestamps 19483@chapter File timestamps 19484 19485@cindex atime 19486@cindex birthtime 19487@cindex ctime 19488@cindex mtime 19489Standard POSIX files have three timestamps: the access timestamp 19490(atime) of the last read, the modification timestamp (mtime) of the 19491last write, and the status change timestamp (ctime) of the last change 19492to the file's meta-information. Some file systems support a 19493fourth time: the birth timestamp (birthtime) of when the file was 19494created; by definition, birthtime never changes. 19495 19496One common example of a ctime change is when the permissions of a file 19497change. Changing the permissions doesn't access the file, so atime 19498doesn't change, nor does it modify the file, so the mtime doesn't 19499change. Yet, something about the file itself has changed, and this 19500must be noted somewhere. This is the job of the ctime field. This is 19501necessary, so that, for example, a backup program can make a fresh 19502copy of the file, including the new permissions value. Another 19503operation that modifies a file's ctime without affecting the others is 19504renaming. 19505 19506Naively, a file's atime, mtime, and ctime are set to the current time 19507whenever you read, write, or change the attributes of the file 19508respectively, and searching a directory counts as reading it. A 19509file's atime and mtime can also be set directly, via the 19510@command{touch} command (@pxref{touch invocation}). In practice, 19511though, timestamps are not updated quite that way. 19512 19513For efficiency reasons, many systems are lazy about updating atimes: 19514when a program accesses a file, they may delay updating the file's 19515atime, or may not update the file's atime if the file has been 19516accessed recently, or may not update the atime at all. Similar 19517laziness, though typically not quite so extreme, applies to mtimes and 19518ctimes. 19519 19520Some systems emulate timestamps instead of supporting them directly, 19521and these emulations may disagree with the naive interpretation. For 19522example, a system may fake an atime or ctime by using the mtime. 19523 19524@cindex clock skew 19525The determination of what time is ``current'' depends on the 19526platform. Platforms with network file systems often use different 19527clocks for the operating system and for file systems; because 19528updates typically uses file systems' clocks by default, clock 19529skew can cause the resulting file timestamps to appear to be in a 19530program's ``future'' or ``past''. 19531 19532@cindex file timestamp resolution 19533When the system updates a file timestamp to a desired time @var{t} 19534(which is either the current time, or a time specified via the 19535@command{touch} command), there are several reasons the file's 19536timestamp may be set to a value that differs from @var{t}. First, 19537@var{t} may have a higher resolution than supported. Second, a file 19538system may use different resolutions for different types of times. 19539Third, file timestamps may use a different resolution than operating 19540system timestamps. Fourth, the operating system primitives used to 19541update timestamps may employ yet a different resolution. For example, 19542in theory a file system might use 10-microsecond resolution for access 19543timestamp and 100-nanosecond resolution for modification timestamp, and the 19544operating system might use nanosecond resolution for the current time 19545and microsecond resolution for the primitive that @command{touch} uses 19546to set a file's timestamp to an arbitrary value. 19547 19548 19549@include parse-datetime.texi 19550 19551@include sort-version.texi 19552 19553@c What's GNU? 19554@c Arnold Robbins 19555@node Opening the software toolbox 19556@chapter Opening the Software Toolbox 19557 19558An earlier version of this chapter appeared in 19559@uref{https://www.linuxjournal.com/article.php?sid=2762, the 19560@cite{What's GNU@?} column of the June 1994 @cite{Linux Journal}}. 19561It was written by Arnold Robbins. 19562 19563@menu 19564* Toolbox introduction:: Toolbox introduction 19565* I/O redirection:: I/O redirection 19566* The who command:: The @command{who} command 19567* The cut command:: The @command{cut} command 19568* The sort command:: The @command{sort} command 19569* The uniq command:: The @command{uniq} command 19570* Putting the tools together:: Putting the tools together 19571@end menu 19572 19573 19574@node Toolbox introduction 19575@unnumberedsec Toolbox Introduction 19576 19577This month's column is only peripherally related to the GNU Project, in 19578that it describes a number of the GNU tools on your GNU/Linux system 19579and how they 19580might be used. What it's really about is the ``Software Tools'' philosophy 19581of program development and usage. 19582 19583The software tools philosophy was an important and integral concept 19584in the initial design and development of Unix (of which GNU/Linux and GNU are 19585essentially clones). Unfortunately, in the modern day press of 19586Internetworking and flashy GUIs, it seems to have fallen by the 19587wayside. This is a shame, since it provides a powerful mental model 19588for solving many kinds of problems. 19589 19590Many people carry a Swiss Army knife around in their pants pockets (or 19591purse). A Swiss Army knife is a handy tool to have: it has several knife 19592blades, a screwdriver, tweezers, toothpick, nail file, corkscrew, and perhaps 19593a number of other things on it. For the everyday, small miscellaneous jobs 19594where you need a simple, general purpose tool, it's just the thing. 19595 19596On the other hand, an experienced carpenter doesn't build a house using 19597a Swiss Army knife. Instead, he has a toolbox chock full of specialized 19598tools -- a saw, a hammer, a screwdriver, a plane, and so on. And he knows 19599exactly when and where to use each tool; you won't catch him hammering nails 19600with the handle of his screwdriver. 19601 19602The Unix developers at Bell Labs were all professional programmers and trained 19603computer scientists. They had found that while a one-size-fits-all program 19604might appeal to a user because there's only one program to use, in practice 19605such programs are 19606 19607@enumerate a 19608@item 19609difficult to write, 19610 19611@item 19612difficult to maintain and 19613debug, and 19614 19615@item 19616difficult to extend to meet new situations. 19617@end enumerate 19618 19619Instead, they felt that programs should be specialized tools. In short, each 19620program ``should do one thing well.'' No more and no less. Such programs are 19621simpler to design, write, and get right -- they only do one thing. 19622 19623Furthermore, they found that with the right machinery for hooking programs 19624together, that the whole was greater than the sum of the parts. By combining 19625several special purpose programs, you could accomplish a specific task 19626that none of the programs was designed for, and accomplish it much more 19627quickly and easily than if you had to write a special purpose program. 19628We will see some (classic) examples of this further on in the column. 19629(An important additional point was that, if necessary, take a detour 19630and build any software tools you may need first, if you don't already 19631have something appropriate in the toolbox.) 19632 19633@node I/O redirection 19634@unnumberedsec I/O Redirection 19635 19636Hopefully, you are familiar with the basics of I/O redirection in the 19637shell, in particular the concepts of ``standard input,'' ``standard output,'' 19638and ``standard error''. Briefly, ``standard input'' is a data source, where 19639data comes from. A program should not need to either know or care if the 19640data source is a regular file, a keyboard, a magnetic tape, or even a punched 19641card reader. Similarly, ``standard output'' is a data sink, where data goes 19642to. The program should neither know nor care where this might be. 19643Programs that only read their standard input, do something to the data, 19644and then send it on, are called @dfn{filters}, by analogy to filters in a 19645water pipeline. 19646 19647With the Unix shell, it's very easy to set up data pipelines: 19648 19649@example 19650program_to_create_data | filter1 | ... | filterN > final.pretty.data 19651@end example 19652 19653We start out by creating the raw data; each filter applies some successive 19654transformation to the data, until by the time it comes out of the pipeline, 19655it is in the desired form. 19656 19657This is fine and good for standard input and standard output. Where does the 19658standard error come in to play? Well, think about @command{filter1} in 19659the pipeline above. What happens if it encounters an error in the data it 19660sees? If it writes an error message to standard output, it will just 19661disappear down the pipeline into @command{filter2}'s input, and the 19662user will probably never see it. So programs need a place where they can send 19663error messages so that the user will notice them. This is standard error, 19664and it is usually connected to your console or window, even if you have 19665redirected standard output of your program away from your screen. 19666 19667For filter programs to work together, the format of the data has to be 19668agreed upon. The most straightforward and easiest format to use is simply 19669lines of text. Unix data files are generally just streams of bytes, with 19670lines delimited by the ASCII LF (Line Feed) character, 19671conventionally called a ``newline'' in the Unix literature. (This is 19672@code{'\n'} if you're a C programmer.) This is the format used by all 19673the traditional filtering programs. (Many earlier operating systems 19674had elaborate facilities and special purpose programs for managing 19675binary data. Unix has always shied away from such things, under the 19676philosophy that it's easiest to simply be able to view and edit your 19677data with a text editor.) 19678 19679OK, enough introduction. Let's take a look at some of the tools, and then 19680we'll see how to hook them together in interesting ways. In the following 19681discussion, we will only present those command line options that interest 19682us. As you should always do, double check your system documentation 19683for the full story. 19684 19685@node The who command 19686@unnumberedsec The @command{who} Command 19687 19688The first program is the @command{who} command. By itself, it generates a 19689list of the users who are currently logged in. Although I'm writing 19690this on a single-user system, we'll pretend that several people are 19691logged in: 19692 19693@example 19694$ who 19695@print{} arnold console Jan 22 19:57 19696@print{} miriam ttyp0 Jan 23 14:19(:0.0) 19697@print{} bill ttyp1 Jan 21 09:32(:0.0) 19698@print{} arnold ttyp2 Jan 23 20:48(:0.0) 19699@end example 19700 19701Here, the @samp{$} is the usual shell prompt, at which I typed @samp{who}. 19702There are three people logged in, and I am logged in twice. On traditional 19703Unix systems, user names are never more than eight characters long. This 19704little bit of trivia will be useful later. The output of @command{who} is nice, 19705but the data is not all that exciting. 19706 19707@node The cut command 19708@unnumberedsec The @command{cut} Command 19709 19710The next program we'll look at is the @command{cut} command. This program 19711cuts out columns or fields of input data. For example, we can tell it 19712to print just the login name and full name from the @file{/etc/passwd} 19713file. The @file{/etc/passwd} file has seven fields, separated by 19714colons: 19715 19716@example 19717arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/bash 19718@end example 19719 19720To get the first and fifth fields, we would use @command{cut} like this: 19721 19722@example 19723$ cut -d: -f1,5 /etc/passwd 19724@print{} root:Operator 19725@dots{} 19726@print{} arnold:Arnold D. Robbins 19727@print{} miriam:Miriam A. Robbins 19728@dots{} 19729@end example 19730 19731With the @option{-c} option, @command{cut} will cut out specific characters 19732(i.e., columns) in the input lines. This is useful for input data 19733that has fixed width fields, and does not have a field separator. For 19734example, list the Monday dates for the current month: 19735 19736@c Is using cal ok? Looked at gcal, but I don't like it. 19737@example 19738$ cal | cut -c 3-5 19739@print{}Mo 19740@print{} 19741@print{} 6 19742@print{} 13 19743@print{} 20 19744@print{} 27 19745@end example 19746 19747@node The sort command 19748@unnumberedsec The @command{sort} Command 19749 19750Next we'll look at the @command{sort} command. This is one of the most 19751powerful commands on a Unix-style system; one that you will often find 19752yourself using when setting up fancy data plumbing. 19753 19754The @command{sort} 19755command reads and sorts each file named on the command line. It then 19756merges the sorted data and writes it to standard output. It will read 19757standard input if no files are given on the command line (thus 19758making it into a filter). The sort is based on the character collating 19759sequence or based on user-supplied ordering criteria. 19760 19761 19762@node The uniq command 19763@unnumberedsec The @command{uniq} Command 19764 19765Finally (at least for now), we'll look at the @command{uniq} program. When 19766sorting data, you will often end up with duplicate lines, lines that 19767are identical. Usually, all you need is one instance of each line. 19768This is where @command{uniq} comes in. The @command{uniq} program reads its 19769standard input. It prints only one 19770copy of each repeated line. It does have several options. Later on, 19771we'll use the @option{-c} option, which prints each unique line, preceded 19772by a count of the number of times that line occurred in the input. 19773 19774 19775@node Putting the tools together 19776@unnumberedsec Putting the Tools Together 19777 19778Now, let's suppose this is a large ISP server system with dozens of users 19779logged in. The management wants the system administrator to write a 19780program that will 19781generate a sorted list of logged in users. Furthermore, even if a user 19782is logged in multiple times, his or her name should only show up in the 19783output once. 19784 19785The administrator could sit down with the system documentation and write a C 19786program that did this. It would take perhaps a couple of hundred lines 19787of code and about two hours to write it, test it, and debug it. 19788However, knowing the software toolbox, the administrator can instead start out 19789by generating just a list of logged on users: 19790 19791@example 19792$ who | cut -c1-8 19793@print{} arnold 19794@print{} miriam 19795@print{} bill 19796@print{} arnold 19797@end example 19798 19799Next, sort the list: 19800 19801@example 19802$ who | cut -c1-8 | sort 19803@print{} arnold 19804@print{} arnold 19805@print{} bill 19806@print{} miriam 19807@end example 19808 19809Finally, run the sorted list through @command{uniq}, to weed out duplicates: 19810 19811@example 19812$ who | cut -c1-8 | sort | uniq 19813@print{} arnold 19814@print{} bill 19815@print{} miriam 19816@end example 19817 19818The @command{sort} command actually has a @option{-u} option that does what 19819@command{uniq} does. However, @command{uniq} has other uses for which one 19820cannot substitute @samp{sort -u}. 19821 19822The administrator puts this pipeline into a shell script, and makes it 19823available for 19824all the users on the system (@samp{#} is the system administrator, 19825or @code{root}, prompt): 19826 19827@example 19828# cat > /usr/local/bin/listusers 19829who | cut -c1-8 | sort | uniq 19830^D 19831# chmod +x /usr/local/bin/listusers 19832@end example 19833 19834There are four major points to note here. First, with just four 19835programs, on one command line, the administrator was able to save about two 19836hours worth of work. Furthermore, the shell pipeline is just about as 19837efficient as the C program would be, and it is much more efficient in 19838terms of programmer time. People time is much more expensive than 19839computer time, and in our modern ``there's never enough time to do 19840everything'' society, saving two hours of programmer time is no mean 19841feat. 19842 19843Second, it is also important to emphasize that with the 19844@emph{combination} of the tools, it is possible to do a special 19845purpose job never imagined by the authors of the individual programs. 19846 19847Third, it is also valuable to build up your pipeline in stages, as we did here. 19848This allows you to view the data at each stage in the pipeline, which helps 19849you acquire the confidence that you are indeed using these tools correctly. 19850 19851Finally, by bundling the pipeline in a shell script, other users can use 19852your command, without having to remember the fancy plumbing you set up for 19853them. In terms of how you run them, shell scripts and compiled programs are 19854indistinguishable. 19855 19856After the previous warm-up exercise, we'll look at two additional, more 19857complicated pipelines. For them, we need to introduce two more tools. 19858 19859The first is the @command{tr} command, which stands for ``transliterate.'' 19860The @command{tr} command works on a character-by-character basis, changing 19861characters. Normally it is used for things like mapping upper case to 19862lower case: 19863 19864@example 19865$ echo ThIs ExAmPlE HaS MIXED case! | tr '[:upper:]' '[:lower:]' 19866@print{} this example has mixed case! 19867@end example 19868 19869There are several options of interest: 19870 19871@table @code 19872@item -c 19873work on the complement of the listed characters, i.e., 19874operations apply to characters not in the given set 19875 19876@item -d 19877delete characters in the first set from the output 19878 19879@item -s 19880squeeze repeated characters in the output into just one character. 19881@end table 19882 19883We will be using all three options in a moment. 19884 19885The other command we'll look at is @command{comm}. The @command{comm} 19886command takes two sorted input files as input data, and prints out the 19887files' lines in three columns. The output columns are the data lines 19888unique to the first file, the data lines unique to the second file, and 19889the data lines that are common to both. The @option{-1}, @option{-2}, and 19890@option{-3} command line options @emph{omit} the respective columns. (This is 19891non-intuitive and takes a little getting used to.) For example: 19892 19893@example 19894$ cat f1 19895@print{} 11111 19896@print{} 22222 19897@print{} 33333 19898@print{} 44444 19899$ cat f2 19900@print{} 00000 19901@print{} 22222 19902@print{} 33333 19903@print{} 55555 19904$ comm f1 f2 19905@print{} 00000 19906@print{} 11111 19907@print{} 22222 19908@print{} 33333 19909@print{} 44444 19910@print{} 55555 19911@end example 19912 19913The file name @file{-} tells @command{comm} to read standard input 19914instead of a regular file. 19915 19916Now we're ready to build a fancy pipeline. The first application is a word 19917frequency counter. This helps an author determine if he or she is over-using 19918certain words. 19919 19920The first step is to change the case of all the letters in our input file 19921to one case. ``The'' and ``the'' are the same word when doing counting. 19922 19923@example 19924$ tr '[:upper:]' '[:lower:]' < whats.gnu | ... 19925@end example 19926 19927The next step is to get rid of punctuation. Quoted words and unquoted words 19928should be treated identically; it's easiest to just get the punctuation out of 19929the way. 19930 19931@example 19932$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | ... 19933@end example 19934 19935The second @command{tr} command operates on the complement of the listed 19936characters, which are all the letters, the digits, the underscore, and 19937the blank. The @samp{\n} represents the newline character; it has to 19938be left alone. (The ASCII tab character should also be included for 19939good measure in a production script.) 19940 19941At this point, we have data consisting of words separated by blank space. 19942The words only contain alphanumeric characters (and the underscore). The 19943next step is break the data apart so that we have one word per line. This 19944makes the counting operation much easier, as we will see shortly. 19945 19946@example 19947$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | 19948> tr -s ' ' '\n' | ... 19949@end example 19950 19951This command turns blanks into newlines. The @option{-s} option squeezes 19952multiple newline characters in the output into just one, removing 19953blank lines. (The @samp{>} is the shell's ``secondary prompt.'' 19954This is what the shell prints when it notices you haven't finished 19955typing in all of a command.) 19956 19957We now have data consisting of one word per line, no punctuation, all one 19958case. We're ready to count each word: 19959 19960@example 19961$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | 19962> tr -s ' ' '\n' | sort | uniq -c | ... 19963@end example 19964 19965At this point, the data might look something like this: 19966 19967@example 19968 60 a 19969 2 able 19970 6 about 19971 1 above 19972 2 accomplish 19973 1 acquire 19974 1 actually 19975 2 additional 19976@end example 19977 19978The output is sorted by word, not by count! What we want is the most 19979frequently used words first. Fortunately, this is easy to accomplish, 19980with the help of two more @command{sort} options: 19981 19982@table @code 19983@item -n 19984do a numeric sort, not a textual one 19985 19986@item -r 19987reverse the order of the sort 19988@end table 19989 19990The final pipeline looks like this: 19991 19992@example 19993$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | 19994> tr -s ' ' '\n' | sort | uniq -c | sort -n -r 19995@print{} 156 the 19996@print{} 60 a 19997@print{} 58 to 19998@print{} 51 of 19999@print{} 51 and 20000@dots{} 20001@end example 20002 20003Whew! That's a lot to digest. Yet, the same principles apply. With six 20004commands, on two lines (really one long one split for convenience), we've 20005created a program that does something interesting and useful, in much 20006less time than we could have written a C program to do the same thing. 20007 20008A minor modification to the above pipeline can give us a simple spelling 20009checker! To determine if you've spelled a word correctly, all you have to 20010do is look it up in a dictionary. If it is not there, then chances are 20011that your spelling is incorrect. So, we need a dictionary. 20012The conventional location for a dictionary is @file{/usr/share/dict/words}. 20013 20014Now, how to compare our file with the dictionary? As before, we generate 20015a sorted list of words, one per line: 20016 20017@example 20018$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | 20019> tr -s ' ' '\n' | sort -u | ... 20020@end example 20021 20022Now, all we need is a list of words that are @emph{not} in the 20023dictionary. Here is where the @command{comm} command comes in. 20024Unfortunately @command{comm} operates on sorted input and 20025@file{/usr/share/dict/words} is not sorted the way that @command{sort} 20026and @command{comm} normally use, so we first create a properly-sorted 20027copy of the dictionary and then run a pipeline that uses the copy. 20028 20029@example 20030$ sort /usr/share/dict/words > sorted-words 20031$ tr '[:upper:]' '[:lower:]' < whats.gnu | tr -cd '[:alnum:]_ \n' | 20032> tr -s ' ' '\n' | sort -u | 20033> comm -23 - sorted-words 20034@end example 20035 20036The @option{-2} and @option{-3} options eliminate lines that are only in the 20037dictionary (the second file), and lines that are in both files. Lines 20038only in the first file (standard input, our stream of words), are 20039words that are not in the dictionary. These are likely candidates for 20040spelling errors. This pipeline was the first cut at a production 20041spelling checker on Unix. 20042 20043There are some other tools that deserve brief mention. 20044 20045@table @command 20046@item grep 20047search files for text that matches a regular expression 20048 20049@item wc 20050count lines, words, characters 20051 20052@item tee 20053a T-fitting for data pipes, copies data to files and to standard output 20054 20055@item sed 20056the stream editor, an advanced tool 20057 20058@item awk 20059a data manipulation language, another advanced tool 20060@end table 20061 20062The software tools philosophy also espoused the following bit of 20063advice: ``Let someone else do the hard part.'' This means, take 20064something that gives you most of what you need, and then massage it the 20065rest of the way until it's in the form that you want. 20066 20067To summarize: 20068 20069@enumerate 1 20070@item 20071Each program should do one thing well. No more, no less. 20072 20073@item 20074Combining programs with appropriate plumbing leads to results where 20075the whole is greater than the sum of the parts. It also leads to novel 20076uses of programs that the authors might never have imagined. 20077 20078@item 20079Programs should never print extraneous header or trailer data, since these 20080could get sent on down a pipeline. (A point we didn't mention earlier.) 20081 20082@item 20083Let someone else do the hard part. 20084 20085@item 20086Know your toolbox! Use each program appropriately. If you don't have an 20087appropriate tool, build one. 20088@end enumerate 20089 20090All the programs discussed are available as described in 20091@uref{https://www.gnu.org/software/coreutils/coreutils.html, 20092GNU core utilities}. 20093 20094None of what I have presented in this column is new. The Software Tools 20095philosophy was first introduced in the book @cite{Software Tools}, by 20096Brian Kernighan and P.J. Plauger (Addison-Wesley, ISBN 0-201-03669-X). 20097This book showed how to write and use software tools. It was written in 200981976, using a preprocessor for FORTRAN named @command{ratfor} (RATional 20099FORtran). At the time, C was not as ubiquitous as it is now; FORTRAN 20100was. The last chapter presented a @command{ratfor} to FORTRAN 20101processor, written in @command{ratfor}. @command{ratfor} looks an awful 20102lot like C; if you know C, you won't have any problem following the 20103code. 20104 20105In 1981, the book was updated and made available as @cite{Software Tools 20106in Pascal} (Addison-Wesley, ISBN 0-201-10342-7). Both books are 20107still in print and are well worth 20108reading if you're a programmer. They certainly made a major change in 20109how I view programming. 20110 20111The programs in both books are available from 20112@uref{https://www.cs.princeton.edu/~bwk/, Brian Kernighan's home page}. 20113For a number of years, there was an active 20114Software Tools Users Group, whose members had ported the original 20115@command{ratfor} programs to essentially every computer system with a 20116FORTRAN compiler. The popularity of the group waned in the middle 1980s 20117as Unix began to spread beyond universities. 20118 20119With the current proliferation of GNU code and other clones of Unix programs, 20120these programs now receive little attention; modern C versions are 20121much more efficient and do more than these programs do. Nevertheless, as 20122exposition of good programming style, and evangelism for a still-valuable 20123philosophy, these books are unparalleled, and I recommend them highly. 20124 20125Acknowledgment: I would like to express my gratitude to Brian Kernighan 20126of Bell Labs, the original Software Toolsmith, for reviewing this column. 20127 20128@node GNU Free Documentation License 20129@appendix GNU Free Documentation License 20130 20131@include fdl.texi 20132 20133@node Concept index 20134@unnumbered Index 20135 20136@printindex cp 20137 20138@bye 20139 20140@c Local variables: 20141@c texinfo-column-for-description: 32 20142@c End: 20143