1{ 2 "type": "module", 3 "source": "doc/api/wasi.md", 4 "modules": [ 5 { 6 "textRaw": "WebAssembly System Interface (WASI)", 7 "name": "webassembly_system_interface_(wasi)", 8 "introduced_in": "v12.16.0", 9 "stability": 1, 10 "stabilityText": "Experimental", 11 "desc": "<p><strong>Source Code:</strong> <a href=\"https://github.com/nodejs/node/blob/v14.20.1/lib/wasi.js\">lib/wasi.js</a></p>\n<p>The WASI API provides an implementation of the <a href=\"https://wasi.dev/\">WebAssembly System Interface</a>\nspecification. WASI gives sandboxed WebAssembly applications access to the\nunderlying operating system via a collection of POSIX-like functions.</p>\n<pre><code class=\"language-mjs\">import fs from 'fs';\nimport { WASI } from 'wasi';\n\nconst wasi = new WASI({\n args: process.argv,\n env: process.env,\n preopens: {\n '/sandbox': '/some/real/path/that/wasm/can/access'\n }\n});\nconst importObject = { wasi_snapshot_preview1: wasi.wasiImport };\n\nconst wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm'));\nconst instance = await WebAssembly.instantiate(wasm, importObject);\n\nwasi.start(instance);\n</code></pre>\n<pre><code class=\"language-cjs\">'use strict';\nconst fs = require('fs');\nconst { WASI } = require('wasi');\nconst wasi = new WASI({\n args: process.argv,\n env: process.env,\n preopens: {\n '/sandbox': '/some/real/path/that/wasm/can/access'\n }\n});\nconst importObject = { wasi_snapshot_preview1: wasi.wasiImport };\n\n(async () => {\n const wasm = await WebAssembly.compile(fs.readFileSync('./demo.wasm'));\n const instance = await WebAssembly.instantiate(wasm, importObject);\n\n wasi.start(instance);\n})();\n</code></pre>\n<p>To run the above example, create a new WebAssembly text format file named\n<code>demo.wat</code>:</p>\n<pre><code class=\"language-text\">(module\n ;; Import the required fd_write WASI function which will write the given io vectors to stdout\n ;; The function signature for fd_write is:\n ;; (File Descriptor, *iovs, iovs_len, nwritten) -> Returns number of bytes written\n (import \"wasi_snapshot_preview1\" \"fd_write\" (func $fd_write (param i32 i32 i32 i32) (result i32)))\n\n (memory 1)\n (export \"memory\" (memory 0))\n\n ;; Write 'hello world\\n' to memory at an offset of 8 bytes\n ;; Note the trailing newline which is required for the text to appear\n (data (i32.const 8) \"hello world\\n\")\n\n (func $main (export \"_start\")\n ;; Creating a new io vector within linear memory\n (i32.store (i32.const 0) (i32.const 8)) ;; iov.iov_base - This is a pointer to the start of the 'hello world\\n' string\n (i32.store (i32.const 4) (i32.const 12)) ;; iov.iov_len - The length of the 'hello world\\n' string\n\n (call $fd_write\n (i32.const 1) ;; file_descriptor - 1 for stdout\n (i32.const 0) ;; *iovs - The pointer to the iov array, which is stored at memory location 0\n (i32.const 1) ;; iovs_len - We're printing 1 string stored in an iov - so one.\n (i32.const 20) ;; nwritten - A place in memory to store the number of bytes written\n )\n drop ;; Discard the number of bytes written from the top of the stack\n )\n)\n</code></pre>\n<p>Use <a href=\"https://github.com/WebAssembly/wabt\">wabt</a> to compile <code>.wat</code> to <code>.wasm</code></p>\n<pre><code class=\"language-console\">$ wat2wasm demo.wat\n</code></pre>\n<p>The <code>--experimental-wasi-unstable-preview1</code> and <code>--experimental-wasm-bigint</code>\nCLI arguments are needed for this example to run.</p>", 12 "classes": [ 13 { 14 "textRaw": "Class: `WASI`", 15 "type": "class", 16 "name": "WASI", 17 "meta": { 18 "added": [ 19 "v13.3.0", 20 "v12.16.0" 21 ], 22 "changes": [] 23 }, 24 "desc": "<p>The <code>WASI</code> class provides the WASI system call API and additional convenience\nmethods for working with WASI-based applications. Each <code>WASI</code> instance\nrepresents a distinct sandbox environment. For security purposes, each <code>WASI</code>\ninstance must have its command-line arguments, environment variables, and\nsandbox directory structure configured explicitly.</p>", 25 "methods": [ 26 { 27 "textRaw": "`wasi.start(instance)`", 28 "type": "method", 29 "name": "start", 30 "meta": { 31 "added": [ 32 "v13.3.0", 33 "v12.16.0" 34 ], 35 "changes": [] 36 }, 37 "signatures": [ 38 { 39 "params": [ 40 { 41 "textRaw": "`instance` {WebAssembly.Instance}", 42 "name": "instance", 43 "type": "WebAssembly.Instance" 44 } 45 ] 46 } 47 ], 48 "desc": "<p>Attempt to begin execution of <code>instance</code> as a WASI command by invoking its\n<code>_start()</code> export. If <code>instance</code> does not contain a <code>_start()</code> export, or if\n<code>instance</code> contains an <code>_initialize()</code> export, then an exception is thrown.</p>\n<p><code>start()</code> requires that <code>instance</code> exports a <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory\"><code>WebAssembly.Memory</code></a> named\n<code>memory</code>. If <code>instance</code> does not have a <code>memory</code> export an exception is thrown.</p>\n<p>If <code>start()</code> is called more than once, an exception is thrown.</p>" 49 }, 50 { 51 "textRaw": "`wasi.initialize(instance)`", 52 "type": "method", 53 "name": "initialize", 54 "meta": { 55 "added": [ 56 "v14.6.0" 57 ], 58 "changes": [] 59 }, 60 "signatures": [ 61 { 62 "params": [ 63 { 64 "textRaw": "`instance` {WebAssembly.Instance}", 65 "name": "instance", 66 "type": "WebAssembly.Instance" 67 } 68 ] 69 } 70 ], 71 "desc": "<p>Attempt to initialize <code>instance</code> as a WASI reactor by invoking its\n<code>_initialize()</code> export, if it is present. If <code>instance</code> contains a <code>_start()</code>\nexport, then an exception is thrown.</p>\n<p><code>initialize()</code> requires that <code>instance</code> exports a <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Memory\"><code>WebAssembly.Memory</code></a> named\n<code>memory</code>. If <code>instance</code> does not have a <code>memory</code> export an exception is thrown.</p>\n<p>If <code>initialize()</code> is called more than once, an exception is thrown.</p>" 72 } 73 ], 74 "properties": [ 75 { 76 "textRaw": "`wasiImport` {Object}", 77 "type": "Object", 78 "name": "wasiImport", 79 "meta": { 80 "added": [ 81 "v13.3.0", 82 "v12.16.0" 83 ], 84 "changes": [] 85 }, 86 "desc": "<p><code>wasiImport</code> is an object that implements the WASI system call API. This object\nshould be passed as the <code>wasi_snapshot_preview1</code> import during the instantiation\nof a <a href=\"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance\"><code>WebAssembly.Instance</code></a>.</p>" 87 } 88 ], 89 "signatures": [ 90 { 91 "params": [ 92 { 93 "textRaw": "`options` {Object}", 94 "name": "options", 95 "type": "Object", 96 "options": [ 97 { 98 "textRaw": "`args` {Array} An array of strings that the WebAssembly application will see as command-line arguments. The first argument is the virtual path to the WASI command itself. **Default:** `[]`.", 99 "name": "args", 100 "type": "Array", 101 "default": "`[]`", 102 "desc": "An array of strings that the WebAssembly application will see as command-line arguments. The first argument is the virtual path to the WASI command itself." 103 }, 104 { 105 "textRaw": "`env` {Object} An object similar to `process.env` that the WebAssembly application will see as its environment. **Default:** `{}`.", 106 "name": "env", 107 "type": "Object", 108 "default": "`{}`", 109 "desc": "An object similar to `process.env` that the WebAssembly application will see as its environment." 110 }, 111 { 112 "textRaw": "`preopens` {Object} This object represents the WebAssembly application's sandbox directory structure. The string keys of `preopens` are treated as directories within the sandbox. The corresponding values in `preopens` are the real paths to those directories on the host machine.", 113 "name": "preopens", 114 "type": "Object", 115 "desc": "This object represents the WebAssembly application's sandbox directory structure. The string keys of `preopens` are treated as directories within the sandbox. The corresponding values in `preopens` are the real paths to those directories on the host machine." 116 }, 117 { 118 "textRaw": "`returnOnExit` {boolean} By default, WASI applications terminate the Node.js process via the `__wasi_proc_exit()` function. Setting this option to `true` causes `wasi.start()` to return the exit code rather than terminate the process. **Default:** `false`.", 119 "name": "returnOnExit", 120 "type": "boolean", 121 "default": "`false`", 122 "desc": "By default, WASI applications terminate the Node.js process via the `__wasi_proc_exit()` function. Setting this option to `true` causes `wasi.start()` to return the exit code rather than terminate the process." 123 }, 124 { 125 "textRaw": "`stdin` {integer} The file descriptor used as standard input in the WebAssembly application. **Default:** `0`.", 126 "name": "stdin", 127 "type": "integer", 128 "default": "`0`", 129 "desc": "The file descriptor used as standard input in the WebAssembly application." 130 }, 131 { 132 "textRaw": "`stdout` {integer} The file descriptor used as standard output in the WebAssembly application. **Default:** `1`.", 133 "name": "stdout", 134 "type": "integer", 135 "default": "`1`", 136 "desc": "The file descriptor used as standard output in the WebAssembly application." 137 }, 138 { 139 "textRaw": "`stderr` {integer} The file descriptor used as standard error in the WebAssembly application. **Default:** `2`.", 140 "name": "stderr", 141 "type": "integer", 142 "default": "`2`", 143 "desc": "The file descriptor used as standard error in the WebAssembly application." 144 } 145 ] 146 } 147 ] 148 } 149 ] 150 } 151 ], 152 "type": "module", 153 "displayName": "WebAssembly System Interface (WASI)" 154 } 155 ] 156}