format::tar +linux +x86_64

This module provides an implementation of the tar archive format for Unix. The specific format implemented is USTAR, however, it is capable of reading most tar variants which are backwards-compatible with the original format (e.g. GNU tar).

To read an archive, use read to create a reader, and next to enumerate its entries. The return value from next contains the file metadata and is an io::stream that you may read the file contents from. You may call skip to skip an archive entry without reading it.



type entry;
type entry_type;

// Undocumented types:
type ent_reader;
type reader;


type error;
type invalid;
type truncated;


const BLOCKSIZE: size;


fn next(*reader) (entry | error | io::EOF);
fn read(io::handle) reader;
fn skip(*entry) (void | io::error);
fn strerror(error) const str;


type entry[link]

type entry = struct {
	name: str,
	mode: uint,
	uid: uint,
	gid: uint,
	fsize: size,
	mtime: uint,
	checksum: uint,
	etype: entry_type,
	link: str,
	uname: str,
	gname: str,
	devmajor: u64,
	devminor: u64,

A file or directory in a tar file.

type entry_type[link]

type entry_type = enum u8 {


A tar file entry. Note that some systems create tarballs with additional vendor-specific values for the entry type, so a default case is recommended when switching against this.

type ent_reader[link]

Show undocumented member
type ent_reader = struct {
	vtable: io::stream,
	src: io::handle,
	orig: size,
	remain: size,

type reader[link]

Show undocumented member
type reader = struct {
	src: io::handle,
	name: [255]u8,


type error[link]

type error = !(truncated | invalid | io::error);

Tagged union of all possible error types.

type invalid[link]

type invalid = !void;

Returned if the source file does not contain a valid ustar archive.

type truncated[link]

type truncated = !void;

Returned if the source file size is not aligned on BLOCKSIZE.


def BLOCKSIZE[link]

def BLOCKSIZE: size;

The size of each block in a tar file.


fn next[link]

fn next(rd: *reader) (entry | error | io::EOF);

Returns the next entry from a tar reader. Parts of this structure (specifically the file name) are borrowed from the reader itself and will not be valid after subsequent calls.

If the return value is a file (i.e. entry.etype == entry_type::FILE), the caller must either call io::read using the return value until it returns io::EOF, or call skip to seek to the next entry in the archive.

Note that reading from the header will modify the file size.

fn read[link]

fn read(src: io::handle) reader;

Creates a new reader for a tar file. Use next to iterate through entries present in the tar file.

fn skip[link]

fn skip(ent: *entry) (void | io::error);

Seeks the underlying tar file to the entry following this one.

fn strerror[link]

fn strerror(err: error) const str;

Converts an error to a human-friendly representation.