EVOLUTION-MANAGER

Edit File: tar.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Create a Tar Archive</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for tar {utils}"><tr><td>tar {utils}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>
Create a Tar Archive
</h2>

<h3>Description</h3>

Create a tar archive.

<h3>Usage</h3>

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

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>tarfile</code></td>
<td>
The pathname of the tar file: tilde expansion (see
<code><a href="../../base/html/path.expand.html">path.expand</a></code>) will be performed. Alternatively, a
<a href="../../base/html/connections.html">connection</a> that can be used for binary writes.
</td></tr>
<tr valign="top"><td><code>files</code></td>
<td>
A character vector of filepaths to be archived:
the default is to archive all files under the current directory.
</td></tr>
<tr valign="top"><td><code>compression</code></td>
<td>
character string giving the type of compression to
be used (default none). Can be abbreviated.
</td></tr>
<tr valign="top"><td><code>compression_level</code></td>
<td>
integer: the level of compression. Only used
for the internal method.
</td></tr>
<tr valign="top"><td><code>tar</code></td>
<td>
character string: the path to the command to be used. If
the command itself contains spaces it needs to be quoted (e.g., by
<code><a href="../../base/html/shQuote.html">shQuote</a></code>) &ndash; but argument <code>tar</code> may also contain
flags separated from the command by spaces.
</td></tr>
<tr valign="top"><td><code>extra_flags</code></td>
<td>
Any extra flags for an external <code>tar</code>.
</td></tr>
</table>

<h3>Details</h3>

This is either a wrapper for a <code>tar</code> command or uses an
internal implementation in R. The latter is used if <code>tarfile</code>
is a connection or if the argument <code>tar</code> is <code>"internal"</code> or
<code>""</code> (the &lsquo;factory-fresh&rsquo; default). Note that whereas
Unix-alike versions of R set the environment variable TAR, its
value is not the default for this function.

Argument <code>extra_flags</code> is passed to an external <code>tar</code> 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: however, this is the default for the
<code>Rtools</code> <code>tar</code>). For GNU <code>tar</code>,
--format=ustar forces a more portable format. (The default is
set at compilation and will be shown at the end of the output from
<code>tar --help</code>: for version 1.30 &lsquo;out-of-the-box&rsquo; it is 
--format=gnu, but the manual says the intention is to change
to --format=posix which is the same as <code>pax</code> &ndash;
it was never part of the POSIX standard for <code>tar</code> and should
not be used.)
For libarchive's <code>bsdtar</code>, --format=ustar is more
portable than the default.

One issue which can cause an external command to fail is a command
line too long for the system shell: as from R 3.5.0 this is worked
around if the external command is detected to be GNU <code>tar</code> or
libarchive <code>tar</code> (aka <code>bsdtar</code>).

Note that <code>files = '.'</code> will usually not work with an external
<code>tar</code> as that would expand the list of files after
<code>tarfile</code> is created. (It does work with the default internal
method.)

<h3>Value</h3>

The return code from <code><a href="../../base/html/system.html">system</a></code> or <code>0</code> for the internal
version, invisibly.

<h3>Portability</h3>

The &lsquo;tar&rsquo; format no longer has an agreed standard!
&lsquo;Unix Standard Tar&rsquo; was part of POSIX 1003.1:1998 but has been
removed in favour of <code>pax</code>, and in any case many common
implementations diverged from the former standard.

Many R platforms use a version of GNU <code>tar</code> (including
<code>Rtools</code> on Windows), but the behaviour seems to be changed
with each version. macOS &gt;= 10.6 and FreeBSD use <code>bsdtar</code>
from the libarchive project (but for macOS, a version from 2010), and
commercial Unixes will have their own versions. <code>bsdtar</code> is
available for many other platforms: macOS up to at least 10.9 had GNU
<code>tar</code> as <code>gnutar</code> and other platforms,
e.g. Solaris, have it as <code>gtar</code>: on a Unix-alike
<code>configure</code> will try <code>gnutar</code> and <code>gtar</code>
before <code>tar</code>.

Known problems arise from

<ul>
<li> The handling of file paths of more than 100 bytes. These were
unsupported in early versions of <code>tar</code>, and supported in one
way by POSIX <code>tar</code> and in another by GNU <code>tar</code> and
yet another by the POSIX <code>pax</code> command which
recent <code>tar</code> programs often support. The internal
implementation warns on paths of more than 100 bytes,
uses the &lsquo;ustar&rsquo; way from the 1998 POSIX
standard which supports up to 256 bytes (depending on the path: in
particular the final component is limited to 100 bytes) if possible,
otherwise the GNU way (which is widely supported, including by
<code><a href="untar.html">untar</a></code>).

Most formats do not record the encoding of file paths.

</li>
<li> (File) links. <code>tar</code> was developed on an OS that used
hard links, and physical files that were referred to more than once
in the list of files to be included were included only once, the
remaining instances 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 regular files file copies can be used.

Names of links in the &lsquo;ustar&rsquo; format are restricted to 100
bytes. There is an GNU extension for arbitrarily long link names,
but <code>bsdtar</code> ignores it. The internal method uses the
GNU extension, with a warning.

</li>
<li> 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.

</li>
<li> File sizes. The &lsquo;ustar&rsquo; format is restricted to 8GB
per (uncompressed) file.

</li></ul>

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

The internal implementation writes only the blocks of 512 bytes
required (including trailing blocks of nuls), unlike GNU <code>tar</code>
which by default pads with nul to a multiple of 20 blocks
(10KB). Implementations which pad differ on whether the block padding
should occur before or after compression (or both): padding was
designed for improved performance on physical tape drives.

The &lsquo;ustar&rsquo; format records file modification times to a
resolution of 1 second: on file systems with higher resolution it is
conventional to discard fractional seconds.

<h3>Compression</h3>

When an external <code>tar</code> command is used, compressing the tar
archive requires that <code>tar</code> supports the -z,
-j or -J flag, and may require the appropriate
command (<code>gzip</code>, <code>bzip2</code> or <code>xz</code>) to be
available. For GNU <code>tar</code>, further compression programs can be
specified by e.g. <code>extra_flags = "-I lz4"</code>.
Some versions of <code>bsdtar</code> accept options such as
--lz4, --lzop and --lrzip or an external
compressor via <code>--use-compress-program lz4</code>: these could
be supplied in <code>extra_flags</code>.

NetBSD prior to 8.0 used flag --xz rather than -J,
so this should be used via <code>extra_flags = "--xz"</code> rather
than <code>compression = "xz"</code>. The commands from OpenBSD and the
Heirloom Toolchest are not documented to support <code>xz</code>.

The <code>tar</code> programs in commercial Unixen such as AIX and
Solaris do not support compression.

For users of macOS (formerly OS X). Apple's HFS and HFS+ file systems
have a legacy concept of &lsquo;resource forks&rsquo; dating from classic
Mac OS and rarely used nowadays. Apple's version of <code>tar</code>
stores these as separate files in the tarball with names prefixed by
&lsquo;._&rsquo;, and unpacks such files into resource forks (if possible):
other ways of unpacking (including <code><a href="untar.html">untar</a></code> in R) unpack
them as separate files.

When argument <code>tar</code> is set to the command <code>tar</code> on macOS,
environment variable COPYFILE_DISABLE=1 is set, which for the
system version of <code>tar</code> prevents these separate files being
included in the tarball.

<a href="https://en.wikipedia.org/wiki/Tar_(file_format)">https://en.wikipedia.org/wiki/Tar_(file_format)</a>,
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_06">http://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html#tag_20_92_13_06</a>
for the way the POSIX utility <code>pax</code> handles <code>tar</code> formats.

<a href="https://github.com/libarchive/libarchive/wiki/FormatTar">https://github.com/libarchive/libarchive/wiki/FormatTar</a>.

<code><a href="untar.html">untar</a></code>.

<hr /><div style="text-align: center;">[Package utils version 3.6.0 <a href="00Index.html">Index</a>]</div>
</body></html>