Extract files from or list the contents of a tar archive.
untar(tarfile, files = NULL, list = FALSE, exdir = ".",
compressed = NA, extras = NULL, verbose = FALSE,
restore_times = TRUE, tar = Sys.getenv("TAR"))The pathname of the tar file: tilde expansion (see
path.expand) will be performed. Alternatively, a
connection that can be used for binary reads.
A character vector of recorded filepaths to be extracted: the default is to extract all files.
If TRUE, list the files (the equivalent of
tar -tf). Otherwise extract the files (the equivalent of
tar -xf).
The directory to extract files to (the equivalent of
tar -C). It will be created if necessary.
logical or character string, used only for an
external tar command. Values "gzip",
"bzip2" and "xz" select that form of compression (and
may be abbreviated to the first letter). TRUE indicates
gzip compression, FALSE no known compression (but
an external tar command may detect compression
automagically), and NA (the default) indicates that the type
is inferred from the file header.
The external command may ignore the selected compression type but detect a type automagically.
NULL or a character string: further command-line
flags such as -p to be passed to an external tar
program.
logical: if true echo the command used for an external
tar program.
logical. If true (default) restore file modification times. If false, the equivalent of the -m flag. Times in tarballs are supposed to be in UTC, but tarballs have been submitted to CRAN with times in the future or far past: this argument allows such times to be discarded.
Note that file times in a tarball are stored with a resolution of 1 second, and can only be restored to the resolution supported by the file system (which on a FAT system is 2 seconds).
character string: the path to the command to be used or
"internal". If the command itself contains spaces it needs
to be quoted -- but tar can also contain flags separated from
the command by spaces.
If list = TRUE, a character vector of (relative or absolute)
paths of files contained in the tar archive.
Otherwise the return code from system with an external
tar or 0L, invisibly.
This is either a wrapper for a tar command or for an
internal implementation written in R. The latter is used if
tarfile is a connection or if the argument tar is
"internal" or "" (except on Windows, when
tar.exe is tried first).
What options are supported will depend on the tar used.
Modern GNU tar versions support compressed archives,
and since 1.15 are able to detect the type of compression
automatically: version 1.22 added support xz compression.
macOS 10.6 and later (and FreeBSD and some other OSes) have a
tar (also known as bsdtar) from the
libarchive project which can also detect gzip and
bzip2 compression automatically. For other flavours of
tar, environment variable R_GZIPCMD gives the command
to decompress gzip and compress files, and
R_BZIPCMD for bzip2 files.
Arguments compressed, extras and verbose are only
used when an external tar is used.
Setting compressed = FALSE allows an external tar to
select the compression type from the file header: some external
commands will detect lrzip, lzma, lz4,
lzop or zstd compression
in addition to the three documented character values of
compressed. (For some external tar commands,
compressed tarfiles can only be read if the appropriate utility
program is available.) For GNU tar, further (de)compression
programs can be specified by e.g.extras = "-I lz4".
For bsdtar this could be
extras = "--use-compress-program lz4".
Most commands will detect (the nowadays rarely seen) .tar.Z
archives compressed by compress.
The internal implementation restores symbolic links as links on a
Unix-alike, and as file copies on Windows (which works only for
existing files, not for directories), and hard links as links. If the
linking operation fails (as it may on a FAT file system), a file copy
is tried. Since it uses gzfile to read a file it can
handle files compressed by any of the methods that function can
handle: at least compress, gzip, bzip2
and xz compression, and some types of lzma
compression. It does not guard against restoring absolute file paths,
as some tar implementations do. It will create the parent
directories for directories or files in the archive if necessary. It
handles the standard (USTAR/POSIX), GNU and pax ways of
handling file paths of more than 100 bytes, and the GNU way of
handling link targets of more than 100 bytes.
You may see warnings from the internal implementation such as
unsupported entry type 'x'
This often indicates an invalid archive: entry types "A-Z" are
allowed as extensions, but other types are reserved. The only thing
you can do with such an archive is to find a tar program that
handles it, and look carefully at the resulting files. There may also
be the warning
using pax extended headers
This is indicates that additional information may have been discarded, such as ACLs, encodings ….
The standards only support ASCII filenames (indeed, only alphanumeric
plus period, underscore and hyphen). untar makes no attempt to
map filenames to those acceptable on the current system, and treats
the filenames in the archive as applicable without any re-encoding in
the current locale.
The internal implementation does not special-case ‘resource
forks’ in macOS: that system's tar command does. This may
lead to unexpected files with names with prefix ._.