R: Create a Tar Archive

tar {utils}

R Documentation

Create a Tar Archive

Description

Create a tar archive.

Usage

tar(tarfile, files = NULL,
    compression = c("none", "gzip", "bzip2", "xz"),
    compression_level = 6, tar = Sys.getenv("tar"),
    extra_flags = "")

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 writes.
`files`	A character vector of filepaths to be archived: the default is to archive all files under the current directory.
`compression`	character string giving the type of compression to be used (default none). Can be abbreviated.
`compression_level`	integer: the level of compression. Only used for the internal method.
`tar`	character string: the path to the command to be used. If the command itself contains spaces it needs to be quoted – but `tar` can also contain flags separated from the command by spaces.
`extra_flags`	any extra flags for an external `tar`.

Details

This is either a wrapper for a tar command or uses an internal implementation in R. The latter is used if tarfile is a connection or if the argument tar is "internal" or "". Note that whereas Unix-alike versions of R set the environment variable TAR, its value is not the default for this function.

Argument extra_flags is passed to an external tar and so is platform-dependent. Possibly useful values include -h (follow symbolic links, also -L on some platforms), --acls, --exclude-backups, --exclude-vcs (and similar) and on Windows --force-local (so drives can be included in filepaths: this is the default for the Rtools tar.

Value

The return code from system or 0 for the internal version, invisibly.

Portability

The ‘tar’ format no longer has an agreed standard! ‘Unix Standard Tar’ was part of POSIX 1003.1:1998 but has been removed in favour of pax, and in any case many common implementations diverged from the former standard. Most R platforms use a version of GNU tar (including Rtools on Windows, but the behaviour seems to be changed with each version), Mac OS 10.6 and FreeBSD use bsdttar from the libarchive project, and commercial Unixes will have their own versions.

Known problems arise from

The handling of file names of more than 100 bytes. These were unsupported in early versions of tar, and supported in one way by POSIX tar and in another by GNU tar. The internal implementation uses the POSIX way which supports up to 255 bytes (depending on the path), and warns on paths of more than 100 bytes.
(File) links. tar was developed on an OS that used hard links, and physical files that were referred to more than one in the list of files to be included were included only once, the remaining instance being added as links. Later a means to include symbolic links was added. The internal implementation supports symbolic links (on OSes that support them), only. Of course, the question arises as to how links should be unpacked on OSes that do not support them: for files at least file copies can be used.
Header fields, in particular the padding to be used when fields are not full or not used. POSIX did define the correct behaviour but commonly used implementations did (and still do) not comply.

For portability, avoid file paths of more than 100 bytes, and links (or at least, hard links and symbolic links to directories).

The internal implementation writes only the blocks of 512 bytes required, unlike GNU tar which by default pads with nul to a multiple of 20 blocks (10KB). Implementations differ on whether the block padding should occur before or after compression (or both).