Time function improvements (fix #1912)

configure.ac

@@ -140,14 +140,21 @@ AC_FIND_FUNC([strptime], [c], [#include <time.h>], [0, 0, 0])
 AC_FIND_FUNC([strftime], [c], [#include <time.h>], [0, 0, 0, 0])
 AC_FIND_FUNC([setenv], [c], [#include <stdlib.h>], [0, 0, 0])
 AC_FIND_FUNC([timegm], [c], [#include <time.h>], [0])
+AC_FIND_FUNC([timelocal], [c], [#include <time.h>], [0])
 AC_FIND_FUNC([gmtime_r], [c], [#include <time.h>], [0, 0])
 AC_FIND_FUNC([gmtime], [c], [#include <time.h>], [0])
 AC_FIND_FUNC([localtime_r], [c], [#include <time.h>], [0, 0])
 AC_FIND_FUNC([localtime], [c], [#include <time.h>], [0])
+AC_FIND_FUNC([mktime], [c], [#include <time.h>], [0])
+AC_FIND_FUNC([_mkgmtime], [c], [#include <time.h>], [0])
+AC_FIND_FUNC([difftime], [c], [#include <time.h>], [0, 0])
 AC_FIND_FUNC([gettimeofday], [c], [#include <sys/time.h>], [0, 0])
-AC_CHECK_MEMBER([struct tm.tm_gmtoff], [AC_DEFINE([HAVE_TM_TM_GMT_OFF],1,[Define to 1 if the system has the tm_gmt_off field in struct tm])],
+AC_STRUCT_TIMEZONE
+AC_CHECK_MEMBER([struct tm.tm_gmtoff], [AC_DEFINE([HAVE_TM_TM_GMTOFF],1,[Define to 1 if the system has the tm_gmtoff field in struct tm])],
                 [], [[#include <time.h>]])
-AC_CHECK_MEMBER([struct tm.__tm_gmtoff], [AC_DEFINE([HAVE_TM___TM_GMT_OFF],1,[Define to 1 if the system has the __tm_gmt_off field in struct tm])],
+AC_CHECK_MEMBER([struct tm.__tm_gmtoff], [AC_DEFINE([HAVE_TM___TM_GMTOFF],1,[Define to 1 if the system has the __tm_gmtoff field in struct tm])],
+                [], [[#include <time.h>]])
+AC_CHECK_MEMBER([struct tm.tm_zone], [AC_DEFINE([HAVE_TM_TM_ZONE],1,[Define to 1 if the system has the tm_zone field in struct tm])],
                 [], [[#include <time.h>]])
 AC_FIND_FUNC([setlocale], [c], [#include <locale.h>], [0,0])
 

docs/content/manual/manual.yml

@@ -2187,10 +2187,11 @@ sections:
 
           Low-level jq interfaces to the C-library time functions are
           also provided: `strptime`, `strftime`, `strflocaltime`,
-          `mktime`, `gmtime`, and `localtime`.  Refer to your host
-          operating system's documentation for the format strings used
-          by `strptime` and `strftime`.  Note: these are not necessarily
-          stable interfaces in jq, particularly as to their localization
+          `mktime`, `gmtime`, `localtime`, `timegm`, and
+          `timelocal`.  Refer to your host operating system's
+          documentation for the format strings used by `strptime`
+          and `strftime`.  Note: these are not necessarily stable
+          interfaces in jq, particularly as to their localization
           functionality.
 
           The `gmtime` builtin consumes a number of seconds since the
@@ -2199,15 +2200,27 @@ sections:
           (in this order): the year, the month (zero-based), the day of
           the month (one-based), the hour of the day, the minute of the
           hour, the second of the minute, the day of the week, and the
-          day of the year -- all one-based unless otherwise stated.  The
-          day of the week number may be wrong on some systems for dates
-          before March 1st 1900, or after December 31 2099.
+          day of the year -all one-based unless otherwise stated-
+          followed by (depending on platform support) a boolean
+          indicating whether the time is in a daylight savings
+          timezone, followed by the offset to UTC, followed by the
+          name of the timezone.  The day of the week number may be
+          wrong on some systems for dates before March 1st 1900, or
+          after December 31 2099.
 
           The `localtime` builtin works like the `gmtime` builtin, but
           using the local timezone setting.
 
-          The `mktime` builtin consumes "broken down time"
-          representations of time output by `gmtime` and `strptime`.
+          The `mktime`, `timegm` and `timelocal` builtins do the
+          opposite of `gmtime` and `localtime`, respectively: they
+          consume "broken down time" representations of time
+          output by `gmtime`, `localtime`, and `strptime`, and
+          output a number of seconds since the Unix epoch.
+
+          Note that the C `mktime()` function interprets its broken
+          down time input as local time, while the jq `mktime`
+          function interpretes its broken down time as UTC.  It is
+          better to use `timelocal` and `timegm` to avoid confusion.
 
           The `strptime(fmt)` builtin parses input strings matching the
           `fmt` argument.  The output is in the "broken down time"
@@ -2230,11 +2243,11 @@ sections:
             input: '"2015-03-05T23:51:47Z"'
             output: ['1425599507']
 
-          - program: 'strptime("%Y-%m-%dT%H:%M:%SZ")'
+          - program: 'strptime("%Y-%m-%dT%H:%M:%SZ")[0:8]'
             input: '"2015-03-05T23:51:47Z"'
             output: ['[2015,2,5,23,51,47,4,63]']
 
-          - program: 'strptime("%Y-%m-%dT%H:%M:%SZ")|mktime'
+          - program: 'strptime("%Y-%m-%dT%H:%M:%SZ")|timegm'
             input: '"2015-03-05T23:51:47Z"'
             output: ['1425599507']