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
stringis 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 CStringis C'sconst char*.unsafe string.fromCString(p)copies what C gives back and checks that it is UTF-8. - C's
long.longin C is 64 bits on Linux and macOS and 32 on Windows; SG calls itCLong(andCULong), 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 theexternblock (struct sqlite3, thenraw 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:
- The
externblock stays inside a module. Its functions are private to the module unless one is markedpublic, so only the module writesunsafe, and the code that uses it writes none. - The public interface uses SG's types. The zlib module takes a
read byte[]and gives aResult<List<byte>, ZlibError>; it checks sizes before C sees them, and turns C's error codes into an enum. The SQLite module turnssqlite3_errmsginto aSqliteErrorwith the code and the message. - What C allocates is owned by a
Disposablestruct. ADatabaseholds araw sqlite3and closes it indispose; zlib'sDeflaterholds thez_streamin 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. - Callbacks are
exportfunctions inside the module. SQLite's rows come through one that fills a struct reached through thevoid*; libcurl writes the body of a response through another, which stops past a size the client chose. - Safe defaults are part of the wrapper. The curl client accepts only
httpandhttps, 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.