sys

Documentation

Index

• Constants
• Variables
• func FdReader(ctx context.Context, sysCtx *Context, fd uint32) io.Reader
• func FdWriter(ctx context.Context, sysCtx *Context, fd uint32) io.Writer
• type Context
  • func DefaultContext(fs fs.FS) *Context
  • func NewContext(max uint32, args, environ []string, stdin io.Reader, stdout, stderr io.Writer, ...) (sysCtx *Context, err error)
  • func (c *Context) Args() []string
  • func (c *Context) ArgsSize() uint32
  • func (c *Context) Environ() []string
  • func (c *Context) EnvironSize() uint32
  • func (c *Context) FS(ctx context.Context) *FSContext
  • func (c *Context) Nanosleep(ctx context.Context, ns int64)
  • func (c *Context) Nanotime(ctx context.Context) int64
  • func (c *Context) NanotimeResolution() sys.ClockResolution
  • func (c *Context) RandSource() io.Reader
  • func (c *Context) Stderr() io.Writer
  • func (c *Context) Stdin() io.Reader
  • func (c *Context) Stdout() io.Writer
  • func (c *Context) Walltime(ctx context.Context) (sec int64, nsec int32)
  • func (c *Context) WalltimeResolution() sys.ClockResolution
• type FSContext
  • func NewFSContext(root fs.FS) *FSContext
  • func (c *FSContext) Close(_ context.Context) (err error)
  • func (c *FSContext) CloseFile(_ context.Context, fd uint32) bool
  • func (c *FSContext) OpenFile(_ context.Context, name string) (uint32, error)
  • func (c *FSContext) OpenedFile(_ context.Context, fd uint32) (*FileEntry, bool)
• type FSKey
• type FileEntry

Constants

const (
	FdStdin = iota
	FdStdout
	FdStderr
)

Variables

var EmptyFS = &emptyFS{}

EmptyFS is exported to special-case an empty file system.

Functions

func FdReader

func FdReader(ctx context.Context, sysCtx *Context, fd uint32) io.Reader

FdReader returns a valid reader for the given file descriptor or nil if syscall.EBADF.

func FdWriter

func FdWriter(ctx context.Context, sysCtx *Context, fd uint32) io.Writer

FdWriter returns a valid writer for the given file descriptor or nil if syscall.EBADF.

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 fs.FS) *Context

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

func NewContext

func NewContext(
	max uint32,
	args, environ []string,
	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,
	fs fs.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() []string

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() []string

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(ctx context.Context) *FSContext

FS returns a possibly nil file system context.

func (*Context) Nanosleep

func (c *Context) Nanosleep(ctx context.Context, ns int64)

Nanosleep implements sys.Nanosleep.

func (*Context) Nanotime

func (c *Context) Nanotime(ctx context.Context) 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) Stderr

func (c *Context) Stderr() io.Writer

Stderr is like exec.Cmd Stderr and defaults to io.Discard. See wazero.ModuleConfig WithStderr

func (*Context) Stdin

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

Stdin is like exec.Cmd Stdin and defaults to a reader of os.DevNull. See wazero.ModuleConfig WithStdin

func (*Context) Stdout

func (c *Context) Stdout() io.Writer

Stdout is like exec.Cmd Stdout and defaults to io.Discard. See wazero.ModuleConfig WithStdout

func (*Context) Walltime

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

Walltime implements sys.Walltime.

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(root fs.FS) *FSContext

NewFSContext creates a FSContext, using the `root` parameter for any paths beginning at "/". If the input is EmptyFS, there is no root filesystem. Otherwise, `root` is assigned file descriptor 3 and the returned context can open files in that file system.

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, `root` is assigned 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

func (*FSContext) Close

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

Close implements io.Closer

func (*FSContext) CloseFile

func (c *FSContext) CloseFile(_ context.Context, fd uint32) bool

CloseFile returns true if a file was opened and closed without error, or false if syscall.EBADF.

func (*FSContext) OpenFile

func (c *FSContext) OpenFile(_ context.Context, name string) (uint32, error)

OpenFile is like syscall.Open and returns the file descriptor of the new file or an error.

TODO: Consider dirflags and oflags. Also, allow non-read-only open based on config about the mount. Ex. allow os.O_RDONLY, os.O_WRONLY, or os.O_RDWR either by config flag or pattern on filename See #390

func (*FSContext) OpenedFile

func (c *FSContext) OpenedFile(_ context.Context, fd uint32) (*FileEntry, bool)

OpenedFile returns a file and true if it was opened or nil and false, if syscall.EBADF.

type FSKey

type FSKey struct{}

FSKey is a context.Context Value key. It allows overriding fs.FS for WASI.

See https://github.com/tetratelabs/wazero/issues/491

type FileEntry

type FileEntry struct {
	Path string
	// File when nil this is the root "/" (fd=3)
	File fs.File
}

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