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

ENVIRONMENT

595     The following environment variables affect the execution of bsdtar:
596
597     TAR_READER_OPTIONS
598                The default options for format readers and compression read‐
599                ers.  The --options option overrides this.
600
601     TAR_WRITER_OPTIONS
602                The default options for format writers and compression writ‐
603                ers.  The --options option overrides this.
604
605     LANG       The locale to use.  See environ(7) for more information.
606
607     TAPE       The default device.  The -f option overrides this.  Please see
608                the description of the -f option above for more details.
609
610     TZ         The timezone to use when displaying dates.  See environ(7) for
611                more information.
612

EXIT STATUS

614     The bsdtar utility exits 0 on success, and >0 if an error occurs.
615

EXAMPLES

617     The following creates a new archive called file.tar.gz that contains two
618     files source.c and source.h:
619           bsdtar -czf file.tar.gz source.c source.h
620
621     To view a detailed table of contents for this archive:
622           bsdtar -tvf file.tar.gz
623
624     To extract all entries from the archive on the default tape drive:
625           bsdtar -x
626
627     To examine the contents of an ISO 9660 cdrom image:
628           bsdtar -tf image.iso
629
630     To move file hierarchies, invoke bsdtar as
631           bsdtar -cf - -C srcdir . | bsdtar -xpf - -C destdir
632     or more traditionally
633           cd srcdir ; bsdtar -cf - . | (cd destdir ; bsdtar -xpf -)
634
635     In create mode, the list of files and directories to be archived can also
636     include directory change instructions of the form -Cfoo/baz and archive
637     inclusions of the form @archive-file.  For example, the command line
638           bsdtar -c -f new.tar foo1 @old.tgz -C/tmp foo2
639     will create a new archive new.tar.  bsdtar will read the file foo1 from
640     the current directory and add it to the output archive.  It will then
641     read each entry from old.tgz and add those entries to the output archive.
642     Finally, it will switch to the /tmp directory and add foo2 to the output
643     archive.
644
645     An input file in mtree(5) format can be used to create an output archive
646     with arbitrary ownership, permissions, or names that differ from existing
647     data on disk:
648
649           $ cat input.mtree
650           #mtree
651           usr/bin uid=0 gid=0 mode=0755 type=dir
652           usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
653           $ tar -cvf output.tar @input.mtree
654
655     The --newer and --newer-mtime switches accept a variety of common date
656     and time specifications, including “12 Mar 2005 7:14:29pm”, “2005-03-12
657     19:14”, “5 minutes ago”, and “19:14 PST May 1”.
658
659     The --options argument can be used to control various details of archive
660     generation or reading.  For example, you can generate mtree output which
661     only contains type, time, and uid keywords:
662           bsdtar -cf file.tar --format=mtree --options='!all,type,time,uid'
663           dir
664     or you can set the compression level used by gzip or xz compression:
665           bsdtar -czf file.tar --options='compression-level=9'.
666     For more details, see the explanation of the archive_read_set_options()
667     and archive_write_set_options() API calls that are described in
668     archive_read(3) and archive_write(3).
669

COMPATIBILITY

671     The bundled-arguments format is supported for compatibility with historic
672     implementations.  It consists of an initial word (with no leading - char‐
673     acter) in which each character indicates an option.  Arguments follow as
674     separate words.  The order of the arguments must match the order of the
675     corresponding characters in the bundled command word.  For example,
676           bsdtar tbf 32 file.tar
677     specifies three flags t, b, and f.  The b and f flags both require argu‐
678     ments, so there must be two additional items on the command line.  The 32
679     is the argument to the b flag, and file.tar is the argument to the f
680     flag.
681
682     The mode options c, r, t, u, and x and the options b, f, l, m, o, v, and
683     w comply with SUSv2.
684
685     For maximum portability, scripts that invoke tar should use the bundled-
686     argument format above, should limit themselves to the c, t, and x modes,
687     and the b, f, m, v, and w options.
688
689     Additional long options are provided to improve compatibility with other
690     tar implementations.
691

SECURITY

693     Certain security issues are common to many archiving programs, including
694     bsdtar.  In particular, carefully-crafted archives can request that
695     bsdtar extract files to locations outside of the target directory.  This
696     can potentially be used to cause unwitting users to overwrite files they
697     did not intend to overwrite.  If the archive is being extracted by the
698     superuser, any file on the system can potentially be overwritten.  There
699     are three ways this can happen.  Although bsdtar has mechanisms to pro‐
700     tect against each one, savvy users should be aware of the implications:
701
702     ·       Archive entries can have absolute pathnames.  By default, bsdtar
703             removes the leading / character from filenames before restoring
704             them to guard against this problem.
705
706     ·       Archive entries can have pathnames that include .. components.
707             By default, bsdtar will not extract files containing .. compo‐
708             nents in their pathname.
709
710     ·       Archive entries can exploit symbolic links to restore files to
711             other directories.  An archive can restore a symbolic link to
712             another directory, then use that link to restore a file into that
713             directory.  To guard against this, bsdtar checks each extracted
714             path for symlinks.  If the final path element is a symlink, it
715             will be removed and replaced with the archive entry.  If -U is
716             specified, any intermediate symlink will also be unconditionally
717             removed.  If neither -U nor -P is specified, bsdtar will refuse
718             to extract the entry.
719     To protect yourself, you should be wary of any archives that come from
720     untrusted sources.  You should examine the contents of an archive with
721           bsdtar -tf filename
722     before extraction.  You should use the -k option to ensure that bsdtar
723     will not overwrite any existing files or the -U option to remove any pre-
724     existing files.  You should generally not extract archives while running
725     with super-user privileges.  Note that the -P option to bsdtar disables
726     the security checks above and allows you to extract an archive while pre‐
727     serving any absolute pathnames, .. components, or symlinks to other
728     directories.
729

SEE ALSO

731     bzip2(1), compress(1), cpio(1), gzip(1), mt(1), pax(1), shar(1), xz(1),
732     libarchive(3), libarchive-formats(5), tar(5)
733

STANDARDS

735     There is no current POSIX standard for the tar command; it appeared in
736     ISO/IEC 9945-1:1996 (“POSIX.1”) but was dropped from IEEE Std 1003.1-2001
737     (“POSIX.1”).  The options supported by this implementation were developed
738     by surveying a number of existing tar implementations as well as the old
739     POSIX specification for tar and the current POSIX specification for pax.
740
741     The ustar and pax interchange file formats are defined by IEEE Std
742     1003.1-2001 (“POSIX.1”) for the pax command.
743

HISTORY

745     A tar command appeared in Seventh Edition Unix, which was released in
746     January, 1979.  There have been numerous other implementations, many of
747     which extended the file format.  John Gilmore's pdtar public-domain
748     implementation (circa November, 1987) was quite influential, and formed
749     the basis of GNU tar.  GNU tar was included as the standard system tar in
750     FreeBSD beginning with FreeBSD 1.0.
751
752     This is a complete re-implementation based on the libarchive(3) library.
753     It was first released with FreeBSD 5.4 in May, 2005.
754

BUGS

756     This program follows ISO/IEC 9945-1:1996 (“POSIX.1”) for the definition
757     of the -l option.  Note that GNU tar prior to version 1.15 treated -l as
758     a synonym for the --one-file-system option.
759
760     The -C dir option may differ from historic implementations.
761
762     All archive output is written in correctly-sized blocks, even if the out‐
763     put is being compressed.  Whether or not the last output block is padded
764     to a full block size varies depending on the format and the output
765     device.  For tar and cpio formats, the last block of output is padded to
766     a full block size if the output is being written to standard output or to
767     a character or block device such as a tape drive.  If the output is being
768     written to a regular file, the last block will not be padded.  Many com‐
769     pressors, including gzip(1) and bzip2(1), complain about the null padding
770     when decompressing an archive created by bsdtar, although they still
771     extract it correctly.
772
773     The compression and decompression is implemented internally, so there may
774     be insignificant differences between the compressed output generated by
775           bsdtar -czf - file
776     and that generated by
777           bsdtar -cf - file | gzip
778
779     The default should be to read and write archives to the standard I/O
780     paths, but tradition (and POSIX) dictates otherwise.
781
782     The r and u modes require that the archive be uncompressed and located in
783     a regular file on disk.  Other archives can be modified using c mode with
784     the @archive-file extension.
785
786     To archive a file called @foo or -foo you must specify it as ./@foo or
787     ./-foo, respectively.
788
789     In create mode, a leading ./ is always removed.  A leading / is stripped
790     unless the -P option is specified.
791
792     There needs to be better support for file selection on both create and
793     extract.
794
795     There is not yet any support for multi-volume archives.
796
797     Converting between dissimilar archive formats (such as tar and cpio)
798     using the @- convention can cause hard link information to be lost.
799     (This is a consequence of the incompatible ways that different archive
800     formats store hardlink information.)
801
802BSD                            February 25, 2017                           BSD
Impressum