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: src/usr.bin/tar/bsdtar.1,v 1.46 2008/12/06 07:37:55 kientzle Exp $ 26.\" 27.Dd March 25, 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, 54and ISO 9660 cdrom images and can create tar, pax, cpio, ar, 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. 70.It Fl r 71Like 72.Fl c , 73but new entries are appended to the archive. 74Note that this only works on uncompressed archives stored in regular files. 75The 76.Fl f 77option is required. 78.It Fl t 79List archive contents to stdout. 80.It Fl u 81Like 82.Fl r , 83but new entries are added only if they have a modification date 84newer than the corresponding entry in the archive. 85Note that this only works on uncompressed archives stored in regular files. 86The 87.Fl f 88option is required. 89.It Fl x 90Extract to disk from the archive. 91If a file with the same name appears more than once in the archive, 92each copy will be extracted, with later copies overwriting (replacing) 93earlier copies. 94.El 95.Pp 96In 97.Fl c , 98.Fl r , 99or 100.Fl u 101mode, each specified file or directory is added to the 102archive in the order specified on the command line. 103By default, the contents of each directory are also archived. 104.Pp 105In extract or list mode, the entire command line 106is read and parsed before the archive is opened. 107The pathnames or patterns on the command line indicate 108which items in the archive should be processed. 109Patterns are shell-style globbing patterns as 110documented in 111.Xr tcsh 1 . 112.Sh OPTIONS 113Unless specifically stated otherwise, options are applicable in 114all operating modes. 115.Bl -tag -width indent 116.It Cm @ Ns Pa archive 117(c and r mode only) 118The specified archive is opened and the entries 119in it will be appended to the current archive. 120As a simple example, 121.Dl Nm Fl c Fl f Pa - Pa newfile Cm @ Ns Pa original.tar 122writes a new archive to standard output containing a file 123.Pa newfile 124and all of the entries from 125.Pa original.tar . 126In contrast, 127.Dl Nm Fl c Fl f Pa - Pa newfile Pa original.tar 128creates a new archive with only two entries. 129Similarly, 130.Dl Nm Fl czf Pa - Fl -format Cm pax Cm @ Ns Pa - 131reads an archive from standard input (whose format will be determined 132automatically) and converts it into a gzip-compressed 133pax-format archive on stdout. 134In this way, 135.Nm 136can be used to convert archives from one format to another. 137.It Fl b Ar blocksize 138Specify the block size, in 512-byte records, for tape drive I/O. 139As a rule, this argument is only needed when reading from or writing 140to tape drives, and usually not even then as the default block size of 14120 records (10240 bytes) is very common. 142.It Fl C Ar directory 143In c and r mode, this changes the directory before adding 144the following files. 145In x mode, change directories after opening the archive 146but before extracting entries from the archive. 147.It Fl -check-links 148(c and r modes only) 149Issue a warning message unless all links to each file are archived. 150.It Fl -chroot 151(x mode only) 152.Fn chroot 153to the current directory after processing any 154.Fl C 155options and before extracting any files. 156.It Fl -exclude Ar pattern 157Do not process files or directories that match the 158specified pattern. 159Note that exclusions take precedence over patterns or filenames 160specified on the command line. 161.It Fl -format Ar format 162(c, r, u mode only) 163Use the specified format for the created archive. 164Supported formats include 165.Dq cpio , 166.Dq pax , 167.Dq shar , 168and 169.Dq ustar . 170Other formats may also be supported; see 171.Xr libarchive-formats 5 172for more information about currently-supported formats. 173In r and u modes, when extending an existing archive, the format specified 174here must be compatible with the format of the existing archive on disk. 175.It Fl f Ar file 176Read the archive from or write the archive to the specified file. 177The filename can be 178.Pa - 179for standard input or standard output. 180If not specified, the default tape device will be used. 181(On 182.Fx , 183the default tape device is 184.Pa /dev/sa0 . ) 185.It Fl H 186(c and r mode only) 187Symbolic links named on the command line will be followed; the 188target of the link will be archived, not the link itself. 189.It Fl h 190(c and r mode only) 191Synonym for 192.Fl L . 193.It Fl I 194Synonym for 195.Fl T . 196.It Fl -include Ar pattern 197Process only files or directories that match the specified pattern. 198Note that exclusions specified with 199.Fl -exclude 200take precedence over inclusions. 201If no inclusions are explicitly specified, all entries are processed by 202default. 203The 204.Fl -include 205option is especially useful when filtering archives. 206For example, the command 207.Dl Nm Fl c Fl f Pa new.tar Fl -include='*foo*' Cm @ Ns Pa old.tgz 208creates a new archive 209.Pa new.tar 210containing only the entries from 211.Pa old.tgz 212containing the string 213.Sq foo . 214.It Fl j 215(c mode only) 216Compress the resulting archive with 217.Xr bzip2 1 . 218In extract or list modes, this option is ignored. 219Note that, unlike other 220.Nm tar 221implementations, this implementation recognizes bzip2 compression 222automatically when reading archives. 223.It Fl k 224(x mode only) 225Do not overwrite existing files. 226In particular, if a file appears more than once in an archive, 227later copies will not overwrite earlier copies. 228.It Fl -keep-newer-files 229(x mode only) 230Do not overwrite existing files that are newer than the 231versions appearing in the archive being extracted. 232.It Fl L 233(c and r mode only) 234All symbolic links will be followed. 235Normally, symbolic links are archived as such. 236With this option, the target of the link will be archived instead. 237.It Fl l 238This is a synonym for the 239.Fl -check-links 240option. 241.It Fl m 242(x mode only) 243Do not extract modification time. 244By default, the modification time is set to the time stored in the archive. 245.It Fl n 246(c, r, u modes only) 247Do not recursively archive the contents of directories. 248.It Fl -newer Ar date 249(c, r, u modes only) 250Only include files and directories newer than the specified date. 251This compares ctime entries. 252.It Fl -newer-mtime Ar date 253(c, r, u modes only) 254Like 255.Fl -newer , 256except it compares mtime entries instead of ctime entries. 257.It Fl -newer-than Pa file 258(c, r, u modes only) 259Only include files and directories newer than the specified file. 260This compares ctime entries. 261.It Fl -newer-mtime-than Pa file 262(c, r, u modes only) 263Like 264.Fl -newer-than , 265except it compares mtime entries instead of ctime entries. 266.It Fl -nodump 267(c and r modes only) 268Honor the nodump file flag by skipping this file. 269.It Fl -null 270(use with 271.Fl I , 272.Fl T , 273or 274.Fl X ) 275Filenames or patterns are separated by null characters, 276not by newlines. 277This is often used to read filenames output by the 278.Fl print0 279option to 280.Xr find 1 . 281.It Fl -numeric-owner 282(x mode only) 283Ignore symbolic user and group names when restoring archives to disk, 284only numeric uid and gid values will be obeyed. 285.It Fl O 286(x, t modes only) 287In extract (-x) mode, files will be written to standard out rather than 288being extracted to disk. 289In list (-t) mode, the file listing will be written to stderr rather than 290the usual stdout. 291.It Fl o 292(x mode) 293Use the user and group of the user running the program rather 294than those specified in the archive. 295Note that this has no significance unless 296.Fl p 297is specified, and the program is being run by the root user. 298In this case, the file modes and flags from 299the archive will be restored, but ACLs or owner information in 300the archive will be discarded. 301.It Fl o 302(c, r, u mode) 303A synonym for 304.Fl -format Ar ustar 305.It Fl -one-file-system 306(c, r, and u modes) 307Do not cross mount points. 308.It Fl -options Ar options 309Select optional behaviors for particular modules. 310The argument is a text string containing comma-separated 311keywords and values. 312These are passed to the modules that handle particular 313formats to control how those formats will behave. 314Each option has one of the following forms: 315.Bl -tag -compact -width indent 316.It Ar key=value 317The key will be set to the specified value in every module that supports it. 318Modules that do not support this key will ignore it. 319.It Ar key 320The key will be enabled in every module that supports it. 321This is equivalent to 322.Ar key Ns Cm =1 . 323.It Ar !key 324The key will be disabled in every module that supports it. 325.It Ar module:key=value , Ar module:key , Ar module:!key 326As above, but the corresponding key and value will be provided 327only to modules whose name matches 328.Ar module . 329.El 330The currently supported modules and keys are: 331.Bl -tag -compact -width indent 332.It Cm iso9660:joliet 333Support Joliet extensions. 334This is enabled by default, use 335.Cm !joliet 336or 337.Cm iso9660:!joliet 338to disable. 339.It Cm gzip:compression-level 340A decimal integer from 0 to 9 specifying the gzip compression level. 341.It Cm xz:compression-level 342A decimal integer from 0 to 9 specifying the xz compression level. 343.It Cm mtree: Ns Ar keyword 344The mtree writer module allows you to specify which mtree keywords 345will be included in the output. 346Supported keywords include: 347.Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent , 348.Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 , 349.Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname . 350The default is equivalent to: 351.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname . 352.It Cm mtree:all 353Enables all of the above keywords. 354You can also use 355.Cm mtree:!all 356to disable all keywords. 357.It Cm mtree:use-set 358Enable generation of 359.Cm /set 360lines in the output. 361.It Cm mtree:indent 362XXX need explanation XXX 363.El 364If a provided option is not supported by any module, that 365is a fatal error. 366.It Fl P 367Preserve pathnames. 368By default, absolute pathnames (those that begin with a / 369character) have the leading slash removed both when creating archives 370and extracting from them. 371Also, 372.Nm 373will refuse to extract archive entries whose pathnames contain 374.Pa .. 375or whose target directory would be altered by a symlink. 376This option suppresses these behaviors. 377.It Fl p 378(x mode only) 379Preserve file permissions. 380Attempt to restore the full permissions, including owner, file modes, file 381flags and ACLs, if available, for each item extracted from the archive. 382By default, newly-created files are owned by the user running 383.Nm , 384the file mode is restored for newly-created regular files, and 385all other types of entries receive default permissions. 386If 387.Nm 388is being run by root, the default is to restore the owner unless the 389.Fl o 390option is also specified. 391.It Fl q ( Fl -fast-read ) 392(x and t mode only) 393Extract or list only the first archive entry that matches each pattern 394or filename operand. 395Exit as soon as each specified pattern or filename has been matched. 396By default, the archive is always read to the very end, since 397there can be multiple entries with the same name and, by convention, 398later entries overwrite earlier entries. 399This option is provided as a performance optimization. 400.It Fl S 401(x mode only) 402Extract files as sparse files. 403For every block on disk, check first if it contains only NULL bytes and seek 404over it otherwise. 405This works similiar to the conv=sparse option of dd. 406.It Fl -strip-components Ar count 407(x mode only) 408Remove the specified number of leading path elements. 409Pathnames with fewer elements will be silently skipped. 410Note that the pathname is edited after checking inclusion/exclusion patterns 411but before security checks. 412.It Fl s Ar pattern 413Modify file or archive member names according to 414.Pa pattern . 415The pattern has the format /old/new/[gps]. 416old is a basic regular expression. 417If it doesn't apply, the pattern is skipped. 418new is the replacement string of the matched part. 419~ is substituted with the match, \1 to \9 with the content of 420the corresponding captured group. 421The optional trailing g specifies that matching should continue 422after the matched part and stopped on the first unmatched pattern. 423The optional trailing s specifies that the pattern applies to the value 424of symbolic links. 425The optional trailing p specifies that after a successful substitution 426the original path name and the new path name should be printed to 427standard error. 428.It Fl T Ar filename 429In x or t mode, 430.Nm 431will read the list of names to be extracted from 432.Pa filename . 433In c mode, 434.Nm 435will read names to be archived from 436.Pa filename . 437The special name 438.Dq -C 439on a line by itself will cause the current directory to be changed to 440the directory specified on the following line. 441Names are terminated by newlines unless 442.Fl -null 443is specified. 444Note that 445.Fl -null 446also disables the special handling of lines containing 447.Dq -C . 448.It Fl U 449(x mode only) 450Unlink files before creating them. 451Without this option, 452.Nm 453overwrites existing files, which preserves existing hardlinks. 454With this option, existing hardlinks will be broken, as will any 455symlink that would affect the location of an extracted file. 456.It Fl -use-compress-program Ar program 457Pipe the input (in x or t mode) or the output (in c mode) through 458.Pa program 459instead of using the builtin compression support. 460.It Fl v 461Produce verbose output. 462In create and extract modes, 463.Nm 464will list each file name as it is read from or written to 465the archive. 466In list mode, 467.Nm 468will produce output similar to that of 469.Xr ls 1 . 470Additional 471.Fl v 472options will provide additional detail. 473.It Fl -version 474Print version of 475.Nm 476and 477.Nm libarchive , 478and exit. 479.It Fl w 480Ask for confirmation for every action. 481.It Fl X Ar filename 482Read a list of exclusion patterns from the specified file. 483See 484.Fl -exclude 485for more information about the handling of exclusions. 486.It Fl y 487(c mode only) 488Compress the resulting archive with 489.Xr bzip2 1 . 490In extract or list modes, this option is ignored. 491Note that, unlike other 492.Nm tar 493implementations, this implementation recognizes bzip2 compression 494automatically when reading archives. 495.It Fl z 496(c mode only) 497Compress the resulting archive with 498.Xr gzip 1 . 499In extract or list modes, this option is ignored. 500Note that, unlike other 501.Nm tar 502implementations, this implementation recognizes gzip compression 503automatically when reading archives. 504.It Fl Z 505(c mode only) 506Compress the resulting archive with 507.Xr compress 1 . 508In extract or list modes, this option is ignored. 509Note that, unlike other 510.Nm tar 511implementations, this implementation recognizes compress compression 512automatically when reading archives. 513.El 514.Sh ENVIRONMENT 515The following environment variables affect the execution of 516.Nm : 517.Bl -tag -width ".Ev BLOCKSIZE" 518.It Ev LANG 519The locale to use. 520See 521.Xr environ 7 522for more information. 523.It Ev TAPE 524The default tape device. 525The 526.Fl f 527option overrides this. 528.It Ev TZ 529The timezone to use when displaying dates. 530See 531.Xr environ 7 532for more information. 533.El 534.Sh FILES 535.Bl -tag -width ".Ev BLOCKSIZE" 536.It Pa /dev/sa0 537The default tape device, if not overridden by the 538.Ev TAPE 539environment variable or the 540.Fl f 541option. 542.El 543.Sh EXIT STATUS 544.Ex -std 545.Sh EXAMPLES 546The following creates a new archive 547called 548.Ar file.tar.gz 549that contains two files 550.Ar source.c 551and 552.Ar source.h : 553.Dl Nm Fl czf Pa file.tar.gz Pa source.c Pa source.h 554.Pp 555To view a detailed table of contents for this 556archive: 557.Dl Nm Fl tvf Pa file.tar.gz 558.Pp 559To extract all entries from the archive on 560the default tape drive: 561.Dl Nm Fl x 562.Pp 563To examine the contents of an ISO 9660 cdrom image: 564.Dl Nm Fl tf Pa image.iso 565.Pp 566To move file hierarchies, invoke 567.Nm 568as 569.Dl Nm Fl cf Pa - Fl C Pa srcdir\ . | Nm Fl xpf Pa - Fl C Pa destdir 570or more traditionally 571.Dl cd srcdir \&; Nm Fl cf Pa -\ . | ( cd destdir \&; Nm Fl xpf Pa - ) 572.Pp 573In create mode, the list of files and directories to be archived 574can also include directory change instructions of the form 575.Cm -C Ns Pa foo/baz 576and archive inclusions of the form 577.Cm @ Ns Pa archive-file . 578For example, the command line 579.Dl Nm Fl c Fl f Pa new.tar Pa foo1 Cm @ Ns Pa old.tgz Cm -C Ns Pa /tmp Pa foo2 580will create a new archive 581.Pa new.tar . 582.Nm 583will read the file 584.Pa foo1 585from the current directory and add it to the output archive. 586It will then read each entry from 587.Pa old.tgz 588and add those entries to the output archive. 589Finally, it will switch to the 590.Pa /tmp 591directory and add 592.Pa foo2 593to the output archive. 594.Pp 595An input file in 596.Xr mtree 5 597format can be used to create an output archive with arbitrary ownership, 598permissions, or names that differ from existing data on disk: 599.Pp 600.Dl $ cat input.mtree 601.Dl #mtree 602.Dl usr/bin uid=0 gid=0 mode=0755 type=dir 603.Dl usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls 604.Dl $ tar -cvf output.tar @input.mtree 605.Pp 606The 607.Fl -newer 608and 609.Fl -newer-mtime 610switches accept a variety of common date and time specifications, including 611.Dq 12 Mar 2005 7:14:29pm , 612.Dq 2005-03-12 19:14 , 613.Dq 5 minutes ago , 614and 615.Dq 19:14 PST May 1 . 616.Pp 617The 618.Fl -options 619argument can be used to control various details of archive generation 620or reading. 621For example, you can generate mtree output which only contains 622.Cm type , Cm time , 623and 624.Cm uid 625keywords: 626.Dl Nm Fl cf Pa file.tar Fl -format=mtree Fl -options='!all,type,time,uid' Pa dir 627or you can set the compression level used by gzip or xz compression: 628.Dl Nm Fl czf Pa file.tar Fl -options='compression-level=9' . 629For more details, see the explanation of the 630.Fn archive_read_set_options 631and 632.Fn archive_write_set_options 633API calls that are described in 634.Xr archive_read 3 635and 636.Xr archive_write 3 . 637.Sh COMPATIBILITY 638The bundled-arguments format is supported for compatibility 639with historic implementations. 640It consists of an initial word (with no leading - character) in which 641each character indicates an option. 642Arguments follow as separate words. 643The order of the arguments must match the order 644of the corresponding characters in the bundled command word. 645For example, 646.Dl Nm Cm tbf 32 Pa file.tar 647specifies three flags 648.Cm t , 649.Cm b , 650and 651.Cm f . 652The 653.Cm b 654and 655.Cm f 656flags both require arguments, 657so there must be two additional items 658on the command line. 659The 660.Ar 32 661is the argument to the 662.Cm b 663flag, and 664.Ar file.tar 665is the argument to the 666.Cm f 667flag. 668.Pp 669The mode options c, r, t, u, and x and the options 670b, f, l, m, o, v, and w comply with SUSv2. 671.Pp 672For maximum portability, scripts that invoke 673.Nm tar 674should use the bundled-argument format above, should limit 675themselves to the 676.Cm c , 677.Cm t , 678and 679.Cm x 680modes, and the 681.Cm b , 682.Cm f , 683.Cm m , 684.Cm v , 685and 686.Cm w 687options. 688.Pp 689Additional long options are provided to improve compatibility with other 690tar implementations. 691.Sh SECURITY 692Certain security issues are common to many archiving programs, including 693.Nm . 694In particular, carefully-crafted archives can request that 695.Nm 696extract files to locations outside of the target directory. 697This can potentially be used to cause unwitting users to overwrite 698files they did not intend to overwrite. 699If the archive is being extracted by the superuser, any file 700on the system can potentially be overwritten. 701There are three ways this can happen. 702Although 703.Nm 704has mechanisms to protect against each one, 705savvy users should be aware of the implications: 706.Bl -bullet -width indent 707.It 708Archive entries can have absolute pathnames. 709By default, 710.Nm 711removes the leading 712.Pa / 713character from filenames before restoring them to guard against this problem. 714.It 715Archive entries can have pathnames that include 716.Pa .. 717components. 718By default, 719.Nm 720will not extract files containing 721.Pa .. 722components in their pathname. 723.It 724Archive entries can exploit symbolic links to restore 725files to other directories. 726An archive can restore a symbolic link to another directory, 727then use that link to restore a file into that directory. 728To guard against this, 729.Nm 730checks each extracted path for symlinks. 731If the final path element is a symlink, it will be removed 732and replaced with the archive entry. 733If 734.Fl U 735is specified, any intermediate symlink will also be unconditionally removed. 736If neither 737.Fl U 738nor 739.Fl P 740is specified, 741.Nm 742will refuse to extract the entry. 743.El 744To protect yourself, you should be wary of any archives that 745come from untrusted sources. 746You should examine the contents of an archive with 747.Dl Nm Fl tf Pa filename 748before extraction. 749You should use the 750.Fl k 751option to ensure that 752.Nm 753will not overwrite any existing files or the 754.Fl U 755option to remove any pre-existing files. 756You should generally not extract archives while running with super-user 757privileges. 758Note that the 759.Fl P 760option to 761.Nm 762disables the security checks above and allows you to extract 763an archive while preserving any absolute pathnames, 764.Pa .. 765components, or symlinks to other directories. 766.Sh SEE ALSO 767.Xr bzip2 1 , 768.Xr compress 1 , 769.Xr cpio 1 , 770.Xr gzip 1 , 771.Xr mt 1 , 772.Xr pax 1 , 773.Xr shar 1 , 774.Xr libarchive 3 , 775.Xr libarchive-formats 5 , 776.Xr tar 5 777.Sh STANDARDS 778There is no current POSIX standard for the tar command; it appeared 779in 780.St -p1003.1-96 781but was dropped from 782.St -p1003.1-2001 . 783The options used by this implementation were developed by surveying a 784number of existing tar implementations as well as the old POSIX specification 785for tar and the current POSIX specification for pax. 786.Pp 787The ustar and pax interchange file formats are defined by 788.St -p1003.1-2001 789for the pax command. 790.Sh HISTORY 791A 792.Nm tar 793command appeared in Seventh Edition Unix, which was released in January, 1979. 794There have been numerous other implementations, 795many of which extended the file format. 796John Gilmore's 797.Nm pdtar 798public-domain implementation (circa November, 1987) 799was quite influential, and formed the basis of GNU tar. 800GNU tar was included as the standard system tar 801in 802.Fx 803beginning with 804.Fx 1.0 . 805.Pp 806This is a complete re-implementation based on the 807.Xr libarchive 3 808library. 809.Sh BUGS 810This program follows 811.St -p1003.1-96 812for the definition of the 813.Fl l 814option. 815Note that GNU tar prior to version 1.15 treated 816.Fl l 817as a synonym for the 818.Fl -one-file-system 819option. 820.Pp 821The 822.Fl C Pa dir 823option may differ from historic implementations. 824.Pp 825All archive output is written in correctly-sized blocks, even 826if the output is being compressed. 827Whether or not the last output block is padded to a full 828block size varies depending on the format and the 829output device. 830For tar and cpio formats, the last block of output is padded 831to a full block size if the output is being 832written to standard output or to a character or block device such as 833a tape drive. 834If the output is being written to a regular file, the last block 835will not be padded. 836Many compressors, including 837.Xr gzip 1 838and 839.Xr bzip2 1 , 840complain about the null padding when decompressing an archive created by 841.Nm , 842although they still extract it correctly. 843.Pp 844The compression and decompression is implemented internally, so 845there may be insignificant differences between the compressed output 846generated by 847.Dl Nm Fl czf Pa - file 848and that generated by 849.Dl Nm Fl cf Pa - file | Nm gzip 850.Pp 851The default should be to read and write archives to the standard I/O paths, 852but tradition (and POSIX) dictates otherwise. 853.Pp 854The 855.Cm r 856and 857.Cm u 858modes require that the archive be uncompressed 859and located in a regular file on disk. 860Other archives can be modified using 861.Cm c 862mode with the 863.Pa @archive-file 864extension. 865.Pp 866To archive a file called 867.Pa @foo 868or 869.Pa -foo 870you must specify it as 871.Pa ./@foo 872or 873.Pa ./-foo , 874respectively. 875.Pp 876In create mode, a leading 877.Pa ./ 878is always removed. 879A leading 880.Pa / 881is stripped unless the 882.Fl P 883option is specified. 884.Pp 885There needs to be better support for file selection on both create 886and extract. 887.Pp 888There is not yet any support for multi-volume archives or for archiving 889sparse files. 890.Pp 891Converting between dissimilar archive formats (such as tar and cpio) using the 892.Cm @ Ns Pa - 893convention can cause hard link information to be lost. 894(This is a consequence of the incompatible ways that different archive 895formats store hardlink information.) 896.Pp 897There are alternative long options for many of the short options that 898are deliberately not documented. 899