examples/libc-calls.mjs
GitHub// @node-skills {"added":["v26.1.0"],"flags":["--no-warnings"]}
// Call libc's strlen/abs/getpid through node:ffi, finding libc by feature detection.
import ffi from 'node:ffi';
import assert from 'node:assert/strict';
// Only the Linux/glibc name is verified. 'libc.so' is a linker script there ("invalid ELF header").
const candidates = {
linux: ['libc.so.6', 'libc.musl-x86_64.so.1', 'libc.musl-aarch64.so.1'],
darwin: ['/usr/lib/libSystem.B.dylib'],
win32: ['msvcrt.dll'],
}[process.platform] ?? [`libc.${ffi.suffix}`];
function openLibc() {
for (const name of candidates) {
try { return new ffi.DynamicLibrary(name); } catch { /* try next */ }
}
return null;
}
{
using libc = openLibc();
if (!libc) { console.log(`skip: no libc among ${candidates}`); process.exit(77); }
const { strlen, abs, getpid } = libc.getFunctions({
strlen: { arguments: ['string'], return: 'uint64' },
abs: { arguments: ['int32'], return: 'int32' },
getpid: { return: 'int32' }, // `arguments` defaults to []
});
assert.equal(strlen('héllo'), 6n); // strings go in as temporary UTF-8; 64-bit returns are bigint
assert.equal(strlen(Buffer.from('abc\0')), 3n); // Buffers pass a pointer to their memory
assert.equal(abs(-5), 5);
assert.equal(getpid(), process.pid);
// Strict argument validation: no coercion.
for (const bad of [1.5, 5n, '5', true]) assert.throws(() => abs(bad), { code: 'ERR_INVALID_ARG_VALUE' });
// A 'string' RETURN type is just a pointer (bigint); decode it with ffi.toString().
const getenv = libc.getFunction('getenv', { arguments: ['string'], return: 'string' });
process.env.NODE_FFI_DEMO = 'ok';
assert.equal(typeof getenv('NODE_FFI_DEMO'), 'bigint');
assert.equal(ffi.toString(getenv('NODE_FFI_DEMO')), 'ok');
assert.equal(ffi.toString(getenv('NODE_FFI_DOES_NOT_EXIST')), null); // NULL -> 0n -> null
// Same symbol, different signature: rejected. Same signature: same wrapper.
assert.throws(() => libc.getFunction('abs', { arguments: ['int64'], return: 'int64' }), { code: 'ERR_INVALID_ARG_VALUE' });
assert.equal(libc.getFunction('abs', { arguments: ['int32'], return: 'int32' }), abs);
assert.equal(ffi.dlsym(libc, 'abs'), abs.pointer);
assert.throws(() => libc.getSymbol('no_such_symbol_xyz'), { code: 'ERR_FFI_CALL_FAILED' });
// Declaring the wrong return width silently truncates: glibc isdigit() returns int 2048, not 0/1.
if (process.report.getReport().header.glibcVersionRuntime) {
const isdigitAsBool = libc.getFunction('isdigit', { arguments: ['int32'], return: 'bool' });
assert.equal(isdigitAsBool(0x35), 0); // '5' IS a digit, but 2048 & 0xff === 0
}
// toFunction(pointer, signature) wraps a raw function address (main only; absent in v26.13.0).
if (typeof libc.toFunction === 'function') {
const toupper = libc.toFunction(libc.getSymbol('toupper'), { arguments: ['int32'], return: 'int32' });
assert.equal(toupper(0x61), 0x41);
}
libc.close();
assert.throws(() => abs(-1), { code: 'ERR_FFI_LIBRARY_CLOSED' });
libc.close(); // second close is a no-op
}