WebAssembly.module.customSections

The customSections() method of the WebAssembly.Module() constructor returns an array containing custom sections available in a given WebAssembly module with a given name.

Syntax

var custSec = WebAssembly.Module.customSections(module, sectionName);

Parameters

module

The WebAssembly.Module object instance you want to return custom sections from.

sectionName

The name you want the returned custom sections to have.

Return value

An array containing ArrayBuffers representing the custom sections of the given module. Each ArrayBuffer contains a copy of the corresponding custom section's data.

Exceptions

If module is not a WebAssembly.Module object instance, a TypeError is thrown.

Custom sections

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

Example

The following example (see the custom-section.html source and live example) compiles and instantiates the loaded simple-name-section.wasm byte code, importing a JavaScript function into the WebAssembly Module in the process. It then exports a function from the module via Instance.exports.

In addition, we 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 this module does contain a name section, the console.log calls are executed, showing that the contents of the returned array is an ArrayBuffer.

var importObject = {
  imports: {
    imported_func: function(arg) {
      console.log(arg);
    }
  }
};

fetch('simple-name-section.wasm').then(function(response) {
  response.arrayBuffer().then(function(bytes) {
    WebAssembly.compile(bytes).then(function(mod) {
      var instance = new WebAssembly.Instance(mod, importObject);
      instance.exports.exported_func();

      if (WebAssembly.Module.customSections(mod, "name").length != 0) {
       console.log("Module contains a name section");
       var nameSections = WebAssembly.Module.customSections(mod, "name");
       console.log(nameSections[0]);
      }
    })
  })
});

Specifications

Specification	Status	Comment
Web Assembly JavaScript API The definition of 'customSections()' in that specification.	Draft	Initial draft definition.

Browser compatibility

[1] Experimental support can be enabled in Chrome 51+ and Opera 38+ by going to chrome://flags and enabling the Experimental WebAssembly flag.

[2] Experimental support can be enabled in Firefox 47+ by enabling the javascript.options.wasm flag in about:config.

See also

• WebAssembly landing page.
• WebAssembly concepts
• Using the WebAssembly JavaScript API