tar-no-std 0.5.0

A no_std, allocation-free library focused on reading regular files from basic Tar archives
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

# `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)](https://www.gnu.org/software/tar/manual/html_section/Formats.html)

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](https://www.gnu.org/software/tar/manual/html_section/Formats.html),
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

```rust
use tar_no_std::TarArchiveRef;

fn main() {
    // 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.