Struct HeaderBuilder 

pub struct HeaderBuilder { /* private fields */ }

Builder for creating tar headers.

This provides a fluent API for constructing tar headers with proper field formatting and checksum calculation.

Example

use tar_core::builder::HeaderBuilder;
use tar_core::EntryType;

let mut builder = HeaderBuilder::new_ustar();
builder
    .path(b"example.txt").unwrap()
    .mode(0o644).unwrap()
    .uid(1000).unwrap()
    .gid(1000).unwrap()
    .size(0).unwrap()
    .mtime(1234567890).unwrap()
    .entry_type(EntryType::Regular);

let header = builder.finish();

Implementations

impl HeaderBuilder

pub fn new_ustar() -> Self

Create a new builder for a UStar format header.

pub fn new_gnu() -> Self

Create a new builder for a GNU tar format header.

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

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

Errors

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

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

Set the file mode.

Errors

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

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

Set the owner user ID.

Format-aware: GNU headers use base-256 for values exceeding the octal range; ustar headers use octal only.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented in the header format.

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

Set the owner group ID.

Format-aware: GNU headers use base-256 for values exceeding the octal range; ustar headers use octal only.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented in the header format.

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

Set the file size.

Format-aware: GNU headers use base-256 for values exceeding the octal range; ustar headers use octal only.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented in the header format.

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

Set the modification time as a Unix timestamp.

Format-aware: GNU headers use base-256 for values exceeding the octal range; ustar headers use octal only.

Errors

Returns HeaderError::FieldOverflow if the value cannot be represented in the header format.

pub fn entry_type(&mut self, entry_type: EntryType) -> &mut Self

Set the entry type.

pub fn link_name(&mut self, link: impl AsRef<[u8]>) -> Result<&mut Self>

Set the link name for symbolic/hard links (100 bytes).

Errors

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

pub fn username(&mut self, name: impl AsRef<[u8]>) -> Result<&mut Self>

Set the owner user name (32 bytes, UStar/GNU only).

Errors

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

pub fn groupname(&mut self, name: impl AsRef<[u8]>) -> Result<&mut Self>

Set the owner group name (32 bytes, UStar/GNU only).

Errors

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

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

Set device major and minor numbers.

Used for character and block device entries.

Errors

Returns HeaderError::FieldOverflow if the values don’t fit in the 8-byte octal fields (max 0o7777777 = 2,097,151).

pub fn prefix(&mut self, prefix: impl AsRef<[u8]>) -> Result<&mut Self>

Set the UStar prefix field for long paths (155 bytes).

Errors

Returns an error if the prefix is longer than 155 bytes.

pub fn as_header(&self) -> &Header

Get a reference to the current header for inspection.

Note: The checksum field will not be valid until finish is called.

pub fn as_header_mut(&mut self) -> &mut Header

Get a mutable reference to the raw header.

This is intended for direct field manipulation that the builder doesn’t expose (e.g. GNU sparse header fields).

pub fn finish(&mut self) -> Header

Compute the checksum and return the final header.

This fills in the checksum field and returns the complete 512-byte header.

Trait Implementations

impl Clone for HeaderBuilder

fn clone(&self) -> HeaderBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HeaderBuilder

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

Formats the value using the given formatter.

impl Default for HeaderBuilder

fn default() -> Self

Returns the “default value” for a type.