1.\" Copyright (c) 2003-2007 Tim Kientzle 2.\" Copyright (c) 2017 Martin Matuska 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd January 31, 2020 29.Dt TAR 1 30.Os 31.Sh NAME 32.Nm tar 33.Nd manipulate tape archives 34.Sh SYNOPSIS 35.Nm 36.Op Ar bundled-flags Ao args Ac 37.Op Ao Ar file Ac | Ao Ar pattern Ac ... 38.Nm 39.Brq Fl c 40.Op Ar options 41.Op Ar files | Ar directories 42.Nm 43.Brq Fl r | Fl u 44.Fl f Ar archive-file 45.Op Ar options 46.Op Ar files | Ar directories 47.Nm 48.Brq Fl t | Fl x 49.Op Ar options 50.Op Ar patterns 51.Sh DESCRIPTION 52.Nm 53creates and manipulates streaming archive files. 54This implementation can extract from tar, pax, cpio, zip, jar, ar, xar, 55rpm, 7-zip, and ISO 9660 cdrom images and can create tar, pax, cpio, ar, zip, 567-zip, and shar archives. 57.Pp 58The first synopsis form shows a 59.Dq bundled 60option word. 61This usage is provided for compatibility with historical implementations. 62See COMPATIBILITY below for details. 63.Pp 64The other synopsis forms show the preferred usage. 65The first option to 66.Nm 67is a mode indicator from the following list: 68.Bl -tag -compact -width indent 69.It Fl c 70Create a new archive containing the specified items. 71The long option form is 72.Fl Fl create . 73.It Fl r 74Like 75.Fl c , 76but new entries are appended to the archive. 77Note that this only works on uncompressed archives stored in regular files. 78The 79.Fl f 80option is required. 81The long option form is 82.Fl Fl append . 83.It Fl t 84List archive contents to stdout. 85The long option form is 86.Fl Fl list . 87.It Fl u 88Like 89.Fl r , 90but new entries are added only if they have a modification date 91newer than the corresponding entry in the archive. 92Note that this only works on uncompressed archives stored in regular files. 93The 94.Fl f 95option is required. 96The long form is 97.Fl Fl update . 98.It Fl x 99Extract to disk from the archive. 100If a file with the same name appears more than once in the archive, 101each copy will be extracted, with later copies overwriting (replacing) 102earlier copies. 103The long option form is 104.Fl Fl extract . 105.El 106.Pp 107In 108.Fl c , 109.Fl r , 110or 111.Fl u 112mode, each specified file or directory is added to the 113archive in the order specified on the command line. 114By default, the contents of each directory are also archived. 115.Pp 116In extract or list mode, the entire command line 117is read and parsed before the archive is opened. 118The pathnames or patterns on the command line indicate 119which items in the archive should be processed. 120Patterns are shell-style globbing patterns as 121documented in 122.Xr tcsh 1 . 123.Sh OPTIONS 124Unless specifically stated otherwise, options are applicable in 125all operating modes. 126.Bl -tag -width indent 127.It Cm @ Ns Pa archive 128(c and r modes only) 129The specified archive is opened and the entries 130in it will be appended to the current archive. 131As a simple example, 132.Dl Nm Fl c Fl f Pa - Pa newfile Cm @ Ns Pa original.tar 133writes a new archive to standard output containing a file 134.Pa newfile 135and all of the entries from 136.Pa original.tar . 137In contrast, 138.Dl Nm Fl c Fl f Pa - Pa newfile Pa original.tar 139creates a new archive with only two entries. 140Similarly, 141.Dl Nm Fl czf Pa - Fl Fl format Cm pax Cm @ Ns Pa - 142reads an archive from standard input (whose format will be determined 143automatically) and converts it into a gzip-compressed 144pax-format archive on stdout. 145In this way, 146.Nm 147can be used to convert archives from one format to another. 148.It Fl a , Fl Fl auto-compress 149(c mode only) 150Use the archive suffix to decide a set of the format and 151the compressions. 152As a simple example, 153.Dl Nm Fl a Fl cf Pa archive.tgz source.c source.h 154creates a new archive with restricted pax format and gzip compression, 155.Dl Nm Fl a Fl cf Pa archive.tar.bz2.uu source.c source.h 156creates a new archive with restricted pax format and bzip2 compression 157and uuencode compression, 158.Dl Nm Fl a Fl cf Pa archive.zip source.c source.h 159creates a new archive with zip format, 160.Dl Nm Fl a Fl jcf Pa archive.tgz source.c source.h 161ignores the 162.Dq -j 163option, and creates a new archive with restricted pax format 164and gzip compression, 165.Dl Nm Fl a Fl jcf Pa archive.xxx source.c source.h 166if it is unknown suffix or no suffix, creates a new archive with 167restricted pax format and bzip2 compression. 168.It Fl Fl acls 169(c, r, u, x modes only) 170Archive or extract POSIX.1e or NFSv4 ACLs. 171This is the reverse of 172.Fl Fl no-acls 173and the default behavior in c, r, and u modes (except on Mac OS X) or if 174.Nm 175is run in x mode as root. 176On Mac OS X this option translates extended ACLs to NFSv4 ACLs. 177To store extended ACLs the 178.Fl Fl mac-metadata 179option is preferred. 180.It Fl B , Fl Fl read-full-blocks 181Ignored for compatibility with other 182.Xr tar 1 183implementations. 184.It Fl b Ar blocksize , Fl Fl block-size Ar blocksize 185Specify the block size, in 512-byte records, for tape drive I/O. 186As a rule, this argument is only needed when reading from or writing 187to tape drives, and usually not even then as the default block size of 18820 records (10240 bytes) is very common. 189.It Fl C Ar directory , Fl Fl cd Ar directory , Fl Fl directory Ar directory 190In c and r mode, this changes the directory before adding 191the following files. 192In x mode, change directories after opening the archive 193but before extracting entries from the archive. 194.It Fl Fl chroot 195(x mode only) 196.Fn chroot 197to the current directory after processing any 198.Fl C 199options and before extracting any files. 200.It Fl Fl clear-nochange-fflags 201(x mode only) 202Before removing file system objects to replace them, clear platform-specific 203file attributes or file flags that might prevent removal. 204.It Fl Fl exclude Ar pattern 205Do not process files or directories that match the 206specified pattern. 207Note that exclusions take precedence over patterns or filenames 208specified on the command line. 209.It Fl Fl exclude-vcs 210Do not process files or directories internally used by the 211version control systems 212.Sq Arch , 213.Sq Bazaar , 214.Sq CVS , 215.Sq Darcs , 216.Sq Mercurial , 217.Sq RCS , 218.Sq SCCS , 219.Sq SVN 220and 221.Sq git . 222.It Fl Fl fflags 223(c, r, u, x modes only) 224Archive or extract platform-specific file attributes or file flags. 225This is the reverse of 226.Fl Fl no-fflags 227and the default behavior in c, r, and u modes or if 228.Nm 229is run in x mode as root. 230.It Fl Fl format Ar format 231(c, r, u mode only) 232Use the specified format for the created archive. 233Supported formats include 234.Dq cpio , 235.Dq pax , 236.Dq shar , 237and 238.Dq ustar . 239Other formats may also be supported; see 240.Xr libarchive-formats 5 241for more information about currently-supported formats. 242In r and u modes, when extending an existing archive, the format specified 243here must be compatible with the format of the existing archive on disk. 244.It Fl f Ar file , Fl Fl file Ar file 245Read the archive from or write the archive to the specified file. 246The filename can be 247.Pa - 248for standard input or standard output. 249The default varies by system; 250on 251.Fx , 252the default is 253.Pa /dev/sa0 ; 254on Linux, the default is 255.Pa /dev/st0 . 256.It Fl Fl gid Ar id 257Use the provided group id number. 258On extract, this overrides the group id in the archive; 259the group name in the archive will be ignored. 260On create, this overrides the group id read from disk; 261if 262.Fl Fl gname 263is not also specified, the group name will be set to 264match the group id. 265.It Fl Fl gname Ar name 266Use the provided group name. 267On extract, this overrides the group name in the archive; 268if the provided group name does not exist on the system, 269the group id 270(from the archive or from the 271.Fl Fl gid 272option) 273will be used instead. 274On create, this sets the group name that will be stored 275in the archive; 276the name will not be verified against the system group database. 277.It Fl H 278(c and r modes only) 279Symbolic links named on the command line will be followed; the 280target of the link will be archived, not the link itself. 281.It Fl h 282(c and r modes only) 283Synonym for 284.Fl L . 285.It Fl I 286Synonym for 287.Fl T . 288.It Fl Fl help 289Show usage. 290.It Fl Fl hfsCompression 291(x mode only) 292Mac OS X specific (v10.6 or later). Compress extracted regular files with HFS+ 293compression. 294.It Fl Fl ignore-zeros 295An alias of 296.Fl Fl options Cm read_concatenated_archives 297for compatibility with GNU tar. 298.It Fl Fl include Ar pattern 299Process only files or directories that match the specified pattern. 300Note that exclusions specified with 301.Fl Fl exclude 302take precedence over inclusions. 303If no inclusions are explicitly specified, all entries are processed by 304default. 305The 306.Fl Fl include 307option is especially useful when filtering archives. 308For example, the command 309.Dl Nm Fl c Fl f Pa new.tar Fl Fl include='*foo*' Cm @ Ns Pa old.tgz 310creates a new archive 311.Pa new.tar 312containing only the entries from 313.Pa old.tgz 314containing the string 315.Sq foo . 316.It Fl J , Fl Fl xz 317(c mode only) 318Compress the resulting archive with 319.Xr xz 1 . 320In extract or list modes, this option is ignored. 321Note that this 322.Nm tar 323implementation recognizes XZ compression automatically when reading archives. 324.It Fl j , Fl Fl bzip , Fl Fl bzip2 , Fl Fl bunzip2 325(c mode only) 326Compress the resulting archive with 327.Xr bzip2 1 . 328In extract or list modes, this option is ignored. 329Note that this 330.Nm tar 331implementation recognizes bzip2 compression automatically when reading 332archives. 333.It Fl k , Fl Fl keep-old-files 334(x mode only) 335Do not overwrite existing files. 336In particular, if a file appears more than once in an archive, 337later copies will not overwrite earlier copies. 338.It Fl Fl keep-newer-files 339(x mode only) 340Do not overwrite existing files that are newer than the 341versions appearing in the archive being extracted. 342.It Fl L , Fl Fl dereference 343(c and r modes only) 344All symbolic links will be followed. 345Normally, symbolic links are archived as such. 346With this option, the target of the link will be archived instead. 347.It Fl l , Fl Fl check-links 348(c and r modes only) 349Issue a warning message unless all links to each file are archived. 350.It Fl Fl lrzip 351(c mode only) 352Compress the resulting archive with 353.Xr lrzip 1 . 354In extract or list modes, this option is ignored. 355Note that this 356.Nm tar 357implementation recognizes lrzip compression automatically when reading 358archives. 359.It Fl Fl lz4 360(c mode only) 361Compress the archive with lz4-compatible compression before writing it. 362In extract or list modes, this option is ignored. 363Note that this 364.Nm tar 365implementation recognizes lz4 compression automatically when reading archives. 366.It Fl Fl zstd 367(c mode only) 368Compress the archive with zstd-compatible compression before writing it. 369In extract or list modes, this option is ignored. 370Note that this 371.Nm tar 372implementation recognizes zstd compression automatically when reading archives. 373.It Fl Fl lzma 374(c mode only) Compress the resulting archive with the original LZMA algorithm. 375In extract or list modes, this option is ignored. 376Use of this option is discouraged and new archives should be created with 377.Fl Fl xz 378instead. 379Note that this 380.Nm tar 381implementation recognizes LZMA compression automatically when reading archives. 382.It Fl Fl lzop 383(c mode only) 384Compress the resulting archive with 385.Xr lzop 1 . 386In extract or list modes, this option is ignored. 387Note that this 388.Nm tar 389implementation recognizes LZO compression automatically when reading archives. 390.It Fl m , Fl Fl modification-time 391(x mode only) 392Do not extract modification time. 393By default, the modification time is set to the time stored in the archive. 394.It Fl Fl mac-metadata 395(c, r, u and x mode only) 396Mac OS X specific. 397Archive or extract extended ACLs and extended file 398attributes using 399.Xr copyfile 3 400in AppleDouble format. 401This is the reverse of 402.Fl Fl no-mac-metadata . 403and the default behavior in c, r, and u modes or if 404.Nm 405is run in x mode as root. 406.It Fl n , Fl Fl norecurse , Fl Fl no-recursion 407Do not operate recursively on the content of directories. 408.It Fl Fl newer Ar date 409(c, r, u modes only) 410Only include files and directories newer than the specified date. 411This compares ctime entries. 412.It Fl Fl newer-mtime Ar date 413(c, r, u modes only) 414Like 415.Fl Fl newer , 416except it compares mtime entries instead of ctime entries. 417.It Fl Fl newer-than Pa file 418(c, r, u modes only) 419Only include files and directories newer than the specified file. 420This compares ctime entries. 421.It Fl Fl newer-mtime-than Pa file 422(c, r, u modes only) 423Like 424.Fl Fl newer-than , 425except it compares mtime entries instead of ctime entries. 426.It Fl Fl nodump 427(c and r modes only) 428Honor the nodump file flag by skipping this file. 429.It Fl Fl nopreserveHFSCompression 430(x mode only) 431Mac OS X specific (v10.6 or later). Do not compress extracted regular files 432which were compressed with HFS+ compression before archived. 433By default, compress the regular files again with HFS+ compression. 434.It Fl Fl null 435(use with 436.Fl I 437or 438.Fl T ) 439Filenames or patterns are separated by null characters, 440not by newlines. 441This is often used to read filenames output by the 442.Fl print0 443option to 444.Xr find 1 . 445.It Fl Fl no-acls 446(c, r, u, x modes only) 447Do not archive or extract POSIX.1e or NFSv4 ACLs. 448This is the reverse of 449.Fl Fl acls 450and the default behavior if 451.Nm 452is run as non-root in x mode (on Mac OS X as any user in c, r, u and x modes). 453.It Fl Fl no-fflags 454(c, r, u, x modes only) 455Do not archive or extract file attributes or file flags. 456This is the reverse of 457.Fl Fl fflags 458and the default behavior if 459.Nm 460is run as non-root in x mode. 461.It Fl Fl no-mac-metadata 462(x mode only) 463Mac OS X specific. 464Do not archive or extract ACLs and extended file attributes 465using 466.Xr copyfile 3 467in AppleDouble format. 468This is the reverse of 469.Fl Fl mac-metadata . 470and the default behavior if 471.Nm 472is run as non-root in x mode. 473.It Fl Fl no-safe-writes 474(x mode only) 475Do not create temporary files and use 476.Xr rename 2 477to replace the original ones. 478This is the reverse of 479.Fl Fl safe-writes . 480.It Fl Fl no-same-owner 481(x mode only) 482Do not extract owner and group IDs. 483This is the reverse of 484.Fl Fl same-owner 485and the default behavior if 486.Nm 487is run as non-root. 488.It Fl Fl no-same-permissions 489(x mode only) 490Do not extract full permissions (SGID, SUID, sticky bit, 491file attributes or file flags, extended file attributes and ACLs). 492This is the reverse of 493.Fl p 494and the default behavior if 495.Nm 496is run as non-root. 497.It Fl Fl no-xattrs 498(c, r, u, x modes only) 499Do not archive or extract extended file attributes. 500This is the reverse of 501.Fl Fl xattrs 502and the default behavior if 503.Nm 504is run as non-root in x mode. 505.It Fl Fl numeric-owner 506This is equivalent to 507.Fl Fl uname 508.Qq 509.Fl Fl gname 510.Qq . 511On extract, it causes user and group names in the archive 512to be ignored in favor of the numeric user and group ids. 513On create, it causes user and group names to not be stored 514in the archive. 515.It Fl O , Fl Fl to-stdout 516(x, t modes only) 517In extract (-x) mode, files will be written to standard out rather than 518being extracted to disk. 519In list (-t) mode, the file listing will be written to stderr rather than 520the usual stdout. 521.It Fl o 522(x mode) 523Use the user and group of the user running the program rather 524than those specified in the archive. 525Note that this has no significance unless 526.Fl p 527is specified, and the program is being run by the root user. 528In this case, the file modes and flags from 529the archive will be restored, but ACLs or owner information in 530the archive will be discarded. 531.It Fl o 532(c, r, u mode) 533A synonym for 534.Fl Fl format Ar ustar 535.It Fl Fl older Ar date 536(c, r, u modes only) 537Only include files and directories older than the specified date. 538This compares ctime entries. 539.It Fl Fl older-mtime Ar date 540(c, r, u modes only) 541Like 542.Fl Fl older , 543except it compares mtime entries instead of ctime entries. 544.It Fl Fl older-than Pa file 545(c, r, u modes only) 546Only include files and directories older than the specified file. 547This compares ctime entries. 548.It Fl Fl older-mtime-than Pa file 549(c, r, u modes only) 550Like 551.Fl Fl older-than , 552except it compares mtime entries instead of ctime entries. 553.It Fl Fl one-file-system 554(c, r, and u modes) 555Do not cross mount points. 556.It Fl Fl options Ar options 557Select optional behaviors for particular modules. 558The argument is a text string containing comma-separated 559keywords and values. 560These are passed to the modules that handle particular 561formats to control how those formats will behave. 562Each option has one of the following forms: 563.Bl -tag -compact -width indent 564.It Ar key=value 565The key will be set to the specified value in every module that supports it. 566Modules that do not support this key will ignore it. 567.It Ar key 568The key will be enabled in every module that supports it. 569This is equivalent to 570.Ar key Ns Cm =1 . 571.It Ar !key 572The key will be disabled in every module that supports it. 573.It Ar module:key=value , Ar module:key , Ar module:!key 574As above, but the corresponding key and value will be provided 575only to modules whose name matches 576.Ar module . 577.El 578.Pp 579The complete list of supported modules and keys 580for create and append modes is in 581.Xr archive_write_set_options 3 582and for extract and list modes in 583.Xr archive_read_set_options 3 . 584.Pp 585Examples of supported options: 586.Bl -tag -compact -width indent 587.It Cm iso9660:joliet 588Support Joliet extensions. 589This is enabled by default, use 590.Cm !joliet 591or 592.Cm iso9660:!joliet 593to disable. 594.It Cm iso9660:rockridge 595Support Rock Ridge extensions. 596This is enabled by default, use 597.Cm !rockridge 598or 599.Cm iso9660:!rockridge 600to disable. 601.It Cm gzip:compression-level 602A decimal integer from 1 to 9 specifying the gzip compression level. 603.It Cm gzip:timestamp 604Store timestamp. 605This is enabled by default, use 606.Cm !timestamp 607or 608.Cm gzip:!timestamp 609to disable. 610.It Cm lrzip:compression Ns = Ns Ar type 611Use 612.Ar type 613as compression method. 614Supported values are bzip2, gzip, lzo (ultra fast), 615and zpaq (best, extremely slow). 616.It Cm lrzip:compression-level 617A decimal integer from 1 to 9 specifying the lrzip compression level. 618.It Cm lz4:compression-level 619A decimal integer from 1 to 9 specifying the lzop compression level. 620.It Cm lz4:stream-checksum 621Enable stream checksum. 622This is by default, use 623.Cm lz4:!stream-checksum 624to disable. 625.It Cm lz4:block-checksum 626Enable block checksum (Disabled by default). 627.It Cm lz4:block-size 628A decimal integer from 4 to 7 specifying the lz4 compression block size 629(7 is set by default). 630.It Cm lz4:block-dependence 631Use the previous block of the block being compressed for 632a compression dictionary to improve compression ratio. 633.It Cm zstd:compression-level 634A decimal integer from 1 to 22 specifying the zstd compression level. 635.It Cm lzop:compression-level 636A decimal integer from 1 to 9 specifying the lzop compression level. 637.It Cm xz:compression-level 638A decimal integer from 0 to 9 specifying the xz compression level. 639.It Cm mtree: Ns Ar keyword 640The mtree writer module allows you to specify which mtree keywords 641will be included in the output. 642Supported keywords include: 643.Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent , 644.Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 , 645.Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname . 646The default is equivalent to: 647.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname . 648.It Cm mtree:all 649Enables all of the above keywords. 650You can also use 651.Cm mtree:!all 652to disable all keywords. 653.It Cm mtree:use-set 654Enable generation of 655.Cm /set 656lines in the output. 657.It Cm mtree:indent 658Produce human-readable output by indenting options and splitting lines 659to fit into 80 columns. 660.It Cm zip:compression Ns = Ns Ar type 661Use 662.Ar type 663as compression method. 664Supported values are store (uncompressed) and deflate (gzip algorithm). 665.It Cm zip:encryption 666Enable encryption using traditional zip encryption. 667.It Cm zip:encryption Ns = Ns Ar type 668Use 669.Ar type 670as encryption type. 671Supported values are zipcrypt (traditional zip encryption), 672aes128 (WinZip AES-128 encryption) and aes256 (WinZip AES-256 encryption). 673.It Cm read_concatenated_archives 674Ignore zeroed blocks in the archive, which occurs when multiple tar archives 675have been concatenated together. 676Without this option, only the contents of 677the first concatenated archive would be read. 678This option is comparable to the 679.Fl i , Fl Fl ignore-zeros 680option of GNU tar. 681.El 682If a provided option is not supported by any module, that 683is a fatal error. 684.It Fl P , Fl Fl absolute-paths 685Preserve pathnames. 686By default, absolute pathnames (those that begin with a / 687character) have the leading slash removed both when creating archives 688and extracting from them. 689Also, 690.Nm 691will refuse to extract archive entries whose pathnames contain 692.Pa .. 693or whose target directory would be altered by a symlink. 694This option suppresses these behaviors. 695.It Fl p , Fl Fl insecure , Fl Fl preserve-permissions 696(x mode only) 697Preserve file permissions. 698Attempt to restore the full permissions, including file modes, file attributes 699or file flags, extended file attributes and ACLs, if available, for each item 700extracted from the archive. 701This is the reverse of 702.Fl Fl no-same-permissions 703and the default if 704.Nm 705is being run as root. 706It can be partially overridden by also specifying 707.Fl Fl no-acls , 708.Fl Fl no-fflags , 709.Fl Fl no-mac-metadata 710or 711.Fl Fl no-xattrs . 712.It Fl Fl passphrase Ar passphrase 713The 714.Pa passphrase 715is used to extract or create an encrypted archive. 716Currently, zip is the only supported format that supports encryption. 717You shouldn't use this option unless you realize how insecure 718use of this option is. 719.It Fl Fl posix 720(c, r, u mode only) 721Synonym for 722.Fl Fl format Ar pax 723.It Fl q , Fl Fl fast-read 724(x and t mode only) 725Extract or list only the first archive entry that matches each pattern 726or filename operand. 727Exit as soon as each specified pattern or filename has been matched. 728By default, the archive is always read to the very end, since 729there can be multiple entries with the same name and, by convention, 730later entries overwrite earlier entries. 731This option is provided as a performance optimization. 732.It Fl S 733(x mode only) 734Extract files as sparse files. 735For every block on disk, check first if it contains only NULL bytes and seek 736over it otherwise. 737This works similar to the conv=sparse option of dd. 738.It Fl s Ar pattern 739Modify file or archive member names according to 740.Pa pattern . 741The pattern has the format 742.Ar /old/new/ Ns Op ghHprRsS 743where 744.Ar old 745is a basic regular expression, 746.Ar new 747is the replacement string of the matched part, 748and the optional trailing letters modify 749how the replacement is handled. 750If 751.Ar old 752is not matched, the pattern is skipped. 753Within 754.Ar new , 755~ is substituted with the match, \e1 to \e9 with the content of 756the corresponding captured group. 757The optional trailing g specifies that matching should continue 758after the matched part and stop on the first unmatched pattern. 759The optional trailing s specifies that the pattern applies to the value 760of symbolic links. 761The optional trailing p specifies that after a successful substitution 762the original path name and the new path name should be printed to 763standard error. 764Optional trailing H, R, or S characters suppress substitutions 765for hardlink targets, regular filenames, or symlink targets, 766respectively. 767Optional trailing h, r, or s characters enable substitutions 768for hardlink targets, regular filenames, or symlink targets, 769respectively. 770The default is 771.Ar hrs 772which applies substitutions to all names. 773In particular, it is never necessary to specify h, r, or s. 774.It Fl Fl safe-writes 775(x mode only) 776Extract files atomically. 777By default 778.Nm 779unlinks the original file with the same name as the extracted file (if it 780exists), and then creates it immediately under the same name and writes to 781it. 782For a short period of time, applications trying to access the file might 783not find it, or see incomplete results. 784If 785.Fl Fl safe-writes 786is enabled, 787.Nm 788first creates a unique temporary file, then writes the new contents to 789the temporary file, and finally renames the temporary file to its final 790name atomically using 791.Xr rename 2 . 792This guarantees that an application accessing the file, will either see 793the old contents or the new contents at all times. 794.It Fl Fl same-owner 795(x mode only) 796Extract owner and group IDs. 797This is the reverse of 798.Fl Fl no-same-owner 799and the default behavior if 800.Nm 801is run as root. 802.It Fl Fl strip-components Ar count 803Remove the specified number of leading path elements. 804Pathnames with fewer elements will be silently skipped. 805Note that the pathname is edited after checking inclusion/exclusion patterns 806but before security checks. 807.It Fl T Ar filename , Fl Fl files-from Ar filename 808In x or t mode, 809.Nm 810will read the list of names to be extracted from 811.Pa filename . 812In c mode, 813.Nm 814will read names to be archived from 815.Pa filename . 816The special name 817.Dq -C 818on a line by itself will cause the current directory to be changed to 819the directory specified on the following line. 820Names are terminated by newlines unless 821.Fl Fl null 822is specified. 823Note that 824.Fl Fl null 825also disables the special handling of lines containing 826.Dq -C . 827Note: If you are generating lists of files using 828.Xr find 1 , 829you probably want to use 830.Fl n 831as well. 832.It Fl Fl totals 833(c, r, u modes only) 834After archiving all files, print a summary to stderr. 835.It Fl U , Fl Fl unlink , Fl Fl unlink-first 836(x mode only) 837Unlink files before creating them. 838This can be a minor performance optimization if most files 839already exist, but can make things slower if most files 840do not already exist. 841This flag also causes 842.Nm 843to remove intervening directory symlinks instead of 844reporting an error. 845See the SECURITY section below for more details. 846.It Fl Fl uid Ar id 847Use the provided user id number and ignore the user 848name from the archive. 849On create, if 850.Fl Fl uname 851is not also specified, the user name will be set to 852match the user id. 853.It Fl Fl uname Ar name 854Use the provided user name. 855On extract, this overrides the user name in the archive; 856if the provided user name does not exist on the system, 857it will be ignored and the user id 858(from the archive or from the 859.Fl Fl uid 860option) 861will be used instead. 862On create, this sets the user name that will be stored 863in the archive; 864the name is not verified against the system user database. 865.It Fl Fl use-compress-program Ar program 866Pipe the input (in x or t mode) or the output (in c mode) through 867.Pa program 868instead of using the builtin compression support. 869.It Fl v , Fl Fl verbose 870Produce verbose output. 871In create and extract modes, 872.Nm 873will list each file name as it is read from or written to 874the archive. 875In list mode, 876.Nm 877will produce output similar to that of 878.Xr ls 1 . 879An additional 880.Fl v 881option will also provide ls-like details in create and extract mode. 882.It Fl Fl version 883Print version of 884.Nm 885and 886.Nm libarchive , 887and exit. 888.It Fl w , Fl Fl confirmation , Fl Fl interactive 889Ask for confirmation for every action. 890.It Fl X Ar filename , Fl Fl exclude-from Ar filename 891Read a list of exclusion patterns from the specified file. 892See 893.Fl Fl exclude 894for more information about the handling of exclusions. 895.It Fl Fl xattrs 896(c, r, u, x modes only) 897Archive or extract extended file attributes. 898This is the reverse of 899.Fl Fl no-xattrs 900and the default behavior in c, r, and u modes or if 901.Nm 902is run in x mode as root. 903.It Fl y 904(c mode only) 905Compress the resulting archive with 906.Xr bzip2 1 . 907In extract or list modes, this option is ignored. 908Note that this 909.Nm tar 910implementation recognizes bzip2 compression automatically when reading 911archives. 912.It Fl Z , Fl Fl compress , Fl Fl uncompress 913(c mode only) 914Compress the resulting archive with 915.Xr compress 1 . 916In extract or list modes, this option is ignored. 917Note that this 918.Nm tar 919implementation recognizes compress compression automatically when reading 920archives. 921.It Fl z , Fl Fl gunzip , Fl Fl gzip 922(c mode only) 923Compress the resulting archive with 924.Xr gzip 1 . 925In extract or list modes, this option is ignored. 926Note that this 927.Nm tar 928implementation recognizes gzip compression automatically when reading 929archives. 930.El 931.Sh ENVIRONMENT 932The following environment variables affect the execution of 933.Nm : 934.Bl -tag -width ".Ev BLOCKSIZE" 935.It Ev TAR_READER_OPTIONS 936The default options for format readers and compression readers. 937The 938.Fl Fl options 939option overrides this. 940.It Ev TAR_WRITER_OPTIONS 941The default options for format writers and compression writers. 942The 943.Fl Fl options 944option overrides this. 945.It Ev LANG 946The locale to use. 947See 948.Xr environ 7 949for more information. 950.It Ev TAPE 951The default device. 952The 953.Fl f 954option overrides this. 955Please see the description of the 956.Fl f 957option above for more details. 958.It Ev TZ 959The timezone to use when displaying dates. 960See 961.Xr environ 7 962for more information. 963.El 964.Sh EXIT STATUS 965.Ex -std 966.Sh EXAMPLES 967The following creates a new archive 968called 969.Ar file.tar.gz 970that contains two files 971.Ar source.c 972and 973.Ar source.h : 974.Dl Nm Fl czf Pa file.tar.gz Pa source.c Pa source.h 975.Pp 976To view a detailed table of contents for this 977archive: 978.Dl Nm Fl tvf Pa file.tar.gz 979.Pp 980To extract all entries from the archive on 981the default tape drive: 982.Dl Nm Fl x 983.Pp 984To examine the contents of an ISO 9660 cdrom image: 985.Dl Nm Fl tf Pa image.iso 986.Pp 987To move file hierarchies, invoke 988.Nm 989as 990.Dl Nm Fl cf Pa - Fl C Pa srcdir \&. | Nm Fl xpf Pa - Fl C Pa destdir 991or more traditionally 992.Dl cd srcdir \&; Nm Fl cf Pa - \&. | ( cd destdir \&; Nm Fl xpf Pa - ) 993.Pp 994In create mode, the list of files and directories to be archived 995can also include directory change instructions of the form 996.Cm -C Ns Pa foo/baz 997and archive inclusions of the form 998.Cm @ Ns Pa archive-file . 999For example, the command line 1000.Dl Nm Fl c Fl f Pa new.tar Pa foo1 Cm @ Ns Pa old.tgz Cm -C Ns Pa /tmp Pa foo2 1001will create a new archive 1002.Pa new.tar . 1003.Nm 1004will read the file 1005.Pa foo1 1006from the current directory and add it to the output archive. 1007It will then read each entry from 1008.Pa old.tgz 1009and add those entries to the output archive. 1010Finally, it will switch to the 1011.Pa /tmp 1012directory and add 1013.Pa foo2 1014to the output archive. 1015.Pp 1016An input file in 1017.Xr mtree 5 1018format can be used to create an output archive with arbitrary ownership, 1019permissions, or names that differ from existing data on disk: 1020.Bd -literal -offset indent 1021$ cat input.mtree 1022#mtree 1023usr/bin uid=0 gid=0 mode=0755 type=dir 1024usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls 1025$ tar -cvf output.tar @input.mtree 1026.Ed 1027.Pp 1028The 1029.Fl Fl newer 1030and 1031.Fl Fl newer-mtime 1032switches accept a variety of common date and time specifications, including 1033.Dq 12 Mar 2005 7:14:29pm , 1034.Dq 2005-03-12 19:14 , 1035.Dq 5 minutes ago , 1036and 1037.Dq 19:14 PST May 1 . 1038.Pp 1039The 1040.Fl Fl options 1041argument can be used to control various details of archive generation 1042or reading. 1043For example, you can generate mtree output which only contains 1044.Cm type , Cm time , 1045and 1046.Cm uid 1047keywords: 1048.Dl Nm Fl cf Pa file.tar Fl Fl format=mtree Fl Fl options='!all,type,time,uid' Pa dir 1049or you can set the compression level used by gzip or xz compression: 1050.Dl Nm Fl czf Pa file.tar Fl Fl options='compression-level=9' . 1051For more details, see the explanation of the 1052.Fn archive_read_set_options 1053and 1054.Fn archive_write_set_options 1055API calls that are described in 1056.Xr archive_read 3 1057and 1058.Xr archive_write 3 . 1059.Sh COMPATIBILITY 1060The bundled-arguments format is supported for compatibility 1061with historic implementations. 1062It consists of an initial word (with no leading - character) in which 1063each character indicates an option. 1064Arguments follow as separate words. 1065The order of the arguments must match the order 1066of the corresponding characters in the bundled command word. 1067For example, 1068.Dl Nm Cm tbf 32 Pa file.tar 1069specifies three flags 1070.Cm t , 1071.Cm b , 1072and 1073.Cm f . 1074The 1075.Cm b 1076and 1077.Cm f 1078flags both require arguments, 1079so there must be two additional items 1080on the command line. 1081The 1082.Ar 32 1083is the argument to the 1084.Cm b 1085flag, and 1086.Ar file.tar 1087is the argument to the 1088.Cm f 1089flag. 1090.Pp 1091The mode options c, r, t, u, and x and the options 1092b, f, l, m, o, v, and w comply with SUSv2. 1093.Pp 1094For maximum portability, scripts that invoke 1095.Nm tar 1096should use the bundled-argument format above, should limit 1097themselves to the 1098.Cm c , 1099.Cm t , 1100and 1101.Cm x 1102modes, and the 1103.Cm b , 1104.Cm f , 1105.Cm m , 1106.Cm v , 1107and 1108.Cm w 1109options. 1110.Pp 1111Additional long options are provided to improve compatibility with other 1112tar implementations. 1113.Sh SECURITY 1114Certain security issues are common to many archiving programs, including 1115.Nm . 1116In particular, carefully-crafted archives can request that 1117.Nm 1118extract files to locations outside of the target directory. 1119This can potentially be used to cause unwitting users to overwrite 1120files they did not intend to overwrite. 1121If the archive is being extracted by the superuser, any file 1122on the system can potentially be overwritten. 1123There are three ways this can happen. 1124Although 1125.Nm 1126has mechanisms to protect against each one, 1127savvy users should be aware of the implications: 1128.Bl -bullet -width indent 1129.It 1130Archive entries can have absolute pathnames. 1131By default, 1132.Nm 1133removes the leading 1134.Pa / 1135character from filenames before restoring them to guard against this problem. 1136.It 1137Archive entries can have pathnames that include 1138.Pa .. 1139components. 1140By default, 1141.Nm 1142will not extract files containing 1143.Pa .. 1144components in their pathname. 1145.It 1146Archive entries can exploit symbolic links to restore 1147files to other directories. 1148An archive can restore a symbolic link to another directory, 1149then use that link to restore a file into that directory. 1150To guard against this, 1151.Nm 1152checks each extracted path for symlinks. 1153If the final path element is a symlink, it will be removed 1154and replaced with the archive entry. 1155If 1156.Fl U 1157is specified, any intermediate symlink will also be unconditionally removed. 1158If neither 1159.Fl U 1160nor 1161.Fl P 1162is specified, 1163.Nm 1164will refuse to extract the entry. 1165.El 1166To protect yourself, you should be wary of any archives that 1167come from untrusted sources. 1168You should examine the contents of an archive with 1169.Dl Nm Fl tf Pa filename 1170before extraction. 1171You should use the 1172.Fl k 1173option to ensure that 1174.Nm 1175will not overwrite any existing files or the 1176.Fl U 1177option to remove any pre-existing files. 1178You should generally not extract archives while running with super-user 1179privileges. 1180Note that the 1181.Fl P 1182option to 1183.Nm 1184disables the security checks above and allows you to extract 1185an archive while preserving any absolute pathnames, 1186.Pa .. 1187components, or symlinks to other directories. 1188.Sh SEE ALSO 1189.Xr bzip2 1 , 1190.Xr compress 1 , 1191.Xr cpio 1 , 1192.Xr gzip 1 , 1193.Xr mt 1 , 1194.Xr pax 1 , 1195.Xr shar 1 , 1196.Xr xz 1 , 1197.Xr libarchive 3 , 1198.Xr libarchive-formats 5 , 1199.Xr tar 5 1200.Sh STANDARDS 1201There is no current POSIX standard for the tar command; it appeared 1202in 1203.St -p1003.1-96 1204but was dropped from 1205.St -p1003.1-2001 . 1206The options supported by this implementation were developed by surveying a 1207number of existing tar implementations as well as the old POSIX specification 1208for tar and the current POSIX specification for pax. 1209.Pp 1210The ustar and pax interchange file formats are defined by 1211.St -p1003.1-2001 1212for the pax command. 1213.Sh HISTORY 1214A 1215.Nm tar 1216command appeared in Seventh Edition Unix, which was released in January, 1979. 1217There have been numerous other implementations, 1218many of which extended the file format. 1219John Gilmore's 1220.Nm pdtar 1221public-domain implementation (circa November, 1987) 1222was quite influential, and formed the basis of GNU tar. 1223GNU tar was included as the standard system tar 1224in 1225.Fx 1226beginning with 1227.Fx 1.0 . 1228.Pp 1229This is a complete re-implementation based on the 1230.Xr libarchive 3 1231library. 1232It was first released with 1233.Fx 5.4 1234in May, 2005. 1235.Sh BUGS 1236This program follows 1237.St -p1003.1-96 1238for the definition of the 1239.Fl l 1240option. 1241Note that GNU tar prior to version 1.15 treated 1242.Fl l 1243as a synonym for the 1244.Fl Fl one-file-system 1245option. 1246.Pp 1247The 1248.Fl C Pa dir 1249option may differ from historic implementations. 1250.Pp 1251All archive output is written in correctly-sized blocks, even 1252if the output is being compressed. 1253Whether or not the last output block is padded to a full 1254block size varies depending on the format and the 1255output device. 1256For tar and cpio formats, the last block of output is padded 1257to a full block size if the output is being 1258written to standard output or to a character or block device such as 1259a tape drive. 1260If the output is being written to a regular file, the last block 1261will not be padded. 1262Many compressors, including 1263.Xr gzip 1 1264and 1265.Xr bzip2 1 , 1266complain about the null padding when decompressing an archive created by 1267.Nm , 1268although they still extract it correctly. 1269.Pp 1270The compression and decompression is implemented internally, so 1271there may be insignificant differences between the compressed output 1272generated by 1273.Dl Nm Fl czf Pa - file 1274and that generated by 1275.Dl Nm Fl cf Pa - file | Nm gzip 1276.Pp 1277The default should be to read and write archives to the standard I/O paths, 1278but tradition (and POSIX) dictates otherwise. 1279.Pp 1280The 1281.Cm r 1282and 1283.Cm u 1284modes require that the archive be uncompressed 1285and located in a regular file on disk. 1286Other archives can be modified using 1287.Cm c 1288mode with the 1289.Pa @archive-file 1290extension. 1291.Pp 1292To archive a file called 1293.Pa @foo 1294or 1295.Pa -foo 1296you must specify it as 1297.Pa ./@foo 1298or 1299.Pa ./-foo , 1300respectively. 1301.Pp 1302In create mode, a leading 1303.Pa ./ 1304is always removed. 1305A leading 1306.Pa / 1307is stripped unless the 1308.Fl P 1309option is specified. 1310.Pp 1311There needs to be better support for file selection on both create 1312and extract. 1313.Pp 1314There is not yet any support for multi-volume archives. 1315.Pp 1316Converting between dissimilar archive formats (such as tar and cpio) using the 1317.Cm @ Ns Pa - 1318convention can cause hard link information to be lost. 1319(This is a consequence of the incompatible ways that different archive 1320formats store hardlink information.) 1321