# Module `posix.time`

Time and Clock Functions.

## Functions

clock_getres (clk) | Find the precision of a clock.
clock_gettime (clk) | Read a clock.
gmtime (t) | Convert epoch time value to a broken-down UTC time.
localtime (t) | Convert epoch time value to a broken-down local time.
mktime (broken) | Convert a broken-down localtime table into an epoch time.
nanosleep (requested) | Sleep with nanosecond precision.
strftime (format, tm) | Return a time string according to format.
strptime (s, format) | Parse a date string.
time () | Get current time.

## Tables

PosixTimespec | Timespec record.
PosixTm | Datetime record.

## Constants

posix.time | Standard constants.

## Functions

clock_getres (clk)
  Find the precision of a clock.

  ### Parameters:

  - clk int name of clock, one of `CLOCK_REALTIME`, `CLOCK_PROCESS_CPUTIME_ID`, `CLOCK_MONOTONIC` or `CLOCK_THREAD_CPUTIME_ID`

  ### Returns:

  PosixTimespec resolution of clk, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  clock_getres(3)
clock_gettime (clk)
  Read a clock.

  ### Parameters:

  - clk int name of clock, one of `CLOCK_REALTIME`, `CLOCK_PROCESS_CPUTIME_ID`, `CLOCK_MONOTONIC` or `CLOCK_THREAD_CPUTIME_ID`

  ### Returns:

  PosixTimespec current value of clk, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  clock_gettime(3)
gmtime (t)
  Convert epoch time value to a broken-down UTC time.

  ### Parameters:

  - t int seconds since epoch

  ### Returns:

  PosixTm broken-down time, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  gmtime(3)
localtime (t)
  Convert epoch time value to a broken-down local time.

  ### Parameters:

  - t int seconds since epoch

  ### Returns:

  PosixTm broken-down time, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  - localtime(3)
  - mktime
mktime (broken)
  Convert a broken-down localtime table into an epoch time.

  ### Parameters:

  - broken PosixTm -down localtime

  ### Returns:

  int seconds since epoch

  ### See also:

  - mktime(3)
  - localtime
nanosleep (requested)
  Sleep with nanosecond precision.

  ### Parameters:

  - requested PosixTimespec sleep time

  ### Returns:

  int `0` if requested time has elapsed, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum
  4. PosixTimespec unslept time remaining, if interrupted

  ### See also:

  - nanosleep(2)
  - posix.unistd.sleep
strftime (format, tm)
  Return a time string according to format. Note that if your host POSIX library provides a `strftime` that assumes the local timezone, %z will always print the local UTC offset, regardless of the `tm_gmoffset` field value passed in.

  ### Parameters:

  - format string specifier with `%` place-holders
  - tm PosixTm broken-down local time

  ### Returns:

  string format with place-holders plugged with tm values

  ### See also:

  strftime(3)
strptime (s, format)
  Parse a date string.

  ### Parameters:

  - s string
  - format string same as for `strftime`

  ### Returns:

  1. PosixTm broken-down local time
  2. int next index of first character not parsed as part of the date, if successful

  ### Or

  nil

  ### See also:

  strptime(3)

  ### Usage:

      posix.strptime('20','%d').monthday == 20

time ()
  Get current time.

  ### Returns:

  int time in seconds since epoch, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  time(2)

## Tables

PosixTimespec
  Timespec record.

  ### Fields:

  - tv_sec int seconds
  - tv_nsec int nanoseconds

  ### See also:

  posix.sys.time.PosixTimeval
PosixTm
  Datetime record.

  ### Fields:

  - tm_sec int second [0,60]
  - tm_min int minute [0,59]
  - tm_hour int hour [0,23]
  - tm_mday int day of month [1, 31]
  - tm_mon int month of year [0,11]
  - tm_year int years since 1900
  - tm_wday int day of week [0=Sunday,6]
  - tm_yday int day of year [0,365[
  - tm_isdst int 0 if daylight savings time is not in effect

## Constants

posix.time
  Standard constants. Any constants not available in the underlying system will be `nil` valued.

  ### Fields:

  - CLOCK_MONOTONIC int the identifier for the system-wide monotonic clock
  - CLOCK_PROCESS_CPUTIME_ID int the identifier for the current process CPU-time clock
  - CLOCK_REALTIME int the identifier for the system-wide realtime clock
  - CLOCK_THREAD_CPUTIME_ID int the identifier for the current thread CPU-time clock

  ### Usage:

      -- Print posix.time constants supported on this host.
      for name, value in pairs (require "posix.time") do
        if type (value) == "number" then
          print (name, value)
         end
      end

generated by LDoc 1.5.0 Last updated 2025-02-16 13:16:41