Luau Bindings — `os`

The require("os") script API. Time and process functions are stock Luau, untouched — a Lua programmer gets the time exactly as they always have. On top of that, AntOS restores the sandboxed host functions and adds the OS's own surface: script control, the hardware clock (os.rtc), settings (os.settings), DBFS volumes (os.dbfs), and the shadow backup (os.shadow). Design & native core: antos_os; the contract that governs it: antos_library_design §5.

local now = os.time()          -- os is a global; no require needed

Tagged [standard] or [antos].

Time & date — all `[standard]`

The stock Luau implementations. AntOS does not touch them.

Function	Behaviour
`os.time([tbl])`	Epoch now, or convert a broken-down table.
`os.date([fmt [, time]])`	Format `time` (default now); `"t"`/`"!t"` tables, `strftime` strings.
`os.clock()`	Process CPU seconds (float) — the benchmarking delta.
`os.difftime(t2, t1)`	Seconds between two `os.time` values.

Fixed deviation: the ESP32-P4 os.clock() returned monotonic wall-time — non-standard. In the rewrite os.clock() with no argument is stock CPU seconds. The other clocks have their canonical home on sys (sys.monotonic, sys.uptime), and os.clock also takes an optional source argument as a convenience:

`os.clock([source])` — clock-source extension `[antos]`

Call	Returns
`os.clock()`	`[standard]` process CPU seconds — unchanged; portable code never passes an argument
`os.clock("monotonic")`	monotonic seconds, never jumps (= `sys.monotonic()`)
`os.clock("uptime")`	seconds since boot (= `sys.uptime()`)
`os.clock("wall")`	high-resolution real time in seconds (a float `os.time`)

The bare call stays exactly standard; the optional string is the AntOS extension, following the same "add an optional argument, never redefine" rule as io.open's tags (antos_library_design §6).

Host functions — restored, `[standard]`

Function	Behaviour
`os.getenv(name)` · `os.remove(path)` · `os.rename(from, to)` · `os.tmpname()` · `os.exit([code])`	The sandboxed host functions, restored with reference signatures (`value`, or `nil, msg`). Paths are drive-letter paths.

Scripts & processes — `[antos]`

Function	Behaviour
`os.arguments(spec)`	The declarative CLI parser every command uses (`*main`/`+value`/`-flag`, auto `?` help — see Quickstart).
`os.run(name, argv)`	Run a command and wait → `{ ok, out, rc, err }`.
`os.spawn(name, argv)`	Start in the background → `{ ok, taskName }`.
`os.exec(cmd)`	Run a command line through the shell.
`os.script_path()`	Path of the running script.
`os.read_script(name)`	The source of a script on the path.
`os.scripts()` · `os.rescan_scripts()`	List script metadata / re-scan the script dirs.

System clock — `[antos]`

Function	Behaviour
`os.set_time(epoch)` or `os.set_time{ year=…, month=…, … }`	Set the system clock. (`os.time`/`os.date` read it, standard.)

Setting the system clock also writes through to the hardware RTC below; the network side is net.ntp_sync.

`os.rtc.*` — the battery-backed hardware clock (MCP79410)

Function	Behaviour
`os.rtc.now()`	Read the RTC → epoch.
`os.rtc.set(epoch \\| fields)`	Set the RTC.
`os.rtc.valid()` · `os.rtc.running()` · `os.rtc.ready()`	Oscillator / validity / bus state.
`os.rtc.status()`	Full status — `{ valid, running, ready, unix, system_unix, … }`.
`os.rtc.serial()`	The chip's unique serial / EUI-48.
`os.rtc.sram_read(off, len)` · `os.rtc.sram_write(off, data)`	The RTC's battery-backed SRAM (raw bytes).
`os.rtc.sram_read_str` · `os.rtc.sram_write_str`	String helpers over SRAM.
`os.rtc.get_ntp_server()` · `os.rtc.set_ntp_server(host)`	The NTP server persisted in RTC SRAM (survives power loss).

Constants: os.rtc.SRAM_SIZE, os.rtc.SRAM_MAGIC_OFF, os.rtc.SRAM_FLAGS_OFF, os.rtc.SRAM_NTP_OFF.

Settings — `os.settings.*` `[antos]`

Read/write config values, and register your own page in the Settings window.

Function	Behaviour
`os.settings.get(key)` · `os.settings.set(key, value)`	Read / write a config value.
`os.settings.toggle(key)`	Flip a boolean setting.
`os.settings.save()`	Persist changes to DBFS.
`os.settings.open()`	Open the local Settings window.
`os.settings.page(title, draw)`	Register a settings tab → a handle. `draw` is a per-frame imgui callback that renders the page's controls when the tab is active; removed when the owner unloads.

The Settings window is a registry, not a fixed list of tabs — pages register themselves, so a library or script adds its own tab and it appears alongside the system pages:

os.settings.page("My Tool", function()
  local changed, v = imgui.checkbox("Enable feature", os.settings.get("mytool.enable"))
  if changed then os.settings.set("mytool.enable", v) end
end)

A page is just an imgui draw callback, so it has the full widget set — and it's the very registry the built-in pages use, so library settings and system settings are indistinguishable.

DBFS volumes — `os.dbfs.*` `[antos]`

The D: drive can hold multiple DBFS volumes; these manage which one is live. Switching changes the entire D: view, so treat it as a mount operation.

Function	Behaviour
`os.dbfs.active()`	The active volume's name.
`os.dbfs.list()`	All DBFS volumes.
`os.dbfs.switch(name)`	Make `name` the active `D:` (remounts).
`os.dbfs.create(name)`	Create a new empty volume.
`os.dbfs.fork(name, from)`	Clone an existing volume.
`os.dbfs.delete(name)`	Delete a volume.

Shadow backup — `os.shadow.*` `[antos]`

Control of the DBFS shadow backup (the paired D!: shadow — see storage).

Function	Behaviour
`os.shadow.status()`	Pairing / sync state.
`os.shadow.enable()` · `os.shadow.close()`	Bring the shadow up / down.
`os.shadow.provision()`	Set up a shadow on a fresh device.
`os.shadow.sync()`	Force a sync now.

System control — `[antos]`

Function	Behaviour
`os.reset([mode])`	Restart — `"warm"` (default; preserves the RAM-held DBFS override) or `"cold"`.
`os.hostname([name])`	Get / set the hostname.
`os.version()`	OS version / build info.
`os.is_dev_mode()`	Whether developer mode is enabled.
`os.notify(msg [, opts])`	Raise a system notification.
`os.panic(msg)`	Trigger a controlled panic (debugging).

os.uptime, os.uptimeMs, and os.heap_info from the P4 os have moved to sys (sys.uptime, sys.uptime_ms, sys.memory) — system introspection lives there now, so os stays about time, scripts, and OS control.

antos_os — design & native core · luau_sys (uptime, memory, tasks) · luau_io · luau_net (NTP) · Quickstart · AntOS Libraries hub

Luau Bindings — os

Time & date — all [standard]

os.clock([source]) — clock-source extension [antos]

Host functions — restored, [standard]

Scripts & processes — [antos]

System clock — [antos]

os.rtc.* — the battery-backed hardware clock (MCP79410)

Settings — os.settings.* [antos]

DBFS volumes — os.dbfs.* [antos]

Shadow backup — os.shadow.* [antos]

System control — [antos]

Related