Collapse Sidebar


This library currently serves the purpose of providing information about the system time under the UTC format. It has been heavily sandboxed from the standard Lua os library and does not allow you to perform any system-altering operations.

int os.time ( table time = UTC time )

Returns how many seconds have passed since the Unix epoch (1 January 1970, 00:00:00), under current UTC time. If provided a table formatted similarly to that returned by os.date, it will return the number of seconds since that time instead.

print(os.time()) --> 1586982482 (ran at approx. April 15th, 2020 at 1:28 PM PST)
   year=2020, month=4, day=15, -- Date components
   hour=16, min=28, sec=0 -- Time components
})) --> 1586968080
int os.difftime ( int t2, int t1 )

Returns the number of seconds from t1 to t2. The difference is computed assuming that t1 and t2 are correctly casted to the time_t format.

dictionary os.date ( string formatString, int time )

Formats the given formatString with date/time information based on the given time, or if not provided, the value returned by os.time. The following specifiers (based on the C function strftime) are supported:

Specifier Meaning Example
%aAbbreviated weekday name * Wed
%AFull weekday name * Wednesday
%bAbbreviated month name * Sep
%BFull month name * September
%cDate and time * 09/16/98 23:48:10
%dDay of the month 16
%HHour, using 24-hour clock23
%IHour, using 12-hour clock11
%jDay of year 259
%mMonth 09
%MMinute 48
%pEither "am" or "pm" pm
%SSecond 10
%UWeek number (first Sunday as the first day of week one)37
%wWeekday 3
%WWeek number (first Monday as the first day of week one)37
%xDate * 09/16/98
%XTime * 23:48:10
%yTwo-digit year 98
%YFull year 1998
%zISO 8601 offset from UTC in timezone (1 minute = 1, 1 hour = 100)-0400
%ZTimezone name or abbreviation *Eastern Daylight Time
%%The % character %

* This value can vary depending on the current locale.
† The example provided is for September 16th, 1998 (a Wednesday) at 11:48:10 PM (23:48:10), ran using locale “en-us” in Eastern Time (ET).

If the provided formatString is exactly "*t" (local time) or "!*t" (UTC time), this function instead returns a dictionary containing the following components, which are normally available in the specifiers above.

Field Type Description
year int An integer that describes the current year of the Current Era (ex. 2017)
month int An integer between 1 and 12 (starting from January) that describes the current month.
wday int An integer between 1 and 7 (starting from Sunday) that describes the current week day.
yday int An integer between 1 and 366 describing how many days we are into the year.
There can be 366 days if it is a leap year.
day int An integer between 1 and 31 describing the current day of the month.
hour int An integer between 1 and 24 describing the current hour of the day.
min int An integer between 0 and 59 describing the current minute of the hour.
sec int An integer between 0 and 60 describing the current second of the hour.
(60 because the function is described to indicate leap seconds, but in practice it probably doesn't).
isdst bool A boolean describing if daylight savings time is currently active.

os.date format string

This code sample uses os.date to format a given timestamp representing September 16th, 1998 at 11:48:10 PM into a string.

os.date format table

This code sample uses os.date to format a given timestamp representing September 16th, 1998 at 11:48:10 PM into a table of useful information.

os.clock ( )

Returns the amount of CPU time used by Lua in seconds. This value has high precision, about 1 microsecond, and is intended for use in benchmarking.

-- Record the initial time:
local startTime = os.clock()
-- Do something you want to measure the performance of:
local a, b = 0, 1
for i = 1, 5000000 do
    a, b = b, a
-- Measure amount of time this took:
local deltaTime = os.clock() - startTime
print("Elapsed time: " .. deltaTime)
-->  Elapsed time: 0.044425600033719 (actual number may vary)