doc/wiki/ManPageBsdtar1.wiki

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