impl<'a, R: Read> Entry<'a, R>

fn path(&self) -> Result<Cow<'_, Path>>

Returns the path name for this entry.

This method may fail if the pathname is not valid Unicode and this is called on a Windows platform.

Note that this function will convert any \ characters to directory separators, and it will not always return the same value as self.header().path() as some archive formats have support for longer path names described in separate entries.

It is recommended to use this method instead of inspecting the header directly to ensure that various archive formats are handled correctly.

fn path_bytes(&self) -> Cow<'_, [u8]>

Returns the raw bytes listed for this entry.

Note that this function will convert any \ characters to directory separators, and it will not always return the same value as self.header().path_bytes() as some archive formats have support for longer path names described in separate entries.

fn link_name(&self) -> Result<Option<Cow<'_, Path>>>

Returns the link name for this entry, if any is found.

This method may fail if the pathname is not valid Unicode and this is called on a Windows platform. Ok(None) being returned, however, indicates that the link name was not present.

Note that this function will convert any \ characters to directory separators, and it will not always return the same value as self.header().link_name() as some archive formats have support for longer path names described in separate entries.

It is recommended to use this method instead of inspecting the header directly to ensure that various archive formats are handled correctly.

fn link_name_bytes(&self) -> Option<Cow<'_, [u8]>>

Returns the link name for this entry, in bytes, if listed.

Note that this will not always return the same value as self.header().link_name_bytes() as some archive formats have support for longer path names described in separate entries.

fn pax_extensions(&mut self) -> Result<Option<PaxExtensions<'_>>>

Returns an iterator over the pax extensions contained in this entry.

Pax extensions are a form of archive where extra metadata is stored in key/value pairs in entries before the entry they're intended to describe. For example this can be used to describe long file name or other metadata like atime/ctime/mtime in more precision.

The returned iterator will yield key/value pairs for each extension.

None will be returned if this entry does not indicate that it itself contains extensions, or if there were no previous extensions describing it.

Note that global pax extensions are intended to be applied to all archive entries.

Also note that this function will read the entire entry if the entry itself is a list of extensions.

fn header(&self) -> &Header

Returns access to the header of this entry in the archive.

This provides access to the metadata for this entry in the archive.

fn size(&self) -> u64

Returns access to the size of this entry in the archive.

In the event the size is stored in a pax extension, that size value will be referenced. Otherwise, the entry size will be stored in the header.

fn raw_header_position(&self) -> u64

Returns the starting position, in bytes, of the header of this entry in the archive.

The header is always a contiguous section of 512 bytes, so if the underlying reader implements Seek, then the slice from header_pos to header_pos + 512 contains the raw header bytes.

fn raw_file_position(&self) -> u64

Returns the starting position, in bytes, of the file of this entry in the archive.

If the file of this entry is continuous (e.g. not a sparse file), and if the underlying reader implements Seek, then the slice from file_pos to file_pos + entry_size contains the raw file bytes.

fn unpack<P: AsRef<Path>>(&mut self, dst: P) -> Result<Unpacked>

Writes this file to the specified location.

This function will write the entire contents of this file into the location specified by dst. Metadata will also be propagated to the path dst.

This function will create a file at the path dst, and it is required that the intermediate directories are created. Any existing file at the location dst will be overwritten.

Note: This function does not have as many sanity checks as Archive::unpack or Entry::unpack_in, and does not prevent writes outside dst. See the [crate-level security documentation][crate#security]. If you're unpacking untrusted archives, prefer Entry::unpack_in instead.

Examples

use std::fs::File;
use tar::Archive;

let mut ar = Archive::new(File::open("foo.tar").unwrap());

for (i, file) in ar.entries().unwrap().enumerate() {
    let mut file = file.unwrap();
    file.unpack(format!("file-{}", i)).unwrap();
}

fn unpack_in<P: AsRef<Path>>(&mut self, dst: P) -> Result<bool>

Extracts this file under the specified path, avoiding security issues.

This function will write the entire contents of this file into the location obtained by appending the path of this file in the archive to dst, creating any intermediate directories if needed. Metadata will also be propagated to the path dst. Any existing file at the location dst will be overwritten.

Security

See the [crate-level security documentation][crate#security].

Examples

use std::fs::File;
use tar::Archive;

let mut ar = Archive::new(File::open("foo.tar").unwrap());

for (i, file) in ar.entries().unwrap().enumerate() {
    let mut file = file.unwrap();
    file.unpack_in("target").unwrap();
}

fn set_mask(&mut self, mask: u32)

Set the mask of the permission bits when unpacking this entry.

The mask will be inverted when applying against a mode, similar to how umask works on Unix. In logical notation it looks like:

new_mode = old_mode & (~mask)

The mask is 0 by default and is currently only implemented on Unix.

fn set_unpack_xattrs(&mut self, unpack_xattrs: bool)

Indicate whether extended file attributes (xattrs on Unix) are preserved when unpacking this entry.

This flag is disabled by default and is currently only implemented on Unix using xattr support. This may eventually be implemented for Windows, however, if other archive implementations are found which do this as well.

fn set_preserve_permissions(&mut self, preserve: bool)

Indicate whether extended permissions (like suid on Unix) are preserved when unpacking this entry.

This flag is disabled by default and is currently only implemented on Unix.

fn set_preserve_mtime(&mut self, preserve: bool)

Indicate whether access time information is preserved when unpacking this entry.

This flag is enabled by default.