qcow2

package module
v0.1.6 Latest Latest
Warning

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

Go to latest
Published: Jul 26, 2023 License: Apache-2.0 Imports: 9 Imported by: 0

README

QCOW2

A Go library for reading and writing QCOW2 disk images. QCOW2 is a format used by QEMU and KVM to store virtual machine disk images.

Written based on the official QCOW2 specification: qcow2.txt.

Caveats

The library is not yet complete. It can read and write most QCOW2 images, but some features are not supported:

  • Compression (expect for reading DEFLATE)
  • Encryption
  • Backing files
  • External data

You shouldn't use this library in any application that requires data integrity. It has not been tested thoroughly and definitely will result in data loss.

Documentation

Index

Constants

View Source
const (
	// Magic bytes for QCOW2 file format.
	Magic = 0x514649FB
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AutoclearFeatures

type AutoclearFeatures uint64

AutoclearFeatures is a bitmask of auto-clear features.

const (
	// AutoclearBitmaps is the bitmaps extension bit. This bit indicates
	// consistency for the bitmaps extension data.
	AutoclearBitmaps AutoclearFeatures = 1 << 0
	// AutoclearRaw is the raw external data bit. If this bit is set,
	// the external data file can be read as a consistent standalone raw image
	// without looking at the qcow2 metadata.
	AutoclearRaw AutoclearFeatures = 1 << 1
)

type CompatibleFeatures

type CompatibleFeatures uint64

CompatibleFeatures is a bitmask of compatible features.

const (
	// CompatibleLazyRefcounts is the lazy refcounts bit. If this bit is set then
	// lazy refcount updates can be used. This means marking the image file dirty
	// and postponing refcount metadata updates.
	CompatibleLazyRefcounts CompatibleFeatures = 1 << 0
)

type CompressionType

type CompressionType uint8

CompressionType is the compression method used for compressed clusters.

const (
	// CompressionTypeDeflate is the deflate compression type.
	CompressionTypeDeflate CompressionType = 0
	// CompressionTypeZstd is the zstd compression type.
	CompressionTypeZstd CompressionType = 1
)

type EncryptionMethod

type EncryptionMethod uint32

EncryptionMethod is the disk encryption method.

const (
	NoEncryption  EncryptionMethod = 0
	AesEncryption EncryptionMethod = 1
)
type Header struct {
	// Magic is the QCOW magic bytes: 'Q', 'F', 'I', 0xfb.
	Magic uint32
	// Version is the QCOW version number.
	Version Version
	// BackingFileOffset is the offset into the image file at which the backing file name is stored (or 0 if no backing file).
	BackingFileOffset uint64
	// BackingFileSize is the length of the backing file name in bytes.
	BackingFileSize uint32
	// ClusterBits is the number of bits that are used for addressing an offset within a cluster.
	ClusterBits uint32
	// Size is the size of the disk image (in bytes).
	Size uint64
	// CryptMethod is the encryption method.
	CryptMethod EncryptionMethod
	// L1Size is the number of entries in the active L1 table.
	L1Size uint32
	// L1TableOffset is the offset into the image file at which the active L1 table starts.
	L1TableOffset uint64
	// RefcountTableOffset is the offset into the image file at which the refcount table starts.
	RefcountTableOffset uint64
	// RefcountTableClusters is the number of clusters that the refcount table occupies.
	RefcountTableClusters uint32
	// NbSnapshots is the number of snapshots contained in the image.
	NbSnapshots uint32
	// SnapshotsOffset is the offset into the image file at which the snapshot table starts.
	SnapshotsOffset uint64
	// IncompatibleFeatures is a bitmask of incompatible features.
	IncompatibleFeatures IncompatibleFeatures
	// CompatibleFeatures is a bitmask of compatible features.
	CompatibleFeatures CompatibleFeatures
	// AutoclearFeatures is a bitmask of auto-clear features.
	AutoclearFeatures AutoclearFeatures
	// RefcountOrder is the descriptor for refcount width: 4 implies 16 bits, 5 implies 32 bits, 6 implies 64 bits.
	RefcountOrder RefcountOrder
	// HeaderLength is the size of the header structure in bytes.
	HeaderLength uint32
}

Header is the QCOW image header.

type HeaderAdditionalFields

type HeaderAdditionalFields struct {
	// CompressionType is the compression method used for compressed clusters.
	// All compressed clusters in an image use the same compression type.
	CompressionType CompressionType
	Padding         [7]byte
}

HeaderAdditionalFields is the additional header fields for version 3.

type HeaderAndAdditionalFields

type HeaderAndAdditionalFields struct {
	Header
	AdditionalFields *HeaderAdditionalFields
	Extensions       []HeaderExtension
}

type HeaderExtension

type HeaderExtension struct {
	HeaderExtensionMetadata
	// Data is the header extension data.
	Data []byte
}

HeaderExtension is a header extension.

type HeaderExtensionMetadata

type HeaderExtensionMetadata struct {
	// Type is the header extension type.
	Type HeaderExtensionType
	// Length is the length of the header extension data.
	Length uint32
}

type HeaderExtensionType

type HeaderExtensionType uint32

HeaderExtensionType is the header extension type.

const (
	// EndOfHeaderExtensionArea is the end of the header extension area.
	EndOfHeaderExtensionArea HeaderExtensionType = 0x00000000
	// BackingFileFormatName is the backing file format name string.
	BackingFileFormatName HeaderExtensionType = 0xe2792aca
	// FeatureNameTable is the feature name table.
	FeatureNameTable HeaderExtensionType = 0x6803f857
	// BitmapsExtension is the bitmaps extension.
	BitmapsExtension HeaderExtensionType = 0x23852875
	// FullDiskEncryptionHeader is the full disk encryption header pointer.
	FullDiskEncryptionHeader HeaderExtensionType = 0x0537be77
	// ExternalDataFileName is the external data file name string.
	ExternalDataFileName HeaderExtensionType = 0x44415441
)

type Image

type Image struct {
	// contains filtered or unexported fields
}

func Create

func Create(path string, size int64) (*Image, error)

func Open

func Open(path string, readOnly bool) (*Image, error)

func (*Image) Close

func (i *Image) Close() error

func (*Image) Read

func (i *Image) Read(p []byte) (n int, err error)

func (*Image) ReadAt

func (i *Image) ReadAt(p []byte, diskOffset int64) (n int, err error)

func (*Image) Size

func (i *Image) Size() (int64, error)

func (*Image) Snapshot added in v0.1.4

func (i *Image) Snapshot() error

Snapshots are not implemented yet but we have some scaffolding in place.

func (*Image) Sync

func (i *Image) Sync() error

func (*Image) Write

func (i *Image) Write(p []byte) (n int, err error)

func (*Image) WriteAt

func (i *Image) WriteAt(p []byte, diskOffset int64) (n int, err error)

type IncompatibleFeatures

type IncompatibleFeatures uint64

IncompatibleFeatures is a bitmask of incompatible features.

const (
	// IncompatibleDirty is the dirty bit. If this bit is set then refcounts may be
	// inconsistent, make sure to scan L1/L2 tables to repair refcounts before
	// accessing the image.
	IncompatibleDirty IncompatibleFeatures = 1 << 0
	// IncompatibleCorrupt is the corrupt bit. If this bit is set then any data
	// structure may be corrupt and the image must not be written to (unless for
	// regaining consistency).
	IncompatibleCorrupt IncompatibleFeatures = 1 << 1
	// IncompatibleExternalData is the external data file bit. If this bit is set, an
	// external data file is used. Guest clusters are then stored in the external
	// data file. For such images, clusters in the external data file are not
	// refcounted.
	IncompatibleExternalData IncompatibleFeatures = 1 << 2
	// IncompatibleExtendedL2 is the extended L2 entries bit. If this bit is set then
	// L2 table entries use an extended format that allows subcluster-based
	// allocation.
	IncompatibleExtendedL2 IncompatibleFeatures = 1 << 3
)

type L1TableEntry

type L1TableEntry uint64

func NewL1TableEntry

func NewL1TableEntry(offset int64) L1TableEntry

func (L1TableEntry) Offset

func (e L1TableEntry) Offset() int64

func (L1TableEntry) Used

func (e L1TableEntry) Used() bool

type L2TableEntry

type L2TableEntry uint64

func NewL2TableEntry

func NewL2TableEntry(hdr *HeaderAndAdditionalFields, offset int64, compressed bool, compressedSize int64) L2TableEntry

func (L2TableEntry) Compressed

func (e L2TableEntry) Compressed() bool

func (L2TableEntry) CompressedSize

func (e L2TableEntry) CompressedSize(hdr *HeaderAndAdditionalFields) int64

func (L2TableEntry) Offset

func (L2TableEntry) Unallocated added in v0.1.4

func (e L2TableEntry) Unallocated() bool

func (L2TableEntry) Used

func (e L2TableEntry) Used() bool

type RefcountOrder

type RefcountOrder uint32

RefcountOrder is the descriptor for refcount width: 4 implies 16 bits, 5 implies 32 bits, 6 implies 64 bits.

const (
	RefcountOrder16 RefcountOrder = 4
	RefcountOrder32 RefcountOrder = 5
	RefcountOrder64 RefcountOrder = 6
)

type Version

type Version uint32

Version is the QCOW version number.

const (
	// Version3 is the QCOW version 3.
	// Only version 3 is supported by this library.
	Version3 Version = 3
)

Directories

Path Synopsis
cmd

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL