Syscall ABI

Overview

ilusm uses two platform paths for system interaction:

• Dedicated VM opcodes - Core operations (strings, file I/O) implemented in the reference VM
• Host builtins - Extension interface for advanced operations (networking, crypto, system calls)

There is no generic syscall(id, …) opcode. The syscall table is reserved for future extensions.

VM Opcodes

These opcodes touch the platform and are implemented in the reference VM:

Opcode	Name	Host Dependency
21	str_at	txtat (stdlib/txt.ilu)
22	str_sub	txtsub
23	str_len	string len
24	str_cat	txtjn
25	file_read	__sys_read_file(path)
26	file_write	__sys_write_file(path, content)

Opcodes 27 (callv) and 15 (call) invoke builtins or user functions.

Host Builtins

Hosts must implement these exact names for a conforming runner. These are called via bytecode call instructions.

File Operations

Name	Args	Returns
__sys_read_file	path str	content str or err
__sys_write_file	path str, content str	nil or err
__sys_read_dir	dir str	list of names or err
__sys_stat	path str	bool (exists)
__sys_remove	path str	nil or err
__sys_mkdir	dir str	nil or err

Network Operations

Name	Args	Returns
__sys_tcp_dial	host str, port num	sock handle or err
__sys_tcp_send	sock, data str	nil or err
__sys_tcp_recv	sock, timeout num	data str or err
__sys_tcp_close	sock	nil
__http_get	url str, headers obj	response obj or err
__http_post	url str, headers obj, body str	response obj or err

System Operations

Name	Args	Returns
__sys_get_env	key str	value str or nil
__sys_set_env	key str, value str	nil or err
__sys_run_command	cmd str, args list	result obj or err
__sys_get_time	none	timestamp num
__sys_sleep	ms num	nil

Cryptographic Operations

Name	Args	Returns
__cry_hash	data str, alg str	hash str or err
__cry_hmac	data str, key str, alg str	hmac str or err
__cry_aes_encrypt	data str, key str, iv str	encrypted str or err
__cry_aes_decrypt	data str, key str, iv str	decrypted str or err
__cry_random	len num	random str or err

Implementation Notes

• Reference VM: See lib/backend/ilusm_vm.ilu for the canonical implementation
• Bytecode Spec: Complete opcode definitions in lib/backend/mcde.ilu
• Host Contract: All hosts must implement the exact names and signatures above
• Error Handling: Failed syscalls should return error objects, not raise exceptions
• Security: File operations are sandboxed to the program's working directory by default

Stdlib Integration

Standard library modules wire to these syscalls:

• net.* → __http_* / __net_* / __sys_tcp_*
• syn / buf / obs → __sys_* / __buf_* / __obs_*
• cry.* → __cry_*
• fs.* → __sys_* file operations

See lib/stdlib/ and Stdlib overview for complete module documentation.