sys

Documentation

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, ...) (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) Osyield()
  • 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) ChangeOpenFlag(fd uint32, flag int) 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) Renumber(from, to uint32) error
  • func (c *FSContext) RootFS() sysfs.FS
• type FileEntry
  • func (f *FileEntry) CachedStat() (ino uint64, fileType fs.FileMode, err error)
  • func (f *FileEntry) Stat(st *platform.Stat_t) (err error)
• type FileTable
• 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,
	osyield *sys.Osyield,
	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) Osyield

func (c *Context) Osyield()

Osyield implements sys.Osyield.

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) ChangeOpenFlag

func (c *FSContext) ChangeOpenFlag(fd uint32, flag int) error

ChangeOpenFlag changes the open flag of the given opened file pointed by `fd`. Currently, this only supports the change of syscall.O_APPEND flag.

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) Renumber

func (c *FSContext) Renumber(from, to uint32) error

Renumber assigns the file pointed by the descriptor `from` to `to`.

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) CachedStat

func (f *FileEntry) CachedStat() (ino uint64, fileType fs.FileMode, err error)

CachedStat returns the cacheable parts of platform.Stat_t or an error if they couldn't be retrieved.

func (*FileEntry) Stat

func (f *FileEntry) Stat(st *platform.Stat_t) (err error)

Stat returns the underlying stat of this file.

type FileTable

type FileTable = descriptor.Table[uint32, *FileEntry]

FileTable is an specialization of the descriptor.Table type used to map file descriptors to file entries.

type ReadDir

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

	// Dirents is the contents of the last platform.Readdir 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.
	//
	// Note: This is wasi-specific and needs to be refactored.
	// In wasi preview1, dot and dot-dot entries are required to exist, but the
	// reverse is true for preview2. More importantly, preview2 holds separate
	// stateful dir-entry-streams per file.
	Dirents []*platform.Dirent
}

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