Built-in functions

Functions implemented directly by the Lynxer interpreter. They can be called by their bare name or with a global. prefix (print(...) and global.print(...) are the same call).

Inside a module, global.name(...) always resolves to a core builtin, never to the module's own function of that name — see modules.

Names that Lynxer recognises but does not implement fail with a source-located <name>() is not supported in Lynxer yet. On a Linux/POSIX build the supported families include the ffi*, async*, sound*, filesystem*, process*, networking*, nativeThread*, nativeMutex*, nativeCondition*, nativeSemaphore* and syscall* builtins; the unsupported set is listed under Unsupported names and is defined by unsupportedTable() in lynxer/builtins.cpp. On a build without POSIX support, the filesystem*/process*/networking*/sound* families join the unsupported set. The syscall* family is routed to a generic syscall dispatcher rather than to a per-name handler.

Input, output and conversion

Strings

Bytes

A bytes value is a byte buffer: the binary counterpart to str's text byte string. It renders as <bytes N>. bytesOf and bytesToStr are byte-for-byte, so bytesToStr accepts any buffer (including one that is not valid UTF-8).

bytes + bytes concatenates, and is compares contents. listToBytes / bytesToList are the numeric-list bridge the math module uses — see stdlib/math.

Sequences

Tuples

Notes

• Tuples are immutable; operations like tupleConcat and tupleSlice return a new tuple.
• Use tupleToList() to iterate over a tuple with a for loop or index manually.

Control, runtime and assertions

Ownership and borrowing

The arguments are variable names, not values; see language.

shared <type> name = variable; is the declaration form of varBorrowMutate; the source may still be written while the alias is active.

Bundled files

Available to programs run from a compiled executable; a normal interpreted run returns empty results.

Included files are written to a private temporary directory when the executable starts, and that directory is removed when the process exits.

global setup(){ import("fileIO"); }

global main(){
    list files = bundledFiles();
    println(files);                 // [] in an interpreted run
    if (returnLength(files) > 0) {
        println(global.fileIO.readFile(bundledFile("message.txt")));
    }
}

Native memory

Typed blocks, structs and owned handles

The original used integer addresses instead of pointers; these built-ins are the typed, bounds-checked form. A block remembers an element type and count, a struct remembers its field layout, and an owned handle shares one liveness flag across every copy of the handle value.

A layout is a comma-separated list of type name fields, where the type is one of the lowercase memory types above:

str layout = "int32 id, float64 score";
println(nativeStructSize(layout));                  // 16
println(nativeStructFieldOffset(layout, "score"));  // 8

int record = nativeStructAllocate(layout);
nativeStructSet(record, "id", 7);
nativeStructSet(record, "score", 12.5);
println(nativeStructGet(record, "score"));          // 12.5
memoryFree(record);

Raw addresses and native calls

An address is a Lynxer integer. These built-ins validate a data address against the allocation registry and wrap a raw function address for nativeCall.

nativeCall uses the interpreter's deliberately small integer ABI: only the fixed shapes the runtime supports are accepted, and an unsupported signature is a source-located error. The caller must supply a valid address with a compatible ABI — an invalid address can crash the process.

any lib = ffiLoadLibrary("libc.so.6");
functionAddress strlen = ffiLookup(lib, "strlen");
println(nativeCall(strlen, "uint64(cstring)", ["hello"]));  // 5
ffiCloseLibrary(lib);

Protection, atomics and volatile access

memoryProtect is POSIX-only and fails with a source-located error elsewhere. Making a page read-only or none also affects unrelated bytes that share it, so callers must keep an allocation's pages to themselves.

Every typed read/write validates the address against the allocation registry and checks the access against the allocation's length, so an unknown address, a freed address, and an out-of-bounds access are source-located errors rather than crashes. 64-bit writes preserve the full signed and unsigned range (see types).

Syscalls

Named syscalls are target-gated. A program first declares the operating system and architecture it targets, then reaches every syscall through that architecture's namespace:

global setup(){ syscalls("Linux", "amd64"); }

global main(){
    amd64.syscallRead(fd, buffer, 16);
}

syscalls(...) takes an operating system and an architecture. The OS is Linux (case-insensitive; Windows and macOS are recognised but no host can select them while named syscalls require Linux), and the architecture is amd64 / x86-64 or arm64 / aarch64. Both must name the machine the program runs on, and only one target can be selected at a time: a different target, a second target, or a syscall call before syscalls(...) is a source-located error. An unknown keyword or namespace prefix reports the closest match, e.g. unknown syscall architecture 'amd6'. You meant: amd64?. The old flat syscallRead(...) spelling is gone; it fails with a pointer to the namespaced form. syscalls(global.sys.platform(), global.sys.architecture()) asserts the host.

Syscall calls take integer arguments only (at most six). syscallPollFileDescriptors takes three arguments; syscallPpollFileDescriptors, syscallWaitForEvents and syscallWaitForEventsWithSignalMask take five.

On amd64 the portable syscallPollFileDescriptors / syscallWaitForEvents wrappers use poll/epoll_wait; on aarch64 they use ppoll/epoll_pwait. The explicit ppoll/epoll_pwait wrappers are available on both. A name whose number is missing from the build's headers fails with syscall '<name>' is not available on this architecture instead of dispatching the wrong table.

Every name below is called as <arch>.<name>(...); the full reference, with the Linux syscall each maps to and its arguments, is syscalls.

The io_uring and sandboxing entries are raw passthroughs: build any struct (io_uring params, Landlock rules, struct seccomp_data) in native memory and pass its address. syscallControlSeccomp is unguarded — operation 0 installs SECCOMP_MODE_STRICT and will terminate the process.

lynxer/examples/syscall_extended.lynx and syscall_io_uring.lynx pin the wiring; lowlevel_syscalls.lynx and lowlevel_arch.lynx are architecture agnostic (they carry a __ARCH__ token the test harness fills in), while amd64Syscalls.lynx and arm64Syscalls.lynx cover the poll/epoll split per target.

Managed filesystem

A small handle-based filesystem API, separate from the fileIO, os and path stdlib modules. Handles are non-negative integers; the interpreter owns the descriptor behind one, and an unknown or already-closed handle is a runtime error rather than a silent failure. Failures preserve the operation and the original errno in the message, for example filesystemOpen() failed: [2] No such file or directory. Descriptors a program leaves open are closed when the process exits.

The family is a faithful native implementation, including its error text. One consequence is worth noting: the reference's Number.null is 0, so the operations that yield "no value" (filesystemClose, filesystemRemove, filesystemRename, filesystemLink, filesystemChmod) return 0 rather than Lynxer's own none.

On a host without POSIX open/stat/dirent, the whole family stays in the unsupported set.

Managed processes

A managed subprocess abstraction: each child gets one pipe per standard stream and a handle the program owns. Commands are not shell-parsed — the first argument names an executable and the second is its argv, so shell syntax needs an explicit shell. Closing the handle closes every pipe and terminates a child that is still running.

A child killed by a signal reports the negative signal number, matching POSIX convention. Poll and wait report -1 both for "still running" and for a timeout, which is why the reference pairs a timeout with a following poll.

Unknown, already closed or invalid handles are runtime errors rather than silent failures, as are writes to a stream the program has already closed.

SIGPIPE is ignored for the whole process, as it is in the reference: writing to a pipe whose reader has exited must report EPIPE, not kill the interpreter.

The family is a faithful native implementation, including its error text, and the value-less operations return 0 for the same Number.null reason as the filesystem family.

On a host without POSIX fork/pipe/waitpid, the whole family stays in the unsupported set.

Managed networking

Managed TCP, UDP and Unix-domain sockets. Addresses stay as host/path strings plus an integer port, so no native address structure crosses the API. Sockets are closed explicitly; anything left open is closed when the process exits.

networkingAccept and networkingOpen both allocate handles from the same registry, so handles are not reusable indices into a fixed table.

networkingSend performs a single send, so a short write is possible on a stream socket; the returned count is what actually left. networkingReceive performs a single recv.

The family is a faithful native implementation, including its error text, and the value-less operations return 0 for the same Number.null reason as the filesystem family.

On a host without POSIX sockets, the whole family stays in the unsupported set.

Managed sound

Audio playback for programs that do not want to import a module. These built-ins are a thin layer over the bundled Rust sound stdlib module — the module owns the audio backend (rodio/cpal/symphonia), so there is one audio implementation rather than one per interface, and the interpreter binary keeps no audio dependency. The built-in layer owns its own handle registry: a handle is valid only if soundLoad returned it, and soundRelease invalidates it.

Playback needs an audio device; without one, soundPlay and soundLoop report that playback did not start. Loading, soundStop, soundSetVolume, soundIsPlaying and soundRelease are device-independent.

stdlib/sound.so must be reachable — next to the interpreter, in stdlib/, or under lynxer/stdlib. A compiled executable only carries it if the program also has import("sound"), because bundling follows imports.

Three deliberate constraints, all recorded in limitations: the backend's own failure text is not Arcade's; soundPause/soundResume work, where the reference fails by design; and soundStop works, where the reference's Arcade version has no Player.stop.

Native threads

nativeThreadStart(function, arguments) runs a Lynxer function on a std::thread. The function is named as a value — nativeThreadStart(global.worker, [int 42]) — which is what makes global.<name> resolve to a callable when no variable has that name.

Threads are cooperative. The interpreter evaluates Lynxer code on one thread at a time (a global lock), and a worker takes that lock before calling back in. The lock is released wherever the holding thread blocks or yields: nativeThreadJoin/nativeThreadJoinAll, the blocking synchronization waits below, asyncSleep, asyncPollWait, and nativeThreadYield. Two threads never evaluate at once — that is why no data race is possible — so a CPU-bound worker does not run in parallel; call nativeThreadYield to interleave it with the main body. Programs that leave a thread running have it joined when the program finishes.

Native synchronization

Mutex, condition-variable and semaphore handles coordinate the cooperative nativeThread* workers. Every blocking wait releases the interpreter lock, so another thread can run and release or signal.

lynxer/examples/native_sync.lynx covers the single-threaded surface and lynxer/examples/native_sync_threads.lynx the blocking waits across two threads. Because the model is cooperative, a blocking wait on a resource that no other thread will release deadlocks — the same as the original.

FFI

The ffi* family loads a native shared library and calls a symbol by signature at run time, with no per-call build step. ffiLoadLibrary/ffiLookup/ ffiCloseLibrary use dlopen/dlsym; the call itself is performed by a Rust engine built on libffi and linked into the interpreter as a staticlib (see native-module-abi). Any signature the engine's grammar can parse is callable — not just a fixed set of shapes — so a mixed argument list, a long argument list, or a void return is fine.

The signatures use the same grammar as native modules; see native-module-abi. A void return yields 0. Argument types are checked strictly: an int64 parameter rejects a string, a float64 parameter rejects a string, and a cstring parameter rejects a number. The value parameter accepts supported Lynxer scalars and nested aggregates; see Versioned typed aggregate values. lynxer/examples/builtin_ffi.lynx demonstrates the full round trip (calling strlen and passing a Lynxer function back as a C callback), and lynxer/examples/builtin_ffi_errors.lynx pins the diagnostics.

Explicit native-module handles

nativeModule* loads a shared object through the same lynxer_module_init_v1 ABI as importAs, but exposes the registered table for inspection instead of binding it into a namespace. Use it when a module's names have to be discovered at run time.

A missing library, a shared object without the entry point, a duplicate registration or a non-zero initializer is a source-located native-module lifecycle error. A retained function address fails cleanly after nativeModuleClose instead of calling unmapped code. lynxer/examples/native_module_api.lynx exercises the whole surface.

Async

The async* family runs Lynxer functions as real tasks. asyncRun(function, arguments?) starts the function on a worker thread and returns a task handle; await expr joins a task handle (and passes any other value through); asyncGather(a, b, ...) joins the handles among its arguments and returns the results as a list. Timers, wakeups and file/IO readiness sources are registered on a poll set and awaited with asyncPollWait; asyncPollDispatch awaits them and invokes a Lynxer callback for each ready event. Concurrency is real but subject to the interpreter's global lock, so tasks interleave rather than run in parallel; blocking operations release the lock. See async.

See lynxer/examples/builtin_async.lynx for a runnable example, and language for the async/await syntax.

Unsupported names

Names Lynxer recognises but does not implement on Linux/POSIX. Each fails with <name>() is not supported in Lynxer yet, except embedPy, whose message is Python bridging (embedPy) is not supported in Lynxer.

The authoritative list is unsupportedTable() in lynxer/builtins.cpp; this table is the POSIX-visible subset. A build without POSIX support adds the filesystem*, process*, networking*, sound*, async* and nativeThread* families. See limitations for the rationale.

sound*, ffi*, async*, nativeThread* and the native-synchronization family are the families that reach outside the interpreter (a device, a shared library, a runtime, or a worker thread); everything else on this page is self-contained.