18 KiB
18 KiB
MontaukOS Syscall Reference
All syscalls are available through #include <montauk/syscall.h> in the montauk namespace. The syscall layer provides syscall0() through syscall6() primitives using AMD64 calling conventions. All raw syscalls return int64_t.
Table of Contents
- Process Management
- File System
- Memory
- Console I/O
- Keyboard and Mouse
- Window Server
- Framebuffer
- Networking
- Audio
- Bluetooth
- Timekeeping
- System Information
- Storage and Disks
- Terminal
- Process I/O Redirection
- Configuration
- User Management
- Utility Libraries
Process Management
void exit(int code); // Terminate process (noreturn)
void yield(); // Yield CPU to scheduler
void sleep_ms(uint64_t ms); // Sleep for milliseconds
int getpid(); // Get current process ID
int spawn(const char* path, const char* args); // Spawn child process (-1 on error)
int waitpid(int pid); // Wait for process to exit
int kill(int pid); // Kill a process
int proclist(ProcInfo* buf, int max); // List all processes (returns count)
ProcInfo struct:
struct ProcInfo {
int32_t pid;
int32_t parentPid;
uint8_t state;
char name[64];
uint64_t heapUsed;
uint64_t cpuTimeMs;
};
Arguments
int getargs(char* buf, uint64_t maxLen); // Get command-line arguments passed to this process
File System
int open(const char* path); // Open file (returns fd, negative on error)
int close(int handle); // Close file handle
int read(int handle, uint8_t* buf, uint64_t off, uint64_t size); // Read bytes at offset (returns bytes read)
int fwrite(int handle, const uint8_t* buf, uint64_t off, uint64_t size); // Write bytes at offset
uint64_t getsize(int handle); // Get file size
int readdir(const char* path, const char** names, int max); // List directory entries (returns count)
int fcreate(const char* path); // Create file (returns fd)
int fdelete(const char* path); // Delete file (0 on success)
int fmkdir(const char* path); // Create directory
int drivelist(int* outDrives, int max); // Enumerate mounted drives (returns count)
Path Format
Paths use the format <drive>:/<path>, e.g. 0:/fonts/Roboto-Medium.ttf. Drive 0 is the boot drive (ramdisk).
Example: Reading a File
int fd = montauk::open("0:/config/settings.toml");
if (fd < 0) { /* error */ }
uint64_t size = montauk::getsize(fd);
uint8_t* buf = (uint8_t*)montauk::malloc(size + 1);
montauk::read(fd, buf, 0, size);
buf[size] = 0; // null-terminate
montauk::close(fd);
// ... use buf ...
montauk::mfree(buf);
Memory
void* alloc(uint64_t size); // Allocate kernel pages (avoid for temp buffers)
void free(void* ptr); // Free kernel pages
For general-purpose allocation, prefer the userspace heap (montauk/heap.h):
void* malloc(uint64_t size);
void mfree(void* ptr);
void* realloc(void* ptr, uint64_t size);
Console I/O
void print(const char* text); // Write string to kernel console
void putchar(char c); // Write single character
These write to the kernel's text-mode console, not to a GUI window.
Keyboard and Mouse
Keyboard (Direct, Non-Windowed)
bool is_key_available(); // Poll for pending keystroke
void getkey(montauk::abi::KeyEvent* out); // Get next keystroke (blocks)
char getchar(); // Get single ASCII character (blocks)
KeyEvent struct:
struct KeyEvent {
bool pressed; // true = key down, false = key up
uint8_t scancode; // PS/2 scancode
char ascii; // ASCII value (0 if non-printable)
bool shift, ctrl, alt;
};
Common Scancodes:
| Scancode | Key |
|---|---|
0x01 |
Escape |
0x0E |
Backspace |
0x0F |
Tab |
0x1C |
Enter |
0x39 |
Space |
0x53 |
Delete |
0x48 |
Up |
0x50 |
Down |
0x4B |
Left |
0x4D |
Right |
0x47 |
Home |
0x4F |
End |
0x49 |
Page Up |
0x51 |
Page Down |
Mouse (Direct, Non-Windowed)
void mouse_state(montauk::abi::MouseState* out); // Get current mouse state
void set_mouse_bounds(int32_t maxX, int32_t maxY); // Set mouse boundary
MouseState struct:
struct MouseState {
int32_t x, y;
uint8_t buttons; // 0x01=Left, 0x02=Right, 0x04=Middle
};
For GUI apps, prefer the windowed event system (win_poll) over direct mouse/keyboard syscalls.
Window Server
These syscalls are for standalone GUI apps that run as separate processes. The desktop compositor manages window frames; your app renders into a shared pixel buffer.
int win_create(const char* title, int w, int h, WinCreateResult* result);
void win_destroy(int id);
uint64_t win_present(int id); // Mark window dirty, present to screen
int win_poll(int id, WinEvent* event); // Poll events (0=none, 1=event, <0=closed)
uint64_t win_resize(int id, int w, int h); // Resize, returns new pixel buffer address
uint64_t win_map(int id); // Get pixel buffer address
int win_enumerate(WinInfo* info, int max); // List all windows
int win_sendevent(int id, const WinEvent* event); // Send event to a window
int win_setscale(int scale); // Set UI scale factor
int win_getscale(); // Get UI scale factor
int win_setcursor(int id, int cursor); // Set cursor style
WinCreateResult struct:
struct WinCreateResult {
int id; // Window ID for subsequent calls
uint64_t pixelVa; // Virtual address of shared pixel buffer (uint32_t* ARGB)
};
WinEvent struct:
struct WinEvent {
int type; // 0=Key, 1=Mouse, 2=Resize, 3=Close, 4=Scale
union {
struct { uint8_t scancode; char ascii; bool pressed, shift, ctrl, alt; } key;
struct { int x, y; uint8_t buttons, prev_buttons; int32_t scroll; } mouse;
struct { int w, h; } resize;
struct { int scale; } scale;
};
};
Event Loop Pattern
while (true) {
montauk::abi::WinEvent ev;
int r = montauk::win_poll(win_id, &ev);
if (r < 0) break; // Window closed
if (r == 0) {
montauk::sleep_ms(16); // No events, idle at ~60fps
continue;
}
switch (ev.type) {
case 0: handle_key(ev.key); break;
case 1: handle_mouse(ev.mouse); break;
case 2: handle_resize(ev.resize); break;
case 3: goto done; // Close
}
render(pixels);
montauk::win_present(win_id);
}
done:
montauk::win_destroy(win_id);
Framebuffer
For direct framebuffer access (fullscreen apps, not typical for windowed apps):
void fb_info(FbInfo* info); // Get dimensions and pitch
void* fb_map(); // Map framebuffer to user address space
FbInfo struct:
struct FbInfo {
uint32_t width, height;
uint32_t pitch; // Bytes per row
};
Networking
DNS and Connectivity
int32_t ping(uint32_t ip, uint32_t timeoutMs); // Ping, returns RTT in ms (-1 on timeout)
uint32_t resolve(const char* hostname); // DNS lookup, returns IPv4 (0 on failure)
void get_netcfg(NetCfg* out); // Get network config
int set_netcfg(const NetCfg* cfg); // Set network config
int net_status(NetStatus* out); // Get link/driver/counter status
Sockets
int socket(int type); // Create socket (0=TCP, 1=UDP)
int connect(int fd, uint32_t ip, uint16_t port); // TCP connect
int bind(int fd, uint16_t port); // Bind to port
int listen(int fd); // Start listening
int accept(int fd); // Accept connection (returns new fd)
int send(int fd, const void* data, uint32_t len); // Send data (returns bytes sent)
int recv(int fd, void* buf, uint32_t maxLen); // Receive data (returns bytes read)
int closesocket(int fd); // Close socket
UDP
int sendto(int fd, const void* data, uint32_t len,
uint32_t destIp, uint16_t destPort);
int recvfrom(int fd, void* buf, uint32_t maxLen,
uint32_t* srcIp, uint16_t* srcPort);
Example: Plain HTTP GET (Port 80)
uint32_t ip = montauk::resolve("example.com");
int sock = montauk::socket(0); // TCP
montauk::connect(sock, ip, 80);
const char* req = "GET / HTTP/1.0\r\nHost: example.com\r\n\r\n";
montauk::send(sock, req, montauk::slen(req));
char buf[4096];
int n = montauk::recv(sock, buf, sizeof(buf) - 1);
buf[n] = 0;
montauk::closesocket(sock);
TLS / HTTPS Library
Header: tls/tls.hpp — requires linking libtls.a and libbearssl.a (build with USE_TLS=1).
Provides a high-level tls::https_fetch() that handles socket creation, BearSSL TLS 1.2 setup, handshake, request/response exchange, and cleanup in a single call.
#include <tls/tls.hpp>
// Load CA certificates (from 0:/os/certs/ca-certificates.crt)
tls::TrustAnchors tas = tls::load_trust_anchors();
// Build HTTP request
const char* host = "en.wikipedia.org";
uint32_t ip = montauk::resolve(host);
char req[256];
// ... build "GET /path HTTP/1.1\r\nHost: ...\r\n\r\n" into req ...
int reqLen = montauk::slen(req);
// Fetch (handles TLS handshake, send, receive, teardown)
char resp[32768];
int n = tls::https_fetch(host, ip, 443, req, reqLen, tas, resp, sizeof(resp));
if (n > 0) {
resp[n] = 0;
// ... parse HTTP response ...
}
API reference:
namespace tls {
// Load PEM CA bundle from 0:/os/certs/ca-certificates.crt
TrustAnchors load_trust_anchors();
// High-level: DNS → socket → TLS → exchange → cleanup
int https_fetch(const char* host, uint32_t ip, uint16_t port,
const char* request, int reqLen,
const TrustAnchors& tas,
char* respBuf, int respMax,
AbortCheckFn abort_check = nullptr);
// Lower-level: run TLS exchange on an existing socket + BearSSL engine
int tls_exchange(int fd, br_ssl_engine_context* eng,
const char* request, int reqLen,
char* respBuf, int respMax,
AbortCheckFn abort_check = nullptr);
// Helpers for manual BearSSL usage
int tls_send_all(int fd, const unsigned char* data, size_t len);
int tls_recv_some(int fd, unsigned char* buf, size_t maxlen);
void get_bearssl_time(uint32_t* days, uint32_t* seconds);
}
The optional AbortCheckFn callback (e.g., bool check_quit()) lets terminal/GUI apps cancel a fetch in progress (return true to abort).
HTTP Wrapper (http/http.hpp)
The MontaukAI dev environment includes a higher-level HTTP wrapper built on top of tls::https_fetch(). It handles DNS, request building, TLS, and response parsing automatically. See the "Networking and HTTPS" section in gui-apps.md for full documentation and examples.
#include <http/http.hpp>
tls::TrustAnchors tas = tls::load_trust_anchors();
auto resp = http::get("api.example.com", "/v1/data", tas);
if (resp.status == 200) { /* resp.body, resp.body_len */ }
http::free_response(&resp);
auto resp2 = http::post("api.example.com", "/v1/submit",
"application/json", json, jsonLen, tas);
http::free_response(&resp2);
Audio
int audio_open(uint32_t sampleRate, uint8_t channels, uint8_t bitsPerSample);
int audio_close(int handle);
int audio_write(int handle, const void* data, uint32_t size); // Write PCM samples
int audio_ctl(int handle, int cmd, int value); // Generic control
Convenience Wrappers
int audio_set_volume(int handle, int percent); // 0-100
int audio_get_volume(int handle);
int audio_pause(int handle);
int audio_resume(int handle);
int audio_get_pos(int handle); // Playback position
int audio_get_output(int handle); // Current output device
int audio_bt_status(int handle); // Bluetooth audio status
Bluetooth
int bt_scan(BtScanResult* buf, int maxCount, uint32_t timeoutMs); // Scan for devices
int bt_connect(const uint8_t* bdAddr); // Connect
int bt_disconnect(const uint8_t* bdAddr); // Disconnect
int bt_list(BtDevInfo* buf, int maxCount); // List connected devices
int bt_info(BtAdapterInfo* buf); // Adapter info
Timekeeping
uint64_t get_ticks(); // CPU tick counter
uint64_t get_milliseconds(); // Milliseconds since boot
void gettime(montauk::abi::DateTime* out); // Wall-clock time
DateTime struct:
struct DateTime {
uint16_t year;
uint8_t month, day, hour, minute, second;
uint8_t weekday;
};
System Information
void get_info(SysInfo* info); // CPU, memory, system info
void memstats(MemStats* out); // Memory usage statistics
int64_t getrandom(void* buf, uint32_t len); // Cryptographic random bytes
void reset(); // System reset (noreturn)
void shutdown(); // System shutdown (noreturn)
Storage and Disks
int partlist(PartInfo* buf, int max); // List GPT partitions
int disk_read(int blockDev, uint64_t lba, uint32_t sectorCount, void* buf); // Raw sector read
int disk_write(int blockDev, uint64_t lba, uint32_t sectorCount, const void* buf); // Raw sector write
int gpt_init(int blockDev); // Initialize GPT
int gpt_add(const GptAddParams* params); // Add partition
int fs_mount(int partIndex, int driveNum); // Mount filesystem
int fs_format(const FsFormatParams* params); // Format filesystem
int diskinfo(DiskInfo* buf, int port); // Get disk info
int devlist(DevInfo* buf, int max); // List block devices
Terminal
For terminal-mode (non-GUI) applications:
void termsize(int* cols, int* rows); // Get terminal dimensions
void termscale(int scale_x, int scale_y); // Set text scaling
void get_termscale(int* scale_x, int* scale_y); // Get text scaling
Process I/O Redirection
For launching child processes with redirected I/O (used by the terminal emulator):
int spawn_redir(const char* path, const char* args); // Spawn with I/O pipes
int childio_read(int childPid, char* buf, int maxLen); // Read child stdout
int childio_write(int childPid, const char* data, int len); // Write to child stdin
int childio_writekey(int childPid, const montauk::abi::KeyEvent* key); // Send keystroke to child
int childio_settermsz(int childPid, int cols, int rows); // Set child terminal size
Configuration
Header: montauk/config.h
TOML-based configuration stored in 0:/config/. Provides per-system and per-user config files.
toml::Doc config::load(const char* name); // Load 0:/config/<name>.toml
int config::save(const char* name, toml::Doc* doc); // Save config (0 = success)
toml::Doc config::load_user(const char* username, const char* name); // Per-user config
int config::save_user(const char* username, const char* name, toml::Doc* doc);
void config::set_string(toml::Doc* doc, const char* key, const char* val);
void config::set_int(toml::Doc* doc, const char* key, int64_t val);
void config::set_bool(toml::Doc* doc, const char* key, bool val);
bool config::unset(toml::Doc* doc, const char* key);
Example
auto doc = montauk::config::load("desktop");
const char* theme = doc.get_string("appearance.theme", "light");
montauk::config::set_string(&doc, "appearance.theme", "dark");
montauk::config::save("desktop", &doc);
User Management
Header: montauk/user.h
User authentication and session management with SHA-256 password hashing.
bool user::authenticate(const char* username, const char* password);
bool user::create_user(const char* username, const char* display_name,
const char* password, const char* role);
bool user::delete_user(const char* username);
bool user::change_password(const char* username, const char* new_password);
void user::set_session(const char* username); // Log in
void user::clear_session(); // Log out
bool user::get_session_username(char* buf, int sz); // Get current process user
bool user::get_home_dir(char* buf, int sz); // Get current process home directory
Utility Libraries
String Functions (montauk/string.h)
int slen(const char* s);
bool streq(const char* a, const char* b);
bool starts_with(const char* str, const char* prefix);
void memcpy(void* dst, const void* src, uint64_t n);
void memmove(void* dst, const void* src, uint64_t n);
void memset(void* dst, int val, uint64_t n);
void strcpy(char* dst, const char* src);
void strncpy(char* dst, const char* src, int max);
Heap (montauk/heap.h)
void* malloc(uint64_t size);
void mfree(void* ptr);
void* realloc(void* ptr, uint64_t size);