untar {utils}R Documentation

Extract or List Tar Archives

Description

Extract files from or list a tar archive.

Usage

untar(tarfile, files = NULL, list = FALSE, exdir = ".",
      compressed = NA, extras = NULL, verbose = FALSE,
      tar = Sys.getenv("TAR"))

Arguments

tarfile The pathname of the tar file: tilde expansion (see path.expand) will be performed. Alternatively, a connection that can be used for binary reads.
files A character vector of recorded filepaths to be extracted: the default is to extract all files.
list If TRUE, just list the files. The equivalent of tar -tf. Otherwise extract the files (the equivalent of tar -xf).
exdir The directory to extract files to (the equivalent of tar -C). It will be created if necessary.
compressed logical or character. 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 the tar command may detect compression automagically), and NA (the default) that the type is inferred from the file header.
extras NULL or a character string: further command-line flags such as -p to be passed to the tar program.
verbose logical: if true echo the command used.
tar character string: the path to the command to be used.

Details

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 flavours of tar will support compressed archives, and since 1.15 are able to detect the type of compression automatically: version 1.20 added support for lzma and version 1.22 for xz compression using LZMA2. For other flavours of tar, environment variable R_GZIPCMD gives the command to decompress gzip and compress files, and R_BZIPCMD for its files. (There is a bsdtar command from the libarchive project used by Mac OS 10.6 (‘Snow Leopard’) which can also detect gzip and bzip2 compression automatically, as can the tar from the ‘Heirloom Toolchest’ project.)

Arguments compressed, extras and verbose are only used when an external tar is used.

The internal implementation restores links (hard and soft) as symbolic links on a Unix-alike, and as file copies on Windows (which works only for files, not for directories). 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 both the standard (USTAR/POSIX) and GNU ways of handling file paths of more than 100 bytes.

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.

Value

If list = TRUE, a character vector of (relative or absolute) paths of files contained in the tar archive.

Otherwise the return code from system, invisibly.

See Also

tar, unzip.


[Package utils version 2.10.1 Index]