Lyx – Foreign Function Interface (FFI)

Das Foreign Function Interface ruft C-Funktionen aus Lyx auf. Die Grundlage ist die C-ABI der Zielplattform: System V AMD64 auf Linux/macOS, AAPCS64 auf ARM64.

Philosophie: Die Units in std/ und data/ kommen ohne externe C-Bibliotheken aus. FFI ist für Fälle gedacht, in denen eine vorhandene C-Bibliothek genutzt werden soll.

FFI ist in Lyx kein offenes Tor: Der Compiler klassifiziert jedes Symbol und weist gefährliche Aufrufe ab, bevor sie in den Build gelangen. Diese Seite beschreibt beides — die Deklarationsform und das Sicherheitsmodell dahinter.

→ Capabilities (LCBS) · Attribute & Pragmas · Rohspeicher

Eine externe Funktion wird mit dem Schlüsselwort extern deklariert — ein Attribut @extern gibt es nicht. Die link-Klausel nennt die Bibliothek und ist Pflicht.

@capabilities([system.exit, system.memory.heap])
import std.io;

extern fn strlen(s: pchar): int64 link "libc.so.6";

fn main(): int64 {
    PrintLn(IntToStr(strlen("hallo")));   // 5
    return 0;
}

• Kein Funktionskörper — nur die Signatur, abgeschlossen mit ;
• Die Bibliothek wird mit vollständigem Dateinamen angegeben: „libc.so.6“, nicht „c“
• Aufrufkonvention: System V AMD64 (Linux/macOS), AAPCS64 (ARM64)

Der Compiler ordnet jedes extern-Symbol einer Klasse zu und entscheidet danach, ob und unter welcher Bedingung es zugelassen wird.

strlen · strlcpy · strlcat · snprintf · vsnprintf · memcpy · memmove · memset · memcmp · malloc · free · realloc · calloc · time · clock_gettime

open · close · read · write · fopen · fclose · fread · fwrite · socket · bind · listen · connect · getenv · setenv · exit · abort · mmap · munmap · mprotect · mlock · munlock · die strncpy/strncat-Familie

fork · kill · wait · waitpid · clone · prctl · unshare · setuid · setgid · setresuid · setresgid

gets · system · popen · sprintf · vsprintf · strcpy · strcat · wcscpy · wcscat · dlopen · die gesamte exec-Familie (execve, execvp, execl, …)

sema error: extern fn in FFI-Blacklist (Klasse 3)

Diese Sperre lässt sich nicht durch eine Capability aufheben — sie gilt unbedingt.

Jedes Symbol, das der Compiler nicht in einer der vier Listen findet, fällt hierher. Das ist der Regelfall, sobald eine fremde Bibliothek eingebunden wird: sqrtf, png_create_read_struct, curl_easy_init — nichts davon steht in einer Liste.

sema error (line 6): extern fn: unbekanntes FFI-Symbol erfordert eine Capability-Angabe (FFI-Sandbox Fail-Closed)

Drei Dinge sind daran zu wissen, und alle drei kosten sonst Zeit:

1. Es ist keine bestimmte Capability gemeint. Die Angabe ist eine Absichtserklärung — jede gültige Liste hebt die Sperre auf. Der Compiler kann das Symbol nicht einordnen und verlangt deshalb, dass der Autor die Verantwortung sichtbar übernimmt.
2. Die Annotation gehört unmittelbar vor die Deklaration, nicht an den Unit-Kopf. Auf Modulebene wirkt sie für diesen Zweck nicht.
3. Für genau eine Capability gibt es die Kurzform @cap(…).

unit main;
import std.io;
import std.string;

@cap(system.exit)
extern fn sqrtf(x: f32): f32 link "libm.so.6";

fn main(): int64 {
    var a: f32 := 16.0;
    var r: f32 := sqrtf(a);
    Print("sqrtf(16) = "); PrintF64(r as f64);
    return 0;
}

sqrtf(16) = 4.000000

printf, fprintf, scanf, sscanf und ihre v-Varianten bilden eine eigene Gruppe. Sie sind nur mit der Capability system.unsafe.format_string zugelassen, sonst gelten sie als Klasse 3:

@capabilities([system.exit, system.memory.heap, system.unsafe.format_string])

Der Bibliotheks- und Symbolname in der link-Klausel wird mitgeprüft. Ein verbotenes Symbol lässt sich also nicht unter anderem Funktionsnamen einschleusen:

extern fn harmlos(cmd: pchar): int64 link "system";

sema error: extern fn: link-Zielsymbol in FFI-Blacklist

Eine nicht klassifizierte Funktion mit zwei oder mehr pchar-Parametern wird abgewiesen — das ist die typische Form von strcpy-artigen Funktionen ohne Längenbegrenzung:

sema error: extern fn: ≥2 pchar-Parameter ohne Größenlimit

Einen Zeigertyp gibt es in Lyx nicht: Jeder void*- oder Struct-Zeiger wird als int64 übergeben, der Zugriff läuft über peek/poke.

extern fn kann die Breite des Rückgabewerts ausdrücken: int8, int16, int32 und die vorzeichenlosen Gegenstücke. Der Codegen erweitert dann vorzeichenrichtig (movsx/movsxd) beziehungsweise füllt mit Nullen (movzx) — #1607.

@cap(system.exit)
extern fn atoi(s: pchar): int32 link "libc.so.6";

fn main(): int64 {
    Print("atoi(\"-1\") = "); PrintLn(IntToStr(atoi("-1"c)));
    return 0;
}

atoi("-1") = -1

Ohne Angabe bleibt alles wie bisher: die Regel greift nur, wo sie dasteht, an bestehenden Deklarationen ändert sich nichts. Das ist zugleich die Falle — eine C-Funktion mit int-Rückgabe, die als int64 deklariert wird, liefert -1 als 4294967295. Genau daran gab std.net.tls Fehlercodes falsch weiter; SSL_read, SSL_write, SSL_connect und Geschwister sind deshalb mit umgestellt.

Nach der SysV-Konvention gehen die ersten acht Gleitkommawerte in xmm0–xmm7; entsprechend nimmt eine extern fn bis zu acht f64-Argumente ohne Stapel entgegen. Bis lyxc 1.1.3B lag die Schranke bei sechs, weil der FFI-Pfad die Werte aus den GP-Registern in die xmm-Register schob (#1640, abgespalten aus #1486). Grafik-APIs wie OpenGL (glOrtho, glFrustum, Matrixfunktionen) waren damit nicht ansprechbar.

import std.io;

@cap(ui.display)
extern fn f8(a: f64, b: f64, c: f64, d: f64, e: f64, f: f64, g: f64, h: f64): f64 link "./libargsum.so";

fn main(): int64 {
    var r: f64 := f8(1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0);
    PrintF64(r);          // 36.000000
    return 0;
}

Ab dem neunten Gleitkommawert geht es über den Stapel; dort meldet der Compiler weiterhin, dass es nicht umgesetzt ist.

Die ersten sechs Argumente liegen in Registern, alles Weitere auf dem Stapel. Bis lyxc 1.1.1C bekam ein extern fn ab dem siebten Argument Müll: die FFI-Ausrichtung (and rsp, -16) verschob den Stapel unmittelbar nach dem Ablegen der Argumente (#1620). Native Lyx-Aufrufe waren nie betroffen, weil sie ohne diese Ausrichtung auskommen. Behoben; Deklarationen mit sieben und mehr Argumenten sind wieder benutzbar.

@capabilities([system.exit, system.memory.heap])
import std.io;
import std.alloc;

extern fn memset(dest: int64, c: int32, n: int64): int64 link "libc.so.6";

fn main(): int64 {
    var puffer: int64 := alloc(16);
    memset(puffer, 65, 16);            // mit 'A' füllen
    PrintLn(IntToStr(peek8(puffer)));  // 65
    free(puffer, 16);
    return 0;
}

Eine extern fn mit link „x.dll“ landet seit lyxc 1.1.3E in der Import-Tabelle der erzeugten PE-Datei; Argumente werden nach der Microsoft-x64-Konvention übergeben. Vorher war von einer Windows-Binary aus keine einzige Win32-Funktion erreichbar: der Aufruf endete im page fault (#1671), Argumente kamen falsch an (#1674), und eine zweite DLL erbte den Namenszeiger der ersten (#1676).

unit Main;
import std.io;

@cap(ui.display)
extern fn lstrlenA(s: pchar): int64 link "kernel32.dll";
@cap(ui.display)
extern fn GetSystemMetrics(i: int64): int64 link "user32.dll";

fn main(): int64 {
    PrintLn(lstrlenA("abcde"));          // 5
    PrintLn(GetSystemMetrics(0) > 0);    // 1
    return 0;
}

lyxc dll2.lyx --target=win64 --format=pe -o dll2.exe

Zwei Punkte dazu:

• Mehrere DLLs in einem Programm sind zulässig — jede Gruppe der Import-Tabelle trägt ihren eigenen Namenszeiger.
• Umgebungsvariablen funktionieren unter Windows: EnvLookupRaw und alles, was darauf aufsetzt (std.datetime, std.os), lesen den Windows-Umgebungsblock statt des SysV-Speicherbilds (#1677).

Jede extern-Deklaration erscheint im Sicherheits-Audit des Builds. Ein Programm ohne @capabilities erhält keinen seccomp-Filter — siehe Capabilities.

Weiterführende Seiten:

• Capabilities — das Rechtemodell hinter FFI
• Rohspeicher — Puffer als int64-Adressen
• Attribute & Pragmas

Letzte Aktualisierung: 2026-08-19 — acht Gleitkommaargumente (#1640) und der Abschnitt „Windows-DLLs“ (#1671, #1674, #1676, #1677) ergänzt; beide Beispiele mit lyxc 1.1.3I übersetzt und ausgeführt (das PE unter Wine).

Vorherige Aktualisierung: 2026-08-18 — Breite der Rückgabe (int8/int16/int32 + unsigned, #1607) und die Stapelargumente ab dem siebten (#1620) ergänzt; Beispiel mit lyxc 1.1.2E übersetzt.

Vorherige Aktualisierung: 2026-08-13 — Längenparameter hebt die ≥2-pchar-Sperre seit lyxc 1.0.17K auf (#1180).

Codebeispiele geprüft: gegen lyxc 1.2.5C übersetzt (Prüflauf 2026-09-08 über die gesamte Doku: 574 Vollprogramme, 0 echte Fehler; zusätzlich 5159 Aufrufe gegen die pub fn-Signaturen in aurum/std gehalten, 0 Abweichungen).