package wasi_snapshot_preview1

wazero – github.com/tetratelabs/wazero/wasi_snapshot_preview1 Index | Examples | Files

package wasi_snapshot_preview1

import "github.com/tetratelabs/wazero/wasi_snapshot_preview1"

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.

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

_, _ = Instantiate(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.

Code:play

package main

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

	"github.com/tetratelabs/wazero"
	"github.com/tetratelabs/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, wazero.NewCompileConfig())
	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)
type Builder

func NewBuilder(r wazero.Runtime) Builder

type Errno

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

Closing the wazero.Runtime has the same effect as closing the result.
To instantiate into another wazero.Namespace, use NewBuilder instead.

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.ModuleBuilder.
	Compile(context.Context, wazero.CompileConfig) (wazero.CompiledModule, error)

	// Instantiate instantiates the ModuleName module into the given namespace.
	//
	// Note: This has the same effect as the same function on wazero.ModuleBuilder.
	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
	// ErrnoNotcapable Extension: Capabilities insufficient.
	ErrnoNotcapable
)

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

Source Files ¶

args.go clock.go environ.go errno.go fs.go poll.go proc.go random.go sched.go sock.go wasi.go

Version: v1.0.0-beta1
Published: Aug 30, 2022
Platform: linux/amd64
Imports: 12 packages
Last checked: 1 hour ago –

Tools for package owners.

?	: This menu
/	: Search site
f	: Jump to identifier
g then g	: Go to top of page
g then b	: Go to end of page
G	: Go to end of page
g then i	: Go to index
g then e	: Go to examples