The R Project SVN R

Rev

Rev 75603 | Rev 85935 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 75603 Rev 76022
Line 1... Line 1...
1 
% File src/library/utils/man/untar.Rd
 1 
% File src/library/utils/man/untar.Rd
2 
% Part of the R package, https://www.R-project.org
 2 
% Part of the R package, https://www.R-project.org
3 
% Copyright 2009-2018 R Core Team
 3 
% Copyright 2009-2019 R Core Team
4 
% Distributed under GPL 2 or later
 4 
% Distributed under GPL 2 or later
5 
 
 5 
 
6 
\name{untar}
 6 
\name{untar}
7 
\alias{untar}
 7 
\alias{untar}
8 
\title{
 8 
\title{
Line 36... Line 36...
36 
    \command{tar -xf}).}
 36 
    \command{tar -xf}).}
37 
 
 37 
 
38 
  \item{exdir}{The directory to extract files to (the equivalent of
 38 
  \item{exdir}{The directory to extract files to (the equivalent of
39 
    \command{tar -C}).  It will be created if necessary.}
 39 
    \command{tar -C}).  It will be created if necessary.}
40 
 
 40 
 
41 
  \item{compressed}{(Deprecated in favour of auto-detection.)  Logical
 41 
  \item{compressed}{(Deprecated in favour of auto-detection, used only
42 
    or character string, used only for an external \command{tar}
 42 
    for an external \command{tar} command.)  Logical or character
43 
    command.  Values \code{"gzip"}, \code{"bzip2"} and \code{"xz"}
 43 
    string.  Values \code{"gzip"}, \code{"bzip2"} and \code{"xz"} select
44 
    select that form of compression (and may be abbreviated to the first
 44 
    that form of compression (and may be abbreviated to the first
45 
    letter).  \code{TRUE} indicates \command{gzip} compression,
 45 
    letter).  \code{TRUE} indicates \command{gzip} compression,
46 
    \code{FALSE} no known compression, and \code{NA} (the default)
 46 
    \code{FALSE} no known compression, and \code{NA} (the default)
47 
    indicates that the type is inferred from the file header.
 47 
    indicates that the type is to be inferred from the file header.
48 
 
 48 
 
49 
    The external command may ignore the selected compression type but
 49 
    The external command may ignore the selected compression type but
50 
    detect a type automagically.
 50 
    detect a type automagically.
51 
  }
 51 
  }
52 
 
 52 
 
Line 70... Line 70...
70
70
71 
  %% even RHEL6 had GNU tar 1.23, Ububtu 14.04 has 1.27
 71 
  %% even RHEL6 had GNU tar 1.23, Ububtu 14.04 has 1.27
72 
  %% macOS has bsdtar from 2010: this supports xz but does not docuemnt it.
 72 
  %% macOS has bsdtar from 2010: this supports xz but does not docuemnt it.
73 
  %% bsdtar had lzma/xz supoort before April 2009 when it added
 73 
  %% bsdtar had lzma/xz supoort before April 2009 when it added
74 
  %% support for command-line unxz etc, not just libraries.
 74 
  %% support for command-line unxz etc, not just libraries.
75 
  \item{support_old_tars}{logical.  If true, the external \command{tar}
 75 
  \item{support_old_tars}{logical.  If false (the default), the external
76 
    command is assumed to be able handle compressed tarfiles and if
 76 
    \command{tar} command is assumed to be able handle compressed
77 
    \code{compressed} does not specify it, to automagically detect the
 77 
    tarfiles and if \code{compressed} does not specify it, to
78 
    type of compression.  (The major implementations have done so since
 78 
    automagically detect the type of compression.  (The major
79 
    2009; for GNU \command{tar} since version 1.22.)
 79 
    implementations have done so since 2009; for GNU \command{tar} since
- 
 
 80 
    version 1.22.)
80 
 
 81 
 
81 
    Otherwise the \R code calls an appropriate decompressor and pipes
 82 
    If true, the \R code calls an appropriate decompressor and pipes
82 
    the output to \command{tar}, for \code{compressed = NA} examining
 83 
    the output to \command{tar}, for \code{compressed = NA} examining
83 
    the tarfile header to determine the type of compression.
 84 
    the tarfile header to determine the type of compression.
84 
  }
 85 
  }
85 
 
 86 
 
86 
  \item{tar}{character string: the path to the command to be used or
 87 
  \item{tar}{character string: the path to the command to be used or
Line 141... Line 142...
141 
  }
 142 
  }
142 
 
 143 
 
143 
  Arguments \code{compressed}, \code{extras} and \code{verbose} are only
 144 
  Arguments \code{compressed}, \code{extras} and \code{verbose} are only
144 
  used when an external \command{tar} is used.
 145 
  used when an external \command{tar} is used.
145 
 
 146 
 
146 
  Some external \command{tar} commands will detect \command{lrzip},
 147 
  Some external \command{tar} commands will detect some of
147 
  \command{lzma}, \command{lz4}, \command{lzop} or \command{zstd}
 148 
  \command{lrzip}, \command{lzma}, \command{lz4}, \command{lzop} and
148 
  compression in addition to \command{gzip}, \command{bzip2} and
 149 
  \command{zstd} compression in addition to \command{gzip},
149 
  \command{xz}.  (For some external \command{tar} commands, compressed
 150 
  \command{bzip2} and \command{xz}.  (For some external \command{tar}
150 
  tarfiles can only be read if the appropriate utility program is
 151 
  commands, compressed tarfiles can only be read if the appropriate
151 
  available.)  For GNU \command{tar}, further (de)compression programs
 152 
  utility program is available.)  For GNU \command{tar}, further
152 
  can be specified by e.g.\sspace{}\code{extras = "-I lz4"}.
 153 
  (de)compression programs can be specified by e.g.\sspace{}\code{extras
153 
  For \command{bsdtar} this could be
 154 
  = "-I lz4"}.  For \command{bsdtar} this could be \code{extras =
154 
  \code{extras = "--use-compress-program lz4"}.
 155 
  "--use-compress-program lz4"}.  Most commands will detect (the
155 
  Most commands will detect (the nowadays rarely seen) \file{.tar.Z}
 156 
  nowadays rarely seen) \file{.tar.Z} archives compressed by
156 
  archives compressed by \code{compress}.
 157 
  \code{compress}.
157
158
158 
  The internal implementation restores symbolic links as links on a
 159 
  The internal implementation restores symbolic links as links on a
159 
  Unix-alike, and as file copies on Windows (which works only for
 160 
  Unix-alike, and as file copies on Windows (which works only for
160 
  existing files, not for directories), and hard links as links.  If the
 161 
  existing files, not for directories), and hard links as links.  If the
161 
  linking operation fails (as it may on a FAT file system), a file copy
 162 
  linking operation fails (as it may on a FAT file system), a file copy
Line 164... Line 165...
164 
  handle: at least \command{compress}, \command{gzip}, \command{bzip2}
 165 
  handle: at least \command{compress}, \command{gzip}, \command{bzip2}
165 
  and \command{xz} compression, and some types of \command{lzma}
 166 
  and \command{xz} compression, and some types of \command{lzma}
166 
  compression.  It does not guard against restoring absolute file paths,
 167 
  compression.  It does not guard against restoring absolute file paths,
167 
  as some \command{tar} implementations do.  It will create the parent
 168 
  as some \command{tar} implementations do.  It will create the parent
168 
  directories for directories or files in the archive if necessary.  It
 169 
  directories for directories or files in the archive if necessary.  It
169 
  handles the standard (USTAR/POSIX), GNU and \command{pax} ways of
 170 
  handles the USTAR/POSIX, GNU and \command{pax} ways of handling file
170 
  handling file paths of more than 100 bytes, and the GNU way of
 171 
  paths of more than 100 bytes, and the GNU way of handling link targets
171 
  handling link targets of more than 100 bytes.
 172 
  of more than 100 bytes.
172 
 
 173 
 
173 
  You may see warnings from the internal implementation such
 174 
  You may see warnings from the internal implementation such
174 
  as \preformatted{    unsupported entry type 'x'}
 175 
  as \preformatted{    unsupported entry type 'x'}
175 
  This often indicates an invalid archive: entry types \code{"A-Z"} are
 176 
  This often indicates an invalid archive: entry types \code{"A-Z"} are
176 
  allowed as extensions, but other types are reserved.  The only thing
 177 
  allowed as extensions, but other types are reserved.  The only thing
Line 178... Line 179...
178 
  handles it, and look carefully at the resulting files.  There may also
 179 
  handles it, and look carefully at the resulting files.  There may also
179 
  be the warning \preformatted{    using pax extended headers}
 180 
  be the warning \preformatted{    using pax extended headers}
180 
  This indicates that additional information may have been discarded,
 181 
  This indicates that additional information may have been discarded,
181 
  such as ACLs, encodings \dots.
 182 
  such as ACLs, encodings \dots.
182 
 
 183 
 
183 
  The standards only support ASCII filenames (indeed, only alphanumeric
 184 
  The former standards only supported ASCII filenames (indeed, only
184 
  plus period, underscore and hyphen).  \code{untar} makes no attempt to
 185 
  alphanumeric plus period, underscore and hyphen).  \code{untar} makes
185 
  map filenames to those acceptable on the current system, and treats
 186 
  no attempt to map filenames to those acceptable on the current system,
186 
  the filenames in the archive as applicable without any re-encoding in
 187 
  and treats the filenames in the archive as applicable without any
187 
  the current locale.
 188 
  re-encoding in the current locale.
188 
 
 189 
 
189 
  The internal implementation does not special-case \sQuote{resource
 190 
  The internal implementation does not special-case \sQuote{resource
190 
  forks} in macOS: that system's \command{tar} command does. This may
 191 
  forks} in macOS: that system's \command{tar} command does. This may
191 
  lead to unexpected files with names with prefix \file{._}.
 192 
  lead to unexpected files with names with prefix \file{._}.
192 
}
 193 
}