preamble.js

The JavaScript APIs in preamble.js provide programmatic access for interacting with the compiled C code, including: calling compiled C functions, accessing memory, converting pointers to JavaScript Strings and Strings to pointers (with different encodings/formats), and other convenience functions.

We call this “preamble.js” because Emscripten’s output JS, at a high level, contains the preamble (from src/preamble.js), then the compiled code, then the postamble. (In slightly more detail, the preamble contains utility functions and setup, while the postamble connects things and handles running the application.)

The preamble code is included in the output JS, which is then optimized all together by the compiler, together with any --pre-js and --post-js files you added and code from any JavaScript libraries (--js-library). That means that you can call methods from the preamble directly, and the compiler will see that you need them, and not remove them as being unused.

If you want to call preamble methods from somewhere the compiler can’t see, like another script tag on the HTML, you need to export them. To do so, add them to EXTRA_EXPORTED_RUNTIME_METHODS (for example, -s 'EXTRA_EXPORTED_RUNTIME_METHODS=["ccall", "cwrap"]' will export call and cwrap). Once exported, you can access them on the Module object (as Module.ccall, for example).

Note

If you try to use Module.ccall or another runtime method without exporting it, you will get an error. In a build with -s ASSERTIONS=1, the compiler emits code to show you a useful error message, which will explain that you need to export it. In general, if you see something odd, it’s useful to build with assertions.

Calling compiled C functions from JavaScript

ccall(ident, returnType, argTypes, args, opts)

Call a compiled C function from JavaScript.

The function executes a compiled C function from JavaScript and returns the result. C++ name mangling means that “normal” C++ functions cannot be called; the function must either be defined in a .c file or be a C++ function defined with extern "C".

returnType and argTypes let you specify the types of parameters and the return value. The possible types are "number", "string" or "array", which correspond to the appropriate JavaScript types. Use "number" for any numeric type or C pointer, string for C char* that represent strings, and "array" for JavaScript arrays and typed arrays; for typed arrays, it must be a Uint8Array or Int8Array.

// Call C from JavaScript
var result = Module.ccall('c_add', // name of C function
        'number', // return type
        ['number', 'number'], // argument types
        [10, 20]); // arguments

// result is 30

Note

  • ccall uses the C stack for temporary values. If you pass a string then it is only “alive” until the call is complete. If the code being called saves the pointer to be used later, it may point to invalid data.

  • If you need a string to live forever, you can create it, for example, using _malloc and stringToUTF8(). However, you must later delete it manually!

  • LLVM optimizations can inline and remove functions, after which you will not be able to call them. Similarly, function names minified by the Closure Compiler are inaccessible. In either case, the solution is to add the functions to the EXPORTED_FUNCTIONS list when you invoke emcc :

    -s EXPORTED_FUNCTIONS="['_main', '_myfunc']"
    

    Exported functions can be called as normal:

    a_result = Module.ccall('myfunc', 'number', ['number'], [10])
    
Arguments:
  • ident – The name of the C function to be called.
  • returnType – The return type of the function. Note that array is not supported as there is no way for us to know the length of the array. For a void function this can be null (note: the JavaScript null value, not a string containing the word “null”).

Note

64-bit integers become two 32-bit parameters, for the low and high bits (since 64-bit integers cannot be represented in JavaScript numbers).

Arguments:
  • argTypes – An array of the types of arguments for the function (if there are no arguments, this can be omitted).
  • args – An array of the arguments to the function, as native JavaScript values (as in returnType). Note that string arguments will be stored on the stack (the JavaScript string will become a C string on the stack).
Returns:

The result of the function call as a native JavaScript value (as in returnType).

Opts:

An optional options object. It can contain the following properties:

  • async: Implies that the ccall will perform an async operation. This assumes you are using the Emterpreter-Async option for your code. When using this option, the ccalled function cannot return a value (it can’t be received synchronously anyhow).
cwrap(ident, returnType, argTypes)

Returns a native JavaScript wrapper for a C function.

This is similar to ccall(), but returns a JavaScript function that can be reused as many time as needed. The C function can be defined in a C file, or be a C-compatible C++ function defined using extern "C" (to prevent name mangling).

// Call C from JavaScript
var c_javascript_add = Module.cwrap('c_add', // name of C function
        'number', // return type
        ['number', 'number']); // argument types

// Call c_javascript_add normally
console.log(c_javascript_add(10, 20)); // 30
console.log(c_javascript_add(20, 30)); // 50

Note

  • cwrap uses the C stack for temporary values. If you pass a string then it is only “alive” until the call is complete. If the code being called saves the pointer to be used later, it may point to invalid data. If you need a string to live forever, you can create it, for example, using _malloc and stringToUTF8(). However, you must later delete it manually!

  • LLVM optimizations can inline and remove functions, after which you will not be able to “wrap” them. Similarly, function names minified by the Closure Compiler are inaccessible. In either case, the solution is to add the functions to the EXPORTED_FUNCTIONS list when you invoke emcc :

  • cwrap does not actually call compiled code (only calling the wrapper it returns does that). That means that it is safe to call cwrap early, before the runtime is fully initialized (but calling the returned wrapped function must wait for the runtime, of course, like calling compiled code in general).

    -s EXPORTED_FUNCTIONS="['_main', '_myfunc']"
    

    Exported functions can be called as normal:

    my_func = Module.cwrap('myfunc', 'number', ['number'])
    my_func(12)
    
Arguments:
  • ident – The name of the C function to be called.
  • returnType – The return type of the function. This can be "number", "string" or "array", which correspond to the appropriate JavaScript types (use "number" for any C pointer, and "array" for JavaScript arrays and typed arrays; note that arrays are 8-bit), or for a void function it can be null (note: the JavaScript null value, not a string containing the word “null”).
  • argTypes – An array of the types of arguments for the function (if there are no arguments, this can be omitted). Types are as in returnType, except that array is not supported as there is no way for us to know the length of the array).
Returns:

A JavaScript function that can be used for running the C function.

Accessing memory

setValue(ptr, value, type[, noSafe])

Sets a value at a specific memory address at run-time.

Note

  • setValue() and getValue() only do aligned writes and reads.
  • The type is an LLVM IR type (one of i8, i16, i32, i64, float, double, or a pointer type like i8* or just *), not JavaScript types as used in ccall() or cwrap(). This is a lower-level operation, and we do need to care what specific type is being used.
Arguments:
  • ptr – A pointer (number) representing the memory address.
  • value – The value to be stored
  • type – An LLVM IR type as a string (see “note” above).
  • noSafe (bool) – Developers should ignore this variable. It is only used in SAFE_HEAP compilation mode, where it can help avoid infinite recursion in some specialist use cases.
getValue(ptr, type[, noSafe])

Gets a value at a specific memory address at run-time.

Note

  • setValue() and getValue() only do aligned writes and reads!
  • The type is an LLVM IR type (one of i8, i16, i32, i64, float, double, or a pointer type like i8* or just *), not JavaScript types as used in ccall() or cwrap(). This is a lower-level operation, and we do need to care what specific type is being used.
Arguments:
  • ptr – A pointer (number) representing the memory address.
  • type – An LLVM IR type as a string (see “note” above).
  • noSafe (bool) – Developers should ignore this variable. It is only used in SAFE_HEAP compilation mode, where it can help avoid infinite recursion in some specialist use cases.
Returns:

The value stored at the specified memory address.

Conversion functions — strings, pointers and arrays

Pointer_stringify(ptr[, length])

Returns a JavaScript String from a pointer, for use in compiled code.

Arguments:
  • ptr – The pointer to be converted to a String.
  • length – The length of the data in the pointer (optional).
Returns:

A JavaScript String containing the data from ptr.

Return type:

String

UTF8ToString(ptr)

Given a pointer ptr to a null-terminated UTF8-encoded string in the Emscripten HEAP, returns a copy of that string as a JavaScript String object.

Arguments:
  • ptr – A pointer to a null-terminated UTF8-encoded string in the Emscripten HEAP.
Returns:

A JavaScript String object

stringToUTF8(str, outPtr, maxBytesToWrite)

Copies the given JavaScript String object str to the Emscripten HEAP at address outPtr, null-terminated and encoded in UTF8 form.

The copy will require at most str.length*4+1 bytes of space in the HEAP. You can use the function lengthBytesUTF8() to compute the exact amount of bytes (excluding the null terminator) needed to encode the string.

Arguments:
  • str (String) – A JavaScript String object.
  • outPtr – Pointer to data copied from str, encoded in UTF8 format and null-terminated.
  • maxBytesToWrite – A limit on the number of bytes that this function can at most write out. If the string is longer than this, the output is truncated. The outputted string will always be null terminated, even if truncation occurred, as long as maxBytesToWrite > 0.
UTF16ToString(ptr)

Given a pointer ptr to a null-terminated UTF16LE-encoded string in the Emscripten HEAP, returns a copy of that string as a JavaScript String object.

Arguments:
  • ptr – A pointer to a null-terminated UTF16LE-encoded string in the Emscripten HEAP.
Returns:

A JavaScript String object

stringToUTF16(str, outPtr, maxBytesToWrite)

Copies the given JavaScript String object str to the Emscripten HEAP at address outPtr, null-terminated and encoded in UTF16LE form.

The copy will require exactly (str.length+1)*2 bytes of space in the HEAP.

Arguments:
  • str (String) – A JavaScript String object.
  • outPtr – Pointer to data copied from str, encoded in UTF16LE format and null-terminated.
  • maxBytesToWrite – A limit on the number of bytes that this function can at most write out. If the string is longer than this, the output is truncated. The outputted string will always be null terminated, even if truncation occurred, as long as maxBytesToWrite >= 2 so that there is space for the null terminator.
UTF32ToString(ptr)

Given a pointer ptr to a null-terminated UTF32LE-encoded string in the Emscripten HEAP, returns a copy of that string as a JavaScript String object.

Arguments:
  • ptr – A pointer to a null-terminated UTF32LE-encoded string in the Emscripten HEAP.
Returns:

A JavaScript String object.

stringToUTF32(str, outPtr, maxBytesToWrite)

Copies the given JavaScript String object str to the Emscripten HEAP at address outPtr, null-terminated and encoded in UTF32LE form.

The copy will require at most (str.length+1)*4 bytes of space in the HEAP, but can use less, since str.length does not return the number of characters in the string, but the number of UTF-16 code units in the string. You can use the function lengthBytesUTF32() to compute the exact amount of bytes (excluding the null terminator) needed to encode the string.

Arguments:
  • str (String) – A JavaScript String object.
  • outPtr – Pointer to data copied from str, encoded in encoded in UTF32LE format and null-terminated.
  • maxBytesToWrite – A limit on the number of bytes that this function can at most write out. If the string is longer than this, the output is truncated. The outputted string will always be null terminated, even if truncation occurred, as long as maxBytesToWrite >= 4` so that there is space for the null terminator.
intArrayFromString(stringy, dontAddNull[, length])

This converts a JavaScript string into a C-line array of numbers, 0-terminated.

Arguments:
  • stringy (String) – The string to be converted.
  • dontAddNull (bool) – If true, the new array is not zero-terminated.
  • length – The length of the array (optional).
Returns:

The array created from stringy.

intArrayToString(array)

This creates a JavaScript string from a zero-terminated C-line array of numbers.

Arguments:
  • array – The array to convert.
Returns:

A String, containing the content of array.

writeStringToMemory(string, buffer, dontAddNull)

Writes a JavaScript string to a specified address in the heap.

Warning

This function is deprecated, you should call the function stringToUTF8 instead, which provides a secure bounded version of the same functionality instead.

// Allocate space for string and extra '0' at the end
var buffer = Module._malloc(myString.length+1);

// Write the string to memory
Module.writeStringToMemory(myString, buffer);

// We can now send buffer into a C function, it is just a normal char* pointer
Arguments:
  • string (String) – The string to write into memory.
  • buffer (Number) – The address (number) where string is to be written.
  • dontAddNull (bool) – If true, the new array is not zero-terminated.
writeArrayToMemory(array, buffer)

Writes an array to a specified address in the heap. Note that memory should to be allocated for the array before it is written.

Arguments:
  • array – The array to write to memory.
  • buffer (Number) – The address (number) where array is to be written.
writeAsciiToMemory(str, buffer, dontAddNull)

Writes an ASCII string to a specified address in the heap. Note that memory should to be allocated for the string before it is written.

The string is assumed to only have characters in the ASCII character set. If ASSERTIONS are enabled and this is not the case, it will fail.

// Allocate space for string
var buffer = Module._malloc(myString.length);

// Write the string to memory
Module.writeStringToMemory(myString, buffer);
Arguments:
  • string – The string to write into memory.
  • buffer – The address where string is to be written.
  • dontAddNull (bool) – If true, the new string is not zero-terminated.

Run dependencies

Note that generally run dependencies are managed by the file packager and other parts of the system. It is rare for developers to use this API directly.

addRunDependency(id)

Adds an id to the list of run dependencies.

This adds a run dependency and increments the run dependency counter.

Arguments:
  • id (String) – An arbitrary id representing the operation.
removeRunDependency(id)

Removes a specified id from the list of run dependencies.

Arguments:
  • id (String) – The identifier for the specific dependency to be removed (added with addRunDependency())

Stack trace

stackTrace()

Returns the current stack track.

Note

The stack trace is not available at least on IE10 and Safari 6.

Returns:The current stack trace, if available.

Type accessors for the memory model

The Emscripten memory representation uses a typed array buffer (ArrayBuffer) to represent memory, with different views into it giving access to the different types. The views for accessing different types of memory are listed below.

HEAP8

View for 8-bit signed memory.

HEAP16

View for 16-bit signed memory.

HEAP32

View for 32-bit signed memory.

HEAPU8

View for 8-bit unsigned memory.

HEAPU16

View for 16-bit unsigned memory.

HEAPU32

View for 32-bit unsigned memory.

HEAPF32

View for 32-bit float memory.

HEAPF64

View for 64-bit float memory.