/ 
File-Raw-Archive-0.02
/ File::Raw::Archive::Entry

NAME

File::Raw::Archive::Entry - Single archive entry (metadata + lazy content)

SYNOPSIS

while (my $entry = $reader->next) {
    say $entry->name, "  ", $entry->size;
    next if $entry->is_dir;
    my $bytes = $entry->slurp;
}

DESCRIPTION

A File::Raw::Archive::Entry object represents one entry in an archive - its header metadata and a lazy handle to the payload bytes. Entries are returned by "next" in File::Raw::Archive::Reader and by the callback passed to "each" in File::Raw::Archive.

The payload can be read at most once via slurp or read; after the reader advances to the next entry any unread bytes are discarded.

METADATA ACCESSORS

All metadata accessors are read-only. String-typed accessors return undef when the field was absent in the archive header; integer-typed accessors return 0.

name

Entry path as stored in the archive, e.g. src/main.c. May include directory components but never a leading /.

size

Payload size in bytes. 0 for directories and symlinks.

mode

POSIX permission bits as an integer (e.g. 0644).

mtime

Last-modification time as integer Unix seconds.

mtime_ns

Sub-second nanosecond component of the modification time (0-999_999_999). Non-zero only when the archive carried a PAX extended mtime record.

uid

Numeric user ID of the entry owner.

gid

Numeric group ID of the entry owner.

type

Integer entry type. Compare against the constants exported by File::Raw::Archive: AE_FILE, AE_DIR, AE_SYMLINK, AE_HARDLINK, AE_FIFO, AE_CHAR, AE_BLOCK, AE_OTHER.

Symlink or hardlink destination string. undef for regular files and directories.

xattrs

Hashref of name => bytes pairs decoded from SCHILY.xattr.* PAX records, or undef when none were present.

is_sparse

True when the entry was recorded as a sparse file in the archive.

TYPE PREDICATES

is_file

True when type is AE_FILE.

is_dir

True when type is AE_DIR.

True when type is AE_SYMLINK.

True when type is AE_SYMLINK or AE_HARDLINK.

PAYLOAD METHODS

slurp

Read the entire entry payload into a byte string and return it. Memoised: calling slurp a second time returns the same scalar without re-reading from the archive. Croaks if the underlying reader has already been closed or advanced past this entry without consuming the payload.

my $bytes = $entry->slurp;
read($n)

Read at most $n bytes from the entry payload and return them. Returns an empty string at end-of-entry. Unlike slurp, each call consumes bytes from the stream; the result is not memoised.

while (length(my $chunk = $entry->read(65536))) {
    $fh->write($chunk);
}

SEE ALSO

File::Raw::Archive, File::Raw::Archive::Reader.

AUTHOR

LNATION <email@lnation.org>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under the Artistic License 2.0 (GPL Compatible).