format

package
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2026 License: MIT Imports: 5 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 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 (
	PXARFormatVersion      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 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 MarshalStatBytes 

func MarshalStatBytes(s Stat) []byte

MarshalStatBytes serializes a Stat into a 40-byte slice.

func WriteHeader 

func WriteHeader(w io.Writer, h Header) error

WriteHeader writes a Header to the writer.

func WriteStat 

func WriteStat(w io.Writer, s Stat) error

WriteStat writes a Stat to the writer.

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 UnmarshalACLDefaultBytes 

func UnmarshalACLDefaultBytes(data []byte) *ACLDefault

UnmarshalACLDefaultBytes 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 ReadDevice 

func ReadDevice(r io.Reader) (Device, error)

ReadDevice reads a Device from the reader.

func (Device) ToDevT 

func (d Device) ToDevT() uint64

ToDevT converts to a Linux dev_t value.

type FCaps 

type FCaps struct {
	Data []byte
}

FCaps represents file capabilities.

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.

func NewGoodbyeItem 

func NewGoodbyeItem(name []byte, offset, size uint64) GoodbyeItem

NewGoodbyeItem creates a GoodbyeItem by hashing the filename.

func ReadGoodbyeItem 

func ReadGoodbyeItem(r io.Reader) (GoodbyeItem, error)

ReadGoodbyeItem reads a GoodbyeItem from the reader. 

type Hardlink struct {
	Offset uint64
	Data   []byte
}

Hardlink stores a hard link target (offset + path). 

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 ReadHeader 

func ReadHeader(r io.Reader) (Header, error)

ReadHeader reads a Header from the reader.

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) 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 ReadPayloadRef 

func ReadPayloadRef(r io.Reader) (PayloadRef, error)

ReadPayloadRef reads a PayloadRef from the reader.

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 Prelude 

type Prelude struct {
	Data []byte
}

Prelude is an optional blob at the start of a v2 archive.

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 ReadStat 

func ReadStat(r io.Reader) (Stat, error)

ReadStat reads a Stat from the reader.

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.

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.

func StatxTimestampFromDurationSinceEpoch 

func StatxTimestampFromDurationSinceEpoch(d time.Duration) StatxTimestamp

StatxTimestampFromDurationSinceEpoch creates a timestamp from a positive duration.

func StatxTimestampNew 

func StatxTimestampNew(secs int64, nanos uint32) StatxTimestamp

StatxTimestampNew creates a timestamp from seconds and nanoseconds.

func StatxTimestampZero 

func StatxTimestampZero() StatxTimestamp

StatxTimestampZero returns a zero-valued timestamp.

func (StatxTimestamp) Duration 

func (ts StatxTimestamp) Duration() time.Duration

Duration converts the timestamp to a duration since epoch. 

type Symlink struct {
	Data []byte
}

Symlink stores the symlink target path.

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.