doc/html/bsdtar.1.html

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