| untar | R Documentation |
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,
support_old_tars = Sys.getenv("R_SUPPORT_OLD_TARS", FALSE),
tar = Sys.getenv("TAR"))
tarfile |
The pathname of the tar file: tilde expansion (see
|
files |
A character vector of recorded filepaths to be extracted: the default is to extract all files. |
list |
If |
exdir |
The directory to extract files to (the equivalent of
|
compressed |
(Deprecated in favour of auto-detection, used only
for an external The external command may ignore the selected compression type but detect a type automagically. |
extras |
|
verbose |
logical: if true echo the command used for an external
|
restore_times |
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). |
support_old_tars |
logical. If false (the default), the external
If true, the R code calls an appropriate decompressor and pipes
the output to |
tar |
character string: the path to the command to be used or
|
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).
Unless otherwise stated three types of compression of the tar file are
supported: gzip, bzip2 and xz.
What options are supported will depend on the tar
implementation used: the "internal" one is intended to provide
support for most in a platform-independent way.
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 for
xz compression.
On a Unix-alike, configure will set environment variable
TAR, preferring GNU tar if found.
bsdtar:macOS 10.6 and later (and FreeBSD and some
other OSes) have a tar
from the libarchive project which detects all three forms
of compression automagically (even if undocumented in macOS).
It is undocumented if NetBSD's tar can
detect compression automagically: for versions before 8 the flag
for xz compression was --xz not -J.
So support_old_tars = TRUE is recommended (or use
bsdtar if installed).
OpenBSD's tar does not detect compression
automagically. It has no support for xz beyond reporting
that the file is xz-compressed. So support_old_tars
= TRUE is recommended.
This tar does automagically
detect gzip and bzip2 compression (undocumented)
but has no support for xz compression.
Environment variable R_GZIPCMD gives the
command to decompress gzip files, and
R_BZIPCMD for bzip2 files. (On Unix-alikes
these are set at installation if found.) xz is used if
available: if not decompression is expected to fail.
Arguments compressed, extras and verbose are only
used when an external tar is used.
Some external tar commands will detect some of
lrzip, lzma, lz4, lzop and
zstd compression in addition to gzip,
bzip2 and xz. (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 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 indicates that additional information may have been discarded, such as ACLs, encodings ....
The former standards only supported 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 ‘._’.
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.
tar, unzip.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.
