doc/html/bsdtar.1.html

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