Standard library · Encoding and data

archive

Making, listing, checking and extracting zip, tar, tar.gz, tar.zst, gzip, zstd and RAR files, with passwords and multi-volume RAR.

import archive

An archive gathers several files into one. Zip compresses each file on its own; tar only puts the files one after another and is usually gzipped afterwards (.tar.gz).

The functions work both in memory and on files. They take the archive data as an address and a length, such as b.data and b.len of a byte buffer.

Every format at a glance

FormatMakeListRead one fileExtract allIs the data checked?
.zipZipCreate, ZipCreate64, ZipCreateFileZipListZipExtractByName, ZipExtractByNameMax, ZipExtractVerifiedZipExtractAllYes with ZipExtractVerified, ZipVerify and ZipExtractAll. ZipExtractByName does not check (see "Check an archive").
.tarTarCreate, TarCreateFileTarListTarExtractByNameTarExtractAllNo. Tar keeps no checksum of the contents.
.tar.gzTarGzCreate, TarGzCreateFileTarGzList, TarGzListMaxTarGzExtractByName, TarGzExtractByNameMaxTarGzExtractAll, TarGzExtractAllMaxYes, by the gzip step: its CRC-32 and length are verified. The Max forms stop a small file from expanding without bound.
.tar.zstTarZstdCreate, TarZstdCreateFileTarZstdList, TarZstdListMaxTarZstdExtractByName, TarZstdExtractByNameMaxTarZstdExtractAll, TarZstdExtractAllMaxYes, by the Zstandard step: its XXH64 checksum is verified. The Max forms stop a small file from expanding without bound.
.bz2 (one file)Bzip2CompressFile, compress.Bzip2CompressBufnot applicableBzip2DecompressFile, compress.Bzip2DecompressBufthe sameYes: every block CRC and the stream CRC are verified, ok is false on a mismatch.
.gz (one file)GzipCompressFile, compress.GzipCompressBufnot applicableGzipDecompressFile, compress.GzipDecompressBufthe sameYes: CRC-32 and length are verified, ok is false on a mismatch.
.xz (one file)XzCompressFile, compress.XzCompressBufnot applicableXzDecompressFile, compress.XzDecompressBufthe sameYes: the headers, the index and the CRC-32, CRC-64 or SHA-256 of every block are verified, ok is false on a mismatch.
.lzma (one file)LzmaCompressFile, compress.LzmaCompressBufnot applicableLzmaDecompressFile, compress.LzmaDecompressBufthe sameOnly the structure: the format has no checksum.
.zst (one file)ZstdCompressFile, ZstdCompressFileLevel, compress.ZstdCompressBufnot applicableZstdDecompressFile, compress.ZstdDecompressBufthe sameYes: the XXH64 checksum is verified when the file has one, ok is false on a mismatch.
.rarRarCreate, RarCreateFile (stored, RAR 5)RarList, RarEntriesRarExtract, RarReadRarExtractAll, RarReadAllYes, every entry; the result is a status code.
.7zSevenZipCreate, SevenZipCreateFile (stored), SevenZipCreateLevel, SevenZipCreateFileLevel (LZMA, levels 1 to 9)SevenZipList, SevenZipEntriesSevenZipExtractByName, SevenZipExtract, SevenZipReadSevenZipExtractAll, SevenZipReadAllYes: the headers, each solid block and each file are checked against their CRC-32; the result is a status code.

Multi-volume sets work for RAR through RarOpenVolumes, for 7z through SevenZipOpenVolumes and for zip through ZipOpenFile (pass the .zip, the .z01 or the .zip.001 piece; the other pieces are found next to it) and written with ZipCreateFileSplit. Passwords work for RAR through RarOpen and for 7z through SevenZipOpen. Zip entries with a password are read through ZipOpenFile and ZipFileSetPassword (ZipCrypto and WinZip AES) and written through ZipFileInput.password.

The compression itself comes from compress; use that package directly to gzip a single file or stream. For reading and writing the files on disk around an archive, see fs.

Limits to know about

  • Zip: zip64 is read and written (64-bit sizes and offsets, the zip64 end record, more than 65535 entries), but the package counts bytes in an int, so in practice an archive and each entry must stay under 2 GB. A bigger entry is listed with its true size, and extracting it reports ZIP_TOO_BIG; ZipCreate returns an empty buffer (and ZipCreateFile false) for input it cannot hold: a negative length, a null address with a length, a name over 65535 bytes, or about 1.9 GB in total. ZipCreate switches to zip64 on its own only for 65535 entries or more; ZipCreate64 always writes the zip64 form, which unzip and 7z read. Methods 0 (stored), 8 (DEFLATE), 12 (bzip2), 14 (LZMA) and 93 (zstd) are read and written, and 9 (Deflate64, what 7-Zip writes with -mm=Deflate64) is read; any other method is reported as ZIP_UNSUPPORTED, and encrypted entries are written as ZipCrypto or WinZip AES-128, AES-192 or AES-256 (ZipFileInput.password and encryption); the in-memory readers refuse them, use ZipOpenFile. ZipExtractByName and ZipExtractByNameMax do not check the CRC-32; ZipExtractVerified, ZipVerify and ZipExtractAll do, and ZipExtractAll skips an entry that fails the check and returns false.
  • Zip names and dates: a name with non-ASCII bytes is written with the UTF-8 flag (general purpose bit 11), so Windows Explorer, unzip and 7-Zip show Persian names correctly. When reading, a name is taken as it is (UTF-8) unless the Info-ZIP "Unicode path" field is present, which then wins. Names from other code pages are not converted. Dates are DOS dates: two second steps, between 1980 and 2107, with no time zone, read here as UTC. Set ZipFileInput.mtime (seconds since 1970) to date an entry; 0, or any time before 1980, writes 1 January 1980. The extra timestamp field is not written. ZipExtractAll sets the modification time of the files it writes from that date, except on Windows and 32 bit systems, and does not touch folders.
  • Tar: names of any length round-trip: a long name is stored in the ustar prefix field when it splits at a slash, otherwise in a PAX path record, and reading understands ustar prefixes, PAX (x and g) and GNU long names and links. Symbolic and hard links are real entries (Entry.kind and Entry.link); devices, pipes and other special entries are listed with kind 4 and skipped by TarExtractAll. Times and modes you set are written (a time past the ustar range goes into a PAX record), and extraction applies the mode and the modification time of files and folders, but not their owner. On Windows symbolic links are not created (the call returns false), hard links become copies and times are not set; times are not set on 32 bit systems either. Entries that are not given a time get 0, and the mode you leave at 0 becomes 644 for files, 755 for folders and 777 for symbolic links.
  • Tar extraction: TarExtractAll skips, and returns false for, a name that is absolute or climbs out with .., a name that passes through a symbolic link it created, a symbolic link whose target is absolute or leaves the target folder (a .. after a name is refused too), and a hard link to a name outside the folder. Set-user-id and similar mode bits are never applied.
  • RAR: RAR 5 archives are read completely: every compression level, solid archives and the built-in filters, with each entry's CRC-32 checked. Older archives (RAR 1.5 to 4.x) are read the same way, including PPMd text compression and the standard filters. Password-protected archives open with RarOpen and a password, including ones whose file names are encrypted; without it they report RAR_ENCRYPTED, and a wrong password reports RAR_BAD_PASSWORD. Multi-volume archives open from the list of volumes (RarOpenVolumes, or RarReadVolumes to load a set from disk); a set with a missing volume reports RAR_MULTIVOLUME for the files that cross it. A file that is both encrypted and split across volumes is read too (checked against the reference unrar on RAR 1.5, 2.0, 3 and 5 sets). The old RAR 1.5 and 2.x passwords work as well, tested with a real WinRAR 2.02 file. The RAR 7 format version 1 (dictionaries over 4 GB, fractional sizes) is read; only a match distance beyond 4 GB has never been run. The in-memory functions need the archive and each entry under 2 GB (a bigger entry reports RAR_TOO_BIG); for bigger RAR 5 files use RarFileOpen, which reads from disk and unpacks in pieces. Extraction restores the Unix permissions and the modification time (on 64-bit systems other than Windows), recreates symbolic links whose target stays inside the destination, and writes hard links and file copies as plain copies; a link that points outside is skipped and reported as RAR_UNSAFE_PATH. New archives are RAR 5 with the files stored, because only WinRAR itself can compress to RAR; any RAR tool opens them.
  • 7z: read, and written with stored data only. LZMA, LZMA2, PPMd, BZip2, Deflate, Deflate64, copy, BCJ2, the branch filters (x86, ARM, ARM64, RISC-V and others), byte swap and delta are supported, with AES-256 passwords (headers too); Multi-volume sets (.7z.001) and self-extracting archives (an executable stub before the archive) are read. Unix modes, times and symbolic links are restored on extraction, and a link that would point outside the target folder is refused. The calls that take a pointer and a length hold everything unpacked in memory, so a solid block is capped at about 1 GiB and the dictionary of an LZMA stream may not pass 1 GiB; SevenZipOpenFile has no such limit (see below). Names are UTF-8; the time is the last change.

The guide below shows the usual jobs: zipping a set of files, making and reading a .tar.gz, telling formats apart by their first bytes, and extracting without letting an archive write outside the target folder.

Zip a set of files

Each file you put into a zip is a ZipFileInput: its path inside the archive, the address and length of its bytes, and the method: 8 for DEFLATE, 0 to store it as it is, or 12, 14 and 93 for bzip2, LZMA and zstd (the ZipMethod... constants). MakeZipFileInputLevel also sets a level for those compressors. Every unzip reads bzip2 entries; LZMA and zstd entries are read by 7-Zip and by Python's zipfile (zstd from Python 3.14), but not by older tools such as Info-ZIP unzip, so use them only when you know the reader. A name that ends with / is a folder. ZipCreateFile writes the archive to disk and returns false when it cannot; bzip2, LZMA and zstd entries are streamed through the encoders in std/compress, so an entry of any size needs only the encoder window in memory (about 1 MiB for zstd at the default level, a few MiB for LZMA, one block for bzip2); ZipCreate keeps it in memory, for example to send it as an HTTP response.

archive-guide-bundle.salam
import archive
import compress

func main:
    html := compress.BufFromStr("<html><body><h1>Hello</h1><p>Hello again, hello once more.</p></body></html>\n")
    css := compress.BufFromStr("body { margin: 0; }\nh1 { margin: 0; }\np { margin: 0; }\n")
    logo := compress.GzipCompressStr("pretend this is an image that is already compressed")
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("site/", null, 0, 0))
    files.Push(archive.MakeZipFileInput("site/index.html", html.data, html.len, 8))
    files.Push(archive.MakeZipFileInput("site/style.css", css.data, css.len, 8))
    files.Push(archive.MakeZipFileInput("site/logo.bin", logo.data, logo.len, 0))
    if not archive.ZipCreateFile(files, "site.zip"):
        println "could not write site.zip"
        ret 1
    end
    mut ok := false
    z := archive.ReadBinaryFile("site.zip", ok)
    mut entries := archive.ZipList(z.data, z.len)
    each e in entries:
        if e.is_dir:
            println e.name, "(folder)"
        else:
            println e.name, e.size, "->", e.compressed_size, "method", e.method
        end
    end
    archive.FreeEntries(entries)
    ret 0
end
Outputsite/ (folder) site/index.html 77 -> 63 method 8 site/style.css 55 -> 29 method 8 site/logo.bin 64 -> 64 method 0

Text shrinks well. The logo is already compressed, so it uses method 0: running DEFLATE on it again would only cost time and could even make it bigger. The same rule holds for JPEG, PNG, MP4 and other zips.

Make and read a .tar.gz

Tar does not compress. It puts each file after a 512 byte header and pads its contents to a multiple of 512 bytes, so three small files already take 3.5 KB. The usual answer is to gzip the whole tar, and all that padding then nearly disappears. In memory that is TarCreate followed by compress.GzipCompressBuf; for a tar that is already on disk, GzipCompressFile and GzipDecompressFile do it file to file. TarGzCreate and TarGzCreateFile do both steps at once.

archive-guide-targz.salam
import archive
import compress

func main:
    readme := compress.BufFromStr("Backup of the config folder.\n")
    conf := compress.BufFromStr("port = 8080\nworkers = 4\nport_admin = 8081\n")
    mut files := Vector {} as Vector<archive.TarFileInput>
    files.Push(archive.MakeTarFileInput("config", null, 0, true))
    files.Push(archive.MakeTarFileInput("config/README", readme.data, readme.len, false))
    files.Push(archive.MakeTarFileInput("config/app.conf", conf.data, conf.len, false))
    tar := archive.TarCreate(files)
    tgz := compress.GzipCompressBuf(tar)
    println "tar:", tar.len, "bytes, tar.gz:", tgz.len, "bytes"
    archive.WriteBinaryFileBuf("config.tar.gz", tgz)

    mut ok := false
    packed := archive.ReadBinaryFile("config.tar.gz", ok)
    plain := compress.GzipDecompressBuf(packed, ok)
    if not ok:
        println "config.tar.gz is not valid gzip"
        ret 1
    end
    mut entries := archive.TarList(plain.data, plain.len)
    each e in entries:
        println e.name, e.size, e.is_dir
    end
    archive.FreeEntries(entries)
    app := archive.TarExtractByName(plain.data, plain.len, "config/app.conf", ok)
    print compress.BufToStrUnsafe(app)
    ret 0
end
Outputtar: 3584 bytes, tar.gz: 208 bytes config 0 true config/README 29 false config/app.conf 42 false port = 8080 workers = 4 port_admin = 8081

Reading goes the other way: TarGzList, TarGzExtractByName and TarGzExtractAll gunzip and read in one call, and set ok to false when the data is not a valid gzip. They refuse to inflate past 1 GiB; give the Max forms a smaller limit for input you do not trust. Directory entries in a tar have size 0 and is_dir set.

Zstandard works the same way: TarZstdCreate builds the tar and compresses it, and TarZstdList, TarZstdExtractByName and TarZstdExtractAll decompress and read in one call, with Max forms to cap the unpacked size. A .tar.zst made with tar --zstd reads the same way. For a single file there is ZstdCompressFile and ZstdDecompressFile.

Read a 7z archive

7z archives are read, and can be made with stored data (no compression). SevenZipList and SevenZipListStatus list the entries, SevenZipExtractByName unpacks one, and SevenZipExtractAll writes everything under a folder. The LZMA, LZMA2, PPMd, BZip2, Deflate and Deflate64 methods are understood, with BCJ2, the branch filters (x86, ARM, ARM64, RISC-V, PowerPC, SPARC, IA-64), byte swap and delta in front of them, solid blocks, empty files and folders, encrypted data and encrypted headers (AES-256). The signature header, the header, every solid block and every file are checked against their CRC-32. Anti items, which mean "delete this name" in an update archive, are left out.

archive-guide-sevenzip.salam
import archive
import compress
import filepath
import os

const PACKED := """
377abcaf271c0004285eeffde1000000000000002200000000000000b6539000e0009a00455d00271bca866798db2a9932
ecb108f48e70217d76d380887c03113d3cbf05381d9da1ba6b83a1a220c4656aeac3932a993abd9ea11cf8b4a761ae3af5
25cd41b942bff3ee0000000000813307ae0fd29aba3d40c090d2ff7d694d8f17af096379cb439267a35290e659701f3be3
6ecf209c510fa5d7b46a9c1bc2ee771f3e97490b78775d756e5d08a454586e1ec479608d69d1666dfa5b88efa423415340
9765eb30ad5f38ecae89e94cbd79558938ae1d384c90fe7db292aab05a6ec1eb816b7fbbeaf3ea941a1f4ff09d06216330
82fa2e2e1849c8fb9600000017064d0109809400070b01000123030101055d001000000c80ce0a01885a3c9d0000
"""

func nib(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func unhex(s: str): compress.ByteBuf:
    mut b := compress.NewByteBuf()
    bp := s as u8*
    mut hi := -1
    repeat s.Len() in i:
        v := nib(bp[i] as int)
        if v < 0:
            continue
        end
        if hi < 0:
            hi = v
        else:
            compress.BufPush(b, hi * 16 + v)
            hi = -1
        end
    end
    ret b
end

func main:
    packed := unhex(PACKED)
    println "7z archive:", archive.IsSevenZip(packed.data, packed.len)

    mut status := 0
    mut list := archive.SevenZipListStatus(packed.data, packed.len, status)
    println "entries:", list.Len(), archive.SevenZipStatusText(status)
    repeat list.Len() in i:
        e := list.Get(i)
        mut kind := "file"
        if e.is_dir:
            kind = "folder"
        end
        println " ", e.name, kind, e.size
    end
    archive.FreeEntries(list)

    mut ok := false
    readme := archive.SevenZipExtractByName(packed.data, packed.len, "readme.txt", ok)
    println "readme.txt:", ok, readme.len, "bytes"
    capped := archive.SevenZipExtractByNameMax(packed.data, packed.len, "readme.txt", 50, ok)
    println "capped at 50:", ok, capped.len

    dir := filepath.Join(os.TempDir(), "salam_sevenzip_guide")
    os.RemoveAll(dir)
    println "extracted:", archive.SevenZipExtractAll(packed.data, packed.len, dir)
    println os.Exists(filepath.Join(dir, "src/main.salam")), os.Exists(filepath.Join(dir, "empty.log"))
    os.RemoveAll(dir)

    mut damaged := compress.BufClone(packed)
    compress.BufSet(damaged, damaged.len - 3, compress.BufGet(damaged, damaged.len - 3) ^ 1)
    broken := archive.SevenZipExtract(damaged.data, damaged.len, "readme.txt", 0, status)
    println "damaged:", archive.SevenZipStatusText(status), broken.len
end
Output7z archive: true entries: 4 ok src folder 0 empty.log file 0 readme.txt file 120 src/main.salam file 35 readme.txt: true 120 bytes capped at 50: false 0 extracted: true true true damaged: checksum mismatch 0

A solid block is one compressed stream holding several files, so reading one file out of it unpacks the whole block; to get many files out of one archive use SevenZipExtractAll, which unpacks each block once. Every call returns a SEVENZIP_... status instead of guessing: a wrong password is SEVENZIP_BAD_PASSWORD, a missing password SEVENZIP_ENCRYPTED, a damaged file SEVENZIP_BAD_CRC or SEVENZIP_CORRUPT. Open an encrypted archive with SevenZipOpen and its password, then use SevenZipEntries, SevenZipRead and SevenZipReadAll:

Tell the format from the first bytes

A file name can lie, the bytes cannot. Every format starts with a fixed signature, so a program that accepts uploads should look at the bytes before it picks a reader:

FormatSignatureCheck
zip50 4b 03 04 (PK) at the startcompare the first four bytes
gzip1f 8b at the startcompare the first two bytes
xzfd 37 7a 58 5a 00 at the startcompare the first six bytes
RARRar! at the startIsRar
7z37 7a bc af 27 1c at the start (a self-extracting archive has it later)IsSevenZip
tarustar at byte 257compare five bytes from offset 257
archive-guide-detect.salam
import archive
import compress

func kind(b: compress.ByteBuf): str:
    if b.len >= 4 and compress.BufGet(b, 0) == 80 and compress.BufGet(b, 1) == 75 and compress.BufGet(b, 2) == 3 and compress.BufGet(b, 3) == 4:
        ret "zip"
    end
    if b.len >= 2 and compress.BufGet(b, 0) == 31 and compress.BufGet(b, 1) == 139:
        ret "gzip"
    end
    if archive.IsRar(b.data, b.len):
        ret "rar"
    end
    if b.len >= 262 and compress.BufGet(b, 257) == 117 and compress.BufGet(b, 258) == 115 and compress.BufGet(b, 259) == 116 and compress.BufGet(b, 260) == 97 and compress.BufGet(b, 261) == 114:
        ret "tar"
    end
    ret "unknown"
end

func count(b: compress.ByteBuf): int:
    k := kind(b)
    if k == "zip": ret archive.ZipList(b.data, b.len).Len() end
    if k == "tar": ret archive.TarList(b.data, b.len).Len() end
    if k == "rar": ret archive.RarList(b.data, b.len).Len() end
    if k == "gzip":
        mut ok := false
        inner := compress.GzipDecompressBuf(b, ok)
        if ok: ret count(inner) end
    end
    ret 0
end

func main:
    note := compress.BufFromStr("a short note\n")
    mut zf := Vector {} as Vector<archive.ZipFileInput>
    zf.Push(archive.MakeZipFileInput("note.txt", note.data, note.len, 8))
    mut tf := Vector {} as Vector<archive.TarFileInput>
    tf.Push(archive.MakeTarFileInput("note.txt", note.data, note.len, false))
    tar := archive.TarCreate(tf)
    samples := [archive.ZipCreate(zf), tar, compress.GzipCompressBuf(tar), note]
    each s in samples:
        println kind(s), s.len, "bytes,", count(s), "entries"
    end
end
Outputzip 129 bytes, 1 entries tar 2048 bytes, 1 entries gzip 100 bytes, 1 entries unknown 13 bytes, 0 entries

The gzip sample is the tar from the line above it, gzipped, so the program opens it and counts the entries of the tar inside. A plain text file matches nothing.

Extract safely

ZipExtractAll and TarExtractAll create the folders they need under the target directory. An archive from someone else can hold names like ../escape.txt or /etc/passwd that would land outside it; both functions skip such entries, write the rest, and return false so you know something was left out. ZipExtractByName and TarExtractByName set ok to false when the name is not in the archive.

archive-guide-extract.salam
import archive
import compress

func main:
    a := compress.BufFromStr("first file\n")
    b := compress.BufFromStr("second file\n")
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("docs/a.txt", a.data, a.len, 8))
    files.Push(archive.MakeZipFileInput("docs/deep/b.txt", b.data, b.len, 8))
    z := archive.ZipCreate(files)
    println "all extracted:", archive.ZipExtractAll(z.data, z.len, "out")
    mut ok := false
    back := archive.ReadBinaryFile("out/docs/deep/b.txt", ok)
    print "out/docs/deep/b.txt:", compress.BufToStrUnsafe(back)

    _ := archive.ZipExtractByName(z.data, z.len, "docs/c.txt", ok)
    println "docs/c.txt found:", ok

    mut evil := Vector {} as Vector<archive.ZipFileInput>
    evil.Push(archive.MakeZipFileInput("../escape.txt", a.data, a.len, 0))
    evil.Push(archive.MakeZipFileInput("safe.txt", a.data, a.len, 0))
    ez := archive.ZipCreate(evil)
    println "all extracted:", archive.ZipExtractAll(ez.data, ez.len, "out2")
    _ := archive.ReadBinaryFile("escape.txt", ok)
    println "escape.txt written:", ok
    _ := archive.ReadBinaryFile("out2/safe.txt", ok)
    println "out2/safe.txt written:", ok
end
Outputall extracted: true out/docs/deep/b.txt: second file docs/c.txt found: false all extracted: false escape.txt written: false out2/safe.txt written: true

A false result from an extract call is therefore not always a disk error: check the entry names with ZipList or TarList when you need to tell the two apart.

Gzip a single file (.gz)

A .gz holds one file, not a folder. GzipCompressFile and GzipDecompressFile go from a path to a path and return false when they cannot read, write or decode; in memory, compress.GzipCompressBuf and compress.GzipDecompressBuf do the same on a buffer. Decompressing checks the trailer, so a damaged or cut file is refused instead of giving back wrong bytes. For data from someone else use compress.GzipDecompressMax, which stops at a size you choose, so a tiny file cannot expand into gigabytes.

archive-guide-gzip.salam
import archive
import compress

func main:
    note := compress.BufFromStr("a log line that repeats, a log line that repeats, a log line that repeats\n")
    archive.WriteBinaryFileBuf("note.txt", note)

    println "gzip a file:", archive.GzipCompressFile("note.txt", "note.txt.gz")
    println "gunzip it:", archive.GzipDecompressFile("note.txt.gz", "note-copy.txt")
    mut ok := false
    copy := archive.ReadBinaryFile("note-copy.txt", ok)
    println "same bytes:", compress.BufEquals(copy, note)

    packed := compress.GzipCompressBuf(note)
    println "in memory:", note.len, "bytes become", packed.len
    back := compress.GzipDecompressBuf(packed, ok)
    println "round trip:", ok, compress.BufEquals(back, note)

    p := packed.data as u8*
    p[packed.len / 2] = ((p[packed.len / 2] as int) ^ 1) as u8
    _ := compress.GzipDecompressBuf(packed, ok)
    println "damaged copy accepted:", ok

    capped := compress.GzipCompressBuf(note)
    _ := compress.GzipDecompressMax(capped.data, capped.len, 10, ok)
    println "over a 10 byte limit accepted:", ok
end
Outputgzip a file: true gunzip it: true same bytes: true in memory: 74 bytes become 48 round trip: true true damaged copy accepted: false over a 10 byte limit accepted: false

To compress several files, put them in a tar first (the .tar.gz section above). To open a .tar.gz you do the same two steps backwards.

Check an archive

"Check" means two different things. To see what is inside without unpacking, list it: ZipList, TarList and RarList (or RarEntries) give every name, size, folder flag and, for zip and RAR, the stored CRC-32; free the list with FreeEntries. To know the data is intact, you need a checksum, and formats differ:

  • gzip and RAR verify themselves. A gzip call returns ok = false; a RAR call sets the status to RAR_BAD_CRC, or RAR_BAD_PASSWORD when a password was wrong.
  • zip stores a CRC-32 for each entry. ZipExtractVerified compares it with the data and sets status to ZIP_OK, ZIP_BAD_CRC and so on; ZipVerify checks every entry and returns how many failed; ZipBadEntries lists them. ZipExtractByName stays unchecked, for speed and for old code: compare compress.CRC32Buf(data) with Entry.crc32 yourself, as the example below does.
  • tar has no checksum for the contents. All you can check is that the listing is sane (names, sizes); for integrity gzip the tar and rely on the gzip trailer, or keep a hash next to the file.
archive-guide-check.salam
import archive
import compress

func main:
    a := compress.BufFromStr("first file, stored as it is\n")
    b := compress.BufFromStr("second file, a little longer than the first one\n")
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("a.txt", a.data, a.len, 0))
    files.Push(archive.MakeZipFileInput("b.txt", b.data, b.len, 0))
    z := archive.ZipCreate(files)

    p := z.data as u8*
    p[40] = ((p[40] as int) ^ 1) as u8

    mut entries := archive.ZipList(z.data, z.len)
    mut ok := false
    each e in entries:
        data := archive.ZipExtractByName(z.data, z.len, e.name, ok)
        good := compress.CRC32Buf(data) == e.crc32
        println e.name, "extracted:", ok, "checksum matches:", good
    end
    archive.FreeEntries(entries)

    mut rar_files := Vector {} as Vector<archive.RarFileInput>
    rar_files.Push(archive.MakeRarFileInput("a.txt", a.data, a.len, false))
    r := archive.RarCreate(rar_files)
    q := r.data as u8*
    q[r.len - 12] = ((q[r.len - 12] as int) ^ 1) as u8
    mut status := 0
    _ := archive.RarExtract(r.data, r.len, "a.txt", 0, status)
    println "rar:", archive.RarStatusText(status)
end
Outputa.txt extracted: true checksum matches: false b.txt extracted: true checksum matches: true rar: checksum mismatch

In the example one byte of the first zip entry was changed. Extraction still reports success for it, but its checksum no longer matches, while the second entry is fine. The RAR entry with the same damage is refused by the extractor itself.

The verified calls do that comparison for you. ZipVerify sets checked to the number of files it inflated and returns how many were bad, or -1 when the data is not a zip; ZipStatusText turns a status into a sentence.

archive-guide-zipverify.salam
import archive
import compress

func main:
    text := "hello archive, hello archive, hello archive"
    b := compress.BufFromStr(text)
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("a.txt", b.data, b.len, 0))
    files.Push(archive.MakeZipFileInput("b.txt", b.data, 5, 8))
    z := archive.ZipCreate(files)
    mut status := 0
    mut checked := 0
    good := archive.ZipExtractVerified(z.data, z.len, "a.txt", 0, status)
    println status == archive.ZIP_OK, good.len, archive.ZipVerify(z.data, z.len, checked), checked

    bp := z.data as u8*
    bp[35] = 0x58 as u8
    bad := archive.ZipExtractVerified(z.data, z.len, "a.txt", 0, status)
    println status == archive.ZIP_BAD_CRC, bad.len, archive.ZipStatusText(status)
    mut ok := false
    plain := archive.ZipExtractByName(z.data, z.len, "a.txt", ok)
    println ok, plain.len
    println archive.ZipVerify(z.data, z.len, checked), checked
    mut broken := archive.ZipBadEntries(z.data, z.len)
    each e in broken:
        println "damaged:", e.name
    end
    archive.FreeEntries(broken)
    _ := archive.ZipExtractVerified(z.data, z.len, "missing.txt", 0, status)
    println status == archive.ZIP_NOT_FOUND, archive.ZipStatusText(status)
end
Outputtrue 43 0 2 true 0 checksum mismatch true 43 1 2 damaged: a.txt true entry not found

The next example covers dates and zip64: ZipFileInput.mtime sets an entry's date, Entry.mtime reads it back, and ZipCreate64 writes the zip64 form.

archive-guide-ziptime.salam
import archive
import compress

func main:
    text := "salam, salam, salam"
    b := compress.BufFromStr(text)
    mut named := archive.MakeZipFileInput("سلام.txt", b.data, b.len, 8)
    named.mtime = 1700000000 as i64
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(named)
    files.Push(archive.MakeZipFileInput("plain.txt", b.data, b.len, 8))
    z := archive.ZipCreate(files)
    mut entries := archive.ZipList(z.data, z.len)
    each e in entries:
        println e.name, e.mtime
    end
    archive.FreeEntries(entries)
    println "utf8 flag:", (archive.LEGet16(z.data, 6) & 0x800) != 0

    wide := archive.ZipCreate64(files)
    mut again := archive.ZipList(wide.data, wide.len)
    println again.Len(), wide.len > z.len, again.Get(0).size
    archive.FreeEntries(again)
    mut checked := 0
    println archive.ZipVerify(wide.data, wide.len, checked), checked
end
Outputسلام.txt 1700000000 plain.txt 315532800 utf8 flag: true 2 true 19 0 2

Read and write a RAR

Reading goes through RarList and RarExtract, the same way as zip. The sample below is a small solid RAR 5 made by WinRAR: the second file is packed against the first, so RarExtract unpacks both to reach it. Every entry is checked against its CRC-32, and the status says what went wrong instead of returning silent garbage.

archive-guide-rar.salam
import archive
import compress

const SAMPLE := """
526172211a07010009efc86f0b0105070406010180808000f59006092302030bc300049c04a48302dcdfaa7280050105
612e7478740a031341fff06a00f2f92ec4de405543522f75043ded152822995a044050507ca7cbf17ff3c348ad0d2727
655f99a332a4c1ac1c51cad46312e761917434a437902ab22276d9e9f3b0b2cd03eb58c5ad77d22302030b9c0004b104
a4830220abc84ec0050105622e7478740a031341fff06ae4e7fa2e440719f5c9e63f0caebd274804c54d756dc27b960e
6971f66c94d170988ae3092702030b8000048000a4830200000000c0050109656d7074792e7478740a031341fff06ae4
e7fa2e1d77565103050400
"""

func digit(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func from_hex(text: str): compress.ByteBuf:
    mut out := compress.NewByteBuf()
    bytes := text as u8*
    mut high := -1
    repeat text.Len() in i:
        v := digit(bytes[i] as int)
        if v < 0:
            continue
        end
        if high < 0:
            high = v
        else:
            compress.BufPush(out, high * 16 + v)
            high = -1
        end
    end
    ret out
end

func main:
    rar := from_hex(SAMPLE)
    println archive.IsRar(rar.data, rar.len)
    mut entries := archive.RarList(rar.data, rar.len)
    each e in entries:
        println e.name, e.size, e.compressed_size
    end
    archive.FreeEntries(entries)

    mut status := 0
    b := archive.RarExtract(rar.data, rar.len, "b.txt", 0, status)
    println archive.RarStatusText(status), b.len
end
Outputtrue a.txt 540 67 b.txt 561 28 empty.txt 0 0 ok 561

Making a RAR is simpler: build RarFileInput values and call RarCreate or RarCreateFile. The result is a valid RAR 5 archive with the files stored uncompressed. If you need real compression, use zip, or .tar.gz as shown above.

Open a password-protected RAR

A RarArchive remembers the data and the password, so the list, a single read and a full extraction share them. With the wrong password the archive does not open (when the names are encrypted) or each read fails with RAR_BAD_PASSWORD; with none at all you get RAR_ENCRYPTED. RAR 5 checks the password up front. RAR 3 and 4 have no check value, so for them a wrong password shows up as a failed checksum, and it is reported the same way.

archive-guide-rar-password.salam
import archive
import compress

const SAMPLE := """
526172211a07010038d1db9021040000010fe945634161dc2d7b3e8b87f362874d32048313f00358e483efb2886b026e
590dc3a9e23be3b7cfa25ea1dd6a6c4c4af8702cb2d51eb2f7798221661b321c792f762b84ffbf221b7100d324e8f848
ca96b61074ef27c65ba5a760024e3e27ccd59be9d8047bce7da160956a1dd1ca59d5970613a92c4582b076eb3398a1b7
8ef8151f33cf3665dea91210eaede8f1c08f503c488358eb375bf44e0a7a90b81067d6a6637ae589c00f19b387d3d769
f8cfa327f9b218211f11fe63a7a1783e45656fcc9573869eaf359485c0e2d4d5066ddc9981c7b13390c6d78d0ea24a04
386db10eb6d52567002ad55ebee7f1a172080c6a7bd1c72ac29e74d0480d38934012ee49a5fcd5111ad5899223384b67
b8491eed31431d7295083a332114430d96e4004c3426c450dbd1985644df90632ebb89c94cb9f9000fe8b54e0335aa44
fe401e45aad3727aee1392db44b09094b58754bc5ae4fd2186aeb6790bbf2dc3a4225dd37203f3eeecf02fcfb2f150a1
4293fbab1e38425c7bdd1909e3b24e6882fb38344a28184e8d993d93616aeb3eb57e60b5681280a7d138329a4cda
"""

func digit(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func from_hex(text: str): compress.ByteBuf:
    mut out := compress.NewByteBuf()
    bytes := text as u8*
    mut high := -1
    repeat text.Len() in i:
        v := digit(bytes[i] as int)
        if v < 0:
            continue
        end
        if high < 0:
            high = v
        else:
            compress.BufPush(out, high * 16 + v)
            high = -1
        end
    end
    ret out
end

func main:
    rar := from_hex(SAMPLE)
    mut locked := archive.RarOpen(rar.data, rar.len, "")
    mut names := archive.RarEntries(locked)
    println names.Len(), archive.RarStatusText(locked.status)
    archive.FreeEntries(names)

    mut wrong := archive.RarOpen(rar.data, rar.len, "guess")
    names = archive.RarEntries(wrong)
    println names.Len(), wrong.status == archive.RAR_BAD_PASSWORD
    archive.FreeEntries(names)

    mut arc := archive.RarOpen(rar.data, rar.len, "secret")
    names = archive.RarEntries(arc)
    each e in names:
        data := archive.RarRead(arc, e.name, 0)
        println e.name, e.size, data.len, archive.RarStatusText(arc.status)
    end
    archive.FreeEntries(names)
    println archive.RarReadAll(arc, "unlocked"), archive.RarStatusText(arc.status)
end
Output0 encrypted data and no password 0 true n1.txt 352 352 ok n2.txt 348 348 ok 2 ok

Read a multi-volume RAR

A big archive is often cut into volumes: name.part01.rar, name.part02.rar, and so on, or the older name.rar, name.r00, name.r01. RarReadVolumes takes the first file name, finds the rest by that naming and loads them; RarOpenVolumes turns the list into a RarArchive, and the usual RarEntries and RarRead work across the cuts. Close the archive with RarClose and free the volumes with RarFreeVolumes.

archive-guide-rar-volumes.salam
import archive
import compress

const VOL1 := """
526172211a0701006de128270b01050701060101808080002c64b9412502130be78600048df500a48302c8ac493d8005
0105762e7478740a0313c60bf16a7ed75827cc5dc30845643444334f3565365536a7751848c413a8c1d5a93ff0a349ca
1575f48991859458af2f2ba874489a028b323f09e3cf1e32ffefaf9f97e7e9e9e3edf6f1fa579a7a7d7c3dbdfcbebe3e
7f9f0fa7dbc3d3d3c16d1eff9ff7f7f2fd6ec95fb7f5e3f169de0de1e7efea4f755ebf7e5fe7d7f1fbe5efdec9ebf7f0
ac07f5f8f3ffbd1b1bddbb560ebd7589d7ab57eac6759257a2be6b5bff06db5907b7bfa37e2771d6115e7d65b5b1ead5
bc777f89dd96b66f649d2dbd8d5fb76ce932faf6d637ab6eb48ebc7784ebcd71b4dd9bcee1bd1377eeefbd11bfaa6188
98a280bb6b6d5a47dab204c174a6eafdbcad94b9666ab7f59414fe5a1970fab96f34eaf29a0edb711056b5ceb7494e85
b83775441bc51f56f4dc85bb03667c21d75603e2af914e76c0fb7fb5f428b8fa03bdef2854a35f5ad1273344a09bfacf
3d171047a766aa0d8c11896e85ced5a3fffcee5af7d608ba9d99ccb1aa2be1aa1342ae8b3ae9744562654f1606e38681
3201eddbf1afb701e2c1bbbff9efe02d2e17480a0962ab9b850cc218ea736bad10726ac6adab51e376d55ac13a036d61
8ec3818e63acd5ef5acb6746eae8ead37a7bb694b7a4c144844a6fa10afaf9603e08b482196964dcc8844ab4e013abdb
b4253899ef86069c3bb146ea4f805c057d5d03e101866c22c2413f3901cef35cb2faa62459ed943aafe3345d4aac4411
bb6c32bd58e376ad8393fda6c9ab56441546a250934dc2b662a55ca908f1fb6b12556784fd827901ad81c55caab012f8
0a35c584d114212450a1a8e1dc067711a39dda12659ce0d861a2ce3fafba224e2122c97cd0f5f92425ddfb9c36c9c953
6714555e7051d7dc252c7646f0df25808c58e78b266f0b92b8b917e2c910c0c3af16037381d7939fc090853cdd8df086
7370634378a2c228d4a8c0273788104daf093c9e6dccb0410dceb0215c0610eebaf222187780368a3dd2303226e99cf9
803e25ff56547e270704384ae9021fbc501683ba7cb179dcc0ae76d5600476f4c2ac82942f313d6213c24edbc0445454
d01f0c5e11d1f2ab6437eeafd08d1a3e40e3b6028205a2d7c3383a23c3fad885328bc65c5718d8d8630cfafc1b88c05c
bceb14fad1feaf94c163c9738d355824356adba1ca97a4a959832f630220a908b8b815c8b9acf685c0a255b735826132
911a80b69b45726abd4f52371614f9e267fe5840155b011bb28b47512603050401000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000
"""

const VOL2 := """
526172211a070100a9c2c4ca0c01050703010601018080800064563ccc25021b0be68600048df500a483020002230880
050105762e7478740a0313c60bf16a7ed75827046840f3834518cedc2f96f6bbb89190a3b6d9c514aacde7ee173d264c
b8f0692c7ca6b792780ee2bef245c9c3c949222294d2e016d242cd89838cbfa39edcb53775439267227627f0b5b02174
c9d22a0f2190336159b20695cd4c7113ce32dd1e2151829ab73dfea0950912309fda1d69b59f9b6e641be295e0f1f394
d8fd5c492fccc8a69b3426b4ab0d12b035942a0dfc9ca3a2401d11d385b8a8f007ead59f3e1694e6f315576c22200f28
4cd5c4a56653424b06d609611a293322bceeaf554095f3cca784064d2e5174624dd2a741e712bf8435f0a0c44458c205
f0a4b74671b82bb9635e6e10b24863da4475cc8f5a03b84b084d8bbf0834706da6cc792f4240b267a1fc20e04f3f4633
546acb84c2681dee1c00a436b6d9cccfdbffa1cad473bc7540b0002c96977021c9e8b443db4c80abd793bb7bd0d3305d
44416d504a0a9b699832d700ad111e6478d7e798ad90f492f8d248b49cd1380d23cfce8c4692ca5f5c3e8958a9b66477
c2a7d91522b7672ec51114c161dd650d948da76149d23cccc99308d707fc1db5100c4eba404d61309b83bb3c7503742b
a94a7440bae2115fd613fe21302d369c8b24bbe9c988d4eec33d9fbdc7c9038887de34419353b1bf82c0855b6c2277d6
8a8492d6e708fc7de0fa008c102633d12552fcaae7639fa3a0de6daf2336895df8a09169ed7e67ba0af51a4119c1daaa
71d7c254c05abbdab89669a40940e34742bf31a601545cdd2010c7e55016edb49cd2d7073b67d5f9ab38d9c418e76a44
f8394a65a783ab16db093629a33bd2ac91bdfb948263c08a0e4c9a4cae7af9eff46102d7bc913b5cb84a12b623a0a09f
ed11700ead0b984e3e78193ce0190ede74759a8ba34e3cee326dab0b3482d69a9af4f2e125c2d5c85cebccceb0e79c72
862a1f4252f2a18c33614af63cd523378109df9c8408d09c7e1dcc497bf400d082d87505f29af8f49a2034d6e575af9c
0e0ae77f857693f8e11cebcfb19f40a6fd1856362b74b7821b726242542b9c1c9c0add41783d931149e85a37418dba78
73ad990a9a4c7ac61b257db791159b11375886f2655cf56469191a5f853dba4f909dd88210d27dae6335450e4886e1a9
0976178ef226e03a38f420961ab7e866c8e252e62d8d1cd7eaaa2634d2747769c7a19d0e2d6c3c119034c1092a54ae36
4d4888b31633aa9473da001976173bcb5422b5d9d1922d044d8b47512603050401000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000
"""

const VOL3 := """
526172211a0701004ac54b440c0105070302060101808080004fb1c48c25020b0bfa8300048df500a4830287c98a0f80
050105762e7478740a0313c60bf16a7ed758276e9e2146d09044d59e5c974bc9e14a51910cdd41b71dcbf4f11fafd98d
16fb2d0683270a40c720ef76ab99b90b355e72e2acf71ea3c079e458b57797a810a9320e5b8f495efd066558b0974909
e6a8cff09481c66b5ee1259c3d36f48eeb7ec0f22fe946721c718c317a6058d161bf759e1c1e9a5b9427d538a4a3aade
0c326b40453c6b35b52d882e9413dbc82c5dc62160fc39a3b92dce54ac533a592fd09af8aba6fc2578f5cf12048671b2
740297a0d81a2d8f87113e877a3d3645e68034c922e7f1af8d0a794f3061e8696f2def1b8d951da84ce31a294f7c79a9
d784db31486ab60718767955e357868e61a57a866f4d072a16d82b283f8370e98ca225dd77dcf92004ea79317d93484a
62722811c2d2124f214fa55393d104c65b346abd4c63ecea91ca5bab74f0eb6af2378bc9734b8ad6ad79745d233884a7
6f99443c8e46eceeb4b9bc79895e4dedea7a4a4a2f1126126cadd27c20d3f24c0fbff173f03b3e4974014f428733869b
7f1b1916980a4335126a67984987f010b31fdcfd33edf46177414ac7a83f0909729736c70710e4bd7fb79cbf1924248d
8a2111eb874fa21f667084ea442d5950d187fd9eb2f066e09224441fbc9f32719e36176cab4d67b74200ba2c55397958
d35451df7777b403b0a724d22cb9a9a5ce7a7d72484b628b53c8b1cb893c158e558776fe1fc54ecdbc7cbe36e87c047d
942702030b8500048500a4830210c43fd080000109736d616c6c2e7478740a0313bd0bf16a5abb310b74696e790a1d77
565103050400
"""

func digit(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func from_hex(text: str): compress.ByteBuf:
    mut out := compress.NewByteBuf()
    bytes := text as u8*
    mut high := -1
    repeat text.Len() in i:
        v := digit(bytes[i] as int)
        if v < 0:
            continue
        end
        if high < 0:
            high = v
        else:
            compress.BufPush(out, high * 16 + v)
            high = -1
        end
    end
    ret out
end

func main:
    mut volumes := Vector {} as Vector<compress.ByteBuf>
    volumes.Push(from_hex(VOL1))
    volumes.Push(from_hex(VOL2))
    volumes.Push(from_hex(VOL3))

    mut arc := archive.RarOpenVolumes(volumes, "")
    mut names := archive.RarEntries(arc)
    each e in names:
        data := archive.RarRead(arc, e.name, 0)
        println e.name, e.size, data.len, archive.RarStatusText(arc.status)
    end
    archive.FreeEntries(names)
    archive.RarClose(arc)

    mut partial := Vector {} as Vector<compress.ByteBuf>
    partial.Push(volumes.Get(0))
    partial.Push(volumes.Get(1))
    mut broken := archive.RarOpenVolumes(partial, "")
    gone := archive.RarRead(broken, "v.txt", 0)
    println gone.len, broken.status == archive.RAR_MULTIVOLUME
    archive.RarClose(broken)

    archive.WriteBinaryFileBuf("set.part01.rar", volumes.Get(0))
    archive.WriteBinaryFileBuf("set.part02.rar", volumes.Get(1))
    archive.WriteBinaryFileBuf("set.part03.rar", volumes.Get(2))
    mut ok := false
    mut found := archive.RarReadVolumes("set.part01.rar", ok)
    println ok, found.Len()
    archive.RarFreeVolumes(found)
end
Outputv.txt 14989 14989 ok small.txt 5 5 ok 0 true true 3

Read a split 7z archive

7z cuts a big archive into plain pieces named name.7z.001, name.7z.002 and so on. SevenZipReadVolumes takes the first file name and loads the rest by counting up; SevenZipOpenVolumes joins the pieces and opens them as one archive. A self-extracting 7z (an executable with the archive appended) opens with SevenZipOpen directly: the signature is searched for in the first 8 MiB.

archive-guide-sevenzip-volumes.salam
import archive
import compress

const PART1 := """
377abcaf271c000457983ded16000000000000004a00000000000000429e4011766f6c756d65206f6e650a766f6c756d6520
74776f0a0104060001091600070b
"""

const PART2 := """
01000101000c1600080a014e6ded24000005011113006e006f00740065002e0074007800740000001900140a0100d9199ec4
1c70dd01150601002080a4810000
"""

func nib(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func unhex(s: str): compress.ByteBuf:
    mut b := compress.NewByteBuf()
    bp := s as u8*
    mut hi := -1
    repeat s.Len() in i:
        v := nib(bp[i] as int)
        if v < 0:
            continue
        end
        if hi < 0:
            hi = v
        else:
            compress.BufPush(b, hi * 16 + v)
            hi = -1
        end
    end
    ret b
end

func main:
    mut volumes := Vector {} as Vector<compress.ByteBuf>
    volumes.Push(unhex(PART1))
    volumes.Push(unhex(PART2))
    mut arc := archive.SevenZipOpenVolumes(volumes, "")
    names := archive.SevenZipEntries(arc)
    println "entries:", names.Len(), arc.status
    data := archive.SevenZipRead(arc, "note.txt", 0)
    print compress.BufToStrUnsafe(data)
    archive.SevenZipClose(arc)
    archive.SevenZipFreeVolumes(volumes)
end
Outputentries: 1 0 volume one volume two

One door for every format

Open reads the first bytes, finds the format and returns an Archive; List, Read, Extract and ExtractAll then work the same for every format and report one set of ARCHIVE_ codes. OpenFile, ListFile and ExtractFile do the same from a path. Gzip, bzip2 and xz files are unpacked on opening, and a tar inside is recognized, so a .tar.gz, .tar.bz2 and .tar.xz open like any other archive. The per-format functions below keep working unchanged.

FormatOpen, list, read, extractMake
zipyesCreate (.zip)
tar, tar.gz, tar.bz2, tar.zstyesCreate (.tar, .tar.gz, .tgz, .tar.bz2, .tar.zst)
tar.xzyesno encoder
gzip, bzip2, xz, zstd (one file)yes, as an archive of one entryCreate for .gz, .bz2 and .zst with exactly one file
RARyes, with a passwordCreate (.rar, stored)
7zyes, with a passwordCreate (.7z, stored)

ExtractAll is the safe way to unpack data you do not trust. Before it writes anything it checks every entry against Limits (entry count, size of one entry, size of all, and the ratio of unpacked size to archive size, which catches compression bombs) and refuses names that are absolute or climb out with .., links that leave the folder, files written through a link, and device entries. If a check fails nothing is written and status says why. The limits use the sizes the archive declares; each format still verifies the real sizes while unpacking. Multi-volume RAR and 7z sets, and large-file streaming, stay with the per-format functions.

The same calls work from a path. ListFile and ExtractFile open the file, do the job and close it; OpenFile gives you an Archive to reuse, and SetLimits tightens the Limits of one archive. Every call reports a status code, and ArchiveStatusText turns it into words. The example makes a .tar.gz, lists and extracts it, hits a limit and a missing file on purpose, and prints all fifteen codes.

archive-guide-open.salam
package main

import archive
import filepath
import os

func main:
    mut files := Vector {} as Vector<archive.FileInput>
    files.Push(archive.MakeFileInput("notes/", null, 0, true))
    files.Push(archive.MakeFileInput("notes/a.txt", "alpha alpha alpha" as void*, 17, false))
    files.Push(archive.MakeFileInput("b.txt", "bravo" as void*, 5, false))

    dir := filepath.Join(os.TempDir(), "salam-guide-open")
    os.RemoveAll(dir)
    os.MkdirAll(dir)
    path := filepath.Join(dir, "demo.tar.gz")
    println "create:", archive.ArchiveStatusText(archive.Create(path, files))
    files.Free()

    mut status := 0
    mut entries := archive.ListFile(path, "", status)
    println "list:", archive.ArchiveStatusText(status)
    each e in entries:
        println " ", e.name, e.size
    end
    archive.FreeEntries(entries)

    out := filepath.Join(dir, "out")
    n := archive.ExtractFile(path, out, "", status)
    println "extract:", n, archive.ArchiveStatusText(status)

    mut arc := archive.OpenFile(path, "")
    println archive.FormatName(arc.format), arc.status
    mut limits := archive.DefaultLimits()
    limits.max_entries = 2
    archive.SetLimits(arc, limits)
    println "tight:", archive.ExtractAll(arc, filepath.Join(dir, "tight")), archive.ArchiveStatusText(arc.status)
    archive.Close(arc)

    missing := archive.ExtractFile(filepath.Join(dir, "none.zip"), out, "", status)
    println "missing:", missing, archive.ArchiveStatusText(status)

    mut code := 0
    until code <= 14:
        println code, archive.ArchiveStatusText(code)
        code++
    end
    os.RemoveAll(dir)
end
Outputcreate: ok list: ok notes/ 0 notes/a.txt 17 b.txt 5 extract: 2 ok tar.gz 0 tight: 0 too many entries missing: 0 file could not be read or written 0 ok 1 entry not found 2 unsupported format, method or feature 3 encrypted data and no password 4 corrupt data 5 checksum mismatch 6 entry too large 7 entry path or link leaves the target folder 8 wrong password 9 a volume of the multi-volume archive is missing 10 file could not be read or written 11 unknown archive format 12 too many entries 13 compression ratio too high 14 dictionary or window larger than the memory limit
CodeConstantMeaning
0ARCHIVE_OKDone.
1ARCHIVE_NOT_FOUNDNo entry with that name.
2ARCHIVE_UNSUPPORTEDA format, method or feature the package does not read.
3ARCHIVE_ENCRYPTEDEncrypted and no password was given.
4ARCHIVE_CORRUPTThe structure is damaged or cut short.
5ARCHIVE_BAD_CRCThe checksum of the data does not match.
6ARCHIVE_TOO_BIGAn entry is over max_entry, or over what fits in memory.
7ARCHIVE_UNSAFE_PATHA name or link would leave the target folder.
8ARCHIVE_BAD_PASSWORDThe password is wrong.
9ARCHIVE_MULTIVOLUMEA volume of the set is missing.
10ARCHIVE_IO_ERRORA file could not be read or written.
11ARCHIVE_UNKNOWN_FORMATThe first bytes match no format.
12ARCHIVE_TOO_MANY_ENTRIESMore entries than max_entries.
13ARCHIVE_BOMBUnpacked size over max_ratio times the archive size.
14ARCHIVE_WINDOW_TOO_BIGThe dictionary of the compressed data is over the memory limit.

Make a 7z archive

Build SevenZipFileInput values and call SevenZipCreate or SevenZipCreateFile. Files, folders, empty files and symbolic links (set link) are written, with modes and times when you give them. SevenZipCreate stores the data; SevenZipCreateLevel and SevenZipCreateFileLevel compress each file with LZMA at levels 1 to 9. The result opens in 7-Zip and in SevenZipExtractAll.

archive-guide-sevenzip-create.salam
import archive
import compress

func main:
    a := compress.BufFromStr("first file\n")
    b := compress.BufFromStr("second file, a little longer\n")
    mut files := Vector {} as Vector<archive.SevenZipFileInput>
    files.Push(archive.MakeSevenZipFileInput("docs/", null, 0, true))
    files.Push(archive.MakeSevenZipFileInput("docs/a.txt", a.data, a.len, false))
    mut second := archive.MakeSevenZipFileInput("docs/b.txt", b.data, b.len, false)
    second.mtime = 1700000000 as i64
    second.mode = 420
    files.Push(second)
    mut link := archive.MakeSevenZipFileInput("docs/latest", null, 0, false)
    link.link = "b.txt"
    files.Push(link)
    packed := archive.SevenZipCreate(files)
    println archive.IsSevenZip(packed.data, packed.len), archive.SevenZipCreateFile(files, "made.7z")

    mut entries := archive.SevenZipList(packed.data, packed.len)
    each e in entries:
        println e.name, e.size, e.is_dir, e.kind, e.mtime
    end
    archive.FreeEntries(entries)

    mut ok := false
    got := archive.SevenZipExtractByName(packed.data, packed.len, "docs/b.txt", ok)
    println ok, compress.BufToStrUnsafe(got) == "second file, a little longer\n"
end
Outputtrue true docs 0 true 1 0 docs/a.txt 11 false 0 0 docs/b.txt 29 false 0 1700000000 docs/latest 5 false 2 0 true true

Big zip files on disk

The functions that take a pointer and a length hold the whole archive in memory, which stops at 2 GiB. For a zip of any size use ZipOpenFile: it reads only the end of the file and the list of entries, and ZipFileExtractTo and ZipFileExtractAll unpack straight to disk in 64 KiB pieces, checking the CRC-32 and the size as they go. Sizes and offsets are 64 bit, zip64 included, so an entry of several gigabytes works and memory use stays small. The only limit is the one you pass: cap is a number of bytes (0 for none), and an entry over it returns ZIP_TOO_BIG before anything is written.

archive-guide-zipfile.salam
import archive
import compress
import os

func main:
    body := "a large file would be unpacked straight to disk\n"
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("data/log.txt", body as void*, body.Len(), 8))
    mut made := archive.ZipCreate(files)
    files.Free()
    archive.WriteBinaryFileBuf("made.zip", made)
    compress.BufFree(made)

    mut zf := archive.ZipOpenFile("made.zip")
    mut entries := archive.ZipFileEntries(zf)
    each e in entries:
        println e.name, e.size
    end
    archive.FreeEntries(entries)

    println archive.ZipFileExtractTo(zf, "data/log.txt", "log.out", 0 as i64) == archive.ZIP_OK
    println archive.ZipFileExtractTo(zf, "data/log.txt", "log.out", 10 as i64) == archive.ZIP_TOO_BIG
    archive.ZipFileClose(zf)
    os.Remove("made.zip")
    os.Remove("log.out")
end
Outputdata/log.txt 48 true true

Big 7z files on disk

SevenZipOpenFile opens a 7z on disk and keeps only its header in memory. SevenZipFileExtractTo and SevenZipFileExtractAll unpack straight to disk: LZMA and LZMA2 data goes through a window as big as the dictionary and out in 64 KiB pieces, so an entry of several gigabytes needs only a few megabytes of memory. Every method streams the same way: PPMd needs only the model memory its properties ask for, bzip2 holds one block, the branch filters (BCJ, ARM, ARM64, RISC-V and the rest), delta, byte swap and BCJ2 are stages that pass each piece on, and AES-256 decrypts in pieces in front of the next coder, so AES then LZMA2 then BCJ reads straight from the file with no temporary file. Encrypted headers go through the same path. BCJ2 reads its range coder stream from the file; its call and jump streams are read from the file when stored and decoded into small buffers (at most memcap) when compressed. A solid block is read once for all of its files. cap limits the bytes of one entry and memcap the memory the decoder may use; both take 0 for no limit.

archive-guide-sevenzipfile.salam
import archive
import os

func main:
    body := "a large file would be unpacked straight to disk\n"
    mut files := Vector {} as Vector<archive.SevenZipFileInput>
    files.Push(archive.MakeSevenZipFileInput("data/log.txt", body as void*, body.Len(), false))
    archive.SevenZipCreateFile(files, "made.7z")
    files.Free()

    mut sf := archive.SevenZipOpenFile("made.7z", "")
    mut entries := archive.SevenZipFileEntries(sf)
    each e in entries:
        println e.name, e.size
    end
    archive.FreeEntries(entries)

    println archive.SevenZipFileExtractTo(sf, "data/log.txt", "log.out", 0 as i64, 0 as i64) == archive.SEVENZIP_OK
    println archive.SevenZipFileExtractTo(sf, "data/log.txt", "log.out", 10 as i64, 0 as i64) == archive.SEVENZIP_TOO_BIG
    archive.SevenZipFileClose(sf)
    os.Remove("made.7z")
    os.Remove("log.out")
end
Outputdata/log.txt 48 true true

Big tar files on disk

TarFileOpen reads a tar from disk one entry at a time: TarFileNext fills an Entry (sizes and offsets are 64 bit, so a 5 GB entry is just an entry), TarFileExtractTo copies its data to a file in 64 KiB pieces, and TarFileExtractAll unpacks the whole archive with the same safety rules as TarExtractAll. Nothing but one entry's header is ever in memory. cap is the only size limit and it is yours (0 for none): TAR_TOO_BIG means an entry is over it. TarGzFileExtractAll and GzipDecompressFileCap do the same for gzip, which is read as a stream. A compressed tar needs no temporary file: TarGzFileExtractAll, TarBz2FileExtractAll, TarXzFileExtractAll and TarZstdFileExtractAll (or TarCompressedFileExtractAll) feed the decoder's output into the tar reader piece by piece, and TarCompressedFileEntries lists one the same way.

archive-guide-tarfile.salam
import archive
import compress
import os

func main:
    body := "streamed straight from the archive\n"
    mut files := Vector {} as Vector<archive.TarFileInput>
    files.Push(archive.MakeTarFileInput("logs/a.txt", body as void*, body.Len(), false))
    files.Push(archive.MakeTarFileInput("logs/b.txt", body as void*, 10, false))
    mut made := archive.TarCreate(files)
    files.Free()
    archive.WriteBinaryFileBuf("made.tar", made)
    compress.BufFree(made)

    mut tf := archive.TarFileOpen("made.tar")
    mut e := archive.Entry {}
    until archive.TarFileNext(tf, e):
        println e.name, e.size
        if e.name == "logs/a.txt":
            println archive.TarFileExtractTo(tf, e, "a.out", 0 as i64) == archive.TAR_OK
            println archive.TarFileExtractTo(tf, e, "a.out", 5 as i64) == archive.TAR_TOO_BIG
        end
        archive.FreeEntry(e)
    end
    archive.TarFileClose(tf)

    println archive.TarFileExtractAll("made.tar", "out", 0 as i64) == archive.TAR_OK
    os.RemoveAll("out")
    os.Remove("made.tar")
    os.Remove("a.out")
end
Outputlogs/a.txt 35 true true logs/b.txt 10 true

Big RAR files on disk

RarFileOpen reads a RAR 5 file's headers only (offsets and sizes are 64 bit); RarFileExtractTo and RarFileExtractAll then unpack to disk, writing the result in pieces and checking the CRC-32 as they go. Compressed entries, solid archives and the built-in filters work. What is held in memory is the packed data of one entry and the decoder window, so the unpacked size can be anything: an entry of several gigabytes is unpacked from a file of a few megabytes in constant memory. The size limits are yours: cap for the unpacked bytes and memcap for that memory, and RAR_TOO_BIG means one of them was passed, and RAR_WINDOW_TOO_BIG that the data needs a window bigger than memcap or 1 GiB. Passwords and volumes work from disk too: RarFileOpenWith opens archives with encrypted files or file names, and RarFileOpenVolumes a set of volumes, decrypting and joining pieces as it unpacks. RarFileExtractAll restores permissions and times and creates safe symbolic links. Older RAR formats (1.5 to 4.x) work the same way, passwords, encrypted file names and volumes included: the packed data is read from the file in pieces and the unpacked data goes to disk in pieces (the VM filters are applied on the way), so an entry or a volume over 4 GiB works with a few megabytes of memory (sizes and offsets are 64 bit, including the high size fields of the headers). Only entries encrypted with the very old RAR 1.5 or 2.0 ciphers still need their packed data in memory, up to 256 MiB.

archive-guide-rarfile.salam
import archive
import os

func main:
    body := "read from a RAR on disk, entry by entry\n"
    mut files := Vector {} as Vector<archive.RarFileInput>
    files.Push(archive.MakeRarFileInput("notes/a.txt", body as void*, body.Len(), false))
    archive.RarCreateFile(files, "made.rar")
    files.Free()

    mut rf := archive.RarFileOpen("made.rar")
    println rf.status == archive.RAR_OK, rf.streaming
    mut entries := archive.RarFileEntries(rf)
    each e in entries:
        println e.name, e.size
    end
    archive.FreeEntries(entries)

    println archive.RarFileExtractTo(rf, "notes/a.txt", "a.out", 0 as i64, 0 as i64) == archive.RAR_OK
    println archive.RarFileExtractTo(rf, "notes/a.txt", "a.out", 5 as i64, 0 as i64) == archive.RAR_TOO_BIG
    archive.RarFileClose(rf)
    os.Remove("made.rar")
    os.Remove("a.out")
end
Outputtrue true notes/a.txt 40 true true

Which function for which job

JobUse
Files for Windows users or a browser downloadZipCreate, ZipCreateFile
A backup or a release bundle on UnixTarGzCreate or TarGzCreateFile
See what is insideZipList, TarList, RarList, then FreeEntries
One file out of an archiveZipExtractByName, TarExtractByName
Everything into a folderZipExtractAll, TarExtractAll
A RAR fileRarList, RarExtract (or RarExtractByName), RarExtractAll; RarCreate to make one
A 7z archive, with or without a password; SevenZipCreate makes one (stored)SevenZipList, SevenZipExtractByName, SevenZipExtractAll; SevenZipOpen, SevenZipEntries, SevenZipRead, SevenZipReadAll when it has a password
A single compressed file (.gz)GzipCompressFile, GzipDecompressFile
A single .xz or .lzma fileXzCompressFile, XzDecompressFile, LzmaCompressFile, LzmaDecompressFile
A single file, smaller than gzip (.bz2)Bzip2CompressFile, Bzip2DecompressFile
A single file in Zstandard (.zst)ZstdCompressFile, ZstdDecompressFile
Check that an archive is intactzip: ZipVerify, ZipExtractVerified; gzip and RAR check themselves; see "Check an archive"
A password-protected or multi-volume RARRarOpen, RarOpenVolumes, then RarEntries, RarRead, RarReadAll
Bytes from and to diskReadBinaryFile, WriteBinaryFileBuf

Types

ZipFile

struct ZipFile
A zip file on disk opened with ZipOpenFile. Only the central directory (the list of entries) is kept in memory; the data stays in the file.
NameTypeDescription
pathstr = ""The path the archive was opened from.
counti64 = 0The number of entries.
sizei64 = 0The size of the file in bytes.
statusint = 0ZIP_OK when the archive opened, otherwise the reason.
passwordstr = ""The password set by ZipFileSetPassword, or an empty string.
cdcompress.ByteBufThe central directory as read from the file. Treat it as private; it is only public so the package can fill it.
volumesVectorThe pieces of a split archive in order, or an empty list for an ordinary file.
startsVectorThe offset of each piece in the joined archive. Treat it as private.
by_diskbool = falseTrue when the pieces are .z01 style and the offsets in the directory are relative to a piece. Treat it as private.
cd_starti64 = 0Where the central directory starts in the joined archive. Treat it as private.
archive-ZipFile.salam
import archive
import compress
import os

func main:
    body := "a large file would be unpacked straight to disk\n"
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("data/log.txt", body as void*, body.Len(), 8))
    mut made := archive.ZipCreate(files)
    files.Free()
    archive.WriteBinaryFileBuf("made.zip", made)
    compress.BufFree(made)

    mut zf := archive.ZipOpenFile("made.zip")
    mut entries := archive.ZipFileEntries(zf)
    each e in entries:
        println e.name, e.size
    end
    archive.FreeEntries(entries)

    println archive.ZipFileExtractTo(zf, "data/log.txt", "log.out", 0 as i64) == archive.ZIP_OK
    println archive.ZipFileExtractTo(zf, "data/log.txt", "log.out", 10 as i64) == archive.ZIP_TOO_BIG
    archive.ZipFileClose(zf)
    os.Remove("made.zip")
    os.Remove("log.out")
end
Outputdata/log.txt 48 true true

SevenZipArchive

struct SevenZipArchive
A 7z archive in memory and the password to open it with; SevenZipOpen makes one. Nothing is copied or read until you call a function on it.
NameTypeDescription
datavoid*The memory address of the archive.
lenint = 0The length of the archive in bytes.
passwordstr = ""The password, or an empty string.
statusint = 0How the last call went: SEVENZIP_OK or one of the other codes.
ownvoid*The joined volumes, when the archive was made by SevenZipOpenVolumes.
archive-SevenZip.salam
import archive
import compress

const ENCRYPTED := """
377abcaf271c000492b1434900010000000000003e0000000000000075a266e9cc0ca30fca42d412a3e1dd1194db4dd8fc
e2cf1a1d4df4ce0ca88687e1ab395abaa1bbe78d42aa044be8e9373779efdfd2ddd634772d8f0c62fa54d113cc6b3ac143
47c180a90a35752ec2feffd2b46d3a9a3c870cb0fe3a0a301165c3ad2ab69243d4c4aa154bf810ebf8b3e5988d6a3a9e4e
59bd2f4e7ad24baf35ba6aaad91e0b0a82e28a8c70941e255f48219088e4a3df6ae61451a7a0ad953c0d9e191005562c55
a4351cc71942b1bc90035da6a20467642f8d730da31f7a96c473e6f1986d738ecaaf865bbc4984c08559da1d3ace6c445a
6c34f94739a978d845b0f96290becff7b72085916669b917dbc847e2c2f359083aad6a78ac2674231153cb170650010980
b000070b0100022406f1070112530fd1de53f747a979d2abd82144f9abe78423030101055d0010000001000c80ad80de0a
0178dd34010000
"""

func nib(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func unhex(s: str): compress.ByteBuf:
    mut b := compress.NewByteBuf()
    bp := s as u8*
    mut hi := -1
    repeat s.Len() in i:
        v := nib(bp[i] as int)
        if v < 0:
            continue
        end
        if hi < 0:
            hi = v
        else:
            compress.BufPush(b, hi * 16 + v)
            hi = -1
        end
    end
    ret b
end

func main:
    packed := unhex(ENCRYPTED)
    mut arc := archive.SevenZipOpen(packed.data, packed.len, "")
    mut names := archive.SevenZipEntries(arc)
    println "no password:", names.Len(), arc.status, archive.SevenZipStatusText(arc.status)

    arc = archive.SevenZipOpen(packed.data, packed.len, "wrong")
    names = archive.SevenZipEntries(arc)
    println "wrong password:", names.Len(), arc.status == archive.SEVENZIP_BAD_PASSWORD

    arc = archive.SevenZipOpen(packed.data, packed.len, "secret")
    names = archive.SevenZipEntries(arc)
    println "right password:", names.Len(), arc.status == archive.SEVENZIP_OK
    repeat names.Len() in i:
        e := names.Get(i)
        println " ", e.name, e.size, e.mode, e.mtime
    end

    data := archive.SevenZipRead(arc, "src/main.salam", 0)
    println compress.BufToStrUnsafe(data)
    missing := archive.SevenZipRead(arc, "nothing.txt", 0)
    println "missing:", arc.status == archive.SEVENZIP_NOT_FOUND, missing.len
    big := archive.SevenZipRead(arc, "readme.txt", 10)
    println "too big:", arc.status == archive.SEVENZIP_TOO_BIG, big.len

    println "unsupported:", archive.SevenZipStatusText(archive.SEVENZIP_UNSUPPORTED)
    println "corrupt:", archive.SevenZipStatusText(archive.SEVENZIP_CORRUPT)
    println "bad crc:", archive.SevenZipStatusText(archive.SEVENZIP_BAD_CRC)
    println "unsafe:", archive.SevenZipStatusText(archive.SEVENZIP_UNSAFE_PATH)
    println "list:", archive.SevenZipList(packed.data, packed.len).Len()
    println "extract:", archive.SevenZipExtract(packed.data, packed.len, "readme.txt", 0, arc.status).len, arc.status
end
Outputno password: 0 3 encrypted data and no password wrong password: 0 true right password: 4 true src 0 493 1700000000 empty.log 0 420 1700000000 readme.txt 120 420 1700000000 src/main.salam 35 420 1700000000 func main: println "salam" end missing: true 0 too big: true 0 unsupported: unsupported format, method or feature corrupt: corrupt data bad crc: checksum mismatch unsafe: entry path or link leaves the target folder list: 0 extract: 0 3

TarFileInput

struct TarFileInput
One file to put in a tar.
NameTypeDescription
namestr = ""The name inside the archive. A name over 100 bytes goes into the ustar prefix or a PAX record, so any length is kept.
data_ptrvoid*The address of the contents.
data_lenint = 0The length of the contents.
is_dirbool = falseThe input is a directory.
modeint = 0File permissions, such as 0o755. Zero means the usual ones.
mtimei64 = 0The modification time in seconds since the Unix epoch; zero by default.
linkstr = ""The target of a symbolic or hard link entry; ignored for other kinds.
kindint = 00 for a file or folder (see is_dir), 2 for a symbolic link, 3 for a hard link.
pathstr = ""A file to read the contents from when the archive is written; used instead of data_ptr for a normal file entry.
archive-Tar.salam
import archive
import compress

func main:
    b := compress.BufFromStr("first line\nsecond line\n")
    mut files := Vector {} as Vector<archive.TarFileInput>
    files.Push(archive.MakeTarFileInput("notes", null, 0, true))
    files.Push(archive.MakeTarFileInput("notes/a.txt", b.data, b.len, false))
    t := archive.TarCreate(files)
    println t.len % 512
    mut entries := archive.TarList(t.data, t.len)
    each e in entries:
        println e.name, e.size, e.is_dir
    end
    archive.FreeEntries(entries)
    mut ok := false
    a := archive.TarExtractByName(t.data, t.len, "notes/a.txt", ok)
    println ok, compress.BufToStrUnsafe(a)
    println archive.TarCreateFile(files, "out.tar"), archive.TarExtractAll(t.data, t.len, "untarred")
    println archive.GzipCompressFile("out.tar", "out.tar.gz"), archive.GzipDecompressFile("out.tar.gz", "back.tar")
    back := archive.ReadBinaryFile("back.tar", ok)
    println ok, back.len == t.len
    archive.EnsureDir("a/b/c")
    println archive.WriteBinaryFile("a/b/c/x.bin", b.data, 3), archive.WriteBinaryFileBuf("a/b/c/y.bin", b)
    mut b2 := compress.NewByteBuf()
    archive.LEPut16(b2, 513)
    archive.LEPut32(b2, 70000)
    println archive.LEGet16(b2.data, 0), archive.LEGet32(b2.data, 2)
end
Output0 notes 0 true notes/a.txt 23 false true first line second line true true true true true true true true 513 70000

TarFile

struct TarFile
A tar file on disk opened with TarFileOpen and read one entry at a time. The archive is never loaded into memory.
NameTypeDescription
pathstr = ""The path the archive was opened from.
sizei64 = 0The size of the file in bytes.
statusint = 0TAR_OK while reading works, otherwise the reason it stopped.
posi64 = 0The offset of the next header (64 bit).
data_offi64 = 0The offset of the data of the entry TarFileNext returned last (64 bit).
fpvoid*The open file handle.
g_TarPaxThe state of PAX global headers while reading.
archive-TarFile.salam
import archive
import compress
import os

func main:
    body := "streamed straight from the archive\n"
    mut files := Vector {} as Vector<archive.TarFileInput>
    files.Push(archive.MakeTarFileInput("logs/a.txt", body as void*, body.Len(), false))
    files.Push(archive.MakeTarFileInput("logs/b.txt", body as void*, 10, false))
    mut made := archive.TarCreate(files)
    files.Free()
    archive.WriteBinaryFileBuf("made.tar", made)
    compress.BufFree(made)

    mut tf := archive.TarFileOpen("made.tar")
    mut e := archive.Entry {}
    until archive.TarFileNext(tf, e):
        println e.name, e.size
        if e.name == "logs/a.txt":
            println archive.TarFileExtractTo(tf, e, "a.out", 0 as i64) == archive.TAR_OK
            println archive.TarFileExtractTo(tf, e, "a.out", 5 as i64) == archive.TAR_TOO_BIG
        end
        archive.FreeEntry(e)
    end
    archive.TarFileClose(tf)

    println archive.TarFileExtractAll("made.tar", "out", 0 as i64) == archive.TAR_OK
    os.RemoveAll("out")
    os.Remove("made.tar")
    os.Remove("a.out")
end
Outputlogs/a.txt 35 true true logs/b.txt 10 true

Entry

struct Entry
One archive entry.
NameTypeDescription
namestr = ""The name and path inside the archive.
sizei64 = 0The original size in bytes.
compressed_sizei64 = 0The compressed size.
is_dirbool = falseThe entry is a directory.
methodint = 0The compression method: zero for plain storage, 8 for DEFLATE, 12 for bzip2, 14 for LZMA, 93 for zstd.
crc32u32 = 0The checksum of the contents.
mtimei64 = 0The modification time in seconds since the Unix epoch: from a tar header, a RAR header, or for zip the DOS date and time read as UTC (0 when the entry has none).
linkstr = ""The target of a tar symbolic or hard link, otherwise empty.
kindint = 0What a tar entry is: 0 file, 1 folder, 2 symbolic link, 3 hard link, 4 other (device, pipe). Zip and RAR entries are 0 or 1; 7z entries are 0, 1 or 2 (a symbolic link, with its target in link).
modeint = 0The permission bits of a tar entry, such as 0o644; 0 for zip and RAR entries.
archive-Zip.salam
import archive
import compress

func main:
    text := "hello archive, hello archive, hello archive"
    b := compress.BufFromStr(text)
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("docs/", null, 0, 0))
    files.Push(archive.MakeZipFileInput("docs/a.txt", b.data, b.len, 8))
    files.Push(archive.MakeZipFileInput("b.txt", b.data, 5, 0))
    z := archive.ZipCreate(files)
    mut entries := archive.ZipList(z.data, z.len)
    each e in entries:
        println e.name, e.size, e.compressed_size < e.size, e.is_dir, e.method
    end
    archive.FreeEntries(entries)
    mut ok := false
    a := archive.ZipExtractByName(z.data, z.len, "docs/a.txt", ok)
    println ok, compress.BufToStrUnsafe(a) == text
    _ := archive.ZipExtractByName(z.data, z.len, "missing", ok)
    println ok
    small := archive.ZipExtractByNameMax(z.data, z.len, "docs/a.txt", 10, ok)
    println ok, small.len
    whole := archive.ZipExtractByNameMax(z.data, z.len, "docs/a.txt", 100, ok)
    println ok, whole.len
    println archive.ZipCreateFile(files, "out.zip"), archive.ZipExtractAll(z.data, z.len, "unzipped")
    read := archive.ReadBinaryFile("unzipped/docs/a.txt", ok)
    println ok, read.len == b.len
    println archive.IsRar(z.data, z.len), archive.RarList(z.data, z.len).Len()
    _ := archive.RarExtractByName(z.data, z.len, "x", ok)
    println ok, archive.RarExtractAll(z.data, z.len, "rar-out")
end
Outputdocs/ 0 false true 0 docs/a.txt 43 true false 8 b.txt 5 false false 0 true true false false 0 true 43 true true true true false 0 false true

SevenZipFileInput

struct SevenZipFileInput
One file, folder or symbolic link to put in a 7z archive.
NameTypeDescription
namestr = ""The name inside the archive; use / between folders. A trailing slash is dropped.
data_ptrvoid*The address of the contents.
data_lenint = 0The length of the contents. An entry with no contents is stored as an empty file.
is_dirbool = falseTrue for a folder entry; it has no contents.
mtimei64 = 0The modification time in seconds since the Unix epoch, or 0 to leave it out.
modeint = 0The Unix permission bits (for example 420 for 0644), or 0 to leave them out.
linkstr = ""The target of a symbolic link. When it is not empty the entry is a link and the contents are ignored.
pathstr = ""A file to read the contents from when the archive is written; used instead of data_ptr.
archive-SevenZipCreate.salam
import archive
import compress

func main:
    a := compress.BufFromStr("first file\n")
    b := compress.BufFromStr("second file, a little longer\n")
    mut files := Vector {} as Vector<archive.SevenZipFileInput>
    files.Push(archive.MakeSevenZipFileInput("docs/", null, 0, true))
    files.Push(archive.MakeSevenZipFileInput("docs/a.txt", a.data, a.len, false))
    mut second := archive.MakeSevenZipFileInput("docs/b.txt", b.data, b.len, false)
    second.mtime = 1700000000 as i64
    second.mode = 420
    files.Push(second)
    mut link := archive.MakeSevenZipFileInput("docs/latest", null, 0, false)
    link.link = "b.txt"
    files.Push(link)
    packed := archive.SevenZipCreate(files)
    println archive.IsSevenZip(packed.data, packed.len), archive.SevenZipCreateFile(files, "made.7z")

    mut entries := archive.SevenZipList(packed.data, packed.len)
    each e in entries:
        println e.name, e.size, e.is_dir, e.kind, e.mtime
    end
    archive.FreeEntries(entries)

    mut ok := false
    got := archive.SevenZipExtractByName(packed.data, packed.len, "docs/b.txt", ok)
    println ok, compress.BufToStrUnsafe(got) == "second file, a little longer\n"
end
Outputtrue true docs 0 true 1 0 docs/a.txt 11 false 0 0 docs/b.txt 29 false 0 1700000000 docs/latest 5 false 2 0 true true

RarFile

struct RarFile
A RAR file on disk opened with RarFileOpen. Only the headers are read; the data stays in the file and is unpacked straight to disk, for RAR 5 and for the older formats (1.5 to 4.x) alike. The older formats are read in pieces too; only entries encrypted with the RAR 1.5 or 2.0 ciphers hold their packed data in memory (up to 256 MiB).
NameTypeDescription
pathstr = ""The path the archive was opened from.
sizei64 = 0The size of the file in bytes.
statusint = 0RAR_OK when the archive opened, otherwise the reason.
streamingbool = falseTrue when the archive is read from disk without loading it (every RAR format).
arc_RarArcThe parsed entry table. Treat it as private.
offsVectorThe 64 bit offset of each entry's data in the file. Treat it as private.
wholecompress.ByteBufThe file contents of an archive that had to be loaded whole (a self-extracting file with a stub in front, under 2 GB). Empty otherwise.
passwordstr = ""The password given to RarFileOpenWith or RarFileOpenVolumes. Treat it as private.
vols_RarVolsThe list of volume paths and the pieces of each entry. Treat it as private.
archive-RarFile.salam
import archive
import os

func main:
    body := "read from a RAR on disk, entry by entry\n"
    mut files := Vector {} as Vector<archive.RarFileInput>
    files.Push(archive.MakeRarFileInput("notes/a.txt", body as void*, body.Len(), false))
    archive.RarCreateFile(files, "made.rar")
    files.Free()

    mut rf := archive.RarFileOpen("made.rar")
    println rf.status == archive.RAR_OK, rf.streaming
    mut entries := archive.RarFileEntries(rf)
    each e in entries:
        println e.name, e.size
    end
    archive.FreeEntries(entries)

    println archive.RarFileExtractTo(rf, "notes/a.txt", "a.out", 0 as i64, 0 as i64) == archive.RAR_OK
    println archive.RarFileExtractTo(rf, "notes/a.txt", "a.out", 5 as i64, 0 as i64) == archive.RAR_TOO_BIG
    archive.RarFileClose(rf)
    os.Remove("made.rar")
    os.Remove("a.out")
end
Outputtrue true notes/a.txt 40 true true

SevenZipFile

struct SevenZipFile
A 7z file on disk opened with SevenZipOpenFile. Only the list of entries (the header) is kept in memory; the data stays in the file.
NameTypeDescription
pathstr = ""The path the archive was opened from.
sizei64 = 0The size of the file in bytes.
starti64 = 0Where the archive begins in the file; not zero for a self-extracting program.
passwordstr = ""The password, or an empty string.
statusint = 0SEVENZIP_OK when the archive opened, otherwise the reason.
hdrcompress.ByteBufThe decoded header. Treat it as private; it is only public so the package can fill it.
volumesVectorThe paths of the pieces when the archive was opened from name.7z.001; one entry otherwise. The pieces are read in place and never joined in memory.
mempvoid*The archive bytes when the package reads an in-memory archive from SevenZipOpen through this type; null for an archive opened from a file. Treat it as private; it is only public so the package can fill it.
memni64 = 0The length of those bytes, 0 for a file. Private like memp.
archive-SevenZipFile.salam
import archive
import os

func main:
    body := "a large file would be unpacked straight to disk\n"
    mut files := Vector {} as Vector<archive.SevenZipFileInput>
    files.Push(archive.MakeSevenZipFileInput("data/log.txt", body as void*, body.Len(), false))
    archive.SevenZipCreateFile(files, "made.7z")
    files.Free()

    mut sf := archive.SevenZipOpenFile("made.7z", "")
    mut entries := archive.SevenZipFileEntries(sf)
    each e in entries:
        println e.name, e.size
    end
    archive.FreeEntries(entries)

    println archive.SevenZipFileExtractTo(sf, "data/log.txt", "log.out", 0 as i64, 0 as i64) == archive.SEVENZIP_OK
    println archive.SevenZipFileExtractTo(sf, "data/log.txt", "log.out", 10 as i64, 0 as i64) == archive.SEVENZIP_TOO_BIG
    archive.SevenZipFileClose(sf)
    os.Remove("made.7z")
    os.Remove("log.out")
end
Outputdata/log.txt 48 true true

ZipFileInput

struct ZipFileInput
One file to put in a zip.
NameTypeDescription
namestr = ""The name inside the archive; a directory name ends with /. Use / between folders, never \.
data_ptrvoid*The address of the contents.
data_lenint = 0The length of the contents.
methodint = 8Zero for plain storage, 8 for DEFLATE, 12 for bzip2, 14 for LZMA or 93 for zstd. Any other number stores the data, and so does an empty entry.
mtimei64 = 0The modification time in seconds since the Unix epoch. Zero, or a time before 1980, writes 1 January 1980; the DOS format cannot go past 2107 and keeps two second steps.
levelint = 0The compression level for bzip2 (1 to 9, default 9), LZMA (1 to 9, default 6) or zstd (1 to 22, default 3). Zero picks the default; DEFLATE and plain storage ignore it.
pathstr = ""A file to read the contents from when the archive is written; used instead of data_ptr. With ZipCreateFile the entry is read and compressed in pieces, so it is never held whole in memory: DEFLATE uses a data descriptor, and bzip2, LZMA and zstd entries are written with a placeholder size that is patched in the local header once the entry is done.
passwordstr = ""The password for this entry; empty means no encryption.
encryptionint = 0ZipEncAuto (0, AES-256 when there is a password), ZipEncZipCrypto (1, the old weak zip encryption), ZipEncAes128, ZipEncAes192 or ZipEncAes256 (WinZip AES, version AE-2). unzip reads only ZipCrypto; 7-Zip and WinZip read both.
archive-Fields.salam
import archive
import compress

func main:
    text := "fields of an entry, fields of an entry"
    b := compress.BufFromStr(text)

    mut zin := Vector {} as Vector<archive.ZipFileInput>
    zin.Push(archive.ZipFileInput { name = "docs/", data_ptr = null, data_len = 0, method = 0 })
    zin.Push(archive.ZipFileInput { name = "docs/a.txt", data_ptr = b.data, data_len = b.len, method = 8 })
    z := archive.ZipCreate(zin)
    mut zentries := archive.ZipList(z.data, z.len)
    each e in zentries:
        println e.name, e.size, e.compressed_size <= e.size, e.is_dir, e.method, e.crc32 == compress.CRC32Buf(b) or e.is_dir, e.mtime >= 0
    end
    archive.FreeEntries(zentries)

    mut tin := Vector {} as Vector<archive.TarFileInput>
    tin.Push(archive.TarFileInput { name = "notes/", data_ptr = null, data_len = 0, is_dir = true })
    tin.Push(archive.TarFileInput { name = "notes/a.txt", data_ptr = b.data, data_len = b.len, is_dir = false })
    t := archive.TarCreate(tin)
    mut tentries := archive.TarList(t.data, t.len)
    each e in tentries:
        println e.name, e.size, e.is_dir
    end
    archive.FreeEntries(tentries)
end
Outputdocs/ 0 true true 0 true true docs/a.txt 38 true false 8 true true notes/ 0 true notes/a.txt 38 false

Limits

struct Limits
The caps that ExtractAll and Open enforce.
NameTypeDescription
max_entriesint = 100000The most entries an archive may have; 0 means no cap. Default 100000.
max_entryi64 = 1073741824The most bytes one entry may unpack to; 0 means no cap. Default 1 GiB.
max_totali64 = 4294967296The most bytes all entries together may unpack to, also the cap for unwrapping gzip, bzip2 and xz. Default 4 GiB.
max_ratioint = 5000The most the unpacked total may exceed the archive size, as a multiple (plus 1 MiB of slack); 0 turns the check off. Default 5000.
archive-Open.salam
/*
 * Salam Programming Language (2024-2026)
 *
 *   +-------------------+
 *   |     S A L A M     |
 *   +-------------------+
 *
 * Designed by Seyyed Ali Mohammadiyeh and the Salam Team
 * Born from a decade of language design experience (since 2018)
 *
 * Repository: https://github.com/SalamLang/Salam
 *
 */

package main

import archive
import compress
import filepath
import os

func main:
    mut files := Vector {} as Vector<archive.FileInput>
    files.Push(archive.MakeFileInput("docs/", null, 0, true))
    files.Push(archive.MakeFileInput("docs/a.txt", "hello hello hello hello" as void*, 23, false))
    files.Push(archive.MakeFileInput("b.txt", "bee" as void*, 3, false))

    mut status := 0
    mut built := archive.CreateBuf(archive.FormatTarGz, files, status)
    println status, archive.FormatName(archive.Detect(built.data, built.len))

    mut arc := archive.Open(built.data, built.len, "")
    println archive.FormatName(arc.format), arc.status
    mut entries := archive.List(arc)
    each e in entries:
        println e.name, e.size, e.is_dir
    end
    archive.FreeEntries(entries)

    mut data := archive.Read(arc, "docs/a.txt")
    println arc.status, compress.BufToStrUnsafe(data)
    compress.BufFree(data)
    mut missing := archive.Read(arc, "nope.txt")
    println arc.status, archive.ArchiveStatusText(arc.status)
    compress.BufFree(missing)

    dest := filepath.Join(os.TempDir(), "salam-open-demo")
    n := archive.ExtractAll(arc, dest)
    println n, archive.ArchiveStatusText(arc.status), os.Exists(filepath.Join(dest, "docs/a.txt"))
    os.RemoveAll(dest)

    mut tight := archive.DefaultLimits()
    tight.max_entries = 2
    mut small := archive.OpenWith(built.data, built.len, "", tight)
    println archive.ExtractAll(small, dest), archive.ArchiveStatusText(small.status)
    archive.Close(small)
    archive.Close(arc)

    println archive.DetectName("backup.tgz") == archive.FormatTarGz, archive.DetectName("notes.txt") == archive.FormatUnknown
    compress.BufFree(built)
    files.Free()
end
Output0 gzip tar.gz 0 docs/ 0 true docs/a.txt 23 false b.txt 3 false 0 hello hello hello hello 1 entry not found 2 ok true 0 too many entries true true

Archive

struct Archive
An opened archive of any format, made by Open, OpenWith or OpenFile. Free it with Close.
NameTypeDescription
datavoid*The address of the archive bytes (not owned, unless read whole by OpenFile). Null for an archive that OpenFile keeps on disk.
lenint = 0The length of the archive bytes.
passwordstr = ""The password given to Open.
formatint = 0The detected format, one of the Format codes.
statusint = 0The ARCHIVE_ code of the last call.
limitsLimitsThe caps in force.
namestr = "data"The name of the one entry in a single-stream file (.gz, .bz2, .xz), taken from the file name by OpenFile; otherwise data.
failint = 0Why the archive could not be opened, or 0.
innercompress.ByteBufThe unpacked bytes of a gzip, bzip2 or xz file, owned by the archive.
filecompress.ByteBufThe file contents, when a file was read whole by OpenFile.
diskint = 0Which on-disk reader an archive opened by OpenFile uses: 1 zip, 2 7z, 3 tar, 4 RAR, 5 tar.gz (decoded as a stream), and 0 when the archive is in memory.
tmpstr = ""Always empty now; a tar.gz opened by OpenFile is read as a stream and no temporary file is made.
gzpathstr = ""The path of a tar.gz that OpenFile reads as a stream (disk 5); empty otherwise.
zfZipFileThe ZipFile behind a zip opened by OpenFile.
szSevenZipFileThe SevenZipFile behind a 7z opened by OpenFile.
tfTarFileThe TarFile behind a tar or tar.gz opened by OpenFile.
rfRarFileThe RarFile behind a RAR opened by OpenFile.

The example for this item is shown with the ones above: archive-Open.salam

FileInput

struct FileInput
One file to put in an archive with Create or CreateBuf.
NameTypeDescription
namestr = ""The name inside the archive. It must be a safe relative path.
data_ptrvoid*The address of the contents.
data_lenint = 0The length of the contents.
is_dirbool = falseThe entry is a folder.

The example for this item is shown with the ones above: archive-Open.salam

RarFileInput

struct RarFileInput
One file to put in a RAR.
NameTypeDescription
namestr = ""The name inside the archive; a directory name ends with /. Use / between folders, never \.
data_ptrvoid*The address of the contents.
data_lenint = 0The length of the contents.
is_dirbool = falseTrue for a directory entry; it has no contents.
mtimei64 = 0The modification time in seconds since the Unix epoch, or 0 to leave it out.
archive-Rar.salam
import archive
import compress

func main:
    a := compress.BufFromStr("first file\n")
    b := compress.BufFromStr("second file, a little longer\n")
    mut files := Vector {} as Vector<archive.RarFileInput>
    files.Push(archive.MakeRarFileInput("docs/", null, 0, true))
    files.Push(archive.MakeRarFileInput("docs/a.txt", a.data, a.len, false))
    mut second := archive.MakeRarFileInput("docs/b.txt", b.data, b.len, false)
    second.mtime = 1700000000 as i64
    files.Push(second)
    r := archive.RarCreate(files)
    println archive.IsRar(r.data, r.len), archive.RarCreateFile(files, "made.rar")

    mut entries := archive.RarList(r.data, r.len)
    each e in entries:
        println e.name, e.size, e.is_dir, e.mtime
    end
    archive.FreeEntries(entries)

    mut status := 0
    got := archive.RarExtract(r.data, r.len, "docs/b.txt", 0, status)
    println status == archive.RAR_OK, compress.BufToStrUnsafe(got) == "second file, a little longer\n"
    _ := archive.RarExtract(r.data, r.len, "docs/none.txt", 0, status)
    println status == archive.RAR_NOT_FOUND, archive.RarStatusText(status)

    mut ok := false
    small := archive.RarExtractByNameMax(r.data, r.len, "docs/b.txt", 5, ok)
    println ok, small.len
    println archive.RarStatusText(archive.RAR_TOO_BIG)

    n := archive.RarExtractAllStatus(r.data, r.len, "rar-out", status)
    println n, archive.RarStatusText(status)

    bad := compress.BufClone(r)
    p := bad.data as u8*
    p[bad.len - 15] = ((p[bad.len - 15] as int) ^ 1) as u8
    _ := archive.RarExtract(bad.data, bad.len, "docs/b.txt", 0, status)
    println status == archive.RAR_BAD_CRC, archive.RarStatusText(status)
end
Outputtrue true docs 0 true 0 docs/a.txt 11 false 0 docs/b.txt 29 false 1700000000 true true true entry not found false 0 entry too large 3 ok true checksum mismatch

RarArchive

struct RarArchive
A RAR archive in memory together with the password to open it. Build one with RarOpen.
NameTypeDescription
datavoid*The address of the archive bytes.
lenint = 0The length of the archive.
passwordstr = ""The password, or an empty string for none.
statusint = 0The result of the last RarEntries, RarRead or RarReadAll call, one of the RAR_ codes.
moreVectorThe volumes after the first one, when the archive was opened with RarOpenVolumes.
archive-RarPassword.salam
import archive
import compress

const SAMPLE := """
526172211a07010038d1db9021040000010fe945634161dc2d7b3e8b87f362874d32048313f00358e483efb2886b026e
590dc3a9e23be3b7cfa25ea1dd6a6c4c4af8702cb2d51eb2f7798221661b321c792f762b84ffbf221b7100d324e8f848
ca96b61074ef27c65ba5a760024e3e27ccd59be9d8047bce7da160956a1dd1ca59d5970613a92c4582b076eb3398a1b7
8ef8151f33cf3665dea91210eaede8f1c08f503c488358eb375bf44e0a7a90b81067d6a6637ae589c00f19b387d3d769
f8cfa327f9b218211f11fe63a7a1783e45656fcc9573869eaf359485c0e2d4d5066ddc9981c7b13390c6d78d0ea24a04
386db10eb6d52567002ad55ebee7f1a172080c6a7bd1c72ac29e74d0480d38934012ee49a5fcd5111ad5899223384b67
b8491eed31431d7295083a332114430d96e4004c3426c450dbd1985644df90632ebb89c94cb9f9000fe8b54e0335aa44
fe401e45aad3727aee1392db44b09094b58754bc5ae4fd2186aeb6790bbf2dc3a4225dd37203f3eeecf02fcfb2f150a1
4293fbab1e38425c7bdd1909e3b24e6882fb38344a28184e8d993d93616aeb3eb57e60b5681280a7d138329a4cda
"""

func digit(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func from_hex(text: str): compress.ByteBuf:
    mut out := compress.NewByteBuf()
    bytes := text as u8*
    mut high := -1
    repeat text.Len() in i:
        v := digit(bytes[i] as int)
        if v < 0:
            continue
        end
        if high < 0:
            high = v
        else:
            compress.BufPush(out, high * 16 + v)
            high = -1
        end
    end
    ret out
end

func main:
    rar := from_hex(SAMPLE)
    mut locked := archive.RarOpen(rar.data, rar.len, "")
    mut names := archive.RarEntries(locked)
    println names.Len(), archive.RarStatusText(locked.status)
    archive.FreeEntries(names)

    mut wrong := archive.RarOpen(rar.data, rar.len, "guess")
    names = archive.RarEntries(wrong)
    println names.Len(), wrong.status == archive.RAR_BAD_PASSWORD
    archive.FreeEntries(names)

    mut arc := archive.RarOpen(rar.data, rar.len, "secret")
    names = archive.RarEntries(arc)
    each e in names:
        data := archive.RarRead(arc, e.name, 0)
        println e.name, e.size, data.len, archive.RarStatusText(arc.status)
    end
    archive.FreeEntries(names)
    println archive.RarReadAll(arc, "unlocked"), archive.RarStatusText(arc.status)
end
Output0 encrypted data and no password 0 true n1.txt 352 352 ok n2.txt 348 348 ok 2 ok

Constants and variables

SEVENZIP_OK

const SEVENZIP_OK: i32 = 0
Everything went well.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_NOT_FOUND

const SEVENZIP_NOT_FOUND: i32 = 1
No entry has the name that was asked for.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_UNSUPPORTED

const SEVENZIP_UNSUPPORTED: i32 = 2
The archive uses something not supported: a method this package does not know, a newer format version, or an AES setting that is too slow to accept.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_ENCRYPTED

const SEVENZIP_ENCRYPTED: i32 = 3
The data or the headers are encrypted and no password was given.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_CORRUPT

const SEVENZIP_CORRUPT: i32 = 4
The archive is damaged or cut short.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_BAD_CRC

const SEVENZIP_BAD_CRC: i32 = 5
A checksum does not match: the signature header, the header, a folder or a file.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_TOO_BIG

const SEVENZIP_TOO_BIG: i32 = 6
The entry is bigger than the max given, or, in the in-memory calls, an entry over the cap given or over what one buffer holds (about 2 GiB); in the SevenZipFile calls, an entry over cap or a decoder that would need more than memcap.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_UNSAFE_PATH

const SEVENZIP_UNSAFE_PATH: i32 = 7
An entry name would leave the target folder (a .. part or an absolute path). Extraction skips it and carries on.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_BAD_PASSWORD

const SEVENZIP_BAD_PASSWORD: i32 = 8
The password given does not decrypt the data.

The example for this item is shown with the ones above: archive-SevenZip.salam

SEVENZIP_IO

const SEVENZIP_IO: i32 = 10
A file could not be read or written.

The example for this item is shown with the ones above: archive-SevenZipFile.salam

TAR_OK

const TAR_OK: i32 = 0
Status: the call succeeded.

The example for this item is shown with the ones above: archive-TarFile.salam

TAR_NOT_FOUND

const TAR_NOT_FOUND: i32 = 1
Status: the entry is not a regular file, so there is nothing to unpack.

The example for this item is shown with the ones above: archive-TarFile.salam

TAR_CORRUPT

const TAR_CORRUPT: i32 = 4
Status: the archive is damaged or cut short.

The example for this item is shown with the ones above: archive-TarFile.salam

TAR_TOO_BIG

const TAR_TOO_BIG: i32 = 6
Status: an entry is larger than the cap given.

The example for this item is shown with the ones above: archive-TarFile.salam

TAR_IO

const TAR_IO: i32 = 7
Status: a file could not be opened, read or written.

The example for this item is shown with the ones above: archive-TarFile.salam

TAR_UNSAFE_PATH

const TAR_UNSAFE_PATH: i32 = 8
Status: an entry name or link target leaves the target folder; that entry was skipped.

The example for this item is shown with the ones above: archive-TarFile.salam

ZIP_OK

const ZIP_OK: i32 = 0
Status: the entry was unpacked and its checksum matched.
archive-ZipVerify.salam
import archive
import compress

func main:
    text := "hello archive, hello archive, hello archive"
    b := compress.BufFromStr(text)
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("a.txt", b.data, b.len, 0))
    files.Push(archive.MakeZipFileInput("b.txt", b.data, 5, 8))
    z := archive.ZipCreate(files)
    mut status := 0
    mut checked := 0
    good := archive.ZipExtractVerified(z.data, z.len, "a.txt", 0, status)
    println status == archive.ZIP_OK, good.len, archive.ZipVerify(z.data, z.len, checked), checked

    bp := z.data as u8*
    bp[35] = 0x58 as u8
    bad := archive.ZipExtractVerified(z.data, z.len, "a.txt", 0, status)
    println status == archive.ZIP_BAD_CRC, bad.len, archive.ZipStatusText(status)
    mut ok := false
    plain := archive.ZipExtractByName(z.data, z.len, "a.txt", ok)
    println ok, plain.len
    println archive.ZipVerify(z.data, z.len, checked), checked
    mut broken := archive.ZipBadEntries(z.data, z.len)
    each e in broken:
        println "damaged:", e.name
    end
    archive.FreeEntries(broken)
    _ := archive.ZipExtractVerified(z.data, z.len, "missing.txt", 0, status)
    println status == archive.ZIP_NOT_FOUND, archive.ZipStatusText(status)
end
Outputtrue 43 0 2 true 0 checksum mismatch true 43 1 2 damaged: a.txt true entry not found

ZIP_NOT_FOUND

const ZIP_NOT_FOUND: i32 = 1
Status: no entry has that name.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZIP_UNSUPPORTED

const ZIP_UNSUPPORTED: i32 = 2
Status: a compression method other than 0 and 8.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZIP_ENCRYPTED

const ZIP_ENCRYPTED: i32 = 3
Status: the entry is encrypted.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZIP_CORRUPT

const ZIP_CORRUPT: i32 = 4
Status: the data is damaged, cut short, or not a zip, or its size does not match.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZIP_BAD_CRC

const ZIP_BAD_CRC: i32 = 5
Status: the entry unpacked but its CRC-32 does not match the one in the archive.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZIP_TOO_BIG

const ZIP_TOO_BIG: i32 = 6
Status: the entry is larger than the max (or cap) given, or, for the in-memory functions, larger than 2 GB.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZIP_IO

const ZIP_IO: i32 = 7
Status: a file could not be opened, read or written.

The example for this item is shown with the ones above: archive-ZipFile.salam

ZIP_UNSAFE_PATH

const ZIP_UNSAFE_PATH: i32 = 8
Status: the entry name is absolute or climbs out of the target folder with .., so nothing was written for it.

The example for this item is shown with the ones above: archive-ZipFile.salam

ZIP_MULTIVOLUME

const ZIP_MULTIVOLUME: i32 = 9
Status: the zip is one piece of a split archive and another piece is missing (or a .zip that says it has earlier disks was opened without them).
archive-ZipSplit.salam
import archive
import compress
import os

func main:
    mut data := compress.NewByteBufCap(150000)
    repeat 150000 in i:
        compress.BufPush(data, 65 + i % 23)
    end
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("big.bin", data.data, data.len, 0))
    println archive.ZipCreateFileSplit(files, "split.zip", 65536 as i64, archive.ZipSplitDisk)
    files.Free()
    compress.BufFree(data)

    mut zf := archive.ZipOpenFile("split.zip")
    println zf.status == archive.ZIP_OK, zf.count, zf.volumes.Len()
    println archive.ZipFileExtractTo(zf, "big.bin", "big.out", 0 as i64) == archive.ZIP_OK, os.FileSize("big.out")
    archive.ZipFileClose(zf)
    os.Remove("big.out")
    os.Remove("split.z01")
    os.Remove("split.z02")
    os.Remove("split.zip")
end
Outputtrue true 1 3 true 150000

ZIP_BAD_PASSWORD

const ZIP_BAD_PASSWORD: i32 = 11
The password does not match the encrypted entry.
archive-ZipPassword.salam
import archive
import compress
import os

const HEX := """
504b03041400090008008e48695d898d35803c0100001a0e000005001c00742e74787455540900039c8cf16a9c8cf16a7578
0b000104e903000004e9030000d1f0d56c6d77a28b2c8bf0eb428f8e10e5e2e8b537f0c08b7098af8bf029e1019ab6418c85
29642a576991cd4b6e9b58c19964a4289b96cc6d03b252711d16c78345911dd3b4a42f5941f5b7973607785e47cd00f0c04e
108f76d066cdf3849b3057f9a1153a4d5cd3baa4d1ba0f8423075418234d58c37243b860cf1765cfe9e4f68a905e97fcea1d
3d8078e4ec86af4d4ab806be237be2dbfa7ca7d4275de84a2a5b14cb24a662b01de7cd6ec90e07a443d7b5a1a6c6bb93dae4
163048cb7858f109e1b86f8979a030523faf2a0ffc1418d3677de5d8d63b83a13d8e3678662ede71b68ea595f7f6c5d72fad
c07efab5cb2961d3ea1be139b99bad89180780c7bf434938afbaccfb872ddc1cc576a22b4a9b7588c2fb89d6471cc64260ba
10dada13ce9f424b7be9845a6ae2a5d46ac0f2847078ab7b9d68cdef32504b0708898d35803c0100001a0e0000504b03040a
00090000008e48695d5f0e2f63380100002c01000005001c006e2e62696e55540900039c8cf16a9c8cf16a75780b000104e9
03000004e903000008affb7424492bfe472c296bd4c1dd298f16ef4d0804791cbac1903adbf3baafe39a4279cd76aa8a8b7f
2775e9b747ec50253a355142ec3bb4fa26280ac927900bf382899dae8a90f97fee5b84bafe72e7920263af4dd0b5723703b2
a3b6f4b039e300951f75977d239f5dd1d696e87326a4ca821b61d1922cd22d6d848afd37d5c62fc6f999f53a875dab5f53e7
9fdaffa02bce9d0cafbc49abf967a76095830941e78c509e3bb77318369281375f6cc4224503226bfe1f299eb692920a6863
88953c4eff9540453314b04783ce56f22a3a7484f77493aed1e2edbb0e8473039e8e1dc07278ec3523ec104bf1df862f4b11
5e602276d720eb296bdebb66e0120f5d9e9ce6afbd5d24cf2b1f79191427036849ce561dc8d08b8350db994713a1ed390863
e8fc83728c1255abf786a5ea9034d2b4d6b1c9f3504b07085f0e2f63380100002c010000504b01021e031400090008008e48
695d898d35803c0100001a0e0000050018000000000001000000a48100000000742e74787455540500039c8cf16a75780b00
0104e903000004e9030000504b01021e030a00090000008e48695d5f0e2f63380100002c0100000500180000000000000000
00a4818b0100006e2e62696e55540500039c8cf16a75780b000104e903000004e9030000504b050600000000020002009600
0000120300000000
"""

func unhex(s: str): compress.ByteBuf:
    mut b := compress.NewByteBuf()
    bp := s as u8*
    mut hi := -1
    repeat s.Len() in i:
        c := bp[i] as int
        mut v := -1
        if c >= 48 and c <= 57:
            v = c - 48
        else c >= 97 and c <= 102:
            v = c - 87
        end
        if v < 0:
            continue
        end
        if hi < 0:
            hi = v
        else:
            compress.BufPush(b, hi * 16 + v)
            hi = -1
        end
    end
    ret b
end

func main:
    archive.WriteBinaryFileBuf("secret.zip", unhex(HEX))
    mut zf := archive.ZipOpenFile("secret.zip")
    println archive.ZipFileExtractTo(zf, "t.txt", "t.out", 0 as i64) == archive.ZIP_ENCRYPTED
    archive.ZipFileSetPassword(zf, "nope")
    println archive.ZipFileExtractTo(zf, "t.txt", "t.out", 0 as i64) == archive.ZIP_BAD_PASSWORD
    archive.ZipFileSetPassword(zf, "pw123")
    println archive.ZipFileExtractTo(zf, "t.txt", "t.out", 0 as i64) == archive.ZIP_OK
    archive.ZipFileClose(zf)
    os.Remove("secret.zip")
    os.Remove("t.out")
end
Outputtrue true true

ZipMethodStore

const ZipMethodStore: i32 = 0
Zip method 0: the data is stored as it is.
archive-ZipMethods.salam
import archive
import compress
import str

func main:
    mut text := compress.NewByteBuf()
    repeat 80 in i:
        line := "line " + str.FromInt(i * 7 % 23) + ": zip entries can use several methods\n"
        compress.BufPushBytes(text, line as void*, line.Len())
    end
    println "text:", text.len, "bytes"
    names := ["store", "deflate", "bzip2", "lzma", "zstd"]
    methods := [archive.ZipMethodStore, archive.ZipMethodDeflate, archive.ZipMethodBzip2, archive.ZipMethodLzma, archive.ZipMethodZstd]
    repeat 5 in i:
        mut files := Vector {} as Vector<archive.ZipFileInput>
        files.Push(archive.MakeZipFileInput("notes.txt", text.data, text.len, methods[i]))
        z := archive.ZipCreate(files)
        mut checked := 0
        mut status := 0
        back := archive.ZipExtractVerified(z.data, z.len, "notes.txt", 0, status)
        println names[i], "method", methods[i], "zip", z.len, "bytes, verify", archive.ZipVerify(z.data, z.len, checked), "same text", status == 0 and compress.BufEquals(back, text)
    end

    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInputLevel("fast.txt", text.data, text.len, archive.ZipMethodZstd, 1))
    mut best := archive.MakeZipFileInput("best.txt", text.data, text.len, archive.ZipMethodZstd)
    best.level = 19
    files.Push(best)
    files.Push(archive.MakeZipFileInput("empty.txt", null, 0, archive.ZipMethodBzip2))
    z := archive.ZipCreate(files)
    mut entries := archive.ZipList(z.data, z.len)
    each e in entries:
        println e.name, "method", e.method, e.size, "->", e.compressed_size
    end
    archive.FreeEntries(entries)
end
Outputtext: 3565 bytes store method 0 zip 3681 bytes, verify 0 same text true deflate method 8 zip 251 bytes, verify 0 same text true bzip2 method 12 zip 297 bytes, verify 0 same text true lzma method 14 zip 252 bytes, verify 0 same text true zstd method 93 zip 270 bytes, verify 0 same text true fast.txt method 93 3565 -> 154 best.txt method 93 3565 -> 142 empty.txt method 0 0 -> 0

ZipMethodDeflate

const ZipMethodDeflate: i32 = 8
Zip method 8: DEFLATE.

The example for this item is shown with the ones above: archive-ZipMethods.salam

ZipMethodDeflate64

const ZipMethodDeflate64: i32 = 9
Zip method 9: Deflate64, the DEFLATE variant of 7-Zip and Windows with a 64 KiB window and longer matches. Zip files with it are read, but not written: asking for method 9 in ZipCreate stores the file.
archive-ZipDeflate64.salam
import archive
import compress

func hex_val(c: int): int:
    if c >= 97: ret c - 87 end
    ret c - 48
end

func unhex(h: str): compress.ByteBuf:
    mut b := compress.NewByteBuf()
    bp := h as u8*
    mut i := 0
    until i + 1 < h.Len():
        compress.BufPush(b, hex_val(bp[i] as int) * 16 + hex_val(bp[i + 1] as int))
        i += 2
    end
    ret b
end

func main:
    z := unhex("504b03041500000009008044695dba1f6638250000003200000005000000742e74787485c8b10d00400405d0fea630c095621f89af1285686c6f04af7c060f6d0813b26b3e5df116504b01023f031500000009008044695dba1f66382500000032000000050024000000000000002080a48100000000742e7478740a00200000000000010018007dda1d582570dd0100000000000000000000000000000000504b0506000000000100010057000000480000000000")
    mut entries := archive.ZipList(z.data, z.len)
    each e in entries:
        println e.name, e.size, e.compressed_size, e.method == archive.ZipMethodDeflate64
    end
    archive.FreeEntries(entries)
    mut status := 0
    text := archive.ZipExtractVerified(z.data, z.len, "t.txt", 0, status)
    println status == archive.ZIP_OK, compress.BufToStrUnsafe(text)
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(archive.MakeZipFileInput("t.txt", text.data, text.len, archive.ZipMethodDeflate64))
    written := archive.ZipCreate(files)
    mut back := archive.ZipList(written.data, written.len)
    println "written with method", back.Get(0).method
    archive.FreeEntries(back)
end
Outputt.txt 50 37 true true deflate64 entry, deflate64 entry, deflate64 entry written with method 0

ZipMethodBzip2

const ZipMethodBzip2: i32 = 12
Zip method 12: bzip2. Every zip reader that knows more than DEFLATE reads it.

The example for this item is shown with the ones above: archive-ZipMethods.salam

ZipMethodLzma

const ZipMethodLzma: i32 = 14
Zip method 14: LZMA. Read by 7-Zip and Python, not by Info-ZIP unzip.

The example for this item is shown with the ones above: archive-ZipMethods.salam

ZipMethodZstd

const ZipMethodZstd: i32 = 93
Zip method 93: Zstandard. Read by recent 7-Zip builds and Python 3.14, not by Info-ZIP unzip.

The example for this item is shown with the ones above: archive-ZipMethods.salam

ZipEncAuto

const ZipEncAuto: i32 = 0
Encryption 0: AES-256 when the entry has a password.
archive-WriteStream.salam
import archive
import compress
import filepath
import os

func same(path: str, want: compress.ByteBuf): bool:
    mut ok := false
    got := archive.ReadBinaryFile(path, ok)
    ret ok and compress.BufEquals(got, want)
end

func main:
    dir := filepath.Join(os.TempDir(), "salam_write_example")
    os.RemoveAll(dir)
    os.MkdirAll(dir)
    plain := filepath.Join(dir, "notes.txt")
    back := filepath.Join(dir, "back.bin")
    text := compress.BufFromStr("Salam keeps notes in plain files. ".Repeat(2000))
    archive.WriteBinaryFileBuf(plain, text)
    archive.SetWriteChunk(16384)

    println "gz:", archive.GzipCompressFile(plain, filepath.Join(dir, "n.gz")), archive.GzipDecompressFile(filepath.Join(dir, "n.gz"), back), same(back, text)
    println "bz2 level 1:", archive.Bzip2CompressFileLevel(plain, filepath.Join(dir, "n.bz2"), 1), archive.Bzip2DecompressFile(filepath.Join(dir, "n.bz2"), back), same(back, text)
    println "xz level 9:", archive.XzCompressFileLevel(plain, filepath.Join(dir, "n.xz"), 9), archive.XzDecompressFile(filepath.Join(dir, "n.xz"), back), same(back, text)
    println "lzma level 3:", archive.LzmaCompressFileLevel(plain, filepath.Join(dir, "n.lzma"), 3), archive.LzmaDecompressFile(filepath.Join(dir, "n.lzma"), back), same(back, text)

    mut tar_files := Vector {} as Vector<archive.TarFileInput>
    tar_files.Push(archive.MakeTarFilePath("docs/notes.txt", plain))
    tar_files.Push(archive.MakeTarFileInput("docs/hello.txt", "hello" as void*, 5, false))
    tgz := filepath.Join(dir, "n.tar.zst")
    println "tar.zst:", archive.TarZstdCreateFileLevel(tar_files, tgz, 5)

    mut zip_files := Vector {} as Vector<archive.ZipFileInput>
    zip_files.Push(archive.MakeZipFilePath("notes.txt", plain, archive.ZipMethodDeflate, 0))
    secret := "top secret"
    zip_files.Push(archive.MakeZipFileInputEncrypted("secret.txt", secret as void*, secret.Len(), archive.ZipMethodDeflate, 0, "pass", archive.ZipEncAuto))
    zpath := filepath.Join(dir, "n.zip")
    println "zip:", archive.ZipCreateFile(zip_files, zpath), archive.ZipCreateFile64(zip_files, filepath.Join(dir, "n64.zip"))
    mut zf := archive.ZipOpenFile(zpath)
    println "entries:", zf.count, "status:", zf.status
    println "no password:", archive.ZipFileExtractTo(zf, "secret.txt", back, 0 as i64) == archive.ZIP_ENCRYPTED
    archive.ZipFileSetPassword(zf, "pass")
    println "password:", archive.ZipFileExtractTo(zf, "secret.txt", back, 0 as i64) == archive.ZIP_OK, same(back, compress.BufFromStr(secret))
    archive.ZipFileClose(zf)

    mut sz_files := Vector {} as Vector<archive.SevenZipFileInput>
    sz_files.Push(archive.MakeSevenZipFilePath("notes.txt", plain))
    szpath := filepath.Join(dir, "n.7z")
    println "7z level 5:", archive.SevenZipCreateFileLevel(sz_files, szpath, 5)
    mut sf := archive.SevenZipOpenFile(szpath, "")
    println "7z extract:", archive.SevenZipFileExtractTo(sf, "notes.txt", back, 0 as i64, 0 as i64), same(back, text)
    archive.SevenZipFileClose(sf)
    os.RemoveAll(dir)
end
Outputgz: true true true bz2 level 1: true true true xz level 9: true true true lzma level 3: true true true tar.zst: true zip: true true entries: 2 status: 0 no password: true password: true true 7z level 5: true 7z extract: 0 true

ZipEncZipCrypto

const ZipEncZipCrypto: i32 = 1
Encryption 1: the old zip encryption (ZipCrypto), which is weak and only for old readers.

The example for this item is shown with the ones above: archive-WriteStream.salam

ZipEncAes128

const ZipEncAes128: i32 = 2
Encryption 2: WinZip AES with a 128 bit key.

The example for this item is shown with the ones above: archive-WriteStream.salam

ZipEncAes192

const ZipEncAes192: i32 = 3
Encryption 3: WinZip AES with a 192 bit key.

The example for this item is shown with the ones above: archive-WriteStream.salam

ZipEncAes256

const ZipEncAes256: i32 = 4
Encryption 4: WinZip AES with a 256 bit key.

The example for this item is shown with the ones above: archive-WriteStream.salam

ZipSplitDisk

const ZipSplitDisk: i32 = 0
Style for ZipCreateFileSplit: pieces named .z01, .z02, ending with .zip.

The example for this item is shown with the ones above: archive-ZipSplit.salam

ZipSplitByte

const ZipSplitByte: i32 = 1
Style for ZipCreateFileSplit: the finished archive cut into .zip.001, .zip.002 and so on.

The example for this item is shown with the ones above: archive-ZipSplit.salam

ARCHIVE_OK

const ARCHIVE_OK: i32 = 0
Status code: Success.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_NOT_FOUND

const ARCHIVE_NOT_FOUND: i32 = 1
Status code: The entry is not in the archive.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_UNSUPPORTED

const ARCHIVE_UNSUPPORTED: i32 = 2
Status code: The format, method or feature is not supported.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_ENCRYPTED

const ARCHIVE_ENCRYPTED: i32 = 3
Status code: The data is encrypted and no password was given.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_CORRUPT

const ARCHIVE_CORRUPT: i32 = 4
Status code: The data is damaged. For a gzip, bzip2 or xz file it also means the data is larger than the max_total limit.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_BAD_CRC

const ARCHIVE_BAD_CRC: i32 = 5
Status code: A checksum does not match.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_TOO_BIG

const ARCHIVE_TOO_BIG: i32 = 6
Status code: An entry or the total is over the limit.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_UNSAFE_PATH

const ARCHIVE_UNSAFE_PATH: i32 = 7
Status code: A name, link or device entry could leave the target folder; nothing is written.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_BAD_PASSWORD

const ARCHIVE_BAD_PASSWORD: i32 = 8
Status code: The password is wrong.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_MULTIVOLUME

const ARCHIVE_MULTIVOLUME: i32 = 9
Status code: A volume of a multi-volume archive is missing.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_IO_ERROR

const ARCHIVE_IO_ERROR: i32 = 10
Status code: The file could not be read or written.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_UNKNOWN_FORMAT

const ARCHIVE_UNKNOWN_FORMAT: i32 = 11
Status code: The first bytes match no known format.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_TOO_MANY_ENTRIES

const ARCHIVE_TOO_MANY_ENTRIES: i32 = 12
Status code: The archive has more entries than max_entries.

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_BOMB

const ARCHIVE_BOMB: i32 = 13
Status code: The listed sizes are far larger than the archive itself (over max_ratio).

The example for this item is shown with the ones above: archive-Open.salam

ARCHIVE_WINDOW_TOO_BIG

const ARCHIVE_WINDOW_TOO_BIG: i32 = 14
Status code: the dictionary or window of the compressed data is larger than the memory limit.

The example for this item is shown with the ones above: archive-Open.salam

FormatUnknown

const FormatUnknown: i32 = 0
Format code: unknown.

The example for this item is shown with the ones above: archive-Open.salam

FormatZip

const FormatZip: i32 = 1
Format code: zip.

The example for this item is shown with the ones above: archive-Open.salam

FormatTar

const FormatTar: i32 = 2
Format code: plain tar.

The example for this item is shown with the ones above: archive-Open.salam

FormatTarGz

const FormatTarGz: i32 = 3
Format code: tar compressed with gzip (.tar.gz, .tgz).

The example for this item is shown with the ones above: archive-Open.salam

FormatTarBz2

const FormatTarBz2: i32 = 4
Format code: tar compressed with bzip2.

The example for this item is shown with the ones above: archive-Open.salam

FormatTarXz

const FormatTarXz: i32 = 5
Format code: tar compressed with xz.

The example for this item is shown with the ones above: archive-Open.salam

FormatGzip

const FormatGzip: i32 = 6
Format code: a single gzip file.

The example for this item is shown with the ones above: archive-Open.salam

FormatBzip2

const FormatBzip2: i32 = 7
Format code: a single bzip2 file.

The example for this item is shown with the ones above: archive-Open.salam

FormatXz

const FormatXz: i32 = 8
Format code: a single xz file.

The example for this item is shown with the ones above: archive-Open.salam

FormatRar

const FormatRar: i32 = 9
Format code: RAR 1.5 to 5.

The example for this item is shown with the ones above: archive-Open.salam

FormatSevenZip

const FormatSevenZip: i32 = 10
Format code: 7z.

The example for this item is shown with the ones above: archive-Open.salam

FormatZstd

const FormatZstd: i32 = 11
Format code: one zstd file.

The example for this item is shown with the ones above: archive-Open.salam

FormatTarZstd

const FormatTarZstd: i32 = 12
Format code: tar compressed with zstd.

The example for this item is shown with the ones above: archive-Open.salam

RAR_OK

const RAR_OK: i32 = 0
Status: the entry was unpacked and its checksum matched.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_NOT_FOUND

const RAR_NOT_FOUND: i32 = 1
Status: no entry has that name.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_UNSUPPORTED

const RAR_UNSUPPORTED: i32 = 2
Status: a RAR version or method this package cannot unpack, such as a format from a newer WinRAR than this package knows.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_ENCRYPTED

const RAR_ENCRYPTED: i32 = 3
Status: the entry or the headers are encrypted and no password was given.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_CORRUPT

const RAR_CORRUPT: i32 = 4
Status: the data is damaged or cut short.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_BAD_CRC

const RAR_BAD_CRC: i32 = 5
Status: the entry unpacked but its CRC-32 does not match the one in the archive.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_MULTIVOLUME

const RAR_MULTIVOLUME: i32 = 6
Status: the entry continues in a volume that was not given.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_TOO_BIG

const RAR_TOO_BIG: i32 = 7
Status: the entry is larger than the max given, or needs more memory than the package will allocate.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_UNSAFE_PATH

const RAR_UNSAFE_PATH: i32 = 8
Status: the entry name would write outside the target directory, so it was skipped.

The example for this item is shown with the ones above: archive-Rar.salam

RAR_BAD_PASSWORD

const RAR_BAD_PASSWORD: i32 = 9
Status: the password is wrong (or, for RAR 3 and 4, the data is damaged).

The example for this item is shown with the ones above: archive-RarPassword.salam

RAR_WINDOW_TOO_BIG

const RAR_WINDOW_TOO_BIG: i32 = 10
Status: the data points back farther than the window the decoder can hold (the smaller of memcap and 1 GiB), or memcap is under 128 KiB. Raise memcap up to 1 GiB, or unpack with another tool.
archive-RarFileSet.salam
import archive
import compress
import filepath
import mem
import os

const PART1 := """
526172211a0701006de128270b01050701060101808080000cf698c92602130b950804b60ea48302e3916346800001086e6f
74652e7478740a03132f8df16a8b8429036469736b2073747265616d20766f6c756d6520766f6c756d652072617220726172
2062797465207061636b2073616c616d20766f6c756d652073747265616d206469736b2073747265616d2073616c616d2076
6f6c756d652073747265616d2073747265616d207061636b2073616c616d207061636b206469736b20726172207061636b20
6469736b207061636b206469736b2072617220726172207261722073616c616d2073616c616d207261722073747265616d20
627974652073747265616d2073616c616d2062797465207061636b206469736b2062797465207061636b2073616c616d2076
6f6c756d6520726172207061636b20726172207061636b2062797465206469736b2073616c616d206279746520766f6c756d
6520726172206469736b20766f6c756d6520766f6c756d6520627974652073616c616d20726172207061636b2073616c616d
206469736b2073616c616d206469736b2062797465206469736b207261722073616c616d20726172206469736b207061636b
20627974652073616c616d2073747265616d2073616c616d2073616c616d20627974652073747265616d2072617220627974
652072617220766f6c756d652073616c616d2073616c616d207261722073747265616d2073616c616d2073747265616d2073
616c616d2073747265616d206469736b2073747265616d20726172206469736b2073616c616d206469736b20726172207061
636b20627974652073616c616d207061636b2073747265616d20726172207261722073747265616d207061636b2073616c61
6d2073616c616d20766f6c756d652073747265616d207061636b2073747265616d206279746520726172207061636b20766f
6c756d65207061636b2073747265616d2073616c616d2073616c616d2062797465207061636b206469736b20726172207261
722073747265616d2073747265616d2073616c616d207061636b20766f6c756d652062797465207061636b2073747265616d
2073747265616d2073747265616d2062797465207061636b2073616c616d206279746520766f6c756d652073616c616d2062
7974652073747265616d20766f6c756d65206469736b20726172206469736b207261722073747265616d207061636b207361
6c616d206469736b20627974652073747265616d20766f6c756d652073616c616d206469736b2073616c616d207261722072
6172206469736b20766f6c756d6520766f6c756d6520627974652073616c616d20766f6c756d65207061636b20766f6c756d
652073616c616d2073747265616d20627974652073616c616d2073616c616d206469736b20627974652073747265616d2062
797465206469736b206469736b20766f6c756d65207061636b2062797465207261722073747265616d207061636b2073616c
616d206469736b207061636b8b47512603050401000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
"""

const PART2 := """
526172211a070100a9c2c4ca0c0105070301060101808080004b1a525026020b0ba10604b60ea483023a674699800001086e
6f74652e7478740a03132f8df16a8b842903207261722073616c616d2062797465206469736b2073747265616d20766f6c75
6d6520627974652073747265616d20766f6c756d6520726172207061636b20766f6c756d6520726172207061636b20627974
6520766f6c756d652073616c616d2073616c616d20627974652072617220766f6c756d65207261722073616c616d20737472
65616d207261722073616c616d2073616c616d2073616c616d206469736b207261722062797465206469736b20766f6c756d
652073747265616d2073616c616d206279746520766f6c756d6520766f6c756d6520726172206469736b2073747265616d20
766f6c756d65207261722073616c616d207061636b2073747265616d20766f6c756d65207061636b2073616c616d2073616c
616d206469736b206469736b20726172207061636b2073747265616d20627974652062797465206469736b2073747265616d
206279746520726172207061636b207061636b20766f6c756d6520627974652073747265616d2073747265616d206469736b
20766f6c756d652073616c616d2073616c616d20766f6c756d652073747265616d2072617220726172206279746520706163
6b20627974652073616c616d20726172206279746520627974652072617220627974652073616c616d207261722072617220
6469736b206469736b2073747265616d2073747265616d2073747265616d206469736b2073616c616d207261722073747265
616d206469736b2073747265616d20766f6c756d652073747265616d2073616c616d207061636b2073616c616d2073747265
616d2073747265616d206469736b2073747265616d20766f6c756d652073747265616d2073747265616d2073747265616d20
7061636b20627974652073616c616d207061636b2073747265616d2073747265616d20766f6c756d652073616c616d207061
636b20726172207061636b207261722073616c616d2073616c616d207061636b206469736b206469736b2073616c616d2064
69736b207061636b207061636b2073616c616d207061636b2073747265616d2073616c616d20766f6c756d65207261722064
69736b2072617220766f6c756d6520627974651d77565103050400
"""

const LOCKED := """
526172211a0701004f8ffa8e21040000010f34559f3b7ae69dc2dd40a39e1c528aafc2c96a316ce4aff36be1173ec9d29470
b91550fbe3c4c45f4dd2fbfe14bccb7ab7ba028efddec80ddb621bbad04a170343323b71489ad58a5039dca2da3bdf435da5
f52ff84b14deed319e54d2a76603c336bfcac6faecf773864d5f7fcaa7c05eb4570fd2f2e39533c099d50b6d39ce1f5bb90f
3c010d404ad0ec9b31003f9c4892bd41af252ddb3c27a2dbb488f20e33f188f4d2e89a9ae2e4afe566fdbb028936a17201d0
2ec33fba353ca4cb04f7a17ee62a89f3d2b3f20824fe874a07a6def01b09b32f4ce51efc7987f310d37ab074af4521d30448
555e46f5958a3c180c407decc1356d2300731e1e29668ce289433a4dc3700e2f1d9160a523a3f00e3aa545c6ff6f2f1f7e41
c4da6ce567f92813032b06e580080be55bd7002ce6ebe526789958b3173e5cf40ff4e383659b3c9af42ed3da8dfc7ecb32ef
cd6e0a09077414475679bd1465caa15710d438cd48bca4d174b4f58c7ee4d54019ece9757f310d13bed92d2301a1cbf4bcb0
3832dbad74df26f38fabb873e2c1d2a4b05d69fe74e31f6d1b43a1674ef75186a699bb8cfe47b06dd238ef625185e182f8d2
14679ae6739f403a6feae65452d8d3f29a2624ba021af6827e1c07a25af6b70bf82085777474c4ad54bf2d4591b8ecdcabc2
651228c42c7a6b39c36052531820b61b5c12d22b26c884611ecdfb1edc9f4a5b4e0ed808746e0b37817ed8fff2c61b1a1399
99190d89e32a8838
"""

func nib(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func save(dir: str, name: str, hex: str): str:
    mut b := compress.NewByteBuf()
    bp := hex as u8*
    mut hi := -1
    repeat hex.Len() in i:
        v := nib(bp[i] as int)
        if v < 0:
            continue
        end
        if hi < 0:
            hi = v
        else:
            compress.BufPush(b, hi * 16 + v)
            hi = -1
        end
    end
    path := filepath.Join(dir, name)
    _ := archive.WriteBinaryFileBuf(path, b)
    compress.BufFree(b)
    ret path
end

func main:
    dir := filepath.Join(os.TempDir(), "salam_rarfile_set")
    os.MkdirAll(dir)
    first := save(dir, "set.part1.rar", PART1)
    second := save(dir, "set.part2.rar", PART2)
    locked := save(dir, "locked.rar", LOCKED)

    mut rf := archive.RarFileOpenVolumes(first, "")
    println "volumes", rf.vols.paths.Len(), archive.RarStatusText(rf.status)
    out := filepath.Join(dir, "out")
    println archive.RarStatusText(archive.RarFileExtractAll(rf, out, 0 as i64, 0 as i64))
    archive.RarFileClose(rf)

    mut bad := archive.RarFileOpenWith(locked, "wrong")
    println "wrong password", archive.RarStatusText(bad.status)
    archive.RarFileClose(bad)
    mut good := archive.RarFileOpenWith(locked, "secret")
    mut es := archive.RarFileEntries(good)
    println "right password", es.Len(), es.Get(0).name, es.Get(0).size
    archive.FreeEntries(es)
    archive.RarFileClose(good)

    mem.Free(out as void*)
    mem.Free(first as void*)
    mem.Free(second as void*)
    mem.Free(locked as void*)
    os.RemoveAll(dir)
    mem.Free(dir as void*)
end
Outputvolumes 2 ok ok wrong password wrong password right password 1 note.txt 1846

Functions

ZipOpenFile

func ZipOpenFile(path: str): ZipFile
Opens a zip on disk by reading only its end and its central directory, so a file of any size opens at once. Sizes and offsets are 64 bit, zip64 included. Entries stored, DEFLATE, DEFLATE64, LZMA, bzip2 and zstd all unpack as a stream. A split archive opens through any of its pieces (.zip, .z01 or .zip.001) and is read in place as one file, zip64 end records and disk numbers included; a missing piece gives ZIP_MULTIVOLUME. Check status before using the result.

The example for this item is shown with the ones above: archive-ZipFile.salam

ZipFileClose

func ZipFileClose(zf &: ZipFile)
Releases the memory held by an opened zip file.

The example for this item is shown with the ones above: archive-ZipFile.salam

ZipFileSetPassword

func ZipFileSetPassword(zf &: ZipFile, password: str)
Sets the password used for encrypted entries (the old zip encryption and WinZip AES-128, AES-192 and AES-256). A wrong password gives ZIP_BAD_PASSWORD and no password gives ZIP_ENCRYPTED. Encrypted data is decrypted into a temporary file first, so the disk needs room for the packed size of one entry.

The example for this item is shown with the ones above: archive-ZipPassword.salam

ZipFileEntries

func ZipFileEntries(zf &: ZipFile): Vector<Entry>
Lists the entries of an opened zip file. Free the result with FreeEntries.

The example for this item is shown with the ones above: archive-ZipFile.salam

ZipFileExtractTo

func ZipFileExtractTo(zf &: ZipFile, name: str, destpath: str, cap: i64): int
Unpacks one entry to a file, reading the archive and writing the result in small pieces, so memory use does not depend on the size of the entry. The CRC-32 and the size are checked at the end; on a failure the partly written file is removed. cap is a limit in bytes for the unpacked data (0 for none): an entry over it returns ZIP_TOO_BIG and writes nothing.

The example for this item is shown with the ones above: archive-ZipFile.salam

ZipFileExtractAll

func ZipFileExtractAll(zf &: ZipFile, destdir: str, cap: i64): int
Unpacks every entry under a folder the same way, with the same checks and the same cap for each entry. Unsafe names are skipped. The result is ZIP_OK or the status of the first entry that failed.

The example for this item is shown with the ones above: archive-ZipFile.salam

IsSevenZip

func IsSevenZip(p: void*, n: int): bool
True when the data starts with the 7z signature.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipStatusText

func SevenZipStatusText(status: int): str
A short English text for a SEVENZIP_... code.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipOpen

func SevenZipOpen(p: void*, n: int, password: str): SevenZipArchive
Wraps archive data and a password in a SevenZipArchive. Nothing is read yet. Use an empty password for archives that are not encrypted.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipReadVolumes

func SevenZipReadVolumes(first: str, ok &: bool): Vector<compress.ByteBuf>
Reads the first volume (name.7z.001) and every following one by counting up the number at the end of the name. ok is false when the first file cannot be read.
archive-SevenZipVolumes.salam
import archive
import compress

const PART1 := """
377abcaf271c000457983ded16000000000000004a00000000000000429e4011766f6c756d65206f6e650a766f6c756d6520
74776f0a0104060001091600070b
"""

const PART2 := """
01000101000c1600080a014e6ded24000005011113006e006f00740065002e0074007800740000001900140a0100d9199ec4
1c70dd01150601002080a4810000
"""

func nib(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func unhex(s: str): compress.ByteBuf:
    mut b := compress.NewByteBuf()
    bp := s as u8*
    mut hi := -1
    repeat s.Len() in i:
        v := nib(bp[i] as int)
        if v < 0:
            continue
        end
        if hi < 0:
            hi = v
        else:
            compress.BufPush(b, hi * 16 + v)
            hi = -1
        end
    end
    ret b
end

func main:
    mut volumes := Vector {} as Vector<compress.ByteBuf>
    volumes.Push(unhex(PART1))
    volumes.Push(unhex(PART2))
    mut arc := archive.SevenZipOpenVolumes(volumes, "")
    names := archive.SevenZipEntries(arc)
    println "entries:", names.Len(), arc.status
    data := archive.SevenZipRead(arc, "note.txt", 0)
    print compress.BufToStrUnsafe(data)
    archive.SevenZipClose(arc)
    archive.SevenZipFreeVolumes(volumes)
end
Outputentries: 1 0 volume one volume two

SevenZipFreeVolumes

func SevenZipFreeVolumes(vols &: Vector<compress.ByteBuf>)
Frees the volumes read by SevenZipReadVolumes.

The example for this item is shown with the ones above: archive-SevenZipVolumes.salam

SevenZipOpenVolumes

func SevenZipOpenVolumes(vols: Vector<compress.ByteBuf>, password: str): SevenZipArchive
Like SevenZipOpen for the volumes of a split archive, in order. The pieces are joined into one buffer that the archive owns; release it with SevenZipClose.

The example for this item is shown with the ones above: archive-SevenZipVolumes.salam

SevenZipClose

func SevenZipClose(arc &: SevenZipArchive)
Releases the memory an archive made by SevenZipOpenVolumes owns.

The example for this item is shown with the ones above: archive-SevenZipVolumes.salam

SevenZipEntries

func SevenZipEntries(arc &: SevenZipArchive): Vector<Entry>
Lists the entries (files and folders; anti items are left out) and sets status. compressed_size is the packed size of the solid block, given on its first file; method is 0 copy, 1 LZMA, 2 LZMA2, 3 PPMd, 4 BZip2, 5 Deflate, 9 other; mode holds the Unix permission bits when the archive has them. Free the list with FreeEntries.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipRead

func SevenZipRead(arc &: SevenZipArchive, name: str, max: int): compress.ByteBuf
Unpacks one entry by name, checks its CRC-32 and sets status. max refuses entries bigger than that many bytes (0 means no limit, which is the 2 GiB a buffer holds). The data is unpacked in pieces, so as a rule only the entry is held in memory, not its whole solid block. Use SevenZipReadAll to read many files.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipReadAll

func SevenZipReadAll(arc &: SevenZipArchive, destdir: str): int
Extracts every entry under destdir and returns how many were written; status reports the first problem. Names that would leave the folder are skipped, symbolic links are created only when their target stays inside the folder, and each solid block is unpacked once. Entries are written to disk in pieces, so there is no limit on their size.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipListStatus

func SevenZipListStatus(p: void*, n: int, status &: int): Vector<Entry>
Like SevenZipList, and status says why the list is empty when the archive could not be read.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipList

func SevenZipList(p: void*, n: int): Vector<Entry>
Lists the entries of a 7z archive with no password; an empty list can mean a bad or encrypted archive, see SevenZipListStatus.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipExtract

func SevenZipExtract(p: void*, n: int, name: str, max: int, status &: int): compress.ByteBuf
Unpacks one entry from an archive with no password; status is a SEVENZIP_... code.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipExtractByNameMax

func SevenZipExtractByNameMax(p: void*, n: int, name: str, max: int, ok &: bool): compress.ByteBuf
Like SevenZipExtractByName, but ok is false for an entry bigger than max bytes (0 means no limit).

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipExtractByName

func SevenZipExtractByName(p: void*, n: int, name: str, ok &: bool): compress.ByteBuf
Unpacks one entry by name; ok becomes false when it is missing, damaged or fails its checksum.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipExtractAllStatus

func SevenZipExtractAllStatus(p: void*, n: int, destdir: str, status &: int): int
Extracts every entry into destdir, returns how many were written and sets status.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipExtractAll

func SevenZipExtractAll(p: void*, n: int, destdir: str): bool
Extracts every entry into destdir; returns false when anything failed or was skipped.

The example for this item is shown with the ones above: archive-SevenZip.salam

SetWriteChunk

func SetWriteChunk(n: int)
Sets how many bytes the gz, bz2, xz, zstd, tar.gz and zip file writers hold and compress at a time (default 4 MiB, anything under 4096 restores the default). The tar.zst and tar.bz2 writers ignore it: they compress the whole tar as one stream. Smaller chunks use less memory and compress a little worse.

The example for this item is shown with the ones above: archive-WriteStream.salam

MakeTarFileInput

func MakeTarFileInput(name: str, data_ptr: void*, data_len: int, is_dir: bool): TarFileInput
Makes one tar input.

The example for this item is shown with the ones above: archive-Tar.salam

MakeTarFilePath

func MakeTarFilePath(name: str, path: str): TarFileInput
Makes a tar input that is read from a file on disk when the archive is written, so TarCreateFile, TarGzCreateFile and TarZstdCreateFile never hold it in memory. Entries of 8 GiB or more get a PAX size record.

The example for this item is shown with the ones above: archive-WriteStream.salam

func MakeTarSymlink(name: str, target: str): TarFileInput
Makes a symbolic link entry that points to target.
archive-TarLinks.salam
import archive
import compress

func main:
    d := compress.BufFromStr("hello\n")
    mut files := Vector {} as Vector<archive.TarFileInput>
    mut a := archive.MakeTarFileInput("a.txt", d.data, d.len, false)
    a.mtime = 1700000000 as i64
    a.mode = 0o640
    files.Push(a)
    files.Push(archive.MakeTarSymlink("current", "a.txt"))
    files.Push(archive.MakeTarHardlink("copy.txt", "a.txt"))
    deep := "reports/".Repeat(20) + "summary.txt"
    files.Push(archive.MakeTarFileInput(deep, d.data, d.len, false))
    t := archive.TarCreate(files)
    mut es := archive.TarList(t.data, t.len)
    each e in es:
        println e.kind, e.name.Len(), e.link, e.size, e.mtime, e.mode
    end
    archive.FreeEntries(es)
    println archive.TarExtractAll(t.data, t.len, "linked")
    mut bad := Vector {} as Vector<archive.TarFileInput>
    bad.Push(archive.MakeTarFileInput("fine.txt", d.data, d.len, false))
    bad.Push(archive.MakeTarSymlink("escape", "../outside"))
    b := archive.TarCreate(bad)
    println archive.TarExtractAll(b.data, b.len, "guarded")
end
Output0 5 6 1700000000 416 2 7 a.txt 0 0 511 3 8 a.txt 0 0 420 0 171 6 0 420 true false
func MakeTarHardlink(name: str, target: str): TarFileInput
Makes a hard link entry to another entry of the same archive, named by target.

The example for this item is shown with the ones above: archive-TarLinks.salam

TarCreate

func TarCreate(files: Vector<TarFileInput>): compress.ByteBuf
Builds a tar archive in memory, in the ustar format with PAX records for what ustar cannot hold; tar does not compress, so gzip the result for that.

The example for this item is shown with the ones above: archive-Tar.salam

TarBz2CreateFile

func TarBz2CreateFile(files: Vector<TarFileInput>, outpath: str): bool
Writes a .tar.bz2 file at bzip2 level 9. The tar stream is compressed as one bzip2 stream while it is written, one block at a time, so memory stays at a block whatever the size of the inputs; the result is what Bzip2CompressLevel gives on the whole tar. Returns false, and leaves no file, when an input cannot be read.
archive-TarBz2.salam
import archive
import compress
import filepath
import os

func main:
    mut files := Vector {} as Vector<archive.TarFileInput>
    hello := compress.BufFromStr("hello\n")
    files.Push(archive.MakeTarFileInput("hello.txt", hello.data, hello.len, false))
    files.Push(archive.MakeTarFileInput("notes", null, 0, true))
    notes := compress.BufFromStr("note\n".Repeat(200))
    files.Push(archive.MakeTarFileInput("notes/list.txt", notes.data, notes.len, false))

    dir := filepath.Join(os.TempDir(), "salam_tarbz2_example")
    os.RemoveAll(dir)
    os.MkdirAll(dir)
    path := filepath.Join(dir, "all.tar.bz2")
    println "file:", archive.TarBz2CreateFile(files, path)
    println "level 1:", archive.TarBz2CreateFileLevel(files, filepath.Join(dir, "fast.tar.bz2"), 1)

    mut ok := false
    packed := archive.ReadBinaryFile(path, ok)
    plain := archive.TarCreate(files)
    one := compress.Bzip2CompressLevel(plain.data, plain.len, 9)
    println "one bzip2 stream:", compress.BufEquals(packed, one)

    dest := filepath.Join(dir, "out")
    println "extract:", archive.TarBz2FileExtractAll(path, dest, 0 as i64)
    println os.Exists(filepath.Join(dest, "notes/list.txt"))
    os.RemoveAll(dir)
end
Outputfile: true level 1: true one bzip2 stream: true extract: 0 true

TarBz2CreateFileLevel

func TarBz2CreateFileLevel(files: Vector<TarFileInput>, outpath: str, level: int): bool
Like TarBz2CreateFile, at the bzip2 level you give (1 to 9; other values are clamped).

The example for this item is shown with the ones above: archive-TarBz2.salam

TarCreateFile

func TarCreateFile(files: Vector<TarFileInput>, outpath: str): bool
Writes a tar archive to a file.

The example for this item is shown with the ones above: archive-Tar.salam

TarList

func TarList(p: void*, n: int): Vector<Entry>
The entries of a tar in memory, with their long names, links, times and modes. Free the list with FreeEntries.

The example for this item is shown with the ones above: archive-Tar.salam

TarExtractByName

func TarExtractByName(p: void*, n: int, name: str, ok &: bool): compress.ByteBuf
The contents of one tar file entry; ok is false when the name is not there or is not a file.

The example for this item is shown with the ones above: archive-Tar.salam

TarExtractAll

func TarExtractAll(p: void*, n: int, destdir: str): bool
Writes every tar entry into the target directory, with links, modes and times. Returns false when it had to skip an unsafe name or link, or an entry it cannot make.

The example for this item is shown with the ones above: archive-Tar.salam

TarGzCreate

func TarGzCreate(files: Vector<TarFileInput>): compress.ByteBuf
Builds a tar in memory and gzips it.
archive-TarGz.salam
import archive
import compress

func main:
    text := "log line\n".Repeat(500)
    d := compress.BufFromStr(text)
    mut files := Vector {} as Vector<archive.TarFileInput>
    files.Push(archive.MakeTarFileInput("app.log", d.data, d.len, false))
    files.Push(archive.MakeTarFileInput("empty", null, 0, true))
    z := archive.TarGzCreate(files)
    println z.len < d.len
    mut ok := false
    mut es := archive.TarGzList(z.data, z.len, ok)
    println ok, es.Len()
    archive.FreeEntries(es)
    one := archive.TarGzExtractByName(z.data, z.len, "app.log", ok)
    println ok, one.len == d.len
    small := archive.TarGzListMax(z.data, z.len, 1000, ok)
    println ok, small.Len()
    _ := archive.TarGzExtractByNameMax(z.data, z.len, "app.log", 100000, ok)
    println ok
    println archive.TarGzExtractAllMax(z.data, z.len, "tooSmall", 1000)
    println archive.TarGzExtractAll(z.data, z.len, "unpacked")
    println archive.TarGzCreateFile(files, "logs.tar.gz")
end
Outputtrue true 2 true true false 0 true false true true

TarGzCreateFile

func TarGzCreateFile(files: Vector<TarFileInput>, outpath: str): bool
Writes a .tar.gz file.

The example for this item is shown with the ones above: archive-TarGz.salam

TarGzListMax

func TarGzListMax(p: void*, n: int, max: int, ok &: bool): Vector<Entry>
Same as TarGzList, with your own limit max on the inflated size in bytes.

The example for this item is shown with the ones above: archive-TarGz.salam

TarGzList

func TarGzList(p: void*, n: int, ok &: bool): Vector<Entry>
The entries of a .tar.gz in memory; ok is false when the gzip is invalid or inflates past 1 GiB.

The example for this item is shown with the ones above: archive-TarGz.salam

TarGzExtractByNameMax

func TarGzExtractByNameMax(p: void*, n: int, name: str, max: int, ok &: bool): compress.ByteBuf
Same as TarGzExtractByName, with your own limit max on the inflated size in bytes.

The example for this item is shown with the ones above: archive-TarGz.salam

TarGzExtractByName

func TarGzExtractByName(p: void*, n: int, name: str, ok &: bool): compress.ByteBuf
The contents of one file of a .tar.gz.

The example for this item is shown with the ones above: archive-TarGz.salam

TarGzExtractAllMax

func TarGzExtractAllMax(p: void*, n: int, destdir: str, max: int): bool
Same as TarGzExtractAll, with your own limit max on the inflated size in bytes.

The example for this item is shown with the ones above: archive-TarGz.salam

TarGzExtractAll

func TarGzExtractAll(p: void*, n: int, destdir: str): bool
Gunzips a .tar.gz and writes it into the target directory like TarExtractAll; false when the gzip is invalid or too big.

The example for this item is shown with the ones above: archive-TarGz.salam

TarZstdCreate

func TarZstdCreate(files: Vector<TarFileInput>): compress.ByteBuf
Builds a tar in memory and compresses it to Zstandard.
archive-TarZstd.salam
import archive
import compress
import filepath
import os

func main:
    mut files := Vector {} as Vector<archive.TarFileInput>
    hello := compress.BufFromStr("hello\n")
    files.Push(archive.MakeTarFileInput("hello.txt", hello.data, hello.len, false))
    files.Push(archive.MakeTarFileInput("notes", null, 0, true))
    notes := compress.BufFromStr("note\n".Repeat(200))
    files.Push(archive.MakeTarFileInput("notes/list.txt", notes.data, notes.len, false))

    tz := archive.TarZstdCreate(files)
    println "tar.zst:", tz.len, "bytes,", compress.IsZstdBuf(tz)
    mut ok := false
    mut entries := archive.TarZstdList(tz.data, tz.len, ok)
    println "entries:", ok, entries.Len()
    each e in entries:
        println e.name, e.size
    end
    archive.FreeEntries(entries)
    one := archive.TarZstdExtractByName(tz.data, tz.len, "hello.txt", ok)
    println ok, compress.BufToStrUnsafe(one)
    small := archive.TarZstdListMax(tz.data, tz.len, 1000, ok)
    println "capped at 1000 bytes:", ok, small.Len()

    dir := filepath.Join(os.TempDir(), "salam_tarzstd_example")
    os.RemoveAll(dir)
    println "extract:", archive.TarZstdExtractAll(tz.data, tz.len, dir)
    println os.Exists(filepath.Join(dir, "notes/list.txt"))
    path := filepath.Join(dir, "all.tar.zst")
    println "file:", archive.TarZstdCreateFile(files, path)
    os.RemoveAll(dir)
end
Outputtar.zst: 178 bytes, true entries: true 3 hello.txt 6 notes 0 notes/list.txt 1000 true hello capped at 1000 bytes: false 0 extract: true true file: true

TarZstdCreateFile

func TarZstdCreateFile(files: Vector<TarFileInput>, outpath: str): bool
Writes a .tar.zst file.

The example for this item is shown with the ones above: archive-TarZstd.salam

TarZstdCreateFileLevel

func TarZstdCreateFileLevel(files: Vector<TarFileInput>, outpath: str, level: int): bool
Like TarZstdCreateFile, at the zstd level you give (1 to 22; the default is 3). The whole tar stream is compressed as one zstd frame while it is written, so memory stays at the encoder window and the size is that of ZstdCompressLevel on the whole tar. Older files made in 4 MB pieces are still read.

The example for this item is shown with the ones above: archive-WriteStream.salam

TarZstdListMax

func TarZstdListMax(p: void*, n: int, max: int, ok &: bool): Vector<Entry>
Same as TarZstdList, with your own limit max on the unpacked size in bytes.

The example for this item is shown with the ones above: archive-TarZstd.salam

TarZstdList

func TarZstdList(p: void*, n: int, ok &: bool): Vector<Entry>
The entries of a .tar.zst in memory; ok is false when the Zstandard data is invalid or unpacks past 1 GiB.

The example for this item is shown with the ones above: archive-TarZstd.salam

TarZstdExtractByNameMax

func TarZstdExtractByNameMax(p: void*, n: int, name: str, max: int, ok &: bool): compress.ByteBuf
Same as TarZstdExtractByName, with your own limit max on the unpacked size in bytes.

The example for this item is shown with the ones above: archive-TarZstd.salam

TarZstdExtractByName

func TarZstdExtractByName(p: void*, n: int, name: str, ok &: bool): compress.ByteBuf
The contents of one file of a .tar.zst.

The example for this item is shown with the ones above: archive-TarZstd.salam

TarZstdExtractAllMax

func TarZstdExtractAllMax(p: void*, n: int, destdir: str, max: int): bool
Same as TarZstdExtractAll, with your own limit max on the unpacked size in bytes.

The example for this item is shown with the ones above: archive-TarZstd.salam

TarZstdExtractAll

func TarZstdExtractAll(p: void*, n: int, destdir: str): bool
Decompresses a .tar.zst and writes it into the target directory like TarExtractAll; false when the Zstandard data is invalid or too big.

The example for this item is shown with the ones above: archive-TarZstd.salam

TarFileOpen

func TarFileOpen(path: str): TarFile
Opens a tar file for reading. Check status before going on.

The example for this item is shown with the ones above: archive-TarFile.salam

TarFileClose

func TarFileClose(tf &: TarFile)
Closes the file and releases the memory of an opened tar file.

The example for this item is shown with the ones above: archive-TarFile.salam

TarFileRewind

func TarFileRewind(tf &: TarFile)
Goes back to the first entry.

The example for this item is shown with the ones above: archive-TarFile.salam

FreeEntry

func FreeEntry(e &: Entry)
Frees the name and link of one entry returned by TarFileNext.

The example for this item is shown with the ones above: archive-TarFile.salam

TarFileNext

func TarFileNext(tf &: TarFile, e &: Entry): bool
Reads the next entry into e and returns false at the end. Sizes and offsets are 64 bit, so entries over 2 GB are listed normally. Free each entry with FreeEntry.

The example for this item is shown with the ones above: archive-TarFile.salam

TarFileEntries

func TarFileEntries(tf &: TarFile): Vector<Entry>
Lists every entry, then rewinds. Free the result with FreeEntries.

The example for this item is shown with the ones above: archive-TarFile.salam

TarFileExtractTo

func TarFileExtractTo(tf &: TarFile, e: Entry, destpath: str, cap: i64): int
Copies the data of the entry returned by the last TarFileNext to a file, in 64 KiB pieces, so memory use does not depend on its size. cap is a limit in bytes (0 for none): a bigger entry returns TAR_TOO_BIG and writes nothing.

The example for this item is shown with the ones above: archive-TarFile.salam

TarFileExtractAll

func TarFileExtractAll(path: str, destdir: str, cap: i64): int
Unpacks a tar on disk under a folder with the same safety rules as TarExtractAll and the same cap for each file. The result is TAR_OK or the status of the first entry that failed.

The example for this item is shown with the ones above: archive-TarFile.salam

TarStatusText

func TarStatusText(status: int): str
A short sentence for a TAR_... status.

The example for this item is shown with the ones above: archive-TarFile.salam

TarGzFileExtractAll

func TarGzFileExtractAll(path: str, destdir: str, cap: i64): int
Unpacks a .tar.gz on disk without writing the tar anywhere: the gzip data is inflated in pieces and fed straight to the tar reader. Same checks as TarFileExtractAll; cap limits each file. A cut or damaged stream gives TAR_CORRUPT and removes the file that was being written.
archive-TarStream.salam
import archive
import os

func main:
    body := "streamed straight from the compressed file\n"
    mut files := Vector {} as Vector<archive.TarFileInput>
    files.Push(archive.MakeTarFileInput("notes/a.txt", body as void*, body.Len(), false))
    files.Push(archive.MakeTarFileInput("notes/b.txt", body as void*, 10, false))
    println archive.TarGzCreateFile(files, "pack.tar.gz")
    files.Free()

    mut st := 0
    mut entries := archive.TarCompressedFileEntries("pack.tar.gz", archive.FormatTarGz, st)
    each e in entries:
        println e.name, e.size
    end
    println st
    archive.FreeEntries(entries)

    println archive.TarGzFileExtractAll("pack.tar.gz", "unpacked", 0 as i64)
    println os.FileSize("unpacked/notes/a.txt"), os.FileSize("unpacked/notes/b.txt")
    println archive.TarCompressedFileExtractAll("pack.tar.gz", archive.FormatTarGz, "capped", 20 as i64)
    println os.Exists("capped/notes/a.txt"), os.Exists("capped/notes/b.txt")
    os.RemoveAll("unpacked")
    os.RemoveAll("capped")
    os.Remove("pack.tar.gz")
end
Outputtrue notes/a.txt 43 notes/b.txt 10 0 0 43 10 6 false true

ReadBinaryFile

func ReadBinaryFile(path: str, ok &: bool): compress.ByteBuf
Reads every byte of a file into a buffer.

The example for this item is shown with the ones above: archive-Zip.salam

WriteBinaryFile

func WriteBinaryFile(path: str, p: void*, n: int): bool
Writes n bytes to a file.

The example for this item is shown with the ones above: archive-Tar.salam

WriteBinaryFileBuf

func WriteBinaryFileBuf(path: str, b: compress.ByteBuf): bool
Writes a buffer to a file.

The example for this item is shown with the ones above: archive-Tar.salam

EnsureDir

func EnsureDir(dir: str)
Makes the directory and the ones above it, when they are not there.

The example for this item is shown with the ones above: archive-Tar.salam

LEGet16

func LEGet16(p: void*, off: int): int
Reads a 16 bit little-endian integer from the given place in memory.

The example for this item is shown with the ones above: archive-Tar.salam

LEGet32

func LEGet32(p: void*, off: int): int
Reads a 32 bit little-endian integer.

The example for this item is shown with the ones above: archive-Tar.salam

LEPut16

func LEPut16(b &: compress.ByteBuf, v: int)
Adds a 16 bit integer to a buffer, little-endian.

The example for this item is shown with the ones above: archive-Tar.salam

LEPut32

func LEPut32(b &: compress.ByteBuf, v: int)
Adds a 32 bit integer, little-endian.

The example for this item is shown with the ones above: archive-Tar.salam

FreeEntries

func FreeEntries(v &: Vector<Entry>)
Frees the memory of the entry list.

The example for this item is shown with the ones above: archive-Zip.salam

GzipCompressFile

func GzipCompressFile(inpath: str, outpath: str): bool
Gzips a file, reading and compressing it in chunks (one gzip member; the compression has a single setting, no levels).

The example for this item is shown with the ones above: archive-Tar.salam

GzipDecompressFileCap

func GzipDecompressFileCap(inpath: str, outpath: str, cap: i64): int
Gunzips a file to another file in 64 KiB pieces, checking the CRC-32 and the size at the end, and returns an ARCHIVE_... status. cap limits the output in bytes (0 for none); a partly written output is removed on failure.

The example for this item is shown with the ones above: archive-TarFile.salam

GzipDecompressFile

func GzipDecompressFile(inpath: str, outpath: str): bool
Decompresses a gzip file.

The example for this item is shown with the ones above: archive-Tar.salam

MakeSevenZipFileInput

func MakeSevenZipFileInput(name: str, data_ptr: void*, data_len: int, is_dir: bool): SevenZipFileInput
Makes one 7z input.

The example for this item is shown with the ones above: archive-SevenZipCreate.salam

MakeSevenZipFilePath

func MakeSevenZipFilePath(name: str, path: str): SevenZipFileInput
Makes a 7z input that is read from a file on disk when the archive is written.

The example for this item is shown with the ones above: archive-WriteStream.salam

SevenZipCreateLevel

func SevenZipCreateLevel(files: Vector<SevenZipFileInput>, level: int): compress.ByteBuf
Builds a 7z archive in memory at a level: 0 stores (what SevenZipCreate does), 1 to 9 compress each file with LZMA in its own folder.

The example for this item is shown with the ones above: archive-WriteStream.salam

SevenZipCreate

func SevenZipCreate(files: Vector<SevenZipFileInput>): compress.ByteBuf
Builds a 7z archive in memory. At level 0 (the default) the files are stored without compression in one solid block, with a CRC-32 each; SevenZipCreateLevel compresses each file with LZMA instead. 7-Zip opens the result. A name that is empty or a negative length gives an empty buffer.

The example for this item is shown with the ones above: archive-SevenZipCreate.salam

SevenZipCreateFileLevel

func SevenZipCreateFileLevel(files: Vector<SevenZipFileInput>, path: str, level: int): bool
Writes a 7z archive to disk at a level like SevenZipCreateLevel. Level 0 copies the files from disk without loading them; with a level only one file is in memory at a time.

The example for this item is shown with the ones above: archive-WriteStream.salam

SevenZipCreateFile

func SevenZipCreateFile(files: Vector<SevenZipFileInput>, path: str): bool
Writes the 7z archive to disk and returns false when it cannot.

The example for this item is shown with the ones above: archive-SevenZipCreate.salam

RarFileOpen

func RarFileOpen(path: str): RarFile
Opens a RAR file by reading only its headers when it is RAR 5. Offsets and sizes are 64 bit. An archive with encrypted files or names needs RarFileOpenWith; a set of volumes needs RarFileOpenVolumes. Without them such files report RAR_ENCRYPTED or RAR_MULTIVOLUME.

The example for this item is shown with the ones above: archive-RarFile.salam

RarFileOpenWith

func RarFileOpenWith(path: str, password: str): RarFile
Like RarFileOpen, with a password for archives whose files or file names are encrypted. A wrong password reports RAR_BAD_PASSWORD. Encrypted RAR 5 data is decrypted while it is unpacked, so it never has to fit in memory.

The example for this item is shown with the ones above: archive-RarFileSet.salam

RarFileOpenVolumes

func RarFileOpenVolumes(first: str, password: str): RarFile
Opens a multi-volume RAR 5 set from its first volume (name.part1.rar, name.part01.rar or name.rar with .r00, .r01...) and finds the rest by name. A file split across volumes is read through all of them in turn, encrypted or not, without joining them in memory; password may be empty. A missing volume reports RAR_MULTIVOLUME for the files that cross it.

The example for this item is shown with the ones above: archive-RarFileSet.salam

RarFileClose

func RarFileClose(rf &: RarFile)
Releases the memory held by an opened RAR file.

The example for this item is shown with the ones above: archive-RarFile.salam

RarFileEntries

func RarFileEntries(rf &: RarFile): Vector<Entry>
Lists the entries. Free the result with FreeEntries.

The example for this item is shown with the ones above: archive-RarFile.salam

RarFileExtractTo

func RarFileExtractTo(rf &: RarFile, name: str, destpath: str, cap: i64, memcap: i64): int
Unpacks one entry to a file. The unpacked data is written in pieces and checked against the CRC-32 on the way, so it never has to fit in memory; only the decoder window and one block of packed data are held, whatever the size of the entry. cap is a limit in bytes for the unpacked data (0 for none), RAR_TOO_BIG is returned for an entry over it. memcap limits the window and block memory (0 for the 1 GiB default, which is also the most the decoder window can be): a dictionary bigger than that is not refused up front: the entry is unpacked with a window of that size, and RAR_WINDOW_TOO_BIG is returned only if the data really points farther back than the window (a RAR 7 archive made with a 6 GiB dictionary unpacks when its matches stay near).

The example for this item is shown with the ones above: archive-RarFile.salam

RarFileExtractAll

func RarFileExtractAll(rf &: RarFile, destdir: str, cap: i64, memcap: i64): int
Unpacks every entry under a folder, solid archives included, with the same limits. The result is RAR_OK or the status of the first entry that failed. Permissions and modification times are restored, symbolic links whose target stays inside the folder are created, and hard links and file copies become plain copies, as in RarReadAll; unsafe names and links are skipped and reported as RAR_UNSAFE_PATH.

The example for this item is shown with the ones above: archive-RarFile.salam

ZstdCompressFile

func ZstdCompressFile(inpath: str, outpath: str): bool
Compresses a file into a Zstandard (.zst) file at level 3; false when it cannot read or write.
archive-Zstd.salam
import archive
import compress
import filepath
import os

func main:
    dir := filepath.Join(os.TempDir(), "salam_zstd_example")
    os.RemoveAll(dir)
    os.MkdirAll(dir)
    plain := filepath.Join(dir, "notes.txt")
    packed := filepath.Join(dir, "notes.txt.zst")
    back := filepath.Join(dir, "notes.back")
    text := compress.BufFromStr("Salam keeps notes in plain files. ".Repeat(50))
    archive.WriteBinaryFileBuf(plain, text)

    println "pack:", archive.ZstdCompressFile(plain, packed)
    mut ok := false
    z := archive.ReadBinaryFile(packed, ok)
    println ok, z.len, "bytes,", compress.IsZstdBuf(z)
    println "unpack:", archive.ZstdDecompressFile(packed, back)
    again := archive.ReadBinaryFile(back, ok)
    println compress.BufEquals(again, text)
    println "level 19:", archive.ZstdCompressFileLevel(plain, packed, 19)
    println "wrong format:", archive.ZstdDecompressFile(plain, back)
    println "missing:", archive.ZstdDecompressFile(filepath.Join(dir, "none.zst"), back)
    os.RemoveAll(dir)
end
Outputpack: true true 57 bytes, true unpack: true true level 19: true wrong format: false missing: false

ZstdCompressFileLevel

func ZstdCompressFileLevel(inpath: str, outpath: str, level: int): bool
Like ZstdCompressFile, at the level you give (0 or less stores, 1 to 22 compress).

The example for this item is shown with the ones above: archive-Zstd.salam

ZstdDecompressFileCap

func ZstdDecompressFileCap(inpath: str, outpath: str, cap: i64): int
Decodes a .zst file to another file without loading either; the window is held in memory. cap limits the output. Returns ARCHIVE_OK, ARCHIVE_TOO_BIG, ARCHIVE_CORRUPT or ARCHIVE_IO_ERROR and removes the output on failure.

The example for this item is shown with the ones above: archive-TarStream.salam

ZstdDecompressFile

func ZstdDecompressFile(inpath: str, outpath: str): bool
Decompresses a Zstandard file; false when it cannot read or write or the data is not valid Zstandard. The checksum is verified and the whole result is held in memory first.

The example for this item is shown with the ones above: archive-Zstd.salam

SevenZipOpenFile

func SevenZipOpenFile(path: str, password: str): SevenZipFile
Opens a 7z on disk by reading its end header only (an encrypted or compressed header is unpacked first), so a file of any size opens at once. Pass the first piece (name.7z.001) of a split archive and the pieces that follow are found and read as one file, without being joined in memory. Check status before using the result.

The example for this item is shown with the ones above: archive-SevenZipFile.salam

SevenZipFileClose

func SevenZipFileClose(sf &: SevenZipFile)
Releases the memory held by an opened 7z file.

The example for this item is shown with the ones above: archive-SevenZipFile.salam

SevenZipFileEntries

func SevenZipFileEntries(sf &: SevenZipFile): Vector<Entry>
Lists the entries of an opened 7z file. Free the result with FreeEntries.

The example for this item is shown with the ones above: archive-SevenZipFile.salam

SevenZipFileExtractTo

func SevenZipFileExtractTo(sf &: SevenZipFile, name: str, destpath: str, cap: i64, memcap: i64): int
Unpacks one entry to a file. LZMA, LZMA2, DEFLATE, DEFLATE64, copy, delta and byte swap run as a stream with a dictionary sized window, so memory stays small and an entry can pass 2 GiB (a solid block is decoded from its start, then stops after the entry). cap is the most bytes an entry may have (0 for none) and gives SEVENZIP_TOO_BIG before anything is written. memcap is the most memory the decoder may use (0 for none). The branch filters, BCJ2, PPMd, bzip2 and AES-256 stream too, alone or in chains such as AES, LZMA2 and BCJ. Past cap or memcap the result is SEVENZIP_TOO_BIG; a PPMd model over 2 GiB is refused with the same status.

The example for this item is shown with the ones above: archive-SevenZipFile.salam

SevenZipFileExtractAll

func SevenZipFileExtractAll(sf &: SevenZipFile, destdir: str, cap: i64, memcap: i64): int
Unpacks every entry under a folder, one pass per solid block, with the same checks, cap and memcap. Unsafe names are skipped and reported as SEVENZIP_UNSAFE_PATH; symbolic links are made when their target stays inside the folder. Returns the first problem, or SEVENZIP_OK.

The example for this item is shown with the ones above: archive-SevenZipFile.salam

SevenZipReadCap

func SevenZipReadCap(arc &: SevenZipArchive, name: str, cap: i64): compress.ByteBuf
Like SevenZipRead with a 64-bit cap in bytes (0 means the 2 GiB a buffer holds). An entry over it returns an empty buffer and sets status to SEVENZIP_TOO_BIG.doc.SevenZipListStatus = Like SevenZipList, and status says why the list is empty when the archive could not be read.

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipReadAllCap

func SevenZipReadAllCap(arc &: SevenZipArchive, destdir: str, cap: i64, memcap: i64): int
Like SevenZipReadAll with limits: cap is the most bytes one entry may unpack to (0 for none; an entry over it is skipped and status becomes SEVENZIP_TOO_BIG) and memcap the most memory a decoder may use (0 for none).

The example for this item is shown with the ones above: archive-SevenZip.salam

SevenZipEntriesOf

func SevenZipEntriesOf(arc &: SevenZipArchive): Vector<Entry>
The same as SevenZipEntries; it is the name the in-memory and on-disk listings share.

The example for this item is shown with the ones above: archive-SevenZip.salam

MakeZipFileInput

func MakeZipFileInput(name: str, data_ptr: void*, data_len: int, method: int): ZipFileInput
Makes one zip input.

The example for this item is shown with the ones above: archive-Zip.salam

MakeZipFileInputLevel

func MakeZipFileInputLevel(name: str, data_ptr: void*, data_len: int, method: int, level: int): ZipFileInput
Makes one zip input with a compression level.

The example for this item is shown with the ones above: archive-ZipMethods.salam

ZipCreate

func ZipCreate(files: Vector<ZipFileInput>): compress.ByteBuf
Builds a zip archive in memory. Names with non-ASCII bytes get the UTF-8 flag. Any method other than 8 stores the file. The result is empty when an input is invalid (negative length, null address with a length, name over 65535 bytes) or the total is over about 1.9 GB. The archive is written by the same entry writer as ZipCreateFile, into a growing buffer, so every entry is compressed in pieces by the encoders and no second copy of the archive body is built; what stays in memory is the returned archive and your input buffers. Encrypted entries take the same path.

The example for this item is shown with the ones above: archive-Zip.salam

ZipCreate64

func ZipCreate64(files: Vector<ZipFileInput>): compress.ByteBuf
Like ZipCreate, but always writes the zip64 form: 64-bit sizes and offsets in extra fields, the zip64 end record and its locator. unzip and 7-Zip read it; use it to test zip64 readers. Empty on invalid input.
archive-ZipTime.salam
import archive
import compress

func main:
    text := "salam, salam, salam"
    b := compress.BufFromStr(text)
    mut named := archive.MakeZipFileInput("سلام.txt", b.data, b.len, 8)
    named.mtime = 1700000000 as i64
    mut files := Vector {} as Vector<archive.ZipFileInput>
    files.Push(named)
    files.Push(archive.MakeZipFileInput("plain.txt", b.data, b.len, 8))
    z := archive.ZipCreate(files)
    mut entries := archive.ZipList(z.data, z.len)
    each e in entries:
        println e.name, e.mtime
    end
    archive.FreeEntries(entries)
    println "utf8 flag:", (archive.LEGet16(z.data, 6) & 0x800) != 0

    wide := archive.ZipCreate64(files)
    mut again := archive.ZipList(wide.data, wide.len)
    println again.Len(), wide.len > z.len, again.Get(0).size
    archive.FreeEntries(again)
    mut checked := 0
    println archive.ZipVerify(wide.data, wide.len, checked), checked
end
Outputسلام.txt 1700000000 plain.txt 315532800 utf8 flag: true 2 true 19 0 2

ZipCreateFile

func ZipCreateFile(files: Vector<ZipFileInput>, outpath: str): bool
Writes a zip archive to a file.

The example for this item is shown with the ones above: archive-Zip.salam

ZipCreateFile64

func ZipCreateFile64(files: Vector<ZipFileInput>, outpath: str): bool
Like ZipCreateFile, but always writes the zip64 form. Without it ZipCreateFile still switches to zip64 for entries of 4 GB or more, for offsets past 4 GB and for 65535 entries or more.

The example for this item is shown with the ones above: archive-WriteStream.salam

MakeZipFilePath

func MakeZipFilePath(name: str, path: str, method: int, level: int): ZipFileInput
Makes a zip input that is read from a file on disk when the archive is written. Stored, DEFLATE, bzip2, LZMA and zstd entries are all read and compressed in pieces.

The example for this item is shown with the ones above: archive-WriteStream.salam

MakeZipFileInputEncrypted

func MakeZipFileInputEncrypted(name: str, data_ptr: void*, data_len: int, method: int, level: int, password: str, encryption: int): ZipFileInput
Makes a zip input with a password and an encryption (ZipEncAuto and the others below).

The example for this item is shown with the ones above: archive-WriteStream.salam

ZipList

func ZipList(p: void*, n: int): Vector<Entry>
The entries of a zip in memory.

The example for this item is shown with the ones above: archive-Zip.salam

ZipExtractByName

func ZipExtractByName(p: void*, n: int, name: str, ok &: bool): compress.ByteBuf
Pulls out the contents of one entry; ok becomes false when the name is not found, the entry is encrypted, or its method is not 0 or 8. The CRC is not checked.

The example for this item is shown with the ones above: archive-Zip.salam

ZipExtractByNameMax

func ZipExtractByNameMax(p: void*, n: int, name: str, max: int, ok &: bool): compress.ByteBuf
Same as ZipExtractByName, but ok becomes false when the entry would be larger than max bytes, checked while it is inflated. Use it on archives from other people, where a few kilobytes can claim to hold gigabytes.

The example for this item is shown with the ones above: archive-Zip.salam

ZipExtractVerified

func ZipExtractVerified(p: void*, n: int, name: str, max: int, status &: int): compress.ByteBuf
Pulls out one entry and checks its size and CRC-32. status is set to one of the ZIP_ codes, ZIP_OK on success, otherwise the reason, and the buffer is empty. max caps the unpacked size, or 0 for no cap.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZipVerify

func ZipVerify(p: void*, n: int, checked &: int): int
Inflates every file entry and checks its size and CRC-32. Sets checked to how many it looked at and returns how many failed (encrypted, unsupported or too big count as failed), 0 when all are good, or -1 when the data is not a zip.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZipBadEntries

func ZipBadEntries(p: void*, n: int): Vector<Entry>
The entries that fail ZipVerify; free the list with FreeEntries.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZipStatusText

func ZipStatusText(status: int): str
A short English description of a ZIP_ status code.

The example for this item is shown with the ones above: archive-ZipVerify.salam

ZipExtractAll

func ZipExtractAll(p: void*, n: int, destdir: str): bool
Writes every entry into the target directory, after checking its CRC-32. An entry with an unsafe name or a failed check is not written and the result is false. When the data is not a zip it has no entries and nothing is written.

The example for this item is shown with the ones above: archive-Zip.salam

TarCompressedFileExtractAll

func TarCompressedFileExtractAll(path: str, format: int, destdir: str, cap: i64): int
Unpacks a compressed tar on disk in one pass. format is FormatTarGz, FormatTarBz2, FormatTarXz or FormatTarZstd. Nothing but the current file is held; the checks and the cap are those of TarFileExtractAll.

The example for this item is shown with the ones above: archive-TarStream.salam

TarCompressedFileEntries

func TarCompressedFileEntries(path: str, format: int, status &: int): Vector<Entry>
Lists a compressed tar on disk in one pass without unpacking the contents. status is set to TAR_OK or why the stream ended early. Free the result with FreeEntries.

The example for this item is shown with the ones above: archive-TarStream.salam

TarBz2FileExtractAll

func TarBz2FileExtractAll(path: str, destdir: str, cap: i64): int
The same for a .tar.bz2: the bzip2 blocks are decoded one at a time and streamed into the tar reader, so memory stays at a block, not at the archive.

The example for this item is shown with the ones above: archive-TarStream.salam

TarXzFileExtractAll

func TarXzFileExtractAll(path: str, destdir: str, cap: i64): int
The same for a .tar.xz: the blocks are decoded one at a time with XzFileToSink and streamed into the tar reader.

The example for this item is shown with the ones above: archive-TarStream.salam

TarZstdFileExtractAll

func TarZstdFileExtractAll(path: str, destdir: str, cap: i64): int
The same for a .tar.zst: decoded with ZstdFileToSink through a sliding window and streamed into the tar reader.

The example for this item is shown with the ones above: archive-TarStream.salam

TarCompressedFileExtractTo

func TarCompressedFileExtractTo(path: str, format: int, name: str, destpath: str, cap: i64, total: i64): int
Unpacks one file of a compressed tar on disk to destpath in one pass, stopping as soon as it is written. cap limits that file and total the whole unpacked stream (0 for none). Returns TAR_NOT_FOUND when no file has that name.

The example for this item is shown with the ones above: archive-TarStream.salam

ZipCreateFileSplit

func ZipCreateFileSplit(files: Vector<ZipFileInput>, outpath: str, part_size: i64, style: int): bool
Writes a zip archive as pieces of at most part_size bytes (at least 65536, under 4 GiB). With ZipSplitDisk the pieces are name.z01, name.z02 and so on, with the last one named name.zip, the way Info-ZIP and 7-Zip write them: every piece has its disk number in the central directory, no header is split across two pieces, and the first piece starts with the spanning marker. With ZipSplitByte the finished archive is cut into name.zip.001, name.zip.002 and so on, which 7-Zip opens as one file. Entries are streamed as in ZipCreateFile and can use any method and password. The archive is first written whole to name.salamsplit.tmp next to the output, so the disk needs room for it twice. Returns false and removes the pieces when something fails.

The example for this item is shown with the ones above: archive-ZipSplit.salam

MakeFileInput

func MakeFileInput(name: str, data_ptr: void*, data_len: int, is_dir: bool): FileInput
Makes one FileInput.

The example for this item is shown with the ones above: archive-Open.salam

DefaultLimits

func DefaultLimits(): Limits
Returns the default Limits.

The example for this item is shown with the ones above: archive-Open.salam

ArchiveStatusText

func ArchiveStatusText(status: int): str
A short English description of an ARCHIVE_ code.

The example for this item is shown with the ones above: archive-Open.salam

FormatName

func FormatName(format: int): str
The short name of a Format code, such as tar.gz.

The example for this item is shown with the ones above: archive-Open.salam

Detect

func Detect(p: void*, n: int): int
Finds the format from the first bytes (and the header checksum for tar). A gzip, bzip2 or xz file is reported as itself even when a tar is inside; Open looks inside.

The example for this item is shown with the ones above: archive-Open.salam

DetectName

func DetectName(path: str): int
Guesses the format from a file name ending such as .zip, .tar.gz, .tgz, .rar or .7z; FormatUnknown when nothing matches.

The example for this item is shown with the ones above: archive-Open.salam

OpenWith

func OpenWith(p: void*, n: int, password: str, limits: Limits): Archive
Like Open with your own Limits.

The example for this item is shown with the ones above: archive-Open.salam

Open

func Open(p: void*, n: int, password: str): Archive
Opens archive bytes of any format, found by its first bytes, with the default limits. A gzip, bzip2 or xz file is unpacked at once and a tar inside is recognized. Check status afterwards.

The example for this item is shown with the ones above: archive-Open.salam

OpenFile

func OpenFile(path: str, password: str): Archive
Opens a file on disk. A zip, tar, tar.gz, 7z or RAR 5 file is not read into memory: only its list of entries is, and every call after that reads and writes in pieces, so the file can be of any size and data stays null. A tar.gz is read as a stream through gzip with no temporary file: listing and extracting each decode it again from the start, stopping as soon as the entry wanted is done, and max_total limits the unpacked bytes of one pass. Other formats (bzip2, xz, zstd, a single gzip file, a RAR with a password) are read whole and opened like Open. Limits apply either way.

The example for this item is shown with the ones above: archive-Open.salam

SetLimits

func SetLimits(arc &: Archive, limits: Limits)
Replaces the limits of an opened archive.

The example for this item is shown with the ones above: archive-Open.salam

Close

func Close(arc &: Archive)
Frees what the archive holds.

The example for this item is shown with the ones above: archive-Open.salam

List

func List(arc &: Archive): Vector<Entry>
Lists the entries of any format, in one Entry model. Free with FreeEntries.

The example for this item is shown with the ones above: archive-Open.salam

Read

func Read(arc &: Archive, name: str): compress.ByteBuf
Reads one entry by name, up to max_entry bytes. status says what happened; the buffer is empty unless it is ARCHIVE_OK.

The example for this item is shown with the ones above: archive-Open.salam

ExtractAll

func ExtractAll(arc &: Archive, destdir: str): int
Extracts everything into a folder. First every entry is checked against the limits and for unsafe names, absolute paths, .., links that leave the folder, writes through links and device entries; if any check fails nothing is written and status says why. Returns the number of files, or 0 on failure.

The example for this item is shown with the ones above: archive-Open.salam

Extract

func Extract(arc &: Archive, name: str, destdir: str): bool
Extracts one file or folder by name, with the same name checks. Returns false and sets status on failure.

The example for this item is shown with the ones above: archive-Open.salam

ListFile

func ListFile(path: str, password: str, status &: int): Vector<Entry>
Opens a file, lists it and closes it. status gets the result.

The example for this item is shown with the ones above: archive-Open.salam

ExtractFile

func ExtractFile(path: str, destdir: str, password: str, status &: int): int
Opens a file, extracts it into a folder and closes it. Returns the number of files.

The example for this item is shown with the ones above: archive-Open.salam

CreateBuf

func CreateBuf(format: int, files: Vector<FileInput>, status &: int): compress.ByteBuf
Builds an archive of the given Format in memory: zip, tar, tar.gz, tar.bz2, rar and 7z (stored), or gzip and bzip2 with exactly one file. Other formats give ARCHIVE_UNSUPPORTED; an unsafe name gives ARCHIVE_UNSAFE_PATH.

The example for this item is shown with the ones above: archive-Open.salam

Create

func Create(path: str, files: Vector<FileInput>): int
Builds an archive and writes it to a path; the format comes from the ending of the name (DetectName). Returns an ARCHIVE_ code.

The example for this item is shown with the ones above: archive-Open.salam

IsRar

func IsRar(p: void*, n: int): bool
True when the data starts with the RAR signature.

The example for this item is shown with the ones above: archive-Zip.salam

RarStatusText

func RarStatusText(status: int): str
A short English description of a RAR_ status code.

The example for this item is shown with the ones above: archive-Rar.salam

RarList

func RarList(p: void*, n: int): Vector<Entry>
The entries of a RAR archive.

The example for this item is shown with the ones above: archive-Zip.salam

RarExtract

func RarExtract(p: void*, n: int, name: str, max: int, status &: int): compress.ByteBuf
The contents of one RAR entry, found by its exact name. status is set to one of the RAR_ codes: RAR_OK on success, otherwise the reason, and the buffer is empty. max caps the unpacked size, or 0 for no cap.

The example for this item is shown with the ones above: archive-Rar.salam

RarExtractByNameMax

func RarExtractByNameMax(p: void*, n: int, name: str, max: int, ok &: bool): compress.ByteBuf
Same as RarExtractByName, but ok becomes false when the entry is larger than max bytes, which is checked before anything is unpacked.

The example for this item is shown with the ones above: archive-Rar.salam

RarExtractByName

func RarExtractByName(p: void*, n: int, name: str, ok &: bool): compress.ByteBuf
The contents of one RAR entry, found by its exact name. ok is false when it is missing, unsupported, encrypted or damaged; use RarExtract to learn which.

The example for this item is shown with the ones above: archive-Zip.salam

RarExtractAllStatus

func RarExtractAllStatus(p: void*, n: int, destdir: str, status &: int): int
Same as RarExtractAll, but returns how many entries were written and sets status to the first problem it met. An entry whose name would leave the target directory, or a symbolic link whose target would, is skipped and reported as RAR_UNSAFE_PATH.

The example for this item is shown with the ones above: archive-Rar.salam

RarExtractAll

func RarExtractAll(p: void*, n: int, destdir: str): bool
Pulls out every RAR entry, never writing outside the target directory.

The example for this item is shown with the ones above: archive-Zip.salam

RarOpen

func RarOpen(p: void*, n: int, password: str): RarArchive
Wraps archive data and a password in a RarArchive. Nothing is copied or read yet.

The example for this item is shown with the ones above: archive-RarPassword.salam

RarEntries

func RarEntries(arc &: RarArchive): Vector<Entry>
The entries of the archive, using its password. Sets status to RAR_ENCRYPTED or RAR_BAD_PASSWORD when the names cannot be read.

The example for this item is shown with the ones above: archive-RarPassword.salam

RarRead

func RarRead(arc &: RarArchive, name: str, max: int): compress.ByteBuf
The contents of one entry, found by its exact name, decrypted with the password. max caps the unpacked size, or 0 for no cap. Sets status.

The example for this item is shown with the ones above: archive-RarPassword.salam

RarReadAll

func RarReadAll(arc &: RarArchive, destdir: str): int
Writes every entry into the target directory, never outside it, and returns how many were written. Sets status to the first problem.

The example for this item is shown with the ones above: archive-RarPassword.salam

RarReadVolumes

func RarReadVolumes(first: str, ok &: bool): Vector<compress.ByteBuf>
Reads the first volume and every following one it can find by the usual names (name.part01.rar, name.part02.rar, or name.rar, name.r00, name.r01). ok is false when the first file cannot be read.
archive-RarVolumes.salam
import archive
import compress

const VOL1 := """
526172211a0701006de128270b01050701060101808080002c64b9412502130be78600048df500a48302c8ac493d8005
0105762e7478740a0313c60bf16a7ed75827cc5dc30845643444334f3565365536a7751848c413a8c1d5a93ff0a349ca
1575f48991859458af2f2ba874489a028b323f09e3cf1e32ffefaf9f97e7e9e9e3edf6f1fa579a7a7d7c3dbdfcbebe3e
7f9f0fa7dbc3d3d3c16d1eff9ff7f7f2fd6ec95fb7f5e3f169de0de1e7efea4f755ebf7e5fe7d7f1fbe5efdec9ebf7f0
ac07f5f8f3ffbd1b1bddbb560ebd7589d7ab57eac6759257a2be6b5bff06db5907b7bfa37e2771d6115e7d65b5b1ead5
bc777f89dd96b66f649d2dbd8d5fb76ce932faf6d637ab6eb48ebc7784ebcd71b4dd9bcee1bd1377eeefbd11bfaa6188
98a280bb6b6d5a47dab204c174a6eafdbcad94b9666ab7f59414fe5a1970fab96f34eaf29a0edb711056b5ceb7494e85
b83775441bc51f56f4dc85bb03667c21d75603e2af914e76c0fb7fb5f428b8fa03bdef2854a35f5ad1273344a09bfacf
3d171047a766aa0d8c11896e85ced5a3fffcee5af7d608ba9d99ccb1aa2be1aa1342ae8b3ae9744562654f1606e38681
3201eddbf1afb701e2c1bbbff9efe02d2e17480a0962ab9b850cc218ea736bad10726ac6adab51e376d55ac13a036d61
8ec3818e63acd5ef5acb6746eae8ead37a7bb694b7a4c144844a6fa10afaf9603e08b482196964dcc8844ab4e013abdb
b4253899ef86069c3bb146ea4f805c057d5d03e101866c22c2413f3901cef35cb2faa62459ed943aafe3345d4aac4411
bb6c32bd58e376ad8393fda6c9ab56441546a250934dc2b662a55ca908f1fb6b12556784fd827901ad81c55caab012f8
0a35c584d114212450a1a8e1dc067711a39dda12659ce0d861a2ce3fafba224e2122c97cd0f5f92425ddfb9c36c9c953
6714555e7051d7dc252c7646f0df25808c58e78b266f0b92b8b917e2c910c0c3af16037381d7939fc090853cdd8df086
7370634378a2c228d4a8c0273788104daf093c9e6dccb0410dceb0215c0610eebaf222187780368a3dd2303226e99cf9
803e25ff56547e270704384ae9021fbc501683ba7cb179dcc0ae76d5600476f4c2ac82942f313d6213c24edbc0445454
d01f0c5e11d1f2ab6437eeafd08d1a3e40e3b6028205a2d7c3383a23c3fad885328bc65c5718d8d8630cfafc1b88c05c
bceb14fad1feaf94c163c9738d355824356adba1ca97a4a959832f630220a908b8b815c8b9acf685c0a255b735826132
911a80b69b45726abd4f52371614f9e267fe5840155b011bb28b47512603050401000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000
"""

const VOL2 := """
526172211a070100a9c2c4ca0c01050703010601018080800064563ccc25021b0be68600048df500a483020002230880
050105762e7478740a0313c60bf16a7ed75827046840f3834518cedc2f96f6bbb89190a3b6d9c514aacde7ee173d264c
b8f0692c7ca6b792780ee2bef245c9c3c949222294d2e016d242cd89838cbfa39edcb53775439267227627f0b5b02174
c9d22a0f2190336159b20695cd4c7113ce32dd1e2151829ab73dfea0950912309fda1d69b59f9b6e641be295e0f1f394
d8fd5c492fccc8a69b3426b4ab0d12b035942a0dfc9ca3a2401d11d385b8a8f007ead59f3e1694e6f315576c22200f28
4cd5c4a56653424b06d609611a293322bceeaf554095f3cca784064d2e5174624dd2a741e712bf8435f0a0c44458c205
f0a4b74671b82bb9635e6e10b24863da4475cc8f5a03b84b084d8bbf0834706da6cc792f4240b267a1fc20e04f3f4633
546acb84c2681dee1c00a436b6d9cccfdbffa1cad473bc7540b0002c96977021c9e8b443db4c80abd793bb7bd0d3305d
44416d504a0a9b699832d700ad111e6478d7e798ad90f492f8d248b49cd1380d23cfce8c4692ca5f5c3e8958a9b66477
c2a7d91522b7672ec51114c161dd650d948da76149d23cccc99308d707fc1db5100c4eba404d61309b83bb3c7503742b
a94a7440bae2115fd613fe21302d369c8b24bbe9c988d4eec33d9fbdc7c9038887de34419353b1bf82c0855b6c2277d6
8a8492d6e708fc7de0fa008c102633d12552fcaae7639fa3a0de6daf2336895df8a09169ed7e67ba0af51a4119c1daaa
71d7c254c05abbdab89669a40940e34742bf31a601545cdd2010c7e55016edb49cd2d7073b67d5f9ab38d9c418e76a44
f8394a65a783ab16db093629a33bd2ac91bdfb948263c08a0e4c9a4cae7af9eff46102d7bc913b5cb84a12b623a0a09f
ed11700ead0b984e3e78193ce0190ede74759a8ba34e3cee326dab0b3482d69a9af4f2e125c2d5c85cebccceb0e79c72
862a1f4252f2a18c33614af63cd523378109df9c8408d09c7e1dcc497bf400d082d87505f29af8f49a2034d6e575af9c
0e0ae77f857693f8e11cebcfb19f40a6fd1856362b74b7821b726242542b9c1c9c0add41783d931149e85a37418dba78
73ad990a9a4c7ac61b257db791159b11375886f2655cf56469191a5f853dba4f909dd88210d27dae6335450e4886e1a9
0976178ef226e03a38f420961ab7e866c8e252e62d8d1cd7eaaa2634d2747769c7a19d0e2d6c3c119034c1092a54ae36
4d4888b31633aa9473da001976173bcb5422b5d9d1922d044d8b47512603050401000000000000000000000000000000
000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
00000000000000000000000000000000
"""

const VOL3 := """
526172211a0701004ac54b440c0105070302060101808080004fb1c48c25020b0bfa8300048df500a4830287c98a0f80
050105762e7478740a0313c60bf16a7ed758276e9e2146d09044d59e5c974bc9e14a51910cdd41b71dcbf4f11fafd98d
16fb2d0683270a40c720ef76ab99b90b355e72e2acf71ea3c079e458b57797a810a9320e5b8f495efd066558b0974909
e6a8cff09481c66b5ee1259c3d36f48eeb7ec0f22fe946721c718c317a6058d161bf759e1c1e9a5b9427d538a4a3aade
0c326b40453c6b35b52d882e9413dbc82c5dc62160fc39a3b92dce54ac533a592fd09af8aba6fc2578f5cf12048671b2
740297a0d81a2d8f87113e877a3d3645e68034c922e7f1af8d0a794f3061e8696f2def1b8d951da84ce31a294f7c79a9
d784db31486ab60718767955e357868e61a57a866f4d072a16d82b283f8370e98ca225dd77dcf92004ea79317d93484a
62722811c2d2124f214fa55393d104c65b346abd4c63ecea91ca5bab74f0eb6af2378bc9734b8ad6ad79745d233884a7
6f99443c8e46eceeb4b9bc79895e4dedea7a4a4a2f1126126cadd27c20d3f24c0fbff173f03b3e4974014f428733869b
7f1b1916980a4335126a67984987f010b31fdcfd33edf46177414ac7a83f0909729736c70710e4bd7fb79cbf1924248d
8a2111eb874fa21f667084ea442d5950d187fd9eb2f066e09224441fbc9f32719e36176cab4d67b74200ba2c55397958
d35451df7777b403b0a724d22cb9a9a5ce7a7d72484b628b53c8b1cb893c158e558776fe1fc54ecdbc7cbe36e87c047d
942702030b8500048500a4830210c43fd080000109736d616c6c2e7478740a0313bd0bf16a5abb310b74696e790a1d77
565103050400
"""

func digit(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func from_hex(text: str): compress.ByteBuf:
    mut out := compress.NewByteBuf()
    bytes := text as u8*
    mut high := -1
    repeat text.Len() in i:
        v := digit(bytes[i] as int)
        if v < 0:
            continue
        end
        if high < 0:
            high = v
        else:
            compress.BufPush(out, high * 16 + v)
            high = -1
        end
    end
    ret out
end

func main:
    mut volumes := Vector {} as Vector<compress.ByteBuf>
    volumes.Push(from_hex(VOL1))
    volumes.Push(from_hex(VOL2))
    volumes.Push(from_hex(VOL3))

    mut arc := archive.RarOpenVolumes(volumes, "")
    mut names := archive.RarEntries(arc)
    each e in names:
        data := archive.RarRead(arc, e.name, 0)
        println e.name, e.size, data.len, archive.RarStatusText(arc.status)
    end
    archive.FreeEntries(names)
    archive.RarClose(arc)

    mut partial := Vector {} as Vector<compress.ByteBuf>
    partial.Push(volumes.Get(0))
    partial.Push(volumes.Get(1))
    mut broken := archive.RarOpenVolumes(partial, "")
    gone := archive.RarRead(broken, "v.txt", 0)
    println gone.len, broken.status == archive.RAR_MULTIVOLUME
    archive.RarClose(broken)

    archive.WriteBinaryFileBuf("set.part01.rar", volumes.Get(0))
    archive.WriteBinaryFileBuf("set.part02.rar", volumes.Get(1))
    archive.WriteBinaryFileBuf("set.part03.rar", volumes.Get(2))
    mut ok := false
    mut found := archive.RarReadVolumes("set.part01.rar", ok)
    println ok, found.Len()
    archive.RarFreeVolumes(found)
end
Outputv.txt 14989 14989 ok small.txt 5 5 ok 0 true true 3

RarFreeVolumes

func RarFreeVolumes(vols &: Vector<compress.ByteBuf>)
Frees the volumes read by RarReadVolumes.

The example for this item is shown with the ones above: archive-RarVolumes.salam

RarOpenVolumes

func RarOpenVolumes(vols: Vector<compress.ByteBuf>, password: str): RarArchive
Like RarOpen, for a list of volumes in order. The buffers must stay alive while the archive is used.

The example for this item is shown with the ones above: archive-RarVolumes.salam

RarClose

func RarClose(arc &: RarArchive)
Releases what a RarArchive holds; the volumes themselves are freed with RarFreeVolumes.

The example for this item is shown with the ones above: archive-RarVolumes.salam

MakeRarFileInput

func MakeRarFileInput(name: str, data_ptr: void*, data_len: int, is_dir: bool): RarFileInput
Makes one RAR input.

The example for this item is shown with the ones above: archive-Rar.salam

RarCreate

func RarCreate(files: Vector<RarFileInput>): compress.ByteBuf
Builds a RAR 5 archive in memory. The files are stored without compression, with a CRC-32 each, and any RAR tool can open the result.

The example for this item is shown with the ones above: archive-Rar.salam

RarCreateFile

func RarCreateFile(files: Vector<RarFileInput>, outpath: str): bool
Writes the RAR 5 archive to disk and returns false when it cannot.

The example for this item is shown with the ones above: archive-Rar.salam

XzCompressFile

func XzCompressFile(inpath: str, outpath: str): bool
Compresses a file into an .xz file (level 6, CRC-64 check); false when it cannot read or write. The file is read and compressed in chunks of SetWriteChunk bytes, written as one .xz stream per chunk.
archive-Xz.salam
import archive
import compress
import filepath
import os

const XZ := """
fd377a585a000004e6d6b44604c05fcf022101160000000000000000bb0ccf6ce0014e00575d0029984986240afb8a34e4
81db780958f3d0144436dd3bb4ca45234051fa042e5be576402f66b72801fb0f3b421e32e3eba071037cdd425338444ede
4cb8c8c742828bc92c1b53df8ea763015d902c3d49f9c602aacf40a000005b35fff6fd65c4e300017bcf020000005e9efc
63b1c467fb020000000004595a
"""

const LZMA := """
5d00008000ffffffffffffffff0029984986240afb8a34e481db780958f3d0144436dd3bb4ca45234051fa042e5be57640
2f66b72801fb0f3b421e32e3eba071037cdd425338444ede4cb8c8c742828bc92c1b53df8ea763015d902c3d49f9c602ad
8d68e0bcfed44dc0
"""

func nib(c: int): int:
    if c >= 48 and c <= 57:
        ret c - 48
    end
    if c >= 97 and c <= 102:
        ret c - 87
    end
    ret -1
end

func unhex(s: str): compress.ByteBuf:
    mut b := compress.NewByteBuf()
    bp := s as u8*
    mut hi := -1
    repeat s.Len() in i:
        v := nib(bp[i] as int)
        if v < 0:
            continue
        end
        if hi < 0:
            hi = v
        else:
            compress.BufPush(b, hi * 16 + v)
            hi = -1
        end
    end
    ret b
end

func main:
    dir := filepath.Join(os.TempDir(), "salam_xz_example")
    os.RemoveAll(dir)
    os.MkdirAll(dir)
    xz_path := filepath.Join(dir, "notes.txt.xz")
    lzma_path := filepath.Join(dir, "notes.txt.lzma")
    out_path := filepath.Join(dir, "notes.txt")
    archive.WriteBinaryFileBuf(xz_path, unhex(XZ))
    archive.WriteBinaryFileBuf(lzma_path, unhex(LZMA))

    println "xz:", archive.XzDecompressFile(xz_path, out_path)
    mut ok := false
    text := archive.ReadBinaryFile(out_path, ok)
    println ok, text.len, "bytes"
    println "lzma:", archive.LzmaDecompressFile(lzma_path, out_path)
    println "wrong format:", archive.XzDecompressFile(lzma_path, out_path)
    println "missing:", archive.XzDecompressFile(filepath.Join(dir, "none.xz"), out_path)

    plain := filepath.Join(dir, "plain.txt")
    archive.WriteBinaryFileBuf(plain, text)
    packed := filepath.Join(dir, "plain.txt.xz")
    println "pack xz:", archive.XzCompressFile(plain, packed), archive.XzDecompressFile(packed, out_path)
    println "pack lzma:", archive.LzmaCompressFile(plain, lzma_path), archive.LzmaDecompressFile(lzma_path, out_path)
    println "pack missing:", archive.XzCompressFile(filepath.Join(dir, "none.txt"), packed)
    os.RemoveAll(dir)
end
Outputxz: true true 335 bytes lzma: true wrong format: false missing: false pack xz: true true pack lzma: true true pack missing: false

XzCompressFileLevel

func XzCompressFileLevel(inpath: str, outpath: str, level: int): bool
Like XzCompressFile, at the level you give (0 to 9; 0 stores in LZMA2 chunks).

The example for this item is shown with the ones above: archive-WriteStream.salam

LzmaCompressFile

func LzmaCompressFile(inpath: str, outpath: str): bool
Compresses a file into an old .lzma file (level 6); false when it cannot read or write.

The example for this item is shown with the ones above: archive-Xz.salam

LzmaCompressFileLevel

func LzmaCompressFileLevel(inpath: str, outpath: str, level: int): bool
Like LzmaCompressFile, at the level you give (1 to 9, default 6). The format cannot be cut into chunks, so the whole file is held in memory.

The example for this item is shown with the ones above: archive-WriteStream.salam

XzDecompressFile

func XzDecompressFile(inpath: str, outpath: str): bool
Decompresses an .xz file into a new file and returns true on success. The checks inside the file are verified; nothing is written when one fails. The whole result is held in memory first.

The example for this item is shown with the ones above: archive-Xz.salam

XzDecompressFileCap

func XzDecompressFileCap(inpath: str, outpath: str, cap: i64): int
Decompresses an .xz file into a new file and returns an ARCHIVE_... status. cap limits the output in bytes (0 for none); ARCHIVE_TOO_BIG means the data would pass it and ARCHIVE_CORRUPT that the file is damaged. Nothing is left behind on failure.
archive-FileCap.salam
import archive
import compress
import filepath
import os

func main:
    dir := filepath.Join(os.TempDir(), "salam_filecap_example")
    os.MkdirAll(dir)
    src := filepath.Join(dir, "plain.bin")
    packed := filepath.Join(dir, "plain.xz")
    back := filepath.Join(dir, "back.bin")
    mut raw := compress.NewByteBuf()
    repeat 20000 in i:
        compress.BufPush(raw, 97 + (i % 5))
    end
    _ := archive.WriteBinaryFileBuf(src, raw)
    _ := archive.XzCompressFile(src, packed)
    println archive.ArchiveStatusText(archive.XzDecompressFileCap(packed, back, 1000 as i64))
    println archive.ArchiveStatusText(archive.XzDecompressFileCap(packed, back, 0 as i64))
    _ := archive.Bzip2CompressFile(src, packed)
    println archive.ArchiveStatusText(archive.Bzip2DecompressFileCap(packed, back, 1000 as i64))
    println archive.ArchiveStatusText(archive.Bzip2DecompressFileCap(packed, back, 0 as i64))
    println archive.ArchiveStatusText(archive.LzmaDecompressFileCap(src, back, 0 as i64))
    os.RemoveAll(dir)
end
Outputentry too large ok entry too large ok corrupt data

LzmaDecompressFileCap

func LzmaDecompressFileCap(inpath: str, outpath: str, cap: i64): int
Decompresses an old .lzma file into a new file like XzDecompressFileCap: an ARCHIVE_... status, ARCHIVE_TOO_BIG past cap.

The example for this item is shown with the ones above: archive-FileCap.salam

LzmaDecompressFile

func LzmaDecompressFile(inpath: str, outpath: str): bool
Decompresses an old .lzma file into a new file and returns true on success.

The example for this item is shown with the ones above: archive-Xz.salam

Bzip2CompressFile

func Bzip2CompressFile(inpath: str, outpath: str): bool
Compresses a file into a bzip2 (.bz2) file; false when it cannot read or write.
archive-Bzip2.salam
import archive
import compress

func main:
    text := compress.BufFromStr("bzip2 file helpers: one file in, one file out.\n")
    println archive.WriteBinaryFileBuf("note.txt", text)
    println archive.Bzip2CompressFile("note.txt", "note.txt.bz2")
    println archive.Bzip2DecompressFile("note.txt.bz2", "back.txt")
    mut ok := false
    back := archive.ReadBinaryFile("back.txt", ok)
    println ok, compress.BufEquals(back, text)
    println archive.Bzip2DecompressFile("note.txt", "bad.txt")
    println archive.Bzip2CompressFile("missing.txt", "missing.txt.bz2")
end
Outputtrue true true true true false false

Bzip2CompressFileLevel

func Bzip2CompressFileLevel(inpath: str, outpath: str, level: int): bool
Like Bzip2CompressFile, at the level you give (1 to 9, the block size in 100 KB steps; a number outside that range is moved into it).

The example for this item is shown with the ones above: archive-WriteStream.salam

Bzip2DecompressFileCap

func Bzip2DecompressFileCap(inpath: str, outpath: str, cap: i64): int
Decompresses a bzip2 file into a new file like XzDecompressFileCap: an ARCHIVE_... status, ARCHIVE_TOO_BIG past cap.

The example for this item is shown with the ones above: archive-FileCap.salam

Bzip2DecompressFile

func Bzip2DecompressFile(inpath: str, outpath: str): bool
Decompresses a bzip2 file; false when it cannot read or write or the data is not valid bzip2.

The example for this item is shown with the ones above: archive-Bzip2.salam