ext

Documentation

Index

• Constants
• type BlockGroupDescriptorTableEntry
• type Compiler
  • func NewCompiler(args *CompilerArgs) *Compiler
  • func (c *Compiler) AddFile(path string, r io.ReadCloser, size int64, force bool) error
  • func (c *Compiler) Commit(ctx context.Context) error
  • func (c *Compiler) Compile(ctx context.Context, w io.WriteSeeker) error
  • func (c *Compiler) IncreaseMinimumFreeSpace(space int64)
  • func (c *Compiler) IncreaseMinimumInodes(inodes int64)
  • func (c *Compiler) MinimumSize() int64
  • func (c *Compiler) Mkdir(path string) error
  • func (c *Compiler) Precompile(ctx context.Context, size int64) error
  • func (c *Compiler) RegionIsHole(begin, size int64) bool
  • func (c *Compiler) SetMinimumInodes(inodes int64)
  • func (c *Compiler) SetMinimumInodesPer64MiB(inodes int64)
• type CompilerArgs
• type Inode
• type Superblock

Constants

const (
	Signature                = 0xEF53
	SectorSize               = 512
	BlockSize                = 0x1000
	SuperblockOffset         = 1024
	InodeSize                = 128
	InodesPerBlock           = BlockSize / InodeSize
	BlockGroupDescriptorSize = 32

	RootDirInode = 2

	InodeTypeDirectory      = 0x4000
	InodeTypeRegularFile    = 0x8000
	InodeTypeSymlink        = 0xA000
	InodeTypeMask           = 0xF000
	InodePermissionsMask    = 0777
	DefaultInodePermissions = 0700
	SuperUID                = 1000
	SuperGID                = 1000

	IncompatFiletype = 0x2
)

Various ext2 build constants.

Types

type BlockGroupDescriptorTableEntry

type BlockGroupDescriptorTableEntry struct {
	BlockBitmapBlockAddr uint32
	InodeBitmapBlockAddr uint32
	InodeTableBlockAddr  uint32
	UnallocatedBlocks    uint16
	UnallocatedInodes    uint16
	Directories          uint16
	// contains filtered or unexported fields
}

BlockGroupDescriptorTableEntry is the structure of an ext block group descriptor table entry.

type Compiler

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

Compiler keeps all variables and settings for a single file-system compile operation. Compilation occurs in a number of stages that have to happen in an exact sequence: NewCompiler, Commit, Precompile, Compile. The compiler was designed this way to allow it to: be adjustable in terms of its contents and its capacity, pre-calculate its minimum space requirements, pre-calculate where "holes" will exist, and build in one continuous stream.

func NewCompiler

func NewCompiler(args *CompilerArgs) *Compiler

NewCompiler returns an initialized Compiler object. The next necessary step is to call Commit on this Compiler, but before doing so it is possible to modify its contents with functions like Mkdir, AddFile, and IncreaseMinimumInodes (to name a few).

func (*Compiler) AddFile

func (c *Compiler) AddFile(path string, r io.ReadCloser, size int64, force bool) error

AddFile allows the caller to add a file to the file-system at 'path', resolving any collisions by overwriting them if 'force' is true. This function must be called before calling Commit, otherwise the behaviour is undefined.

func (*Compiler) Commit

func (c *Compiler) Commit(ctx context.Context) error

Commit is the second of the four steps necessary to compile a file-system image, and should be called sometime after NewCompiler and before Precompile. It is responsible for locking-in some values and calculating the minimum size of the file-system. Any calls to functions that change the contents or capacity of the file-system must be done before this function is called.

func (*Compiler) Compile

func (c *Compiler) Compile(ctx context.Context, w io.WriteSeeker) error

Compile is the final operation performed by the Compiler, and should only be called after a successful call to the Precompile function. It writes the file-system to the provided io.WriteSeeker, w. Despite using io.Seeker functionality to improve performance, the compiler has been written in a way such that it never needs to seek "backwards", which means you can wrap any io.Writer with a vio.WriteSeeker and it will work.

NOTE: Many seek calls are not relative (they use io.SeekStart for the whence argument), and they expect the "start" to be the place where the file-system begins. For this reason it is recommended to use a vio.WriteSeeker here when building full disk images.

func (*Compiler) IncreaseMinimumFreeSpace

func (c *Compiler) IncreaseMinimumFreeSpace(space int64)

IncreaseMinimumFreeSpace allows the caller to add a minimum amount of extra free space to the file-system image in bytes. The Compiler cannot know how the space will be used in practice, which means it's possible this free space will be consumed by pointer blocks or wasted by small files during runtime.

func (*Compiler) IncreaseMinimumInodes

func (c *Compiler) IncreaseMinimumInodes(inodes int64)

IncreaseMinimumInodes allows the caller to force in some extra empty inodes on top of whatever would have otherwise been there. This function can only be called before calling Commit, otherwise the behaviour is undefined.

func (*Compiler) MinimumSize

func (c *Compiler) MinimumSize() int64

MinimumSize returns the minimum number of bytes needed to contain the file-system image. It can be called after a successful call to Commit, and is intended to provide useful information to the caller that can help it determine what final size should be supplied to the Precompile step as an argument.

func (*Compiler) Mkdir

func (c *Compiler) Mkdir(path string) error

Mkdir allows the caller to add an empty directory to the file-system at 'path' if no file or directory is already mapped there. This function must be called before calling Commit, otherwise the behaviour is undefined.

func (*Compiler) Precompile

func (c *Compiler) Precompile(ctx context.Context, size int64) error

Precompile locks in the file-system size and computes the entire structure of the final file-system image. It does this so that the RegionIsHole function can be used by the caller in situations where identifying empty regions in the image is important, like when embedding the file-system into a sparse VMDK image file. It must be called only after a successful Commit and is necessary before calling the final function: Compile.

func (*Compiler) RegionIsHole

func (c *Compiler) RegionIsHole(begin, size int64) bool

RegionIsHole can be called after a successful Precompile. Its purpose is to provide advance notice to sparse disk image formatting logic on regions within the image that will be completely empty. The two args are measured in bytes, and the function returns true if every byte starting at begin and continuing for the full size is zeroed.

func (*Compiler) SetMinimumInodes

func (c *Compiler) SetMinimumInodes(inodes int64)

SetMinimumInodes allows the caller to specify the minimum number of inodes that should be built onto the file-system. This function can only be called before calling Commit, otherwise the behaviour is undefined.

func (*Compiler) SetMinimumInodesPer64MiB

func (c *Compiler) SetMinimumInodesPer64MiB(inodes int64)

SetMinimumInodesPer64MiB allows the caller to impose some minimum number of inodes relative to the total file-system image size. This function can only be caleld before calling Commit, otherwise the behaviour is undefined.

type CompilerArgs

type CompilerArgs struct {
	FileTree vio.FileTree
	Logger   elog.Logger
}

CompilerArgs organizes all inputs necessary to create a new Compiler. Because the compiler is designed to be configured in stages by the caller very little goes here.

type Inode

type Inode struct {
	Permissions      uint16
	UID              uint16
	SizeLower        uint32
	LastAccessTime   uint32
	CreationTime     uint32
	ModificationTime uint32
	DeletionTime     uint32
	GID              uint16
	Links            uint16
	Sectors          uint32
	Flags            uint32
	OSV              uint32
	DirectPointer    [12]uint32
	SinglyIndirect   uint32
	DoublyIndirect   uint32
	TriplyIndirect   uint32
	GenNo            uint32
	FileACL          uint32
	SizeUpper        uint32
	FragAddr         uint32
	OSStuff          [12]byte
}

Inode is the structure of an inode as written to the disk.

type Superblock

type Superblock struct {
	TotalInodes         uint32
	TotalBlocks         uint32
	ReservedBlocks      uint32
	UnallocatedBlocks   uint32
	UnallocatedInodes   uint32
	SuperblockNumber    uint32
	BlockSize           uint32
	FragmentSize        uint32
	BlocksPerGroup      uint32
	FragmentsPerGroup   uint32
	InodesPerGroup      uint32
	LastMountTime       uint32
	LastWrittenTime     uint32
	MountsSinceCheck    uint16
	MountsCheckInterval uint16
	Signature           uint16
	State               uint16
	ErrorProtocol       uint16
	VersionMinor        uint16
	TimeLastCheck       uint32
	TimeCheckInterval   uint32
	OS                  uint32
	VersionMajor        uint32
	SuperUser           uint16
	SuperGroup          uint16

	RequiredFeatures uint32
	// contains filtered or unexported fields
}

Superblock is the structure of a superblock as written to the disk.