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