Reads an index without copying stored payloads. Example: a, e := read_archive(bytes, .TAR);
#import "Extensions/Archive";
Reads and writes ZIP and TAR archives within explicit size limits. Entry metadata is owned by the Archive; payloads are read on demand. Input bytes (or a source) must outlive the archive.
#import "Extensions/Archive";
items := Archive_Item.[.{ name = "a.txt", data = cast([] u8) "hi" }];
bytes, error := encode_archive(items, .ZIP);
assert(error.kind == .NONE);
defer free(bytes.data);
a, e := read_archive(bytes, .ZIP);
assert(e.kind == .NONE);
defer free_archive(*a);
assert(a.entries.count == 1 && a.entries[0].name == "a.txt");Procedures#
General#
Returns a borrowed stored payload or an owned inflated buffer, verifying ZIP CRC first. Example: d, e := read_entry(*a, 0); defer free_archive(*d);
Copies stored data in 64 KiB pieces; deflate uses one bounded entry buffer. Example: error := copy_entry(*a, 0, sink);
Releases index metadata and gzip backing; never frees borrowed input. Example: free_archive(*a);
Write#
Encodes entries into an owned byte buffer. Example: bytes, e := encode_archive(items, .ZIP);
Writes to a sink without seeking; ZIP uses data descriptors. Deflate buffers one entry. Example: error := write_archive(sink, items, .ZIP);
Extract#
Extracts regular files/directories under an existing destination, rejecting all archive links. Existing files are never overwritten. On error, earlier outputs remain; discard the destination. Example: error := extract(*archive, "unpack", Archive_Limits.{});
Types#
The container format of an archive.
Archive_Format :: enum {
ZIP;
TAR;
TAR_GZIP;
}What an entry is.
Archive_Kind :: enum {
FILE;
DIRECTORY;
SYMLINK;
HARDLINK;
OTHER;
}How a ZIP entry's payload is stored.
Archive_Method :: enum u16 {
STORED = 0;
DEFLATE = 8;
}Why an archive operation failed.
Archive_Error_Kind :: enum {
NONE;
INVALID;
UNSUPPORTED;
LIMIT;
CHECKSUM;
PATH;
DUPLICATE;
IO;
}The outcome of an operation; kind is .NONE on success. Release entry with free_archive.
Archive_Error :: struct {
kind: Archive_Error_Kind;
message: string;
offset: s64;
entry: string;
}Bounds applied while indexing, reading, writing and extracting, to contain hostile input.
A negative value (or a max_ratio of 0 or less) makes the operation fail with .INVALID.
Archive_Limits :: struct {
max_archive: s64 = 1 << 30;
max_metadata: s64 = 16 << 20;
max_entries: s64 = 100000;
max_entry: s64 = 256 << 20;
max_total: s64 = 1 << 30;
max_ratio: s64 = 1000;
}A seekable byte source for read_archive. A read-at callback may return short reads. Its source must stay alive and unchanged.
Archive_Source :: struct {
data: *void;
size: s64;
read_at: (data: *void, offset: s64, buffer: [] u8) -> s64, string;
}One indexed archive entry. The strings are owned by the Archive that holds the entry.
Archive_Entry :: struct {
name: string;
link: string;
kind: Archive_Kind;
size: s64;
compressed_size: s64;
mtime: float64;
method: Archive_Method;
crc: u32;
offset: s64;
record_start: s64;
record_end: s64;
zip: bool;
}An open archive: the entry index plus what is needed to read payloads. Release it with free_archive.
Archive :: struct {
entries: [..] Archive_Entry;
limits: Archive_Limits;
bytes: [] u8;
source: Archive_Source;
owned: [] u8;
format: Archive_Format;
metadata: s64;
total: s64;
}The bytes of one entry from read_entry. When owned they were allocated and free_archive
releases them; otherwise they borrow the archive's input.
Archive_Data :: struct {
bytes: [] u8;
owned: bool;
}An entry to write with write_archive or encode_archive. Nothing is copied: name, data and
link must stay valid until the call returns.
Archive_Item :: struct {
name: string;
data: [] u8;
kind: Archive_Kind;
link: string;
mtime: s64;
method: Archive_Method;
}Receives output bytes; returns false when it cannot take them all. data is the sink's own state.
A byte sink for write_archive and copy_entry. It owns nothing and works on every target, wasm
included. To write to a file or socket, point data at it and forward to its own write, as
forward does for an Extensions/Io writer.
Archive_Writer :: struct {
data: *void;
write_proc: Archive_Write_Proc;
}forward :: (data: *void, bytes: [] u8) -> bool {
_, error := Io.write((cast(*Io.Writer) data).*, bytes);
return error == .NONE;
}
io_writer := Io.writer_of(*file);
error := write_archive(Archive_Writer.{ data = *io_writer, write_proc = forward }, items, .ZIP);