format

package
v0.29.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 17, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package format defines the pxar binary format types and constants.

All values are stored in little endian ordering. The archive contains a list of items. Each item starts with a 16-byte Header, followed by item data.

Headers

Every item is prefixed by a Header (Type uint64 + Size uint64). The Type field identifies the item's role (ENTRY, FILENAME, PAYLOAD, etc.) and Size is the total item size including the header. Header.MarshalTo provides zero-copy serialization into a caller-provided buffer.

Stat

Stat (40 bytes) carries POSIX stat information: mode, flags, uid, gid, and a high-precision mtime (StatxTimestamp with Secs/Nanos and 4-byte padding). The _pad field at bytes 36-39 is always 0, matching Rust's Endian trait.

StatV1 (32 bytes) uses nanosecond-precision mtime and converts via ToStat().

Devices

Device encodes major/minor numbers. ToDevT and DeviceFromDevT convert to/from Linux dev_t format (matching Rust's makedev/dev_major/dev_minor).

Goodbye Tables

Directory entries end with a goodbye table — a binary search tree of GoodbyeItem entries sorted by filename hash (SipHash24). The BST layout enables O(log n) filename lookups without a separate index.

Payload References

In v2 split archives, PayloadRef maps file content to byte offsets in a separate payload stream, decoupling metadata from content for efficient catalog access and chunk deduplication.

SipHash24

HashFilename computes a SipHash-2-4 hash using the pxar fixed key, matching the Rust implementation for goodbye table lookups.

Package format defines the pxar binary format types and constants.

All values are stored in little endian ordering. The archive contains a list of items. Each item starts with a Header, followed by item data.

Index

Constants

View Source 
const (
	ACLRead    uint64 = 4
	ACLWrite   uint64 = 2
	ACLExecute uint64 = 1
	ACLNoMask  uint64 = ^uint64(0)
)

ACL permission bit constants.

View Source 
const (
	HashKey1 uint64 = 0x83ac3f1cfbb450db
	HashKey2 uint64 = 0xaa4f1b6879369fbd
)

Hash keys for SipHash24 filename hashing. Generated from: echo -n 'PROXMOX ARCHIVE FORMAT' | sha1sum

View Source 
const (
	Version                uint64 = 0x730f6c75df16a40d
	PXAREntry              uint64 = 0xd5956474e588acef
	PXAREntryV1            uint64 = 0x11da850a1c1cceff
	PXARPrelude            uint64 = 0xe309d79d9f7b771b
	PXARFilename           uint64 = 0x16701121063917b3
	PXARSymlink            uint64 = 0x27f971e7dbf5dc5f
	PXARDevice             uint64 = 0x9fc9e906586d5ce9
	PXARXAttr              uint64 = 0x0dab0229b57dcd03
	PXARACLUser            uint64 = 0x2ce8540a457d55b8
	PXARACLGroup           uint64 = 0x136e3eceb04c03ab
	PXARACLGroupObj        uint64 = 0x10868031e9582876
	PXARACLDefault         uint64 = 0xbbbb13415a6896f5
	PXARACLDefaultUser     uint64 = 0xc89357b40532cd1f
	PXARACLDefaultGroup    uint64 = 0xf90a8a5816038ffe
	PXARFCaps              uint64 = 0x2da9dd9db5f7fb67
	PXARQuotaProjID        uint64 = 0xe07540e82f7d1cbb
	PXARHardlink           uint64 = 0x51269c8422bd7275
	PXARPayload            uint64 = 0x28147a1b0b7c1a25
	PXARPayloadRef         uint64 = 0x419d3d6bc4ba977e
	PXARGoodbye            uint64 = 0x2fec4fa642d5731d
	PXARGoodbyeTailMarker  uint64 = 0xef5eed5b753e1555
	PXARPayloadStartMarker uint64 = 0x834c68c2194a4ed2
	PXARPayloadTailMarker  uint64 = 0x6c72b78b984c81b5
)

Pxar format type constants.

View Source 
const (
	ModeIFMT   uint64 = 0o0170000
	ModeIFSOCK uint64 = 0o0140000
	ModeIFLNK  uint64 = 0o0120000
	ModeIFREG  uint64 = 0o0100000
	ModeIFBLK  uint64 = 0o0060000
	ModeIFDIR  uint64 = 0o0040000
	ModeIFCHR  uint64 = 0o0020000
	ModeIFIFO  uint64 = 0o0010000

	ModeISUID uint64 = 0o0004000
	ModeISGID uint64 = 0o0002000
	ModeISVTX uint64 = 0o0001000
)

File mode type constants matching Linux stat.h values.

View Source 
const (
	MaxFilenameLen uint64 = 4 * 1024
	MaxPathLen     uint64 = 4 * 1024
	MaxXAttrLen    uint64 = 255 + 64*1024
)

Size limits.

View Source 
const HeaderSize = 16

HeaderSize is the byte size of Header.

Variables

This section is empty.

Functions

func AppendStatBytesInto added in v0.18.0 

func AppendStatBytesInto(dst []byte, s Stat) []byte

AppendStatBytesInto writes the serialized Stat into dst and returns the extended slice. dst must have capacity for 40 additional bytes.

func CheckFilename 

func CheckFilename(name []byte) error

CheckFilename validates that a filename is a legal path component.

func HashFilename 

func HashFilename(name []byte) uint64

HashFilename computes the SipHash24 of a filename for use in goodbye tables.

func MarshalACLDefaultBytes 

func MarshalACLDefaultBytes(d ACLDefault) []byte

MarshalACLDefaultBytes serializes an ACLDefault into a 32-byte slice.

func MarshalACLGroupBytes 

func MarshalACLGroupBytes(g ACLGroup) []byte

MarshalACLGroupBytes serializes an ACLGroup into a 16-byte slice.

func MarshalACLGroupObjectBytes 

func MarshalACLGroupObjectBytes(o ACLGroupObject) []byte

MarshalACLGroupObjectBytes serializes an ACLGroupObject into an 8-byte slice.

func MarshalACLUserBytes 

func MarshalACLUserBytes(u ACLUser) []byte

MarshalACLUserBytes serializes an ACLUser into a 16-byte slice.

func MarshalDeviceBytes 

func MarshalDeviceBytes(d Device) []byte

MarshalDeviceBytes serializes a Device into a 16-byte slice.

func MarshalStatBytesInto added in v0.17.5 

func MarshalStatBytesInto(buf []byte, s Stat)

MarshalStatBytesInto writes the serialized Stat into buf (must be >= 40 bytes).

Types

type ACLDefault 

type ACLDefault struct {
	UserObjPermissions  ACLPermissions
	GroupObjPermissions ACLPermissions
	OtherPermissions    ACLPermissions
	MaskPermissions     ACLPermissions
}

ACLDefault represents the default ACL entry for a directory. 32 bytes.

func UnmarshalACLDefault added in v0.18.0 

func UnmarshalACLDefault(data []byte) ACLDefault

UnmarshalACLDefault parses an ACLDefault from a 32-byte slice.

type ACLGroup 

type ACLGroup struct {
	GID         uint64
	Permissions ACLPermissions
}

ACLGroup represents a group ACL entry. 24 bytes.

type ACLGroupObject 

type ACLGroupObject struct {
	Permissions ACLPermissions
}

ACLGroupObject represents the group object ACL entry. 8 bytes.

type ACLPermissions 

type ACLPermissions uint64

ACLPermissions represents ACL permission bits. 8 bytes.

type ACLUser 

type ACLUser struct {
	UID         uint64
	Permissions ACLPermissions
}

ACLUser represents a user ACL entry. 24 bytes.

type Device 

type Device struct {
	Major uint64
	Minor uint64
}

Device represents a device node with major/minor numbers. 16 bytes.

func DeviceFromDevT 

func DeviceFromDevT(dev uint64) Device

DeviceFromDevT creates a Device from a Linux dev_t value.

func (Device) ToDevT 

func (d Device) ToDevT() uint64

ToDevT converts to a Linux dev_t value.

type FormatVersion 

type FormatVersion int

FormatVersion represents the pxar format version. 

const (
	FormatVersion1 FormatVersion = 1
	FormatVersion2 FormatVersion = 2
)

func DeserializeFormatVersion 

func DeserializeFormatVersion(version uint64) (FormatVersion, error)

DeserializeFormatVersion parses a format version number.

func (FormatVersion) Serialize 

func (v FormatVersion) Serialize() []byte

Serialize returns the bytes to write for this format version. V1 returns nil (not encoded), V2 returns the version number as LE uint64.

func (FormatVersion) String 

func (v FormatVersion) String() string

String returns a human-readable format version name.

type GoodbyeItem 

type GoodbyeItem struct {
	Hash   uint64
	Offset uint64
	Size   uint64
}

GoodbyeItem is an entry in the goodbye lookup table. 24 bytes. 

type Header struct {
	Type uint64
	Size uint64
}

Header is the binary header preceding every pxar item. 16 bytes total.

func HeaderWithContentSize 

func HeaderWithContentSize(htype, contentSize uint64) Header

HeaderWithContentSize creates a Header where Size = contentSize + HeaderSize.

func NewHeader 

func NewHeader(htype, fullSize uint64) Header

NewHeader creates a Header with the given full size.

func (Header) CheckHeaderSize 

func (h Header) CheckHeaderSize() error

CheckHeaderSize validates the header's size fields.

func (Header) ContentSize 

func (h Header) ContentSize() uint64

ContentSize returns the size of the content after the header.

func (Header) MarshalTo added in v0.18.0 

func (h Header) MarshalTo(dst []byte)

MarshalTo writes the header as 16 little-endian bytes into dst.

func (Header) MaxContentSize 

func (h Header) MaxContentSize() uint64

MaxContentSize returns the maximum allowed content size for this header type.

func (Header) String 

func (h Header) String() string

String returns a human-readable description of the header.

type PayloadRef 

type PayloadRef struct {
	Offset uint64
	Size   uint64
}

PayloadRef references file content in a separate payload archive. 16 bytes.

func UnmarshalPayloadRefBytes 

func UnmarshalPayloadRefBytes(data []byte) PayloadRef

UnmarshalPayloadRefBytes parses a PayloadRef from a 16-byte slice.

func (PayloadRef) Bytes 

func (pr PayloadRef) Bytes() []byte

Bytes returns the little-endian bytes of the PayloadRef.

type QuotaProjectID 

type QuotaProjectID struct {
	ProjID uint64
}

QuotaProjectID represents an ext4/XFS quota project ID. 8 bytes.

type Stat 

type Stat struct {
	Mode  uint64
	Flags uint64
	UID   uint32
	GID   uint32
	Mtime StatxTimestamp
}

Stat contains file metadata similar to Unix stat. 40 bytes.

func UnmarshalStatBytes 

func UnmarshalStatBytes(data []byte) Stat

UnmarshalStatBytes parses a Stat from a 40-byte slice.

func (Stat) FileMode 

func (s Stat) FileMode() uint64

FileMode returns the permission portion of the mode (Mode & ^ModeIFMT).

func (Stat) FileType 

func (s Stat) FileType() uint64

FileType returns the file type portion of the mode (Mode & ModeIFMT).

func (Stat) IsBlockDev 

func (s Stat) IsBlockDev() bool

IsBlockDev reports whether the stat represents a block device.

func (Stat) IsCharDev 

func (s Stat) IsCharDev() bool

IsCharDev reports whether the stat represents a character device.

func (Stat) IsDevice 

func (s Stat) IsDevice() bool

IsDevice reports whether the stat represents a device (char or block).

func (Stat) IsDir 

func (s Stat) IsDir() bool

IsDir reports whether the stat represents a directory.

func (Stat) IsFIFO 

func (s Stat) IsFIFO() bool

IsFIFO reports whether the stat represents a FIFO.

func (Stat) IsRegularFile 

func (s Stat) IsRegularFile() bool

IsRegularFile reports whether the stat represents a regular file.

func (Stat) IsSocket 

func (s Stat) IsSocket() bool

IsSocket reports whether the stat represents a socket. 

func (s Stat) IsSymlink() bool

IsSymlink reports whether the stat represents a symbolic link.

func (Stat) StatEqual added in v0.13.0 

func (s Stat) StatEqual(other Stat) bool

StatEqual reports whether two Stat entries are equivalent for metadata change detection. Two entries are considered equal if their file type, permissions, uid, gid, and mtime match. File size comparison is done separately since Stat doesn't carry size.

type StatV1 

type StatV1 struct {
	Mode  uint64
	Flags uint64
	UID   uint32
	GID   uint32
	Mtime uint64
}

StatV1 is the legacy format stat structure. 32 bytes.

func UnmarshalStatV1Bytes 

func UnmarshalStatV1Bytes(data []byte) StatV1

UnmarshalStatV1Bytes parses a StatV1 from a 32-byte slice.

func (StatV1) ToStat 

func (v1 StatV1) ToStat() Stat

ToStat converts a V1 stat to the current Stat format.

type StatxTimestamp 

type StatxTimestamp struct {
	Secs  int64
	Nanos uint32
	// contains filtered or unexported fields
}

StatxTimestamp represents a high-precision timestamp. 16 bytes. The _pad field ensures binary layout matches the wire format.

func NewStatxTimestamp added in v0.18.0 

func NewStatxTimestamp(secs int64, nanos uint32) StatxTimestamp

NewStatxTimestamp creates a timestamp from seconds and nanoseconds.

func NewStatxTimestampFromDuration added in v0.18.0 

func NewStatxTimestampFromDuration(d time.Duration) StatxTimestamp

NewStatxTimestampFromDuration creates a timestamp from a signed duration relative to the unix epoch. A positive duration denotes a point in time after the epoch; a negative duration denotes a point in time before it.

For pre-epoch values this applies the statx carry convention used by the pxar wire format and Linux's struct statx_timestamp: a non-zero sub-second remainder is represented as (secs-1, 1e9-nanos) so that the value stays monotonically ordered. This mirrors Rust's StatxTimestamp::from_duration_since_epoch / from_duration_before_epoch.

func NewStatxTimestampFromTime added in v0.29.0 

func NewStatxTimestampFromTime(t time.Time) StatxTimestamp

NewStatxTimestampFromTime creates a timestamp from a point in time, equivalent to Rust's From<SystemTime> for StatxTimestamp. It works for any time representable as Unix seconds (no time.Duration overflow), including times well before the epoch.

func (StatxTimestamp) Duration 

func (ts StatxTimestamp) Duration() time.Duration

Duration converts the timestamp to a signed duration since the epoch. The result, added to the epoch, yields the original point in time for both post- and pre-epoch timestamps. It is the exact inverse of NewStatxTimestampFromDuration across the full signed range.

func (StatxTimestamp) Time added in v0.29.0 

func (ts StatxTimestamp) Time() time.Time

Time converts the timestamp to a time.Time relative to the unix epoch, equivalent to Rust's StatxTimestamp::system_time. It is the exact inverse of NewStatxTimestampFromTime for both post- and pre-epoch timestamps.

type XAttr 

type XAttr struct {
	Data    []byte
	NameLen int
}

XAttr represents an extended attribute (name + value).

func NewXAttr 

func NewXAttr(name, value []byte) XAttr

NewXAttr creates an XAttr from a name and value.

func (XAttr) Name 

func (x XAttr) Name() []byte

Name returns the attribute name as a string (without null terminator).

func (XAttr) Value 

func (x XAttr) Value() []byte

Value returns the attribute value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.