| bsdtar.1 (228763) | bsdtar.1 (228776) |
|---|---|
| 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. --- 8 unchanged lines hidden (view full) --- 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.\" | 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. --- 8 unchanged lines hidden (view full) --- 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: head/contrib/libarchive/tar/bsdtar.1 228763 2011-12-21 11:13:29Z mm $ | 25.\" $FreeBSD: head/contrib/libarchive/tar/bsdtar.1 228776 2011-12-21 15:30:49Z mm $ |
| 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 --- 11 unchanged lines hidden (view full) --- 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. | 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 --- 11 unchanged lines hidden (view full) --- 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, | 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. | 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 . |
|
| 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. | 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 . |
|
| 78.It Fl t 79List archive contents to stdout. | 82.It Fl t 83List archive contents to stdout. |
| 84The long option form is 85.Fl Fl list . |
|
| 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. | 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 . |
|
| 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. | 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 . |
|
| 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 --- 20 unchanged lines hidden (view full) --- 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, | 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 --- 20 unchanged lines hidden (view full) --- 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, |
| 130.Dl Nm Fl czf Pa - Fl -format Cm pax Cm @ Ns Pa - | 140.Dl Nm Fl czf Pa - Fl 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. | 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. |
| 137.It Fl b Ar blocksize | 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 |
| 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. | 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. |
| 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 | 161.It Fl 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. | 162(x mode only) 163.Fn chroot 164to the current directory after processing any 165.Fl C 166options and before extracting any files. |
| 156.It Fl -exclude Ar pattern | 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 |
| 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. | 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. |
| 161.It Fl -format Ar format | 176.It Fl 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. | 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. |
| 175.It Fl f Ar file | 190.It Fl f Ar file , Fl Fl file 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. | 191Read the archive from or write the archive to the specified file. 192The filename can be 193.Pa - 194for standard input or standard output. |
| 180If not specified, the default tape device will be used. 181(On | 195The default varies by system; 196on |
| 182.Fx , | 197.Fx , |
| 183the default tape device is 184.Pa /dev/sa0 . ) | 198the default is 199.Pa /dev/sa0 ; 200on Linux, the default is 201.Pa /dev/st0 . |
| 185.It Fl Fl gid Ar id 186Use the provided group id number. 187On extract, this overrides the group id in the archive; 188the group name in the archive will be ignored. 189On create, this overrides the group id read from disk; 190if 191.Fl Fl gname 192is not also specified, the group name will be set to --- 16 unchanged lines hidden (view full) --- 209target of the link will be archived, not the link itself. 210.It Fl h 211(c and r mode only) 212Synonym for 213.Fl L . 214.It Fl I 215Synonym for 216.Fl T . | 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 --- 16 unchanged lines hidden (view full) --- 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 . |
| 217.It Fl -include Ar pattern | 234.It Fl Fl help 235Show usage. 236.It Fl Fl include Ar pattern |
| 218Process only files or directories that match the specified pattern. 219Note that exclusions specified with | 237Process only files or directories that match the specified pattern. 238Note that exclusions specified with |
| 220.Fl -exclude | 239.Fl Fl exclude |
| 221take precedence over inclusions. 222If no inclusions are explicitly specified, all entries are processed by 223default. 224The | 240take precedence over inclusions. 241If no inclusions are explicitly specified, all entries are processed by 242default. 243The |
| 225.Fl -include | 244.Fl Fl include |
| 226option is especially useful when filtering archives. 227For example, the command | 245option is especially useful when filtering archives. 246For example, the command |
| 228.Dl Nm Fl c Fl f Pa new.tar Fl -include='*foo*' Cm @ Ns Pa old.tgz | 247.Dl Nm Fl c Fl f Pa new.tar Fl Fl include='*foo*' Cm @ Ns Pa old.tgz |
| 229creates a new archive 230.Pa new.tar 231containing only the entries from 232.Pa old.tgz 233containing the string 234.Sq foo . | 248creates a new archive 249.Pa new.tar 250containing only the entries from 251.Pa old.tgz 252containing the string 253.Sq foo . |
| 235.It Fl j | 254.It Fl J , Fl Fl xz |
| 236(c mode only) 237Compress the resulting archive with | 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 |
|
| 238.Xr bzip2 1 . 239In extract or list modes, this option is ignored. 240Note that, unlike other 241.Nm tar 242implementations, this implementation recognizes bzip2 compression 243automatically when reading archives. | 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. |
| 244.It Fl k | 272.It Fl k , Fl Fl keep-old-files |
| 245(x mode only) 246Do not overwrite existing files. 247In particular, if a file appears more than once in an archive, 248later copies will not overwrite earlier copies. | 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. |
| 249.It Fl -keep-newer-files | 277.It Fl Fl keep-newer-files |
| 250(x mode only) 251Do not overwrite existing files that are newer than the 252versions appearing in the archive being extracted. | 278(x mode only) 279Do not overwrite existing files that are newer than the 280versions appearing in the archive being extracted. |
| 253.It Fl L | 281.It Fl L , Fl Fl dereference |
| 254(c and r mode only) 255All symbolic links will be followed. 256Normally, symbolic links are archived as such. 257With this option, the target of the link will be archived instead. | 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. |
| 258.It Fl l 259This is a synonym for the 260.Fl -check-links 261option. 262.It Fl m | 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 |
| 263(x mode only) 264Do not extract modification time. 265By default, the modification time is set to the time stored in the archive. | 299(x mode only) 300Do not extract modification time. 301By default, the modification time is set to the time stored in the archive. |
| 266.It Fl n | 302.It Fl n , Fl Fl norecurse , Fl Fl no-recursion |
| 267(c, r, u modes only) 268Do not recursively archive the contents of directories. | 303(c, r, u modes only) 304Do not recursively archive the contents of directories. |
| 269.It Fl -newer Ar date | 305.It Fl Fl newer Ar date |
| 270(c, r, u modes only) 271Only include files and directories newer than the specified date. 272This compares ctime entries. | 306(c, r, u modes only) 307Only include files and directories newer than the specified date. 308This compares ctime entries. |
| 273.It Fl -newer-mtime Ar date | 309.It Fl Fl newer-mtime Ar date |
| 274(c, r, u modes only) 275Like | 310(c, r, u modes only) 311Like |
| 276.Fl -newer , | 312.Fl Fl newer , |
| 277except it compares mtime entries instead of ctime entries. | 313except it compares mtime entries instead of ctime entries. |
| 278.It Fl -newer-than Pa file | 314.It Fl Fl newer-than Pa file |
| 279(c, r, u modes only) 280Only include files and directories newer than the specified file. 281This compares ctime entries. | 315(c, r, u modes only) 316Only include files and directories newer than the specified file. 317This compares ctime entries. |
| 282.It Fl -newer-mtime-than Pa file | 318.It Fl Fl newer-mtime-than Pa file |
| 283(c, r, u modes only) 284Like | 319(c, r, u modes only) 320Like |
| 285.Fl -newer-than , | 321.Fl Fl newer-than , |
| 286except it compares mtime entries instead of ctime entries. | 322except it compares mtime entries instead of ctime entries. |
| 287.It Fl -nodump | 323.It Fl Fl nodump |
| 288(c and r modes only) 289Honor the nodump file flag by skipping this file. | 324(c and r modes only) 325Honor the nodump file flag by skipping this file. |
| 290.It Fl -null | 326.It Fl Fl null |
| 291(use with | 327(use with |
| 292.Fl I , 293.Fl T , | 328.Fl I |
| 294or | 329or |
| 295.Fl X ) | 330.Fl T ) |
| 296Filenames or patterns are separated by null characters, 297not by newlines. 298This is often used to read filenames output by the 299.Fl print0 300option to 301.Xr find 1 . | 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 . |
| 302.It Fl -numeric-owner 303(x mode only) 304Ignore symbolic user and group names when restoring archives to disk, 305only numeric uid and gid values will be obeyed. | |
| 306.It Fl Fl no-same-owner 307(x mode only) 308Do not extract owner and group IDs. 309This is the reverse of 310.Fl Fl same-owner 311and the default behavior if 312.Nm 313is run as non-root. --- 11 unchanged lines hidden (view full) --- 325.Fl Fl uname 326.Qq 327.Fl Fl gname 328.Qq . 329On extract, it causes user and group names in the archive 330to be ignored in favor of the numeric user and group ids. 331On create, it causes user and group names to not be stored 332in the archive. | 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. --- 11 unchanged lines hidden (view full) --- 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. |
| 333.It Fl O | 364.It Fl O , Fl Fl to-stdout |
| 334(x, t modes only) 335In extract (-x) mode, files will be written to standard out rather than 336being extracted to disk. 337In list (-t) mode, the file listing will be written to stderr rather than 338the usual stdout. 339.It Fl o 340(x mode) 341Use the user and group of the user running the program rather 342than those specified in the archive. 343Note that this has no significance unless 344.Fl p 345is specified, and the program is being run by the root user. 346In this case, the file modes and flags from 347the archive will be restored, but ACLs or owner information in 348the archive will be discarded. 349.It Fl o 350(c, r, u mode) 351A synonym for | 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 |
| 352.Fl -format Ar ustar 353.It Fl -one-file-system | 383.Fl Fl format Ar ustar 384.It Fl Fl one-file-system |
| 354(c, r, and u modes) 355Do not cross mount points. | 385(c, r, and u modes) 386Do not cross mount points. |
| 356.It Fl -options Ar options | 387.It Fl Fl options Ar options |
| 357Select optional behaviors for particular modules. 358The argument is a text string containing comma-separated 359keywords and values. 360These are passed to the modules that handle particular 361formats to control how those formats will behave. 362Each option has one of the following forms: 363.Bl -tag -compact -width indent 364.It Ar key=value --- 54 unchanged lines hidden (view full) --- 419.It Cm zip:compression Ns = Ns Ar type 420Use 421.Ar type 422as compression method. 423Supported values are store (uncompressed) and deflate (gzip algorithm). 424.El 425If a provided option is not supported by any module, that 426is a fatal error. | 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 --- 54 unchanged lines hidden (view full) --- 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. |
| 427.It Fl P | 458.It Fl P , Fl Fl absolute-paths |
| 428Preserve pathnames. 429By default, absolute pathnames (those that begin with a / 430character) have the leading slash removed both when creating archives 431and extracting from them. 432Also, 433.Nm 434will refuse to extract archive entries whose pathnames contain 435.Pa .. 436or whose target directory would be altered by a symlink. 437This option suppresses these behaviors. | 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. |
| 438.It Fl p | 469.It Fl p , Fl Fl insecure , Fl Fl preserve-permissions |
| 439(x mode only) 440Preserve file permissions. 441Attempt to restore the full permissions, including owner, file modes, file 442flags and ACLs, if available, for each item extracted from the archive. | 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. |
| 443By default, newly-created files are owned by the user running 444.Nm , 445the file mode is restored for newly-created regular files, and 446all other types of entries receive default permissions. 447If | 474This is the default, if |
| 448.Nm | 475.Nm |
| 449is being run by root, the default is to restore the owner unless the 450.Fl o 451option is also specified. 452.It Fl q ( Fl -fast-read ) | 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 |
| 453(x and t mode only) 454Extract or list only the first archive entry that matches each pattern 455or filename operand. 456Exit as soon as each specified pattern or filename has been matched. 457By default, the archive is always read to the very end, since 458there can be multiple entries with the same name and, by convention, 459later entries overwrite earlier entries. 460This option is provided as a performance optimization. 461.It Fl S 462(x mode only) 463Extract files as sparse files. 464For every block on disk, check first if it contains only NULL bytes and seek 465over it otherwise. | 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. |
| 466This works similiar to the conv=sparse option of dd. 467.It Fl -strip-components Ar count | 498This works similar to the conv=sparse option of dd. 499.It Fl Fl same-owner |
| 468(x mode only) | 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) |
|
| 469Remove the specified number of leading path elements. 470Pathnames with fewer elements will be silently skipped. 471Note that the pathname is edited after checking inclusion/exclusion patterns 472but before security checks. 473.It Fl s Ar pattern 474Modify file or archive member names according to 475.Pa pattern . 476The pattern has the format --- 14 unchanged lines hidden (view full) --- 491the corresponding captured group. 492The optional trailing g specifies that matching should continue 493after the matched part and stopped on the first unmatched pattern. 494The optional trailing s specifies that the pattern applies to the value 495of symbolic links. 496The optional trailing p specifies that after a successful substitution 497the original path name and the new path name should be printed to 498standard error. | 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 --- 14 unchanged lines hidden (view full) --- 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. |
| 499.It Fl T Ar filename | 539.It Fl T Ar filename , Fl Fl files-from Ar filename |
| 500In x or t mode, 501.Nm 502will read the list of names to be extracted from 503.Pa filename . 504In c mode, 505.Nm 506will read names to be archived from 507.Pa filename . 508The special name 509.Dq -C 510on a line by itself will cause the current directory to be changed to 511the directory specified on the following line. 512Names are terminated by newlines unless | 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 |
| 513.Fl -null | 553.Fl Fl null |
| 514is specified. 515Note that | 554is specified. 555Note that |
| 516.Fl -null | 556.Fl Fl null |
| 517also disables the special handling of lines containing 518.Dq -C . | 557also disables the special handling of lines containing 558.Dq -C . |
| 519.It Fl U | 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 |
| 520(x mode only) 521Unlink files before creating them. | 563(x mode only) 564Unlink files before creating them. |
| 522Without this option, | 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 |
| 523.Nm | 569.Nm |
| 524overwrites existing files, which preserves existing hardlinks. 525With this option, existing hardlinks will be broken, as will any 526symlink that would affect the location of an extracted file. | 570to remove intervening directory symlinks instead of 571reporting an error. 572See the SECURITY section below for more details. |
| 527.It Fl Fl uid Ar id 528Use the provided user id number and ignore the user 529name from the archive. 530On create, if 531.Fl Fl uname 532is not also specified, the user name will be set to 533match the user id. 534.It Fl Fl uname Ar name --- 7 unchanged lines hidden (view full) --- 542will be used instead. 543On create, this sets the user name that will be stored 544in the archive; 545the name is not verified against the system user database. 546.It Fl Fl use-compress-program Ar program 547Pipe the input (in x or t mode) or the output (in c mode) through 548.Pa program 549instead of using the builtin compression support. | 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 --- 7 unchanged lines hidden (view full) --- 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. |
| 550.It Fl v | 596.It Fl v , Fl Fl verbose |
| 551Produce verbose output. 552In create and extract modes, 553.Nm 554will list each file name as it is read from or written to 555the archive. 556In list mode, 557.Nm 558will produce output similar to that of 559.Xr ls 1 . 560Additional 561.Fl v 562options will provide additional detail. | 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. |
| 563.It Fl -version | 609.It Fl Fl version |
| 564Print version of 565.Nm 566and 567.Nm libarchive , 568and exit. | 610Print version of 611.Nm 612and 613.Nm libarchive , 614and exit. |
| 569.It Fl w | 615.It Fl w , Fl Fl confirmation , Fl Fl interactive |
| 570Ask for confirmation for every action. | 616Ask for confirmation for every action. |
| 571.It Fl X Ar filename | 617.It Fl X Ar filename , Fl Fl exclude-from Ar filename |
| 572Read a list of exclusion patterns from the specified file. 573See | 618Read a list of exclusion patterns from the specified file. 619See |
| 574.Fl -exclude | 620.Fl Fl exclude |
| 575for more information about the handling of exclusions. 576.It Fl y 577(c mode only) 578Compress the resulting archive with 579.Xr bzip2 1 . 580In extract or list modes, this option is ignored. 581Note that, unlike other 582.Nm tar 583implementations, this implementation recognizes bzip2 compression 584automatically when reading archives. | 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. |
| 585.It Fl z | 631.It Fl Z , Fl Fl compress , Fl Fl uncompress |
| 586(c mode only) 587Compress the resulting archive with | 632(c mode only) 633Compress the resulting archive with |
| 588.Xr gzip 1 . | 634.Xr compress 1 . |
| 589In extract or list modes, this option is ignored. 590Note that, unlike other 591.Nm tar | 635In extract or list modes, this option is ignored. 636Note that, unlike other 637.Nm tar |
| 592implementations, this implementation recognizes gzip compression | 638implementations, this implementation recognizes compress compression |
| 593automatically when reading archives. | 639automatically when reading archives. |
| 594.It Fl Z | 640.It Fl z , Fl Fl gunzip , Fl Fl gzip |
| 595(c mode only) 596Compress the resulting archive with | 641(c mode only) 642Compress the resulting archive with |
| 597.Xr compress 1 . | 643.Xr gzip 1 . |
| 598In extract or list modes, this option is ignored. 599Note that, unlike other 600.Nm tar | 644In extract or list modes, this option is ignored. 645Note that, unlike other 646.Nm tar |
| 601implementations, this implementation recognizes compress compression | 647implementations, this implementation recognizes gzip compression |
| 602automatically when reading archives. 603.El | 648automatically when reading archives. 649.El |
| 604.Sh EXIT STATUS 605.Ex -std | |
| 606.Sh ENVIRONMENT 607The following environment variables affect the execution of 608.Nm : 609.Bl -tag -width ".Ev BLOCKSIZE" 610.It Ev LANG 611The locale to use. 612See 613.Xr environ 7 614for more information. 615.It Ev TAPE | 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 |
| 616The default tape device. | 660The default device. |
| 617The 618.Fl f 619option overrides this. | 661The 662.Fl f 663option overrides this. |
| 664Please see the description of the 665.Fl f 666option above for more details. |
|
| 620.It Ev TZ 621The timezone to use when displaying dates. 622See 623.Xr environ 7 624for more information. 625.El | 667.It Ev TZ 668The timezone to use when displaying dates. 669See 670.Xr environ 7 671for more information. 672.El |
| 626.Sh FILES 627.Bl -tag -width ".Ev BLOCKSIZE" 628.It Pa /dev/sa0 629The default tape device, if not overridden by the 630.Ev TAPE 631environment variable or the 632.Fl f 633option. 634.El | 673.Sh EXIT STATUS 674.Ex -std |
| 635.Sh EXAMPLES 636The following creates a new archive 637called 638.Ar file.tar.gz 639that contains two files 640.Ar source.c 641and 642.Ar source.h : --- 46 unchanged lines hidden (view full) --- 689.Pp 690.Dl $ cat input.mtree 691.Dl #mtree 692.Dl usr/bin uid=0 gid=0 mode=0755 type=dir 693.Dl usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls 694.Dl $ tar -cvf output.tar @input.mtree 695.Pp 696The | 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 : --- 46 unchanged lines hidden (view full) --- 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 |
| 697.Fl -newer | 737.Fl Fl newer |
| 698and | 738and |
| 699.Fl -newer-mtime | 739.Fl Fl newer-mtime |
| 700switches accept a variety of common date and time specifications, including 701.Dq 12 Mar 2005 7:14:29pm , 702.Dq 2005-03-12 19:14 , 703.Dq 5 minutes ago , 704and 705.Dq 19:14 PST May 1 . 706.Pp 707The | 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 |
| 708.Fl -options | 748.Fl Fl options |
| 709argument can be used to control various details of archive generation 710or reading. 711For example, you can generate mtree output which only contains 712.Cm type , Cm time , 713and 714.Cm uid 715keywords: | 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: |
| 716.Dl Nm Fl cf Pa file.tar Fl -format=mtree Fl -options='!all,type,time,uid' Pa dir | 756.Dl Nm Fl cf Pa file.tar Fl Fl format=mtree Fl Fl options='!all,type,time,uid' Pa dir |
| 717or you can set the compression level used by gzip or xz compression: | 757or you can set the compression level used by gzip or xz compression: |
| 718.Dl Nm Fl czf Pa file.tar Fl -options='compression-level=9' . | 758.Dl Nm Fl czf Pa file.tar Fl Fl options='compression-level=9' . |
| 719For more details, see the explanation of the 720.Fn archive_read_set_options 721and 722.Fn archive_write_set_options 723API calls that are described in 724.Xr archive_read 3 725and 726.Xr archive_write 3 . --- 129 unchanged lines hidden (view full) --- 856.Sh SEE ALSO 857.Xr bzip2 1 , 858.Xr compress 1 , 859.Xr cpio 1 , 860.Xr gzip 1 , 861.Xr mt 1 , 862.Xr pax 1 , 863.Xr shar 1 , | 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 . --- 129 unchanged lines hidden (view full) --- 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 , |
|
| 864.Xr libarchive 3 , 865.Xr libarchive-formats 5 , 866.Xr tar 5 867.Sh STANDARDS 868There is no current POSIX standard for the tar command; it appeared 869in 870.St -p1003.1-96 871but was dropped from 872.St -p1003.1-2001 . | 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 . |
| 873The options used by this implementation were developed by surveying a | 914The options supported by this implementation were developed by surveying a |
| 874number of existing tar implementations as well as the old POSIX specification 875for tar and the current POSIX specification for pax. 876.Pp 877The ustar and pax interchange file formats are defined by 878.St -p1003.1-2001 879for the pax command. 880.Sh HISTORY 881A --- 9 unchanged lines hidden (view full) --- 891in 892.Fx 893beginning with 894.Fx 1.0 . 895.Pp 896This is a complete re-implementation based on the 897.Xr libarchive 3 898library. | 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 --- 9 unchanged lines hidden (view full) --- 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. |
|
| 899.Sh BUGS 900This program follows 901.St -p1003.1-96 902for the definition of the 903.Fl l 904option. 905Note that GNU tar prior to version 1.15 treated 906.Fl l 907as a synonym for the | 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 |
| 908.Fl -one-file-system | 952.Fl Fl one-file-system |
| 909option. 910.Pp 911The 912.Fl C Pa dir 913option may differ from historic implementations. 914.Pp 915All archive output is written in correctly-sized blocks, even 916if the output is being compressed. --- 61 unchanged lines hidden (view full) --- 978There is not yet any support for multi-volume archives or for archiving 979sparse files. 980.Pp 981Converting between dissimilar archive formats (such as tar and cpio) using the 982.Cm @ Ns Pa - 983convention can cause hard link information to be lost. 984(This is a consequence of the incompatible ways that different archive 985formats store hardlink information.) | 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. --- 61 unchanged lines hidden (view full) --- 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.) |
| 986.Pp 987There are alternative long options for many of the short options that 988are deliberately not documented. | |