gokm/fs

import "gokm/fs"

Package fs lets Go code implement a Linux filesystem.

Implement Dir and file nodes, register a FileSystem, and it can be mounted with `mount -t <name> none /mnt`. gokm compiles the kernel-side glue (VFS callbacks, inode/dentry caches, user-memory copies) into the module automatically when this package is imported.

type root struct{ ... }   // implements fs.Dir (+ Creator, Mkdirer, Remover)
type file struct{ ... }   // implements fs.Node (+ Reader, Writer, Truncater)

func main() {
	err := fs.Register(&fs.FileSystem{
		Name:  "myfs",
		Mount: func() (fs.Dir, error) { return newRoot(), nil },
	})
	if err != nil {
		kernel.FailLoad(err)
	}
}

Nodes must be comparable (use pointer types): the framework maps each node to an inode number. Methods return kernel.Errno values (kernel.ENOENT, kernel.ENOSPC, …) to report specific errors; other errors become EIO. Methods can be called concurrently from several CPUs (like HTTP handlers): protect shared state with a sync.Mutex. The kernel already serializes some operations (creating/removing entries in one directory, writes to one file).

Index#

Functions#

func Register#

func Register(f *FileSystem) error

Register registers the filesystem type with the kernel. It’s unregistered automatically at module exit (or earlier with Unregister).

Types#

type Attr#

type Attr struct {
	Mode Mode  // type and permissions
	Size int64 // size in bytes (regular files)
	// Timestamps; zero values leave the kernel's in-memory ones.
	Atime, Mtime, Ctime time.Time
}

Attr are a node’s attributes.

type Creator#

type Creator interface {
	Create(name string, mode Mode) (Node, error)
}

Creator creates regular files in a directory.

type Device#

type Device struct {
	// struct super_block

	// bytes

}

Device is the block device a filesystem is mounted from.

func (*Device) BlockSize#

func (d *Device) BlockSize() int

BlockSize returns the block size used by ReadBlocks/WriteBlocks (512 at mount time).

func (*Device) Blocks#

func (d *Device) Blocks() uint64

Blocks returns the device size in blocks.

func (*Device) ReadBlocks#

func (d *Device) ReadBlocks(block uint64, p []byte) error

ReadBlocks reads len(p)/BlockSize() blocks starting at block into p (len(p) must be a multiple of the block size). Reads go through the kernel’s buffer cache; other Go code keeps running while this one waits for the device.

func (*Device) ReadOnly#

func (d *Device) ReadOnly() bool

ReadOnly reports whether the filesystem is mounted read-only.

func (*Device) SetBlockSize#

func (d *Device) SetBlockSize(size int) error

SetBlockSize changes the block size (a power of two between the device’s logical block size and the page size).

func (*Device) Size#

func (d *Device) Size() int64

Size returns the device size in bytes.

func (*Device) Sync#

func (d *Device) Sync() error

Sync writes all dirty blocks of the device and waits for them.

func (*Device) WriteBlocks#

func (d *Device) WriteBlocks(block uint64, p []byte) error

WriteBlocks writes p (a multiple of the block size) starting at block. Data reaches the buffer cache; it’s written to the device later, or on Sync.

type Dir#

type Dir interface {
	Node
	// Lookup returns the child called name, or (nil, nil) / kernel.ENOENT
	// if there is none.
	Lookup(name string) (Node, error)
	// ReadDir calls yield for each entry, in a stable order, until yield
	// returns false.
	ReadDir(yield func(name string, n Node) bool) error
}

Dir is a directory.

type FileSystem#

type FileSystem struct {
	Name string
	// Magic is reported by statfs (f_type). Default: 0x676f6b6d ("gokm").
	Magic uint32
	// Mount is called for each mount and returns its root directory.
	Mount func() (Dir, error)
	// MountDevice, instead of Mount, makes this a block-device filesystem
	// (mount -t name /dev/... /mnt): it gets the device and returns the
	// root directory.
	MountDevice func(dev *Device, opts MountOptions) (Dir, error)
	// MaxFileSize limits file sizes (default: the kernel's maximum).
	MaxFileSize int64

	// kernel struct, 0 when not registered

}

FileSystem is a filesystem type.

func (*FileSystem) Unregister#

func (f *FileSystem) Unregister()

Unregister unregisters the filesystem type. Mounted instances keep the module loaded, so this only happens once all are unmounted.

type Forgetter#

type Forgetter interface {
	Forget()
}

Forgetter is implemented by nodes that want to know when the kernel is done with them after they were removed (e.g. the last close of an unlinked file): the moment to release their storage.

type Mkdirer#

type Mkdirer interface {
	Mkdir(name string, mode Mode) (Dir, error)
}

Mkdirer creates subdirectories.

type Mode#

type Mode uint32

Mode is a file type and permission bits, with Linux’s layout (S_IFDIR…).

const (
	ModeType    Mode = 0o170000
	ModeDir     Mode = 0o040000
	ModeRegular Mode = 0o100000
	ModeSymlink Mode = 0o120000
	ModePerm    Mode = 0o7777
)

func (Mode) IsDir#

func (m Mode) IsDir() bool

func (Mode) IsRegular#

func (m Mode) IsRegular() bool
func (m Mode) IsSymlink() bool

type MountOptions#

type MountOptions struct {
	ReadOnly bool
}

MountOptions describes a mount.

type Node#

type Node interface {
	Attr() Attr
}

Node is anything in the filesystem.

type Reader#

type Reader interface {
	ReadAt(p []byte, off int64) (int, error)
}

Reader reads file content at off. Return 0 (with nil or io.EOF) at end of file.

type Readlinker#

type Readlinker interface {
	Readlink() (string, error)
}

Readlinker is implemented by symbolic links.

type Remover#

type Remover interface {
	Remove(name string) error
}

Remover removes an entry (a file, or an empty directory: the framework checks emptiness before calling it for rmdir).

type Renamer#

type Renamer interface {
	Rename(oldName string, newDir Dir, newName string) error
}

Renamer moves the entry oldName of this directory to newName in newDir (possibly the same directory), replacing what’s there. The framework already checked that a replaced directory is empty and that the types match.

type SetTimer#

type SetTimer interface {
	SetTimes(atime, mtime *time.Time) error
}

SetTimer is implemented by nodes whose timestamps can be changed (touch, utimes). A nil time means unchanged.

type StatFS#

type StatFS struct {
	BlockSize   int64
	Blocks      uint64
	BlocksFree  uint64
	BlocksAvail uint64
	Files       uint64
	FilesFree   uint64
	NameLen     int64
}

StatFS are filesystem statistics, in units of BlockSize.

type Statfser#

type Statfser interface {
	Statfs() (StatFS, error)
}

Statfser is implemented by a root Dir to report statfs(2) numbers (otherwise they’re zero).

type Symlinker#

type Symlinker interface {
	Symlink(name, target string) (Node, error)
}

Symlinker creates symbolic links in a directory. The returned node should report ModeSymlink and implement Readlinker.

type Syncer#

type Syncer interface {
	Sync() error
}

Syncer is implemented by a root Dir that caches metadata: Sync writes it to the device (sync(2), syncfs(2), fsync(2), unmount).

type Truncater#

type Truncater interface {
	Truncate(size int64) error
}

Truncater changes a file’s size (truncate, O_TRUNC).

type Unmounter#

type Unmounter interface {
	Unmount()
}

Unmounter is implemented by a root Dir that wants to know when its mount goes away.

type Writer#

type Writer interface {
	WriteAt(p []byte, off int64) (int, error)
}

Writer writes file content at off, growing the file if needed.

type Xattrer#

type Xattrer interface {
	GetXattr(name string) ([]byte, error)
	SetXattr(name string, value []byte) error
	RemoveXattr(name string) error
	ListXattrs() ([]string, error)
}

Xattrer stores a node’s extended attributes (getfattr/setfattr): names come with their namespace prefix, “user.” or “trusted.” (the kernel checks permissions; trusted.* needs CAP_SYS_ADMIN). GetXattr and RemoveXattr return kernel.ENODATA for a missing name. SetXattr gets a copy of the value; the framework handles the create-only and replace-only flags. Without Xattrer, setting fails with EOPNOTSUPP.