updates and clarifications, including to which extracted paths have been altered

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

Author: ripley

src/library/utils/R/tar.R

@@ -41,11 +41,12 @@ untar <- function(tarfile, files = NULL, list = FALSE, exdir = ".",
 
     ## The ability of external tar commands to handle compressed tarfiles
     ## automagically varies and is poorly documented.
-    ## E.g. macOS says its tar handles bzip2 but does not mention xz nor lzma.
-    ## (And it supports -J and --lzma flags not mentioned by man tar.)
+    ## E.g. macOS used to say its tar handles bzip2 but did not mention xz nor lzma.
     ##
     ## But as all commonly-used tars do (some commercial Unix do not,
     ## but GNU tar is commonly used there).
+    ##
+    ## OTOH some (e.g. macOS) need external commands which may not be present.
     cflag <- ""
     if (!missing(compressed))
         warning("untar(compressed=) is deprecated", call. = FALSE, domain = NA)
@@ -124,7 +125,7 @@ untar <- function(tarfile, files = NULL, list = FALSE, exdir = ".",
     }
 }
 
-##' R's "internal" untar() -- called from of untar(), *not* exported
+##' R's "internal" untar() -- called from untar(), *not* exported
 untar2 <- function(tarfile, files = NULL, list = FALSE, exdir = ".",
                    restore_times = TRUE)
 {
@@ -151,7 +152,8 @@ untar2 <- function(tarfile, files = NULL, list = FALSE, exdir = ".",
             path <- gsub("\\\\", "/", path)
             while(grepl("^/", path) || grepl("^[a-zA-Z]:", path)) {
                 if (grepl("^/", path)) {
-                    warning("removing leading '/'")
+                    warning(gettextf("removing leading '/' from '%s'", path),
+                            call. = FALSE, domain = NA)
                     path <- sub("^/+", "", path)
                 }
                 if (grepl("^[a-zA-Z]:", path)) {
@@ -162,7 +164,8 @@ untar2 <- function(tarfile, files = NULL, list = FALSE, exdir = ".",
             }
         } else {
             if (grepl("^/", path)) {
-                warning("removing leading '/'")
+                warning(gettextf("removing leading '/' from '%s'", path),
+                        call. = FALSE, domain = NA)
                 path <- sub("^/+", "", path)
             }
         }
@@ -175,11 +178,8 @@ untar2 <- function(tarfile, files = NULL, list = FALSE, exdir = ".",
             return(".")
         p <- ""
         for(el in parts) {
-            if (nzchar(p))
-                p <- file.path(p, el)
-            else
-                p <- el
-            if(isTRUE(nzchar(Sys.readlink(p), keepNA=TRUE)))
+            p <- if (nzchar(p)) file.path(p, el) else el
+            if(isTRUE(nzchar(Sys.readlink(p), keepNA = TRUE)))
                 stop("cannot extract through symlink")
         }
         p
@@ -433,7 +433,7 @@ tar <- function(tarfile, files = NULL,
             ## Could pipe through gzip etc: might be safer for xz
             ## as -J was lzma in GNU tar 1.20:21
             ## NetBSD < 8 used --xz not -J
-            ## OpenBSD and Heirloom Toolchest have no support for xz
+            ## OpenBSD and Heirloom Toolchest had no support for xz
             flags <- switch(match.arg(compression),
                             "none" = "-cf",
                             "gzip" = "-zcf",
@@ -449,7 +449,7 @@ tar <- function(tarfile, files = NULL,
             if (is.null(extra_flags)) extra_flags <- ""
             ## precaution added in R 3.5.0 for over-long command lines
             nc <- nchar(ff <- paste(shQuote(files), collapse=" "))
-            ## -T is not supported by Solaris nor Heirloom Toolchest's tar
+            ## -T was not supported by Solaris nor Heirloom Toolchest's tar
             if(nc > 1000 &&
                any(grepl("(GNU tar|libarchive)",
                          tryCatch(system(paste(tar, "--version"), intern = TRUE),

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} or \option{-P} to be passed to an external
-    \command{tar} program.}
+    flags such as \option{-p}, \option{-P} or \option{-k} to be passed
+    to an external \command{tar} program.}
 
   \item{verbose}{logical: if true echo the command used for an external
     \command{tar} program.}
@@ -112,36 +112,36 @@ untar(tarfile, files = NULL, list = FALSE, exdir = ".",
       compression.
 
       On a Unix-alike, \command{configure} will set environment variable
-      \env{TAR}, preferring GNU tar if found.}
+      \env{TAR}, preferring GNU tar if found as \command{gtar} or
+      \command{gnutar}.}
 
     %% bsdtar had it in FreeBSB 5.3 (2004)
-    \item{\code{bsdtar}:}{macOS 10.6 and later (and FreeBSD and some
-      other OSes) have a \command{tar} from the \I{libarchive} project
-      which detects known-to-it forms of compression automagically.
-      However, this may rely on an external command being available: macOS
-      has a tar which knows about \code{zstd} compression, but relies
-      on a \command{zstd} command which it does not supply.
+    \item{\code{bsdtar}:}{macOS 10.6 and later (and FreeBSD, NetBSD >= 9
+      and some other OSes) have a \command{tar} from the \I{libarchive}
+      project which detects known-to-it forms of compression
+      automagically.  However, this may rely on an external command
+      being available: macOS has a tar which knows about \code{zstd}
+      compression, but relies on a \command{zstd} command which it does
+      not supply.
 
       This added support for \command{xz} in 2019 and for \command{zstd}
       in 2020 (if the appropriate library or external program is
       available).
-    }
 
-    \item{NetBSD:}{It is undocumented if \I{NetBSD}'s \command{tar} can
-      detect compression automagically: for versions before 8 the flag
-      for \command{xz} compression was \option{--xz} not \option{-J}.
-      So \code{support_old_tars = TRUE} is recommended (or use
-      \command{bsdtar} if installed).}
+      Recent versions of Windows supply a build of \code{bsdtar} as
+      \code{tar.exe}, but with compiled-in support only for \code{gzip}
+      compresssion.
+    }
 
     %% https://news.ycombinator.com/item?id=10722697
     \item{OpenBSD:}{\I{OpenBSD}'s \command{tar} does not detect compression
       automagically.  It has no support for \command{xz} beyond reporting
       that the file is \command{xz}-compressed.  So \code{support_old_tars
 	= TRUE} is recommended.}
 
-    \item{Heirloom Toolchest:}{This \command{tar} does automagically
-      detect \command{gzip} and \command{bzip2} compression (undocumented)
-      but had no support for \command{xz} nor \command{zstd} compression.}
+    %% \item{Heirloom Toolchest:}{This \command{tar} does automagically
+    %%   detect \command{gzip} and \command{bzip2} compression (undocumented)
+    %%   but had no support for \command{xz} nor \command{zstd} compression.}
 
     \item{Older support:}{Environment variable \env{R_GZIPCMD} gives the
       command to decompress \command{gzip} files, and
@@ -151,8 +151,8 @@ untar(tarfile, files = NULL, list = FALSE, exdir = ".",
       decompression is expected to fail.}
   }
 
-  Arguments \code{compressed}, \code{extras} and \code{verbose} are only
-  used when an external \command{tar} is used.
+  Arguments \code{compressed} and \code{verbose} are only used for an
+  external \command{tar}.
 
   Some external \command{tar} commands will detect some of
   \command{lrzip}, \command{lzma}, \command{lz4} and \command{lzop}
@@ -174,12 +174,11 @@ untar(tarfile, files = NULL, list = FALSE, exdir = ".",
   handle files compressed by any of the methods that function can
   handle: at least \command{compress}, \command{gzip}, \command{bzip2},
   \command{xz} and \command{zstd} compression, and some types of
-  \command{lzma} compression.  It does not guard against restoring
-  absolute file paths, as some \command{tar} implementations do.  It
-  will create the parent directories for directories or files in the
-  archive if necessary.  It handles the \I{USTAR}/POSIX, GNU and
-  \command{pax} ways of handling file paths of more than 100 bytes, and
-  the GNU way of handling link targets of more than 100 bytes.
+  \command{lzma} compression.  It will create the parent directories for
+  directories or files in the archive if necessary.  It handles the
+  \I{USTAR}/POSIX, GNU and \command{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 \preformatted{    unsupported entry type 'x'}
@@ -206,7 +205,12 @@ untar(tarfile, files = NULL, list = FALSE, exdir = ".",
   \command{bsdtar} remove the leading slash on absolute filepaths:
   specify \code{extras = "-P"} to override this. \command{bsdtar}
   refuses to extract paths containing \code{".."}  with the same
-  workaround.
+  workaround.  The internal implementation removes leading slashes (with
+  a warning) and stops with an error for paths starting with \code{"~"}
+  or containing \code{".."}.
+  
+  Extracted files will overwrite any existing file unless flag \option{-k}
+  is included in \code{extras}.
 }
 
 \value{