package sys

Import Path
	github.com/tetratelabs/wazero/internal/sys (on go.dev)

Dependency Relation
	imports 14 packages, and imported by 2 packages

Involved Source Files

	    fs.go
	    lazy.go
	    stdio.go
	    sys.go
Package-Level Type Names (total 6)

	/* sort by: alphabet | popularity */
	 type Context (struct)
		Context holds module-scoped system resources currently only supported by
		built-in host functions.

		Methods (total 14)
			(*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

			(*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

			(*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

			(*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

			(*Context) FS() *FSContext
				FS returns the possibly empty (UnimplementedFS) file system context.

			(*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.

			(*Context) Nanosleep(ns int64)
				Nanosleep implements sys.Nanosleep.

			(*Context) Nanotime() int64
				Nanotime implements sys.Nanotime.

			(*Context) NanotimeResolution() sys.ClockResolution
				NanotimeResolution returns resolution of Nanotime.

			(*Context) Osyield()
				Osyield implements sys.Osyield.

			(*Context) RandSource() io.Reader
				RandSource is a source of random bytes and defaults to a deterministic source.
				see wazero.ModuleConfig WithRandSource

			(*Context) Walltime() (sec int64, nsec int32)
				Walltime implements platform.Walltime.

			(*Context) WalltimeNanos() int64
				WalltimeNanos returns platform.Walltime as epoch nanoseconds.

			(*Context) WalltimeResolution() sys.ClockResolution
				WalltimeResolution returns resolution of Walltime.

		As Outputs Of (at least 2)
			func DefaultContext(fs experimentalsys.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, osyield sys.Osyield, fs []experimentalsys.FS, guestPaths []string, tcpListeners []*net.TCPListener) (sysCtx *Context, err error)
		As Inputs Of (at least one exported)
			func github.com/tetratelabs/wazero/internal/wasm.(*Store).Instantiate(ctx context.Context, module *wasm.Module, name string, sys *Context, typeIDs []wasm.FunctionTypeID) (*wasm.ModuleInstance, error)

	 type DirentCache (struct)
		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.

		Methods (only one)
			(*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`.

		As Outputs Of (at least one exported)
			func (*FileEntry).DirentCache() (*DirentCache, sys.Errno)

	 type FileEntry (struct)
		FileEntry maps a path to an open file in a file system.

		Fields (total 4)
			FS sys.FS
				FS is the filesystem associated with the pre-open.

			File fsapi.File
				File is always non-nil.

			IsPreopen bool
				IsPreopen is a directory that is lazily opened.

			Name string
				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.

		Methods (only one)
			(*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.

		As Outputs Of (at least one exported)
			func (*FSContext).LookupFile(fd int32) (*FileEntry, bool)

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

	 type FSContext (struct)

		Methods (total 6)
			(*FSContext) Close() (err error)
				Close implements io.Closer

			(*FSContext) CloseFile(fd int32) (errno sys.Errno)
				CloseFile returns any error closing the existing file.

			(*FSContext) LookupFile(fd int32) (*FileEntry, bool)
				LookupFile returns a file if it is in the table.

			(*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.

			(*FSContext) Renumber(from, to int32) sys.Errno
				Renumber assigns the file pointed by the descriptor `from` to `to`.

			(*FSContext) SockAccept(sockFD int32, nonblock bool) (int32, sys.Errno)
				SockAccept accepts a sock.TCPConn into the file table and returns its file
				descriptor.

		Implements (at least 2)
			*FSContext : github.com/prometheus/common/expfmt.Closer
			*FSContext : io.Closer
		As Outputs Of (at least one exported)
			func (*Context).FS() *FSContext

	 type StdinFile (struct)
		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.

		Fields (total 2)
			noopStdinFile.noopStdioFile.UnimplementedFile experimentalsys.UnimplementedFile
			Reader io.Reader
		Methods (total 20)
			( StdinFile) Close() (errno experimentalsys.Errno)
				Close implements the same method as documented on sys.File

			( StdinFile) Datasync() sys.Errno
				Datasync implements File.Datasync

			( StdinFile) Dev() (uint64, sys.Errno)
				Dev implements File.Dev

			( StdinFile) Ino() (sys.Inode, sys.Errno)
				Ino implements File.Ino

			( StdinFile) IsAppend() bool
				IsAppend implements File.IsAppend

			( StdinFile) IsDir() (bool, experimentalsys.Errno)
				IsDir implements the same method as documented on sys.File

			( StdinFile) IsNonblock() bool
				IsNonblock implements the same method as documented on fsapi.File

			( StdinFile) Poll(flag fsapi.Pflag, timeoutMillis int32) (ready bool, errno experimentalsys.Errno)
				Poll implements the same method as documented on fsapi.File

			( StdinFile) Pread([]byte, int64) (int, sys.Errno)
				Pread implements File.Pread

			( StdinFile) Pwrite([]byte, int64) (int, sys.Errno)
				Pwrite implements File.Pwrite

			(*StdinFile) Read(buf []byte) (int, experimentalsys.Errno)
				Read implements the same method as documented on sys.File

			( StdinFile) Readdir(int) (dirents []sys.Dirent, errno sys.Errno)
				Readdir implements File.Readdir

			( StdinFile) Seek(int64, int) (int64, sys.Errno)
				Seek implements File.Seek

			( StdinFile) SetAppend(bool) sys.Errno
				SetAppend implements File.SetAppend

			( StdinFile) SetNonblock(bool) experimentalsys.Errno
				SetNonblock implements the same method as documented on fsapi.File

			( StdinFile) Stat() (sys.Stat_t, experimentalsys.Errno)
				Stat implements the same method as documented on sys.File

			( StdinFile) Sync() sys.Errno
				Sync implements File.Sync

			( StdinFile) Truncate(int64) sys.Errno
				Truncate implements File.Truncate

			( StdinFile) Utimens(int64, int64) sys.Errno
				Utimens implements File.Utimens

			( StdinFile) Write([]byte) (int, sys.Errno)
				Write implements File.Write

		Implements (at least 2)
			*StdinFile : github.com/tetratelabs/wazero/internal/fsapi.File
			*StdinFile : github.com/tetratelabs/wazero/experimental/sys.File


Package-Level Functions (total 3)

	 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(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 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.


Package-Level Constants (total 4)

	const FdPreopen int32 = 3
		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

	const FdStderr int32 = 2
	const FdStdin int32 = 0
	const FdStdout int32 = 1

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.