Syscall Reference

Complete reference for all Strat9 OS syscalls. Syscalls are invoked via the syscall instruction (x86_64). Arguments are passed in registers; the return value is in RAX.

ABI convention: Success returns a non-negative value. Errors return a negative errno value (two's complement). Userspace checks if result > 0xFFFF_F000 to detect errors, then applies !result + 1 to get the errno number.

Constants

AT_* flags (for *at syscalls)

ConstantValueDescription
AT_FDCWD-100Use the process's current working directory as the base directory
AT_REMOVEDIR0x200Remove a directory (for SYS_UNLINKAT)
AT_SYMLINK_NOFOLLOW0x100Do not follow symbolic links (for SYS_FSTATAT)
AT_EMPTY_PATH0x1000Operate on the fd itself when path is empty

Open flags

FlagValueDescription
O_RDONLY0Open for reading
O_WRONLY1Open for writing
O_RDWR2Open for reading and writing
O_CREAT0x40Create file if it does not exist
O_EXCL0x800Fail if file already exists (with O_CREAT)
O_TRUNC0x200Truncate file to zero length
O_APPEND0x400Append to end of file
O_NONBLOCK0x800Non-blocking mode
O_DIRECTORY0x10000Open as directory
O_NOFOLLOW0x20000Do not follow symlinks

Protection flags (mmap)

FlagValueDescription
PROT_READ1Page can be read
PROT_WRITE2Page can be written
PROT_EXEC4Page can be executed

Signal constants

ConstantValueDescription
SIG_DFL0Default signal handling
SIG_IGN1Ignore signal
SIG_BLOCK0Block signals in set
SIG_UNBLOCK1Unblock signals in set
SIG_SETMASK2Set signal mask to set

Waitpid options

FlagValueDescription
WNOHANG1Return immediately if no child has exited
WUNTRACED2Also return for stopped children
WCONTINUED4Also return for continued children

Clock IDs

ConstantValueDescription
CLOCK_REALTIME0System-wide real-time clock
CLOCK_MONOTONIC1Monotonic clock (not affected by adjustments)
CLOCK_PROCESS_CPUTIME_ID2Per-process CPU time
CLOCK_THREAD_CPUTIME_ID3Per-thread CPU time

Handle operations

#SyscallParametersReturnDescription
0SYS_NULL:0No-op (used for benchmarking)
1SYS_HANDLE_DUPLICATEhandle: u64new handleDuplicate a capability handle
2SYS_HANDLE_CLOSEhandle: u640Close a capability handle
3SYS_HANDLE_WAIThandle: u64, timeout_ns: u640Wait on a handle (blocks until ready or timeout)
4SYS_HANDLE_GRANThandle: u64, target_pid: u640Grant a capability to another process
5SYS_HANDLE_REVOKEhandle: u640Revoke a capability (all holders lose access)
6SYS_HANDLE_INFOhandle: u64, out_ptr: u640Query capability info (writes HandleInfo struct)

Errors: EBADF (invalid handle), EPERM (no grant permission), ESRCH (target process not found)


Memory management

#SyscallParametersReturnDescription
100SYS_MMAPaddr: u64, len: u64, prot: u64, flags: u64, fd: u64, offset: u64mapped addressMap a memory region
101SYS_MUNMAPaddr: u64, len: u640Unmap a memory region
102SYS_BRKaddr: u64new breakSet/clear the data break
103SYS_MREMAPold_addr: u64, old_len: u64, new_len: u64, flags: u64, new_addr: u64new addressRemap a memory region
104SYS_MPROTECTaddr: u64, len: u64, prot: u640Change memory protection flags
105SYS_MEM_REGION_EXPORTaddr: u64, len: u64region handleExport a memory region as a shareable handle
106SYS_MEM_REGION_MAPregion_handle: u64, addr: u64, len: u64mapped addressMap an exported memory region
107SYS_MEM_REGION_INFOregion_handle: u64, out_ptr: u640Query region metadata

Prot flags: PROT_READ (1), PROT_WRITE (2), PROT_EXEC (4)

Errors: EINVAL (bad alignment/flags), ENOMEM (out of memory), EACCES (permission denied), EEXIST (region already mapped)


IPC : Ports

#SyscallParametersReturnDescription
200SYS_IPC_CREATE_PORT:port handleCreate a new IPC port
201SYS_IPC_SENDport_handle: u64, msg_ptr: u64, msg_len: u640Send a message to a port
202SYS_IPC_RECVport_handle: u64, buf_ptr: u64, buf_len: u64bytes receivedReceive a message (blocks)
203SYS_IPC_CALLport_handle: u64, msg_ptr: u64, msg_len: u64bytes receivedSynchronous RPC (send + wait for reply)
204SYS_IPC_REPLYmsg_ptr: u64, msg_len: u640Reply to the current IPC call
205SYS_IPC_BIND_PORTport_handle: u640Bind a port as a listener
206SYS_IPC_UNBIND_PORTport_handle: u640Unbind a listening port
207SYS_IPC_TRY_RECVport_handle: u64, buf_ptr: u64, buf_len: u64bytes received (0 if empty)Non-blocking receive
208SYS_IPC_CONNECTport_handle: u640Connect to a bound port
210SYS_IPC_RING_CREATEsize_log2: u64ring handleCreate a shared ring buffer
211SYS_IPC_RING_MAPring_handle: u64, addr: u640Map a shared ring into address space

Errors: EBADF (invalid handle), ENOSPC (ring full), EAGAIN (non-blocking, nothing available), ETIMEDOUT (timeout exceeded)


IPC : Channels (typed MPMC)

#SyscallParametersReturnDescription
220SYS_CHAN_CREATEcapacity: u64channel handleCreate a typed channel
221SYS_CHAN_SENDhandle: u64, msg_ptr: u640Send a message (blocks if full)
222SYS_CHAN_RECVhandle: u64, msg_ptr: u640Receive a message (blocks if empty)
223SYS_CHAN_TRY_RECVhandle: u64, msg_ptr: u641 if received, 0 if emptyNon-blocking receive
224SYS_CHAN_CLOSEhandle: u640Close channel handle

Errors: EBADF (invalid handle), EPIPE (all endpoints disconnected), EAGAIN (try_recv on empty channel)


IPC : Semaphores

#SyscallParametersReturnDescription
230SYS_SEM_CREATEinitial_value: u64semaphore handleCreate a counting semaphore
231SYS_SEM_WAIThandle: u640Decrement (blocks if zero)
232SYS_SEM_TRYWAIThandle: u641 if acquired, 0 if would blockNon-blocking decrement
233SYS_SEM_POSThandle: u640Increment (wake a waiter)
234SYS_SEM_CLOSEhandle: u640Close semaphore handle

Errors: EBADF (invalid handle), EAGAIN (try_wait on zero semaphore)


PCI

#SyscallParametersReturnDescription
240SYS_PCI_ENUMcriteria_ptr: u64, out_ptr: u64, max_count: u64device countEnumerate PCI devices matching criteria
241SYS_PCI_CFG_READaddr_ptr: u64, offset: u64, width: u64config valueRead PCI configuration register
242SYS_PCI_CFG_WRITEaddr_ptr: u64, offset: u64, width: u64, value: u640Write PCI configuration register

Errors: EINVAL (invalid width/offset), EACCES (no PCI capability)


Async I/O

#SyscallParametersReturnDescription
250SYS_ASYNC_SETUPhandle: u64, event_mask: u64async contextSet up async notification on a handle
251SYS_ASYNC_ENTERctx: u640Enter async wait (yields until event)
252SYS_ASYNC_CANCELctx: u640Cancel pending async wait
253SYS_ASYNC_MAPctx: u64, ring_handle: u640Map an event ring to the async context
254SYS_ASYNC_DESTROYctx: u640Destroy async context

Process management

#SyscallParametersReturnDescription
300SYS_PROC_EXITexit_code: u64: (never returns)Terminate current process
301SYS_PROC_YIELD:0Yield CPU to scheduler
302SYS_PROC_FORKframe: &SyscallFramechild PID (parent), 0 (child)Fork the current process (COW)
308SYS_PROC_GETPID:process IDGet current process ID
309SYS_PROC_GETPPID:parent PIDGet parent process ID
310SYS_PROC_WAITPIDpid: i64, status_ptr: u64, options: u64child PIDWait for a child process
311SYS_GETPID:process IDAlias for SYS_PROC_GETPID
312SYS_GETTID:thread IDGet current thread ID
314SYS_PROC_WAIT::Wait for any child
315SYS_PROC_EXECVEpath_ptr: u64, path_len: u64, argv_ptr: u64, envp_ptr: u64: (replaces image)Execute a new program
341SYS_THREAD_CREATEentry: u64, stack: u64, arg: u64thread IDCreate a new thread
342SYS_THREAD_JOINtid: u64, status_ptr: u640Wait for thread to exit
343SYS_THREAD_EXITstatus: u64: (never returns)Terminate current thread

Errors: ECHILD (no child processes), EAGAIN (thread creation failed), ENOMEM (out of memory)


Futex

#SyscallParametersReturnDescription
303SYS_FUTEX_WAITaddr: u64, val: u32, timeout_ns: u640Sleep if *addr == val
304SYS_FUTEX_WAKEaddr: u64, max_wake: u32woken countWake up to N waiters
305SYS_FUTEX_REQUEUEaddr: u64, max_wake: u32, addr2: u64, max_requeue: u32woken countWake + requeue to addr2
306SYS_FUTEX_CMP_REQUEUEaddr: u64, max_wake: u32, addr2: u64, max_requeue: u32, cmp_val: u32woken countConditional requeue
307SYS_FUTEX_WAKE_OPaddr: u64, max_wake: u32, addr2: u64, max_requeue: u32, wake_op: u32woken countAtomic op + wake

Errors: EAGAIN (value mismatch in WAIT), ETIMEDOUT (timeout expired), EFAULT (invalid address)


Signals

#SyscallParametersReturnDescription
320SYS_KILLpid: i64, signum: u320Send signal to a process
321SYS_SIGPROCMASKhow: i32, set_ptr: u64, oldset_ptr: u640Get/set signal mask
322SYS_SIGACTIONsignum: u64, act_ptr: u64, oact_ptr: u640Set signal handler
323SYS_SIGALTSTACKss_ptr: u64, old_ss_ptr: u640Set alternate signal stack
324SYS_SIGPENDINGset_ptr: u640Get pending signals
325SYS_SIGSUSPENDmask_ptr: u64: (restarted on signal)Suspend until signal
326SYS_SIGTIMEDWAITset_ptr: u64, info_ptr: u64, timeout_ptr: u64signal numberWait for specific signal
327SYS_SIGQUEUEpid: i64, signum: u32, sigval_ptr: u640Queue a signal with data
328SYS_KILLPGpgrp: u64, signum: u320Send signal to process group
352SYS_TGKILLtgid: u64, tid: u64, signum: u320Send signal to specific thread
353SYS_RT_SIGRETURN::Return from signal handler

Process groups & sessions

#SyscallParametersReturnDescription
316SYS_FCNTLfd: u64, cmd: u64, arg: u64depends on cmdFile control operations
317SYS_SETPGIDpid: u64, pgid: u640Set process group ID
318SYS_GETPGIDpid: u64pgidGet process group ID
319SYS_SETSID:session IDCreate new session
329SYS_GETITIMERwhich: u64, out_ptr: u640Get interval timer
330SYS_SETITIMERwhich: u64, in_ptr: u64, out_ptr: u640Set interval timer
331SYS_GETPGRP:pgrpGet current process group
332SYS_GETSIDpid: u64sidGet session ID
333SYS_SET_TID_ADDRESStidptr: u640Set clear-on-exit TID address
334SYS_EXIT_GROUPexit_code: u64: (never returns)Exit all threads in process

User/group IDs

#SyscallParametersReturnDescription
335SYS_GETUID:uidGet real user ID
336SYS_GETEUID:euidGet effective user ID
337SYS_GETGID:gidGet real group ID
338SYS_GETEGID:egidGet effective group ID
339SYS_SETUIDuid: u640Set user ID
340SYS_SETGIDgid: u640Set group ID

Misc process

#SyscallParametersReturnDescription
344SYS_UNAMEuts_ptr: u640Get system information (name, release, etc.)
350SYS_ARCH_PRCTLcode: u64, addr: u640Architecture-specific process control

File I/O

#SyscallParametersReturnDescription
403SYS_OPENpath_ptr: u64, path_len: u64, flags: u64file descriptorOpen a file
404SYS_WRITEfd: u64, buf_ptr: u64, buf_len: u64bytes writtenWrite to a file descriptor
405SYS_READfd: u64, buf_ptr: u64, buf_len: u64bytes readRead from a file descriptor
406SYS_CLOSEfd: u640Close a file descriptor
407SYS_LSEEKfd: u64, offset: u64, whence: u64new positionSeek in a file
408SYS_FSTATfd: u64, stat_ptr: u640Get file status (fstat)
409SYS_STATpath_ptr: u64, path_len: u64, stat_ptr: u640Get file status by path
413SYS_ACCESSpath_ptr: u64, path_len: u64, mode: u640Check file accessibility (uses effective UID/GID, not real). Prefer SYS_FACCESSAT for new code.
430SYS_GETDENTSfd: u64, buf_ptr: u64, buf_len: u64bytes readRead directory entries
431SYS_PIPEfds_ptr: u640Create a pipe pair
432SYS_DUPold_fd: u64new fdDuplicate file descriptor
433SYS_DUP2old_fd: u64, new_fd: u64new fdDuplicate to specific fd
456SYS_PREADfd: u64, buf_ptr: u64, buf_len: u64, offset: u64bytes readPread at offset
457SYS_PWRITEfd: u64, buf_ptr: u64, buf_len: u64, offset: u64bytes writtenPwrite at offset

Open flags: O_RDONLY (0), O_WRONLY (1), O_RDWR (2), O_CREAT (0x40), O_TRUNC (0x200), O_APPEND (0x400), O_EXCL (0x800)

Errors: ENOENT (file not found), EACCES (permission denied), EBADF (bad fd), ENOTDIR (not a directory), EISDIR (is a directory), ENOSPC (disk full), EIO (I/O error)


File system operations

#SyscallParametersReturnDescription
440SYS_CHDIRpath_ptr: u64, path_len: u640Change working directory
441SYS_FCHDIRfd: u640Change working directory by fd
442SYS_GETCWDbuf_ptr: u64, buf_len: u64bytes writtenGet current working directory
443SYS_IOCTLfd: u64, cmd: u64, arg: u64depends on cmdDevice I/O control
444SYS_UMASKmask: u64old maskSet file mode creation mask
445SYS_UNLINKpath_ptr: u64, path_len: u640Delete a file
446SYS_RMDIRpath_ptr: u64, path_len: u640Remove a directory
447SYS_MKDIRpath_ptr: u64, path_len: u64, mode: u640Create a directory
448SYS_RENAMEold_ptr: u64, old_len: u64, new_ptr: u64, new_len: u640Rename a file
449SYS_LINKold_ptr: u64, old_len: u64, new_ptr: u64, new_len: u640Create a hard link
450SYS_SYMLINKtarget_ptr: u64, target_len: u64, link_ptr: u64, link_len: u640Create a symbolic link
451SYS_READLINKpath_ptr: u64, path_len: u64, buf_ptr: u64, buf_len: u64bytes readRead symbolic link target
452SYS_CHMODpath_ptr: u64, path_len: u64, mode: u640Change file permissions
453SYS_FCHMODfd: u64, mode: u640Change file permissions by fd
454SYS_TRUNCATEpath_ptr: u64, path_len: u64, len: u640Truncate a file
455SYS_FTRUNCATEfd: u64, len: u640Truncate a file by fd

*at variants (relative to directory fd)

These syscalls resolve paths relative to a directory file descriptor instead of the process CWD. They are the POSIX-standard way to open, stat, and manipulate files safely in multi-threaded programs.

Special dirfd values

ValueConstantMeaning
-100AT_FDCWDUse the process's current working directory (CWD) as the base
≥ 0valid fdUse the opened directory referenced by this file descriptor

Syscall reference

#SyscallParametersReturnDescription
462SYS_OPENATdirfd: u64, path_ptr: u64, path_len: u64, flags: u64file descriptorOpen a file relative to dirfd. If path_ptr is absolute, dirfd is ignored.
463SYS_FSTATATdirfd: u64, path_ptr: u64, path_len: u64, stat_ptr: u64, flags: u640Get file status relative to dirfd. stat_ptr receives a FileStat struct.
464SYS_UNLINKATdirfd: u64, path_ptr: u64, path_len: u64, flags: u640Delete a file relative to dirfd. If AT_REMOVEDIR flag is set, removes a directory.
465SYS_RENAMEATolddirfd: u64, old_ptr: u64, old_len: u64, newdirfd: u64, new_ptr: u64, new_len: u640Rename/move a file. Source and destination can have different base directories.
466SYS_MKDIRATdirfd: u64, path_ptr: u64, path_len: u64, mode: u640Create a directory relative to dirfd.
467SYS_READLINKATdirfd: u64, path_ptr: u64, path_len: u64, buf_ptr: u64, buf_len: u64bytes readRead the target of a symbolic link relative to dirfd.
468SYS_FACCESSATdirfd: u64, path_ptr: u64, path_len: u64, mode: u64, flags: u640Check file accessibility. mode: R_OK (4), W_OK (2), X_OK (1), F_OK (0).

Flags

FlagValueDescription
AT_FDCWD-100Use process CWD as base directory
AT_REMOVEDIR0x200Unlink a directory instead of a file (for SYS_UNLINKAT)
AT_SYMLINK_NOFOLLOW0x100Do not follow symlinks (for SYS_FSTATAT)
AT_EMPTY_PATH0x1000Operate on dirfd itself when path is empty

Errors

EBADF (invalid dirfd), ENOENT (path not found), EACCES (permission denied), ENOTDIR (dirfd is not a directory), EEXIST (file exists for CREATE_EXCL), EINVAL (invalid flags)


Poll / I/O multiplexing

#SyscallParametersReturnDescription
460SYS_POLLfds_ptr: u64, nfds: u64, timeout_ms: i64ready countPoll file descriptors
461SYS_PPOLLfds_ptr: u64, nfds: u64, timeout_ptr: u64, sigmask_ptr: u64ready countPpoll with signal mask

Network

#SyscallParametersReturnDescription
410SYS_NET_RECVbuf_ptr: u64, buf_len: u64bytes receivedReceive network packet
411SYS_NET_SENDbuf_ptr: u64, buf_len: u64bytes sentSend network packet
412SYS_NET_INFOinfo_type: u64, buf_ptr: u640Query network info (IP, gateway, etc.)

Volume (block device)

#SyscallParametersReturnDescription
420SYS_VOLUME_READhandle: u64, offset: u64, buf_ptr: u64, buf_len: u64bytes readRead from volume
421SYS_VOLUME_WRITEhandle: u64, offset: u64, buf_ptr: u64, buf_len: u64bytes writtenWrite to volume
422SYS_VOLUME_INFOhandle: u64, out_ptr: u640Query volume info

Time

#SyscallParametersReturnDescription
500SYS_CLOCK_GETTIMEclock_id: u64, tp_ptr: u640Get clock time
501SYS_NANOSLEEPreq_ptr: u64, rem_ptr: u640Sleep for a duration
502SYS_CLOCK_NANOSLEEPclock_id: u64, flags: u64, req_ptr: u64, rem_ptr: u640Sleep on a specific clock

Clock IDs: CLOCK_REALTIME (0), CLOCK_MONOTONIC (1), CLOCK_PROCESS_CPUTIME_ID (2), CLOCK_THREAD_CPUTIME_ID (3)


Debug & miscellaneous

#SyscallParametersReturnDescription
600SYS_DEBUG_LOGmsg_ptr: u64, msg_len: u640Write a debug message to kernel log
601SYS_GETRANDOMbuf: u64, len: usize, flags: u32bytes writtenFill buffer with random bytes
610SYS_SET_ROBUST_LISThead: u64, len: usize0Set robust futex list head
611SYS_GET_ROBUST_LISTpid: i64, head_ptr: u64, len_ptr: u640Get robust futex list head

Module management

#SyscallParametersReturnDescription
700SYS_MODULE_LOADpath_ptr: u64, path_len: u64module IDLoad a kernel module
701SYS_MODULE_UNLOADmodule_id: u640Unload a kernel module
702SYS_MODULE_GET_SYMBOLmodule_id: u64, name_ptr: u64, name_len: u64symbol addressLook up a symbol in a loaded module
703SYS_MODULE_QUERYout_ptr: u64, max_count: u64module countList loaded modules

Silo management

#SyscallParametersReturnDescription
800SYS_SILO_CREATE:silo IDCreate a new silo
801SYS_SILO_CONFIGsilo_id: u64, key_ptr: u64, key_len: u64, val_ptr: u64, val_len: u640Configure a silo
802SYS_SILO_ATTACH_MODULEsilo_id: u64, module_id: u640Attach a module to a silo
803SYS_SILO_STARTsilo_id: u640Start a silo
804SYS_SILO_STOPsilo_id: u640Stop a silo
805SYS_SILO_KILLsilo_id: u640Kill a silo (force stop)
806SYS_SILO_EVENT_NEXTsilo_id: u64, out_ptr: u640Wait for next silo event
807SYS_SILO_SUSPENDsilo_id: u640Suspend a silo
808SYS_SILO_RESUMEsilo_id: u640Resume a silo
809SYS_SILO_PLEDGEpromises_ptr: u64, promises_len: u640Restrict syscalls (pledge)
810SYS_SILO_UNVEILpath_ptr: u64, path_len: u64, perms_ptr: u64, perms_len: u640Restrict filesystem access (unveil)
811SYS_SILO_ENTER_SANDBOX:0Enter sandbox mode (irreversible)
812SYS_SILO_RENAMEsilo_id: u64, name_ptr: u64, name_len: u640Rename a silo

ABI version

#SyscallParametersReturnDescription
900SYS_ABI_VERSION:(major << 16) | minorQuery ABI version

Common errno values

ValueNameDescription
1EPERMOperation not permitted
2ENOENTNo such file or directory
3ESRCHNo such process
4EINTRInterrupted system call
5EIOInput/output error
7E2BIGArgument list too long
9EBADFBad file descriptor
10ECHILDNo child processes
11EAGAINResource temporarily unavailable
12ENOMEMOut of memory
13EACCESPermission denied
14EFAULTBad address
17EEXISTFile exists
20ENOTDIRNot a directory
21EISDIRIs a directory
22EINVALInvalid argument
28ENOSPCNo space left on device
32EPIPEBroken pipe
38ENOSYSFunction not implemented
52ENOTSUPNot supported
98EADDRINUSEAddress already in use
110ETIMEDOUTConnection timed out
111ECONNREFUSEDConnection refused