Crate tar_no_std

source ·
Expand description

Library to read Tar archives (by GNU Tar) in no_std contexts 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.

The crate is simple and only supports reading of “basic” archives, therefore no extensions, such as GNU Longname. The maximum supported file name length is 100 characters including the NULL-byte. The maximum supported file size is 8 GiB. Also, directories are not supported yet but only flat collections of files.

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

This crate focuses on extracting files from uncompressed Tar archives created with default options by GNU Tar. GNU Extensions such as sparse files, incremental archives, and long filename extension are not supported yet. gnu.org provides a good overview over possible archive formats and their limitations.

Example

use tar_no_std::TarArchiveRef;

// log: not mandatory
std::env::set_var("RUST_LOG", "trace");
env_logger::init();

// 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);
// Vec needs an allocator of course, but the library itself doesn't need one
let entries = archive.entries().collect::<Vec<_>>();
println!("{:#?}", entries);
println!("content of last file:");
let last_file_content = unsafe { core::str::from_utf8_unchecked(entries[2].data()) };
println!("{:#?}", last_file_content);

Structs

  • ArchiveEntry
    Describes an entry in an archive. Currently only supports files but no directories.
  • ArchiveIterator
    Iterator over the files of the archive. Each iteration starts at the next Tar header entry.
  • 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. “New” (version?) GNU Tar versions use this archive format by default. (https://www.gnu.org/software/tar/manual/html_node/Formats.html#Formats).
  • Size
    The file size is encoded as octal ASCII number inside a Tar header.
  • StaticCString
    A C-String that is stored in a static array. There is always a terminating NULL-byte.
  • TarArchiveRef
    Wrapper type around bytes, which represents a Tar archive. Unlike [TarArchive], this uses only a reference to the data.

Enums

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