OS Time

The global os table provides timestamps, date formatting, elapsed-time measurement, and time-difference calculations. In a workflow, current-time reads use the workflow's time reference; outside a workflow they use the system clock.

This is an API reference. Timestamp literals and formatted outputs are illustrative; current values depend on the runtime or workflow clock and timezone.

Loading

The os table is global and does not require loading with require.

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

Getting Timestamps

Read a Unix timestamp in seconds since January 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

With no arguments, os.time() returns the current Unix timestamp.

When called with a table, missing fields use the defaults shown above. The year, month, and day fields use the current date when omitted.

-- 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 a string or return its date fields in a 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
%W 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 the format is "*t", os.date() 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 true when the zone's UTC offset is nonzero in this release; not a reliable DST indicator false

Use "!*t" for UTC date table.

Measuring Elapsed Time

Read the seconds between the current runtime time reference and the OS-time module's initialization time:

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

Unlike standard Lua's CPU-time definition, this implementation is based on elapsed time. In workflows, it uses the workflow time reference.

Time Difference

Calculate the 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

The result is t2 - t1 in seconds and is negative when t1 > t2.

Platform Constant

The os.platform constant identifies the runtime:

os.platform  -- "wippy"