C interop
Call native libraries with an explicit ABI and work with C strings and pointers.
Current support and portability#
The current compiler emits LLVM IR and uses Clang to link calls to native C functions. C interoperability is available in this implementation, but Ocean’s native interfaces are still evolving and are not a stable portability guarantee.
Where practical, prefer an existing Ocean package or implement the functionality in Ocean rather than depending heavily on extern calls. Functionality shared by many programs can be exposed through a standard-library package; platform-specific parts can use inline assembly when needed. If native calls are necessary, keep their declarations together, document the platform and ABI they assume, and test them on each supported target. A platform-specific library implementation can expose an ordinary Ocean API so its callers do not need to repeat those assumptions.
Declare external functions#
Extern declarations use C-style ordering: return type first, then the function name, then type-first parameters. They are file-scoped and called through extern.name. The declaration must match the target’s application binary interface (ABI): the storage widths, argument layout, and calling convention expected by the native function. C int is i32 on the tested host, while Ocean int is i64.
An extern declaration promises that the named symbol exists in the native libraries linked into the program and that its signature matches the target’s native calling conventions. Ocean cannot infer the correct C signature from a symbol name. Check argument widths, pointer types, return types, and the target platform’s conventions when writing the declaration.
Extern declarations intentionally use a different ordering from ordinary Ocean functions. They also have a separate call qualifier, extern, so a native function does not collide with an Ocean function or local variable of the same name. A declaration applies only to its own source file.
extern int write(i32 fd, buffer<i8>[] data, int count);
func main() {
text := "Hello from native code!\n";
extern.write(1, text.data, len(text));
}
This example uses the host’s write function to send a byte count to file descriptor one, standard output. text.data supplies a raw byte buffer, not the header of an Ocean string. The example signature is for the current tested host and should be checked when targeting another native ABI.
Pass C NULL explicitly#
Ocean’s explicit null marker is distinct from a zero-address pointer. When a C API requires NULL, pass zero(*void), or a zero-address pointer of the required type. Do not pass Ocean null as C NULL. Check pointers returned by C with a numeric zero comparison, such as (handle -> int) == 0. This matters for optional native parameters and failed pointer-returning operations.
Strings at a C boundary#
Ocean strings carry a header and have no implicit trailing NUL. Pass .data for a raw buffer. For APIs expecting a C string (char*), append \0 explicitly. A string’s .data argument is an isolated temporary valid only during its enclosing call; create a named mutable i8[] copy for persistent access.
A C API may expect a pointer to bytes terminated by a zero byte, a pointer and explicit length, or writable storage that it retains. Those are different contracts. An Ocean string value does not automatically satisfy all of them merely because it contains text.
For a length-based operation such as write, pass .data together with len(text). For a C-string operation, explicitly provide a terminator, for example "Ocean\0".data. The terminator is part of the string’s bytes, so do not add it blindly when an API already takes an explicit text length.
A string’s temporary .data buffer isolates its immutable contents from writes during the native call. If the API keeps the pointer afterward, a temporary is insufficient. Use a named mutable byte array with a lifetime that covers every native use of that pointer.
Void pointers and casts#
*void holds a native address without specifying the type of object stored there. You cannot dereference it until you cast it to a pointer with a concrete pointee type. Typed pointers convert automatically to *void. Converting back requires an explicit cast; multi-token cast targets are grouped in parentheses.
An untyped pointer is useful for APIs such as malloc that allocate storage without knowing its eventual Ocean type. Before dereferencing that storage, cast the address to a pointer with a concrete pointee type. The grouped target syntax raw -> (*int) makes the compound type part of the cast.
Typed pointers convert to *void automatically when passed to a compatible parameter. The reverse conversion remains explicit because it asserts how the underlying storage will be interpreted. Neither conversion by itself allocates, copies, initializes, or frees an object.
extern *void malloc(uint bytes);
extern void free(*void memory);
func main() {
byteCount := sizeof(int);
raw := extern.malloc(byteCount -> uint);
if (raw == zero(*void)) panic "allocation failed";
value := raw -> (*int);
*value = 42;
extern.free(value);
}
The allocation is checked against a zero-address pointer because this is a C allocation result. The address is then interpreted as integer storage, written, and released with C free. Keep allocation and deallocation APIs matched; this example deliberately uses native allocation rather than Ocean new.
This declaration uses a 64-bit unsigned size_t argument for malloc, as on the tested 64-bit host. The byte count is not a C int; verify the target’s size_t width before reusing the declaration on another platform.