Struct tokio_tar::Builder

source ·
pub struct Builder<W: Write + Unpin + Send> { /* private fields */ }
Expand description

A structure for building archives

This structure has methods for building up an archive from scratch into any arbitrary writer.

Implementations§

source§

impl<W: Write + Unpin + Send + 'static> Builder<W>

source

pub fn new(obj: W) -> Builder<W>

Create a new archive builder with the underlying object as the destination of all data written. The builder will use HeaderMode::Complete by default.

On drop, would write [TERMINATION] into the end of the archive, use skip_termination method to disable this.

source§

impl<W: Write + Unpin + Send> Builder<W>

source

pub fn new_non_terminated(obj: W) -> Builder<W>

Create a new archive builder with the underlying object as the destination of all data written. The builder will use HeaderMode::Complete by default.

The [TERMINATION] symbol would not be written to the archive in the end.

source

pub fn mode(&mut self, mode: HeaderMode)

Changes the HeaderMode that will be used when reading fs Metadata for methods that implicitly read metadata for an input Path. Notably, this does not apply to append(Header).

Follow symlinks, archiving the contents of the file they point to rather than adding a symlink to the archive. Defaults to true.

source

pub fn skip_termination(&mut self)

Skip writing final termination bytes into the archive.

source

pub fn get_ref(&self) -> &W

Gets shared reference to the underlying object.

source

pub fn get_mut(&mut self) -> &mut W

Gets mutable reference to the underlying object.

Note that care must be taken while writing to the underlying object. But, e.g. get_mut().flush() is claimed to be safe and useful in the situations when one needs to be ensured that tar entry was flushed to the disk.

source

pub async fn into_inner(self) -> Result<W>

Unwrap this archive, returning the underlying object.

This function will finish writing the archive if the finish function hasn’t yet been called, returning any I/O error which happens during that operation.

source

pub async fn append<R: Read + Unpin>( &mut self, header: &Header, data: R ) -> Result<()>

Adds a new entry to this archive.

This function will append the header specified, followed by contents of the stream specified by data. To produce a valid archive the size field of header must be the same as the length of the stream that’s being written. Additionally the checksum for the header should have been set via the set_cksum method.

Note that this will not attempt to seek the archive to a valid position, so if the archive is in the middle of a read or some other similar operation then this may corrupt the archive.

Also note that after all entries have been written to an archive the finish function needs to be called to finish writing the archive.

Errors

This function will return an error for any intermittent I/O error which occurs when either reading or writing.

Examples
use tokio_tar::{Builder, Header};

let mut header = Header::new_gnu();
header.set_path("foo")?;
header.set_size(4);
header.set_cksum();

let mut data: &[u8] = &[1, 2, 3, 4];

let mut ar = Builder::new(Vec::new());
ar.append(&header, data).await?;
let data = ar.into_inner().await?;
source

pub async fn append_data<P: AsRef<Path>, R: Read + Unpin>( &mut self, header: &mut Header, path: P, data: R ) -> Result<()>

Adds a new entry to this archive with the specified path.

This function will set the specified path in the given header, which may require appending a GNU long-name extension entry to the archive first. The checksum for the header will be automatically updated via the set_cksum method after setting the path. No other metadata in the header will be modified.

Then it will append the header, followed by contents of the stream specified by data. To produce a valid archive the size field of header must be the same as the length of the stream that’s being written.

Note that this will not attempt to seek the archive to a valid position, so if the archive is in the middle of a read or some other similar operation then this may corrupt the archive.

Also note that after all entries have been written to an archive the finish function needs to be called to finish writing the archive.

Errors

This function will return an error for any intermittent I/O error which occurs when either reading or writing.

Examples
use tokio_tar::{Builder, Header};

let mut header = Header::new_gnu();
header.set_size(4);
header.set_cksum();

let mut data: &[u8] = &[1, 2, 3, 4];

let mut ar = Builder::new(Vec::new());
ar.append_data(&mut header, "really/long/path/to/foo", data).await?;
let data = ar.into_inner().await?;
source

pub async fn append_path<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Adds a file on the local filesystem to this archive.

This function will open the file specified by path and insert the file into the archive with the appropriate metadata set, returning any I/O error which occurs while writing. The path name for the file inside of this archive will be the same as path, and it is required that the path is a relative path.

Note that this will not attempt to seek the archive to a valid position, so if the archive is in the middle of a read or some other similar operation then this may corrupt the archive.

Also note that after all files have been written to an archive the finish function needs to be called to finish writing the archive.

Examples
use tokio_tar::Builder;

let mut ar = Builder::new(Vec::new());

ar.append_path("foo/bar.txt").await?;
source

pub async fn append_path_with_name<P: AsRef<Path>, N: AsRef<Path>>( &mut self, path: P, name: N ) -> Result<()>

Adds a file on the local filesystem to this archive under another name.

This function will open the file specified by path and insert the file into the archive as name with appropriate metadata set, returning any I/O error which occurs while writing. The path name for the file inside of this archive will be name is required to be a relative path.

Note that this will not attempt to seek the archive to a valid position, so if the archive is in the middle of a read or some other similar operation then this may corrupt the archive.

Also note that after all files have been written to an archive the finish function needs to be called to finish writing the archive.

Examples
use tokio_tar::Builder;

let mut ar = Builder::new(Vec::new());

// Insert the local file "foo/bar.txt" in the archive but with the name
// "bar/foo.txt".
ar.append_path_with_name("foo/bar.txt", "bar/foo.txt").await?;
source

pub async fn append_file<P: AsRef<Path>>( &mut self, path: P, file: &mut File ) -> Result<()>

Adds a file to this archive with the given path as the name of the file in the archive.

This will use the metadata of file to populate a Header, and it will then append the file to the archive with the name path.

Note that this will not attempt to seek the archive to a valid position, so if the archive is in the middle of a read or some other similar operation then this may corrupt the archive.

Also note that after all files have been written to an archive the finish function needs to be called to finish writing the archive.

Examples
use tokio::fs::File;
use tokio_tar::Builder;

let mut ar = Builder::new(Vec::new());

// Open the file at one location, but insert it into the archive with a
// different name.
let mut f = File::open("foo/bar/baz.txt").await?;
ar.append_file("bar/baz.txt", &mut f).await?;
source

pub async fn append_dir<P, Q>(&mut self, path: P, src_path: Q) -> Result<()>where P: AsRef<Path>, Q: AsRef<Path>,

Adds a directory to this archive with the given path as the name of the directory in the archive.

This will use stat to populate a Header, and it will then append the directory to the archive with the name path.

Note that this will not attempt to seek the archive to a valid position, so if the archive is in the middle of a read or some other similar operation then this may corrupt the archive.

Also note that after all files have been written to an archive the finish function needs to be called to finish writing the archive.

Examples
use tokio::fs;
use tokio_tar::Builder;

let mut ar = Builder::new(Vec::new());

// Use the directory at one location, but insert it into the archive
// with a different name.
ar.append_dir("bardir", ".").await?;
source

pub async fn append_dir_all<P, Q>(&mut self, path: P, src_path: Q) -> Result<()>where P: AsRef<Path>, Q: AsRef<Path>,

Adds a directory and all of its contents (recursively) to this archive with the given path as the name of the directory in the archive.

Note that this will not attempt to seek the archive to a valid position, so if the archive is in the middle of a read or some other similar operation then this may corrupt the archive.

Also note that after all files have been written to an archive the finish function needs to be called to finish writing the archive.

Examples
use tokio::fs;
use tokio_tar::Builder;

let mut ar = Builder::new(Vec::new());

// Use the directory at one location, but insert it into the archive
// with a different name.
ar.append_dir_all("bardir", ".").await?;
source

pub async fn finish(&mut self) -> Result<()>

Finish writing this archive, emitting the termination sections.

This function should only be called when the archive has been written entirely and if an I/O error happens the underlying object still needs to be acquired.

In most situations the into_inner method should be preferred.

Trait Implementations§

source§

impl<W: Write + Unpin + Send> Drop for Builder<W>

source§

fn drop(&mut self)

Executes the destructor for this type. Read more

Auto Trait Implementations§

§

impl<W> !RefUnwindSafe for Builder<W>

§

impl<W> Send for Builder<W>

§

impl<W> Sync for Builder<W>where W: Sync,

§

impl<W> Unpin for Builder<W>

§

impl<W> !UnwindSafe for Builder<W>

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.