std/clib

Standard Library documentation

Dynamic C library loading and scalar FFI calls.

Back to Stdlib View Source

Module

Name
std/clib
Area
Standard Library
Source
modules/std/clib.zzm

NAME

std/clib - Dynamic C library loading and scalar FFI calls.

SYNOPSIS

  from std/clib import CLib;

  let lib := CLib.open("t/fixtures/example_clib/libgreet.so");
  let greet := lib.func(
    "greet",
    [],
    {
      type: "binary",
      terminated_by: "nul",
      free: "greet_free"
    }
  );

  say to_string(greet.call());

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is not supported by zuzu-js in the browser.

DESCRIPTION

This runtime-supported module loads C dynamic libraries and calls exported C functions through explicitly declared signatures.

The first implementation supports null, booleans, 64-bit integers, 64-bit floats, and BinaryString byte buffers. Other data types are out of scope.

The runtime copies returned binary data before returning it to ZuzuScript. If a return descriptor includes free, that symbol is called after the copy so libraries can return owned memory safely.

On Unix-like systems, dynamic libraries usually use .so on Linux and .dylib on macOS. Windows libraries usually use .dll. Exact availability depends on the host runtime. Browser runtimes reject this module as unsupported.

EXPORTS

Classes

  • CLib

    Static methods:

    • CLib.open(String path)

      Parameters: path is a dynamic library path. Returns: CLibrary. Loads a dynamic library.

  • CLibrary

    Methods:

    • func(String name, Array params, return_type, options?)

      Parameters: name is a symbol name, params describes parameter types, return_type describes the return type, and options is optional. Returns: CFunction. Looks up a symbol and returns a callable C function wrapper.

    • has_symbol(String name)

      Parameters: name is a symbol name. Returns: Boolean. Returns whether the loaded library exports the named symbol.

    • close()

      Parameters: none. Returns: null. Invalidates the library and functions created from it.

  • CFunction

    Methods:

    • call(...)

      Parameters: arguments must match the declared C signature. Returns: value. Calls the C function using the declared signature.

COPYRIGHT AND LICENCE

std/clib is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.