Struct tar::Builder [−][src]
pub struct Builder<W: Write> { /* fields omitted */ }
Expand description
A structure for building archives
This structure has methods for building up an archive from scratch into any arbitrary writer.
Implementations
Create a new archive builder with the underlying object as the
destination of all data written. The builder will use
HeaderMode::Complete
by default.
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.
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.
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.
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 tar::{Builder, Header};
let mut header = Header::new_gnu();
header.set_path("foo").unwrap();
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).unwrap();
let data = ar.into_inner().unwrap();
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 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).unwrap();
let data = ar.into_inner().unwrap();
Adds a new link (symbolic or hard) entry to this archive with the specified path and target.
This function is similar to Self::append_data
which supports long filenames,
but also supports long link targets using GNU extensions if necessary.
You must set the entry type to either EntryType::Link
or EntryType::Symlink
.
The set_cksum
method will be invoked after setting the path. No other metadata in the
header will be modified.
If you are intending to use GNU extensions, you must use this method over calling
Header::set_link_name
because that function will fail on long links.
Similar constraints around the position of the archive and completion
apply as with Self::append_data
.
Errors
This function will return an error for any intermittent I/O error which occurs when either reading or writing.
Examples
use tar::{Builder, Header, EntryType};
let mut ar = Builder::new(Vec::new());
let mut header = Header::new_gnu();
header.set_username("foo");
header.set_entry_type(EntryType::Symlink);
header.set_size(0);
ar.append_link(&mut header, "really/long/path/to/foo", "other/really/long/target").unwrap();
let data = ar.into_inner().unwrap();
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 tar::Builder;
let mut ar = Builder::new(Vec::new());
ar.append_path("foo/bar.txt").unwrap();
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.
Note if the path
is a directory. This will just add an entry to the archive,
rather than contents of the directory.
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 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").unwrap();
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 std::fs::File;
use 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").unwrap();
ar.append_file("bar/baz.txt", &mut f).unwrap();
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.
Note this will not add the contents of the directory to the archive.
See append_dir_all
for recusively adding the contents of the directory.
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 std::fs;
use 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", ".").unwrap();
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 std::fs;
use 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", ".").unwrap();
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.