Skip to main content

​
Creating C Functions

C functions can be exposed to JavaScript using QuickJS’s function creation APIs.

​
JS_NewCFunction

Create a simple JavaScript function backed by C code. 
static inline JSValue JS_NewCFunction(JSContext *ctx, JSCFunction *func,
                                      const char *name, int length)

​
Parameters

  • ctx - The JavaScript context
  • func - Pointer to the C function implementation
  • name - Name of the function as it appears in JavaScript
  • length - The length property of the function (expected argument count)

​
Returns

Returns a new JavaScript function object.

​
C Function Signature

typedef JSValue JSCFunction(JSContext *ctx, JSValueConst this_val,
                            int argc, JSValueConst *argv);

​
Example

From examples/fib.c: 
static JSValue js_fib(JSContext *ctx, JSValue this_val,
                      int argc, JSValue *argv)
{
    int n, res;
    if (JS_ToInt32(ctx, &n, argv[0]))
        return JS_EXCEPTION;
    res = fib(n);
    return JS_NewInt32(ctx, res);
}

// Create the function
JSValue fib_func = JS_NewCFunction(ctx, js_fib, "fib", 1);
JS_SetPropertyStr(ctx, global_obj, "fib", fib_func);

​
JS_NewCFunction2

Create a JavaScript function with more control over its type and behavior. 
JSValue JS_NewCFunction2(JSContext *ctx, JSCFunction *func,
                         const char *name,
                         int length, JSCFunctionEnum cproto, int magic);

​
Parameters

  • ctx - The JavaScript context
  • func - Pointer to the C function
  • name - Function name
  • length - The length property
  • cproto - Function type (constructor, getter, setter, etc.)
  • magic - Magic value passed to the function

​
Function Types

typedef enum JSCFunctionEnum {
    JS_CFUNC_generic,
    JS_CFUNC_generic_magic,
    JS_CFUNC_constructor,
    JS_CFUNC_constructor_magic,
    JS_CFUNC_constructor_or_func,
    JS_CFUNC_constructor_or_func_magic,
    JS_CFUNC_f_f,
    JS_CFUNC_f_f_f,
    JS_CFUNC_getter,
    JS_CFUNC_setter,
    JS_CFUNC_getter_magic,
    JS_CFUNC_setter_magic,
    JS_CFUNC_iterator_next,
} JSCFunctionEnum;

​
Example

JSValue ctor = JS_NewCFunction2(ctx, js_point_ctor, "Point", 2,
                                JS_CFUNC_constructor, 0);

​
JS_SetPropertyFunctionList

Convenience function to add multiple functions to an object at once. 
int JS_SetPropertyFunctionList(JSContext *ctx, JSValueConst obj,
                               const JSCFunctionListEntry *tab,
                               int len);

​
Parameters

  • ctx - The JavaScript context
  • obj - The object to add properties to
  • tab - Array of function list entries
  • len - Number of entries in the array

​
Returns

Returns 0 on success, -1 on error.

​
Example

From examples/fib.c: 
static const JSCFunctionListEntry js_fib_funcs[] = {
    JS_CFUNC_DEF("fib", 1, js_fib),
};

JS_SetPropertyFunctionList(ctx, global_obj, js_fib_funcs,
                          countof(js_fib_funcs));
From examples/point.c: 
static const JSCFunctionListEntry js_point_proto_funcs[] = {
    JS_CGETSET_MAGIC_DEF("x", js_point_get_xy, js_point_set_xy, 0),
    JS_CGETSET_MAGIC_DEF("y", js_point_get_xy, js_point_set_xy, 1),
    JS_CFUNC_DEF("norm", 0, js_point_norm),
};

JSValue point_proto = JS_NewObject(ctx);
JS_SetPropertyFunctionList(ctx, point_proto, js_point_proto_funcs,
                          countof(js_point_proto_funcs));

​
Helper Macros

​
JS_CFUNC_DEF

Define a regular function. 
#define JS_CFUNC_DEF(name, length, func1)

​
JS_CGETSET_MAGIC_DEF

Define a getter/setter pair with a magic value. 
#define JS_CGETSET_MAGIC_DEF(name, fgetter, fsetter, magic)

​
JS_CFUNC_MAGIC_DEF

Define a function with a magic value. 
#define JS_CFUNC_MAGIC_DEF(name, length, func1, magic)

​
Notes

  • C functions receive constant JSValueConst parameters (they don’t need to free them)
  • C functions must return a newly allocated JSValue
  • Always return JS_EXCEPTION on error after setting an exception with JS_Throw* functions
  • There is no implicit stack - parameters are passed as normal C function arguments

Build docs developers (and LLMs) love

Get started for freeTalk to us