vendor/tar/src/builder.rs

   1 use std::borrow::Cow;
   2 use std::fs;
   3 use std::io;
   4 use std::io::prelude::*;
   5 use std::path::Path;
   6
   7 use crate::header::{bytes2path, path2bytes, HeaderMode};
   8 use crate::{other, EntryType, Header};
   9
  10 /// A structure for building archives
  11 ///
  12 /// This structure has methods for building up an archive from scratch into any
  13 /// arbitrary writer.
  14 pub struct Builder<W: Write> {
  15     mode: HeaderMode,
  16     follow: bool,
  17     finished: bool,
  18     obj: Option<W>,
  19 }
  20
  21 impl<W: Write> Builder<W> {
  22     /// Create a new archive builder with the underlying object as the
  23     /// destination of all data written. The builder will use
  24     /// `HeaderMode::Complete` by default.
  25     pub fn new(obj: W) -> Builder<W> {
  26         Builder {
  27             mode: HeaderMode::Complete,
  28             follow: true,
  29             finished: false,
  30             obj: Some(obj),
  31         }
  32     }
  33
  34     /// Changes the HeaderMode that will be used when reading fs Metadata for
  35     /// methods that implicitly read metadata for an input Path. Notably, this
  36     /// does _not_ apply to `append(Header)`.
  37     pub fn mode(&mut self, mode: HeaderMode) {
  38         self.mode = mode;
  39     }
  40
  41     /// Follow symlinks, archiving the contents of the file they point to rather
  42     /// than adding a symlink to the archive. Defaults to true.
  43     pub fn follow_symlinks(&mut self, follow: bool) {
  44         self.follow = follow;
  45     }
  46
  47     /// Gets shared reference to the underlying object.
  48     pub fn get_ref(&self) -> &W {
  49         self.obj.as_ref().unwrap()
  50     }
  51
  52     /// Gets mutable reference to the underlying object.
  53     ///
  54     /// Note that care must be taken while writing to the underlying
  55     /// object. But, e.g. `get_mut().flush()` is clamed to be safe and
  56     /// useful in the situations when one needs to be ensured that
  57     /// tar entry was flushed to the disk.
  58     pub fn get_mut(&mut self) -> &mut W {
  59         self.obj.as_mut().unwrap()
  60     }
  61
  62     /// Unwrap this archive, returning the underlying object.
  63     ///
  64     /// This function will finish writing the archive if the `finish` function
  65     /// hasn't yet been called, returning any I/O error which happens during
  66     /// that operation.
  67     pub fn into_inner(mut self) -> io::Result<W> {
  68         if !self.finished {
  69             self.finish()?;
  70         }
  71         Ok(self.obj.take().unwrap())
  72     }
  73
  74     /// Adds a new entry to this archive.
  75     ///
  76     /// This function will append the header specified, followed by contents of
  77     /// the stream specified by `data`. To produce a valid archive the `size`
  78     /// field of `header` must be the same as the length of the stream that's
  79     /// being written. Additionally the checksum for the header should have been
  80     /// set via the `set_cksum` method.
  81     ///
  82     /// Note that this will not attempt to seek the archive to a valid position,
  83     /// so if the archive is in the middle of a read or some other similar
  84     /// operation then this may corrupt the archive.
  85     ///
  86     /// Also note that after all entries have been written to an archive the
  87     /// `finish` function needs to be called to finish writing the archive.
  88     ///
  89     /// # Errors
  90     ///
  91     /// This function will return an error for any intermittent I/O error which
  92     /// occurs when either reading or writing.
  93     ///
  94     /// # Examples
  95     ///
  96     /// ```
  97     /// use tar::{Builder, Header};
  98     ///
  99     /// let mut header = Header::new_gnu();
 100     /// header.set_path("foo").unwrap();
 101     /// header.set_size(4);
 102     /// header.set_cksum();
 103     ///
 104     /// let mut data: &[u8] = &[1, 2, 3, 4];
 105     ///
 106     /// let mut ar = Builder::new(Vec::new());
 107     /// ar.append(&header, data).unwrap();
 108     /// let data = ar.into_inner().unwrap();
 109     /// ```
 110     pub fn append<R: Read>(&mut self, header: &Header, mut data: R) -> io::Result<()> {
 111         append(self.get_mut(), header, &mut data)
 112     }
 113
 114     /// Adds a new entry to this archive with the specified path.
 115     ///
 116     /// This function will set the specified path in the given header, which may
 117     /// require appending a GNU long-name extension entry to the archive first.
 118     /// The checksum for the header will be automatically updated via the
 119     /// `set_cksum` method after setting the path. No other metadata in the
 120     /// header will be modified.
 121     ///
 122     /// Then it will append the header, followed by contents of the stream
 123     /// specified by `data`. To produce a valid archive the `size` field of
 124     /// `header` must be the same as the length of the stream that's being
 125     /// written.
 126     ///
 127     /// Note that this will not attempt to seek the archive to a valid position,
 128     /// so if the archive is in the middle of a read or some other similar
 129     /// operation then this may corrupt the archive.
 130     ///
 131     /// Also note that after all entries have been written to an archive the
 132     /// `finish` function needs to be called to finish writing the archive.
 133     ///
 134     /// # Errors
 135     ///
 136     /// This function will return an error for any intermittent I/O error which
 137     /// occurs when either reading or writing.
 138     ///
 139     /// # Examples
 140     ///
 141     /// ```
 142     /// use tar::{Builder, Header};
 143     ///
 144     /// let mut header = Header::new_gnu();
 145     /// header.set_size(4);
 146     /// header.set_cksum();
 147     ///
 148     /// let mut data: &[u8] = &[1, 2, 3, 4];
 149     ///
 150     /// let mut ar = Builder::new(Vec::new());
 151     /// ar.append_data(&mut header, "really/long/path/to/foo", data).unwrap();
 152     /// let data = ar.into_inner().unwrap();
 153     /// ```
 154     pub fn append_data<P: AsRef<Path>, R: Read>(
 155         &mut self,
 156         header: &mut Header,
 157         path: P,
 158         data: R,
 159     ) -> io::Result<()> {
 160         prepare_header_path(self.get_mut(), header, path.as_ref())?;
 161         header.set_cksum();
 162         self.append(&header, data)
 163     }
 164
 165     /// Adds a file on the local filesystem to this archive.
 166     ///
 167     /// This function will open the file specified by `path` and insert the file
 168     /// into the archive with the appropriate metadata set, returning any I/O
 169     /// error which occurs while writing. The path name for the file inside of
 170     /// this archive will be the same as `path`, and it is required that the
 171     /// path is a relative path.
 172     ///
 173     /// Note that this will not attempt to seek the archive to a valid position,
 174     /// so if the archive is in the middle of a read or some other similar
 175     /// operation then this may corrupt the archive.
 176     ///
 177     /// Also note that after all files have been written to an archive the
 178     /// `finish` function needs to be called to finish writing the archive.
 179     ///
 180     /// # Examples
 181     ///
 182     /// ```no_run
 183     /// use tar::Builder;
 184     ///
 185     /// let mut ar = Builder::new(Vec::new());
 186     ///
 187     /// ar.append_path("foo/bar.txt").unwrap();
 188     /// ```
 189     pub fn append_path<P: AsRef<Path>>(&mut self, path: P) -> io::Result<()> {
 190         let mode = self.mode.clone();
 191         let follow = self.follow;
 192         append_path_with_name(self.get_mut(), path.as_ref(), None, mode, follow)
 193     }
 194
 195     /// Adds a file on the local filesystem to this archive under another name.
 196     ///
 197     /// This function will open the file specified by `path` and insert the file
 198     /// into the archive as `name` with appropriate metadata set, returning any
 199     /// I/O error which occurs while writing. The path name for the file inside
 200     /// of this archive will be `name` and `path` is required to be a relative
 201     /// path.
 202     ///
 203     /// Note that this will not attempt to seek the archive to a valid position,
 204     /// so if the archive is in the middle of a read or some other similar
 205     /// operation then this may corrupt the archive.
 206     ///
 207     /// Also note that after all files have been written to an archive the
 208     /// `finish` function needs to be called to finish writing the archive.
 209     ///
 210     /// # Examples
 211     ///
 212     /// ```no_run
 213     /// use tar::Builder;
 214     ///
 215     /// let mut ar = Builder::new(Vec::new());
 216     ///
 217     /// // Insert the local file "foo/bar.txt" in the archive but with the name
 218     /// // "bar/foo.txt".
 219     /// ar.append_path_with_name("foo/bar.txt", "bar/foo.txt").unwrap();
 220     /// ```
 221     pub fn append_path_with_name<P: AsRef<Path>, N: AsRef<Path>>(
 222         &mut self,
 223         path: P,
 224         name: N,
 225     ) -> io::Result<()> {
 226         let mode = self.mode.clone();
 227         let follow = self.follow;
 228         append_path_with_name(
 229             self.get_mut(),
 230             path.as_ref(),
 231             Some(name.as_ref()),
 232             mode,
 233             follow,
 234         )
 235     }
 236
 237     /// Adds a file to this archive with the given path as the name of the file
 238     /// in the archive.
 239     ///
 240     /// This will use the metadata of `file` to populate a `Header`, and it will
 241     /// then append the file to the archive with the name `path`.
 242     ///
 243     /// Note that this will not attempt to seek the archive to a valid position,
 244     /// so if the archive is in the middle of a read or some other similar
 245     /// operation then this may corrupt the archive.
 246     ///
 247     /// Also note that after all files have been written to an archive the
 248     /// `finish` function needs to be called to finish writing the archive.
 249     ///
 250     /// # Examples
 251     ///
 252     /// ```no_run
 253     /// use std::fs::File;
 254     /// use tar::Builder;
 255     ///
 256     /// let mut ar = Builder::new(Vec::new());
 257     ///
 258     /// // Open the file at one location, but insert it into the archive with a
 259     /// // different name.
 260     /// let mut f = File::open("foo/bar/baz.txt").unwrap();
 261     /// ar.append_file("bar/baz.txt", &mut f).unwrap();
 262     /// ```
 263     pub fn append_file<P: AsRef<Path>>(&mut self, path: P, file: &mut fs::File) -> io::Result<()> {
 264         let mode = self.mode.clone();
 265         append_file(self.get_mut(), path.as_ref(), file, mode)
 266     }
 267
 268     /// Adds a directory to this archive with the given path as the name of the
 269     /// directory in the archive.
 270     ///
 271     /// This will use `stat` to populate a `Header`, and it will then append the
 272     /// directory to the archive with the name `path`.
 273     ///
 274     /// Note that this will not attempt to seek the archive to a valid position,
 275     /// so if the archive is in the middle of a read or some other similar
 276     /// operation then this may corrupt the archive.
 277     ///
 278     /// Also note that after all files have been written to an archive the
 279     /// `finish` function needs to be called to finish writing the archive.
 280     ///
 281     /// # Examples
 282     ///
 283     /// ```
 284     /// use std::fs;
 285     /// use tar::Builder;
 286     ///
 287     /// let mut ar = Builder::new(Vec::new());
 288     ///
 289     /// // Use the directory at one location, but insert it into the archive
 290     /// // with a different name.
 291     /// ar.append_dir("bardir", ".").unwrap();
 292     /// ```
 293     pub fn append_dir<P, Q>(&mut self, path: P, src_path: Q) -> io::Result<()>
 294     where
 295         P: AsRef<Path>,
 296         Q: AsRef<Path>,
 297     {
 298         let mode = self.mode.clone();
 299         append_dir(self.get_mut(), path.as_ref(), src_path.as_ref(), mode)
 300     }
 301
 302     /// Adds a directory and all of its contents (recursively) to this archive
 303     /// with the given path as the name of the directory in the archive.
 304     ///
 305     /// Note that this will not attempt to seek the archive to a valid position,
 306     /// so if the archive is in the middle of a read or some other similar
 307     /// operation then this may corrupt the archive.
 308     ///
 309     /// Also note that after all files have been written to an archive the
 310     /// `finish` function needs to be called to finish writing the archive.
 311     ///
 312     /// # Examples
 313     ///
 314     /// ```
 315     /// use std::fs;
 316     /// use tar::Builder;
 317     ///
 318     /// let mut ar = Builder::new(Vec::new());
 319     ///
 320     /// // Use the directory at one location, but insert it into the archive
 321     /// // with a different name.
 322     /// ar.append_dir_all("bardir", ".").unwrap();
 323     /// ```
 324     pub fn append_dir_all<P, Q>(&mut self, path: P, src_path: Q) -> io::Result<()>
 325     where
 326         P: AsRef<Path>,
 327         Q: AsRef<Path>,
 328     {
 329         let mode = self.mode.clone();
 330         let follow = self.follow;
 331         append_dir_all(
 332             self.get_mut(),
 333             path.as_ref(),
 334             src_path.as_ref(),
 335             mode,
 336             follow,
 337         )
 338     }
 339
 340     /// Finish writing this archive, emitting the termination sections.
 341     ///
 342     /// This function should only be called when the archive has been written
 343     /// entirely and if an I/O error happens the underlying object still needs
 344     /// to be acquired.
 345     ///
 346     /// In most situations the `into_inner` method should be preferred.
 347     pub fn finish(&mut self) -> io::Result<()> {
 348         if self.finished {
 349             return Ok(());
 350         }
 351         self.finished = true;
 352         self.get_mut().write_all(&[0; 1024])
 353     }
 354 }
 355
 356 fn append(mut dst: &mut Write, header: &Header, mut data: &mut Read) -> io::Result<()> {
 357     dst.write_all(header.as_bytes())?;
 358     let len = io::copy(&mut data, &mut dst)?;
 359
 360     // Pad with zeros if necessary.
 361     let buf = [0; 512];
 362     let remaining = 512 - (len % 512);
 363     if remaining < 512 {
 364         dst.write_all(&buf[..remaining as usize])?;
 365     }
 366
 367     Ok(())
 368 }
 369
 370 fn append_path_with_name(
 371     dst: &mut Write,
 372     path: &Path,
 373     name: Option<&Path>,
 374     mode: HeaderMode,
 375     follow: bool,
 376 ) -> io::Result<()> {
 377     let stat = if follow {
 378         fs::metadata(path).map_err(|err| {
 379             io::Error::new(
 380                 err.kind(),
 381                 format!("{} when getting metadata for {}", err, path.display()),
 382             )
 383         })?
 384     } else {
 385         fs::symlink_metadata(path).map_err(|err| {
 386             io::Error::new(
 387                 err.kind(),
 388                 format!("{} when getting metadata for {}", err, path.display()),
 389             )
 390         })?
 391     };
 392     let ar_name = name.unwrap_or(path);
 393     if stat.is_file() {
 394         append_fs(dst, ar_name, &stat, &mut fs::File::open(path)?, mode, None)
 395     } else if stat.is_dir() {
 396         append_fs(dst, ar_name, &stat, &mut io::empty(), mode, None)
 397     } else if stat.file_type().is_symlink() {
 398         let link_name = fs::read_link(path)?;
 399         append_fs(
 400             dst,
 401             ar_name,
 402             &stat,
 403             &mut io::empty(),
 404             mode,
 405             Some(&link_name),
 406         )
 407     } else {
 408         Err(other(&format!("{} has unknown file type", path.display())))
 409     }
 410 }
 411
 412 fn append_file(
 413     dst: &mut Write,
 414     path: &Path,
 415     file: &mut fs::File,
 416     mode: HeaderMode,
 417 ) -> io::Result<()> {
 418     let stat = file.metadata()?;
 419     append_fs(dst, path, &stat, file, mode, None)
 420 }
 421
 422 fn append_dir(dst: &mut Write, path: &Path, src_path: &Path, mode: HeaderMode) -> io::Result<()> {
 423     let stat = fs::metadata(src_path)?;
 424     append_fs(dst, path, &stat, &mut io::empty(), mode, None)
 425 }
 426
 427 fn prepare_header(size: u64, entry_type: u8) -> Header {
 428     let mut header = Header::new_gnu();
 429     let name = b"././@LongLink";
 430     header.as_gnu_mut().unwrap().name[..name.len()].clone_from_slice(&name[..]);
 431     header.set_mode(0o644);
 432     header.set_uid(0);
 433     header.set_gid(0);
 434     header.set_mtime(0);
 435     // + 1 to be compliant with GNU tar
 436     header.set_size(size + 1);
 437     header.set_entry_type(EntryType::new(entry_type));
 438     header.set_cksum();
 439     header
 440 }
 441
 442 fn prepare_header_path(dst: &mut Write, header: &mut Header, path: &Path) -> io::Result<()> {
 443     // Try to encode the path directly in the header, but if it ends up not
 444     // working (probably because it's too long) then try to use the GNU-specific
 445     // long name extension by emitting an entry which indicates that it's the
 446     // filename.
 447     if let Err(e) = header.set_path(path) {
 448         let data = path2bytes(&path)?;
 449         let max = header.as_old().name.len();
 450         //  Since e isn't specific enough to let us know the path is indeed too
 451         //  long, verify it first before using the extension.
 452         if data.len() < max {
 453             return Err(e);
 454         }
 455         let header2 = prepare_header(data.len() as u64, b'L');
 456         // null-terminated string
 457         let mut data2 = data.chain(io::repeat(0).take(1));
 458         append(dst, &header2, &mut data2)?;
 459         // Truncate the path to store in the header we're about to emit to
 460         // ensure we've got something at least mentioned.
 461         let path = bytes2path(Cow::Borrowed(&data[..max]))?;
 462         header.set_path(&path)?;
 463     }
 464     Ok(())
 465 }
 466
 467 fn prepare_header_link(dst: &mut Write, header: &mut Header, link_name: &Path) -> io::Result<()> {
 468     // Same as previous function but for linkname
 469     if let Err(e) = header.set_link_name(&link_name) {
 470         let data = path2bytes(&link_name)?;
 471         if data.len() < header.as_old().linkname.len() {
 472             return Err(e);
 473         }
 474         let header2 = prepare_header(data.len() as u64, b'K');
 475         let mut data2 = data.chain(io::repeat(0).take(1));
 476         append(dst, &header2, &mut data2)?;
 477     }
 478     Ok(())
 479 }
 480
 481 fn append_fs(
 482     dst: &mut Write,
 483     path: &Path,
 484     meta: &fs::Metadata,
 485     read: &mut Read,
 486     mode: HeaderMode,
 487     link_name: Option<&Path>,
 488 ) -> io::Result<()> {
 489     let mut header = Header::new_gnu();
 490
 491     prepare_header_path(dst, &mut header, path)?;
 492     header.set_metadata_in_mode(meta, mode);
 493     if let Some(link_name) = link_name {
 494         prepare_header_link(dst, &mut header, link_name)?;
 495     }
 496     header.set_cksum();
 497     append(dst, &header, read)
 498 }
 499
 500 fn append_dir_all(
 501     dst: &mut Write,
 502     path: &Path,
 503     src_path: &Path,
 504     mode: HeaderMode,
 505     follow: bool,
 506 ) -> io::Result<()> {
 507     let mut stack = vec![(src_path.to_path_buf(), true, false)];
 508     while let Some((src, is_dir, is_symlink)) = stack.pop() {
 509         let dest = path.join(src.strip_prefix(&src_path).unwrap());
 510         // In case of a symlink pointing to a directory, is_dir is false, but src.is_dir() will return true
 511         if is_dir || (is_symlink && follow && src.is_dir()) {
 512             for entry in fs::read_dir(&src)? {
 513                 let entry = entry?;
 514                 let file_type = entry.file_type()?;
 515                 stack.push((entry.path(), file_type.is_dir(), file_type.is_symlink()));
 516             }
 517             if dest != Path::new("") {
 518                 append_dir(dst, &dest, &src, mode)?;
 519             }
 520         } else if !follow && is_symlink {
 521             let stat = fs::symlink_metadata(&src)?;
 522             let link_name = fs::read_link(&src)?;
 523             append_fs(dst, &dest, &stat, &mut io::empty(), mode, Some(&link_name))?;
 524         } else {
 525             append_file(dst, &dest, &mut fs::File::open(src)?, mode)?;
 526         }
 527     }
 528     Ok(())
 529 }
 530
 531 impl<W: Write> Drop for Builder<W> {
 532     fn drop(&mut self) {
 533         let _ = self.finish();
 534     }
 535 }