From 60864b1b56807019874ced9496641aa715e681bb Mon Sep 17 00:00:00 2001 From: Dietmar Maurer Date: Mon, 18 Mar 2019 12:27:30 +0100 Subject: [PATCH] src/pxar.rs: improve docu --- src/pxar.rs | 69 +++++++++++++++++++++++++++-------------------------- 1 file changed, 35 insertions(+), 34 deletions(-) diff --git a/src/pxar.rs b/src/pxar.rs index a488351e..803f59b3 100644 --- a/src/pxar.rs +++ b/src/pxar.rs @@ -1,50 +1,51 @@ -//! *pxar* Implementation +//! *pxar* Implementation (proxmox file archive format) //! //! This code implements a slightly modified version of the *catar* //! format used in the [casync](https://github.com/systemd/casync) -//! toolkit (we are not 100% binary compatible). It is a file archive +//! toolkit (we are not 100\% binary compatible). It is a file archive //! format defined by 'Lennart Poettering', specially defined for //! efficent deduplication. //! Every archive contains items in the following order: -//! * ENTRY -- containing general stat() data and related bits -//! * USER -- user name as text, if enabled -//! * GROUP -- group name as text, if enabled -//! * XATTR -- one extended attribute -//! * ... -- more of these when there are multiple defined -//! * ACL_USER -- one USER ACL entry -//! * ... -- more of these when there are multiple defined -//! * ACL_GROUP -- one GROUP ACL entry -//! * ... -- more of these when there are multiple defined -//! * ACL_GROUP_OBJ -- The ACL_GROUP_OBJ -//! * ACL_DEFAULT -- The various default ACL fields if there's one defined -//! * ACL_DEFAULT_USER -- one USER ACL entry -//! * ... -- more of these when multiple are defined -//! * ACL_DEFAULT_GROUP -- one GROUP ACL entry -//! * ... -- more of these when multiple are defined -//! * FCAPS -- file capability in Linux disk format -//! * QUOTA_PROJECT_ID -- the ext4/xfs quota project ID -//! * PAYLOAD -- file contents, if it is one -//! * SYMLINK -- symlink target, if it is one -//! * DEVICE -- device major/minor, if it is a block/char device +//! * `ENTRY` -- containing general stat() data and related bits +//! * `USER` -- user name as text, if enabled +//! * `GROUP` -- group name as text, if enabled +//! * `XATTR` -- one extended attribute +//! * ... -- more of these when there are multiple defined +//! * `ACL_USER` -- one `USER ACL` entry +//! * ... -- more of these when there are multiple defined +//! * `ACL_GROUP` -- one `GROUP ACL` entry +//! * ... -- more of these when there are multiple defined +//! * `ACL_GROUP_OBJ` -- The `ACL_GROUP_OBJ` +//! * `ACL_DEFAULT` -- The various default ACL fields if there's one defined +//! * `ACL_DEFAULT_USER` -- one USER ACL entry +//! * ... -- more of these when multiple are defined +//! * `ACL_DEFAULT_GROUP` -- one GROUP ACL entry +//! * ... -- more of these when multiple are defined +//! * `FCAPS` -- file capability in Linux disk format +//! * `QUOTA_PROJECT_ID` -- the ext4/xfs quota project ID +//! * `PAYLOAD` -- file contents, if it is one +//! * `SYMLINK` -- symlink target, if it is one +//! * `DEVICE` -- device major/minor, if it is a block/char device //! //! If we are serializing a directory, then this is followed by: //! -//! * FILENAME -- name of the first directory entry (strictly ordered!) -//! * -- serialization of the first directory entry's metadata and contents, +//! * `FILENAME` -- name of the first directory entry (strictly ordered!) +//! * `` -- serialization of the first directory entry's metadata and contents, //! following the exact same archive format -//! * FILENAME -- name of the second directory entry (strictly ordered!) -//! * -- serialization of the second directory entry +//! * `FILENAME` -- name of the second directory entry (strictly ordered!) +//! * `` -- serialization of the second directory entry //! * ... -//! * GOODBYE -- lookup table at the end of a list of directory entries +//! * `GOODBYE` -- lookup table at the end of a list of directory entries -///! The original format has no way to deal with hardlinks, so we -///! extended the format by a special HARDLINK tag, which can replace -///! an ENTRY tag. The HARDLINK tag contains an 64bit offset which -///! points to the linked ENTRY inside the archive, followed by the -///! full path name of that ENTRY. HARDLINKs may not have further data -///! (user, group, acl, ...) because this is already defined by the -///! linked ENTRY. +//! +//! The original format has no way to deal with hardlinks, so we +//! extended the format by a special `HARDLINK` tag, which can replace +//! an `ENTRY` tag. The `HARDLINK` tag contains an 64bit offset which +//! points to the linked `ENTRY` inside the archive, followed by the +//! full path name of that `ENTRY`. `HARDLINK`s may not have further data +//! (user, group, acl, ...) because this is already defined by the +//! linked `ENTRY`. mod binary_search_tree; pub use binary_search_tree::*;