doc/html/bsdtar.1.html

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