osLua

The os library gets high precision timestamps and formats dates. If you're confused why this library is named os, it's because Lua 5.1 has functions like os.execute and os.remove which could execute arbitrary shell commands and remove files. Luau removed those functions, leaving only the time handling ones for sandboxing purposes.

It has no access to files, processes or environment variables. Instead, Luau and Luwu runtimes provide their own libraries:

Summary
os.clockLua
Returns a high-precision timestamp in seconds
os.dateLua
Formats a timestamp as a date string or table
os.difftimeLuadeprecated
Returns the difference between two timestamps in seconds
os.timeLua
Returns the current time or a date's Unix timestamp

os.clockLua

function os.clock(): number

Returns a high-precision timestamp in seconds. Its starting point isn't defined and only the difference between two calls means anything. The precision is better than a microsecond.

Input
const start = os.clock()
local total = 0
for i = 1, 100_000 do
    total += i
end
const elapsed = os.clock() - start
print(elapsed < 1)
Output
true

os.dateLua

function os.date(format: string?, time: number?): string
function os.date(format: "*t" | "!*t", time: number?): {
    year: number,
    month: number,
    day: number,
    hour: number,
    min: number,
    sec: number,
    wday: number,
    yday: number,
    isdst: boolean,
}

Formats the Unix timestamp time (the current time by default) as a date. A format starting with ! gives the date in UTC and any other format uses the local time zone. Before 1970, only UTC works: a negative time in the local time zone gives nil.

With "*t" or "!*t", the result is a table:

Any other format is a strftime format string. The specifiers are %a %A %b %B %c %d %H %I %j %m %M %p %S %U %w %W %x %X %y %Y %z %Z %% and any other specifier raises an error. The default format is "%c": the date and time in the host's usual notation.

Input
print(os.date("!%Y-%m-%d %H:%M", 0))
const date = os.date("!*t", 86_400 * 365)
print(`{date.year}-{date.month}-{date.day}, weekday {date.wday}`)
Output
1970-01-01 00:00
1971-1-1, weekday 6

os.difftimeLuadeprecated

function os.difftime(t2: number, t1: number?): number

Returns t2 - t1 in seconds and treats a missing t1 as 0. Because timestamps are seconds, you should probably just subtract them. Luau keeps this function around just for compatibiliity, so we so we treat that as deprecated.

Apparently Luau's builtin typedefs incorrectly have it accepting 'date' tables. Fixed in Luwu.

os.timeLua

function os.time(date: {
    year: number,
    month: number,
    day: number,
    hour: number?,
    min: number?,
    sec: number?,
    isdst: boolean?,
}?): number?

Without an argument, returns the current time as a Unix timestamp: the number of seconds since midnight UTC on 1 January 1970.

With a table, returns the timestamp of that date and time in UTC. year, month and day are required. hour defaults to 12 and min and sec default to 0. Values past their range carry over: month 13 is January of the next year and day 32 of January is 1 February. isdst has no effect. A date before 1970 gives nil.

Lua's os.time reads the table as local time. Luwu reads it as UTC and the result is the same on every machine.

Input
print(os.time({ year = 2024, month = 1, day = 1, hour = 0 }))
print(os.time({ year = 2024, month = 13, day = 1, hour = 0 }))
Output
1704067200
1735689600