sys

Documentation

Index

• Constants
• func StripPrefixesAndTrailingSlash(path string) string
• type Context
  • func DefaultContext(fs experimentalsys.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) InitFSContext(stdin io.Reader, stdout, stderr io.Writer, fs []sys.FS, guestPaths []string, ...) (err error)
  • 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 DirentCache
  • func (d *DirentCache) Read(pos uint64, n uint32) (dirents []sys.Dirent, errno sys.Errno)
• type FSContext
  • func (c *FSContext) Close() (err error)
  • func (c *FSContext) CloseFile(fd int32) (errno sys.Errno)
  • func (c *FSContext) LookupFile(fd int32) (*FileEntry, bool)
  • func (c *FSContext) OpenFile(fs sys.FS, path string, flag sys.Oflag, perm fs.FileMode) (int32, sys.Errno)
  • func (c *FSContext) Renumber(from, to int32) sys.Errno
  • func (c *FSContext) RootFS() sys.FS
  • func (c *FSContext) SockAccept(sockFD int32, nonblock bool) (int32, sys.Errno)
• type FileEntry
  • func (f *FileEntry) DirentCache() (*DirentCache, sys.Errno)
• type FileTable
• type StdinFile
  • func (StdinFile) Poll(flag fsapi.Pflag, timeoutMillis int32) (ready bool, errno experimentalsys.Errno)
  • func (f *StdinFile) Read(buf []byte) (int, experimentalsys.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
)

Functions

func StripPrefixesAndTrailingSlash

func StripPrefixesAndTrailingSlash(path string) string

StripPrefixesAndTrailingSlash skips any leading "./" or "/" such that the result index begins with another string. A result of "." coerces to the empty string "" because the current directory is handled by the guest.

Results are the offset/len pair which is an optimization to avoid re-slicing overhead, as this function is called for every path operation.

Note: Relative paths should be handled by the guest, as that's what knows what the current directory is. However, paths that escape the current directory e.g. "../.." have been found in `tinygo test` and this implementation takes care to avoid it.

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

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

Note: 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,
	fs []experimentalsys.FS, guestPaths []string,
	tcpListeners []*net.TCPListener,
) (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) InitFSContext

func (c *Context) InitFSContext(
	stdin io.Reader,
	stdout, stderr io.Writer,
	fs []sys.FS, guestPaths []string,
	tcpListeners []*net.TCPListener,
) (err error)

InitFSContext initializes a FSContext with stdio streams and optional pre-opened filesystems and TCP listeners.

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 DirentCache

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

DirentCache is a caching abstraction of sys.File Readdir.

This is special-cased for "wasi_snapshot_preview1.fd_readdir", and may be unneeded, or require changes, to support preview1 or preview2.

• The position of the dirents are serialized as `d_next`. For reasons described below, any may need to be re-read. This accepts any positions in the cache, rather than track the position of the last dirent.
• dot entries ("." and "..") must be returned. See /RATIONALE.md for why.
• An sys.Dirent Name is variable length, it could exceed memory size and need to be re-read.
• Multiple dirents may be returned. It is more efficient to read from the underlying file in bulk vs one-at-a-time.

The last results returned by Read are cached, but entries before that position are not. This support re-reading entries that couldn't fit into memory without accidentally caching all entries in a large directory. This approach is sometimes called a sliding window.

func (*DirentCache) Read

func (d *DirentCache) Read(pos uint64, n uint32) (dirents []sys.Dirent, errno sys.Errno)

Read is similar to and returns the same errors as `Readdir` on sys.File. The main difference is this caches entries returned, resulting in multiple valid positions to read from.

When zero, `pos` means rewind to the beginning of this directory. This implies a rewind (Seek to zero on the underlying sys.File), unless the initial entries are still cached.

When non-zero, `pos` is the zero based index of all dirents returned since last rewind. Only entries beginning at `pos` are cached for subsequent calls. A non-zero `pos` before the cache returns sys.ENOENT for reasons described on DirentCache documentation.

Up to `n` entries are cached and returned. When `n` exceeds the cache, the difference are read from the underlying sys.File via `Readdir`. EOF is when `len(dirents)` returned are less than `n`.

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) (errno sys.Errno)

CloseFile returns any error closing the existing file.

func (*FSContext) LookupFile

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

LookupFile returns a file if it is in the table.

func (*FSContext) OpenFile

func (c *FSContext) OpenFile(fs sys.FS, path string, flag sys.Oflag, perm fs.FileMode) (int32, sys.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) sys.Errno

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

func (*FSContext) RootFS

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

RootFS returns a possibly unimplemented root filesystem. Any files that should be added to the table should be inserted via InsertFile.

TODO: This is only used by GOOS=js and tests: Remove when we remove GOOS=js (after Go 1.22 is released).

func (*FSContext) SockAccept

func (c *FSContext) SockAccept(sockFD int32, nonblock bool) (int32, sys.Errno)

SockAccept accepts a sock.TCPConn into the file table and returns its file descriptor.

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 sys.FS

	// File is always non-nil.
	File fsapi.File
	// contains filtered or unexported fields
}

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

func (*FileEntry) DirentCache

func (f *FileEntry) DirentCache() (*DirentCache, sys.Errno)

DirentCache gets or creates a DirentCache for this file or returns an error.

Errors

A zero sys.Errno is success. The below are expected otherwise:

• sys.ENOSYS: the implementation does not support this function.
• sys.EBADF: the dir was closed or not readable.
• sys.ENOTDIR: the file was not a directory.

Notes

• See /RATIONALE.md for design notes.

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

func (StdinFile) Poll(flag fsapi.Pflag, timeoutMillis int32) (ready bool, errno experimentalsys.Errno)

Poll implements the same method as documented on fsapi.File

func (*StdinFile) Read

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

Read implements the same method as documented on sys.File