C functions and unsafe code
A package with native code calls the functions of a C library directly: declare c states a C
function's signature in Velt, the call is a plain C call with no runtime in between, and every
call sits in unsafe code with a comment saying why it is sound. The declarations are checked
against the library's C headers, and only packages the program allows in
allowNative may contain them.
declare c("c") function abs(n: i32): i32;
/** `n` without its sign. */
export function magnitude(n: i32): i32 {
// SAFETY: abs of any i32 but INT_MIN, which is clamped first.
return unsafe { abs(n == -2147483648 ? -2147483647 : n) };
}Code that uses the package calls magnitude, a safe function, and never sees the C call. This
page is the language side: the declarations, what crosses, unsafe and where it may be. The
types for pointers, buffers and strings are in velt/ffi; writing, building and
publishing such a package is in Packages with native code.
declare c functions
declare c("c") function llabs(x: i64): i64;
declare c("sqlite3") function sqlite3_libversion_number(): i32;
declare c("c", { errno: true }) function close(fd: i32): i32;declare c("<library>") function name(…): R;declares the C functionnameof a library. The library is a key ofnative.cin the package'spackage.velt(native);"c"is the platform's C library. A package that declares C functions says so in its manifest:native: { c: { c: { headers: ["<stdlib.h>"] } } }is enough to call the C library alone. Withoutnative.c, its first declaration is an error.- A declaration is allowed only in a file of a package, not in a lone file, and only in a package the program allows (below).
name$suffixdeclares the same C function under another Velt name, with the same signature. One C function has one signature in a program.- Calling one needs an
unsafeblock or function (below). { errno: true }saves the C library'serrnoafter each call, forlastOsError()(velt/os) to read right after it. Without it, a call leaves whatlastOsError()reads alone. On Windows,lastOsError()after adeclare ccall does not report the C library's error yet: it readsGetLastError(), which the C library doesn't set.export declare c functionexports the declaration. It is raw API: only other allowed native packages can import it.- Parameters are plain: type parameters, rest and optional parameters and
asyncare errors that name the parameter. - On WebAssembly targets there are no C libraries, so a call of a C function (or a read of a C constant) is an error naming it.
What crosses
| Velt parameter or result | C type | at the call |
|---|---|---|
i8 … u64 | an integer of that width and sign (char matches either sign) | passed as it is |
isize, usize | ssize_t, ptrdiff_t, intptr_t; size_t, uintptr_t | passed as it is |
f32, f64, bool | float, double, _Bool | passed as it is |
void (result only) | void | |
Ptr<T>, Ptr<T> | null | T * (void * matches any Ptr) | the address; null is NULL |
null | any pointer | always NULL |
u8[], f64[], … | T * | the address of the first element, borrowed for the call |
readonly u8[], … | const T * or T * | the same; C only reads it |
StrBytes | const char * | the string's UTF-8 bytes, no NUL, no copy |
CString | const char * | NUL-terminated bytes made once |
Out<T> | T * (a number or bool) | C writes its value |
OutPtr<T> | T ** or const T ** | C writes the pointer |
Ptr<void> | a function pointer | the address |
- An array of numbers is read at the call, after every argument: a written array (not
readonly) counts as modified, and au8[]parameter also takes a typed array, aDataViewor asubarray. An empty array reaches C as a non-null address that must not be read. longandunsigned longfollow the target: 64 bits on Linux and macOS, 32 on Windows. The header check holds a declaration to the target's width.- A C enum crosses as the integer type of its width: its fixed type, or its widest constant. A packed enum can't cross.
- A
Ptr<T>result (not| null) that isNULLstops the program, naming the C function, since no C header says a pointer can't beNULL. DeclarePtr<T> | nullwhere it can. - A parameter typed
stringis an error that points atStrBytesandCString. The types are invelt/ffi.
declare c type
import { Ptr } from "velt/ffi";
declare c type FILE;
declare c("c") function tmpfile(): Ptr<FILE> | null;
declare c("c") function fwrite(buf: readonly u8[], size: usize, n: usize, f: Ptr<FILE>): usize;A C type that exists only behind pointers. Ptr<FILE> and Ptr<u8> are different types, so one
can't be passed for the other. A declare c type can't be made with new or held by value. It
is raw API: only allowed native packages can import it.
declare c const
import { Ptr } from "velt/ffi";
export declare c const SQLITE_OK: i32;
export declare c const SQLITE_OPEN_READWRITE: i32;
export declare c const SQLITE_TRANSIENT: Ptr<void>;A constant whose value comes from the package's C headers, for each target: an object-like
macro, an enumerator, or a static const that clang can evaluate. It has no initializer and no
library name: the package's libraries that list headers are read. Reading one needs no
unsafe.
Tis an integer,f32,f64,bool,Ptr<U>orPtr<U> | null.- An integer type fits by the value: a flag
#defined as anintcan be au32if its value fits.f32needs a Cfloat,f64afloatordouble,boola_Bool, andPtr<U>a pointer of that C type. ANULLneeds| null. - A C function pointer is a
Ptr<void>, sodeclare c const SQLITE_TRANSIENT: Ptr<void>;binds that value. - A string macro, a function-like macro and a variable are errors.
- A package needs
native.cwithheadersand must be allowed by the program, as for C functions. A library withunchecked: truehas no headers to read, so it has no constants. - Users of a registry or git package never run clang for these: a build takes the values from
the package's
c-headers.json.
declare c struct
export declare c struct CGPoint { x: f64; y: f64; }
export declare c struct CGSize { width: f64; height: f64; }
export declare c struct CGRect { origin: CGPoint; size: CGSize; }
const r: CGRect = { origin: { x: 1, y: 2 }, size: { width: 3, height: 4 } };
const wider = { ...r, size: { ...r.size, width: 6 } } as CGRect;A C struct as a Velt value, laid out as C lays it out.
- Fields are listed in C's order. Each is an integer (
i8…u64,isize,usize),f32,f64,boolor another C struct. A C enum field is its integer type (i32), not a Velt enum (which is ani64); adeclare c typeexists only behind a pointer. - What it can't have: methods, a constructor, type parameters, defaults, optional, private
or static fields, and
implements. It can't be empty, and it can't hold itself by value. - A value. A C struct is copied and never counted. Build it from a literal of its type. Its
fields are read-only: a changed copy is
{ ...v, x: … }. On 64-bit targets (x86-64 and arm64 on Linux, macOS and Windows) the fields sit in order, each at its alignment, as in C. On wasm32,isizeandusizeare 8 bytes in Velt and 4 in C, so the layout differs there. - Equality by content. A C struct has no identity, so every comparison compares its fields,
each number as that operation compares numbers:
==,===,indexOfandlastIndexOftreatNaNas unequal and-0as0;Object.istreatsNaNas itself and-0as not0;MapandSetkeys andincludestreat everyNaNas equal and-0as0. Ananyholding a C struct compares the same way. Ptr<S>is a C pointer to one.- A package's users can import its C structs: unlike
declare c type, they aren't raw API.
unsafe
/** The bytes at `p`. Unsafe: `p` points at `len` readable bytes. */
export unsafe function bytesAt(p: Ptr<u8>, len: usize): u8[] {
return readBytes(p, len);
}
export function home(): string | null {
// SAFETY: getenv returns a NUL-terminated string or NULL, read before any setenv.
const p = unsafe { getenv(new CString("HOME")) };
// SAFETY: as above.
return p === null ? null : unsafe { readCString(p) };
}Calling an unsafe function or method needs an unsafe context: an unsafe { … } block, an
unsafe { … } expression (one expression, and its value), or the body of an unsafe function.
declare c functions, velt/ffi's readBytes, readUtf8 and readCString,
and Ptr.at are unsafe. Calling one anywhere else is an error:
error: calling unsafe function `raw` needs an `unsafe` block or function- Contexts are lexical. A closure written inside one is unsafe code
(
(n: i64) => unsafe { raw(n) }is one too); a nested function declaration is not. unsafemarks functions (unsafe function,unsafe async function,export unsafe function) and methods (unsafe at(i: i64),static unsafe m(),unsafe get x()), not fields.- An unsafe function can be called, not used as a value. An unsafe method can't implement an interface method or override a safe one, and overloads and their implementation are all unsafe or all safe.
- The methods the language calls by itself can't be unsafe: symbol-keyed methods
(
[Symbol.dispose], iterators, operators),toString,toLocaleString,valueOf,toJSONandthen. - Dynamic code doesn't reach unsafe members: an unsafe method, getter or setter read, called or
written through
any,ProxyorReflectis aTypeErrornaming it ('peek' is unsafe, so it can't be reached through `any`). Call it on its class, in unsafe code. unsafeis a contextual keyword: a variable, function or member namedunsafestill works, and a line break after it ends it.
Safety comments
Each piece of unsafe code says why it is sound, or the build fails:
- an unsafe block or expression needs a comment with
SAFETY:in the comment lines directly above its line, saying why the code is sound; - an unsafe function or method needs such a comment, or an
Unsafe:paragraph in its doc comment saying what callers must guarantee.
error: `unsafe` code needs a `// SAFETY:` comment directly before itWhere unsafe code may be
unsafe blocks, expressions, functions and methods, and declare c declarations, are allowed
only in the standard library and in packages with native code (native.c in package.velt)
that the program allows with allowNative. A program's
own files count when the program's own package.velt declares native code. Anywhere else they
are an error:
// SAFETY: callers pass a non-negative `n`.
unsafe function raw(n: i64): i64 {
return n * 2;
}
// SAFETY: 3 is non-negative.
console.log(unsafe { raw(3) });error: unsafe function `raw` needs a native package
error: `unsafe` code needs a native package- The raw API stays there too.
Ptr,OutPtr,readBytes,readUtf8andreadCStringfrom velt/ffi, a package'sdeclare c types, its exporteddeclare cfunctions and its unsafe functions can be imported only by allowed native packages: by name, re-exported, or as a namespace import's member (ffi.Ptr). Other code uses a binding's safe API.CString,Out,StrBytes,byteLengthand C structs can be imported anywhere. - A safe function can still return a
Ptr; code that receives one can't read or write through it withoutunsafe. APtr's address can't be written throughany, and the fields of anOutPtror aCStringare no members throughany. - An npm package isn't part of the package around it: a file under a
node_modules, or under a directory below a package's root with its ownpackage.jsonorpackage.velt, has no package's trust. - A source generator's output can't contain
unsafecode. velt checklists every piece of unsafe code a program allows, by package, file and line (Packages with native code).
Checked against C headers
A wrong declaration would corrupt memory, so velt checks each declare c function against the
library's C headers, for the build's target, in the packages built where they are developed (the
program's own package, a path dependency, a workspace member). A library in native.c lists its
headers, or says unchecked: true (a binary-only SDK, which allowNative's refusal and
velt check point out).
-
A declaration must name a function the headers declare, with as many parameters, and each parameter and the result must match the table above, typedefs resolved.
isizeandusizematch exactly C's pointer-sized types and those need them, so a declaration right on one target is right on every target. -
A mismatch is an error naming the header line and what to declare. On Windows, where
longis 32 bits (velt check --target x86_64-pc-windows-msvcchecks it from any machine):Texterror: parameter 1 of C function `labs` is `long` in stdlib.h:301, not the declaration's `i64` = note: declare `i32` -
The check uses a pinned zig (0.17.1) for clang and the C library headers of every target, downloaded once into
~/.velt/cache/zig/(about 55 MB, 100 MB on Windows, checksum-verified), or the oneVELT_ZIGnames. A check that passed is remembered, so clang runs again only when a header or a declaration changes. -
velt native headerschecks the package on every target and writesc-headers.json, whichvelt publishruns and a git package commits. Users of a registry or git package never need zig: their builds compare the package's declarations with that record (publishing).
Variadic functions (printf), callbacks into Velt, pointers C keeps after the call, async C
calls, string constants, headers per build condition (macOS frameworks), and in C structs:
arrays, pointer fields, passing or returning a struct by value, Out<S>, and the header check
of structs. Each is an error that says so.
velt check --ts-compat reports unsafe under the rule unsafe, declare c functions under
declare-fn, and declare c const and declare c struct as Velt-only
(code shared with TypeScript).
declare system function (System functions) is separate: it
binds C library functions from the compiler's table of safe ones, in any module, with no
unsafe.