Esc

Archive

moduleextensionSource
  • macOS: Everything works on macOS
  • Linux: Everything works on Linux
  • Windows: Everything works on Windows
  • Wasm: Everything works on Wasm
·since 0.36.1

#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.

Example↗
#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#

Write#

Extract#

extractsince 0.36.1Source
(a: *Archive, dest_dir: string, limits := Archive_Limits.{}) -> Archive_Error

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#

Archive_Formatenumsince 0.36.1Source

The container format of an archive.

Archive_Format :: enum {
    ZIP;
    TAR;
    TAR_GZIP;
}
Archive_Kindenumsince 0.36.1Source

What an entry is.

Archive_Kind :: enum {
    FILE;
    DIRECTORY;
    SYMLINK;
    HARDLINK;
    OTHER;
}
Archive_Methodenumsince 0.36.1Source

How a ZIP entry's payload is stored.

Archive_Method :: enum u16 {
    STORED = 0;
    DEFLATE = 8;
}
Archive_Error_Kindenumsince 0.36.1Source

Why an archive operation failed.

Archive_Error_Kind :: enum {
    NONE;
    INVALID;
    UNSUPPORTED;
    LIMIT;
    CHECKSUM;
    PATH;
    DUPLICATE;
    IO;
}
Archive_Limitsstructsince 0.36.1Source

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;
}
Archive_Sourcestructsince 0.36.1Source

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;
}
Archive_Entrystructsince 0.36.1Source

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;
}
Archive_Datastructsince 0.36.1Source

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;
}
Archive_Write_Proctypesince 0.36.1Source
:: #type (data: *void, bytes: [] u8) -> bool

Receives output bytes; returns false when it cannot take them all. data is the sink's own state.

Archive_Writerstructsince 0.36.1Source

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);