Skip to main content

Working with C

SG compiles through C, and it speaks C's language at the edge: it calls a library of C directly, with no wrapper to write by hand, and C can call functions written in SG. What the compiler cannot check, a call into code it cannot see, is written inside unsafe, so the places to look at closely are easy to find (Unsafe code is the chapter about them).

Calling a function of C​

An extern block declares functions of C with SG's types. extern { } is the C library itself; extern "z" { } names a library, linked as -lz. Each call is written inside unsafe:

extern {
nuint strlen(read CString text)
int abs(int value)
int toupper(int c)
}

void main() {
var text = CString.from("hello") ?? panic("a zero byte inside")
print(unsafe strlen(read text))
print(unsafe abs(-7))
print((char)unsafe toupper((int)'q'))
}

It prints:

5
7
Q

Without unsafe, the compiler says why it is needed:

extern {
int abs(int value)
}

void main() {
print(abs(-7))
}
error: `abs` is a function of C, and the checker cannot see what it does, so it is written inside `unsafe`
--> example.sg:6:11
6 | print(abs(-7))
| ^^^^^^^
hint: `unsafe abs(-7)`, or `unsafe { ... }` around several statements

extern "z", "zlib" { } gives the names a library has on different systems, and the first one the C compiler finds is linked. A library outside the usual folders is found with -L folder (see Building programs). The interpreter calls C too: it builds a small library of wrappers with the C compiler and opens it, so sg file.sg and a compiled program call the same functions. While a call of C waits, the other tasks run.

C's types​

A function of C takes integers, float, double, bool, raw pointers (raw T), structs of plain data by value, and borrows: ref T and read T are C's T* and const T* for the time of the call. It gives back a number, a bool, a raw T, a struct of plain data, or nothing.

  • Text. An SG string is not ended by a zero byte, so it does not go to C as it is. CString.from(text) makes one that is, and gives an error when the text has a zero byte inside; read CString is C's const char*. unsafe string.fromCString(p) copies what C gives back and checks that it is UTF-8.
  • C's long. long in C is 64 bits on Linux and macOS and 32 on Windows; SG calls it CLong (and CULong), so a declaration says the same thing on every system.
  • Structs. A struct of plain data (numbers, bool, char, raw pointers, arrays and structs of them) is laid out as C lays it out, and goes by value. A type of C that SG only points at is declared without a body in the extern block (struct sqlite3, then raw sqlite3).
  • Buffers. list.pointer() gives the items of a list, an array or a slice of plain data, and is written only as an argument of a C function, so the pointer cannot outlive the call.
extern {
Div div(int numer, int denom)
CLong labs(CLong value)
double frexp(double value, ref int exponent)
raw byte strdup(read CString text)
}

// C's `div_t`: plain data, laid out as C lays it out.
struct Div {
int quot
int rem
}

void main() {
var d = unsafe div(17, 5)
print($"{d.quot} remainder {d.rem}")

CLong big = unsafe labs(-2000000000)
long wide = big
print(wide)

int exponent = 0
var fraction = unsafe frexp(8.0, ref exponent)
print($"{fraction} * 2^{exponent}")

var name = CString.from("tea") ?? panic("a zero byte inside")
var copy = unsafe strdup(read name)
print(unsafe string.fromCString(copy) ?? "not UTF-8")
unsafe Memory.free(copy)
}

It prints:

3 remainder 2
2000000000
0.5 * 2^4
tea

A type C does not have is refused where it is declared, with the way to write it:

extern {
nuint strlen(read string text)
}

void main() {
print(unsafe strlen("hello"))
}
error: the C function `strlen` cannot take a `read string`
--> example.sg:2:18
2 | nuint strlen(read string text)
| ^^^^^^^^^^^
hint: a text goes to C as `read CString`: `CString.from(text)` makes one

A function of C with a varying count of arguments is declared with ... (int snprintf(raw byte s, nuint n, read CString format, ...)), and each value after the parameters must have a type C reads, so (long)30 rather than a bare 30. A variable of C is declared without parentheses (int opterr) and read inside unsafe. C.errno() reads what the last call left in errno.

A C file beside the program​

Some things of C cannot be declared: a macro, a static inline function, a builtin of the compiler. extern "./native.c" { } names a C file in the module's folder in place of a library. It is compiled with the program, so a function written there can reach all of those and be inlined:

// native.c
#include <stdint.h>

#define SQUARE(x) ((x) * (x))

static inline int32_t clamp(int32_t value, int32_t low, int32_t high) {
return value < low ? low : value > high ? high : value;
}

int32_t square_clamped(int32_t value) {
return clamp(SQUARE(value), 0, 100);
}

uint32_t count_bits(uint32_t value) {
return (uint32_t)__builtin_popcount(value);
}

The program needs that file beside it, so it is not run on this page; saved as main.sg next to native.c, sg main.sg and the compiled program both print 49, 100 and 8:

extern "./native.c" {
int square_clamped(int value)
uint count_bits(uint value)
}

void main() {
print(unsafe square_clamped(7))
print(unsafe square_clamped(12))
print(unsafe count_bits(0xff))
}

When the file needs a library, the module names it in a block of its own (extern "m" { }, empty if nothing else is declared).

Being called by C​

export makes a function that C calls by the name written. It takes and gives only types C has. A pointer to a function, as C calls it, is a CFunc<A, B, R> (the parameters, then what it returns); the name of an export function or of a function of C is one. Here C's qsort calls back into SG:

extern {
void qsort(raw void base, nuint count, nuint size, CFunc<raw void, raw void, int> compare)
}

// C calls this by its name, with pointers to two items.
export int byValue(raw void a, raw void b) {
var x = unsafe ((raw int)a)[0]
var y = unsafe ((raw int)b)[0]
if x < y {
return -1
}
if x > y {
return 1
}
return 0
}

void main() {
var numbers = List<int> { 42, -7, 19, 0, 3 }
unsafe qsort((raw void)numbers.pointer(), (nuint)numbers.length(), 4, byValue)
print(numbers)
}

It prints:

[-7, 0, 3, 19, 42]

State that a callback needs goes through C's void*: unsafe Memory.addressOf(ref state) gives the address, and inside the callback unsafe (ref State)data lends it again. The interpreter remembers every address it gave, and a wrong type, a value that has ended or an address it never gave is a panic. A panic inside an export function ends the process with its message, since nothing unwinds through C.

A struct of SG that is not plain data goes to C by its address: an export function gives it as T* (C keeps it), takes it back as T* (it ends there), or is lent it as read T or ref T for the call.

A library for C​

sg build folder --library builds a static library (libfolder.a, folder.lib on Windows) and writes the header C includes; --shared builds a shared one (.so, .dylib, .dll). Only the export functions are seen from outside. A folder stats with this file:

// The average of `count` numbers C gives; 0 for none.
export double stats_mean(raw double values, nuint count) {
if count == 0 {
return 0.0
}
var numbers = unsafe Memory.view(values, (nint)count)
double sum = 0.0
for n in numbers {
sum += n
}
return sum / (double)count
}

and a program of C that uses it:

// main.c
#include <stdio.h>
#include "stats.h"

int main(void) {
double values[] = { 2.0, 4.0, 9.0 };
printf("%g\n", stats_mean(values, 3));
return 0;
}

build like this, and the program prints 5; sg build says how a program links the library:

$ sg build stats --library -o build/libstats.a
built build/libstats.a and build/stats.h; a program links it with `build/libstats.a -lm -pthread`
$ cc -std=c11 -Ibuild -o prog main.c build/libstats.a -lm -pthread

The header declares double stats_mean(double *values, uint64_t count);, with extern "C" for C++ and the macro Windows' DLLs need. A type C holds only by its address is declared without its fields (typedef struct Calculator Calculator;), so C cannot reach inside it. Each library carries its own runtime, which starts on first use from any thread; a panic aborts the program.

Wrapping a library safely​

The repository's examples wrap three libraries of C (SQLite, libcurl and zlib) the same way, and the way generalises:

  1. The extern block stays inside a module. Its functions are private to the module unless one is marked public, so only the module writes unsafe, and the code that uses it writes none.
  2. The public interface uses SG's types. The zlib module takes a read byte[] and gives a Result<List<byte>, ZlibError>; it checks sizes before C sees them, and turns C's error codes into an enum. The SQLite module turns sqlite3_errmsg into a SqliteError with the code and the message.
  3. What C allocates is owned by a Disposable struct. A Database holds a raw sqlite3 and closes it in dispose; zlib's Deflater holds the z_stream in raw memory, where it stays put because zlib keeps its address, and gives it back when the deflater ends, closed or not. Nothing can be leaked or used after it is freed, because the owner decides when it ends.
  4. Callbacks are export functions inside the module. SQLite's rows come through one that fills a struct reached through the void*; libcurl writes the body of a response through another, which stops past a size the client chose.
  5. Safe defaults are part of the wrapper. The curl client accepts only http and https, on the first request and on every redirect, always checks certificates, and has a size and a time limit.

The user of such a module writes var db = try Database.open(":memory:") and never sees a pointer.