Documentation
¶
Overview ¶
Package pxar implements the PXAR archive format: record framing constants, encoders for every entry type (v1 and the v2 split-archive additions), and the goodbye-table construction (siphash naming hash plus the casync implicit binary search tree layout).
The package is used for byte encoding and size calculation only, no filesystem access and no I/O. Every encoder has a matching size function used by the archive planner, so planned and emitted sizes can't diverge.
Index ¶
- Constants
- func AppendACLDefault(dst []byte, a ACLDefault) []byte
- func AppendACLDefaultGroup(dst []byte, a ACLGroup) []byte
- func AppendACLDefaultUser(dst []byte, a ACLUser) []byte
- func AppendACLGroup(dst []byte, a ACLGroup) []byte
- func AppendACLGroupObj(dst []byte, permissions uint64) []byte
- func AppendACLUser(dst []byte, a ACLUser) []byte
- func AppendDevice(dst []byte, d Device) []byte
- func AppendEntry(dst []byte, e Entry) []byte
- func AppendFCaps(dst []byte, data []byte) []byte
- func AppendFilename(dst []byte, name string) []byte
- func AppendFormatVersion(dst []byte, version uint64) []byte
- func AppendGoodbye(dst []byte, items []GoodbyeItem, dirEntryStart, goodbyeStart uint64) []byte
- func AppendHardlink(dst []byte, offset uint64, target string) []byte
- func AppendPayloadHeader(dst []byte, size uint64) []byte
- func AppendPayloadRef(dst []byte, offset, size uint64) []byte
- func AppendPayloadStartMarker(dst []byte) []byte
- func AppendPayloadTailMarker(dst []byte) []byte
- func AppendQuotaProjID(dst []byte, projid uint64) []byte
- func AppendSymlink(dst []byte, target string) []byte
- func AppendXAttr(dst []byte, name string, value []byte) []byte
- func Hash(name string) uint64
- func SizeFCaps(data []byte) uint64
- func SizeFilename(name string) uint64
- func SizeGoodbye(n int) uint64
- func SizeHardlink(target string) uint64
- func SizePayload(size uint64) uint64
- func SizeSymlink(target string) uint64
- func SizeXAttr(name string, value []byte) uint64
- func ValidateFilename(name string) error
- type ACLDefault
- type ACLGroup
- type ACLUser
- type Device
- type Entry
- type GoodbyeItem
Constants ¶
const ( ACLRead uint64 = 4 ACLWrite uint64 = 2 ACLExecute uint64 = 1 // ACLNoMask marks an absent mask in ACLDefault. ACLNoMask uint64 = ^uint64(0) )
ACL permission bits (per entry, rwx as in POSIX ACLs).
const ( ACLUserSize = HeaderSize + 16 ACLGroupSize = HeaderSize + 16 ACLGroupObjSize = HeaderSize + 8 ACLDefaultSize = HeaderSize + 32 )
Encoded sizes of the fixed-layout ACL records.
const ( // TypeEntry is the stat record: mode, flags, uid, gid, mtime. TypeEntry uint64 = 0xd5956474e588acef // TypeEntryV1 is the obsolete stat record layout of early pxar versions. // Decode-only concern; never emitted. TypeEntryV1 uint64 = 0x11da850a1c1cceff // TypeFilename precedes each directory child: name bytes + NUL. TypeFilename uint64 = 0x16701121063917b3 // TypeSymlink carries the link target: target bytes + NUL. TypeSymlink uint64 = 0x27f971e7dbf5dc5f // TypeDevice carries major/minor numbers for block and char devices. TypeDevice uint64 = 0x9fc9e906586d5ce9 // TypeXAttr carries one extended attribute: name + NUL + value. TypeXAttr uint64 = 0x0dab0229b57dcd03 // ACL record types; bodies are defined in encode.go. TypeACLUser uint64 = 0x2ce8540a457d55b8 TypeACLGroup uint64 = 0x136e3eceb04c03ab TypeACLGroupObj uint64 = 0x10868031e9582876 TypeACLDefault uint64 = 0xbbbb13415a6896f5 TypeACLDefaultUser uint64 = 0xc89357b40532cd1f TypeACLDefaultGroup uint64 = 0xf90a8a5816038ffe // TypeFCaps carries the raw security.capability xattr value. TypeFCaps uint64 = 0x2da9dd9db5f7fb67 // TypeQuotaProjID carries the filesystem quota project id. TypeQuotaProjID uint64 = 0xe07540e82f7d1cbb // TypeHardlink references an earlier entry: offset (u64) + path + NUL. TypeHardlink uint64 = 0x51269c8422bd7275 // TypePayload frames regular file content. TypePayload uint64 = 0x28147a1b0b7c1a25 // TypeGoodbye terminates a directory: a BST of per-child items. TypeGoodbye uint64 = 0x2fec4fa642d5731d // GoodbyeTailMarker is the hash value of the final goodbye item. GoodbyeTailMarker uint64 = 0xef5eed5b753e1555 // v2 (split archive) additions. TypeFormatVersion uint64 = 0x730f6c75df16a40d TypePrelude uint64 = 0xe309d79d9f7b771b TypePayloadRef uint64 = 0x419d3d6bc4ba977e PayloadStartMarker uint64 = 0x834c68c2194a4ed2 PayloadTailMarker uint64 = 0x6c72b78b984c81b5 )
Record type identifiers. Every item in a pxar stream is framed as a 16-byte header — type (u64 LE) followed by length (u64 LE, including the header) — and a body. Values match proxmox/pxar src/format/mod.rs.
const DeviceSize = HeaderSize + 16
DeviceSize is the full encoded size of a Device record.
const EntrySize = HeaderSize + 40
EntrySize is the full encoded size of an Entry record.
const FormatVersionSize = HeaderSize + 8
FormatVersionSize is the full encoded size of a TypeFormatVersion record.
const HeaderSize = 16
HeaderSize is the size of the type+length framing of every record.
const MarkerSize = HeaderSize
MarkerSize is the encoded size of the bare-header payload stream markers.
const PayloadRefSize = HeaderSize + 16
PayloadRefSize is the full encoded size of a TypePayloadRef record.
const QuotaProjIDSize = HeaderSize + 8
QuotaProjIDSize is the full encoded size of a TypeQuotaProjID record.
Variables ¶
This section is empty.
Functions ¶
func AppendACLDefault ¶
func AppendACLDefault(dst []byte, a ACLDefault) []byte
AppendACLDefault encodes the default-ACL object permissions (TypeACLDefault).
func AppendACLDefaultGroup ¶
AppendACLDefaultGroup encodes a default named-group ACL entry (TypeACLDefaultGroup).
func AppendACLDefaultUser ¶
AppendACLDefaultUser encodes a default named-user ACL entry (TypeACLDefaultUser).
func AppendACLGroup ¶
AppendACLGroup encodes a named-group ACL entry (TypeACLGroup).
func AppendACLGroupObj ¶
AppendACLGroupObj encodes the owning-group permissions (TypeACLGroupObj), present when a mask entry makes the stat group bits carry the mask instead.
func AppendACLUser ¶
AppendACLUser encodes a named-user ACL entry (TypeACLUser).
func AppendDevice ¶
AppendDevice encodes d as a TypeDevice record.
func AppendEntry ¶
AppendEntry encodes e as a TypeEntry record.
func AppendFCaps ¶
AppendFCaps encodes the raw security.capability xattr value.
func AppendFilename ¶
AppendFilename encodes a directory child's name (NUL-terminated).
func AppendFormatVersion ¶
AppendFormatVersion encodes the format version record that opens a v2 metadata stream (version 1 is expressed by the record's absence).
func AppendGoodbye ¶
func AppendGoodbye(dst []byte, items []GoodbyeItem, dirEntryStart, goodbyeStart uint64) []byte
AppendGoodbye encodes a directory's goodbye table. dirEntryStart is the absolute offset of the directory's own TypeEntry record (i.e. after its filename record; for the root directory, the archive start), goodbyeStart the absolute offset where this goodbye record begins. Items may be in any order; they are sorted by hash and permuted into the BST layout. Item offsets are encoded as distances backwards from goodbyeStart.
func AppendHardlink ¶
AppendHardlink encodes a hardlink record: offset is the distance in bytes from the start of this hardlink's own TypeFilename record back to the start of the link target's TypeFilename record (the upstream encoder's current_position - target_position); target is the archive-relative path of the target (NUL-terminated).
func AppendPayloadHeader ¶
AppendPayloadHeader encodes the header of a TypePayload record. The size bytes of raw file content follow the header in the stream; they are written by the emitter, not by this package.
func AppendPayloadRef ¶
AppendPayloadRef encodes a v2 payload reference: offset addresses the payload record's *header* in the payload stream, size is the content byte count (the referenced record's length minus its header).
func AppendPayloadStartMarker ¶
AppendPayloadStartMarker encodes the record that opens a payload stream.
func AppendPayloadTailMarker ¶
AppendPayloadTailMarker encodes the record that closes a payload stream.
func AppendQuotaProjID ¶
AppendQuotaProjID encodes a filesystem quota project id.
func AppendSymlink ¶
AppendSymlink encodes a symlink target (NUL-terminated).
func AppendXAttr ¶
AppendXAttr encodes one extended attribute: name + NUL + value.
func SizeFilename ¶
SizeFilename returns the encoded size of a TypeFilename record.
func SizeGoodbye ¶
SizeGoodbye returns the full encoded size of a goodbye record for a directory with n children (n items plus the tail marker).
func SizeHardlink ¶
SizeHardlink returns the encoded size of a TypeHardlink record.
func SizePayload ¶
SizePayload returns the full encoded size of a payload record whose content is size bytes: the header plus the raw content that follows it.
func SizeSymlink ¶
SizeSymlink returns the encoded size of a TypeSymlink record.
func ValidateFilename ¶
ValidateFilename reports whether name is usable as a pxar directory child name: non-empty, no '/', no NUL, and not "." or "..".
Types ¶
type ACLDefault ¶
type ACLDefault struct {
UserObjPermissions uint64
GroupObjPermissions uint64
OtherPermissions uint64
MaskPermissions uint64 // ACLNoMask when no mask entry exists
}
ACLDefault is the body of a TypeACLDefault record.
type Entry ¶
type Entry struct {
Mode uint64 // full st_mode: type bits + permission bits
Flags uint64
UID uint32
GID uint32
MtimeSecs int64 // seconds since epoch (may be negative)
MtimeNanos uint32 // nanoseconds within MtimeSecs
}
Entry is the stat record body (TypeEntry).
type GoodbyeItem ¶
GoodbyeItem describes one directory child for goodbye-table construction. Start and Length are in stream coordinates: Start is the absolute offset of the child's TypeFilename record, Length the child's total encoded length (filename record through goodbye table or payload, inclusive).
Source Files