qcow2

package module
v0.0.0-...-3170d4d Latest Latest
Warning

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

 Go to latest Published: Jun 7, 2024 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 

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 (e L2TableEntry) Offset(hdr *HeaderAndAdditionalFields) int64

func (L2TableEntry) Unallocated 

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
)

Source Files

View all Source files

Directories

Path Synopsis
cmd
qcow2-benchmark

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.