From 9051b8a16e33c6e6de247b8d54917213112587b9 Mon Sep 17 00:00:00 2001 From: Daniel Hammer Date: Sat, 29 Aug 2026 12:38:25 +0200 Subject: [PATCH] cleanup: update syscall man page --- programs/man/syscalls.2 | 164 ++++++++++++++++++++++++++++++++-------- 1 file changed, 131 insertions(+), 33 deletions(-) diff --git a/programs/man/syscalls.2 b/programs/man/syscalls.2 index cd9e3e0..95474b8 100644 --- a/programs/man/syscalls.2 +++ b/programs/man/syscalls.2 @@ -3,10 +3,9 @@ syscalls - overview of MontaukOS system calls .SH DESCRIPTION - MontaukOS provides 150 system calls (numbers 0-149, sparsely - assigned -- not every number in the range is in use) for - userspace programs. Syscalls use the x86-64 SYSCALL instruction - with the following register convention: + MontaukOS provides 176 system calls (numbers 0-184, with numbers + 140-148 reserved) for userspace programs. Syscalls use the x86-64 + SYSCALL instruction with the following register convention: RAX Syscall number (in) / return value (out) RDI Argument 1 @@ -44,13 +43,20 @@ int montauk::spawn(const char* path, const char* args = nullptr); .B SYS_WAITPID (23) - Block until the given process has exited. - void montauk::waitpid(int pid); + Block until the given process has exited. Returns 0-255 for a normal + exit, 256 plus the signal number if it was killed or crashed, or 0 if + the PID is unknown or its exit record is no longer available. + int montauk::waitpid(int pid); .B SYS_GETARGS (25) Get the argument string passed to this process at spawn time. int montauk::getargs(char* buf, uint64_t maxLen); +.B SYS_GETEXECPATH (151) + Copy the absolute path from which this process was spawned into buf. + Returns the copied path length, or -1 on invalid arguments. + int mtk_getexecpath(char* buf, unsigned long maxLen); + .B SYS_GETENVIRON (171), SYS_SETENVIRON (172), SYS_SPAWN_ENV (173) Libc process-environment transport. Environment data is encoded as consecutive NAME=VALUE strings with a final empty string. Applications @@ -95,7 +101,7 @@ int montauk::getuser(char* buf, uint64_t maxLen); .SH THREADING - Threads share the spawning process's address space and heap + Threads share the calling process's address space and heap (see montauk/heap.h for the heap lock). Declared in montauk/thread.h. @@ -146,9 +152,9 @@ void montauk::close(int handle); .B SYS_READDIR (10) - List directory entries (max 256 per call for VFS directories, - 128 for driver-backed listings such as 0:/os/). For larger - directories use SYS_READDIR_AT. + List directory entries (max 256 per call for ramdisk directories, + 128 for FAT32 and ext2 directories). For larger directories use + SYS_READDIR_AT. int montauk::readdir(const char* path, const char** names, int max); .B SYS_READDIR_AT (136) @@ -182,6 +188,15 @@ manager move operations). int montauk::frename(const char* oldPath, const char* newPath); +.B SYS_STAT (152) + Get a path's size, timestamps, mode, and directory status. + int montauk::stat(const char* path, montauk::abi::FileStat* out); + +.B SYS_UTIME (167) + Set a path's access and modification timestamps. This is the kernel + transport used by the libc utime(3) interface. + int utime(const char* path, const struct utimbuf* times); + .B SYS_DRIVELIST (79) List mounted drive numbers. int montauk::drivelist(int* outDrives, int max); @@ -234,13 +249,18 @@ uint64_t montauk::get_milliseconds(); .B SYS_GETTIME (28) - Get the current wall-clock date and time (UTC). + Get the current wall-clock date and time in the configured timezone. Fills a montauk::abi::DateTime struct with Year, Month, Day, Hour, Minute, and Second fields. void montauk::gettime(montauk::abi::DateTime* out); +.B SYS_SETUNIXTIME (153) + Set the system wall clock from a UTC Unix timestamp. Returns 0 on + success or -1 if the timestamp is outside the supported range. + int montauk::set_unix_time(int64_t unixSeconds); + .B SYS_SETTZ (90) - Set the process/system timezone offset, in minutes from UTC. + Set the system-wide timezone offset, in minutes from UTC. void montauk::settz(int offset_minutes); .B SYS_GETTZ (91) @@ -276,7 +296,8 @@ Block until the input serial number differs from observedSerial or the timeout elapses; used to sleep efficiently between input-driven redraws. - uint64_t montauk::input_wait(uint64_t observedSerial, uint64_t timeoutMs); + uint64_t montauk::input_wait(uint64_t observedSerial, + uint64_t timeoutMs); .SH MOUSE .B SYS_MOUSESTATE (47) @@ -315,6 +336,48 @@ and RX/TX packet counters. int montauk::net_status(montauk::abi::NetStatus* out); +.B SYS_NETIFS (165) + List registered link-layer network interfaces. The global IP + configuration belongs to the entry whose active field is set. + int montauk::net_interfaces(montauk::abi::NetIfInfo* buf, + int maxCount); + +.SH WI-FI +.B SYS_WIFI_SCAN (158) + Perform a channel scan and block until it finishes or timeoutMs + elapses. Returns the number of results, or -1 if no adapter is ready. + int montauk::wifi_scan(montauk::abi::WifiNetwork* buf, + int maxCount, uint32_t timeoutMs); + +.B SYS_WIFI_INFO (159) + Get adapter, link, scan, join, and last-error status. + int montauk::wifi_info(montauk::abi::WifiInfo* out); + +.B SYS_WIFI_CONNECT (160) + Join a network and block until the link is up or the attempt fails. + int montauk::wifi_connect(const char* ssid, + const char* password); + +.B SYS_WIFI_DISCONNECT (161) + Disconnect from the current Wi-Fi network. + int montauk::wifi_disconnect(); + +.B SYS_WIFI_SCAN_START (162) + Start a non-blocking channel scan. Returns 0 if started, 1 if a scan + is already running, or -1 if no adapter is ready. + int montauk::wifi_scan_start(uint32_t timeoutMs); + +.B SYS_WIFI_RESULTS (163) + Copy results from the most recent scan without accessing the radio. + int montauk::wifi_results(montauk::abi::WifiNetwork* buf, + int maxCount); + +.B SYS_WIFI_CONNECT_ASYNC (164) + Start a non-blocking network join. Observe SYS_WIFI_INFO for progress + and the final result. + int montauk::wifi_connect_async(const char* ssid, + const char* password); + .SH SOCKETS .B SYS_SOCKET (29) Create a socket. type=SOCK_TCP (1) or SOCK_UDP (2). @@ -370,6 +433,30 @@ Map the framebuffer into process memory. void* montauk::fb_map(); +.B SYS_FBFLIP (150) + Flip between double-buffered hardware scanout buffers. Index -1 + queries support; index -2 acquires ownership and returns the current + front-buffer index. Flag bit 0 waits for vertical blank. + int64_t montauk::fb_flip(int64_t index, uint64_t flags); + +.SH DISPLAY CONTROL +.B SYS_DISPLAYINFO (154) + Get connector, mode, capability, and brightness information. + int montauk::display_info(montauk::abi::DisplayInfo* out); + +.B SYS_DISPLAYMODES (155) + Enumerate supported display modes. Returns the number written. + int montauk::display_modes(montauk::abi::DisplayModeInfo* out, + int maxCount); + +.B SYS_DISPLAYSETMODE (156) + Switch to a mode returned by SYS_DISPLAYMODES. + int montauk::display_set_mode(int modeIndex); + +.B SYS_DISPLAYBRIGHTNESS (157) + Set brightness to 0-100 percent, or pass -1 to query it. + int montauk::display_brightness(int percent = -1); + .SH TERMINAL .B SYS_TERMSIZE (24) Get terminal dimensions (columns and rows). @@ -414,8 +501,9 @@ Get the CPU power/thermal snapshot (HWP state, throttling, package temperature, base/max/effective frequency). Returns 0 on success, -1 if unsupported by the running hardware. - int montauk::syscall1(SYS_POWERINFO, (uint64_t)&out); - // out: montauk::abi::PowerInfo* + montauk::abi::PowerInfo out; + int64_t rc = montauk::syscall1( + montauk::abi::SYS_POWERINFO, (uint64_t)&out); .SH KERNEL LOG .B SYS_LOG (46) @@ -445,7 +533,8 @@ .B SYS_CHILDIO_WRITEKEY (52) Forward a raw key event to a redirected child. - int montauk::childio_writekey(int childPid, const montauk::abi::KeyEvent* key); + int montauk::childio_writekey( + int childPid, const montauk::abi::KeyEvent* key); .B SYS_CHILDIO_SETTERMSZ (53) Tell a redirected child its terminal dimensions changed. @@ -595,18 +684,21 @@ audio_set_volume, audio_get_volume AUDIO_CTL_{SET,GET}_VOLUME (0/1) audio_get_pos AUDIO_CTL_GET_POS (2) audio_pause, audio_resume AUDIO_CTL_PAUSE (3) - audio_get_output AUDIO_CTL_GET_OUTPUT (4): 0=HDA, 1=Bluetooth - audio_set_output AUDIO_CTL_SET_OUTPUT (5): switch all streams - (SET_OUTPUT, 5) switch a stream's output route - audio_bt_status AUDIO_CTL_BT_STATUS (6): 0=unavailable, 1=setup, 2=ready - audio_set_master_volume, _get_ AUDIO_CTL_{SET,GET}_MASTER_VOLUME (7/8), 0-100 - audio_set_mute, audio_get_mute AUDIO_CTL_{SET,GET}_MUTE (9/10), per-stream - audio_set_master_mute, _get_ AUDIO_CTL_{SET,GET}_MASTER_MUTE (11/12) + audio_get_output GET_OUTPUT (4): 0=HDA, 1=Bluetooth + audio_set_output SET_OUTPUT (5): all streams + audio_ctl(handle, 5, output) SET_OUTPUT (5): one stream + audio_bt_status BT_STATUS (6): unavailable/setup/ready + audio_set_master_volume SET_MASTER_VOLUME (7), 0-100 + audio_get_master_volume GET_MASTER_VOLUME (8) + audio_set_mute, audio_get_mute MUTE (9/10), per-stream + audio_set_master_mute SET_MASTER_MUTE (11) + audio_get_master_mute GET_MASTER_MUTE (12) .B SYS_AUDIOLIST (128) Enumerate active mixer streams (owner PID, name, format, volume, mute/pause state). - int montauk::audio_list(montauk::abi::AudioStreamInfo* buf, int maxCount); + int montauk::audio_list(montauk::abi::AudioStreamInfo* buf, + int maxCount); .B SYS_AUDIOWAIT (129) Return the current mixer state serial. With timeoutMs > 0, @@ -662,7 +754,8 @@ List currently connected USB interfaces. Each UsbInterfaceInfo contains stable identifiers for the current connection, endpoint addresses, maximum packet sizes, and kernelDriverBound/claimed flags. - int montauk::usb_list(montauk::abi::UsbInterfaceInfo* buf, int maxCount); + int montauk::usb_list(montauk::abi::UsbInterfaceInfo* buf, + int maxCount); .B SYS_USB_CLAIM (179) Exclusively claim an unbound interface. Returns a generation-checked handle @@ -677,8 +770,9 @@ Execute a USB control transfer on endpoint zero. The requestType direction bit determines whether data is read or written. request.length must equal dataLen; control payloads are currently limited to 4096 bytes. - int montauk::usb_control(int handle, const montauk::abi::UsbControlRequest* request, - void* data, uint32_t dataLen); + int montauk::usb_control( + int handle, const montauk::abi::UsbControlRequest* request, + void* data, uint32_t dataLen); .B SYS_USB_BULK_IN_START (182) Start a continuous bulk-IN transfer pool. transferBytes is 1..4096 and @@ -721,7 +815,8 @@ .B SYS_CLIPBOARD_GET_TEXT (121) Read the clipboard's text contents. int montauk::clipboard_get_text(char* buf, uint32_t bufLen, - uint32_t* outLen, uint64_t* outSerial = nullptr); + uint32_t* outLen, + uint64_t* outSerial = nullptr); .B SYS_CLIPBOARD_CLEAR (122) Clear the clipboard. @@ -766,13 +861,15 @@ .B SYS_MAILBOX_SEND (104) Send a typed message, optionally attaching a handle to transfer to the receiver. - int montauk::mailbox_send(int handle, uint32_t msgType, const void* data, - uint16_t len, int attachHandle = -1); + int montauk::mailbox_send(int handle, uint32_t msgType, + const void* data, uint16_t len, + int attachHandle = -1); .B SYS_MAILBOX_RECV (105) Receive a message. int montauk::mailbox_recv(int handle, uint32_t* outMsgType, void* data, - uint16_t* inOutLen, int* outAttachHandle = nullptr); + uint16_t* inOutLen, + int* outAttachHandle = nullptr); .B SYS_WAITSET_CREATE (106) Create a waitset for multiplexing waits across many handles. @@ -790,8 +887,9 @@ .B SYS_WAITSET_WAIT (109) Block until any member handle's watched signals fire, or timeoutMs elapses. - int montauk::waitset_wait(int waitsetHandle, montauk::abi::IpcWaitResult* outReady, - uint64_t timeoutMs = ~0ULL); + int montauk::waitset_wait( + int waitsetHandle, montauk::abi::IpcWaitResult* outReady, + uint64_t timeoutMs = ~0ULL); .B SYS_PROC_OPEN (110) Open a handle to another process by PID (for waiting on its