1BSDTAR(1)                 BSD General Commands Manual                BSDTAR(1)
2

NAME

4     bsdtar — manipulate tape archives
5

SYNOPSIS

7     bsdtar [bundled-flags ⟨args⟩] [⟨file⟩ | ⟨pattern⟩ ...]
8     bsdtar {-c} [options] [files | directories]
9     bsdtar {-r | -u} -f archive-file [options] [files | directories]
10     bsdtar {-t | -x} [options] [patterns]
11

DESCRIPTION

13     bsdtar creates and manipulates streaming archive files.  This implementa‐
14     tion can extract from tar, pax, cpio, zip, jar, ar, xar, rpm, 7-zip, and
15     ISO 9660 cdrom images and can create tar, pax, cpio, ar, zip, 7-zip, and
16     shar archives.
17
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.
21
22     The other synopsis forms show the preferred usage.  The first option to
23     bsdtar is a mode indicator from the following list:
24     -c      Create a new archive containing the specified items.  The long
25             option form is --create.
26     -r      Like -c, but new entries are appended to the archive.  Note that
27             this only works on uncompressed archives stored in regular files.
28             The -f option is required.  The long option form is --append.
29     -t      List archive contents to stdout.  The long option form is --list.
30     -u      Like -r, 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 -f option is required.  The long form is
34             --update.
35     -x      Extract 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 --extract.
39
40     In -c, -r, or -u mode, 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.
43
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).
48

OPTIONS

50     Unless specifically stated otherwise, options are applicable in all oper‐
51     ating modes.
52
53     @archive
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‐
56             ple example,
57                   bsdtar -c -f - newfile @original.tar
58             writes a new archive to standard output containing a file newfile
59             and all of the entries from original.tar.  In contrast,
60                   bsdtar -c -f - newfile original.tar
61             creates a new archive with only two entries.  Similarly,
62                   bsdtar -czf - --format pax @-
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, bsdtar can be used to
66             convert archives from one format to another.
67
68     -a, --auto-compress
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                   bsdtar -a -cf archive.tgz source.c source.h
72             creates a new archive with restricted pax format and gzip com‐
73             pression,
74                   bsdtar -a -cf archive.tar.bz2.uu source.c source.h
75             creates a new archive with restricted pax format and bzip2 com‐
76             pression and uuencode compression,
77                   bsdtar -a -cf archive.zip source.c source.h
78             creates a new archive with zip format,
79                   bsdtar -a -jcf archive.tgz source.c source.h
80             ignores the “-j” option, and creates a new archive with
81             restricted pax format and gzip compression,
82                   bsdtar -a -jcf archive.xxx source.c source.h
83             if it is unknown suffix or no suffix, creates a new archive with
84             restricted pax format and bzip2 compression.
85
86     --acls  (c, r, u, x modes only) Archive or extract POSIX.1e or NFSv4
87             ACLs.  This is the reverse of --no-acls and the default behavior
88             in c, r, and u modes (except on Mac OS X) or if bsdtar is run in
89             x mode as root.  On Mac OS X this option translates extended ACLs
90             to NFSv4 ACLs.  To store extended ACLs the --mac-metadata option
91             is preferred.
92
93     -B, --read-full-blocks
94             Ignored for compatibility with other tar(1) implementations.
95
96     -b blocksize, --block-size blocksize
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.
101
102     -C directory, --cd directory, --directory directory
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.
106
107     --chroot
108             (x mode only) chroot() to the current directory after processing
109             any -C options and before extracting any files.
110
111     --clear-nochange-fflags
112             (x mode only) Before removing file system objects to replace
113             them, clear platform-specific file attributes or file flags that
114             might prevent removal.
115
116     --exclude pattern
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.
120
121     --exclude-vcs
122             Do not process files or directories internally used by the ver‐
123             sion control systems ‘Arch’, ‘Bazaar’, ‘CVS’, ‘Darcs’,
124             ‘Mercurial’, ‘RCS’, ‘SCCS’, ‘SVN’ and ‘git’.
125
126     --fflags
127             (c, r, u, x modes only) Archive or extract platform-specific file
128             attributes or file flags.  This is the reverse of --no-fflags and
129             the default behavior in c, r, and u modes or if bsdtar is run in
130             x mode as root.
131
132     --format format
133             (c, r, u mode only) Use the specified format for the created ar‐
134             chive.  Supported formats include “cpio”, “pax”, “shar”, and
135             “ustar”.  Other formats may also be supported; see
136             libarchive-formats(5) for more information about currently-sup‐
137             ported formats.  In r and u modes, when extending an existing ar‐
138             chive, the format specified here must be compatible with the for‐
139             mat of the existing archive on disk.
140
141     -f file, --file file
142             Read the archive from or write the archive to the specified file.
143             The filename can be - for standard input or standard output.  The
144             default varies by system; on FreeBSD, the default is /dev/sa0; on
145             Linux, the default is /dev/st0.
146
147     --gid id
148             Use the provided group id number.  On extract, this overrides the
149             group id in the archive; the group name in the archive will be
150             ignored.  On create, this overrides the group id read from disk;
151             if --gname is not also specified, the group name will be set to
152             match the group id.
153
154     --gname name
155             Use the provided group name.  On extract, this overrides the
156             group name in the archive; if the provided group name does not
157             exist on the system, the group id (from the archive or from the
158             --gid option) will be used instead.  On create, this sets the
159             group name that will be stored in the archive; the name will not
160             be verified against the system group database.
161
162     -H      (c and r modes only) Symbolic links named on the command line
163             will be followed; the target of the link will be archived, not
164             the link itself.
165
166     -h      (c and r modes only) Synonym for -L.
167
168     -I      Synonym for -T.
169
170     --help  Show usage.
171
172     --hfsCompression
173             (x mode only) Mac OS X specific (v10.6 or later). Compress
174             extracted regular files with HFS+ compression.
175
176     --ignore-zeros
177             An alias of --options read_concatenated_archives for compatibil‐
178             ity with GNU tar.
179
180     --include pattern
181             Process only files or directories that match the specified pat‐
182             tern.  Note that exclusions specified with --exclude take prece‐
183             dence over inclusions.  If no inclusions are explicitly speci‐
184             fied, all entries are processed by default.  The --include option
185             is especially useful when filtering archives.  For example, the
186             command
187                   bsdtar -c -f new.tar --include='*foo*' @old.tgz
188             creates a new archive new.tar containing only the entries from
189             old.tgz containing the string ‘foo’.
190
191     -J, --xz
192             (c mode only) Compress the resulting archive with xz(1).  In
193             extract or list modes, this option is ignored.  Note that this
194             tar implementation recognizes XZ compression automatically when
195             reading archives.
196
197     -j, --bzip, --bzip2, --bunzip2
198             (c mode only) Compress the resulting archive with bzip2(1).  In
199             extract or list modes, this option is ignored.  Note that this
200             tar implementation recognizes bzip2 compression automatically
201             when reading archives.
202
203     -k, --keep-old-files
204             (x mode only) Do not overwrite existing files.  In particular, if
205             a file appears more than once in an archive, later copies will
206             not overwrite earlier copies.
207
208     --keep-newer-files
209             (x mode only) Do not overwrite existing files that are newer than
210             the versions appearing in the archive being extracted.
211
212     -L, --dereference
213             (c and r modes only) All symbolic links will be followed.  Nor‐
214             mally, symbolic links are archived as such.  With this option,
215             the target of the link will be archived instead.
216
217     -l, --check-links
218             (c and r modes only) Issue a warning message unless all links to
219             each file are archived.
220
221     --lrzip
222             (c mode only) Compress the resulting archive with lrzip(1).  In
223             extract or list modes, this option is ignored.  Note that this
224             tar implementation recognizes lrzip compression automatically
225             when reading archives.
226
227     --lz4   (c mode only) Compress the archive with lz4-compatible compres‐
228             sion before writing it.  In extract or list modes, this option is
229             ignored.  Note that this tar implementation recognizes lz4 com‐
230             pression automatically when reading archives.
231
232     --zstd  (c mode only) Compress the archive with zstd-compatible compres‐
233             sion before writing it.  In extract or list modes, this option is
234             ignored.  Note that this tar implementation recognizes zstd com‐
235             pression automatically when reading archives.
236
237     --lzma  (c mode only) Compress the resulting archive with the original
238             LZMA algorithm.  In extract or list modes, this option is
239             ignored.  Use of this option is discouraged and new archives
240             should be created with --xz instead.  Note that this tar imple‐
241             mentation recognizes LZMA compression automatically when reading
242             archives.
243
244     --lzop  (c mode only) Compress the resulting archive with lzop(1).  In
245             extract or list modes, this option is ignored.  Note that this
246             tar implementation recognizes LZO compression automatically when
247             reading archives.
248
249     -m, --modification-time
250             (x mode only) Do not extract modification time.  By default, the
251             modification time is set to the time stored in the archive.
252
253     --mac-metadata
254             (c, r, u and x mode only) Mac OS X specific.  Archive or extract
255             extended ACLs and extended file attributes using copyfile(3) in
256             AppleDouble format.  This is the reverse of --no-mac-metadata.
257             and the default behavior in c, r, and u modes or if bsdtar is run
258             in x mode as root.
259
260     -n, --norecurse, --no-recursion
261             Do not operate recursively on the content of directories.
262
263     --newer date
264             (c, r, u modes only) Only include files and directories newer
265             than the specified date.  This compares ctime entries.
266
267     --newer-mtime date
268             (c, r, u modes only) Like --newer, except it compares mtime
269             entries instead of ctime entries.
270
271     --newer-than file
272             (c, r, u modes only) Only include files and directories newer
273             than the specified file.  This compares ctime entries.
274
275     --newer-mtime-than file
276             (c, r, u modes only) Like --newer-than, except it compares mtime
277             entries instead of ctime entries.
278
279     --nodump
280             (c and r modes only) Honor the nodump file flag by skipping this
281             file.
282
283     --nopreserveHFSCompression
284             (x mode only) Mac OS X specific (v10.6 or later). Do not compress
285             extracted regular files which were compressed with HFS+ compres‐
286             sion before archived.  By default, compress the regular files
287             again with HFS+ compression.
288
289     --null  (use with -I or -T) Filenames or patterns are separated by null
290             characters, not by newlines.  This is often used to read file‐
291             names output by the -print0 option to find(1).
292
293     --no-acls
294             (c, r, u, x modes only) Do not archive or extract POSIX.1e or
295             NFSv4 ACLs.  This is the reverse of --acls and the default behav‐
296             ior if bsdtar is run as non-root in x mode (on Mac OS X as any
297             user in c, r, u and x modes).
298
299     --no-fflags
300             (c, r, u, x modes only) Do not archive or extract file attributes
301             or file flags.  This is the reverse of --fflags and the default
302             behavior if bsdtar is run as non-root in x mode.
303
304     --no-mac-metadata
305             (x mode only) Mac OS X specific.  Do not archive or extract ACLs
306             and extended file attributes using copyfile(3) in AppleDouble
307             format.  This is the reverse of --mac-metadata.  and the default
308             behavior if bsdtar is run as non-root in x mode.
309
310     --no-safe-writes
311             (x mode only) Do not create temporary files and use rename(2) to
312             replace the original ones.  This is the reverse of --safe-writes.
313
314     --no-same-owner
315             (x mode only) Do not extract owner and group IDs.  This is the
316             reverse of --same-owner and the default behavior if bsdtar is run
317             as non-root.
318
319     --no-same-permissions
320             (x mode only) Do not extract full permissions (SGID, SUID, sticky
321             bit, file attributes or file flags, extended file attributes and
322             ACLs).  This is the reverse of -p and the default behavior if
323             bsdtar is run as non-root.
324
325     --no-xattrs
326             (c, r, u, x modes only) Do not archive or extract extended file
327             attributes.  This is the reverse of --xattrs and the default
328             behavior if bsdtar is run as non-root in x mode.
329
330     --numeric-owner
331             This is equivalent to --uname "" --gname "".  On extract, it
332             causes user and group names in the archive to be ignored in favor
333             of the numeric user and group ids.  On create, it causes user and
334             group names to not be stored in the archive.
335
336     -O, --to-stdout
337             (x, t modes only) In extract (-x) mode, files will be written to
338             standard out rather than being extracted to disk.  In list (-t)
339             mode, the file listing will be written to stderr rather than the
340             usual stdout.
341
342     -o      (x mode) Use the user and group of the user running the program
343             rather than those specified in the archive.  Note that this has
344             no significance unless -p is specified, and the program is being
345             run by the root user.  In this case, the file modes and flags
346             from the archive will be restored, but ACLs or owner information
347             in the archive will be discarded.
348
349     -o      (c, r, u mode) A synonym for --format ustar
350
351     --older date
352             (c, r, u modes only) Only include files and directories older
353             than the specified date.  This compares ctime entries.
354
355     --older-mtime date
356             (c, r, u modes only) Like --older, except it compares mtime
357             entries instead of ctime entries.
358
359     --older-than file
360             (c, r, u modes only) Only include files and directories older
361             than the specified file.  This compares ctime entries.
362
363     --older-mtime-than file
364             (c, r, u modes only) Like --older-than, except it compares mtime
365             entries instead of ctime entries.
366
367     --one-file-system
368             (c, r, and u modes) Do not cross mount points.
369
370     --options options
371             Select optional behaviors for particular modules.  The argument
372             is a text string containing comma-separated keywords and values.
373             These are passed to the modules that handle particular formats to
374             control how those formats will behave.  Each option has one of
375             the following forms:
376             key=value
377                     The key will be set to the specified value in every mod‐
378                     ule that supports it.  Modules that do not support this
379                     key will ignore it.
380             key     The key will be enabled in every module that supports it.
381                     This is equivalent to key=1.
382             !key    The key will be disabled in every module that supports
383                     it.
384             module:key=value, module:key, module:!key
385                     As above, but the corresponding key and value will be
386                     provided only to modules whose name matches module.
387
388             The complete list of supported modules and keys for create and
389             append modes is in archive_write_set_options(3) and for extract
390             and list modes in archive_read_set_options(3).
391
392             Examples of supported options:
393             iso9660:joliet
394                     Support Joliet extensions.  This is enabled by default,
395                     use !joliet or iso9660:!joliet to disable.
396             iso9660:rockridge
397                     Support Rock Ridge extensions.  This is enabled by
398                     default, use !rockridge or iso9660:!rockridge to disable.
399             gzip:compression-level
400                     A decimal integer from 1 to 9 specifying the gzip com‐
401                     pression level.
402             gzip:timestamp
403                     Store timestamp.  This is enabled by default, use
404                     !timestamp or gzip:!timestamp to disable.
405             lrzip:compression=type
406                     Use type as compression method.  Supported values are
407                     bzip2, gzip, lzo (ultra fast), and zpaq (best, extremely
408                     slow).
409             lrzip:compression-level
410                     A decimal integer from 1 to 9 specifying the lrzip com‐
411                     pression level.
412             lz4:compression-level
413                     A decimal integer from 1 to 9 specifying the lzop com‐
414                     pression level.
415             lz4:stream-checksum
416                     Enable stream checksum.  This is by default, use
417                     lz4:!stream-checksum to disable.
418             lz4:block-checksum
419                     Enable block checksum (Disabled by default).
420             lz4:block-size
421                     A decimal integer from 4 to 7 specifying the lz4 compres‐
422                     sion block size (7 is set by default).
423             lz4:block-dependence
424                     Use the previous block of the block being compressed for
425                     a compression dictionary to improve compression ratio.
426             zstd:compression-level
427                     A decimal integer specifying the zstd compression level.
428                     Supported values depend on the library version, common
429                     values are from 1 to 22.
430             lzop:compression-level
431                     A decimal integer from 1 to 9 specifying the lzop com‐
432                     pression level.
433             xz:compression-level
434                     A decimal integer from 0 to 9 specifying the xz compres‐
435                     sion level.
436             mtree:keyword
437                     The mtree writer module allows you to specify which mtree
438                     keywords will be included in the output.  Supported key‐
439                     words include: cksum, device, flags, gid, gname, indent,
440                     link, md5, mode, nlink, rmd160, sha1, sha256, sha384,
441                     sha512, size, time, uid, uname.  The default is equiva‐
442                     lent to: “device, flags, gid, gname, link, mode, nlink,
443                     size, time, type, uid, uname”.
444             mtree:all
445                     Enables all of the above keywords.  You can also use
446                     mtree:!all to disable all keywords.
447             mtree:use-set
448                     Enable generation of /set lines in the output.
449             mtree:indent
450                     Produce human-readable output by indenting options and
451                     splitting lines to fit into 80 columns.
452             zip:compression=type
453                     Use type as compression method.  Supported values are
454                     store (uncompressed) and deflate (gzip algorithm).
455             zip:encryption
456                     Enable encryption using traditional zip encryption.
457             zip:encryption=type
458                     Use type as encryption type.  Supported values are
459                     zipcrypt (traditional zip encryption), aes128 (WinZip
460                     AES-128 encryption) and aes256 (WinZip AES-256 encryp‐
461                     tion).
462             read_concatenated_archives
463                     Ignore zeroed blocks in the archive, which occurs when
464                     multiple tar archives have been concatenated together.
465                     Without this option, only the contents of the first con‐
466                     catenated archive would be read.  This option is compara‐
467                     ble to the -i, --ignore-zeros option of GNU tar.
468             If a provided option is not supported by any module, that is a
469             fatal error.
470
471     -P, --absolute-paths
472             Preserve pathnames.  By default, absolute pathnames (those that
473             begin with a / character) have the leading slash removed both
474             when creating archives and extracting from them.  Also, bsdtar
475             will refuse to extract archive entries whose pathnames contain ..
476             or whose target directory would be altered by a symlink.  This
477             option suppresses these behaviors.
478
479     -p, --insecure, --preserve-permissions
480             (x mode only) Preserve file permissions.  Attempt to restore the
481             full permissions, including file modes, file attributes or file
482             flags, extended file attributes and ACLs, if available, for each
483             item extracted from the archive.  This is the reverse of
484             --no-same-permissions and the default if bsdtar is being run as
485             root.  It can be partially overridden by also specifying
486             --no-acls, --no-fflags, --no-mac-metadata or --no-xattrs.
487
488     --passphrase passphrase
489             The passphrase is used to extract or create an encrypted archive.
490             Currently, zip is the only supported format that supports encryp‐
491             tion.  You shouldn't use this option unless you realize how inse‐
492             cure use of this option is.
493
494     --posix
495             (c, r, u mode only) Synonym for --format pax
496
497     -q, --fast-read
498             (x and t mode only) Extract or list only the first archive entry
499             that matches each pattern or filename operand.  Exit as soon as
500             each specified pattern or filename has been matched.  By default,
501             the archive is always read to the very end, since there can be
502             multiple entries with the same name and, by convention, later
503             entries overwrite earlier entries.  This option is provided as a
504             performance optimization.
505
506     -S      (x mode only) Extract files as sparse files.  For every block on
507             disk, check first if it contains only NULL bytes and seek over it
508             otherwise.  This works similar to the conv=sparse option of dd.
509
510     -s pattern
511             Modify file or archive member names according to pattern.  The
512             pattern has the format /old/new/[ghHprRsS] where old is a basic
513             regular expression, new is the replacement string of the matched
514             part, and the optional trailing letters modify how the replace‐
515             ment is handled.  If old is not matched, the pattern is skipped.
516             Within new, ~ is substituted with the match, \1 to \9 with the
517             content of the corresponding captured group.  The optional trail‐
518             ing g specifies that matching should continue after the matched
519             part and stop on the first unmatched pattern.  The optional
520             trailing s specifies that the pattern applies to the value of
521             symbolic links.  The optional trailing p specifies that after a
522             successful substitution the original path name and the new path
523             name should be printed to standard error.  Optional trailing H,
524             R, or S characters suppress substitutions for hardlink targets,
525             regular filenames, or symlink targets, respectively.  Optional
526             trailing h, r, or s characters enable substitutions for hardlink
527             targets, regular filenames, or symlink targets, respectively.
528             The default is hrs which applies substitutions to all names.  In
529             particular, it is never necessary to specify h, r, or s.
530
531     --safe-writes
532             (x mode only) Extract files atomically.  By default bsdtar
533             unlinks the original file with the same name as the extracted
534             file (if it exists), and then creates it immediately under the
535             same name and writes to it.  For a short period of time, applica‐
536             tions trying to access the file might not find it, or see incom‐
537             plete results.  If --safe-writes is enabled, bsdtar first creates
538             a unique temporary file, then writes the new contents to the tem‐
539             porary file, and finally renames the temporary file to its final
540             name atomically using rename(2).  This guarantees that an appli‐
541             cation accessing the file, will either see the old contents or
542             the new contents at all times.
543
544     --same-owner
545             (x mode only) Extract owner and group IDs.  This is the reverse
546             of --no-same-owner and the default behavior if bsdtar is run as
547             root.
548
549     --strip-components count
550             Remove the specified number of leading path elements.  Pathnames
551             with fewer elements will be silently skipped.  Note that the
552             pathname is edited after checking inclusion/exclusion patterns
553             but before security checks.
554
555     -T filename, --files-from filename
556             In x or t mode, bsdtar will read the list of names to be
557             extracted from filename.  In c mode, bsdtar will read names to be
558             archived from filename.  The special name “-C” on a line by
559             itself will cause the current directory to be changed to the
560             directory specified on the following line.  Names are terminated
561             by newlines unless --null is specified.  Note that --null also
562             disables the special handling of lines containing “-C”.  Note:
563             If you are generating lists of files using find(1), you probably
564             want to use -n as well.
565
566     --totals
567             (c, r, u modes only) After archiving all files, print a summary
568             to stderr.
569
570     -U, --unlink, --unlink-first
571             (x mode only) Unlink files before creating them.  This can be a
572             minor performance optimization if most files already exist, but
573             can make things slower if most files do not already exist.  This
574             flag also causes bsdtar to remove intervening directory symlinks
575             instead of reporting an error.  See the SECURITY section below
576             for more details.
577
578     --uid id
579             Use the provided user id number and ignore the user name from the
580             archive.  On create, if --uname is not also specified, the user
581             name will be set to match the user id.
582
583     --uname name
584             Use the provided user name.  On extract, this overrides the user
585             name in the archive; if the provided user name does not exist on
586             the system, it will be ignored and the user id (from the archive
587             or from the --uid option) will be used instead.  On create, this
588             sets the user name that will be stored in the archive; the name
589             is not verified against the system user database.
590
591     --use-compress-program program
592             Pipe the input (in x or t mode) or the output (in c mode) through
593             program instead of using the builtin compression support.
594
595     -v, --verbose
596             Produce verbose output.  In create and extract modes, bsdtar will
597             list each file name as it is read from or written to the archive.
598             In list mode, bsdtar will produce output similar to that of
599             ls(1).  An additional -v option will also provide ls-like details
600             in create and extract mode.
601
602     --version
603             Print version of bsdtar and libarchive, and exit.
604
605     -w, --confirmation, --interactive
606             Ask for confirmation for every action.
607
608     -X filename, --exclude-from filename
609             Read a list of exclusion patterns from the specified file.  See
610             --exclude for more information about the handling of exclusions.
611
612     --xattrs
613             (c, r, u, x modes only) Archive or extract extended file
614             attributes.  This is the reverse of --no-xattrs and the default
615             behavior in c, r, and u modes or if bsdtar is run in x mode as
616             root.
617
618     -y      (c mode only) Compress the resulting archive with bzip2(1).  In
619             extract or list modes, this option is ignored.  Note that this
620             tar implementation recognizes bzip2 compression automatically
621             when reading archives.
622
623     -Z, --compress, --uncompress
624             (c mode only) Compress the resulting archive with compress(1).
625             In extract or list modes, this option is ignored.  Note that this
626             tar implementation recognizes compress compression automatically
627             when reading archives.
628
629     -z, --gunzip, --gzip
630             (c mode only) Compress the resulting archive with gzip(1).  In
631             extract or list modes, this option is ignored.  Note that this
632             tar implementation recognizes gzip compression automatically when
633             reading archives.
634

ENVIRONMENT

636     The following environment variables affect the execution of bsdtar:
637
638     TAR_READER_OPTIONS
639                The default options for format readers and compression read‐
640                ers.  The --options option overrides this.
641
642     TAR_WRITER_OPTIONS
643                The default options for format writers and compression writ‐
644                ers.  The --options option overrides this.
645
646     LANG       The locale to use.  See environ(7) for more information.
647
648     TAPE       The default device.  The -f option overrides this.  Please see
649                the description of the -f option above for more details.
650
651     TZ         The timezone to use when displaying dates.  See environ(7) for
652                more information.
653

EXIT STATUS

655     The bsdtar utility exits 0 on success, and >0 if an error occurs.
656

EXAMPLES

658     The following creates a new archive called file.tar.gz that contains two
659     files source.c and source.h:
660           bsdtar -czf file.tar.gz source.c source.h
661
662     To view a detailed table of contents for this archive:
663           bsdtar -tvf file.tar.gz
664
665     To extract all entries from the archive on the default tape drive:
666           bsdtar -x
667
668     To examine the contents of an ISO 9660 cdrom image:
669           bsdtar -tf image.iso
670
671     To move file hierarchies, invoke bsdtar as
672           bsdtar -cf - -C srcdir . | bsdtar -xpf - -C destdir
673     or more traditionally
674           cd srcdir ; bsdtar -cf - . | (cd destdir ; bsdtar -xpf -)
675
676     In create mode, the list of files and directories to be archived can also
677     include directory change instructions of the form -Cfoo/baz and archive
678     inclusions of the form @archive-file.  For example, the command line
679           bsdtar -c -f new.tar foo1 @old.tgz -C/tmp foo2
680     will create a new archive new.tar.  bsdtar will read the file foo1 from
681     the current directory and add it to the output archive.  It will then
682     read each entry from old.tgz and add those entries to the output archive.
683     Finally, it will switch to the /tmp directory and add foo2 to the output
684     archive.
685
686     An input file in mtree(5) format can be used to create an output archive
687     with arbitrary ownership, permissions, or names that differ from existing
688     data on disk:
689
690           $ cat input.mtree
691           #mtree
692           usr/bin uid=0 gid=0 mode=0755 type=dir
693           usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
694           $ tar -cvf output.tar @input.mtree
695
696     The --newer and --newer-mtime switches accept a variety of common date
697     and time specifications, including “12 Mar 2005 7:14:29pm”, “2005-03-12
698     19:14”, “5 minutes ago”, and “19:14 PST May 1”.
699
700     The --options argument can be used to control various details of archive
701     generation or reading.  For example, you can generate mtree output which
702     only contains type, time, and uid keywords:
703           bsdtar -cf file.tar --format=mtree --options='!all,type,time,uid'
704           dir
705     or you can set the compression level used by gzip or xz compression:
706           bsdtar -czf file.tar --options='compression-level=9'.
707     For more details, see the explanation of the archive_read_set_options()
708     and archive_write_set_options() API calls that are described in
709     archive_read(3) and archive_write(3).
710

COMPATIBILITY

712     The bundled-arguments format is supported for compatibility with historic
713     implementations.  It consists of an initial word (with no leading - char‐
714     acter) in which each character indicates an option.  Arguments follow as
715     separate words.  The order of the arguments must match the order of the
716     corresponding characters in the bundled command word.  For example,
717           bsdtar tbf 32 file.tar
718     specifies three flags t, b, and f.  The b and f flags both require argu‐
719     ments, so there must be two additional items on the command line.  The 32
720     is the argument to the b flag, and file.tar is the argument to the f
721     flag.
722
723     The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and
724     w comply with SUSv2.
725
726     For maximum portability, scripts that invoke tar should use the bundled-
727     argument format above, should limit themselves to the c, t, and x modes,
728     and the b, f, m, v, and w options.
729
730     Additional long options are provided to improve compatibility with other
731     tar implementations.
732

SECURITY

734     Certain security issues are common to many archiving programs, including
735     bsdtar.  In particular, carefully-crafted archives can request that
736     bsdtar extract files to locations outside of the target directory.  This
737     can potentially be used to cause unwitting users to overwrite files they
738     did not intend to overwrite.  If the archive is being extracted by the
739     superuser, any file on the system can potentially be overwritten.  There
740     are three ways this can happen.  Although bsdtar has mechanisms to pro‐
741     tect against each one, savvy users should be aware of the implications:
742
743     ·       Archive entries can have absolute pathnames.  By default, bsdtar
744             removes the leading / character from filenames before restoring
745             them to guard against this problem.
746
747     ·       Archive entries can have pathnames that include .. components.
748             By default, bsdtar will not extract files containing .. compo‐
749             nents in their pathname.
750
751     ·       Archive entries can exploit symbolic links to restore files to
752             other directories.  An archive can restore a symbolic link to
753             another directory, then use that link to restore a file into that
754             directory.  To guard against this, bsdtar checks each extracted
755             path for symlinks.  If the final path element is a symlink, it
756             will be removed and replaced with the archive entry.  If -U is
757             specified, any intermediate symlink will also be unconditionally
758             removed.  If neither -U nor -P is specified, bsdtar will refuse
759             to extract the entry.
760     To protect yourself, you should be wary of any archives that come from
761     untrusted sources.  You should examine the contents of an archive with
762           bsdtar -tf filename
763     before extraction.  You should use the -k option to ensure that bsdtar
764     will not overwrite any existing files or the -U option to remove any pre-
765     existing files.  You should generally not extract archives while running
766     with super-user privileges.  Note that the -P option to bsdtar disables
767     the security checks above and allows you to extract an archive while pre‐
768     serving any absolute pathnames, .. components, or symlinks to other
769     directories.
770

SEE ALSO

772     bzip2(1), compress(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), xz(1),
773     libarchive(3), libarchive-formats(5), tar(5)
774

STANDARDS

776     There is no current POSIX standard for the tar command; it appeared in
777     ISO/IEC 9945-1:1996 (“POSIX.1”) but was dropped from IEEE Std 1003.1-2001
778     (“POSIX.1”).  The options supported by this implementation were developed
779     by surveying a number of existing tar implementations as well as the old
780     POSIX specification for tar and the current POSIX specification for pax.
781
782     The ustar and pax interchange file formats are defined by IEEE Std
783     1003.1-2001 (“POSIX.1”) for the pax command.
784

HISTORY

786     A tar command appeared in Seventh Edition Unix, which was released in
787     January, 1979.  There have been numerous other implementations, many of
788     which extended the file format.  John Gilmore's pdtar public-domain
789     implementation (circa November, 1987) was quite influential, and formed
790     the basis of GNU tar.  GNU tar was included as the standard system tar in
791     FreeBSD beginning with FreeBSD 1.0.
792
793     This is a complete re-implementation based on the libarchive(3) library.
794     It was first released with FreeBSD 5.4 in May, 2005.
795

BUGS

797     This program follows ISO/IEC 9945-1:1996 (“POSIX.1”) for the definition
798     of the -l option.  Note that GNU tar prior to version 1.15 treated -l as
799     a synonym for the --one-file-system option.
800
801     The -C dir option may differ from historic implementations.
802
803     All archive output is written in correctly-sized blocks, even if the out‐
804     put is being compressed.  Whether or not the last output block is padded
805     to a full block size varies depending on the format and the output
806     device.  For tar and cpio formats, the last block of output is padded to
807     a full block size if the output is being written to standard output or to
808     a character or block device such as a tape drive.  If the output is being
809     written to a regular file, the last block will not be padded.  Many com‐
810     pressors, including gzip(1) and bzip2(1), complain about the null padding
811     when decompressing an archive created by bsdtar, although they still
812     extract it correctly.
813
814     The compression and decompression is implemented internally, so there may
815     be insignificant differences between the compressed output generated by
816           bsdtar -czf - file
817     and that generated by
818           bsdtar -cf - file | gzip
819
820     The default should be to read and write archives to the standard I/O
821     paths, but tradition (and POSIX) dictates otherwise.
822
823     The r and u modes require that the archive be uncompressed and located in
824     a regular file on disk.  Other archives can be modified using c mode with
825     the @archive-file extension.
826
827     To archive a file called @foo or -foo you must specify it as ./@foo or
828     ./-foo, respectively.
829
830     In create mode, a leading ./ is always removed.  A leading / is stripped
831     unless the -P option is specified.
832
833     There needs to be better support for file selection on both create and
834     extract.
835
836     There is not yet any support for multi-volume archives.
837
838     Converting between dissimilar archive formats (such as tar and cpio)
839     using the @- convention can cause hard link information to be lost.
840     (This is a consequence of the incompatible ways that different archive
841     formats store hardlink information.)
842
843BSD                            January 31, 2020                            BSD
Impressum