tar/
lib.rs

1//! A library for reading and writing TAR archives
2//!
3//! This library provides utilities necessary to manage [TAR archives][1]
4//! abstracted over a reader or writer. Great strides are taken to ensure that
5//! an archive is never required to be fully resident in memory, and all objects
6//! provide largely a streaming interface to read bytes from.
7//!
8//! [1]: https://en.wikipedia.org/wiki/Tar_%28computing%29
9//!
10//! # Security
11//!
12//! When unpacking archives ([`Archive::unpack`], [`Entry::unpack_in`]), a
13//! best-effort is made to prevent writing files outside the destination
14//! directory: paths containing `..` are rejected, and symlink targets within
15//! the archive are validated before use.
16//!
17//! **Concurrent mutation of the destination tree is outside the threat model.**
18//! If another process modifies the destination (for example, by atomically
19//! swapping a symlink) while extraction is in progress, this crate may follow
20//! a path outside the intended destination. Preventing such TOCTOU races
21//! requires OS primitives (e.g. `openat`/`O_PATH` used throughout) that this
22//! crate does not use. When extracting untrusted archives in an environment
23//! where the destination may be concurrently modified, use the [`cap-std`]
24//! crate and/or OS-level sandboxing.
25//!
26//! [`cap-std`]: https://docs.rs/cap-std/
27
28// More docs about the detailed tar format can also be found here:
29// https://man.freebsd.org/cgi/man.cgi?query=tar&sektion=5&manpath=FreeBSD+8-current
30
31// NB: some of the coding patterns and idioms here may seem a little strange.
32//     This is currently attempting to expose a super generic interface while
33//     also not forcing clients to codegen the entire crate each time they use
34//     it. To that end lots of work is done to ensure that concrete
35//     implementations are all found in this crate and the generic functions are
36//     all just super thin wrappers (e.g. easy to codegen).
37
38#![doc(html_root_url = "https://docs.rs/tar/0.4")]
39#![deny(missing_docs)]
40#![cfg_attr(test, deny(warnings))]
41
42use std::io::{Error, ErrorKind};
43
44pub use crate::archive::{Archive, Entries};
45pub use crate::builder::{Builder, EntryWriter};
46pub use crate::entry::{Entry, Unpacked};
47pub use crate::entry_type::EntryType;
48pub use crate::header::GnuExtSparseHeader;
49#[cfg(all(any(unix, windows), not(target_arch = "wasm32")))]
50pub use crate::header::DETERMINISTIC_TIMESTAMP;
51pub use crate::header::{GnuHeader, GnuSparseHeader, Header, HeaderMode, OldHeader, UstarHeader};
52pub use crate::pax::{PaxExtension, PaxExtensions};
53
54mod archive;
55mod builder;
56mod entry;
57mod entry_type;
58mod error;
59mod header;
60mod pax;
61
62fn other(msg: &str) -> Error {
63    Error::new(ErrorKind::Other, msg)
64}
tar/lib.rs

tar/
lib.rs
