Call C libraries natively

Prepare the native host

Native only, published ASPL 0.7.0. Follow the native installation path and system requirements first. These examples use x86-64 Linux, the System V ABI and glibc. libc.so.6 supplies puts, abs, strlen and memset; libm.so.6 supplies sqrt. They need no input lines, source modules or data assets. A built ELF still needs its named shared libraries.

Download a supplied source variant from the C collection. Keep its original filename and user names. An English-keyword source may still contain Arabic user names and strings. No C example has an action to open it in the browser.

Print through a foreign adapter profile

The puts example declares the exact profile c_int__const_char_ptr, mapping ASPL (string) -> i64 to C int(const char *). Both the declaration and call require unsafe. C receives a temporary copy, not ASPL string storage. puts adds LF after مرحبا. The program checks for a negative C result and otherwise returns 0; the unspecified positive C return is not a useful process status.

unsafe foreign print_line(message: string) -> i64
    = c_int__const_char_ptr("libc.so.6", "puts");

fn start_main() -> i64 {
    let result_value = unsafe print_line("مرحبا");
    if result_value < 0 { return 1; }
    return 0;
}

{
  "browser": {
    "check": "policy-rejection",
    "class": "policy-rejection",
    "reason": "foreign-imports-not-supported",
    "output": ""
  },
  "native": {
    "check": 0,
    "status": 0,
    "output": "مرحبا\n"
  }
}

aspl check puts.aspl
aspl run puts.aspl
aspl build -o puts-program puts.aspl
./puts-program

Use طباعة-سي.لبات for the Arabic variant. Success prints مرحبا\n and exits with 0. The double example uses c_double__double with libm.so.6 and sqrt: it checks that sqrt(4.0) is 2.0, prints nothing and exits with 0.

Declare an exact fixed signature

The contextual c / سي tag derives a fixed C signature from source types. In the ordinary example, abs uses i32 -> i32, while strlen uses string -> u64 plus cstring(text). Its Arabic string has ten UTF-8 bytes, so strlen returns 10, not five characters. The program checks both results, prints nothing and returns 0.

unsafe foreign absolute(value: i32) -> i32 = c("libc.so.6", "abs");
unsafe foreign byte_length(text: string) -> u64 = c("libc.so.6", "strlen", cstring(text));
fn start_main() -> i64 {
    if unsafe absolute(i32(-7)) not matches i32(7) { return 1; }
    if unsafe byte_length("مرحبا") not matches u64(10) { return 2; }
    return 0;
}

{
  "native": {
    "check": 0,
    "status": 0,
    "output": ""
  }
}

aspl check ordinary.aspl
aspl run ordinary.aspl
aspl build -o ordinary-program ordinary.aspl
./ordinary-program

The two supplied variants share the filename ordinary.aspl; save one at a time or put them in separate directories. Match the actual C prototype exactly. Read the signature table before adapting a declaration. ASPL does not import headers or infer a prototype from a symbol name.

Copy bytes into a Buffer

The Buffer example imports core::c, copies 00 FF 41 from a list<u8>, changes the original list, and calls memset through an explicit output span. The first extracted list keeps its copied bytes; the shared native Buffer changes to 20 20 20. It handles oversized extraction as foreign.invalid_argument, closes one alias, checks foreign.closed through another, and closes again successfully.

import core::c;
unsafe foreign fill(target: c::Buffer, byte: i32, count: u64) -> c_ptr
    = c("libc.so.6", "memset", output(target, count));
fn start_main() -> i64 {
    var source: list<u8> = [0, 255, 65];
    let created = c::buffer(source);
    if not created::ok { print(created::error::code); return 1; }
    let owned = created::value;
    let alias = owned;
    source[0] = 7;
    let copied = c::bytes(owned, u64(3));
    if not copied::ok { return 2; }
    unsafe fill(owned, i32(32), u64(3));
    let changed = c::bytes(alias, u64(3))::value;
    if copied::value[0] not matches 0 or copied::value[1] not matches 255 or copied::value[2] not matches 65 { return 3; }
    if changed[0] not matches 32 or changed[1] not matches 32 or changed[2] not matches 32 { return 4; }
    let oversized = c::bytes(owned, u64(4));
    if oversized::ok or oversized::error::code not matches "foreign.invalid_argument" { return 5; }
    if not c::close(owned)::ok { return 6; }
    let closed = c::capacity(alias);
    if closed::ok or closed::error::code not matches "foreign.closed" { return 7; }
    if not c::close(alias)::ok { return 8; }
    return 0;
}

{
  "native": {
    "check": 0,
    "status": 0,
    "output": ""
  }
}

aspl check buffer.لبات
aspl run buffer.لبات
aspl build -o buffer-program buffer.لبات
./buffer-program

Both variants use buffer.لبات; keep them in separate directories. Success has no output and status 0. Buffer aliases share one native owner. Construction and extraction copy bytes; assignment does not copy the mutable native storage. See Buffer operations and spans.

Recognize failures and limits

check and build validate declarations without opening their libraries. run and generated programs resolve every foreign declaration before the entry function, including unused declarations. An unavailable library or symbol gives status 4 and prevents source effects. A missing unsafe marker or unsupported signature gives a source error with status 1.

An embedded NUL in a C-string loan traps before C entry with status 5. The original string profile reports foreign-string-contains-nul; generic cstring reports invalid-foreign-argument. Invalid byte counts, closed Buffers and writable aliases also trap before entry. Buffer utilities instead return failed result values for documented refusals. Check ok before accessing value or error; close returns result<unit> with no readable value.

Ordinary unsafe calls run synchronously and may block or crash. They have no managed cancellation or callback privileges. The public toolchain supplies reviewed managed HTTP and Raylib bindings, but no public API for installing arbitrary managed bindings. Contributor callback fixtures are excluded from this collection. Use the foreign API reference, HTTP collection or Raylib collection for the applicable contract.