grub

README

About the Go GRUB module

This module contains pure Go implementation of the GRUB environment block data format.

Technically GRUB recommends that all interactions with grubenv are to be performed by executing the grub-editenv program. This does, however, put an unnecessary burden on launching the new process, parsing the output and handling errors. This format is not officially documented but is now well recognized and stable since at least 2013.

Unlike the naive approach, extreme care is taken to match the original C implementation.

Overview of package

The grub package provides the high-level Env type and the low-level Cursor type. The former provides functions for looking up, assigning and deleting keys and is the recommended way to work with environment. The latter offers low-level cursor access to navigate a grubenv-like byte slice and perform specific operations. Use the cursor type to work with corrupted environment blocks of where you may find duplicate keys.

Contributions

Contributions are welcome. Please try to respect Go requirements (1.22 at the moment) and the overall coding and testing style.

License and REUSE

This project is licensed under the Apache 2.0 license, see the LICENSE file for details. The project is compliant with https://reuse.software/ - making it easy to ensure license and copyright compliance by automating software bill-of-materials. In other words, it's a good citizen in the modern free software stacks.

Documentation

Overview

Package grub provides manipulation functions for GRUB environment block. Use OpenEnv to load an environment block. Use Env.Get, Env.Set, Env.Delete to manipulate entries. For low-level access use NewCursor to navigate the raw contents of the environment block file.

Index

• Constants
• Variables
• type Cursor
  • func NewCursor(buf []byte) *Cursor
  • func (cur *Cursor) Delete()
  • func (cur *Cursor) Entry() string
  • func (cur *Cursor) InsertBefore(key, value string) error
  • func (cur *Cursor) Key() string
  • func (cur *Cursor) Next() bool
  • func (cur *Cursor) SetValue(value string) error
  • func (cur *Cursor) Value() string
• type Env
  • func LoadEnv(path string) (*Env, error)
  • func NewEnv() *Env
  • func (env *Env) Delete(key string)
  • func (env *Env) Get(key string) string
  • func (env *Env) Lookup(key string) (string, bool)
  • func (env *Env) Save(path string) error
  • func (env *Env) Set(key, value string) error
  • func (env *Env) String() string

Constants

const (
	// EnvHeader is a fixed string at the beginning of the environment block.
	EnvHeader = "# GRUB Environment Block\n"
)

Variables

var (
	// ErrInsufficientSpace records inability to perform modifications due to insufficient space.
	ErrInsufficientSpace = errors.New("insufficient remaining space")

	// ErrCorruptedEntry records corrupted entry devoid of the '=' byte.
	ErrCorruptedEntry = errors.New("corrupted entry")

	// ErrInvalidCursor records attempt to use the cursor at an invalid position.
	ErrInvalidCursor = errors.New("cursor is not pointing to a valid entry")
)

var (
	// ErrInvalidSize records attempts to open a grub environment block of size other than expected.
	ErrInvalidSize = errors.New("invalid environment size")
)

Types

type Cursor

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

Cursor navigates entries in a GRUB environment block.

The cursor automatically skips the header and the unused space. At any time the cursor is either at a valid position corresponding to an entry or is at the end of the block.

Subsequent calls of Next advance cursor position.

func NewCursor

func NewCursor(buf []byte) *Cursor

NewCursor returns a cursor for the given buffer.

The cursor may modify the buffer if any of the mutating functions, like SetValue, Delete and Insert, are called.

func (*Cursor) Delete

func (cur *Cursor) Delete()

Delete deletes the current entry.

Immediately after calling Delete, the current entry is invalid. Call Next to find the next valid entry.

func (*Cursor) Entry

func (cur *Cursor) Entry() string

Entry returns the entry at the current cursor position.

The entry is returned in its raw form, it cannot be used directly.

func (*Cursor) InsertBefore

func (cur *Cursor) InsertBefore(key, value string) error

InsertBefore creates a new entry at the current cursor position.

The cursor should not be at the initial header position as doing so will create an incorrect environment file by shifting the header down the buffer.

func (*Cursor) Key

func (cur *Cursor) Key() string

Key returns the name of the entry at the cursor position.

func (*Cursor) Next

func (cur *Cursor) Next() bool

Next advances towards the next key-value entry.

func (*Cursor) SetValue

func (cur *Cursor) SetValue(value string) error

SetValue replaces the value of the current key.

The value is automatically escaped. Depending on the size of the entry at the cursor, the new value either: replaces the old value in place, uses less space than before, causing all the remaining records to shift left, uses more space than before, causing all the remaining records to shift right if sufficient space is available.

SetValue fails if the current entry is corrupted or if storing the new value would exceed available space.

func (*Cursor) Value

func (cur *Cursor) Value() string

Value returns the value of the entry at the cursor position.

type Env

type Env [1024]byte

Env is a GRUB environment block.

GRUB environment block is a fixed-size byte array for storing key-value pairs terminated with a newline byte. Any byte may be escaped with the '\' byte. The block has a fixed size informative header which must be present. All unused space in the block is filled with '#' bytes

Note that the zero value is not a valid environment block.

func LoadEnv

func LoadEnv(path string) (*Env, error)

LoadEnv loads an environment block from the given file.

LoadEnv fails if the file is not exactly 1024 bytes long.

func NewEnv

func NewEnv() *Env

NewEnv returns an empty, valid environment block.

func (*Env) Delete

func (env *Env) Delete(key string)

Delete deletes the given variable.

If there are multiple variables with the same name, they are all deleted.

func (*Env) Get

func (env *Env) Get(key string) string

Get returns the value of the given variable.

If the variable is defined multiple times, the first value is returned. If the variable is not defined, an empty string is returned.

func (*Env) Lookup

func (env *Env) Lookup(key string) (string, bool)

Lookup returns the value of the given variable.

Lookup is like Get except that it also returns a boolean flag indicating if the variable was defined or not.

func (*Env) Save

func (env *Env) Save(path string) error

Save saves the environment block to the given file.

The file is written to without any fancy replacement logic. In case of power loss the original file may be truncated or clobbered. The file is created with mode 0o600 to avoid leaking information.

func (*Env) Set

func (env *Env) Set(key, value string) error

Set sets the value of a given variable.

Existing variable is resized in place, without affecting the order. If the variable is not defined it is inserted after all the existing variables.

Set may fail if the value is too long to store. In that case the environment block is not modified.

If there are multiple variables with the same name, they are all modified.

func (*Env) String

func (env *Env) String() string