OS Time

Standard Lua os time functions. Provides real wall-clock time for timestamps, date formatting, and time calculations.

Loading

Global os table. No require needed.

os.time()
os.date()
os.clock()
os.difftime()

Getting Timestamps

Get Unix timestamp (seconds since Jan 1, 1970 UTC):

-- Current timestamp
local now = os.time()  -- 1718462445

-- Specific date/time
local t = os.time({
    year = 2024,
    month = 12,
    day = 25,
    hour = 10,
    min = 30,
    sec = 0
})

Signature: os.time([spec]) -> number

Parameters:

Field Type Default Description
year number current year Four-digit year (e.g., 2024)
month number current month Month 1-12
day number current day Day of month 1-31
hour number 0 Hour 0-23
min number 0 Minute 0-59
sec number 0 Second 0-59

When called with no arguments, returns current Unix timestamp.

When called with a table, any missing field uses defaults shown above. The year, month, and day fields default to current date if not specified.

-- Just date (time defaults to midnight)
os.time({year = 2024, month = 6, day = 15})

-- Partial (fills in current year/month)
os.time({day = 1})  -- first of current month

Formatting Dates

Format a timestamp as string or return a date table:

local now = os.time()

-- Default format os.date() -- "Sat Jun 15 14:30:45 2024"

-- Custom format os.date("%Y-%m-%d", now) -- "2024-06-15" os.date("%H:%M:%S", now) -- "14:30:45" os.date("%Y-%m-%dT%H:%M:%S", now) -- "2024-06-15T14:30:45"

-- UTC time (prefix format with !) os.date("!%Y-%m-%d %H:%M:%S", now) -- UTC instead of local

-- Date table local t = os.date("*t", now)

Signature: os.date([format], [timestamp]) -> string | table

Parameter Type Default Description
format string "%c" Format string, "*t" for table
timestamp number current time Unix timestamp to format

Format Specifiers

Code Output Example
%Y 4-digit year 2024
%y 2-digit year 24
%m Month (01-12) 06
%d Day (01-31) 15
%H Hour 24h (00-23) 14
%I Hour 12h (01-12) 02
%M Minute (00-59) 30
%S Second (00-59) 45
%p AM/PM PM
%A Weekday name Saturday
%a Weekday short Sat
%B Month name June
%b Month short Jun
%w Weekday (0-6, Sunday=0) 6
%j Day of year (001-366) 167
%U ISO 8601 week number (01-53, week starts Monday) 24
%z Timezone offset -0700
%Z Timezone name PDT
%c Full date/time Sat Jun 15 14:30:45 2024
%x Date only 06/15/24
%X Time only 14:30:45
%% Literal % %

Date Table

When format is "*t", returns a table:

local t = os.date("*t")
Field Type Description Example
year number Four-digit year 2024
month number Month (1-12) 6
day number Day of month (1-31) 15
hour number Hour (0-23) 14
min number Minute (0-59) 30
sec number Second (0-59) 45
wday number Weekday (1-7, Sunday=1) 7
yday number Day of year (1-366) 167
isdst boolean Daylight saving time false

Use "!*t" for UTC date table.

Measuring Elapsed Time

Get seconds elapsed since Lua runtime started:

local start = os.clock()

-- do work
for i = 1, 1000000 do end

local elapsed = os.clock() - start
print(string.format("Took %.3f seconds", elapsed))

Signature: os.clock() -> number

Time Difference

Get difference between two timestamps in seconds:

local t1 = os.time({year = 2024, month = 1, day = 1})
local t2 = os.time({year = 2024, month = 12, day = 31})

local diff = os.difftime(t2, t1)  -- t2 - t1
local days = diff / 86400
print(days)  -- 365

Signature: os.difftime(t2, t1) -> number

Parameter Type Description
t2 number Later timestamp
t1 number Earlier timestamp

Returns t2 - t1 in seconds. Can be negative if t1 > t2.

Platform Constant

Constant identifying the runtime:

os.platform  -- "wippy"