1 TAR(1) BSD General Commands Manual TAR(1)
4 1mtar 22m— manipulate tape archives
7 1mtar 22m[4mbundled-flags24m ⟨args⟩] [⟨4mfile24m⟩ | ⟨4mpattern24m⟩ ...]
8 1mtar 22m{1m-c22m} [4moptions24m] [4mfiles24m | 4mdirectories24m]
9 1mtar 22m{1m-r 22m| 1m-u22m} 1m-f 4m22marchive-file24m [4moptions24m] [4mfiles24m | 4mdirectories24m]
10 1mtar 22m{1m-t 22m| 1m-x22m} [4moptions24m] [4mpatterns24m]
13 1mtar 22mcreates and manipulates streaming archive files. This implementation
14 can extract from tar, pax, cpio, zip, jar, ar, xar, rpm, 7-zip, and ISO
15 9660 cdrom images and can create tar, pax, cpio, ar, zip, 7-zip, and shar
18 The first synopsis form shows a “bundled” option word. This usage is
19 provided for compatibility with historical implementations. See COMPATI‐
20 BILITY below for details.
22 The other synopsis forms show the preferred usage. The first option to
23 1mtar 22mis a mode indicator from the following list:
24 1m-c 22mCreate a new archive containing the specified items. The long
25 option form is 1m--create22m.
26 1m-r 22mLike 1m-c22m, but new entries are appended to the archive. Note that
27 this only works on uncompressed archives stored in regular files.
28 The 1m-f 22moption is required. The long option form is 1m--append22m.
29 1m-t 22mList archive contents to stdout. The long option form is 1m--list22m.
30 1m-u 22mLike 1m-r22m, but new entries are added only if they have a modifica‐
31 tion date newer than the corresponding entry in the archive.
32 Note that this only works on uncompressed archives stored in reg‐
33 ular files. The 1m-f 22moption is required. The long form is
35 1m-x 22mExtract to disk from the archive. If a file with the same name
36 appears more than once in the archive, each copy will be
37 extracted, with later copies overwriting (replacing) earlier
38 copies. The long option form is 1m--extract22m.
40 In 1m-c22m, 1m-r22m, or 1m-u 22mmode, each specified file or directory is added to the
41 archive in the order specified on the command line. By default, the con‐
42 tents of each directory are also archived.
44 In extract or list mode, the entire command line is read and parsed
45 before the archive is opened. The pathnames or patterns on the command
46 line indicate which items in the archive should be processed. Patterns
47 are shell-style globbing patterns as documented in tcsh(1).
50 Unless specifically stated otherwise, options are applicable in all oper‐
54 (c and r modes only) The specified archive is opened and the
55 entries in it will be appended to the current archive. As a sim‐
57 1mtar -c -f 4m22m-24m 4mnewfile24m 1m@4m22moriginal.tar0m
58 writes a new archive to standard output containing a file 4mnewfile0m
59 and all of the entries from 4moriginal.tar24m. In contrast,
60 1mtar -c -f 4m22m-24m 4mnewfile24m 4moriginal.tar0m
61 creates a new archive with only two entries. Similarly,
62 1mtar -czf 4m22m-24m 1m--format pax @4m22m-0m
63 reads an archive from standard input (whose format will be deter‐
64 mined automatically) and converts it into a gzip-compressed pax-
65 format archive on stdout. In this way, 1mtar 22mcan be used to con‐
66 vert archives from one format to another.
68 1m-a22m, 1m--auto-compress0m
69 (c mode only) Use the archive suffix to decide a set of the for‐
70 mat and the compressions. As a simple example,
71 1mtar -a -cf 4m22marchive.tgz24m 4msource.c24m 4msource.h0m
72 creates a new archive with restricted pax format and gzip com‐
74 1mtar -a -cf 4m22marchive.tar.bz2.uu24m 4msource.c24m 4msource.h0m
75 creates a new archive with restricted pax format and bzip2 com‐
76 pression and uuencode compression,
77 1mtar -a -cf 4m22marchive.zip24m 4msource.c24m 4msource.h0m
78 creates a new archive with zip format,
79 1mtar -a -jcf 4m22marchive.tgz24m 4msource.c24m 4msource.h0m
80 ignores the “-j” option, and creates a new archive with
81 restricted pax format and gzip compression,
82 1mtar -a -jcf 4m22marchive.xxx24m 4msource.c24m 4msource.h0m
83 if it is unknown suffix or no suffix, creates a new archive with
84 restricted pax format and bzip2 compression.
86 1m--acls 22m(c, r, u, x modes only) Archive or extract POSIX.1e or NFSv4
87 ACLs. This is the reverse of 1m--no-acls 22mand the default behavior
88 in c, r, and u modes (except Mac OS X) or if 1mtar 22mis run in x mode
89 as root. On Mac OS X this option translates extended ACLs to
90 NFSv4 ACLs. To store extended ACLs the 1m--mac-metadata 22moption is
93 1m-B22m, 1m--read-full-blocks0m
94 Ignored for compatibility with other tar(1) implementations.
96 1m-b 4m22mblocksize24m, 1m--block-size 4m22mblocksize0m
97 Specify the block size, in 512-byte records, for tape drive I/O.
98 As a rule, this argument is only needed when reading from or
99 writing to tape drives, and usually not even then as the default
100 block size of 20 records (10240 bytes) is very common.
102 1m-C 4m22mdirectory24m, 1m--cd 4m22mdirectory24m, 1m--directory 4m22mdirectory0m
103 In c and r mode, this changes the directory before adding the
104 following files. In x mode, change directories after opening the
105 archive but before extracting entries from the archive.
108 (x mode only) 1mchroot22m() to the current directory after processing
109 any 1m-C 22moptions and before extracting any files.
111 1m--clear-nochange-fflags0m
112 (x mode only) Before removing file system objects to replace
113 them, clear platform-specific file flags that might prevent
116 1m--exclude 4m22mpattern0m
117 Do not process files or directories that match the specified pat‐
118 tern. Note that exclusions take precedence over patterns or
119 filenames specified on the command line.
122 (c, r, u, x modes only) Archive or extract file flags. This is
123 the reverse of 1m--no-fflags 22mand the default behavior in c, r, and
124 u modes or if 1mtar 22mis run in x mode as root.
126 1m--format 4m22mformat0m
127 (c, r, u mode only) Use the specified format for the created ar‐
128 chive. Supported formats include “cpio”, “pax”, “shar”, and
129 “ustar”. Other formats may also be supported; see
130 libarchive-formats(5) for more information about currently-sup‐
131 ported formats. In r and u modes, when extending an existing ar‐
132 chive, the format specified here must be compatible with the for‐
133 mat of the existing archive on disk.
135 1m-f 4m22mfile24m, 1m--file 4m22mfile0m
136 Read the archive from or write the archive to the specified file.
137 The filename can be 4m-24m for standard input or standard output. The
138 default varies by system; on FreeBSD, the default is 4m/dev/sa024m; on
139 Linux, the default is 4m/dev/st024m.
142 Use the provided group id number. On extract, this overrides the
143 group id in the archive; the group name in the archive will be
144 ignored. On create, this overrides the group id read from disk;
145 if 1m--gname 22mis not also specified, the group name will be set to
148 1m--gname 4m22mname0m
149 Use the provided group name. On extract, this overrides the
150 group name in the archive; if the provided group name does not
151 exist on the system, the group id (from the archive or from the
152 1m--gid 22moption) will be used instead. On create, this sets the
153 group name that will be stored in the archive; the name will not
154 be verified against the system group database.
156 1m-H 22m(c and r modes only) Symbolic links named on the command line
157 will be followed; the target of the link will be archived, not
160 1m-h 22m(c and r modes only) Synonym for 1m-L22m.
162 1m-I 22mSynonym for 1m-T22m.
164 1m--help 22mShow usage.
167 (x mode only) Mac OS X specific (v10.6 or later). Compress
168 extracted regular files with HFS+ compression.
171 An alias of 1m--options read_concatenated_archives 22mfor compatibil‐
174 1m--include 4m22mpattern0m
175 Process only files or directories that match the specified pat‐
176 tern. Note that exclusions specified with 1m--exclude 22mtake prece‐
177 dence over inclusions. If no inclusions are explicitly speci‐
178 fied, all entries are processed by default. The 1m--include 22moption
179 is especially useful when filtering archives. For example, the
181 1mtar -c -f 4m22mnew.tar24m 1m--include='*foo*' @4m22mold.tgz0m
182 creates a new archive 4mnew.tar24m containing only the entries from
183 4mold.tgz24m containing the string ‘foo’.
186 (c mode only) Compress the resulting archive with xz(1). In
187 extract or list modes, this option is ignored. Note that, unlike
188 other 1mtar 22mimplementations, this implementation recognizes XZ com‐
189 pression automatically when reading archives.
191 1m-j22m, 1m--bzip22m, 1m--bzip222m, 1m--bunzip20m
192 (c mode only) Compress the resulting archive with bzip2(1). In
193 extract or list modes, this option is ignored. Note that, unlike
194 other 1mtar 22mimplementations, this implementation recognizes bzip2
195 compression automatically when reading archives.
197 1m-k22m, 1m--keep-old-files0m
198 (x mode only) Do not overwrite existing files. In particular, if
199 a file appears more than once in an archive, later copies will
200 not overwrite earlier copies.
202 1m--keep-newer-files0m
203 (x mode only) Do not overwrite existing files that are newer than
204 the versions appearing in the archive being extracted.
206 1m-L22m, 1m--dereference0m
207 (c and r modes only) All symbolic links will be followed. Nor‐
208 mally, symbolic links are archived as such. With this option,
209 the target of the link will be archived instead.
211 1m-l22m, 1m--check-links0m
212 (c and r modes only) Issue a warning message unless all links to
213 each file are archived.
216 (c mode only) Compress the resulting archive with lrzip(1). In
217 extract or list modes, this option is ignored.
219 1m--lz4 22m(c mode only) Compress the archive with lz4-compatible compres‐
220 sion before writing it. In input mode, this option is ignored;
221 lz4 compression is recognized automatically on input.
223 1m--lzma 22m(c mode only) Compress the resulting archive with the original
224 LZMA algorithm. Use of this option is discouraged and new ar‐
225 chives should be created with 1m--xz 22minstead. Note that, unlike
226 other 1mtar 22mimplementations, this implementation recognizes LZMA
227 compression automatically when reading archives.
229 1m--lzop 22m(c mode only) Compress the resulting archive with lzop(1). In
230 extract or list modes, this option is ignored.
232 1m-m22m, 1m--modification-time0m
233 (x mode only) Do not extract modification time. By default, the
234 modification time is set to the time stored in the archive.
237 (c, r, u and x mode only) Mac OS X specific. Archive or extract
238 extended ACLs and extended attributes using copyfile(3) in Apple‐
239 Double format. This is the reverse of 1m--no-mac-metadata22m. and the
240 default behavior in c, r, and u modes or if 1mtar 22mis run in x mode
243 1m-n22m, 1m--norecurse22m, 1m--no-recursion0m
244 (c, r, u modes only) Do not recursively archive the contents of
247 1m--newer 4m22mdate0m
248 (c, r, u modes only) Only include files and directories newer
249 than the specified date. This compares ctime entries.
251 1m--newer-mtime 4m22mdate0m
252 (c, r, u modes only) Like 1m--newer22m, except it compares mtime
253 entries instead of ctime entries.
255 1m--newer-than 4m22mfile0m
256 (c, r, u modes only) Only include files and directories newer
257 than the specified file. This compares ctime entries.
259 1m--newer-mtime-than 4m22mfile0m
260 (c, r, u modes only) Like 1m--newer-than22m, except it compares mtime
261 entries instead of ctime entries.
264 (c and r modes only) Honor the nodump file flag by skipping this
267 1m--nopreserveHFSCompression0m
268 (x mode only) Mac OS X specific(v10.6 or later). Do not compress
269 extracted regular files which were compressed with HFS+ compres‐
270 sion before archived. By default, compress the regular files
271 again with HFS+ compression.
273 1m--null 22m(use with 1m-I 22mor 1m-T22m) Filenames or patterns are separated by null
274 characters, not by newlines. This is often used to read file‐
275 names output by the 1m-print0 22moption to find(1).
278 (c, r, u, x modes only) Do not archive or extract POSIX.1e or
279 NFSv4 ACLs. This is the reverse of 1m--acls 22mand the default behav‐
280 ior if 1mtar 22mis run as non-root in x mode (on Mac OS X also in c, r
284 (c, r, u, x modes only) Do not archive or extract file flags.
285 This is the reverse of 1m--fflags 22mand the default behavior if 1mtar0m
286 is run as non-root in x mode.
288 1m--no-mac-metadata0m
289 (x mode only) Mac OS X specific. Do not archive or extract ACLs
290 and extended attributes using copyfile(3) in AppleDouble format.
291 This is the reverse of 1m--mac-metadata22m. and the default behavior
292 if 1mtar 22mis run as non-root in x mode.
294 1m-n22m, 1m--norecurse22m, 1m--no-recursion0m
297 (x mode only) Do not extract owner and group IDs. This is the
298 reverse of 1m--same-owner 22mand the default behavior if 1mtar 22mis run as
301 1m--no-same-permissions0m
302 (x mode only) Do not extract full permissions (SGID, SUID, sticky
303 bit, ACLs, extended attributes or extended file flags). This is
304 the reverse of 1m-p 22mand the default behavior if 1mtar 22mis run as non-
305 root and can be overridden by also specifying 1m--acls22m, 1m--fflags22m,
306 1m--mac-metadata, --same-owner22m, 1m--same-permissions 22mand 1m--xattrs22m.
309 (c, r, u, x modes only) Do not archive or extract extended
310 attributes. This is the reverse of 1m--xattrs 22mand the default
311 behavior if 1mtar 22mis run as non-root in x mode.
314 This is equivalent to 1m--uname 22m"" 1m--gname 22m"". On extract, it
315 causes user and group names in the archive to be ignored in favor
316 of the numeric user and group ids. On create, it causes user and
317 group names to not be stored in the archive.
319 1m-O22m, 1m--to-stdout0m
320 (x, t modes only) In extract (-x) mode, files will be written to
321 standard out rather than being extracted to disk. In list (-t)
322 mode, the file listing will be written to stderr rather than the
325 1m-o 22m(x mode) Use the user and group of the user running the program
326 rather than those specified in the archive. Note that this has
327 no significance unless 1m-p 22mis specified, and the program is being
328 run by the root user. In this case, the file modes and flags
329 from the archive will be restored, but ACLs or owner information
330 in the archive will be discarded.
332 1m-o 22m(c, r, u mode) A synonym for 1m--format 4m22mustar0m
334 1m--older 4m22mdate0m
335 (c, r, u modes only) Only include files and directories older
336 than the specified date. This compares ctime entries.
338 1m--older-mtime 4m22mdate0m
339 (c, r, u modes only) Like 1m--older22m, except it compares mtime
340 entries instead of ctime entries.
342 1m--older-than 4m22mfile0m
343 (c, r, u modes only) Only include files and directories older
344 than the specified file. This compares ctime entries.
346 1m--older-mtime-than 4m22mfile0m
347 (c, r, u modes only) Like 1m--older-than22m, except it compares mtime
348 entries instead of ctime entries.
350 1m--one-file-system0m
351 (c, r, and u modes) Do not cross mount points.
353 1m--options 4m22moptions0m
354 Select optional behaviors for particular modules. The argument
355 is a text string containing comma-separated keywords and values.
356 These are passed to the modules that handle particular formats to
357 control how those formats will behave. Each option has one of
360 The key will be set to the specified value in every mod‐
361 ule that supports it. Modules that do not support this
363 4mkey24m The key will be enabled in every module that supports it.
364 This is equivalent to 4mkey24m1m=122m.
365 4m!key24m The key will be disabled in every module that supports
367 4mmodule:key=value24m, 4mmodule:key24m, 4mmodule:!key0m
368 As above, but the corresponding key and value will be
369 provided only to modules whose name matches 4mmodule24m.
370 The currently supported modules and keys are:
372 Support Joliet extensions. This is enabled by default,
373 use 1m!joliet 22mor 1miso9660:!joliet 22mto disable.
374 1miso9660:rockridge0m
375 Support Rock Ridge extensions. This is enabled by
376 default, use 1m!rockridge 22mor 1miso9660:!rockridge 22mto disable.
377 1mgzip:compression-level0m
378 A decimal integer from 1 to 9 specifying the gzip com‐
381 Store timestamp. This is enabled by default, use
382 1m!timestamp 22mor 1mgzip:!timestamp 22mto disable.
383 1mlrzip:compression22m=4mtype0m
384 Use 4mtype24m as compression method. Supported values are
385 bzip2, gzip, lzo (ultra fast), and zpaq (best, extremely
387 1mlrzip:compression-level0m
388 A decimal integer from 1 to 9 specifying the lrzip com‐
390 1mlz4:compression-level0m
391 A decimal integer from 1 to 9 specifying the lzop com‐
393 1mlz4:stream-checksum0m
394 Enable stream checksum. This is by default, use
395 1mlz4:!stream-checksum 22mto disable.
396 1mlz4:block-checksum0m
397 Enable block checksum (Disabled by default).
399 A decimal integer from 4 to 7 specifying the lz4 compres‐
400 sion block size (7 is set by default).
401 1mlz4:block-dependence0m
402 Use the previous block of the block being compressed for
403 a compression dictionary to improve compression ratio.
404 1mlzop:compression-level0m
405 A decimal integer from 1 to 9 specifying the lzop com‐
407 1mxz:compression-level0m
408 A decimal integer from 0 to 9 specifying the xz compres‐
410 1mmtree:4m22mkeyword0m
411 The mtree writer module allows you to specify which mtree
412 keywords will be included in the output. Supported key‐
413 words include: 1mcksum22m, 1mdevice22m, 1mflags22m, 1mgid22m, 1mgname22m, 1mindent22m,
414 1mlink22m, 1mmd522m, 1mmode22m, 1mnlink22m, 1mrmd16022m, 1msha122m, 1msha25622m, 1msha38422m,
415 1msha51222m, 1msize22m, 1mtime22m, 1muid22m, 1muname22m. The default is equiva‐
416 lent to: “device, flags, gid, gname, link, mode, nlink,
417 size, time, type, uid, uname”.
419 Enables all of the above keywords. You can also use
420 1mmtree:!all 22mto disable all keywords.
422 Enable generation of 1m/set 22mlines in the output.
424 Produce human-readable output by indenting options and
425 splitting lines to fit into 80 columns.
426 1mzip:compression22m=4mtype0m
427 Use 4mtype24m as compression method. Supported values are
428 store (uncompressed) and deflate (gzip algorithm).
430 Enable encryption using traditional zip encryption.
431 1mzip:encryption22m=4mtype0m
432 Use 4mtype24m as encryption type. Supported values are
433 zipcrypt (traditional zip encryption), aes128 (WinZip
434 AES-128 encryption) and aes256 (WinZip AES-256 encryp‐
436 1mread_concatenated_archives0m
437 Ignore zeroed blocks in the archive, which occurs when
438 multiple tar archives have been concatenated together.
439 Without this option, only the contents of the first con‐
440 catenated archive would be read. This option is compara‐
441 ble to the 1m-i22m, 1m--ignore-zeros 22moption of GNU tar.
442 If a provided option is not supported by any module, that is a
445 1m-P22m, 1m--absolute-paths0m
446 Preserve pathnames. By default, absolute pathnames (those that
447 begin with a / character) have the leading slash removed both
448 when creating archives and extracting from them. Also, 1mtar 22mwill
449 refuse to extract archive entries whose pathnames contain 4m..24m or
450 whose target directory would be altered by a symlink. This
451 option suppresses these behaviors.
453 1m-p22m, 1m--insecure22m, 1m--preserve-permissions0m
454 (x mode only) Preserve file permissions. Attempt to restore the
455 full permissions, including owner, file modes, ACLs, extended
456 atributes and extended file flags, if available, for each item
457 extracted from the archive. This is the default, if 1mtar 22mis being
458 run by root and can be overridden by also specifying 1m--no-acls22m,
459 1m--no-fflags22m, 1m--no-mac-metadata, --no-same-owner22m,
460 1m--no-same-permissions 22mand 1m--no-xattrs22m.
462 1m--passphrase 4m22mpassphrase0m
463 The 4mpassphrase24m is used to extract or create an encrypted archive.
464 Currently, zip is the only supported format that supports encryp‐
465 tion. You shouldn't use this option unless you realize how inse‐
466 cure use of this option is.
469 (c, r, u mode only) Synonym for 1m--format 4m22mpax0m
471 1m-q22m, 1m--fast-read0m
472 (x and t mode only) Extract or list only the first archive entry
473 that matches each pattern or filename operand. Exit as soon as
474 each specified pattern or filename has been matched. By default,
475 the archive is always read to the very end, since there can be
476 multiple entries with the same name and, by convention, later
477 entries overwrite earlier entries. This option is provided as a
478 performance optimization.
480 1m-S 22m(x mode only) Extract files as sparse files. For every block on
481 disk, check first if it contains only NULL bytes and seek over it
482 otherwise. This works similar to the conv=sparse option of dd.
485 Modify file or archive member names according to 4mpattern24m. The
486 pattern has the format 4m/old/new/24m[ghHprRsS] where 4mold24m is a basic
487 regular expression, 4mnew24m is the replacement string of the matched
488 part, and the optional trailing letters modify how the replace‐
489 ment is handled. If 4mold24m is not matched, the pattern is skipped.
490 Within 4mnew24m, ~ is substituted with the match, \1 to \9 with the
491 content of the corresponding captured group. The optional trail‐
492 ing g specifies that matching should continue after the matched
493 part and stop on the first unmatched pattern. The optional
494 trailing s specifies that the pattern applies to the value of
495 symbolic links. The optional trailing p specifies that after a
496 successful substitution the original path name and the new path
497 name should be printed to standard error. Optional trailing H,
498 R, or S characters suppress substitutions for hardlink targets,
499 regular filenames, or symlink targets, respectively. Optional
500 trailing h, r, or s characters enable substitutions for hardlink
501 targets, regular filenames, or symlink targets, respectively.
502 The default is 4mhrs24m which applies substitutions to all names. In
503 particular, it is never necessary to specify h, r, or s.
506 (x mode only) Extract owner and group IDs. This is the reverse
507 of 1m--no-same-owner 22mand the default behavior if 1mtar 22mis run as
510 1m--strip-components 4m22mcount0m
511 Remove the specified number of leading path elements. Pathnames
512 with fewer elements will be silently skipped. Note that the
513 pathname is edited after checking inclusion/exclusion patterns
514 but before security checks.
516 1m-T 4m22mfilename24m, 1m--files-from 4m22mfilename0m
517 In x or t mode, 1mtar 22mwill read the list of names to be extracted
518 from 4mfilename24m. In c mode, 1mtar 22mwill read names to be archived
519 from 4mfilename24m. The special name “-C” on a line by itself will
520 cause the current directory to be changed to the directory speci‐
521 fied on the following line. Names are terminated by newlines
522 unless 1m--null 22mis specified. Note that 1m--null 22malso disables the
523 special handling of lines containing “-C”. Note: If you are
524 generating lists of files using find(1), you probably want to use
528 (c, r, u modes only) After archiving all files, print a summary
531 1m-U22m, 1m--unlink22m, 1m--unlink-first0m
532 (x mode only) Unlink files before creating them. This can be a
533 minor performance optimization if most files already exist, but
534 can make things slower if most files do not already exist. This
535 flag also causes 1mtar 22mto remove intervening directory symlinks
536 instead of reporting an error. See the SECURITY section below
540 Use the provided user id number and ignore the user name from the
541 archive. On create, if 1m--uname 22mis not also specified, the user
542 name will be set to match the user id.
544 1m--uname 4m22mname0m
545 Use the provided user name. On extract, this overrides the user
546 name in the archive; if the provided user name does not exist on
547 the system, it will be ignored and the user id (from the archive
548 or from the 1m--uid 22moption) will be used instead. On create, this
549 sets the user name that will be stored in the archive; the name
550 is not verified against the system user database.
552 1m--use-compress-program 4m22mprogram0m
553 Pipe the input (in x or t mode) or the output (in c mode) through
554 4mprogram24m instead of using the builtin compression support.
556 1m-v22m, 1m--verbose0m
557 Produce verbose output. In create and extract modes, 1mtar 22mwill
558 list each file name as it is read from or written to the archive.
559 In list mode, 1mtar 22mwill produce output similar to that of ls(1).
560 An additional 1m-v 22moption will also provide ls-like details in cre‐
561 ate and extract mode.
564 Print version of 1mtar 22mand 1mlibarchive22m, and exit.
566 1m-w22m, 1m--confirmation22m, 1m--interactive0m
567 Ask for confirmation for every action.
569 1m-X 4m22mfilename24m, 1m--exclude-from 4m22mfilename0m
570 Read a list of exclusion patterns from the specified file. See
571 1m--exclude 22mfor more information about the handling of exclusions.
574 (c, r, u, x modes only) Archive or extract extended attributes.
575 This is the reverse of 1m--no-xattrs 22mand the default behavior in c,
576 r, and u modes or if 1mtar 22mis run in x mode as root.
578 1m-y 22m(c mode only) Compress the resulting archive with bzip2(1). In
579 extract or list modes, this option is ignored. Note that, unlike
580 other 1mtar 22mimplementations, this implementation recognizes bzip2
581 compression automatically when reading archives.
583 1m-Z22m, 1m--compress22m, 1m--uncompress0m
584 (c mode only) Compress the resulting archive with compress(1).
585 In extract or list modes, this option is ignored. Note that,
586 unlike other 1mtar 22mimplementations, this implementation recognizes
587 compress compression automatically when reading archives.
589 1m-z22m, 1m--gunzip22m, 1m--gzip0m
590 (c mode only) Compress the resulting archive with gzip(1). In
591 extract or list modes, this option is ignored. Note that, unlike
592 other 1mtar 22mimplementations, this implementation recognizes gzip
593 compression automatically when reading archives.
596 The following environment variables affect the execution of 1mtar22m:
599 The default options for format readers and compression read‐
600 ers. The 1m--options 22moption overrides this.
603 The default options for format writers and compression writ‐
604 ers. The 1m--options 22moption overrides this.
606 LANG The locale to use. See environ(7) for more information.
608 TAPE The default device. The 1m-f 22moption overrides this. Please see
609 the description of the 1m-f 22moption above for more details.
611 TZ The timezone to use when displaying dates. See environ(7) for
615 The 1mtar 22mutility exits 0 on success, and >0 if an error occurs.
618 The following creates a new archive called 4mfile.tar.gz24m that contains two
619 files 4msource.c24m and 4msource.h24m:
620 1mtar -czf 4m22mfile.tar.gz24m 4msource.c24m 4msource.h0m
622 To view a detailed table of contents for this archive:
623 1mtar -tvf 4m22mfile.tar.gz0m
625 To extract all entries from the archive on the default tape drive:
628 To examine the contents of an ISO 9660 cdrom image:
629 1mtar -tf 4m22mimage.iso0m
631 To move file hierarchies, invoke 1mtar 22mas
632 1mtar -cf 4m22m-24m 1m-C 4m22msrcdir24m 4m.24m | 1mtar -xpf 4m22m-24m 1m-C 4m22mdestdir0m
633 or more traditionally
634 cd srcdir ; 1mtar -cf 4m22m-24m 4m.24m | (4mcd24m 4mdestdir24m 4m;24m 1mtar -xpf 4m22m-24m)
636 In create mode, the list of files and directories to be archived can also
637 include directory change instructions of the form 1m-C4m22mfoo/baz24m and archive
638 inclusions of the form 1m@4m22marchive-file24m. For example, the command line
639 1mtar -c -f 4m22mnew.tar24m 4mfoo124m 1m@4m22mold.tgz24m 1m-C4m22m/tmp24m 4mfoo20m
640 will create a new archive 4mnew.tar24m. 1mtar 22mwill read the file 4mfoo124m from the
641 current directory and add it to the output archive. It will then read
642 each entry from 4mold.tgz24m and add those entries to the output archive.
643 Finally, it will switch to the 4m/tmp24m directory and add 4mfoo224m to the output
646 An input file in mtree(5) format can be used to create an output archive
647 with arbitrary ownership, permissions, or names that differ from existing
652 usr/bin uid=0 gid=0 mode=0755 type=dir
653 usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
654 $ tar -cvf output.tar @input.mtree
656 The 1m--newer 22mand 1m--newer-mtime 22mswitches accept a variety of common date
657 and time specifications, including “12 Mar 2005 7:14:29pm”, “2005-03-12
658 19:14”, “5 minutes ago”, and “19:14 PST May 1”.
660 The 1m--options 22margument can be used to control various details of archive
661 generation or reading. For example, you can generate mtree output which
662 only contains 1mtype22m, 1mtime22m, and 1muid 22mkeywords:
663 1mtar -cf 4m22mfile.tar24m 1m--format=mtree --options='!all,type,time,uid' 4m22mdir0m
664 or you can set the compression level used by gzip or xz compression:
665 1mtar -czf 4m22mfile.tar24m 1m--options='compression-level=9'22m.
666 For more details, see the explanation of the 1marchive_read_set_options22m()
667 and 1marchive_write_set_options22m() API calls that are described in
668 archive_read(3) and archive_write(3).
671 The bundled-arguments format is supported for compatibility with historic
672 implementations. It consists of an initial word (with no leading - char‐
673 acter) in which each character indicates an option. Arguments follow as
674 separate words. The order of the arguments must match the order of the
675 corresponding characters in the bundled command word. For example,
676 1mtar tbf 32 4m22mfile.tar0m
677 specifies three flags 1mt22m, 1mb22m, and 1mf22m. The 1mb 22mand 1mf 22mflags both require argu‐
678 ments, so there must be two additional items on the command line. The 4m320m
679 is the argument to the 1mb 22mflag, and 4mfile.tar24m is the argument to the 1mf0m
682 The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and
685 For maximum portability, scripts that invoke 1mtar 22mshould use the bundled-
686 argument format above, should limit themselves to the 1mc22m, 1mt22m, and 1mx 22mmodes,
687 and the 1mb22m, 1mf22m, 1mm22m, 1mv22m, and 1mw 22moptions.
689 Additional long options are provided to improve compatibility with other
693 Certain security issues are common to many archiving programs, including
694 1mtar22m. In particular, carefully-crafted archives can request that 1mtar0m
695 extract files to locations outside of the target directory. This can
696 potentially be used to cause unwitting users to overwrite files they did
697 not intend to overwrite. If the archive is being extracted by the supe‐
698 ruser, any file on the system can potentially be overwritten. There are
699 three ways this can happen. Although 1mtar 22mhas mechanisms to protect
700 against each one, savvy users should be aware of the implications:
702 1m· 22mArchive entries can have absolute pathnames. By default, 1mtar0m
703 removes the leading 4m/24m character from filenames before restoring
704 them to guard against this problem.
706 1m· 22mArchive entries can have pathnames that include 4m..24m components.
707 By default, 1mtar 22mwill not extract files containing 4m..24m components
710 1m· 22mArchive entries can exploit symbolic links to restore files to
711 other directories. An archive can restore a symbolic link to
712 another directory, then use that link to restore a file into that
713 directory. To guard against this, 1mtar 22mchecks each extracted path
714 for symlinks. If the final path element is a symlink, it will be
715 removed and replaced with the archive entry. If 1m-U 22mis specified,
716 any intermediate symlink will also be unconditionally removed.
717 If neither 1m-U 22mnor 1m-P 22mis specified, 1mtar 22mwill refuse to extract the
719 To protect yourself, you should be wary of any archives that come from
720 untrusted sources. You should examine the contents of an archive with
721 1mtar -tf 4m22mfilename0m
722 before extraction. You should use the 1m-k 22moption to ensure that 1mtar 22mwill
723 not overwrite any existing files or the 1m-U 22moption to remove any pre-
724 existing files. You should generally not extract archives while running
725 with super-user privileges. Note that the 1m-P 22moption to 1mtar 22mdisables the
726 security checks above and allows you to extract an archive while preserv‐
727 ing any absolute pathnames, 4m..24m components, or symlinks to other directo‐
731 bzip2(1), compress(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), xz(1),
732 libarchive(3), libarchive-formats(5), tar(5)
735 There is no current POSIX standard for the tar command; it appeared in
736 ISO/IEC 9945-1:1996 (“POSIX.1”) but was dropped from IEEE Std 1003.1-2001
737 (“POSIX.1”). The options supported by this implementation were developed
738 by surveying a number of existing tar implementations as well as the old
739 POSIX specification for tar and the current POSIX specification for pax.
741 The ustar and pax interchange file formats are defined by IEEE Std
742 1003.1-2001 (“POSIX.1”) for the pax command.
745 A 1mtar 22mcommand appeared in Seventh Edition Unix, which was released in
746 January, 1979. There have been numerous other implementations, many of
747 which extended the file format. John Gilmore's 1mpdtar 22mpublic-domain
748 implementation (circa November, 1987) was quite influential, and formed
749 the basis of GNU tar. GNU tar was included as the standard system tar in
750 FreeBSD beginning with FreeBSD 1.0.
752 This is a complete re-implementation based on the libarchive(3) library.
753 It was first released with FreeBSD 5.4 in May, 2005.
756 This program follows ISO/IEC 9945-1:1996 (“POSIX.1”) for the definition
757 of the 1m-l 22moption. Note that GNU tar prior to version 1.15 treated 1m-l 22mas
758 a synonym for the 1m--one-file-system 22moption.
760 The 1m-C 4m22mdir24m option may differ from historic implementations.
762 All archive output is written in correctly-sized blocks, even if the out‐
763 put is being compressed. Whether or not the last output block is padded
764 to a full block size varies depending on the format and the output
765 device. For tar and cpio formats, the last block of output is padded to
766 a full block size if the output is being written to standard output or to
767 a character or block device such as a tape drive. If the output is being
768 written to a regular file, the last block will not be padded. Many com‐
769 pressors, including gzip(1) and bzip2(1), complain about the null padding
770 when decompressing an archive created by 1mtar22m, although they still extract
773 The compression and decompression is implemented internally, so there may
774 be insignificant differences between the compressed output generated by
775 1mtar -czf 4m22m-24m 4mfile0m
776 and that generated by
777 1mtar -cf 4m22m-24m 4mfile24m | 1mgzip0m
779 The default should be to read and write archives to the standard I/O
780 paths, but tradition (and POSIX) dictates otherwise.
782 The 1mr 22mand 1mu 22mmodes require that the archive be uncompressed and located in
783 a regular file on disk. Other archives can be modified using 1mc 22mmode with
784 the 4m@archive-file24m extension.
786 To archive a file called 4m@foo24m or 4m-foo24m you must specify it as 4m./@foo24m or
787 4m./-foo24m, respectively.
789 In create mode, a leading 4m./24m is always removed. A leading 4m/24m is stripped
790 unless the 1m-P 22moption is specified.
792 There needs to be better support for file selection on both create and
795 There is not yet any support for multi-volume archives.
797 Converting between dissimilar archive formats (such as tar and cpio)
798 using the 1m@4m22m-24m convention can cause hard link information to be lost.
799 (This is a consequence of the incompatible ways that different archive
800 formats store hardlink information.)
802 BSD February 24, 2017 BSD
projects / platform / upstream / libarchive.git / blob