jerryscript/10.EXT-REFERENCE-HANDLER.md

---
layout: page
title: 'Extension API: External Function Handlers'
category: documents
permalink: /ext-reference-handler/
---

* toc
{:toc}

#  Common external function handlers

## jerryx_handler_assert_fatal

**Summary**

Hard assert for scripts. The routine calls `jerry_port_fatal` on assertion failure.

**Prototype**

```c
jerry_value_t
jerryx_handler_assert_fatal (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                             const jerry_value_t args_p[], const jerry_length_t args_cnt);
```

- `func_obj_val` - the function object that was called (unused).
- `this_p` - the `this` value of the call (unused).
- `args_p` - the array of function arguments.
- `args_cnt` - the number of function arguments.
- return value - `jerry_value_t` representing boolean true, if only one argument
  was passed and that argument was a boolean true. Note that the function does
  not return otherwise.

**See also**

- [jerryx_handler_register_global](#jerryx_handler_register_global)


## jerryx_handler_assert_throw

**Summary**

Soft assert for scripts. The routine throws an error on assertion failure.

**Prototype**

```c
jerry_value_t
jerryx_handler_assert_throw (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                             const jerry_value_t args_p[], const jerry_length_t args_cnt);
```

- `func_obj_val` - the function object that was called (unused).
- `this_p` - the `this` value of the call (unused).
- `args_p` - the array of function arguments.
- `args_cnt` - the number of function arguments.
- return value - `jerry_value_t` representing boolean true, if only one argument
  was passed and that argument was a boolean true, an error otherwise.

**See also**

- [jerryx_handler_register_global](#jerryx_handler_register_global)


## jerryx_handler_assert

**Summary**

An alias to `jerryx_handler_assert_fatal`.

**See also**

- [jerryx_handler_assert_fatal](#jerryx_handler_assert_fatal)


## jerryx_handler_gc

**Summary**

Expose garbage collector to scripts. If the first argument of the function
is logical true, it performs a high severity gc. Otherwise a low severity
gc is performed, which is also the default if no parameters passed.

**Prototype**

```c
jerry_value_t
jerryx_handler_gc (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                   const jerry_value_t args_p[], const jerry_length_t args_cnt);
```

- `func_obj_val` - the function object that was called (unused).
- `this_p` - the `this` value of the call (unused).
- `args_p` - the array of function arguments (unused).
- `args_cnt` - the number of function arguments (unused).
- return value - `jerry_value_t` representing `undefined`.

**See also**

- [jerryx_handler_register_global](#jerryx_handler_register_global)


## jerryx_handler_print

**Summary**

Provide a `print` implementation for scripts. The routine converts all of its
arguments to strings and outputs them char-by-char using
`jerry_port_print_char`. The NUL character is output as "\u0000",
other characters are output bytewise.

*Note*: This implementation does not use standard C `printf` to print its
output. This allows more flexibility but also extends the core JerryScript
engine port API. Applications that want to use `jerryx_handler_print` must
ensure that their port implementation also provides
`jerry_port_print_char`.

**Prototype**

```c
jerry_value_t
jerryx_handler_print (const jerry_value_t func_obj_val, const jerry_value_t this_p,
                      const jerry_value_t args_p[], const jerry_length_t args_cnt);
```

- `func_obj_val` - the function object that was called (unused).
- `this_p` - the `this` value of the call (unused).
- `args_p` - the array of function arguments.
- `args_cnt` - the number of function arguments.
- return value - `jerry_value_t` representing `undefined` if all arguments could
  be converted to strings, an `Error` otherwise.

**See also**

- [jerryx_handler_register_global](#jerryx_handler_register_global)
- [jerry_port_print_char](05.PORT-API.md#jerry_port_print_char)


# Handler registration helper

## jerryx_handler_register_global

**Summary**

Register a JavaScript function in the global object.

*Note*: Returned value must be freed with `jerry_release_value`, when it is no
longer needed.

**Prototype**

```c
jerry_value_t
jerryx_handler_register_global (const jerry_char_t *name_p,
                                jerry_external_handler_t handler_p);
```

- `name_p` - the name of the function to be registered.
- `handler_p` - the address of the external function handler.
- return value - `jerry_value_t` representing boolean true, if the operation was
  successful, an `Error` otherwise.

**Example**

[doctest]: # (test="compile")

```c
#include "jerryscript.h"
#include "jerryscript-ext/handler.h"

static const struct {
  const char *name_p;
  jerry_external_handler_t handler_p;
} common_functions[] =
{
  { "assert", jerryx_handler_assert },
  { "gc", jerryx_handler_gc },
  { "print", jerryx_handler_print },
  { NULL, NULL }
};

static void
register_common_functions (void)
{
  jerry_value_t ret = jerry_create_undefined ();

  for (int i = 0; common_functions[i].name_p != NULL && !jerry_value_is_error (ret); i++)
  {
    ret = jerryx_handler_register_global ((const jerry_char_t *) common_functions[i].name_p,
                                          common_functions[i].handler_p);
  }

  jerry_release_value (ret);
}
```