1
.\" Copyright (c) 2003-2007 Tim Kientzle
2
.\" All rights reserved.
4
.\" Redistribution and use in source and binary forms, with or without
5
.\" modification, are permitted provided that the following conditions
7
.\" 1. Redistributions of source code must retain the above copyright
8
.\" notice, this list of conditions and the following disclaimer.
9
.\" 2. Redistributions in binary form must reproduce the above copyright
10
.\" notice, this list of conditions and the following disclaimer in the
11
.\" documentation and/or other materials provided with the distribution.
13
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25
.\" $FreeBSD: src/usr.bin/tar/bsdtar.1,v 1.46 2008/12/06 07:37:55 kientzle Exp $
32
.Nd manipulate tape archives
35
.Op Ar bundled-flags Ao args Ac
36
.Op Ao Ar file Ac | Ao Ar pattern Ac ...
40
.Op Ar files | Ar directories
45
.Op Ar files | Ar directories
52
creates and manipulates streaming archive files.
53
This implementation can extract from tar, pax, cpio, zip, jar, ar,
54
and ISO 9660 cdrom images and can create tar, pax, cpio, ar,
57
The first synopsis form shows a
60
This usage is provided for compatibility with historical implementations.
61
See COMPATIBILITY below for details.
63
The other synopsis forms show the preferred usage.
66
is a mode indicator from the following list:
67
.Bl -tag -compact -width indent
69
Create a new archive containing the specified items.
73
but new entries are appended to the archive.
74
Note that this only works on uncompressed archives stored in regular files.
79
List archive contents to stdout.
83
but new entries are added only if they have a modification date
84
newer than the corresponding entry in the archive.
85
Note that this only works on uncompressed archives stored in regular files.
90
Extract to disk from the archive.
91
If a file with the same name appears more than once in the archive,
92
each copy will be extracted, with later copies overwriting (replacing)
101
mode, each specified file or directory is added to the
102
archive in the order specified on the command line.
103
By default, the contents of each directory are also archived.
105
In extract or list mode, the entire command line
106
is read and parsed before the archive is opened.
107
The pathnames or patterns on the command line indicate
108
which items in the archive should be processed.
109
Patterns are shell-style globbing patterns as
113
Unless specifically stated otherwise, options are applicable in
115
.Bl -tag -width indent
116
.It Cm @ Ns Pa archive
118
The specified archive is opened and the entries
119
in it will be appended to the current archive.
121
.Dl Nm Fl c Fl f Pa - Pa newfile Cm @ Ns Pa original.tar
122
writes a new archive to standard output containing a file
124
and all of the entries from
127
.Dl Nm Fl c Fl f Pa - Pa newfile Pa original.tar
128
creates a new archive with only two entries.
130
.Dl Nm Fl czf Pa - Fl -format Cm pax Cm @ Ns Pa -
131
reads an archive from standard input (whose format will be determined
132
automatically) and converts it into a gzip-compressed
133
pax-format archive on stdout.
136
can be used to convert archives from one format to another.
137
.It Fl b Ar blocksize
138
Specify the block size, in 512-byte records, for tape drive I/O.
139
As a rule, this argument is only needed when reading from or writing
140
to tape drives, and usually not even then as the default block size of
141
20 records (10240 bytes) is very common.
142
.It Fl C Ar directory
143
In c and r mode, this changes the directory before adding
145
In x mode, change directories after opening the archive
146
but before extracting entries from the archive.
149
Issue a warning message unless all links to each file are archived.
153
to the current directory after processing any
155
options and before extracting any files.
156
.It Fl -exclude Ar pattern
157
Do not process files or directories that match the
159
Note that exclusions take precedence over patterns or filenames
160
specified on the command line.
161
.It Fl -format Ar format
163
Use the specified format for the created archive.
164
Supported formats include
170
Other formats may also be supported; see
171
.Xr libarchive-formats 5
172
for more information about currently-supported formats.
173
In r and u modes, when extending an existing archive, the format specified
174
here must be compatible with the format of the existing archive on disk.
176
Read the archive from or write the archive to the specified file.
179
for standard input or standard output.
180
If not specified, the default tape device will be used.
183
the default tape device is
187
Symbolic links named on the command line will be followed; the
188
target of the link will be archived, not the link itself.
196
.It Fl -include Ar pattern
197
Process only files or directories that match the specified pattern.
198
Note that exclusions specified with
200
take precedence over inclusions.
201
If no inclusions are explicitly specified, all entries are processed by
205
option is especially useful when filtering archives.
206
For example, the command
207
.Dl Nm Fl c Fl f Pa new.tar Fl -include='*foo*' Cm @ Ns Pa old.tgz
208
creates a new archive
210
containing only the entries from
212
containing the string
216
Compress the resulting archive with
218
In extract or list modes, this option is ignored.
219
Note that, unlike other
221
implementations, this implementation recognizes bzip2 compression
222
automatically when reading archives.
225
Do not overwrite existing files.
226
In particular, if a file appears more than once in an archive,
227
later copies will not overwrite earlier copies.
228
.It Fl -keep-newer-files
230
Do not overwrite existing files that are newer than the
231
versions appearing in the archive being extracted.
234
All symbolic links will be followed.
235
Normally, symbolic links are archived as such.
236
With this option, the target of the link will be archived instead.
238
This is a synonym for the
243
Do not extract modification time.
244
By default, the modification time is set to the time stored in the archive.
247
Do not recursively archive the contents of directories.
248
.It Fl -newer Ar date
250
Only include files and directories newer than the specified date.
251
This compares ctime entries.
252
.It Fl -newer-mtime Ar date
256
except it compares mtime entries instead of ctime entries.
257
.It Fl -newer-than Pa file
259
Only include files and directories newer than the specified file.
260
This compares ctime entries.
261
.It Fl -newer-mtime-than Pa file
265
except it compares mtime entries instead of ctime entries.
268
Honor the nodump file flag by skipping this file.
275
Filenames or patterns are separated by null characters,
277
This is often used to read filenames output by the
281
.It Fl -numeric-owner
283
Ignore symbolic user and group names when restoring archives to disk,
284
only numeric uid and gid values will be obeyed.
287
In extract (-x) mode, files will be written to standard out rather than
288
being extracted to disk.
289
In list (-t) mode, the file listing will be written to stderr rather than
293
Use the user and group of the user running the program rather
294
than those specified in the archive.
295
Note that this has no significance unless
297
is specified, and the program is being run by the root user.
298
In this case, the file modes and flags from
299
the archive will be restored, but ACLs or owner information in
300
the archive will be discarded.
305
.It Fl -one-file-system
307
Do not cross mount points.
308
.It Fl -options Ar options
309
Select optional behaviors for particular modules.
310
The argument is a text string containing comma-separated
312
These are passed to the modules that handle particular
313
formats to control how those formats will behave.
314
Each option has one of the following forms:
315
.Bl -tag -compact -width indent
317
The key will be set to the specified value in every module that supports it.
318
Modules that do not support this key will ignore it.
320
The key will be enabled in every module that supports it.
321
This is equivalent to
324
The key will be disabled in every module that supports it.
325
.It Ar module:key=value , Ar module:key , Ar module:!key
326
As above, but the corresponding key and value will be provided
327
only to modules whose name matches
330
The currently supported modules and keys are:
331
.Bl -tag -compact -width indent
332
.It Cm iso9660:joliet
333
Support Joliet extensions.
334
This is enabled by default, use
339
.It Cm iso9660:rockridge
340
Support Rock Ridge extensions.
341
This is enabled by default, use
344
.Cm iso9660:!rockridge
346
.It Cm gzip:compression-level
347
A decimal integer from 0 to 9 specifying the gzip compression level.
348
.It Cm xz:compression-level
349
A decimal integer from 0 to 9 specifying the xz compression level.
350
.It Cm mtree: Ns Ar keyword
351
The mtree writer module allows you to specify which mtree keywords
352
will be included in the output.
353
Supported keywords include:
354
.Cm cksum , Cm device , Cm flags , Cm gid , Cm gname , Cm indent ,
355
.Cm link , Cm md5 , Cm mode , Cm nlink , Cm rmd160 , Cm sha1 , Cm sha256 ,
356
.Cm sha384 , Cm sha512 , Cm size , Cm time , Cm uid , Cm uname .
357
The default is equivalent to:
358
.Dq device, flags, gid, gname, link, mode, nlink, size, time, type, uid, uname .
360
Enables all of the above keywords.
363
to disable all keywords.
369
Produce human-readable output by indenting options and splitting lines
370
to fit into 80 columns.
371
.It Cm zip:compression Ns = Ns Ar type
374
as compression method.
375
Supported values are store (uncompressed) and deflate (gzip algorithm).
377
If a provided option is not supported by any module, that
381
By default, absolute pathnames (those that begin with a /
382
character) have the leading slash removed both when creating archives
383
and extracting from them.
386
will refuse to extract archive entries whose pathnames contain
388
or whose target directory would be altered by a symlink.
389
This option suppresses these behaviors.
392
Preserve file permissions.
393
Attempt to restore the full permissions, including owner, file modes, file
394
flags and ACLs, if available, for each item extracted from the archive.
395
By default, newly-created files are owned by the user running
397
the file mode is restored for newly-created regular files, and
398
all other types of entries receive default permissions.
401
is being run by root, the default is to restore the owner unless the
403
option is also specified.
404
.It Fl q ( Fl -fast-read )
406
Extract or list only the first archive entry that matches each pattern
408
Exit as soon as each specified pattern or filename has been matched.
409
By default, the archive is always read to the very end, since
410
there can be multiple entries with the same name and, by convention,
411
later entries overwrite earlier entries.
412
This option is provided as a performance optimization.
415
Extract files as sparse files.
416
For every block on disk, check first if it contains only NULL bytes and seek
418
This works similiar to the conv=sparse option of dd.
419
.It Fl -strip-components Ar count
421
Remove the specified number of leading path elements.
422
Pathnames with fewer elements will be silently skipped.
423
Note that the pathname is edited after checking inclusion/exclusion patterns
424
but before security checks.
426
Modify file or archive member names according to
428
The pattern has the format
429
.Ar /old/new/ Ns Op gps
432
is a basic regular expression,
434
is the replacement string of the matched part,
435
and the optional trailing letters modify
436
how the replacement is handled.
439
is not matched, the pattern is skipped.
442
~ is substituted with the match, \e1 to \e9 with the content of
443
the corresponding captured group.
444
The optional trailing g specifies that matching should continue
445
after the matched part and stopped on the first unmatched pattern.
446
The optional trailing s specifies that the pattern applies to the value
448
The optional trailing p specifies that after a successful substitution
449
the original path name and the new path name should be printed to
454
will read the list of names to be extracted from
458
will read names to be archived from
462
on a line by itself will cause the current directory to be changed to
463
the directory specified on the following line.
464
Names are terminated by newlines unless
469
also disables the special handling of lines containing
473
Unlink files before creating them.
476
overwrites existing files, which preserves existing hardlinks.
477
With this option, existing hardlinks will be broken, as will any
478
symlink that would affect the location of an extracted file.
479
.It Fl -use-compress-program Ar program
480
Pipe the input (in x or t mode) or the output (in c mode) through
482
instead of using the builtin compression support.
484
Produce verbose output.
485
In create and extract modes,
487
will list each file name as it is read from or written to
491
will produce output similar to that of
495
options will provide additional detail.
503
Ask for confirmation for every action.
505
Read a list of exclusion patterns from the specified file.
508
for more information about the handling of exclusions.
511
Compress the resulting archive with
513
In extract or list modes, this option is ignored.
514
Note that, unlike other
516
implementations, this implementation recognizes bzip2 compression
517
automatically when reading archives.
520
Compress the resulting archive with
522
In extract or list modes, this option is ignored.
523
Note that, unlike other
525
implementations, this implementation recognizes gzip compression
526
automatically when reading archives.
529
Compress the resulting archive with
531
In extract or list modes, this option is ignored.
532
Note that, unlike other
534
implementations, this implementation recognizes compress compression
535
automatically when reading archives.
540
The following environment variables affect the execution of
542
.Bl -tag -width ".Ev BLOCKSIZE"
547
for more information.
549
The default tape device.
552
option overrides this.
554
The timezone to use when displaying dates.
557
for more information.
560
.Bl -tag -width ".Ev BLOCKSIZE"
562
The default tape device, if not overridden by the
564
environment variable or the
569
The following creates a new archive
572
that contains two files
576
.Dl Nm Fl czf Pa file.tar.gz Pa source.c Pa source.h
578
To view a detailed table of contents for this
580
.Dl Nm Fl tvf Pa file.tar.gz
582
To extract all entries from the archive on
583
the default tape drive:
586
To examine the contents of an ISO 9660 cdrom image:
587
.Dl Nm Fl tf Pa image.iso
589
To move file hierarchies, invoke
592
.Dl Nm Fl cf Pa - Fl C Pa srcdir\ . | Nm Fl xpf Pa - Fl C Pa destdir
593
or more traditionally
594
.Dl cd srcdir \&; Nm Fl cf Pa -\ . | ( cd destdir \&; Nm Fl xpf Pa - )
596
In create mode, the list of files and directories to be archived
597
can also include directory change instructions of the form
599
and archive inclusions of the form
600
.Cm @ Ns Pa archive-file .
601
For example, the command line
602
.Dl Nm Fl c Fl f Pa new.tar Pa foo1 Cm @ Ns Pa old.tgz Cm -C Ns Pa /tmp Pa foo2
603
will create a new archive
608
from the current directory and add it to the output archive.
609
It will then read each entry from
611
and add those entries to the output archive.
612
Finally, it will switch to the
616
to the output archive.
620
format can be used to create an output archive with arbitrary ownership,
621
permissions, or names that differ from existing data on disk:
623
.Dl $ cat input.mtree
625
.Dl usr/bin uid=0 gid=0 mode=0755 type=dir
626
.Dl usr/bin/ls uid=0 gid=0 mode=0755 type=file content=myls
627
.Dl $ tar -cvf output.tar @input.mtree
633
switches accept a variety of common date and time specifications, including
634
.Dq 12 Mar 2005 7:14:29pm ,
635
.Dq 2005-03-12 19:14 ,
638
.Dq 19:14 PST May 1 .
642
argument can be used to control various details of archive generation
644
For example, you can generate mtree output which only contains
649
.Dl Nm Fl cf Pa file.tar Fl -format=mtree Fl -options='!all,type,time,uid' Pa dir
650
or you can set the compression level used by gzip or xz compression:
651
.Dl Nm Fl czf Pa file.tar Fl -options='compression-level=9' .
652
For more details, see the explanation of the
653
.Fn archive_read_set_options
655
.Fn archive_write_set_options
656
API calls that are described in
659
.Xr archive_write 3 .
661
The bundled-arguments format is supported for compatibility
662
with historic implementations.
663
It consists of an initial word (with no leading - character) in which
664
each character indicates an option.
665
Arguments follow as separate words.
666
The order of the arguments must match the order
667
of the corresponding characters in the bundled command word.
669
.Dl Nm Cm tbf 32 Pa file.tar
670
specifies three flags
679
flags both require arguments,
680
so there must be two additional items
684
is the argument to the
688
is the argument to the
692
The mode options c, r, t, u, and x and the options
693
b, f, l, m, o, v, and w comply with SUSv2.
695
For maximum portability, scripts that invoke
697
should use the bundled-argument format above, should limit
712
Additional long options are provided to improve compatibility with other
715
Certain security issues are common to many archiving programs, including
717
In particular, carefully-crafted archives can request that
719
extract files to locations outside of the target directory.
720
This can potentially be used to cause unwitting users to overwrite
721
files they did not intend to overwrite.
722
If the archive is being extracted by the superuser, any file
723
on the system can potentially be overwritten.
724
There are three ways this can happen.
727
has mechanisms to protect against each one,
728
savvy users should be aware of the implications:
729
.Bl -bullet -width indent
731
Archive entries can have absolute pathnames.
736
character from filenames before restoring them to guard against this problem.
738
Archive entries can have pathnames that include
743
will not extract files containing
745
components in their pathname.
747
Archive entries can exploit symbolic links to restore
748
files to other directories.
749
An archive can restore a symbolic link to another directory,
750
then use that link to restore a file into that directory.
751
To guard against this,
753
checks each extracted path for symlinks.
754
If the final path element is a symlink, it will be removed
755
and replaced with the archive entry.
758
is specified, any intermediate symlink will also be unconditionally removed.
765
will refuse to extract the entry.
767
To protect yourself, you should be wary of any archives that
768
come from untrusted sources.
769
You should examine the contents of an archive with
770
.Dl Nm Fl tf Pa filename
774
option to ensure that
776
will not overwrite any existing files or the
778
option to remove any pre-existing files.
779
You should generally not extract archives while running with super-user
785
disables the security checks above and allows you to extract
786
an archive while preserving any absolute pathnames,
788
components, or symlinks to other directories.
798
.Xr libarchive-formats 5 ,
801
There is no current POSIX standard for the tar command; it appeared
806
The options used by this implementation were developed by surveying a
807
number of existing tar implementations as well as the old POSIX specification
808
for tar and the current POSIX specification for pax.
810
The ustar and pax interchange file formats are defined by
816
command appeared in Seventh Edition Unix, which was released in January, 1979.
817
There have been numerous other implementations,
818
many of which extended the file format.
821
public-domain implementation (circa November, 1987)
822
was quite influential, and formed the basis of GNU tar.
823
GNU tar was included as the standard system tar
829
This is a complete re-implementation based on the
835
for the definition of the
838
Note that GNU tar prior to version 1.15 treated
846
option may differ from historic implementations.
848
All archive output is written in correctly-sized blocks, even
849
if the output is being compressed.
850
Whether or not the last output block is padded to a full
851
block size varies depending on the format and the
853
For tar and cpio formats, the last block of output is padded
854
to a full block size if the output is being
855
written to standard output or to a character or block device such as
857
If the output is being written to a regular file, the last block
859
Many compressors, including
863
complain about the null padding when decompressing an archive created by
865
although they still extract it correctly.
867
The compression and decompression is implemented internally, so
868
there may be insignificant differences between the compressed output
870
.Dl Nm Fl czf Pa - file
871
and that generated by
872
.Dl Nm Fl cf Pa - file | Nm gzip
874
The default should be to read and write archives to the standard I/O paths,
875
but tradition (and POSIX) dictates otherwise.
881
modes require that the archive be uncompressed
882
and located in a regular file on disk.
883
Other archives can be modified using
889
To archive a file called
893
you must specify it as
899
In create mode, a leading
904
is stripped unless the
908
There needs to be better support for file selection on both create
911
There is not yet any support for multi-volume archives or for archiving
914
Converting between dissimilar archive formats (such as tar and cpio) using the
916
convention can cause hard link information to be lost.
917
(This is a consequence of the incompatible ways that different archive
918
formats store hardlink information.)
920
There are alternative long options for many of the short options that
921
are deliberately not documented.
added
removed
src/libarchive/tar/bsdtar.1
