updates, mention -P

git-svn-id: https://svn.r-project.org/R/trunk@88328 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: ripley

src/library/utils/man/tar.Rd

@@ -188,12 +188,12 @@ tar(tarfile, files = NULL,
   \I{Heirloom Toolchest} are not documented to support \command{xz} nor
   \command{zstd}.
 
-  The \command{tar} program in recent macOS (e.g.\sspace{}15.2) does
-  support \command{zstd} compression.\emph{via} an
-  external command, but Apple does not supply one.
+  The \command{tar} program in recent macOS (e.g.\sspace{}15.5) does
+  support \command{zstd} compression.\emph{via} an external
+  \command{zstd} program, but Apple does not supply one.
 
-  The \command{tar} programs in commercial Unixen such as \I{AIX} and
-  Solaris do not support compression.
+  %% The \command{tar} programs in commercial Unixen such as \I{AIX} and
+  %% Solaris do not support compression.
 
   GNU \command{tar} added support in version 1.22 for \command{xz}
   compression and in version 1.31 for \command{zstd} compression.
@@ -204,15 +204,21 @@ tar(tarfile, files = NULL,
   support parallel compression --- but this function can be used to write
   an uncompressed tarball which can then be compressed in parallel, for
   example with \command{zstd -T0}.
+
+  Some external commands have \sQuote{security} measures to by default
+  change the recorded file paths.  For example, GNU \code{tar} and
+  \command{bsdtar} remove the leading slash on absolute filepaths:
+  specify \code{extra_flags = "-P"} to override this.
 }
 
 \note{
-  For users of macOS.  Apple's file systems have a legacy concept of
+  For users of macOS.  Apple's legacy file systems had a concept of
   \sQuote{resource forks} dating from classic Mac OS and rarely used
-  nowadays.  Apple's version of \command{tar} stores these as separate
-  files in the tarball with names prefixed by \file{._}, and unpacks
-  such files into resource forks (if possible): other ways of unpacking
-  (including \code{\link{untar}} in \R) unpack them as separate files.
+  nowadays (and only partially supported in APFS).  Apple's version of
+  \command{tar} stored these as separate files in the tarball with names
+  prefixed by \file{._}, and unpacks such files into resource forks (if
+  possible): other ways of unpacking (including \code{\link{untar}} in
+  \R) unpack them as separate files.
 
   When argument \code{tar} is set to the command \command{tar} on macOS,
   environment variable \env{COPYFILE_DISABLE=1} is set, which for the

src/library/utils/man/untar.Rd

@@ -52,8 +52,8 @@ untar(tarfile, files = NULL, list = FALSE, exdir = ".",
   }
 
   \item{extras}{\code{NULL} or a character string: further command-line
-    flags such as \option{-p} to be passed to an external \command{tar}
-    program.}
+    flags such as \option{-p} or \option{-P} to be passed to an external
+    \command{tar} program.}
 
   \item{verbose}{logical: if true echo the command used for an external
     \command{tar} program.}
@@ -200,6 +200,13 @@ untar(tarfile, files = NULL, list = FALSE, exdir = ".",
   The internal implementation does not special-case \sQuote{resource
   forks} in macOS: that system's \command{tar} command does. This may
   lead to unexpected files with names with prefix \file{._}.
+
+  Some external commands have \sQuote{security} measures to change the
+  extracted file paths.  For example, GNU \code{tar} and
+  \command{bsdtar} remove the leading slash on absolute filepaths:
+  specify \code{extras = "-P"} to override this. \command{bsdtar}
+  refuses to exract paths containing \code{".."}  with the same
+  workaround.
 }
 
 \value{