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 BSDTAR 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 and ISO 9660 cdrom images and can create tar, pax, cpio, ar, zip, 55and 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 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 overriden 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 Fl same-owner 500(x mode only) 501Extract owner and group IDs. 502This is the reverse of 503.Fl Fl no-same-owner 504and the default behavior if 505.Nm 506is run as root. 507.It Fl Fl strip-components Ar count 508(x mode only) 509Remove the specified number of leading path elements. 510Pathnames with fewer elements will be silently skipped. 511Note that the pathname is edited after checking inclusion/exclusion patterns 512but before security checks. 513.It Fl s Ar pattern 514Modify file or archive member names according to 515.Pa pattern . 516The pattern has the format 517.Ar /old/new/ Ns Op gps 518where 519.Ar old 520is a basic regular expression, 521.Ar new 522is the replacement string of the matched part, 523and the optional trailing letters modify 524how the replacement is handled. 525If 526.Ar old 527is not matched, the pattern is skipped. 528Within 529.Ar new , 530~ is substituted with the match, \e1 to \e9 with the content of 531the corresponding captured group. 532The optional trailing g specifies that matching should continue 533after the matched part and stopped on the first unmatched pattern. 534The optional trailing s specifies that the pattern applies to the value 535of symbolic links. 536The optional trailing p specifies that after a successful substitution 537the original path name and the new path name should be printed to 538standard error. 539.It Fl T Ar filename , Fl Fl files-from Ar filename 540In x or t mode, 541.Nm 542will read the list of names to be extracted from 543.Pa filename . 544In c mode, 545.Nm 546will read names to be archived from 547.Pa filename . 548The special name 549.Dq -C 550on a line by itself will cause the current directory to be changed to 551the directory specified on the following line. 552Names are terminated by newlines unless 553.Fl Fl null 554is specified. 555Note that 556.Fl Fl null 557also disables the special handling of lines containing 558.Dq -C . 559.It Fl Fl totals 560(c, r, u mode only) 561After archiving all files, print a summary to stderr. 562.It Fl U , Fl Fl unlink , Fl Fl unlink-first 563(x mode only) 564Unlink files before creating them. 565This can be a minor performance optimization if most files 566already exist, but can make things slower if most files 567do not already exist. 568This flag also causes 569.Nm 570to remove intervening directory symlinks instead of 571reporting an error. 572See the SECURITY section below for more details. 573.It Fl Fl uid Ar id 574Use the provided user id number and ignore the user 575name from the archive. 576On create, if 577.Fl Fl uname 578is not also specified, the user name will be set to 579match the user id. 580.It Fl Fl uname Ar name 581Use the provided user name. 582On extract, this overrides the user name in the archive; 583if the provided user name does not exist on the system, 584it will be ignored and the user id 585(from the archive or from the 586.Fl Fl uid 587option) 588will be used instead. 589On create, this sets the user name that will be stored 590in the archive; 591the name is not verified against the system user database. 592.It Fl Fl use-compress-program Ar program 593Pipe the input (in x or t mode) or the output (in c mode) through 594.Pa program 595instead of using the builtin compression support. 596.It Fl v , Fl Fl verbose 597Produce verbose output. 598In create and extract modes, 599.Nm 600will list each file name as it is read from or written to 601the archive. 602In list mode, 603.Nm 604will produce output similar to that of 605.Xr ls 1 . 606Additional 607.Fl v 608options will provide additional detail. 609.It Fl Fl version 610Print version of 611.Nm 612and 613.Nm libarchive , 614and exit. 615.It Fl w , Fl Fl confirmation , Fl Fl interactive 616Ask for confirmation for every action. 617.It Fl X Ar filename , Fl Fl exclude-from Ar filename 618Read a list of exclusion patterns from the specified file. 619See 620.Fl Fl exclude 621for more information about the handling of exclusions. 622.It Fl y 623(c mode only) 624Compress the resulting archive with 625.Xr bzip2 1 . 626In extract or list modes, this option is ignored. 627Note that, unlike other 628.Nm tar 629implementations, this implementation recognizes bzip2 compression 630automatically when reading archives. 631.It Fl Z , Fl Fl compress , Fl Fl uncompress 632(c mode only) 633Compress the resulting archive with 634.Xr compress 1 . 635In extract or list modes, this option is ignored. 636Note that, unlike other 637.Nm tar 638implementations, this implementation recognizes compress compression 639automatically when reading archives. 640.It Fl z , Fl Fl gunzip , Fl Fl gzip 641(c mode only) 642Compress the resulting archive with 643.Xr gzip 1 . 644In extract or list modes, this option is ignored. 645Note that, unlike other 646.Nm tar 647implementations, this implementation recognizes gzip compression 648automatically when reading archives. 649.El 650.Sh ENVIRONMENT 651The following environment variables affect the execution of 652.Nm : 653.Bl -tag -width ".Ev BLOCKSIZE" 654.It Ev LANG 655The locale to use. 656See 657.Xr environ 7 658for more information. 659.It Ev TAPE 660The default device. 661The 662.Fl f 663option overrides this. 664Please see the description of the 665.Fl f 666option above for more details. 667.It Ev TZ 668The timezone to use when displaying dates. 669See 670.Xr environ 7 671for more information. 672.El 673.Sh EXIT STATUS 674.Ex -std 675.Sh EXAMPLES 676The following creates a new archive 677called 678.Ar file.tar.gz 679that contains two files 680.Ar source.c 681and 682.Ar source.h : 683.Dl Nm Fl czf Pa file.tar.gz Pa source.c Pa source.h 684.Pp 685To view a detailed table of contents for this 686archive: 687.Dl Nm Fl tvf Pa file.tar.gz 688.Pp 689To extract all entries from the archive on 690the default tape drive: 691.Dl Nm Fl x 692.Pp 693To examine the contents of an ISO 9660 cdrom image: 694.Dl Nm Fl tf Pa image.iso 695.Pp 696To move file hierarchies, invoke 697.Nm 698as 699.Dl Nm Fl cf Pa - Fl C Pa srcdir\ . | Nm Fl xpf Pa - Fl C Pa destdir 700or more traditionally 701.Dl cd srcdir \&; Nm Fl cf Pa -\ . | ( cd destdir \&; Nm Fl xpf Pa - ) 702.Pp 703In create mode, the list of files and directories to be archived 704can also include directory change instructions of the form 705.Cm -C Ns Pa foo/baz 706and archive inclusions of the form 707.Cm @ Ns Pa archive-file . 708For example, the command line 709.Dl Nm Fl c Fl f Pa new.tar Pa foo1 Cm @ Ns Pa old.tgz Cm -C Ns Pa /tmp Pa foo2 710will create a new archive 711.Pa new.tar . 712.Nm 713will read the file 714.Pa foo1 715from the current directory and add it to the output archive. 716It will then read each entry from 717.Pa old.tgz 718and add those entries to the output archive. 719Finally, it will switch to the 720.Pa /tmp 721directory and add 722.Pa foo2 723to the output archive. 724.Pp 725An input file in 726.Xr mtree 5 727format can be used to create an output archive with arbitrary ownership, 728permissions, or names that differ from existing data on disk: 729.Pp 730.Dl $ cat input.mtree 731.Dl #mtree 732.Dl usr/bin uid=0 gid=0 mode=0755 type=dir 733.Dl usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls 734.Dl $ tar -cvf output.tar @input.mtree 735.Pp 736The 737.Fl Fl newer 738and 739.Fl Fl newer-mtime 740switches accept a variety of common date and time specifications, including 741.Dq 12 Mar 2005 7:14:29pm , 742.Dq 2005-03-12 19:14 , 743.Dq 5 minutes ago , 744and 745.Dq 19:14 PST May 1 . 746.Pp 747The 748.Fl Fl options 749argument can be used to control various details of archive generation 750or reading. 751For example, you can generate mtree output which only contains 752.Cm type , Cm time , 753and 754.Cm uid 755keywords: 756.Dl Nm Fl cf Pa file.tar Fl Fl format=mtree Fl Fl options='!all,type,time,uid' Pa dir 757or you can set the compression level used by gzip or xz compression: 758.Dl Nm Fl czf Pa file.tar Fl Fl options='compression-level=9' . 759For more details, see the explanation of the 760.Fn archive_read_set_options 761and 762.Fn archive_write_set_options 763API calls that are described in 764.Xr archive_read 3 765and 766.Xr archive_write 3 . 767.Sh COMPATIBILITY 768The bundled-arguments format is supported for compatibility 769with historic implementations. 770It consists of an initial word (with no leading - character) in which 771each character indicates an option. 772Arguments follow as separate words. 773The order of the arguments must match the order 774of the corresponding characters in the bundled command word. 775For example, 776.Dl Nm Cm tbf 32 Pa file.tar 777specifies three flags 778.Cm t , 779.Cm b , 780and 781.Cm f . 782The 783.Cm b 784and 785.Cm f 786flags both require arguments, 787so there must be two additional items 788on the command line. 789The 790.Ar 32 791is the argument to the 792.Cm b 793flag, and 794.Ar file.tar 795is the argument to the 796.Cm f 797flag. 798.Pp 799The mode options c, r, t, u, and x and the options 800b, f, l, m, o, v, and w comply with SUSv2. 801.Pp 802For maximum portability, scripts that invoke 803.Nm tar 804should use the bundled-argument format above, should limit 805themselves to the 806.Cm c , 807.Cm t , 808and 809.Cm x 810modes, and the 811.Cm b , 812.Cm f , 813.Cm m , 814.Cm v , 815and 816.Cm w 817options. 818.Pp 819Additional long options are provided to improve compatibility with other 820tar implementations. 821.Sh SECURITY 822Certain security issues are common to many archiving programs, including 823.Nm . 824In particular, carefully-crafted archives can request that 825.Nm 826extract files to locations outside of the target directory. 827This can potentially be used to cause unwitting users to overwrite 828files they did not intend to overwrite. 829If the archive is being extracted by the superuser, any file 830on the system can potentially be overwritten. 831There are three ways this can happen. 832Although 833.Nm 834has mechanisms to protect against each one, 835savvy users should be aware of the implications: 836.Bl -bullet -width indent 837.It 838Archive entries can have absolute pathnames. 839By default, 840.Nm 841removes the leading 842.Pa / 843character from filenames before restoring them to guard against this problem. 844.It 845Archive entries can have pathnames that include 846.Pa .. 847components. 848By default, 849.Nm 850will not extract files containing 851.Pa .. 852components in their pathname. 853.It 854Archive entries can exploit symbolic links to restore 855files to other directories. 856An archive can restore a symbolic link to another directory, 857then use that link to restore a file into that directory. 858To guard against this, 859.Nm 860checks each extracted path for symlinks. 861If the final path element is a symlink, it will be removed 862and replaced with the archive entry. 863If 864.Fl U 865is specified, any intermediate symlink will also be unconditionally removed. 866If neither 867.Fl U 868nor 869.Fl P 870is specified, 871.Nm 872will refuse to extract the entry. 873.El 874To protect yourself, you should be wary of any archives that 875come from untrusted sources. 876You should examine the contents of an archive with 877.Dl Nm Fl tf Pa filename 878before extraction. 879You should use the 880.Fl k 881option to ensure that 882.Nm 883will not overwrite any existing files or the 884.Fl U 885option to remove any pre-existing files. 886You should generally not extract archives while running with super-user 887privileges. 888Note that the 889.Fl P 890option to 891.Nm 892disables the security checks above and allows you to extract 893an archive while preserving any absolute pathnames, 894.Pa .. 895components, or symlinks to other directories. 896.Sh SEE ALSO 897.Xr bzip2 1 , 898.Xr compress 1 , 899.Xr cpio 1 , 900.Xr gzip 1 , 901.Xr mt 1 , 902.Xr pax 1 , 903.Xr shar 1 , 904.Xr xz 1 , 905.Xr libarchive 3 , 906.Xr libarchive-formats 5 , 907.Xr tar 5 908.Sh STANDARDS 909There is no current POSIX standard for the tar command; it appeared 910in 911.St -p1003.1-96 912but was dropped from 913.St -p1003.1-2001 . 914The options supported by this implementation were developed by surveying a 915number of existing tar implementations as well as the old POSIX specification 916for tar and the current POSIX specification for pax. 917.Pp 918The ustar and pax interchange file formats are defined by 919.St -p1003.1-2001 920for the pax command. 921.Sh HISTORY 922A 923.Nm tar 924command appeared in Seventh Edition Unix, which was released in January, 1979. 925There have been numerous other implementations, 926many of which extended the file format. 927John Gilmore's 928.Nm pdtar 929public-domain implementation (circa November, 1987) 930was quite influential, and formed the basis of GNU tar. 931GNU tar was included as the standard system tar 932in 933.Fx 934beginning with 935.Fx 1.0 . 936.Pp 937This is a complete re-implementation based on the 938.Xr libarchive 3 939library. 940It was first released with 941.Fx 5.4 942in May, 2005. 943.Sh BUGS 944This program follows 945.St -p1003.1-96 946for the definition of the 947.Fl l 948option. 949Note that GNU tar prior to version 1.15 treated 950.Fl l 951as a synonym for the 952.Fl Fl one-file-system 953option. 954.Pp 955The 956.Fl C Pa dir 957option may differ from historic implementations. 958.Pp 959All archive output is written in correctly-sized blocks, even 960if the output is being compressed. 961Whether or not the last output block is padded to a full 962block size varies depending on the format and the 963output device. 964For tar and cpio formats, the last block of output is padded 965to a full block size if the output is being 966written to standard output or to a character or block device such as 967a tape drive. 968If the output is being written to a regular file, the last block 969will not be padded. 970Many compressors, including 971.Xr gzip 1 972and 973.Xr bzip2 1 , 974complain about the null padding when decompressing an archive created by 975.Nm , 976although they still extract it correctly. 977.Pp 978The compression and decompression is implemented internally, so 979there may be insignificant differences between the compressed output 980generated by 981.Dl Nm Fl czf Pa - file 982and that generated by 983.Dl Nm Fl cf Pa - file | Nm gzip 984.Pp 985The default should be to read and write archives to the standard I/O paths, 986but tradition (and POSIX) dictates otherwise. 987.Pp 988The 989.Cm r 990and 991.Cm u 992modes require that the archive be uncompressed 993and located in a regular file on disk. 994Other archives can be modified using 995.Cm c 996mode with the 997.Pa @archive-file 998extension. 999.Pp 1000To archive a file called 1001.Pa @foo 1002or 1003.Pa -foo 1004you must specify it as 1005.Pa ./@foo 1006or 1007.Pa ./-foo , 1008respectively. 1009.Pp 1010In create mode, a leading 1011.Pa ./ 1012is always removed. 1013A leading 1014.Pa / 1015is stripped unless the 1016.Fl P 1017option is specified. 1018.Pp 1019There needs to be better support for file selection on both create 1020and extract. 1021.Pp 1022There is not yet any support for multi-volume archives or for archiving 1023sparse files. 1024.Pp 1025Converting between dissimilar archive formats (such as tar and cpio) using the 1026.Cm @ Ns Pa - 1027convention can cause hard link information to be lost. 1028(This is a consequence of the incompatible ways that different archive 1029formats store hardlink information.) 1030