1 .TH TAR 1 "February 24, 2017" ""
5 \- manipulate tape archives
10 [\fIbundled-flags\fP <args>]
11 [<\fIfile\fP> | <\fIpattern\fP> ...]
16 [\fIfiles\fP | \fIdirectories\fP]
19 {\fB\-r\fP | \fB\-u\fP}
20 \fB\-f\fP \fIarchive-file\fP
22 [\fIfiles\fP | \fIdirectories\fP]
25 {\fB\-t\fP | \fB\-x\fP}
31 creates and manipulates streaming archive files.
32 This implementation can extract from tar, pax, cpio, zip, jar, ar, xar,
33 rpm, 7-zip, and ISO 9660 cdrom images and can create tar, pax, cpio, ar, zip,
34 7-zip, and shar archives.
36 The first synopsis form shows a
39 This usage is provided for compatibility with historical implementations.
40 See COMPATIBILITY below for details.
42 The other synopsis forms show the preferred usage.
45 is a mode indicator from the following list:
49 Create a new archive containing the specified items.
50 The long option form is
56 but new entries are appended to the archive.
57 Note that this only works on uncompressed archives stored in regular files.
61 The long option form is
65 List archive contents to stdout.
66 The long option form is
72 but new entries are added only if they have a modification date
73 newer than the corresponding entry in the archive.
74 Note that this only works on uncompressed archives stored in regular files.
82 Extract to disk from the archive.
83 If a file with the same name appears more than once in the archive,
84 each copy will be extracted, with later copies overwriting (replacing)
86 The long option form is
95 mode, each specified file or directory is added to the
96 archive in the order specified on the command line.
97 By default, the contents of each directory are also archived.
99 In extract or list mode, the entire command line
100 is read and parsed before the archive is opened.
101 The pathnames or patterns on the command line indicate
102 which items in the archive should be processed.
103 Patterns are shell-style globbing patterns as
108 Unless specifically stated otherwise, options are applicable in
112 \fB@\fP \fIarchive\fP
114 The specified archive is opened and the entries
115 in it will be appended to the current archive.
118 \fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fB@\fP \fIoriginal.tar\fP
120 writes a new archive to standard output containing a file
122 and all of the entries from
126 \fB\%tar\fP \fB\-c\fP \fB\-f\fP \fI-\fP \fInewfile\fP \fIoriginal.tar\fP
128 creates a new archive with only two entries.
131 \fB\%tar\fP \fB\-czf\fP \fI-\fP \fB\-Fl\fP format \fBpax\fP \fB@\fP \fI-\fP
133 reads an archive from standard input (whose format will be determined
134 automatically) and converts it into a gzip-compressed
135 pax-format archive on stdout.
138 can be used to convert archives from one format to another.
140 \fB\-a\fP, \fB\-Fl\fP auto-compress
142 Use the archive suffix to decide a set of the format and
146 \fB\%tar\fP \fB\-a\fP \fB\-cf\fP \fIarchive.tgz\fP source.c source.h
148 creates a new archive with restricted pax format and gzip compression,
150 \fB\%tar\fP \fB\-a\fP \fB\-cf\fP \fIarchive.tar.bz2.uu\fP source.c source.h
152 creates a new archive with restricted pax format and bzip2 compression
153 and uuencode compression,
155 \fB\%tar\fP \fB\-a\fP \fB\-cf\fP \fIarchive.zip\fP source.c source.h
157 creates a new archive with zip format,
159 \fB\%tar\fP \fB\-a\fP \fB\-jcf\fP \fIarchive.tgz\fP source.c source.h
163 option, and creates a new archive with restricted pax format
164 and gzip compression,
166 \fB\%tar\fP \fB\-a\fP \fB\-jcf\fP \fIarchive.xxx\fP source.c source.h
168 if it is unknown suffix or no suffix, creates a new archive with
169 restricted pax format and bzip2 compression.
172 (c, r, u, x modes only)
173 Archive or extract POSIX.1e or NFSv4 ACLs. This is the reverse of
175 and the default behavior in c, r, and u modes (except Mac OS X) or if
177 is run in x mode as root. On Mac OS X this option translates extended ACLs
178 to NFSv4 ACLs. To store extended ACLs the
179 \fB\-Fl\fP mac-metadata
182 \fB\-B\fP, \fB\-Fl\fP read-full-blocks
183 Ignored for compatibility with other
187 \fB\-b\fP \fIblocksize\fP, \fB\-Fl\fP block-size \fIblocksize\fP
188 Specify the block size, in 512-byte records, for tape drive I/O.
189 As a rule, this argument is only needed when reading from or writing
190 to tape drives, and usually not even then as the default block size of
191 20 records (10240 bytes) is very common.
193 \fB\-C\fP \fIdirectory\fP, \fB\-Fl\fP cd \fIdirectory\fP, \fB\-Fl\fP directory \fIdirectory\fP
194 In c and r mode, this changes the directory before adding
196 In x mode, change directories after opening the archive
197 but before extracting entries from the archive.
202 to the current directory after processing any
204 options and before extracting any files.
206 \fB\-Fl\fP clear-nochange-fflags
208 Before removing file system objects to replace them, clear platform-specific
209 file flags that might prevent removal.
211 \fB\-Fl\fP exclude \fIpattern\fP
212 Do not process files or directories that match the
214 Note that exclusions take precedence over patterns or filenames
215 specified on the command line.
218 (c, r, u, x modes only)
219 Archive or extract file flags. This is the reverse of
221 and the default behavior in c, r, and u modes or if
223 is run in x mode as root.
225 \fB\-Fl\fP format \fIformat\fP
227 Use the specified format for the created archive.
228 Supported formats include
234 Other formats may also be supported; see
235 \fBlibarchive-formats\fP(5)
236 for more information about currently-supported formats.
237 In r and u modes, when extending an existing archive, the format specified
238 here must be compatible with the format of the existing archive on disk.
240 \fB\-f\fP \fIfile\fP, \fB\-Fl\fP file \fIfile\fP
241 Read the archive from or write the archive to the specified file.
244 for standard input or standard output.
245 The default varies by system;
250 on Linux, the default is
253 \fB\-Fl\fP gid \fIid\fP
254 Use the provided group id number.
255 On extract, this overrides the group id in the archive;
256 the group name in the archive will be ignored.
257 On create, this overrides the group id read from disk;
260 is not also specified, the group name will be set to
263 \fB\-Fl\fP gname \fIname\fP
264 Use the provided group name.
265 On extract, this overrides the group name in the archive;
266 if the provided group name does not exist on the system,
268 (from the archive or from the
271 will be used instead.
272 On create, this sets the group name that will be stored
274 the name will not be verified against the system group database.
278 Symbolic links named on the command line will be followed; the
279 target of the link will be archived, not the link itself.
293 \fB\-Fl\fP hfsCompression
295 Mac OS X specific (v10.6 or later). Compress extracted regular files with HFS+
298 \fB\-Fl\fP ignore-zeros
300 \fB\-Fl\fP options \fBread_concatenated_archives\fP
301 for compatibility with GNU tar.
303 \fB\-Fl\fP include \fIpattern\fP
304 Process only files or directories that match the specified pattern.
305 Note that exclusions specified with
307 take precedence over inclusions.
308 If no inclusions are explicitly specified, all entries are processed by
312 option is especially useful when filtering archives.
313 For example, the command
315 \fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fB\-Fl\fP include='*foo*' \fB@\fP \fIold.tgz\fP
317 creates a new archive
319 containing only the entries from
321 containing the string
324 \fB\-J\fP, \fB\-Fl\fP xz
326 Compress the resulting archive with
328 In extract or list modes, this option is ignored.
329 Note that, unlike other
331 implementations, this implementation recognizes XZ compression
332 automatically when reading archives.
334 \fB\-j\fP, \fB\-Fl\fP bzip, \fB\-Fl\fP bzip2, \fB\-Fl\fP bunzip2
336 Compress the resulting archive with
338 In extract or list modes, this option is ignored.
339 Note that, unlike other
341 implementations, this implementation recognizes bzip2 compression
342 automatically when reading archives.
344 \fB\-k\fP, \fB\-Fl\fP keep-old-files
346 Do not overwrite existing files.
347 In particular, if a file appears more than once in an archive,
348 later copies will not overwrite earlier copies.
350 \fB\-Fl\fP keep-newer-files
352 Do not overwrite existing files that are newer than the
353 versions appearing in the archive being extracted.
355 \fB\-L\fP, \fB\-Fl\fP dereference
357 All symbolic links will be followed.
358 Normally, symbolic links are archived as such.
359 With this option, the target of the link will be archived instead.
361 \fB\-l\fP, \fB\-Fl\fP check-links
363 Issue a warning message unless all links to each file are archived.
367 Compress the resulting archive with
369 In extract or list modes, this option is ignored.
373 Compress the archive with lz4-compatible compression before writing it.
374 In input mode, this option is ignored; lz4 compression is recognized
375 automatically on input.
378 (c mode only) Compress the resulting archive with the original LZMA algorithm.
379 Use of this option is discouraged and new archives should be created with
382 Note that, unlike other
384 implementations, this implementation recognizes LZMA compression
385 automatically when reading archives.
389 Compress the resulting archive with
391 In extract or list modes, this option is ignored.
393 \fB\-m\fP, \fB\-Fl\fP modification-time
395 Do not extract modification time.
396 By default, the modification time is set to the time stored in the archive.
398 \fB\-Fl\fP mac-metadata
399 (c, r, u and x mode only)
400 Mac OS X specific. Archive or extract extended ACLs and extended attributes
403 in AppleDouble format. This is the reverse of
404 \fB\-Fl\fP no-mac-metadata.
405 and the default behavior in c, r, and u modes or if
407 is run in x mode as root.
409 \fB\-n\fP, \fB\-Fl\fP norecurse, \fB\-Fl\fP no-recursion
411 Do not recursively archive the contents of directories.
413 \fB\-Fl\fP newer \fIdate\fP
415 Only include files and directories newer than the specified date.
416 This compares ctime entries.
418 \fB\-Fl\fP newer-mtime \fIdate\fP
422 except it compares mtime entries instead of ctime entries.
424 \fB\-Fl\fP newer-than \fIfile\fP
426 Only include files and directories newer than the specified file.
427 This compares ctime entries.
429 \fB\-Fl\fP newer-mtime-than \fIfile\fP
432 \fB\-Fl\fP newer-than,
433 except it compares mtime entries instead of ctime entries.
437 Honor the nodump file flag by skipping this file.
439 \fB\-Fl\fP nopreserveHFSCompression
441 Mac OS X specific(v10.6 or later). Do not compress extracted regular files
442 which were compressed with HFS+ compression before archived.
443 By default, compress the regular files again with HFS+ compression.
450 Filenames or patterns are separated by null characters,
452 This is often used to read filenames output by the
458 (c, r, u, x modes only)
459 Do not archive or extract POSIX.1e or NFSv4 ACLs. This is the reverse of
461 and the default behavior if
463 is run as non-root in x mode (on Mac OS X also in c, r and u modes).
466 (c, r, u, x modes only)
467 Do not archive or extract file flags. This is the reverse of
469 and the default behavior if
471 is run as non-root in x mode.
473 \fB\-Fl\fP no-mac-metadata
475 Mac OS X specific. Do not archive or extract ACLs and extended attributes using
477 in AppleDouble format. This is the reverse of
478 \fB\-Fl\fP mac-metadata.
479 and the default behavior if
481 is run as non-root in x mode.
483 \fB\-n\fP, \fB\-Fl\fP norecurse, \fB\-Fl\fP no-recursion
485 \fB\-Fl\fP no-same-owner
487 Do not extract owner and group IDs.
488 This is the reverse of
489 \fB\-Fl\fP same-owner
490 and the default behavior if
494 \fB\-Fl\fP no-same-permissions
496 Do not extract full permissions (SGID, SUID, sticky bit, ACLs,
497 extended attributes or extended file flags).
498 This is the reverse of
500 and the default behavior if
502 is run as non-root and can be overridden by also specifying
505 \fB\-Fl\fP mac-metadata,
506 \fB\-Fl\fP same-owner,
507 \fB\-Fl\fP same-permissions
512 (c, r, u, x modes only)
513 Do not archive or extract extended attributes. This is the reverse of
515 and the default behavior if
517 is run as non-root in x mode.
519 \fB\-Fl\fP numeric-owner
520 This is equivalent to
525 On extract, it causes user and group names in the archive
526 to be ignored in favor of the numeric user and group ids.
527 On create, it causes user and group names to not be stored
530 \fB\-O\fP, \fB\-Fl\fP to-stdout
532 In extract (-x) mode, files will be written to standard out rather than
533 being extracted to disk.
534 In list (-t) mode, the file listing will be written to stderr rather than
539 Use the user and group of the user running the program rather
540 than those specified in the archive.
541 Note that this has no significance unless
543 is specified, and the program is being run by the root user.
544 In this case, the file modes and flags from
545 the archive will be restored, but ACLs or owner information in
546 the archive will be discarded.
551 \fB\-Fl\fP format \fIustar\fP
553 \fB\-Fl\fP older \fIdate\fP
555 Only include files and directories older than the specified date.
556 This compares ctime entries.
558 \fB\-Fl\fP older-mtime \fIdate\fP
562 except it compares mtime entries instead of ctime entries.
564 \fB\-Fl\fP older-than \fIfile\fP
566 Only include files and directories older than the specified file.
567 This compares ctime entries.
569 \fB\-Fl\fP older-mtime-than \fIfile\fP
572 \fB\-Fl\fP older-than,
573 except it compares mtime entries instead of ctime entries.
575 \fB\-Fl\fP one-file-system
577 Do not cross mount points.
579 \fB\-Fl\fP options \fIoptions\fP
580 Select optional behaviors for particular modules.
581 The argument is a text string containing comma-separated
583 These are passed to the modules that handle particular
584 formats to control how those formats will behave.
585 Each option has one of the following forms:
589 The key will be set to the specified value in every module that supports it.
590 Modules that do not support this key will ignore it.
593 The key will be enabled in every module that supports it.
594 This is equivalent to
598 The key will be disabled in every module that supports it.
600 \fImodule:key=value\fP, \fImodule:key\fP, \fImodule:!key\fP
601 As above, but the corresponding key and value will be provided
602 only to modules whose name matches
605 The currently supported modules and keys are:
609 Support Joliet extensions.
610 This is enabled by default, use
613 \fBiso9660:!joliet\fP
616 \fBiso9660:rockridge\fP
617 Support Rock Ridge extensions.
618 This is enabled by default, use
621 \fBiso9660:!rockridge\fP
624 \fBgzip:compression-level\fP
625 A decimal integer from 1 to 9 specifying the gzip compression level.
628 Store timestamp. This is enabled by default, use
631 \fBgzip:!timestamp\fP
634 \fBlrzip:compression\fP=\fItype\fP
637 as compression method.
638 Supported values are bzip2, gzip, lzo (ultra fast),
639 and zpaq (best, extremely slow).
641 \fBlrzip:compression-level\fP
642 A decimal integer from 1 to 9 specifying the lrzip compression level.
644 \fBlz4:compression-level\fP
645 A decimal integer from 1 to 9 specifying the lzop compression level.
647 \fBlz4:stream-checksum\fP
648 Enable stream checksum. This is by default, use
649 \fBlz4:!stream-checksum\fP
652 \fBlz4:block-checksum\fP
653 Enable block checksum (Disabled by default).
656 A decimal integer from 4 to 7 specifying the lz4 compression block size
657 (7 is set by default).
659 \fBlz4:block-dependence\fP
660 Use the previous block of the block being compressed for
661 a compression dictionary to improve compression ratio.
663 \fBlzop:compression-level\fP
664 A decimal integer from 1 to 9 specifying the lzop compression level.
666 \fBxz:compression-level\fP
667 A decimal integer from 0 to 9 specifying the xz compression level.
669 \fBmtree:\fP \fIkeyword\fP
670 The mtree writer module allows you to specify which mtree keywords
671 will be included in the output.
672 Supported keywords include:
673 \fBcksum\fP, \fBdevice\fP, \fBflags\fP, \fBgid\fP, \fBgname\fP, \fBindent\fP,
674 \fBlink\fP, \fBmd5\fP, \fBmode\fP, \fBnlink\fP, \fBrmd160\fP, \fBsha1\fP, \fBsha256\fP,
675 \fBsha384\fP, \fBsha512\fP, \fBsize\fP, \fBtime\fP, \fBuid\fP, \fBuname\fP.
676 The default is equivalent to:
677 ``device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname''.
680 Enables all of the above keywords.
683 to disable all keywords.
691 Produce human-readable output by indenting options and splitting lines
692 to fit into 80 columns.
694 \fBzip:compression\fP=\fItype\fP
697 as compression method.
698 Supported values are store (uncompressed) and deflate (gzip algorithm).
701 Enable encryption using traditional zip encryption.
703 \fBzip:encryption\fP=\fItype\fP
707 Supported values are zipcrypt (traditional zip encryption),
708 aes128 (WinZip AES-128 encryption) and aes256 (WinZip AES-256 encryption).
710 \fBread_concatenated_archives\fP
711 Ignore zeroed blocks in the archive, which occurs when multiple tar archives
712 have been concatenated together. Without this option, only the contents of
713 the first concatenated archive would be read. This option is comparable to
715 \fB\-i\fP, \fB\-Fl\fP ignore-zeros
718 If a provided option is not supported by any module, that
721 \fB\-P\fP, \fB\-Fl\fP absolute-paths
723 By default, absolute pathnames (those that begin with a /
724 character) have the leading slash removed both when creating archives
725 and extracting from them.
728 will refuse to extract archive entries whose pathnames contain
730 or whose target directory would be altered by a symlink.
731 This option suppresses these behaviors.
733 \fB\-p\fP, \fB\-Fl\fP insecure, \fB\-Fl\fP preserve-permissions
735 Preserve file permissions.
736 Attempt to restore the full permissions, including owner, file modes, ACLs,
737 extended atributes and extended file flags, if available, for each item
738 extracted from the archive. This is the default, if
740 is being run by root and can be overridden by also specifying
742 \fB\-Fl\fP no-fflags,
743 \fB\-Fl\fP no-mac-metadata,
744 \fB\-Fl\fP no-same-owner,
745 \fB\-Fl\fP no-same-permissions
747 \fB\-Fl\fP no-xattrs.
749 \fB\-Fl\fP passphrase \fIpassphrase\fP
752 is used to extract or create an encrypted archive.
753 Currently, zip is the only supported format that supports encryption.
754 You shouldn't use this option unless you realize how insecure
755 use of this option is.
760 \fB\-Fl\fP format \fIpax\fP
762 \fB\-q\fP, \fB\-Fl\fP fast-read
764 Extract or list only the first archive entry that matches each pattern
766 Exit as soon as each specified pattern or filename has been matched.
767 By default, the archive is always read to the very end, since
768 there can be multiple entries with the same name and, by convention,
769 later entries overwrite earlier entries.
770 This option is provided as a performance optimization.
774 Extract files as sparse files.
775 For every block on disk, check first if it contains only NULL bytes and seek
777 This works similar to the conv=sparse option of dd.
779 \fB\-s\fP \fIpattern\fP
780 Modify file or archive member names according to
782 The pattern has the format
783 \fI/old/new/\fP [ghHprRsS]
786 is a basic regular expression,
788 is the replacement string of the matched part,
789 and the optional trailing letters modify
790 how the replacement is handled.
793 is not matched, the pattern is skipped.
796 ~ is substituted with the match, \e1 to \e9 with the content of
797 the corresponding captured group.
798 The optional trailing g specifies that matching should continue
799 after the matched part and stop on the first unmatched pattern.
800 The optional trailing s specifies that the pattern applies to the value
802 The optional trailing p specifies that after a successful substitution
803 the original path name and the new path name should be printed to
805 Optional trailing H, R, or S characters suppress substitutions
806 for hardlink targets, regular filenames, or symlink targets,
808 Optional trailing h, r, or s characters enable substitutions
809 for hardlink targets, regular filenames, or symlink targets,
813 which applies substitutions to all names.
814 In particular, it is never necessary to specify h, r, or s.
816 \fB\-Fl\fP same-owner
818 Extract owner and group IDs.
819 This is the reverse of
820 \fB\-Fl\fP no-same-owner
821 and the default behavior if
825 \fB\-Fl\fP strip-components \fIcount\fP
826 Remove the specified number of leading path elements.
827 Pathnames with fewer elements will be silently skipped.
828 Note that the pathname is edited after checking inclusion/exclusion patterns
829 but before security checks.
831 \fB\-T\fP \fIfilename\fP, \fB\-Fl\fP files-from \fIfilename\fP
834 will read the list of names to be extracted from
838 will read names to be archived from
842 on a line by itself will cause the current directory to be changed to
843 the directory specified on the following line.
844 Names are terminated by newlines unless
849 also disables the special handling of lines containing
851 Note: If you are generating lists of files using
853 you probably want to use
859 After archiving all files, print a summary to stderr.
861 \fB\-U\fP, \fB\-Fl\fP unlink, \fB\-Fl\fP unlink-first
863 Unlink files before creating them.
864 This can be a minor performance optimization if most files
865 already exist, but can make things slower if most files
866 do not already exist.
867 This flag also causes
869 to remove intervening directory symlinks instead of
871 See the SECURITY section below for more details.
873 \fB\-Fl\fP uid \fIid\fP
874 Use the provided user id number and ignore the user
875 name from the archive.
878 is not also specified, the user name will be set to
881 \fB\-Fl\fP uname \fIname\fP
882 Use the provided user name.
883 On extract, this overrides the user name in the archive;
884 if the provided user name does not exist on the system,
885 it will be ignored and the user id
886 (from the archive or from the
889 will be used instead.
890 On create, this sets the user name that will be stored
892 the name is not verified against the system user database.
894 \fB\-Fl\fP use-compress-program \fIprogram\fP
895 Pipe the input (in x or t mode) or the output (in c mode) through
897 instead of using the builtin compression support.
899 \fB\-v\fP, \fB\-Fl\fP verbose
900 Produce verbose output.
901 In create and extract modes,
903 will list each file name as it is read from or written to
907 will produce output similar to that of
911 option will also provide ls-like details in create and extract mode.
920 \fB\-w\fP, \fB\-Fl\fP confirmation, \fB\-Fl\fP interactive
921 Ask for confirmation for every action.
923 \fB\-X\fP \fIfilename\fP, \fB\-Fl\fP exclude-from \fIfilename\fP
924 Read a list of exclusion patterns from the specified file.
927 for more information about the handling of exclusions.
930 (c, r, u, x modes only)
931 Archive or extract extended attributes. This is the reverse of
933 and the default behavior in c, r, and u modes or if
935 is run in x mode as root.
939 Compress the resulting archive with
941 In extract or list modes, this option is ignored.
942 Note that, unlike other
944 implementations, this implementation recognizes bzip2 compression
945 automatically when reading archives.
947 \fB\-Z\fP, \fB\-Fl\fP compress, \fB\-Fl\fP uncompress
949 Compress the resulting archive with
951 In extract or list modes, this option is ignored.
952 Note that, unlike other
954 implementations, this implementation recognizes compress compression
955 automatically when reading archives.
957 \fB\-z\fP, \fB\-Fl\fP gunzip, \fB\-Fl\fP gzip
959 Compress the resulting archive with
961 In extract or list modes, this option is ignored.
962 Note that, unlike other
964 implementations, this implementation recognizes gzip compression
965 automatically when reading archives.
969 The following environment variables affect the execution of
973 .B TAR_READER_OPTIONS
974 The default options for format readers and compression readers.
977 option overrides this.
979 .B TAR_WRITER_OPTIONS
980 The default options for format writers and compression writers.
983 option overrides this.
989 for more information.
995 option overrides this.
996 Please see the description of the
998 option above for more details.
1001 The timezone to use when displaying dates.
1004 for more information.
1008 The \fBtar\fP utility exits 0 on success, and >0 if an error occurs.
1011 The following creates a new archive
1014 that contains two files
1019 \fB\%tar\fP \fB\-czf\fP \fIfile.tar.gz\fP \fIsource.c\fP \fIsource.h\fP
1022 To view a detailed table of contents for this
1025 \fB\%tar\fP \fB\-tvf\fP \fIfile.tar.gz\fP
1028 To extract all entries from the archive on
1029 the default tape drive:
1031 \fB\%tar\fP \fB\-x\fP
1034 To examine the contents of an ISO 9660 cdrom image:
1036 \fB\%tar\fP \fB\-tf\fP \fIimage.iso\fP
1039 To move file hierarchies, invoke
1043 \fB\%tar\fP \fB\-cf\fP \fI-\fP \fB\-C\fP \fIsrcdir\\fP. | \fB\%tar\fP \fB\-xpf\fP \fI-\fP \fB\-C\fP \fIdestdir\fP
1045 or more traditionally
1047 cd srcdir \&; \fB\%tar\fP \fB\-cf\fP \fI-\\fP. | (cd destdir \&; \fB\%tar\fP \fB\-xpf\fP \fI-\fP)
1050 In create mode, the list of files and directories to be archived
1051 can also include directory change instructions of the form
1052 \fB-C\fP \fIfoo/baz\fP
1053 and archive inclusions of the form
1054 \fB@\fP \fIarchive-file\fP.
1055 For example, the command line
1057 \fB\%tar\fP \fB\-c\fP \fB\-f\fP \fInew.tar\fP \fIfoo1\fP \fB@\fP \fIold.tgz\fP \fB-C\fP \fI/tmp\fP \fIfoo2\fP
1059 will create a new archive
1064 from the current directory and add it to the output archive.
1065 It will then read each entry from
1067 and add those entries to the output archive.
1068 Finally, it will switch to the
1072 to the output archive.
1076 format can be used to create an output archive with arbitrary ownership,
1077 permissions, or names that differ from existing data on disk:
1083 usr/bin uid=0 gid=0 mode=0755 type=dir
1084 usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
1085 $ tar -cvf output.tar @input.mtree
1091 \fB\-Fl\fP newer-mtime
1092 switches accept a variety of common date and time specifications, including
1093 ``12 Mar 2005 7:14:29pm'',
1094 ``2005-03-12 19:14'',
1097 ``19:14 PST May 1''.
1101 argument can be used to control various details of archive generation
1103 For example, you can generate mtree output which only contains
1104 \fBtype\fP, \fBtime\fP,
1109 \fB\%tar\fP \fB\-cf\fP \fIfile.tar\fP \fB\-Fl\fP format=mtree \fB\-Fl\fP options='!all,type,time,uid' \fIdir\fP
1111 or you can set the compression level used by gzip or xz compression:
1113 \fB\%tar\fP \fB\-czf\fP \fIfile.tar\fP \fB\-Fl\fP options='compression-level=9'.
1115 For more details, see the explanation of the
1116 \fB\%archive_read_set_options\fP()
1118 \fB\%archive_write_set_options\fP()
1119 API calls that are described in
1120 \fBarchive_read\fP(3)
1122 \fBarchive_write\fP(3).
1125 The bundled-arguments format is supported for compatibility
1126 with historic implementations.
1127 It consists of an initial word (with no leading - character) in which
1128 each character indicates an option.
1129 Arguments follow as separate words.
1130 The order of the arguments must match the order
1131 of the corresponding characters in the bundled command word.
1134 \fB\%tar\fP \fBtbf\fP 32 \fIfile.tar\fP
1136 specifies three flags
1145 flags both require arguments,
1146 so there must be two additional items
1147 on the command line.
1150 is the argument to the
1154 is the argument to the
1158 The mode options c, r, t, u, and x and the options
1159 b, f, l, m, o, v, and w comply with SUSv2.
1161 For maximum portability, scripts that invoke
1163 should use the bundled-argument format above, should limit
1178 Additional long options are provided to improve compatibility with other
1179 tar implementations.
1182 Certain security issues are common to many archiving programs, including
1184 In particular, carefully-crafted archives can request that
1186 extract files to locations outside of the target directory.
1187 This can potentially be used to cause unwitting users to overwrite
1188 files they did not intend to overwrite.
1189 If the archive is being extracted by the superuser, any file
1190 on the system can potentially be overwritten.
1191 There are three ways this can happen.
1194 has mechanisms to protect against each one,
1195 savvy users should be aware of the implications:
1198 Archive entries can have absolute pathnames.
1203 character from filenames before restoring them to guard against this problem.
1205 Archive entries can have pathnames that include
1210 will not extract files containing
1212 components in their pathname.
1214 Archive entries can exploit symbolic links to restore
1215 files to other directories.
1216 An archive can restore a symbolic link to another directory,
1217 then use that link to restore a file into that directory.
1218 To guard against this,
1220 checks each extracted path for symlinks.
1221 If the final path element is a symlink, it will be removed
1222 and replaced with the archive entry.
1225 is specified, any intermediate symlink will also be unconditionally removed.
1232 will refuse to extract the entry.
1234 To protect yourself, you should be wary of any archives that
1235 come from untrusted sources.
1236 You should examine the contents of an archive with
1238 \fB\%tar\fP \fB\-tf\fP \fIfilename\fP
1243 option to ensure that
1245 will not overwrite any existing files or the
1247 option to remove any pre-existing files.
1248 You should generally not extract archives while running with super-user
1254 disables the security checks above and allows you to extract
1255 an archive while preserving any absolute pathnames,
1257 components, or symlinks to other directories.
1268 \fBlibarchive\fP(3),
1269 \fBlibarchive-formats\fP(5),
1273 There is no current POSIX standard for the tar command; it appeared
1275 ISO/IEC 9945-1:1996 (``POSIX.1'')
1276 but was dropped from
1277 IEEE Std 1003.1-2001 (``POSIX.1'').
1278 The options supported by this implementation were developed by surveying a
1279 number of existing tar implementations as well as the old POSIX specification
1280 for tar and the current POSIX specification for pax.
1282 The ustar and pax interchange file formats are defined by
1283 IEEE Std 1003.1-2001 (``POSIX.1'')
1284 for the pax command.
1289 command appeared in Seventh Edition Unix, which was released in January, 1979.
1290 There have been numerous other implementations,
1291 many of which extended the file format.
1294 public-domain implementation (circa November, 1987)
1295 was quite influential, and formed the basis of GNU tar.
1296 GNU tar was included as the standard system tar
1302 This is a complete re-implementation based on the
1305 It was first released with
1310 This program follows
1311 ISO/IEC 9945-1:1996 (``POSIX.1'')
1312 for the definition of the
1315 Note that GNU tar prior to version 1.15 treated
1317 as a synonym for the
1318 \fB\-Fl\fP one-file-system
1323 option may differ from historic implementations.
1325 All archive output is written in correctly-sized blocks, even
1326 if the output is being compressed.
1327 Whether or not the last output block is padded to a full
1328 block size varies depending on the format and the
1330 For tar and cpio formats, the last block of output is padded
1331 to a full block size if the output is being
1332 written to standard output or to a character or block device such as
1334 If the output is being written to a regular file, the last block
1336 Many compressors, including
1340 complain about the null padding when decompressing an archive created by
1342 although they still extract it correctly.
1344 The compression and decompression is implemented internally, so
1345 there may be insignificant differences between the compressed output
1348 \fB\%tar\fP \fB\-czf\fP \fI-\fP file
1350 and that generated by
1352 \fB\%tar\fP \fB\-cf\fP \fI-\fP file | \fB\%gzip\fP
1355 The default should be to read and write archives to the standard I/O paths,
1356 but tradition (and POSIX) dictates otherwise.
1362 modes require that the archive be uncompressed
1363 and located in a regular file on disk.
1364 Other archives can be modified using
1370 To archive a file called
1374 you must specify it as
1380 In create mode, a leading
1385 is stripped unless the
1387 option is specified.
1389 There needs to be better support for file selection on both create
1392 There is not yet any support for multi-volume archives.
1394 Converting between dissimilar archive formats (such as tar and cpio) using the
1396 convention can cause hard link information to be lost.
1397 (This is a consequence of the incompatible ways that different archive
1398 formats store hardlink information.)