The WebAssembly.customSections()
function returns a copy of the contents of all custom sections in the given module with the given string name.
Syntax
WebAssembly.Module.customSections(module, sectionName);
Parameters
- module
- The
WebAssembly.Module
object whose custom sections are being considered. - sectionName
- The string name of the desired custom section.
Return value
A (possibly empty) array containing ArrayBuffer
copies of the contents of all custom sections matching sectionName
.
Exceptions
If module
is not a WebAssembly.Module
object instance, a TypeError
is thrown.
Description
A wasm module is comprised of a sequence of sections. Most of these sections are fully specified and validated by the wasm spec, but modules can also contain custom sections that are ignored and skipped over during validation. (Read High level structure for information on section structures, and how normal sections ("known sections") and custom sections are distinguished.)
This provides developers with a way to include custom data inside wasm modules for other purposes, for example the name custom section, which allows developers to provide names for all the functions and locals in the module (like "symbols" in a native build).
Note that the WebAssembly text format currently doesn't have a syntax specified for adding new custom sections; you can however add a name section to your wasm during conversion from text format over to .wasm. The wast2wasm command available as part of the wabt tool has a --debug-names
option — specify this during conversion to get a .wasm with a names custom section, for example:
wast2wasm simple-name-section.was -o simple-name-section.wasm --debug-names
Examples
Using customSections
The following example (see the custom-section.html source and live example) compiles the loaded simple-name-section.wasm byte code.
We then do a check using WebAssembly.Module.customSections
, looking to see whether the module instance contains a "name" custom section by checking that its length
is more than 0. Since there is a "name" section in the example, an ArrayBuffer
object is returned.
WebAssembly.compileStreaming(fetch('simple-name-section.wasm')) .then(function(mod) { var nameSections = WebAssembly.Module.customSections(mod, "name"); if (nameSections.length != 0) { console.log("Module contains a name section"); console.log(nameSections[0]); }; });
Specifications
Specification |
---|
WebAssembly JavaScript Interface The definition of 'customSections()' in that specification. |
Browser compatibility
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
customSections | Chrome Full support 57 | Edge Full support 16 | Firefox
Full support
52
| IE No support No | Opera Full support 44 | Safari Full support 11 | WebView Android Full support 57 | Chrome Android Full support 57 | Firefox Android
Full support
52
| Opera Android Full support 43 | Safari iOS Full support 11 | Samsung Internet Android Full support 7.0 | nodejs Full support 8.0.0 |
Legend
- Full support
- Full support
- No support
- No support
- See implementation notes.
- See implementation notes.