cleanup: update syscall man page

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
+    MontaukOS provides 176 system calls (numbers 0-184, with numbers
-    assigned -- not every number in the range is in use) for
+    140-148 reserved) for userspace programs. Syscalls use the x86-64
-    userspace programs. Syscalls use the x86-64 SYSCALL instruction
+    SYSCALL instruction with the following register convention:
-    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.
+    Block until the given process has exited. Returns 0-255 for a normal
-        void montauk::waitpid(int pid);
+    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,
+    List directory entries (max 256 per call for ramdisk directories,
-    128 for driver-backed listings such as 0:/os/). For larger
+    128 for FAT32 and ext2 directories). For larger directories use
-    directories use SYS_READDIR_AT.
+    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);
+        montauk::abi::PowerInfo out;
-        // out: montauk::abi::PowerInfo*
+        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_get_output              GET_OUTPUT (4): 0=HDA, 1=Bluetooth
-        audio_set_output                       AUDIO_CTL_SET_OUTPUT (5): switch all streams
+        audio_set_output              SET_OUTPUT (5): all streams
-        (SET_OUTPUT, 5)                        switch a stream's output route
+        audio_ctl(handle, 5, output)  SET_OUTPUT (5): one stream
-        audio_bt_status                        AUDIO_CTL_BT_STATUS (6): 0=unavailable, 1=setup, 2=ready
+        audio_bt_status               BT_STATUS (6): unavailable/setup/ready
-        audio_set_master_volume, _get_          AUDIO_CTL_{SET,GET}_MASTER_VOLUME (7/8), 0-100
+        audio_set_master_volume       SET_MASTER_VOLUME (7), 0-100
-        audio_set_mute, audio_get_mute         AUDIO_CTL_{SET,GET}_MUTE (9/10), per-stream
+        audio_get_master_volume       GET_MASTER_VOLUME (8)
-        audio_set_master_mute, _get_           AUDIO_CTL_{SET,GET}_MASTER_MUTE (11/12)
+        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,7 +770,8 @@
     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,
+        int montauk::usb_control(
+            int handle, const montauk::abi::UsbControlRequest* request,
             void* data, uint32_t dataLen);
 
 .B SYS_USB_BULK_IN_START (182)
@@ -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,
+        int montauk::mailbox_send(int handle, uint32_t msgType,
-                                 uint16_t len, int attachHandle = -1);
+                                  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,7 +887,8 @@
 .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,
+        int montauk::waitset_wait(
+            int waitsetHandle, montauk::abi::IpcWaitResult* outReady,
             uint64_t timeoutMs = ~0ULL);
 
 .B SYS_PROC_OPEN (110)