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#
func Register(f *FileSystem) error- type Attr
- type Creator
- type Device
func (d *Device) BlockSize() intfunc (d *Device) Blocks() uint64func (d *Device) ReadBlocks(block uint64, p []byte) errorfunc (d *Device) ReadOnly() boolfunc (d *Device) SetBlockSize(size int) errorfunc (d *Device) Size() int64func (d *Device) Sync() errorfunc (d *Device) WriteBlocks(block uint64, p []byte) error
- type Dir
- type FileSystem
- type Forgetter
- type Mkdirer
- type Mode
- type MountOptions
- type Node
- type Reader
- type Readlinker
- type Remover
- type Renamer
- type SetTimer
- type StatFS
- type Statfser
- type Symlinker
- type Syncer
- type Truncater
- type Unmounter
- type Writer
- type Xattrer
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 (Mode) IsSymlink#
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.