From 035bef406ab2fb17a317d12cba8852a6ab4d6ed8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcel=20St=C3=B6r?= Date: Sun, 9 Feb 2020 23:50:33 +0100 Subject: [PATCH] Fix formatting and function sorting --- docs/modules/time.md | 342 ++++++++++++++++++++++--------------------- 1 file changed, 174 insertions(+), 168 deletions(-) diff --git a/docs/modules/time.md b/docs/modules/time.md index 1b46af09..fd2b245e 100644 --- a/docs/modules/time.md +++ b/docs/modules/time.md @@ -1,175 +1,9 @@ -# Timer Module +# Time/NTP Module | Since | Origin / Contributor | Maintainer | Source | | :----- | :-------------------- | :---------- | :------ | | 2018-11-25 | [Skirmantas Lauzikas](https://github.com/x-logLT) | [Skirmantas Lauzikas](https://github.com/x-logLT) | [time.c](../../components/modules/time.c)| -This module offers facilities for coverting beteen unix time and calendar, setting/getting system time, locale and controll of NTP client. - -## time.set() -Sets system time to a given timestamp in the Unix epoch (i.e. seconds from midnight 1970/01/01). - -#### Syntax -`time.set(time)` - -#### Parameters -- `time` number of seconds since the Epoch - -#### Returns -`nil' - -#### Example -```lua ---set time to 2018-11-20 01:40:50 -time.set(1542678050) -``` - -#### See also -[`time.cal2epoc()`](#timecal2epoch) - -## time.get() -Returns current system time in the Unix epoch (i.e. seconds from midnight 1970/01/01). - -#### Syntax -time.get() - -#### Parameters -none - -#### Returns -A two-value timestamp consisting of: - -- `sec` seconds since the Unix epoch -- `usec` the microseconds part - -#### Example -```lua -sec, usec = time.get() -``` - -#### See also -[`time.epch2cal()`](#timeepoch2cal) - -## time.getlocal() -Returns current system time adjusted for the locale in calendar format. - -#### Syntax -time.getlocal() - -#### Parameters -none - -#### Returns -A table containing the fields: - -- `year` 1970 ~ 2038 -- `mon` month 1 ~ 12 in current year -- `day` day 1 ~ 31 in current month -- `hour` -- `min` -- `sec` -- `yday` day 1 ~ 366 in current year -- `wday` day 1 ~ 7 in current weak (Sunday is 1) -- `dst` day time adjustment: - - 1 (DST in effect, i.e. daylight time) - - 0 (DST not in effect, i.e. standard time) - - -1 (Unknown DST status) - -#### Example -```lua -localTime = time.getlocal() -print(string.format("%04d-%02d-%02d %02d:%02d:%02d DST:%d", localTime["year"], localTime["mon"], localTime["day"], localTime["hour"], localTime["min"], localTime["sec"], localTime["dst"])) -``` - -## time.settimezone() -Sets correct format for Time Zone locale - -#### Syntax -`time.settimezone(timezone)` - -#### Parameters -- `timezone` a string representing timezone, can also include DST adjustment. For full syntax see [TZ variable documentation](http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html). - -#### Returns -`nil` - -#### Example -```lua ---set timezone to Eastern Standard Time -time.settimezone("EST+5") -``` - -## time.initntp() -Initializes and starts ntp client - -#### Syntax -`time.initntp([ntpAddr])` - -#### Parameters -- `ntpAddr` address of a ntp server, defaults to "pool.ntp.org" if none is specified - -#### Returns -`nil` - -#### Example -```lua -time.initntp("pool.ntp.org") -``` - -## time.ntpenabled() -Checks if ntp client is enabled. - -#### Syntax -`time.ntpenabled()` - -#### Parameters -none - -#### Returns -`true' if ntp client is enabled. - -## time.ntpstop() -Stops ntp client. - -#### Syntax -`time.ntpstop()` - -#### Parameters -none - -#### Returns -`nil` - -## time.epoch2cal() -Converts timestamp in Unix epoch to calendar format - -#### Syntax -`time.epoch2cal(time) - -#### Parameters -- `time` number of seconds since the Epoch - -#### Returns -A table containing the fields: - -- `year` 1970 ~ 2038 -- `mon` month 1 ~ 12 in current year -- `day` day 1 ~ 31 in current month -- `hour` -- `min` -- `sec` -- `yday` day 1 ~ 366 in current year -- `wday` day 1 ~ 7 in current weak (Sunday is 1) -- `dst` day time adjustment: - - 1 (DST in effect, i.e. daylight time) - - 0 (DST not in effect, i.e. standard time) - - -1 (Unknown DST status) - -#### Example -```lua ---Gets current time calendar format, no locale adjustment -time = time.epoch2cal(time.get()) -print(string.format("%04d-%02d-%02d %02d:%02d:%02d DST:%d", time["year"], time["mon"], time["day"], time["hour"], time["min"], time["sec"], time["dst"])) -``` +This module offers facilities for converting between Unix time and calendar, setting/getting system time, locale and control of NTP client. ## time.cal2epoch() Converts calendar table to a timestamp in Unix epoch @@ -204,3 +38,175 @@ timestamp = time.cal2epoch(calendar) time.set(timestamp) ``` + +## time.epoch2cal() +Converts timestamp in Unix epoch to calendar format + +#### Syntax +`time.epoch2cal(time) + +#### Parameters +- `time` number of seconds since the Epoch + +#### Returns +A table containing the fields: + +- `year` 1970 ~ 2038 +- `mon` month 1 ~ 12 in current year +- `day` day 1 ~ 31 in current month +- `hour` +- `min` +- `sec` +- `yday` day 1 ~ 366 in current year +- `wday` day 1 ~ 7 in current weak (Sunday is 1) +- `dst` day time adjustment: + - 1 (DST in effect, i.e. daylight time) + - 0 (DST not in effect, i.e. standard time) + - -1 (Unknown DST status) + +#### Example +```lua +--Gets current time calendar format, no locale adjustment +time = time.epoch2cal(time.get()) +print(string.format("%04d-%02d-%02d %02d:%02d:%02d DST:%d", time["year"], time["mon"], time["day"], time["hour"], time["min"], time["sec"], time["dst"])) +``` + + +## time.get() +Returns current system time in the Unix epoch (seconds from midnight 1970/01/01). + +#### Syntax +time.get() + +#### Parameters +none + +#### Returns +A two-value timestamp consisting of: + +- `sec` seconds since the Unix epoch +- `usec` the microseconds part + +#### Example +```lua +sec, usec = time.get() +``` + +#### See also +[`time.epch2cal()`](#timeepoch2cal) + + +## time.getlocal() +Returns current system time adjusted for the locale in calendar format. + +#### Syntax +time.getlocal() + +#### Parameters +none + +#### Returns +A table containing the fields: + +- `year` 1970 ~ 2038 +- `mon` month 1 ~ 12 in current year +- `day` day 1 ~ 31 in current month +- `hour` +- `min` +- `sec` +- `yday` day 1 ~ 366 in current year +- `wday` day 1 ~ 7 in current weak (Sunday is 1) +- `dst` day time adjustment: + - 1 (DST in effect, i.e. daylight time) + - 0 (DST not in effect, i.e. standard time) + - -1 (Unknown DST status) + +#### Example +```lua +localTime = time.getlocal() +print(string.format("%04d-%02d-%02d %02d:%02d:%02d DST:%d", localTime["year"], localTime["mon"], localTime["day"], localTime["hour"], localTime["min"], localTime["sec"], localTime["dst"])) +``` + +## time.initntp() +Initializes and starts NTP client + +#### Syntax +`time.initntp([ntpAddr])` + +#### Parameters +- `ntpAddr` address of a NTP server, defaults to "pool.ntp.org" if none is specified + +#### Returns +`nil` + +#### Example +```lua +time.initntp("pool.ntp.org") +``` + + +## time.ntpenabled() +Checks if NTP client is enabled. + +#### Syntax +`time.ntpenabled()` + +#### Parameters +none + +#### Returns +`true' if NTP client is enabled. + + +## time.ntpstop() +Stops NTP client. + +#### Syntax +`time.ntpstop()` + +#### Parameters +none + +#### Returns +`nil` + + +## time.set() +Sets system time to a given timestamp in the Unix epoch (seconds from midnight 1970/01/01). + +#### Syntax +`time.set(time)` + +#### Parameters +- `time` number of seconds since the Epoch + +#### Returns +`nil` + +#### Example +```lua +--set time to 2018-11-20 01:40:50 +time.set(1542678050) +``` + +#### See also +[`time.cal2epoc()`](#timecal2epoch) + + +## time.settimezone() +Sets correct format for Time Zone locale + +#### Syntax +`time.settimezone(timezone)` + +#### Parameters +- `timezone` a string representing timezone, can also include DST adjustment. For full syntax see [TZ variable documentation](http://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html). + +#### Returns +`nil` + +#### Example +```lua +--set timezone to Eastern Standard Time +time.settimezone("EST+5") +```