From a11c50d0869185961b50936e8282474d188c626e Mon Sep 17 00:00:00 2001 From: Rae McKelvey <633012+okdistribute@users.noreply.github.com> Date: Sat, 11 Jul 2026 02:20:12 +0200 Subject: [PATCH] docs(languages): add C bindings via iroh-c-ffi --- docs.json | 1 + languages/c.mdx | 85 +++++++++++++++++++++++++++++++++++++++++++++ languages/index.mdx | 33 +++++++++--------- 3 files changed, 103 insertions(+), 16 deletions(-) create mode 100644 languages/c.mdx diff --git a/docs.json b/docs.json index c449c54..a17cf61 100644 --- a/docs.json +++ b/docs.json @@ -26,6 +26,7 @@ "languages/swift", "languages/kotlin", "languages/javascript", + "languages/c", "languages/go", "languages/wasm-browser" ] diff --git a/languages/c.mdx b/languages/c.mdx new file mode 100644 index 0000000..3ab507b --- /dev/null +++ b/languages/c.mdx @@ -0,0 +1,85 @@ +--- +title: "C" +description: "Use iroh from C via the iroh-c-ffi bindings." +--- + +| Platform | Architectures | +| --- | --- | +| Linux | x86_64 (glibc) | +| macOS | arm64 | +| Windows | x86_64 | + +- **Header:** [`irohnet.h`](https://github.com/n0-computer/iroh-c-ffi/blob/main/irohnet.h), checked into the repo +- **Examples:** [main.c](https://github.com/n0-computer/iroh-c-ffi/blob/main/main.c) and the [multi-thread examples](https://github.com/n0-computer/iroh-c-ffi/tree/main) +- **All languages:** [platform support matrix](/languages#platform-support) + +[`iroh-c-ffi`](https://github.com/n0-computer/iroh-c-ffi) is a raw C API generated with [safer-ffi](https://github.com/getditto/safer-ffi) — unlike the Python, Swift, Kotlin, and JavaScript bindings, it isn't built on `iroh-ffi`/uniffi. There are no prebuilt binaries; you build the static/shared library from source and link against it. + +## Install + +```bash +git clone https://github.com/n0-computer/iroh-c-ffi +cd iroh-c-ffi +cargo build --release +``` + +This produces `target/release/libiroh_c_ffi.{a,so,dylib}`. The matching header is already checked in as `irohnet.h`; regenerate it only if you're tracking an API change: + +```bash +cargo run --features headers --bin generate_headers --release +``` + +## Hello, iroh + +```c +#include +#include +#include "irohnet.h" + +int main(void) { + char alpn[] = "hello-c-ffi/0"; + slice_ref_uint8_t alpn_slice; + alpn_slice.ptr = (uint8_t *) alpn; + alpn_slice.len = strlen(alpn); + + EndpointConfig_t config = endpoint_config_default(); + endpoint_config_add_alpn(&config, alpn_slice); + + Endpoint_t *ep = endpoint_default(); + if (endpoint_bind(&config, NULL, NULL, &ep) != 0) { + fprintf(stderr, "failed to bind\n"); + return 1; + } + endpoint_online(&ep, 5000); + + EndpointAddr_t addr = endpoint_addr_default(); + endpoint_addr(&ep, &addr); + printf("endpoint id: %s\n", public_key_as_base32(&addr.id)); + + endpoint_free(ep); + endpoint_config_free(config); + return 0; +} +``` + +Build and link against the library from the previous step: + +```bash +cc -o hello hello.c -L target/release -liroh_c_ffi -lm +``` + +This binds an endpoint with a single ALPN, waits up to 5 seconds for a home relay, and prints the endpoint id. See the [CI workflow](https://github.com/n0-computer/iroh-c-ffi/blob/main/.github/workflows/ci.yml) for the extra link flags Windows needs. + +## Next steps + + + A full server/client pair: bind, accept, send, and receive over uni- and bi-directional streams. + + + + `multi-thread-server.c`, `multi-thread-client.c`, and `single-thread-server.c` for handling concurrent connections. + + + + Source, generated header, and issue tracker for the C bindings. + diff --git a/languages/index.mdx b/languages/index.mdx index bb26136..5ab152e 100644 --- a/languages/index.mdx +++ b/languages/index.mdx @@ -1,9 +1,9 @@ --- title: "Overview" -description: "Use iroh from Rust, Python, Swift, Kotlin, JavaScript or Go." +description: "Use iroh from Rust, Python, Swift, Kotlin, JavaScript, C, or Go." --- -iroh is available in Rust, Python, Swift, Kotlin, JavaScript, and Go. Pick the language that fits your app and follow its guide to get a working endpoint in minutes. +iroh is available in Rust, Python, Swift, Kotlin, JavaScript, C, and Go. Pick the language that fits your app and follow its guide to get a working endpoint in minutes. | Language | Status | Platform notes | | --- | --- | --- | @@ -12,6 +12,7 @@ iroh is available in Rust, Python, Swift, Kotlin, JavaScript, and Go. Pick the l | [Swift](/languages/swift) | Official | iOS + macOS | | [Kotlin](/languages/kotlin) | Official | JVM + Android | | [JavaScript](/languages/javascript) | Official | Node.js via N-API | +| [C](/languages/c) | Official | Raw FFI via [iroh-c-ffi](https://github.com/n0-computer/iroh-c-ffi), build from source | | [Go](/languages/go) | Community | FFI bindings via [iroh-ffi](https://github.com/n0-computer/iroh-ffi) | "Community" bindings are built and maintained by community members rather than @@ -19,7 +20,7 @@ the number0 team. They aren't covered by official support, may lag behind iroh releases, and cover fewer platforms — check each binding's page for current status before depending on it. -All five official bindings share the same basic API surface for sending streams +All six official bindings share the same basic API surface for sending streams or datagrams over QUIC. The Rust language bindings are the most complete and up-to-date, and contain custom configuration and protocol features. @@ -31,19 +32,19 @@ up-to-date, and contain custom configuration and protocol features. The [n0.computer](https://n0.computer) team offers official support for the following platforms. -| Platform | Rust | Python | Swift | Kotlin | JavaScript | Go | -| --- | --- | --- | --- | --- | --- | -- | -| iOS (device + sim) | ✓ | — | ✓ | — | — | - | -| Android (aarch64, armv7) | ✓ | — | — | ✓ | ✓ | - | -| macOS arm64 | ✓ | ✓ | ✓ | ✓ | ✓ | - | -| macOS x86_64 | ✓ | ✓ | ✗ | ✓ | ✗ | - | -| Linux x86_64 (glibc) | ✓ | ✓ | — | ✓ | ✓ | - | -| Linux x86_64 (musl) | ✓ | ✗ | — | ✗ | ✓ | ✓ | -| Linux aarch64 (glibc) | ✓ | ✓ | — | ✓ | ✓ | - | -| Linux aarch64 (musl) | ✓ | ✗ | — | ✗ | ✓ | ✓ | -| Linux armv7 | ✓ | ✗ | — | ✗ | ✓ | - | -| Windows x86_64 | ✓ | ✓ | — | ✓ | ✓ | - | -| Windows aarch64 | ✓ | ✗ | — | ✗ | ✓ | - | +| Platform | Rust | Python | Swift | Kotlin | JavaScript | C | Go | +| --- | --- | --- | --- | --- | --- | - | -- | +| iOS (device + sim) | ✓ | — | ✓ | — | — | ✗ | - | +| Android (aarch64, armv7) | ✓ | — | — | ✓ | ✓ | ✗ | - | +| macOS arm64 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | +| macOS x86_64 | ✓ | ✓ | ✗ | ✓ | ✗ | ✗ | - | +| Linux x86_64 (glibc) | ✓ | ✓ | — | ✓ | ✓ | ✓ | - | +| Linux x86_64 (musl) | ✓ | ✗ | — | ✗ | ✓ | ✗ | ✓ | +| Linux aarch64 (glibc) | ✓ | ✓ | — | ✓ | ✓ | ✗ | - | +| Linux aarch64 (musl) | ✓ | ✗ | — | ✗ | ✓ | ✗ | ✓ | +| Linux armv7 | ✓ | ✗ | — | ✗ | ✓ | ✗ | - | +| Windows x86_64 | ✓ | ✓ | — | ✓ | ✓ | ✓ | - | +| Windows aarch64 | ✓ | ✗ | — | ✗ | ✓ | ✗ | - | Get in touch and tell us what you're building. We can prioritize new bindings or help you maintain your own.