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