Struct Header 

pub struct Header { /* private fields */ }

High-level tar header wrapper with accessor methods.

This struct wraps a [u8; 512] and provides convenient methods for accessing header fields, detecting the format, and verifying checksums.

Format Detection

The format is detected by examining the magic field:

• UStar: magic = “ustar\0”, version = “00”
• GNU: magic = “ustar “, version = “ \0”
• Old: anything else

Example

use tar_core::Header;

let mut header = Header::new_ustar();
assert!(header.is_ustar());
assert!(!header.is_gnu());

Implementations

impl Header

pub fn new_ustar() -> Self

Create a new header with UStar format magic and version.

pub fn new_gnu() -> Self

Create a new header with GNU tar format magic and version.

pub fn new_old() -> Self

Create a new old-style (V7/POSIX.1-1988) header with no magic bytes.

This header format is the original archive header format which all other versions are compatible with (e.g., they are a superset). This header format limits path name length and cannot contain extra metadata like atime/ctime.

pub fn as_bytes(&self) -> &[u8; 512]

Get a reference to the underlying bytes.

pub fn as_mut_bytes(&mut self) -> &mut [u8; 512]

Get a mutable reference to the underlying bytes.

pub fn from_bytes(bytes: &[u8; 512]) -> &Header

Interpret a [u8; 512] as a tar header reference.

pub fn as_old(&self) -> &OldHeader

View this header as an old-style header.

pub fn as_ustar(&self) -> &UstarHeader

View this header as a UStar header.

pub fn as_gnu(&self) -> &GnuHeader

View this header as a GNU header.

pub fn try_as_ustar(&self) -> Option<&UstarHeader>

View this header as a UStar header if it has the correct magic.

Returns None if this is not a UStar format header.

pub fn try_as_gnu(&self) -> Option<&GnuHeader>

View this header as a GNU header if it has the correct magic.

Returns None if this is not a GNU format header.

pub fn as_old_mut(&mut self) -> &mut OldHeader

View this header as a mutable old-style header.

pub fn as_ustar_mut(&mut self) -> &mut UstarHeader

View this header as a mutable UStar header.

pub fn as_gnu_mut(&mut self) -> &mut GnuHeader

View this header as a mutable GNU header.

pub fn try_as_ustar_mut(&mut self) -> Option<&mut UstarHeader>

View this header as a mutable UStar header if it has the correct magic.

Returns None if this is not a UStar format header.

pub fn try_as_gnu_mut(&mut self) -> Option<&mut GnuHeader>

View this header as a mutable GNU header if it has the correct magic.

Returns None if this is not a GNU format header.

pub fn is_ustar(&self) -> bool

Check if this header uses UStar format.

pub fn is_gnu(&self) -> bool

Check if this header uses GNU tar format.

pub fn entry_type(&self) -> EntryType

Get the entry type.

pub fn entry_size(&self) -> Result<u64>

Get the entry size (file content length) in bytes.

Errors

Returns HeaderError::InvalidOctal if the size field is not valid.

pub fn mode(&self) -> Result<u32>

Get the file mode (permissions).

Errors

Returns HeaderError::InvalidOctal if the mode field is not valid.

pub fn uid(&self) -> Result<u64>

Get the owner user ID.

Errors

Returns HeaderError::InvalidOctal if the uid field is not valid.

pub fn gid(&self) -> Result<u64>

Get the owner group ID.

Errors

Returns HeaderError::InvalidOctal if the gid field is not valid.

pub fn mtime(&self) -> Result<u64>

Get the modification time as a Unix timestamp.

Errors

Returns HeaderError::InvalidOctal if the mtime field is not valid.

pub fn path_bytes(&self) -> &[u8]

Get the raw path bytes from the header.

This returns only the name field (bytes 0..100). For UStar format, the prefix field (bytes 345..500) may also contain path components that should be prepended.

pub fn link_name_bytes(&self) -> &[u8]

Get the raw link name bytes.

pub fn device_major(&self) -> Result<Option<u32>>

Get the device major number (for character/block devices).

Returns None for old-style headers without device fields.

Errors

Returns HeaderError::InvalidOctal if the field is not valid octal.

pub fn device_minor(&self) -> Result<Option<u32>>

Get the device minor number (for character/block devices).

Returns None for old-style headers without device fields.

Errors

Returns HeaderError::InvalidOctal if the field is not valid octal.

pub fn username(&self) -> Option<&[u8]>

Get the owner user name.

Returns None for old-style headers without user/group name fields.

pub fn groupname(&self) -> Option<&[u8]>

Get the owner group name.

Returns None for old-style headers without user/group name fields.

pub fn prefix(&self) -> Option<&[u8]>

Get the UStar prefix field for long paths.

Returns None for old-style or GNU headers.

pub fn verify_checksum(&self) -> Result<()>

Verify the header checksum.

The checksum is computed as the unsigned sum of all header bytes, treating the checksum field (bytes 148..156) as spaces.

Errors

Returns HeaderError::ChecksumMismatch if the checksum is invalid, or HeaderError::InvalidOctal if the stored checksum cannot be parsed.

pub fn compute_checksum(&self) -> u64

Compute the header checksum.

This computes the unsigned sum of all header bytes, treating the checksum field (bytes 148..156) as spaces (0x20).

pub fn is_empty(&self) -> bool

Check if this header represents an empty block (all zeros).

Two consecutive empty blocks mark the end of a tar archive.

pub fn set_size(&mut self, size: u64) -> Result<()>

Set the file size (bytes 124-136).

For GNU headers, uses octal ASCII if the value fits, otherwise base-256 encoding. For ustar headers, uses octal ASCII only.

For values that always fit regardless of format (≤ ~8GB), prefer the infallible set_size_small.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented. For ustar, the octal limit is 0o77777777777 (8,589,934,591). For GNU, any u64 fits via base-256.

pub fn set_size_small(&mut self, size: u32)

Set the file size from a u32 (bytes 124-136).

Infallible because any u32 (max ~4.3 billion) fits in the 12-byte octal field (max 8,589,934,591) regardless of header format.

pub fn set_mode(&mut self, mode: u32) -> Result<()>

Set the file mode (bytes 100-108).

The mode is always written as octal ASCII (both GNU and ustar).

For typical Unix modes (≤ 0o7777), prefer the infallible set_mode_small.

Errors

Returns HeaderError::FieldOverflow if the value exceeds the 8-byte octal capacity (max 0o7777777 = 2,097,151).

pub fn set_mode_small(&mut self, mode: u16)

Set the file mode from a u16 (bytes 100-108).

Infallible because any u16 (max 65,535) fits in the 8-byte octal field (max 2,097,151). Covers all standard Unix permission bits (0o7777).

pub fn set_uid(&mut self, uid: u64) -> Result<()>

Set the owner user ID (bytes 108-116).

For GNU headers, uses base-256 encoding for values that exceed the octal range. For ustar headers, only octal ASCII is available.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented. For ustar, the octal limit is 0o7777777 (2,097,151). For GNU, the base-256 limit is 2^63 - 1.

pub fn set_gid(&mut self, gid: u64) -> Result<()>

Set the owner group ID (bytes 116-124).

For GNU headers, uses base-256 encoding for values that exceed the octal range. For ustar headers, only octal ASCII is available.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented. For ustar, the octal limit is 0o7777777 (2,097,151). For GNU, the base-256 limit is 2^63 - 1.

pub fn set_mtime(&mut self, mtime: u64) -> Result<()>

Set the modification time as a Unix timestamp (bytes 136-148).

For GNU headers, uses octal ASCII if the value fits, otherwise base-256 encoding. For ustar headers, uses octal ASCII only.

For timestamps that always fit regardless of format (≤ ~2106), prefer the infallible set_mtime_small.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented. For ustar, the octal limit is 0o77777777777 (8,589,934,591). For GNU, any u64 fits via base-256.

pub fn set_mtime_small(&mut self, mtime: u32)

Set the modification time from a u32 Unix timestamp (bytes 136-148).

Infallible because any u32 (max ~4.3 billion, i.e. year ~2106) fits in the 12-byte octal field regardless of header format.

pub fn set_entry_type(&mut self, ty: EntryType)

Set the entry type (byte 156).

pub fn set_checksum(&mut self)

Compute and set the header checksum (bytes 148-156).

This should be called after all other header fields have been set. The format is 7 octal digits with leading zeros plus a null terminator, matching tar-rs for bit-identical output.

pub fn set_path(&mut self, path: &[u8]) -> Result<()>

Set the file path (name field, bytes 0-100).

Errors

Returns an error if the path is longer than 100 bytes.

pub fn set_link_name(&mut self, link: &[u8]) -> Result<()>

Set the link name (bytes 157-257).

Errors

Returns an error if the link name is longer than 100 bytes.

pub fn set_username(&mut self, name: &[u8]) -> Result<()>

Set the owner user name (bytes 265-297, UStar/GNU only).

Errors

Returns an error if the username is longer than 32 bytes.

pub fn set_groupname(&mut self, name: &[u8]) -> Result<()>

Set the owner group name (bytes 297-329, UStar/GNU only).

Errors

Returns an error if the group name is longer than 32 bytes.

pub fn set_device(&mut self, major: u32, minor: u32) -> Result<()>

Set device major and minor numbers (bytes 329-337 and 337-345).

Used for character and block device entries.

Errors

Returns HeaderError::FieldOverflow if either value cannot be represented in its 8-byte octal field (max 0o7777777 = 2097151). For device numbers that fit in u16, prefer the infallible set_device_small.

pub fn set_device_small(&mut self, major: u16, minor: u16)

Set device major and minor numbers from u16 values.

Infallible because any u16 (max 65535) fits in the 8-byte octal fields (max 2097151). Covers all real-world device numbers.

Trait Implementations

impl Clone for Header

fn clone(&self) -> Header

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Header

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Header

fn default() -> Self

Returns the “default value” for a type.

impl FromBytes for Header

where [u8; 512]: FromBytes,

fn ref_from_bytes( source: &[u8], ) -> Result<&Self, ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: KnownLayout + Immutable,

Interprets the given source as a &Self.

fn ref_from_prefix( source: &[u8], ) -> Result<(&Self, &[u8]), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: KnownLayout + Immutable,

Interprets the prefix of the given source as a &Self without copying.

fn ref_from_suffix( source: &[u8], ) -> Result<(&[u8], &Self), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, Infallible>>

where Self: Immutable + KnownLayout,

Interprets the suffix of the given bytes as a &Self.

fn mut_from_bytes( source: &mut [u8], ) -> Result<&mut Self, ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout,

Interprets the given source as a &mut Self.

fn mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout,

Interprets the prefix of the given source as a &mut Self without copying.

fn mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, Infallible>>

where Self: IntoBytes + KnownLayout,

Interprets the suffix of the given source as a &mut Self without copying.

fn read_from_bytes(source: &[u8]) -> Result<Self, SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the given source.

fn read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the prefix of the given source.

fn read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the suffix of the given source.

fn read_from_io<R>(src: R) -> Result<Self, Error>

where Self: Sized, R: Read,

Reads a copy of self from an io::Read.

impl FromZeros for Header

where [u8; 512]: FromZeros,

fn zero(&mut self)

Overwrites self with zeros.

fn new_zeroed() -> Self

where Self: Sized,

Creates an instance of Self from zeroed bytes.

fn new_box_zeroed() -> Result<Box<Self>, AllocError>

where Self: Sized,

Creates a Box<Self> from zeroed bytes.

fn new_vec_zeroed(len: usize) -> Result<Vec<Self>, AllocError>

where Self: Sized,

Creates a Vec<Self> from zeroed bytes.

fn extend_vec_zeroed( v: &mut Vec<Self>, additional: usize, ) -> Result<(), AllocError>

where Self: Sized,

Extends a Vec<Self> by pushing additional new items onto the end of the vector. The new items are initialized with zeros.

fn insert_vec_zeroed( v: &mut Vec<Self>, position: usize, additional: usize, ) -> Result<(), AllocError>

where Self: Sized,

Inserts additional new items into Vec<Self> at position. The new items are initialized with zeros.

impl IntoBytes for Header

where [u8; 512]: IntoBytes,

fn as_bytes(&self) -> &[u8]

where Self: Immutable,

Gets the bytes of this value.

fn as_mut_bytes(&mut self) -> &mut [u8]

where Self: FromBytes,

Gets the bytes of this value mutably.

fn write_to(&self, dst: &mut [u8]) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to dst.

fn write_to_prefix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the prefix of dst.

fn write_to_suffix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the suffix of dst.

fn write_to_io<W>(&self, dst: W) -> Result<(), Error>

where Self: Immutable, W: Write,

Writes a copy of self to an io::Write.

impl KnownLayout for Header

where Self: Sized,

type PointerMetadata = ()

The type of metadata stored in a pointer to Self.

fn size_for_metadata(meta: Self::PointerMetadata) -> Option<usize>

Computes the size of an object of type Self with the given pointer metadata.

impl TryFromBytes for Header

where [u8; 512]: TryFromBytes,

fn try_ref_from_bytes( source: &[u8], ) -> Result<&Self, ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout + Immutable,

Attempts to interpret the given source as a &Self.

fn try_ref_from_prefix( source: &[u8], ) -> Result<(&Self, &[u8]), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout + Immutable,

Attempts to interpret the prefix of the given source as a &Self.

fn try_ref_from_suffix( source: &[u8], ) -> Result<(&[u8], &Self), ConvertError<AlignmentError<&[u8], Self>, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: KnownLayout + Immutable,

Attempts to interpret the suffix of the given source as a &Self.

fn try_mut_from_bytes( bytes: &mut [u8], ) -> Result<&mut Self, ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the given source as a &mut Self without copying.

fn try_mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the prefix of the given source as a &mut Self.

fn try_mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), ConvertError<AlignmentError<&mut [u8], Self>, SizeError<&mut [u8], Self>, ValidityError<&mut [u8], Self>>>

where Self: KnownLayout + IntoBytes,

Attempts to interpret the suffix of the given source as a &mut Self.

fn try_read_from_bytes( source: &[u8], ) -> Result<Self, ConvertError<Infallible, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: Sized,

Attempts to read the given source as a Self.

fn try_read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), ConvertError<Infallible, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: Sized,

Attempts to read a Self from the prefix of the given source.

fn try_read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), ConvertError<Infallible, SizeError<&[u8], Self>, ValidityError<&[u8], Self>>>

where Self: Sized,

Attempts to read a Self from the suffix of the given source.

impl Copy for Header

impl Immutable for Header

where [u8; 512]: Immutable,