Calling C Shared Libraries from Dyalog APL with ⎕NA

Calling a C function from Dyalog APL

You can make a function from a C shared library available as an APL name using the system function ⎕NA. Once bound, the APL argument is automatically converted to the specified C type, the C routine executes, and its result is converted back to an APL array.

Worked example: a simple “twice” function

Create a C source file named example.c:

/* example.c */
double twice(double x) { return 2.0 * x; }

Compile it to a shared library (Linux example):

gcc -shared -fPIC -o libexample.so example.c

Start a Dyalog APL session and bind the function:

twice←⎕NA './libexample.so' 'twice' double double

Call the bound name with an APL argument:

twice 3

The expected result is the numeric array 6 (the APL interpreter converts the argument to a C double, the C function returns 2.0 * 3.0 = 6.0, and the result is converted back to an APL double scalar).

How ⎕NA works

When ⎕NA is evaluated, Dyalog loads the specified shared library into the APL process address space, looks up the symbol matching the given function name, and creates an internal call‑wrapper that knows the requested return type and argument types. Each time the APL name is invoked, the wrapper converts the APL arguments according to the type list, invokes the C function using the platform’s calling convention, and converts the returned value (if any) back to an APL array.

Limits and common mistakes

• ABI compatibility: The shared library must be built for the same bitness (32‑bit vs 64‑bit) and use the same calling convention as the APL interpreter. Mixing, for example, a 32‑bit library with a 64‑bit Dyalog process will cause a load failure.
• Type signature mismatch: If the APL‑specified return or argument types do not match the actual C function signature, APL may raise a DOMAIN ERROR or, worse, silently produce incorrect results because the bit patterns are interpreted incorrectly.
• Memory management: APL does not automatically free memory that the C function allocates and returns as a pointer. The caller (the C code) must manage such memory, or you must provide a companion C routine to release it.
• Supported data kinds: ⎕NA directly supports scalar numeric types (int8, int16, int32, int64, float, double) and raw pointers for strings or structures. Passing complex APL arrays (nested, heterogeneous) requires manual marshalling.

Verification and practical checks

1. Compile the C source as shown above to produce libexample.so (Linux) or example.dll (Windows).
2. In Dyalog APL, bind the function with the exact library path, symbol name, return type, and argument types.
3. Invoke the bound name with a known input (e.g., twice 3) and compare the result to the expected value (6).
4. To confirm that type checking is active, deliberately alter the APL signature—for instance, specify int32 for the argument while the C function expects a double—and observe a DOMAIN ERROR.