wasi_snapshot_preview1

Documentation

Overview

Package wasi_snapshot_preview1 contains Go-defined functions to access system calls, such as opening a file, similar to Go's x/sys package. These are accessible from WebAssembly-defined functions via importing ModuleName. All WASI functions return a single Errno result: ErrnoSuccess on success.

e.g. Call Instantiate before instantiating any wasm binary that imports "wasi_snapshot_preview1", Otherwise, it will error due to missing imports.

ctx := context.Background()
r := wazero.NewRuntime(ctx)
defer r.Close(ctx) // This closes everything this Runtime created.

wasi_snapshot_preview1.MustInstantiate(ctx, r)
mod, _ := r.InstantiateModuleFromBinary(ctx, wasm)

See https://github.com/WebAssembly/WASI

Example

This is an example of how to use WebAssembly System Interface (WASI) with its simplest function: "proc_exit".

See https://github.com/tetratelabs/wazero/tree/main/examples/wasi for another example.

package main

import (
	"context"
	_ "embed"
	"fmt"
	"log"
	"os"

	"wa-lang.org/wazero"
	"wa-lang.org/wazero/sys"
)

// exitOnStartWasm was generated by the following:
//
//	cd testdata; wat2wasm --debug-names exit_on_start.wat
//
//go:embed testdata/exit_on_start.wasm
var exitOnStartWasm []byte

// This is an example of how to use WebAssembly System Interface (WASI) with its simplest function: "proc_exit".
//
// See https://github.com/tetratelabs/wazero/tree/main/examples/wasi for another example.
func main() {
	// Choose the context to use for function calls.
	ctx := context.Background()

	// Create a new WebAssembly Runtime.
	r := wazero.NewRuntime(ctx)

	// Instantiate WASI, which implements system I/O such as console output.
	wm, err := Instantiate(ctx, r)
	if err != nil {
		log.Panicln(err)
	}
	defer wm.Close(testCtx)

	// Compile the WebAssembly module using the default configuration.
	code, err := r.CompileModule(ctx, exitOnStartWasm)
	if err != nil {
		log.Panicln(err)
	}
	defer code.Close(ctx)

	// InstantiateModule runs the "_start" function which is like a "main" function.
	// Override default configuration (which discards stdout).
	mod, err := r.InstantiateModule(ctx, code, wazero.NewModuleConfig().WithStdout(os.Stdout).WithName("wasi-demo"))
	if mod != nil {
		defer r.Close(ctx)
	}

	// Note: Most compilers do not exit the module after running "_start", unless
	// there was an error. This allows you to call exported functions.
	if exitErr, ok := err.(*sys.ExitError); ok {
		fmt.Printf("exit_code: %d\n", exitErr.ExitCode())
	}

}

Output:

exit_code: 2

Index

• Constants
• func ErrnoName(errno Errno) string
• func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error)
• func MustInstantiate(ctx context.Context, r wazero.Runtime)
• type Builder
  • func NewBuilder(r wazero.Runtime) Builder
• type Errno
• type FunctionExporter
  • func NewFunctionExporter() FunctionExporter

Examples

• Package

Constants

const (
	ModuleName = "wasi_snapshot_preview1"
)

ModuleName is the module name WASI functions are exported into.

See https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md

Functions

func ErrnoName

func ErrnoName(errno Errno) string

ErrnoName returns the POSIX error code name, except ErrnoSuccess, which is not an error. e.g. Errno2big -> "E2BIG"

func Instantiate

func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error)

Instantiate instantiates the ModuleName module into the runtime default namespace.

Notes

• Failure cases are documented on wazero.Namespace InstantiateModule.
• Closing the wazero.Runtime has the same effect as closing the result.
• To instantiate into another wazero.Namespace, use NewBuilder instead.

func MustInstantiate

func MustInstantiate(ctx context.Context, r wazero.Runtime)

MustInstantiate calls Instantiate or panics on error.

This is a simpler function for those who know the module ModuleName is not already instantiated, and don't need to unload it.

Types

type Builder

type Builder interface {
	// Compile compiles the ModuleName module that can instantiated in any
	// namespace (wazero.Namespace).
	//
	// Note: This has the same effect as the same function on wazero.HostModuleBuilder.
	Compile(context.Context) (wazero.CompiledModule, error)

	// Instantiate instantiates the ModuleName module into the given namespace.
	//
	// Note: This has the same effect as the same function on wazero.HostModuleBuilder.
	Instantiate(context.Context, wazero.Namespace) (api.Closer, error)
}

Builder configures the ModuleName module for later use via Compile or Instantiate.

func NewBuilder

func NewBuilder(r wazero.Runtime) Builder

NewBuilder returns a new Builder.

type Errno

type Errno = uint32 // neither uint16 nor an alias for parity with wasm.ValueType

Errno are the error codes returned by WASI functions.

Notes

• This is not always an error, as ErrnoSuccess is a valid code.
• Codes are defined even when not relevant to WASI for use in higher-level libraries or alignment with POSIX.

See https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#-errno-enumu16 and https://linux.die.net/man/3/errno

const (
	// ErrnoSuccess No error occurred. System call completed successfully.
	ErrnoSuccess Errno = iota
	// Errno2big Argument list too long.
	Errno2big
	// ErrnoAcces Permission denied.
	ErrnoAcces
	// ErrnoAddrinuse Address in use.
	ErrnoAddrinuse
	// ErrnoAddrnotavail Address not available.
	ErrnoAddrnotavail
	// ErrnoAfnosupport Address family not supported.
	ErrnoAfnosupport
	// ErrnoAgain Resource unavailable, or operation would block.
	ErrnoAgain
	// ErrnoAlready Connection already in progress.
	ErrnoAlready
	// ErrnoBadf Bad file descriptor.
	ErrnoBadf
	// ErrnoBadmsg Bad message.
	ErrnoBadmsg
	// ErrnoBusy Device or resource busy.
	ErrnoBusy
	// ErrnoCanceled Operation canceled.
	ErrnoCanceled
	// ErrnoChild No child processes.
	ErrnoChild
	// ErrnoConnaborted Connection aborted.
	ErrnoConnaborted
	// ErrnoConnrefused Connection refused.
	ErrnoConnrefused
	// ErrnoConnreset Connection reset.
	ErrnoConnreset
	// ErrnoDeadlk Resource deadlock would occur.
	ErrnoDeadlk
	// ErrnoDestaddrreq Destination address required.
	ErrnoDestaddrreq
	// ErrnoDom Mathematics argument out of domain of function.
	ErrnoDom
	// ErrnoDquot Reserved.
	ErrnoDquot
	// ErrnoExist File exists.
	ErrnoExist
	// ErrnoFault Bad address.
	ErrnoFault
	// ErrnoFbig File too large.
	ErrnoFbig
	// ErrnoHostunreach Host is unreachable.
	ErrnoHostunreach
	// ErrnoIdrm Identifier removed.
	ErrnoIdrm
	// ErrnoIlseq Illegal byte sequence.
	ErrnoIlseq
	// ErrnoInprogress Operation in progress.
	ErrnoInprogress
	// ErrnoIntr Interrupted function.
	ErrnoIntr
	// ErrnoInval Invalid argument.
	ErrnoInval
	// ErrnoIo I/O error.
	ErrnoIo
	// ErrnoIsconn Socket is connected.
	ErrnoIsconn
	// ErrnoIsdir Is a directory.
	ErrnoIsdir
	// ErrnoLoop Too many levels of symbolic links.
	ErrnoLoop
	// ErrnoMfile File descriptor value too large.
	ErrnoMfile
	// ErrnoMlink Too many links.
	ErrnoMlink
	// ErrnoMsgsize Message too large.
	ErrnoMsgsize
	// ErrnoMultihop Reserved.
	ErrnoMultihop
	// ErrnoNametoolong Filename too long.
	ErrnoNametoolong
	// ErrnoNetdown Network is down.
	ErrnoNetdown
	// ErrnoNetreset Connection aborted by network.
	ErrnoNetreset
	// ErrnoNetunreach Network unreachable.
	ErrnoNetunreach
	// ErrnoNfile Too many files open in system.
	ErrnoNfile
	// ErrnoNobufs No buffer space available.
	ErrnoNobufs
	// ErrnoNodev No such device.
	ErrnoNodev
	// ErrnoNoent No such file or directory.
	ErrnoNoent
	// ErrnoNoexec Executable file format error.
	ErrnoNoexec
	// ErrnoNolck No locks available.
	ErrnoNolck
	// ErrnoNolink Reserved.
	ErrnoNolink
	// ErrnoNomem Not enough space.
	ErrnoNomem
	// ErrnoNomsg No message of the desired type.
	ErrnoNomsg
	// ErrnoNoprotoopt No message of the desired type.
	ErrnoNoprotoopt
	// ErrnoNospc No space left on device.
	ErrnoNospc
	// ErrnoNosys function not supported.
	ErrnoNosys
	// ErrnoNotconn The socket is not connected.
	ErrnoNotconn
	// ErrnoNotdir Not a directory or a symbolic link to a directory.
	ErrnoNotdir
	// ErrnoNotempty Directory not empty.
	ErrnoNotempty
	// ErrnoNotrecoverable State not recoverable.
	ErrnoNotrecoverable
	// ErrnoNotsock Not a socket.
	ErrnoNotsock
	// ErrnoNotsup Not supported, or operation not supported on socket.
	ErrnoNotsup
	// ErrnoNotty Inappropriate I/O control operation.
	ErrnoNotty
	// ErrnoNxio No such device or address.
	ErrnoNxio
	// ErrnoOverflow Value too large to be stored in data type.
	ErrnoOverflow
	// ErrnoOwnerdead Previous owner died.
	ErrnoOwnerdead
	// ErrnoPerm Operation not permitted.
	ErrnoPerm
	// ErrnoPipe Broken pipe.
	ErrnoPipe
	// ErrnoProto Protocol error.
	ErrnoProto
	// ErrnoProtonosupport Protocol error.
	ErrnoProtonosupport
	// ErrnoPrototype Protocol wrong type for socket.
	ErrnoPrototype
	// ErrnoRange Result too large.
	ErrnoRange
	// ErrnoRofs Read-only file system.
	ErrnoRofs
	// ErrnoSpipe Invalid seek.
	ErrnoSpipe
	// ErrnoSrch No such process.
	ErrnoSrch
	// ErrnoStale Reserved.
	ErrnoStale
	// ErrnoTimedout Connection timed out.
	ErrnoTimedout
	// ErrnoTxtbsy Text file busy.
	ErrnoTxtbsy
	// ErrnoXdev Cross-device link.
	ErrnoXdev
)

Note: Below prefers POSIX symbol names over WASI ones, even if the docs are from WASI. See https://linux.die.net/man/3/errno See https://github.com/WebAssembly/WASI/blob/snapshot-01/phases/snapshot/docs.md#variants-1

type FunctionExporter

type FunctionExporter interface {
	ExportFunctions(wazero.HostModuleBuilder)
}

FunctionExporter exports functions into a wazero.HostModuleBuilder.

func NewFunctionExporter

func NewFunctionExporter() FunctionExporter

NewFunctionExporter returns a new FunctionExporter. This is used for the following two use cases:

• Overriding a builtin function with an alternate implementation.
• Exporting functions to the module "wasi_unstable" for legacy code.

Example of overriding default behavior

// Export the default WASI functions.
wasiBuilder := r.NewHostModuleBuilder(ModuleName)
wasi_snapshot_preview1.NewFunctionExporter().ExportFunctions(wasiBuilder)

// Subsequent calls to NewFunctionBuilder override built-in exports.
wasiBuilder.NewFunctionBuilder().
	WithFunc(func(ctx context.Context, mod api.Module, exitCode uint32) {
	// your custom logic
	}).Export("proc_exit")

Example of using the old module name for WASI

// Instantiate the current WASI functions under the wasi_unstable
// instead of wasi_snapshot_preview1.
wasiBuilder := r.NewHostModuleBuilder("wasi_unstable")
wasi_snapshot_preview1.NewFunctionExporter().ExportFunctions(wasiBuilder)
_, err := wasiBuilder.Instantiate(testCtx, r)