package sys

import "github.com/tetratelabs/wazero/internal/sys"

Index ¶

• Constants
• func WriterForFile(fsc *FSContext, fd uint32) (writer io.Writer)
• type Context
• func DefaultContext(fs sysfs.FS) *Context
• func NewContext( max uint32, args, environ [][]byte, stdin io.Reader, stdout, stderr io.Writer, randSource io.Reader, walltime *sys.Walltime, walltimeResolution sys.ClockResolution, nanotime *sys.Nanotime, nanotimeResolution sys.ClockResolution, nanosleep *sys.Nanosleep, rootFS sysfs.FS, ) (sysCtx *Context, err error)
• func (c *Context) Args() [][]byte
• func (c *Context) ArgsSize() uint32
• func (c *Context) Environ() [][]byte
• func (c *Context) EnvironSize() uint32
• func (c *Context) FS() *FSContext
• func (c *Context) Nanosleep(ns int64)
• func (c *Context) Nanotime() int64
• func (c *Context) NanotimeResolution() sys.ClockResolution
• func (c *Context) RandSource() io.Reader
• func (c *Context) Walltime() (sec int64, nsec int32)
• func (c *Context) WalltimeNanos() int64
• func (c *Context) WalltimeResolution() sys.ClockResolution
• type FSContext
• func NewFSContext(stdin io.Reader, stdout, stderr io.Writer, rootFS sysfs.FS) (fsc *FSContext, err error)
• func (c *FSContext) Close(context.Context) (err error)
• func (c *FSContext) CloseFile(fd uint32) error
• func (c *FSContext) LookupFile(fd uint32) (*FileEntry, bool)
• func (c *FSContext) OpenFile(fs sysfs.FS, path string, flag int, perm fs.FileMode) (uint32, error)
• func (c *FSContext) ReOpenDir(fd uint32) (*FileEntry, error)
• func (c *FSContext) RootFS() sysfs.FS
• type FileEntry
• func (f *FileEntry) IsDir() bool
• func (f *FileEntry) Stat() (stat fs.FileInfo, err error)
• type FileTable
• func (t *FileTable) Delete(fd uint32)
• func (t *FileTable) Grow(n int)
• func (t *FileTable) Insert(file *FileEntry) (fd uint32)
• func (t *FileTable) Len() (n int)
• func (t *FileTable) Lookup(fd uint32) (file *FileEntry, found bool)
• func (t *FileTable) Range(f func(uint32, *FileEntry) bool)
• func (t *FileTable) Reset()
• type ReadDir

Constants ¶

const (
	FdStdin uint32 = iota
	FdStdout
	FdStderr
	// FdPreopen is the file descriptor of the first pre-opened directory.
	//
	// # Why file descriptor 3?
	//
	// While not specified, the most common WASI implementation, wasi-libc,
	// expects POSIX style file descriptor allocation, where the lowest
	// available number is used to open the next file. Since 1 and 2 are taken
	// by stdout and stderr, the next is 3.
	//   - https://github.com/WebAssembly/WASI/issues/122
	//   - https://pubs.opengroup.org/onlinepubs/9699919799/functions/V2_chap02.html#tag_15_14
	//   - https://github.com/WebAssembly/wasi-libc/blob/wasi-sdk-16/libc-bottom-half/sources/preopens.c#L215
	FdPreopen
)

Functions ¶

func WriterForFile ¶

func WriterForFile(fsc *FSContext, fd uint32) (writer io.Writer)

WriterForFile returns a writer for the given file descriptor or nil if not opened or not writeable (e.g. a directory or a file not opened for writes).

Types ¶

type Context ¶

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

Context holds module-scoped system resources currently only supported by built-in host functions.

func DefaultContext ¶

func DefaultContext(fs sysfs.FS) *Context

DefaultContext returns Context with no values set except a possible nil fs.FS

func NewContext ¶

func NewContext(
	max uint32,
	args, environ [][]byte,
	stdin io.Reader,
	stdout, stderr io.Writer,
	randSource io.Reader,
	walltime *sys.Walltime,
	walltimeResolution sys.ClockResolution,
	nanotime *sys.Nanotime,
	nanotimeResolution sys.ClockResolution,
	nanosleep *sys.Nanosleep,
	rootFS sysfs.FS,
) (sysCtx *Context, err error)

NewContext is a factory function which helps avoid needing to know defaults or exporting all fields. Note: max is exposed for testing. max is only used for env/args validation.

func (*Context) Args ¶

func (c *Context) Args() [][]byte

Args is like os.Args and defaults to nil.

Note: The count will never be more than math.MaxUint32. See wazero.ModuleConfig WithArgs

func (*Context) ArgsSize ¶

func (c *Context) ArgsSize() uint32

ArgsSize is the size to encode Args as Null-terminated strings.

Note: To get the size without null-terminators, subtract the length of Args from this value. See wazero.ModuleConfig WithArgs See https://en.wikipedia.org/wiki/Null-terminated_string

func (*Context) Environ ¶

func (c *Context) Environ() [][]byte

Environ are "key=value" entries like os.Environ and default to nil.

Note: The count will never be more than math.MaxUint32. See wazero.ModuleConfig WithEnv

func (*Context) EnvironSize ¶

func (c *Context) EnvironSize() uint32

EnvironSize is the size to encode Environ as Null-terminated strings.

Note: To get the size without null-terminators, subtract the length of Environ from this value. See wazero.ModuleConfig WithEnv See https://en.wikipedia.org/wiki/Null-terminated_string

func (*Context) FS ¶

func (c *Context) FS() *FSContext

FS returns the possibly empty (sysfs.UnimplementedFS) file system context.

func (*Context) Nanosleep ¶

func (c *Context) Nanosleep(ns int64)

Nanosleep implements sys.Nanosleep.

func (*Context) Nanotime ¶

func (c *Context) Nanotime() int64

Nanotime implements sys.Nanotime.

func (*Context) NanotimeResolution ¶

func (c *Context) NanotimeResolution() sys.ClockResolution

NanotimeResolution returns resolution of Nanotime.

func (*Context) RandSource ¶

func (c *Context) RandSource() io.Reader

RandSource is a source of random bytes and defaults to a deterministic source. see wazero.ModuleConfig WithRandSource

func (*Context) Walltime ¶

func (c *Context) Walltime() (sec int64, nsec int32)

Walltime implements platform.Walltime.

func (*Context) WalltimeNanos ¶

func (c *Context) WalltimeNanos() int64

WalltimeNanos returns platform.Walltime as epoch nanoseconds.

func (*Context) WalltimeResolution ¶

func (c *Context) WalltimeResolution() sys.ClockResolution

WalltimeResolution returns resolution of Walltime.

type FSContext ¶

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

func NewFSContext ¶

func NewFSContext(stdin io.Reader, stdout, stderr io.Writer, rootFS sysfs.FS) (fsc *FSContext, err error)

NewFSContext creates a FSContext with stdio streams and an optional pre-opened filesystem.

If `preopened` is not sysfs.UnimplementedFS, it is inserted into the file descriptor table as FdPreopen.

func (*FSContext) Close ¶

func (c *FSContext) Close(context.Context) (err error)

Close implements api.Closer

func (*FSContext) CloseFile ¶

func (c *FSContext) CloseFile(fd uint32) error

CloseFile returns any error closing the existing file.

func (*FSContext) LookupFile ¶

func (c *FSContext) LookupFile(fd uint32) (*FileEntry, bool)

LookupFile returns a file if it is in the table.

func (*FSContext) OpenFile ¶

func (c *FSContext) OpenFile(fs sysfs.FS, path string, flag int, perm fs.FileMode) (uint32, error)

OpenFile opens the file into the table and returns its file descriptor. The result must be closed by CloseFile or Close.

func (*FSContext) ReOpenDir ¶

func (c *FSContext) ReOpenDir(fd uint32) (*FileEntry, error)

ReOpenDir re-opens the directory while keeping the same file descriptor. TODO: this might not be necessary once we have our own File type.

func (*FSContext) RootFS ¶

func (c *FSContext) RootFS() sysfs.FS

RootFS returns the underlying filesystem. Any files that should be added to the table should be inserted via InsertFile.

type FileEntry ¶

type FileEntry struct {
	// Name is the name of the directory up to its pre-open, or the pre-open
	// name itself when IsPreopen.
	//
	// Note: This can drift on rename.
	Name string

	// IsPreopen is a directory that is lazily opened.
	IsPreopen bool

	// FS is the filesystem associated with the pre-open.
	FS sysfs.FS

	// File is always non-nil.
	File fs.File

	// ReadDir is present when this File is a fs.ReadDirFile and `ReadDir`
	// was called.
	ReadDir *ReadDir
	// contains filtered or unexported fields
}

FileEntry maps a path to an open file in a file system.

func (*FileEntry) IsDir ¶

func (f *FileEntry) IsDir() bool

IsDir returns true if the file is a directory.

func (*FileEntry) Stat ¶

func (f *FileEntry) Stat() (stat fs.FileInfo, err error)

Stat returns the underlying stat of this file.

type FileTable ¶

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

FileTable is a data structure mapping 32 bit file descriptor to file objects.

The data structure optimizes for memory density and lookup performance, trading off compute at insertion time. This is a useful compromise for the use cases we employ it with: files are usually read or written a lot more often than they are opened, each operation requires a table lookup so we are better off spending extra compute to insert files in the table in order to get cheaper lookups. Memory efficiency is also crucial to support scaling with programs that open thousands of files: having a high or non-linear memory-to-item ratio could otherwise be used as an attack vector by malicous applications attempting to damage performance of the host.

func (*FileTable) Delete ¶

func (t *FileTable) Delete(fd uint32)

Delete deletes the file stored at the given fd from the table.

func (*FileTable) Grow ¶

func (t *FileTable) Grow(n int)

Grow ensures that t has enough room for n files, potentially reallocating the internal buffers if their capacity was too small to hold this many files.

func (*FileTable) Insert ¶

func (t *FileTable) Insert(file *FileEntry) (fd uint32)

Insert inserts the given file to the table, returning the fd that it is mapped to.

The method does not perform deduplication, it is possible for the same file to be inserted multiple times, each insertion will return a different fd.

func (*FileTable) Len ¶

func (t *FileTable) Len() (n int)

Len returns the number of files stored in the table.

func (*FileTable) Lookup ¶

func (t *FileTable) Lookup(fd uint32) (file *FileEntry, found bool)

Lookup returns the file associated with the given fd (may be nil).

func (*FileTable) Range ¶

func (t *FileTable) Range(f func(uint32, *FileEntry) bool)

Range calls f for each file and its associated fd in the table. The function f might return false to interupt the iteration.

func (*FileTable) Reset ¶

func (t *FileTable) Reset()

Reset clears the content of the table.

type ReadDir ¶

type ReadDir struct {
	// CountRead is the total count of files read including Entries.
	CountRead uint64

	// Entries is the contents of the last fs.ReadDirFile call. Notably,
	// directory listing are not rewindable, so we keep entries around in case
	// the caller mis-estimated their buffer and needs a few still cached.
	Entries []fs.DirEntry
}

ReadDir is the status of a prior fs.ReadDirFile call.

Source Files ¶

file_table.go fs.go sys.go