Named syscalls

Lynxer exposes one named built-in per Linux syscall. They are raw ABI calls: argument layouts, flags, structures and pointer lifetimes are the caller's responsibility. Every wrapper is target-gated and reached through the architecture's namespace.

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

global main(){
    println(amd64.syscallGetProcessId());
    println(amd64.syscallYieldProcessor());
}

Selecting an operating system and architecture

syscalls("<os>", "<arch>") must run before any syscall call; it declares which operating system and architecture the program targets.

• Both keywords must name the host. syscalls("Linux", "arm64") on an amd64 machine is an error, not a cross-target dispatch, and so are syscalls("Linux", "amd64") on a non-Linux host and syscalls("winAPI", "amd64") on a non-Windows host.
• Matching is case-insensitive, and winAPI/windows/win32 are synonyms, so syscalls(global.sys.platform(), global.sys.architecture()) asserts the host (see stdlib/sys); sys.platform() returns win32 on Windows.
• Only one target at a time may be selected; re-selecting the same one is a no-op, a different one is an error.
• A misspelled keyword or namespace prefix reports the closest match, e.g. unknown syscall architecture 'amd6'. You meant: amd64?.
• The former flat syscallRead(...) spelling is gone; it fails with a pointer to the namespaced form.

Calls then use the matching namespace — amd64.syscallRead(...) or arm64.syscallRead(...). A call through the wrong namespace is an error.

Windows API calls

Selecting the Windows target (winAPI, windows or win32) is only possible on a Windows host. It makes the winAPI.* namespace available — the Win32 calls a program needs, in the camelCase Win32 naming:

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

global main(){
    println(winAPI.getProcessId());
    println(winAPI.getCurrentDirectory());
    println(winAPI.getComputerName());
}

Files and handles. A handle is an integer (-1 on failure) and must be closed with closeHandle; the file calls use the same scalar-sentinel convention as the rest of the stdlib, with getLastError() for the reason:

Beyond files, the surface also covers process control (getCurrentThreadId, openProcess, terminateProcess, getExitCodeProcess, createProcess, waitForSingleObject), the console session (getStdHandle, getConsoleMode, setConsoleMode, setConsoleTitle, getConsoleOutputCP, setConsoleOutputCP), file attributes and paths (getFileAttributes, setFileAttributes, getFullPathName, flushFileBuffers) and the high-resolution timer (queryPerformanceCounter, queryPerformanceFrequency). The full reference is windows-api.

Most calls are kernel32; getKnownFolderPath uses shell32/ole32. The long tail — other DLLs, user32, advapi32, *A/*W pairs, structs — is reachable today through ffiLoadLibrary/ffiLookup/ffiCall with a cdecl: signature (see native-modules); a curated wrapper for it may come later.

The namespace prefix is matched case-insensitively, an unknown function reports the closest match, and a winAPI.* call made before the selection (or after selecting another target) is a source-located error. Win32 handles, *W/*A pairs and struct layouts are not exposed yet; see windows and the tracker in ../todo.

For a complete reference, see windows-api.

Calling convention

• Arguments are positional integers, zero to six of them.
• Pointer arguments must be native addresses, such as those returned by memoryAllocate; strings and structures are prepared in native memory first.
• The result is the syscall's return value as an integer. A result of -1 is raised as a source-located error carrying the Linux errno message, e.g. syscall 'syscallRead' failed: Bad file descriptor.
• These wrappers require a Linux runtime. 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.

Portable poll/epoll

poll(2) and epoll_wait(2) do not exist on AArch64, so the two portable wrappers dispatch to whichever the host has, while the explicit ppoll / epoll_pwait forms are available on both architectures:

Working directories

File descriptors and files

Directory entries, links, ownership, and permissions

Memory and program execution

Processes and threads

Clocks, sleep, and randomness

Signals

Sockets

Polling and event loops

System information and resources

Async I/O (io_uring)

Raw passthrough; build the io_uring_params and submission structures in native memory and pass their addresses. Available on both architectures.

Sandboxing (Landlock and seccomp)

Raw passthrough. The seccomp syscall is unguarded: operation 0 installs SECCOMP_MODE_STRICT, which terminates a process that issues anything outside its tiny allowlist.

Fixtures

• lynxer/examples/lowlevel_syscalls.lynx, lowlevel_arch.lynx, syscall_extended.lynx and syscall_io_uring.lynx are architecture-agnostic: they carry a __ARCH__ token that the test harness fills in (SYSCALL_ARCH, from uname -m).
• lynxer/examples/amd64Syscalls.lynx and arm64Syscalls.lynx are pinned to one target and run under make testLynxerAmd64Syscalls / make testLynxerArm64Syscalls.

See also

• builtins — the summary table and the gate rules.
• stdlib/sys — global.sys.architecture(), the keyword to pass.
• legacy-surface — how the original flat naming maps onto the namespaced form.
• builtins — the memoryAllocate / memoryWrite* builtins used to prepare buffers and structures for these calls.