untar {utils} | R Documentation

## Extract or List Tar Archives

### Description

Extract files from or list the contents of a tar archive.

### Usage

    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"))

### 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. For a compressed `tarfile`, and if a connection is to be used, that should be created by `gzfile(.)` (or `gzcon(.)` which currently only works for `"gzip"`, whereas `gzfile()` works for all compressions available in `tar()`).
`files` | A character vector of recorded filepaths to be extracted: the default is to extract all files.
`list` | If `TRUE`, 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`

(Deprecated in favour of auto-detection, used only for an external `tar` command.) Logical or character string. 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, and `NA` (the default) indicates that the type is to be inferred from the file header.

The external command may ignore the selected compression type but detect a type automagically.

`extras` | `NULL` or a character string: further command-line flags such as -p to be passed to an external `tar` program.
`verbose` | logical: if true echo the command used for an external `tar` program.

`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 `tar` command is assumed to be able handle compressed tarfiles and if `compressed` does not specify it, to automagically detect the type of compression. (The major implementations have done so since 2009; for GNU `tar` since version 1.22.)

If true, the R code calls an appropriate decompressor and pipes the output to `tar`, for `compressed = NA` examining the tarfile header to determine the type of compression.

`tar` | 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.

### 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).

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.

GNU tar:

  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).

NetBSD:

  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:

  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.

Heirloom Toolchest:

  This `tar` does automagically detect `gzip` and `bzip2` compression (undocumented) but has no support for `xz` compression.

Older support:

  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 ‘._’.

### 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` with an external `tar` or `0L`, invisibly.

### See Also

`tar`, `unzip`.

[Package utils version 3.6.0 Index]