Crate tar_no_std 

tar-no-std - Parse Tar Archives (Tarballs)

Due to historical reasons, there are several formats of Tar archives. All of them are based on the same principles, but have some subtle differences that often make them incompatible with each other. (reference)

Library to read Tar archives in no_std environments with zero allocations. If you have a standard environment and need full feature support, I recommend the use of https://crates.io/crates/tar instead.

TL;DR

Most ordinary Tar archives containing regular files will work.

Limitations

Archives created by a typical GNU tar or macOS tar invocation work when their regular-file names and sizes fit in the regular Tar headers. This includes basic Tar and ustar archives, as well as PAX archives that use extended records only for optional metadata such as high-precision timestamps. PAX headers and their metadata are skipped; the following regular-file headers provide the filenames and sizes.

Archives that rely on unsupported extensions do not work correctly. This includes GNU long names, sparse files, incremental archives, and PAX-only paths or file sizes. The maximum supported filename length is 256 characters excluding the NULL-byte, and the maximum supported file size is 8GiB. Directories, links, and other special entries are skipped; iteration yields only regular files, preserving directory paths encoded in their names.

Use Case

This library is useful, if you write a kernel or a similar low-level application, which needs “a bunch of files” from an archive (like an “init ramdisk”). The Tar file could for example come as a Multiboot2 boot module provided by the bootloader.

Example

use tar_no_std::TarArchiveRef;

// also works in no_std environment (except the println!, of course)
let archive = include_bytes!("../tests/gnu_tar_default.tar");
let archive = TarArchiveRef::new(archive).unwrap();
// Vec needs an allocator of course, but the library itself doesn't need one
let entries = archive.entries().collect::<Vec<_>>();
println!("{:#?}", entries);

Cargo Features

This crate allows the usage of the additional Cargo build time feature alloc. When this is active, the crate also provides the type TarArchive, which owns the data on the heap.

Compression (tar.gz)

If your Tar file is compressed, e.g. by .tar.gz/gzip, you need to uncompress the bytes first (e.g. by a gzip library). Afterwards, this crate can read the Tar archive format from the uncompressed bytes.

MSRV

The MSRV is 1.85.0 stable.

Structs

ArchiveEntry

Describes an entry in an archive. Currently only supports files but no directories.

ArchiveEntryIterator

Iterator over the files of the archive.

ArchiveHeaderIterator

Iterates over the headers of a validated Tar archive.

InvalidTypeFlagError

Mode

Wrapper around the UNIX file permissions given in octal ASCII.

ModeFlags

UNIX file permissions in octal format.

PosixHeader

Header of the TAR format as specified by POSIX (POSIX 1003.1-1990).

TarArchive

An owning, validated Tar archive.

TarArchiveRef

Wrapper type around bytes, which represents a Tar archive. To iterate the entries, use TarArchiveRef::entries.

TarFormatDecimal

A decimal number. Trailing spaces in the string are ignored.

TarFormatNumber

A number with a specified base. Trailing spaces in the string are ignored.

TarFormatOctal

An octal number. Trailing spaces in the string are ignored.

TarFormatString

Base type for strings embedded in a Tar header. The length depends on the context. The returned string is likely to be UTF-8/ASCII, which is verified by getters, such as TarFormatString::as_str.

TypeFlagRaw

Enums

CorruptDataError

Describes why archive validation failed.

ModeError

Errors that may happen when parsing the ModeFlags.

TypeFlag

Describes the kind of payload, that follows after a PosixHeader. The properties of this payload are described inside the header.

Constants

MIN_BLOCK_COUNT

Minimum amount of blocks that an archive must have to be considered sane.