sys

Documentation

Index

• Constants
• type Context
  • func DefaultContext(fs fsapi.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) NewFSContext(stdin io.Reader, stdout, stderr io.Writer, rootFS fsapi.FS) (err error)
  • 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 (c *FSContext) Close() (err error)
  • func (c *FSContext) CloseFile(fd int32) syscall.Errno
  • func (c *FSContext) CloseReaddir(idx int32)
  • func (c *FSContext) LookupFile(fd int32) (*FileEntry, bool)
  • func (c *FSContext) LookupReaddir(idx int32, f *FileEntry) (*Readdir, syscall.Errno)
  • func (c *FSContext) OpenFile(fs fsapi.FS, path string, flag int, perm fs.FileMode) (int32, syscall.Errno)
  • func (c *FSContext) Renumber(from, to int32) syscall.Errno
  • func (c *FSContext) RootFS() fsapi.FS
• type FileEntry
• type FileTable
• type Readdir
  • func NewReaddir(dirInit func() ([]fsapi.Dirent, syscall.Errno), ...) (*Readdir, syscall.Errno)
  • func (d *Readdir) Advance() syscall.Errno
  • func (d *Readdir) Cookie() uint64
  • func (d *Readdir) Peek() (*fsapi.Dirent, syscall.Errno)
  • func (d *Readdir) Reset() syscall.Errno
  • func (d *Readdir) Rewind(cookie int64) syscall.Errno
  • func (d *Readdir) Skip(n uint64)
• type ReaddirTable
• type StdinFile
  • func (StdinFile) AccessMode() int
  • func (StdinFile) PollRead(*time.Duration) (ready bool, errno syscall.Errno)
  • func (f *StdinFile) Read(buf []byte) (int, syscall.Errno)

Constants

const (
	FdStdin int32 = 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
)

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

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

This is only used for testing.

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 fsapi.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 (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) NewFSContext

func (c *Context) NewFSContext(stdin io.Reader, stdout, stderr io.Writer, rootFS fsapi.FS) (err error)

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

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

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 (*FSContext) Close

func (c *FSContext) Close() (err error)

Close implements io.Closer

func (*FSContext) CloseFile

func (c *FSContext) CloseFile(fd int32) syscall.Errno

CloseFile returns any error closing the existing file.

func (*FSContext) CloseReaddir

func (c *FSContext) CloseReaddir(idx int32)

CloseReaddir delete the Readdir struct at the given index

Note: Currently only necessary in tests. In the future, the idx will have to be disposed explicitly, unless we maintain a map fd -> []idx, and we let CloseFile close all the idx in []idx.

func (*FSContext) LookupFile

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

LookupFile returns a file if it is in the table.

func (*FSContext) LookupReaddir

func (c *FSContext) LookupReaddir(idx int32, f *FileEntry) (*Readdir, syscall.Errno)

LookupReaddir returns a Readdir struct or creates an empty one if it was not present.

Note: this currently assumes that idx == fd, where fd is the file descriptor of the directory. CloseFile will delete this idx from the internal store. In the future, idx may be independent of a file fd, and the idx may have to be disposed with an explicit CloseReaddir.

func (*FSContext) OpenFile

func (c *FSContext) OpenFile(fs fsapi.FS, path string, flag int, perm fs.FileMode) (int32, syscall.Errno)

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

func (*FSContext) Renumber

func (c *FSContext) Renumber(from, to int32) syscall.Errno

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

func (*FSContext) RootFS

func (c *FSContext) RootFS() fsapi.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.
	//
	// # Notes
	//
	//   - This can drift on rename.
	//   - This relates to the guest path, which is not the real file path
	//     except if the entire host filesystem was made available.
	Name string

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

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

	// File is always non-nil.
	File fsapi.File
}

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

type FileTable

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

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

type Readdir

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

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

func NewReaddir

func NewReaddir(
	dirInit func() ([]fsapi.Dirent, syscall.Errno),
	dirReader func(n uint64) ([]fsapi.Dirent, syscall.Errno),
) (*Readdir, syscall.Errno)

NewReaddir is a constructor for Readdir. It takes a dirInit

func (*Readdir) Advance

func (d *Readdir) Advance() syscall.Errno

Advance advances the internal counters and indices to the next value. It also empties and refill the buffer with the next set of values when the internal cursor reaches the end of it.

func (*Readdir) Cookie

func (d *Readdir) Cookie() uint64

Cookie returns a cookie representing the current state of the ReadDir struct.

Note: this returns the countRead field, but it is an implementation detail.

func (*Readdir) Peek

func (d *Readdir) Peek() (*fsapi.Dirent, syscall.Errno)

Peek emits the current value. It returns syscall.ENOENT when there are no entries left in the directory.

func (*Readdir) Reset

func (d *Readdir) Reset() syscall.Errno

Reset seeks the internal cursor to 0 and refills the buffer.

func (*Readdir) Rewind

func (d *Readdir) Rewind(cookie int64) syscall.Errno

Rewind seeks the internal cursor to the state represented by the cookie. It returns a syscall.Errno if the cursor was reset and an I/O error occurred while trying to re-init.

func (*Readdir) Skip

func (d *Readdir) Skip(n uint64)

Skip is equivalent to calling n times Advance.

type ReaddirTable

type ReaddirTable = descriptor.Table[int32, *Readdir]

ReaddirTable is a specialization of the descriptor.Table type used to map file descriptors to Readdir structs.

type StdinFile

type StdinFile struct {
	io.Reader
	// contains filtered or unexported fields
}

StdinFile is a fs.ModeDevice file for use implementing FdStdin. This is safer than reading from os.DevNull as it can never overrun operating system file descriptors.

func (StdinFile) AccessMode

func (StdinFile) AccessMode() int

AccessMode implements the same method as documented on internalapi.File

func (StdinFile) PollRead

func (StdinFile) PollRead(*time.Duration) (ready bool, errno syscall.Errno)

PollRead implements the same method as documented on internalapi.File

func (*StdinFile) Read

func (f *StdinFile) Read(buf []byte) (int, syscall.Errno)

Read implements the same method as documented on internalapi.File