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 ex‐
37             tracted, 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 be‐
45     fore 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 en‐
55             tries in it will be appended to the current archive.  As a simple
56             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 re‐
81             stricted 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 ex‐
174             tracted 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 ex‐
193             tract or list modes, this option is ignored.  Note that this tar
194             implementation recognizes XZ compression automatically when read‐
195             ing 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 ig‐
239             nored.  Use of this option is discouraged and new archives should
240             be created with --xz instead.  Note that this tar implementation
241             recognizes LZMA compression automatically when reading archives.
242
243     --lzop  (c mode only) Compress the resulting archive with lzop(1).  In
244             extract or list modes, this option is ignored.  Note that this
245             tar implementation recognizes LZO compression automatically when
246             reading archives.
247
248     -m, --modification-time
249             (x mode only) Do not extract modification time.  By default, the
250             modification time is set to the time stored in the archive.
251
252     --mac-metadata
253             (c, r, u and x mode only) Mac OS X specific.  Archive or extract
254             extended ACLs and extended file attributes using copyfile(3) in
255             AppleDouble format.  This is the reverse of --no-mac-metadata.
256             and the default behavior in c, r, and u modes or if bsdtar is run
257             in x mode as root.
258
259     -n, --norecurse, --no-recursion
260             Do not operate recursively on the content of directories.
261
262     --newer date
263             (c, r, u modes only) Only include files and directories newer
264             than the specified date.  This compares ctime entries.
265
266     --newer-mtime date
267             (c, r, u modes only) Like --newer, except it compares mtime en‐
268             tries instead of ctime entries.
269
270     --newer-than file
271             (c, r, u modes only) Only include files and directories newer
272             than the specified file.  This compares ctime entries.
273
274     --newer-mtime-than file
275             (c, r, u modes only) Like --newer-than, except it compares mtime
276             entries instead of ctime entries.
277
278     --nodump
279             (c and r modes only) Honor the nodump file flag by skipping this
280             file.
281
282     --nopreserveHFSCompression
283             (x mode only) Mac OS X specific (v10.6 or later). Do not compress
284             extracted regular files which were compressed with HFS+ compres‐
285             sion before archived.  By default, compress the regular files
286             again with HFS+ compression.
287
288     --null  (use with -I or -T) Filenames or patterns are separated by null
289             characters, not by newlines.  This is often used to read file‐
290             names output by the -print0 option to find(1).
291
292     --no-acls
293             (c, r, u, x modes only) Do not archive or extract POSIX.1e or
294             NFSv4 ACLs.  This is the reverse of --acls and the default behav‐
295             ior if bsdtar is run as non-root in x mode (on Mac OS X as any
296             user in c, r, u and x modes).
297
298     --no-fflags
299             (c, r, u, x modes only) Do not archive or extract file attributes
300             or file flags.  This is the reverse of --fflags and the default
301             behavior if bsdtar is run as non-root in x mode.
302
303     --no-mac-metadata
304             (x mode only) Mac OS X specific.  Do not archive or extract ACLs
305             and extended file attributes using copyfile(3) in AppleDouble
306             format.  This is the reverse of --mac-metadata.  and the default
307             behavior if bsdtar is run as non-root in x mode.
308
309     --no-read-sparse
310             (c, r, u modes only) Do not read sparse file information from
311             disk.  This is the reverse of --read-sparse.
312
313     --no-safe-writes
314             (x mode only) Do not create temporary files and use rename(2) to
315             replace the original ones.  This is the reverse of --safe-writes.
316
317     --no-same-owner
318             (x mode only) Do not extract owner and group IDs.  This is the
319             reverse of --same-owner and the default behavior if bsdtar is run
320             as non-root.
321
322     --no-same-permissions
323             (x mode only) Do not extract full permissions (SGID, SUID, sticky
324             bit, file attributes or file flags, extended file attributes and
325             ACLs).  This is the reverse of -p and the default behavior if
326             bsdtar is run as non-root.
327
328     --no-xattrs
329             (c, r, u, x modes only) Do not archive or extract extended file
330             attributes.  This is the reverse of --xattrs and the default be‐
331             havior if bsdtar is run as non-root in x mode.
332
333     --numeric-owner
334             This is equivalent to --uname "" --gname "".  On extract, it
335             causes user and group names in the archive to be ignored in favor
336             of the numeric user and group ids.  On create, it causes user and
337             group names to not be stored in the archive.
338
339     -O, --to-stdout
340             (x, t modes only) In extract (-x) mode, files will be written to
341             standard out rather than being extracted to disk.  In list (-t)
342             mode, the file listing will be written to stderr rather than the
343             usual stdout.
344
345     -o      (x mode) Use the user and group of the user running the program
346             rather than those specified in the archive.  Note that this has
347             no significance unless -p is specified, and the program is being
348             run by the root user.  In this case, the file modes and flags
349             from the archive will be restored, but ACLs or owner information
350             in the archive will be discarded.
351
352     -o      (c, r, u mode) A synonym for --format ustar
353
354     --older date
355             (c, r, u modes only) Only include files and directories older
356             than the specified date.  This compares ctime entries.
357
358     --older-mtime date
359             (c, r, u modes only) Like --older, except it compares mtime en‐
360             tries instead of ctime entries.
361
362     --older-than file
363             (c, r, u modes only) Only include files and directories older
364             than the specified file.  This compares ctime entries.
365
366     --older-mtime-than file
367             (c, r, u modes only) Like --older-than, except it compares mtime
368             entries instead of ctime entries.
369
370     --one-file-system
371             (c, r, and u modes) Do not cross mount points.
372
373     --options options
374             Select optional behaviors for particular modules.  The argument
375             is a text string containing comma-separated keywords and values.
376             These are passed to the modules that handle particular formats to
377             control how those formats will behave.  Each option has one of
378             the following forms:
379             key=value
380                     The key will be set to the specified value in every mod‐
381                     ule that supports it.  Modules that do not support this
382                     key will ignore it.
383             key     The key will be enabled in every module that supports it.
384                     This is equivalent to key=1.
385             !key    The key will be disabled in every module that supports
386                     it.
387             module:key=value, module:key, module:!key
388                     As above, but the corresponding key and value will be
389                     provided only to modules whose name matches module.
390
391             The complete list of supported modules and keys for create and
392             append modes is in archive_write_set_options(3) and for extract
393             and list modes in archive_read_set_options(3).
394
395             Examples of supported options:
396             iso9660:joliet
397                     Support Joliet extensions.  This is enabled by default,
398                     use !joliet or iso9660:!joliet to disable.
399             iso9660:rockridge
400                     Support Rock Ridge extensions.  This is enabled by de‐
401                     fault, use !rockridge or iso9660:!rockridge to disable.
402             gzip:compression-level
403                     A decimal integer from 1 to 9 specifying the gzip com‐
404                     pression level.
405             gzip:timestamp
406                     Store timestamp.  This is enabled by default, use
407                     !timestamp or gzip:!timestamp to disable.
408             lrzip:compression=type
409                     Use type as compression method.  Supported values are
410                     bzip2, gzip, lzo (ultra fast), and zpaq (best, extremely
411                     slow).
412             lrzip:compression-level
413                     A decimal integer from 1 to 9 specifying the lrzip com‐
414                     pression level.
415             lz4:compression-level
416                     A decimal integer from 1 to 9 specifying the lzop com‐
417                     pression level.
418             lz4:stream-checksum
419                     Enable stream checksum.  This is by default, use
420                     lz4:!stream-checksum to disable.
421             lz4:block-checksum
422                     Enable block checksum (Disabled by default).
423             lz4:block-size
424                     A decimal integer from 4 to 7 specifying the lz4 compres‐
425                     sion block size (7 is set by default).
426             lz4:block-dependence
427                     Use the previous block of the block being compressed for
428                     a compression dictionary to improve compression ratio.
429             zstd:compression-level
430                     A decimal integer specifying the zstd compression level.
431                     Supported values depend on the library version, common
432                     values are from 1 to 22.
433             zstd:threads
434                     Specify the number of worker threads to use.  Setting
435                     threads to a special value 0 makes zstd(1) use as many
436                     threads as there are CPU cores on the system.
437             lzop:compression-level
438                     A decimal integer from 1 to 9 specifying the lzop com‐
439                     pression level.
440             xz:compression-level
441                     A decimal integer from 0 to 9 specifying the xz compres‐
442                     sion level.
443             xz:threads
444                     Specify the number of worker threads to use.  Setting
445                     threads to a special value 0 makes xz(1) use as many
446                     threads as there are CPU cores on the system.
447             mtree:keyword
448                     The mtree writer module allows you to specify which mtree
449                     keywords will be included in the output.  Supported key‐
450                     words include: cksum, device, flags, gid, gname, indent,
451                     link, md5, mode, nlink, rmd160, sha1, sha256, sha384,
452                     sha512, size, time, uid, uname.  The default is equiva‐
453                     lent to: “device, flags, gid, gname, link, mode, nlink,
454                     size, time, type, uid, uname”.
455             mtree:all
456                     Enables all of the above keywords.  You can also use
457                     mtree:!all to disable all keywords.
458             mtree:use-set
459                     Enable generation of /set lines in the output.
460             mtree:indent
461                     Produce human-readable output by indenting options and
462                     splitting lines to fit into 80 columns.
463             zip:compression=type
464                     Use type as compression method.  Supported values are
465                     store (uncompressed) and deflate (gzip algorithm).
466             zip:encryption
467                     Enable encryption using traditional zip encryption.
468             zip:encryption=type
469                     Use type as encryption type.  Supported values are
470                     zipcrypt (traditional zip encryption), aes128 (WinZip
471                     AES-128 encryption) and aes256 (WinZip AES-256 encryp‐
472                     tion).
473             read_concatenated_archives
474                     Ignore zeroed blocks in the archive, which occurs when
475                     multiple tar archives have been concatenated together.
476                     Without this option, only the contents of the first con‐
477                     catenated archive would be read.  This option is compara‐
478                     ble to the -i, --ignore-zeros option of GNU tar.
479             If a provided option is not supported by any module, that is a
480             fatal error.
481
482     -P, --absolute-paths
483             Preserve pathnames.  By default, absolute pathnames (those that
484             begin with a / character) have the leading slash removed both
485             when creating archives and extracting from them.  Also, bsdtar
486             will refuse to extract archive entries whose pathnames contain ..
487             or whose target directory would be altered by a symlink.  This
488             option suppresses these behaviors.
489
490     -p, --insecure, --preserve-permissions
491             (x mode only) Preserve file permissions.  Attempt to restore the
492             full permissions, including file modes, file attributes or file
493             flags, extended file attributes and ACLs, if available, for each
494             item extracted from the archive.  This is the reverse of
495             --no-same-permissions and the default if bsdtar is being run as
496             root.  It can be partially overridden by also specifying
497             --no-acls, --no-fflags, --no-mac-metadata or --no-xattrs.
498
499     --passphrase passphrase
500             The passphrase is used to extract or create an encrypted archive.
501             Currently, zip is the only supported format that supports encryp‐
502             tion.  You shouldn't use this option unless you realize how inse‐
503             cure use of this option is.
504
505     --posix
506             (c, r, u mode only) Synonym for --format pax
507
508     -q, --fast-read
509             (x and t mode only) Extract or list only the first archive entry
510             that matches each pattern or filename operand.  Exit as soon as
511             each specified pattern or filename has been matched.  By default,
512             the archive is always read to the very end, since there can be
513             multiple entries with the same name and, by convention, later en‐
514             tries overwrite earlier entries.  This option is provided as a
515             performance optimization.
516
517     --read-sparse
518             (c, r, u modes only) Read sparse file information from disk.
519             This is the reverse of --no-read-sparse and the default behavior.
520
521     -S      (x mode only) Extract files as sparse files.  For every block on
522             disk, check first if it contains only NULL bytes and seek over it
523             otherwise.  This works similar to the conv=sparse option of dd.
524
525     -s pattern
526             Modify file or archive member names according to pattern.  The
527             pattern has the format /old/new/[ghHprRsS] where old is a basic
528             regular expression, new is the replacement string of the matched
529             part, and the optional trailing letters modify how the replace‐
530             ment is handled.  If old is not matched, the pattern is skipped.
531             Within new, ~ is substituted with the match, \1 to \9 with the
532             content of the corresponding captured group.  The optional trail‐
533             ing g specifies that matching should continue after the matched
534             part and stop on the first unmatched pattern.  The optional
535             trailing s specifies that the pattern applies to the value of
536             symbolic links.  The optional trailing p specifies that after a
537             successful substitution the original path name and the new path
538             name should be printed to standard error.  Optional trailing H,
539             R, or S characters suppress substitutions for hardlink targets,
540             regular filenames, or symlink targets, respectively.  Optional
541             trailing h, r, or s characters enable substitutions for hardlink
542             targets, regular filenames, or symlink targets, respectively.
543             The default is hrs which applies substitutions to all names.  In
544             particular, it is never necessary to specify h, r, or s.
545
546     --safe-writes
547             (x mode only) Extract files atomically.  By default bsdtar un‐
548             links the original file with the same name as the extracted file
549             (if it exists), and then creates it immediately under the same
550             name and writes to it.  For a short period of time, applications
551             trying to access the file might not find it, or see incomplete
552             results.  If --safe-writes is enabled, bsdtar first creates a
553             unique temporary file, then writes the new contents to the tempo‐
554             rary file, and finally renames the temporary file to its final
555             name atomically using rename(2).  This guarantees that an appli‐
556             cation accessing the file, will either see the old contents or
557             the new contents at all times.
558
559     --same-owner
560             (x mode only) Extract owner and group IDs.  This is the reverse
561             of --no-same-owner and the default behavior if bsdtar is run as
562             root.
563
564     --strip-components count
565             Remove the specified number of leading path elements.  Pathnames
566             with fewer elements will be silently skipped.  Note that the
567             pathname is edited after checking inclusion/exclusion patterns
568             but before security checks.
569
570     -T filename, --files-from filename
571             In x or t mode, bsdtar will read the list of names to be ex‐
572             tracted from filename.  In c mode, bsdtar will read names to be
573             archived from filename.  The special name “-C” on a line by it‐
574             self will cause the current directory to be changed to the direc‐
575             tory specified on the following line.  Names are terminated by
576             newlines unless --null is specified.  Note that --null also dis‐
577             ables the special handling of lines containing “-C”.  Note:  If
578             you are generating lists of files using find(1), you probably
579             want to use -n as well.
580
581     --totals
582             (c, r, u modes only) After archiving all files, print a summary
583             to stderr.
584
585     -U, --unlink, --unlink-first
586             (x mode only) Unlink files before creating them.  This can be a
587             minor performance optimization if most files already exist, but
588             can make things slower if most files do not already exist.  This
589             flag also causes bsdtar to remove intervening directory symlinks
590             instead of reporting an error.  See the SECURITY section below
591             for more details.
592
593     --uid id
594             Use the provided user id number and ignore the user name from the
595             archive.  On create, if --uname is not also specified, the user
596             name will be set to match the user id.
597
598     --uname name
599             Use the provided user name.  On extract, this overrides the user
600             name in the archive; if the provided user name does not exist on
601             the system, it will be ignored and the user id (from the archive
602             or from the --uid option) will be used instead.  On create, this
603             sets the user name that will be stored in the archive; the name
604             is not verified against the system user database.
605
606     --use-compress-program program
607             Pipe the input (in x or t mode) or the output (in c mode) through
608             program instead of using the builtin compression support.
609
610     -v, --verbose
611             Produce verbose output.  In create and extract modes, bsdtar will
612             list each file name as it is read from or written to the archive.
613             In list mode, bsdtar will produce output similar to that of
614             ls(1).  An additional -v option will also provide ls-like details
615             in create and extract mode.
616
617     --version
618             Print version of bsdtar and libarchive, and exit.
619
620     -w, --confirmation, --interactive
621             Ask for confirmation for every action.
622
623     -X filename, --exclude-from filename
624             Read a list of exclusion patterns from the specified file.  See
625             --exclude for more information about the handling of exclusions.
626
627     --xattrs
628             (c, r, u, x modes only) Archive or extract extended file at‐
629             tributes.  This is the reverse of --no-xattrs and the default be‐
630             havior in c, r, and u modes or if bsdtar is run in x mode as
631             root.
632
633     -y      (c mode only) Compress the resulting archive with bzip2(1).  In
634             extract or list modes, this option is ignored.  Note that this
635             tar implementation recognizes bzip2 compression automatically
636             when reading archives.
637
638     -Z, --compress, --uncompress
639             (c mode only) Compress the resulting archive with compress(1).
640             In extract or list modes, this option is ignored.  Note that this
641             tar implementation recognizes compress compression automatically
642             when reading archives.
643
644     -z, --gunzip, --gzip
645             (c mode only) Compress the resulting archive with gzip(1).  In
646             extract or list modes, this option is ignored.  Note that this
647             tar implementation recognizes gzip compression automatically when
648             reading archives.
649

ENVIRONMENT

651     The following environment variables affect the execution of bsdtar:
652
653     TAR_READER_OPTIONS
654                The default options for format readers and compression read‐
655                ers.  The --options option overrides this.
656
657     TAR_WRITER_OPTIONS
658                The default options for format writers and compression writ‐
659                ers.  The --options option overrides this.
660
661     LANG       The locale to use.  See environ(7) for more information.
662
663     TAPE       The default device.  The -f option overrides this.  Please see
664                the description of the -f option above for more details.
665
666     TZ         The timezone to use when displaying dates.  See environ(7) for
667                more information.
668

EXIT STATUS

670     The bsdtar utility exits 0 on success, and >0 if an error occurs.
671

EXAMPLES

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

COMPATIBILITY

727     The bundled-arguments format is supported for compatibility with historic
728     implementations.  It consists of an initial word (with no leading - char‐
729     acter) in which each character indicates an option.  Arguments follow as
730     separate words.  The order of the arguments must match the order of the
731     corresponding characters in the bundled command word.  For example,
732           bsdtar tbf 32 file.tar
733     specifies three flags t, b, and f.  The b and f flags both require argu‐
734     ments, so there must be two additional items on the command line.  The 32
735     is the argument to the b flag, and file.tar is the argument to the f
736     flag.
737
738     The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and
739     w comply with SUSv2.
740
741     For maximum portability, scripts that invoke tar should use the bundled-
742     argument format above, should limit themselves to the c, t, and x modes,
743     and the b, f, m, v, and w options.
744
745     Additional long options are provided to improve compatibility with other
746     tar implementations.
747

SECURITY

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

SEE ALSO

787     bzip2(1), compress(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), xz(1),
788     libarchive(3), libarchive-formats(5), tar(5)
789

STANDARDS

791     There is no current POSIX standard for the tar command; it appeared in
792     ISO/IEC 9945-1:1996 (“POSIX.1”) but was dropped from IEEE Std 1003.1-2001
793     (“POSIX.1”).  The options supported by this implementation were developed
794     by surveying a number of existing tar implementations as well as the old
795     POSIX specification for tar and the current POSIX specification for pax.
796
797     The ustar and pax interchange file formats are defined by IEEE Std
798     1003.1-2001 (“POSIX.1”) for the pax command.
799

HISTORY

801     A tar command appeared in Seventh Edition Unix, which was released in
802     January, 1979.  There have been numerous other implementations, many of
803     which extended the file format.  John Gilmore's pdtar public-domain im‐
804     plementation (circa November, 1987) was quite influential, and formed the
805     basis of GNU tar.  GNU tar was included as the standard system tar in
806     FreeBSD beginning with FreeBSD 1.0.
807
808     This is a complete re-implementation based on the libarchive(3) library.
809     It was first released with FreeBSD 5.4 in May, 2005.
810

BUGS

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