do not edit — generated by btf.

syscalls

this page is the table: all 24 syscalls kaboom currently has, their exact signatures, and what each one hands back on success and on failure. it's ported straight from idt.nsc's own numbered doc comment above syscall_dispatch, so the two can't quietly drift apart -- if this table and the running kernel ever disagree, the comment (and this page) is what's stale, not the other way around. read kernel for the dispatch mechanism itself: the int-gate at vector 0x80, the shared error-logging path (sys_doerror), and how kaboom_errno gets set. this page only covers the 24 individual calls.

the calling convention: syscall number goes in rax, which is also where the return value comes back. up to three arguments go in rdi, rsi, rdx -- a fourth, where one exists, goes in r10. that's the same register order and positions the real x86-64 sysv/syscall convention uses, kept purely for familiarity; the actual entry mechanism here is a classic int-gate, not the syscall instruction. the failure convention is not uniform across calls -- some return a negative value, some a plain 0 or 1 boolean -- so check the returns column for each one rather than assuming.

#	call	returns	notes
1	`print(str)`	void	debug-prints a nul-terminated string (rdi) to vga and serial both. the original proof-of-mechanism syscall, kept around for back-compat rather than removed now that real i/o exists.
2	`write(fd, buf, len)`	bytes written, or -1
3	`read(fd, buf, maxlen)`	bytes read, or -1
4	`open(path, path_len)`	fd, or -1
5	`close(fd)`	0, or -1
6	`listdir(names_out, max)`	count of entries written	lists the current directory. see syscall 21 for the path-taking version.
7	`exec(path, path_len, argc, argv)`	the child's exit code (whatever it left in rax when it returned), or -1	four args -- the fourth, argv, comes in r10, not rdx. path resolution, the `/bin` fallback, permission enforcement, and the shebang re-exec mechanism (including the paging window swap for sh nesting against itself) are all covered on kernel; this row is just the call's own contract. -1 is genuinely ambiguous here -- exec itself failing looks the same as a child whose own legitimate exit code happened to be -1 -- a known, pre-existing wart, not something this table is hiding.
8	`klog_read(buf, maxlen)`	bytes copied from the kernel log
9	`mkdir(name, name_len, perm)`	new inode number, or -1	the one create-style call that hands back something other than a plain 1/0 -- a caller that needs the inode it just made (rather than just knowing it worked) doesn't have to look it up again afterward.
10	`rmdir(name, name_len)`	1, or 0
11	`rm(name, name_len)`	1, or 0
12	`cd(name, name_len)`	1, or 0
13	`pwd(buf)`	path length
14	`info(buf)`	always 0	fills buf (room for 4 u64s) with total_blocks, blocks_used, inode_count, inodes_used. the return value is always 0 -- the actual result comes back through buf, not rax.
15	`writefile(name, name_len, data, len)`	1, or 0	four args -- len is the fourth, in r10, same convention as syscall 7. finds or creates name in the current directory and overwrites its entire content.
16	`vga_clear()`	void	no args. clears vga and serial both, despite the name only naming one of them.
17	`chmod(name, name_len, perm)`	1, or 0	see syscall 24 for the read-back counterpart.
18	`alloc(size)`	ptr, or 0 if the heap arena is exhausted	userspace's way to get memory dynamically instead of declaring a huge fixed-size global or stack buffer. wraps the same `kalloc` every kernel-side subsystem already uses.
19	`free(ptr)`	void	no args used beyond the pointer, and always a no-op -- kaboom's arena allocator never frees. this exists as real api surface, so a program can call free without having to know that, not because it does anything yet.
20	`stat(path, path_len)`	-1 not found, 1 a file, 2 a directory
21	`listdir_path(path, path_len, names_out, max)`	count, or -1 if path doesn't resolve to a directory	four args -- max is the fourth, in r10, same convention as syscall 7. the path-taking version of syscall 6.
22	`date(buf)`	void	fills buf (room for 6 u64s) with second, minute, hour, day, month, and full year, read straight from the cmos rtc.
23	`errno(void)`	`kaboom_errno` -- 0 generic, 1 permission denied	no args. this is the userspace half of the same `kaboom_errno`/`sys_doerror` mechanism covered on kernel: `klogs` already gets the real reason a syscall failed, but a command's own user-visible error message had no way to ask "was that permission denied, or something else" until this existed. reads whatever `kaboom_errno` was left at by the most recent syscall this same process made -- check it right after a failing call, before making another one, or a later unrelated call's own reset overwrites it.
24	`getperm(path, path_len)`	the resolved inode's permission bitmask (r=1 w=2 x=4), or -1 if path doesn't resolve	chmod's read-back counterpart -- what a `perms` command uses to show what's actually set.

grows further once real coreutils show what else they need.