Struct EntryBuilder 

pub struct EntryBuilder { /* private fields */ }

Builder for complete tar entries including extension headers.

This handles the complexity of emitting multiple headers when paths or link targets exceed the 100-byte limit. It supports both GNU (LongLink/LongName) and PAX extension mechanisms.

Sans-IO Design

This builder does not perform any I/O. It produces Vec<Header> blocks or contiguous Vec<u8> that can be written to any output.

Extension Handling

• Short paths (≤100 bytes): Single header, no extensions needed
• Long paths (>100 bytes): Extension header + data blocks + main header
• Long link targets: Same as long paths, using appropriate extension

Example

use tar_core::builder::{EntryBuilder, ExtensionMode};
use tar_core::EntryType;

// Create a simple entry (short path)
let mut builder = EntryBuilder::new_gnu();
builder
    .path(b"hello.txt")
    .mode(0o644).unwrap()
    .size(1024).unwrap()
    .entry_type(EntryType::Regular);
let blocks = builder.finish();
assert_eq!(blocks.len(), 1); // Just one header block

// Create an entry with a long path
let long_path = "a/".repeat(60) + "file.txt";
let mut builder = EntryBuilder::new_gnu();
builder
    .path(long_path.as_bytes())
    .mode(0o644).unwrap()
    .size(0).unwrap()
    .entry_type(EntryType::Regular);
let blocks = builder.finish();
assert!(blocks.len() > 1); // Extension header(s) + main header

Implementations

impl EntryBuilder

pub fn new_gnu() -> Self

Create a new builder using GNU tar format for the underlying header.

This sets the extension mode to GNU (LongLink/LongName).

pub fn new_ustar() -> Self

Create a new builder using UStar format for the underlying header.

This sets the extension mode to PAX (extended headers).

pub fn with_mode(header: HeaderBuilder, mode: ExtensionMode) -> Self

Create a new builder with explicit format and extension mode.

pub fn extension_mode(&self) -> ExtensionMode

Get the current extension mode.

pub fn set_extension_mode(&mut self, mode: ExtensionMode) -> &mut Self

Set the extension mode.

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

Set the file path.

If the path exceeds 100 bytes, it will be stored using the configured extension mechanism (GNU or PAX). The main header’s name field will contain a truncated version (first 100 bytes, matching GNU tar).

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

Set the link target for symbolic/hard links.

If the link target exceeds 100 bytes, it will be stored using the configured extension mechanism.

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

Set the file mode (permissions).

Errors

Returns an error if the mode exceeds the maximum value for the 7-digit octal field (0o7777777 / 2097151). Standard Unix permission modes (up to 0o7777) always fit.

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

Set the owner user ID.

If the value overflows the header field and this builder uses PAX extensions, the value is stored as a PAX record instead (with 0 written to the header field for compatibility).

Errors

Returns an error only if the value overflows and PAX fallback is not available (GNU mode with value >= 2^63).

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

Set the owner group ID.

If the value overflows the header field and this builder uses PAX extensions, the value is stored as a PAX record instead (with 0 written to the header field for compatibility).

Errors

Returns an error only if the value overflows and PAX fallback is not available (GNU mode with value >= 2^63).

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

Set the file size.

If the value overflows the header field and this builder uses PAX extensions, the value is stored as a PAX record instead (with 0 written to the header field for compatibility).

Errors

Returns an error only if the value overflows and PAX fallback is not available (GNU mode with value >= 2^63).

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

Set the modification time as a Unix timestamp.

If the value overflows the header field and this builder uses PAX extensions, the value is stored as a PAX record instead (with 0 written to the header field for compatibility).

Errors

Returns an error only if the value overflows and PAX fallback is not available (GNU mode with value >= 2^63).

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

Set the entry type.

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

Set the owner user name.

If the name exceeds the 32-byte header field and this builder uses PAX extensions, the full name is stored as a PAX uname record (with the header field zeroed for compatibility).

Errors

Returns an error only if the name overflows and PAX fallback is not available (GNU mode).

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

Set the owner group name.

If the name exceeds the 32-byte header field and this builder uses PAX extensions, the full name is stored as a PAX gname record (with the header field zeroed for compatibility).

Errors

Returns an error only if the name overflows and PAX fallback is not available (GNU mode).

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 an error if the values don’t fit in the header fields.

pub fn sparse( &mut self, sparse_map: &[SparseEntry], real_size: u64, ) -> &mut Self

Mark this entry as a sparse file.

The sparse_map describes which regions of the logical file contain real data — gaps are implicitly zero-filled. The real_size is the logical file size as seen by readers.

The caller must also call size() with the on-disk content size (the sum of all sparse entry lengths).

On finish(), the builder emits format-appropriate sparse metadata:

• GNU mode: Sets entry type to GnuSparse, writes inline descriptors and extension blocks, sets realsize in the GNU header.
• PAX mode: Adds GNU.sparse.* PAX extensions (v1.0 format) and emits the sparse map as a data prefix block.

pub fn add_pax(&mut self, key: &str, value: impl AsRef<[u8]>) -> &mut Self

Add a custom PAX extension record.

This is useful for adding metadata that doesn’t fit in standard header fields. The PAX extension will be emitted regardless of the extension mode setting.

pub fn header(&self) -> &HeaderBuilder

Get a reference to the underlying header builder.

pub fn header_mut(&mut self) -> &mut HeaderBuilder

Get a mutable reference to the underlying header builder.

pub fn needs_extension(&self) -> bool

Check if this entry requires extension headers.

pub fn finish(&mut self) -> Vec<Header>

Build the complete header sequence as a vector of 512-byte blocks.

Returns all blocks needed for this entry’s headers:

• For short paths: just the main header (1 block)
• For GNU long paths: LongName header + data blocks + main header
• For PAX: extended header + data blocks + main header
• For GNU sparse: above + extension blocks after the main header
• For PAX sparse: PAX header includes GNU.sparse.* keys, plus a sparse map data prefix block after the main header

pub fn finish_bytes(&mut self) -> Vec<u8>

Build the complete header sequence as contiguous bytes.

This is a convenience method that flattens the block vector.

Trait Implementations

impl Clone for EntryBuilder

fn clone(&self) -> EntryBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for EntryBuilder

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

Formats the value using the given formatter.

impl Default for EntryBuilder

fn default() -> Self

Returns the “default value” for a type.