date.h File Reference

Time and date handling routines. More...

#include <locale.h>
#include <stdbool.h>
#include <stdint.h>
#include <time.h>

Include dependency graph for date.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Tz
	List of recognised Timezones. More...

Macros
#define	TIME_T_MAX   ((((time_t) 1 << (sizeof(time_t) * 8 - 2)) - 1) * 2 + 1)
#define	TIME_T_MIN   (-TIME_T_MAX - 1)
#define	TM_YEAR_MAX    (1970 + (((((TIME_T_MAX - 59) / 60) - 59) / 60) - 23) / 24 / 366)
#define	TM_YEAR_MIN   (1970 - (TM_YEAR_MAX - 1970) - 1)

Functions
time_t	mutt_date_add_timeout (time_t now, time_t timeout)
	Safely add a timeout to a given time_t value.
int	mutt_date_check_month (const char *s)
	Is the string a valid month name.
time_t	mutt_date_now (void)
	Return the number of seconds since the Unix epoch.
uint64_t	mutt_date_now_ms (void)
	Return the number of milliseconds since the Unix epoch.
struct tm	mutt_date_gmtime (time_t t)
	Converts calendar time to a broken-down time structure expressed in UTC timezone.
size_t	mutt_date_localtime_format (char *buf, size_t buflen, const char *format, time_t t)
	Format localtime.
size_t	mutt_date_localtime_format_locale (char *buf, size_t buflen, const char *format, time_t t, locale_t loc)
	Format localtime using a given locale.
struct tm	mutt_date_localtime (time_t t)
	Converts calendar time to a broken-down time structure expressed in user timezone.
int	mutt_date_local_tz (time_t t)
	Calculate the local timezone in seconds east of UTC.
void	mutt_date_make_date (struct Buffer *buf, bool local)
	Write a date in RFC822 format to a buffer.
int	mutt_date_make_imap (struct Buffer *buf, time_t timestamp)
	Format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz.
time_t	mutt_date_make_time (struct tm *t, bool local)
	Convert struct tm to time_t
int	mutt_date_make_tls (char *buf, size_t buflen, time_t timestamp)
	Format date in TLS certificate verification style.
void	mutt_date_normalize_time (struct tm *tm)
	Fix the contents of a struct tm.
time_t	mutt_date_parse_date (const char *s, struct Tz *tz_out)
	Parse a date string in RFC822 format.
time_t	mutt_date_parse_imap (const char *s)
	Parse date of the form: DD-MMM-YYYY HH:MM:SS +ZZzz.
void	mutt_date_sleep_ms (size_t ms)
	Sleep for milliseconds.
void	mutt_time_now (struct timespec *tp)
	Set the provided time field to the current time.

Detailed Description

Time and date handling routines.

Authors

• Richard Russon
• Victor Fernandes
• Pietro Cerutti

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file date.h.

Macro Definition Documentation

TIME_T_MAX

#define TIME_T_MAX   ((((time_t) 1 << (sizeof(time_t) * 8 - 2)) - 1) * 2 + 1)

Definition at line 40 of file date.h.

TIME_T_MIN

#define TIME_T_MIN   (-TIME_T_MAX - 1)

Definition at line 41 of file date.h.

TM_YEAR_MAX

#define TM_YEAR_MAX    (1970 + (((((TIME_T_MAX - 59) / 60) - 59) / 60) - 23) / 24 / 366)

Definition at line 42 of file date.h.

TM_YEAR_MIN

#define TM_YEAR_MIN   (1970 - (TM_YEAR_MAX - 1970) - 1)

Definition at line 44 of file date.h.

Function Documentation

mutt_date_add_timeout()

time_t mutt_date_add_timeout	(	time_t	now,
		time_t	timeout
	)

Safely add a timeout to a given time_t value.

Parameters

now	Time now
timeout	Timeout in seconds

Return values

num	Unix time to timeout

This will truncate instead of overflowing.

Definition at line 890 of file date.c.

{
  if (timeout < 0)
    return now;
 
  if ((TIME_T_MAX - now) < timeout)
    return TIME_T_MAX;
 
  return now + timeout;
}

Here is the caller graph for this function:

mutt_date_check_month()

int mutt_date_check_month

(

const char *

s

)

Is the string a valid month name.

Parameters

s	String to check (must be at least 3 bytes long)

Return values

num	Index into Months array (0-based)
-1	Error

Note

Only the first three characters are checked

The comparison is case insensitive

Definition at line 432 of file date.c.

{
  if (!s)
    return -1;
 
  char buf[4] = { 0 };
  memcpy(buf, s, 3);
  uint32_t sv;
  memcpy(&sv, buf, sizeof(sv));
  for (int i = 0; i < mutt_array_size(Months); i++)
  {
    uint32_t mv;
    memcpy(&mv, Months[i], sizeof(mv));
    if (sv == mv)
      return i;
  }
 
  return -1; /* error */
}

Here is the caller graph for this function:

mutt_date_now()

time_t mutt_date_now

(

void

)

Return the number of seconds since the Unix epoch.

Return values

num	Number of seconds since the Unix epoch, or 0 on failure

Definition at line 456 of file date.c.

{
  return mutt_date_now_ms() / 1000;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_now_ms()

uint64_t mutt_date_now_ms

(

void

)

Return the number of milliseconds since the Unix epoch.

Return values

num	The number of ms since the Unix epoch, or 0 on failure

Definition at line 465 of file date.c.

{
  struct timeval tv = { 0, 0 };
  gettimeofday(&tv, NULL);
  /* We assume that gettimeofday doesn't modify its first argument on failure.
   * We also kind of assume that gettimeofday does not fail. */
  return ((uint64_t) tv.tv_sec * 1000) + (tv.tv_usec / 1000);
}

Here is the caller graph for this function:

mutt_date_gmtime()

struct tm mutt_date_gmtime

(

time_t

t

)

Converts calendar time to a broken-down time structure expressed in UTC timezone.

Parameters

t

Time

Return values

obj	Broken-down time representation

Definition at line 927 of file date.c.

{
  struct tm tm = { 0 };
 
  struct tm *ret = gmtime_r(&t, &tm);
  if (!ret)
  {
    mutt_debug(LL_DEBUG1, "Could not convert time_t via gmtime_r() to struct tm: time_t = %jd\n",
               (intmax_t) t);
    struct tm default_tm = { 0 }; // 1970-01-01 00:00:00
    mktime(&default_tm); // update derived fields making tm into a valid tm.
    tm = default_tm;
  }
  return tm;
}

Here is the caller graph for this function:

mutt_date_localtime_format()

size_t mutt_date_localtime_format	(	char *	buf,
		size_t	buflen,
		const char *	format,
		time_t	t
	)

Format localtime.

Parameters

buf	Buffer to store formatted time
buflen	Buffer size
format	Format to apply
t	Time to format

Return values

num	Number of Bytes added to buffer, excluding NUL byte

Definition at line 951 of file date.c.

{
  if (!buf || !format)
    return 0;
 
  struct tm tm = mutt_date_localtime(t);
  return strftime(buf, buflen, format, &tm);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_localtime_format_locale()

size_t mutt_date_localtime_format_locale	(	char *	buf,
		size_t	buflen,
		const char *	format,
		time_t	t,
		locale_t	loc
	)

Format localtime using a given locale.

Parameters

buf	Buffer to store formatted time
buflen	Buffer size
format	Format to apply
t	Time to format
loc	Locale to use

Return values

num	Number of Bytes added to buffer, excluding NUL byte

Definition at line 969 of file date.c.

{
  if (!buf || !format)
    return 0;
 
  struct tm tm = mutt_date_localtime(t);
  return strftime_l(buf, buflen, format, &tm, loc);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_localtime()

struct tm mutt_date_localtime

(

time_t

t

)

Converts calendar time to a broken-down time structure expressed in user timezone.

Parameters

t

Time

Return values

obj	Broken-down time representation

Definition at line 906 of file date.c.

{
  struct tm tm = { 0 };
 
  struct tm *ret = localtime_r(&t, &tm);
  if (!ret)
  {
    mutt_debug(LL_DEBUG1, "Could not convert time_t via localtime_r() to struct tm: time_t = %jd\n",
               (intmax_t) t);
    struct tm default_tm = { 0 }; // 1970-01-01 00:00:00
    mktime(&default_tm); // update derived fields making tm into a valid tm.
    tm = default_tm;
  }
  return tm;
}

Here is the caller graph for this function:

mutt_date_local_tz()

int mutt_date_local_tz

(

time_t

t

)

Calculate the local timezone in seconds east of UTC.

Parameters

t	Time to examine

Return values

num	Seconds east of UTC

Returns the local timezone in seconds east of UTC for the time t, or for the current time if t is zero.

Definition at line 219 of file date.c.

{
  /* Check we haven't overflowed the time (on 32-bit arches) */
  if ((t == TIME_T_MAX) || (t == TIME_T_MIN))
    return 0;
 
  if (t == 0)
    t = mutt_date_now();
 
  struct tm tm = mutt_date_gmtime(t);
  return compute_tz(t, &tm);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_make_date()

void mutt_date_make_date	(	struct Buffer *	buf,
		bool	local
	)

Write a date in RFC822 format to a buffer.

Parameters

buf	Buffer for result
local	If true, use the local timezone. Otherwise use UTC.

Appends the date to the passed in buffer. The buffer is not cleared because some callers prepend quotes.

Definition at line 397 of file date.c.

{
  if (!buf)
    return;
 
  struct tm tm = { 0 };
  int tz = 0;
 
  time_t t = mutt_date_now();
  if (local)
  {
    tm = mutt_date_localtime(t);
    tz = mutt_date_local_tz(t);
  }
  else
  {
    tm = mutt_date_gmtime(t);
  }
 
  tz /= 60;
 
  buf_add_printf(buf, "%s, %d %s %d %02d:%02d:%02d %+03d%02d", Weekdays[tm.tm_wday],
                 tm.tm_mday, Months[tm.tm_mon], tm.tm_year + 1900, tm.tm_hour,
                 tm.tm_min, tm.tm_sec, tz / 60, abs(tz) % 60);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_make_imap()

int mutt_date_make_imap	(	struct Buffer *	buf,
		time_t	timestamp
	)

Format date in IMAP style: DD-MMM-YYYY HH:MM:SS +ZZzz.

Parameters

buf	Buffer to store the results
timestamp	Time to format

Return values

num	Characters written to buf

Definition at line 811 of file date.c.

{
  if (!buf)
    return -1;
 
  struct tm tm = mutt_date_localtime(timestamp);
  int tz = mutt_date_local_tz(timestamp);
 
  tz /= 60;
 
  return buf_printf(buf, "%02d-%s-%d %02d:%02d:%02d %+03d%02d", tm.tm_mday,
                    Months[tm.tm_mon], tm.tm_year + 1900, tm.tm_hour, tm.tm_min,
                    tm.tm_sec, tz / 60, abs(tz) % 60);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_make_time()

time_t mutt_date_make_time	(	struct tm *	t,
		bool	local
	)

Convert struct tm to time_t

Parameters

t	Time to convert
local	Should the local timezone be considered

Return values

num	Time in Unix format
TIME_T_MIN	Error

Convert a struct tm to time_t, but don't take the local timezone into account unless "local" is nonzero

Definition at line 242 of file date.c.

{
  if (!t)
    return TIME_T_MIN;
 
  static const int AccumDaysPerMonth[mutt_array_size(Months)] = {
    0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334,
  };
 
  /* Prevent an integer overflow, with some arbitrary limits. */
  if (t->tm_year > 10000)
    return TIME_T_MAX;
  if (t->tm_year < -10000)
    return TIME_T_MIN;
 
  if ((t->tm_mday < 1) || (t->tm_mday > 31))
    return TIME_T_MIN;
  if ((t->tm_hour < 0) || (t->tm_hour > 23) || (t->tm_min < 0) ||
      (t->tm_min > 59) || (t->tm_sec < 0) || (t->tm_sec > 60))
  {
    return TIME_T_MIN;
  }
  if (t->tm_year > 9999)
    return TIME_T_MAX;
 
  /* Compute the number of days since January 1 in the same year */
  int yday = AccumDaysPerMonth[t->tm_mon % mutt_array_size(Months)];
 
  /* The leap years are 1972 and every 4. year until 2096,
   * but this algorithm will fail after year 2099 */
  yday += t->tm_mday;
  if ((t->tm_year % 4) || (t->tm_mon < 2))
    yday--;
  t->tm_yday = yday;
 
  time_t g = yday;
 
  /* Compute the number of days since January 1, 1970 */
  g += (t->tm_year - 70) * (time_t) 365;
  g += (t->tm_year - 69) / 4;
 
  /* Compute the number of hours */
  g *= 24;
  g += t->tm_hour;
 
  /* Compute the number of minutes */
  g *= 60;
  g += t->tm_min;
 
  /* Compute the number of seconds */
  g *= 60;
  g += t->tm_sec;
 
  if (local)
    g -= compute_tz(g, t);
 
  return g;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_make_tls()

int mutt_date_make_tls	(	char *	buf,
		size_t	buflen,
		time_t	timestamp
	)

Format date in TLS certificate verification style.

Parameters

buf	Buffer to store the results
buflen	Length of buffer
timestamp	Time to format

Return values

num	Characters written to buf

e.g., Mar 17 16:40:46 2016 UTC. The time is always in UTC.

Caller should provide a buffer of at least 27 bytes.

Definition at line 837 of file date.c.

{
  if (!buf)
    return -1;
 
  struct tm tm = mutt_date_gmtime(timestamp);
  return snprintf(buf, buflen, "%s, %d %s %d %02d:%02d:%02d UTC",
                  Weekdays[tm.tm_wday], tm.tm_mday, Months[tm.tm_mon],
                  tm.tm_year + 1900, tm.tm_hour, tm.tm_min, tm.tm_sec);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_normalize_time()

void mutt_date_normalize_time

(

struct tm *

tm

)

Fix the contents of a struct tm.

Parameters

tm	Time to correct

If values have been added/subtracted from a struct tm, it can lead to invalid dates, e.g. Adding 10 days to the 25th of a month.

This function will correct any over/under-flow.

Definition at line 310 of file date.c.

{
  if (!tm)
    return;
 
  static const char DaysPerMonth[mutt_array_size(Months)] = {
    31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31,
  };
  int leap;
 
  while (tm->tm_sec < 0)
  {
    tm->tm_sec += 60;
    tm->tm_min--;
  }
  while (tm->tm_sec >= 60)
  {
    tm->tm_sec -= 60;
    tm->tm_min++;
  }
  while (tm->tm_min < 0)
  {
    tm->tm_min += 60;
    tm->tm_hour--;
  }
  while (tm->tm_min >= 60)
  {
    tm->tm_min -= 60;
    tm->tm_hour++;
  }
  while (tm->tm_hour < 0)
  {
    tm->tm_hour += 24;
    tm->tm_mday--;
  }
  while (tm->tm_hour >= 24)
  {
    tm->tm_hour -= 24;
    tm->tm_mday++;
  }
  /* use loops on NNNdwmy user input values? */
  while (tm->tm_mon < 0)
  {
    tm->tm_mon += 12;
    tm->tm_year--;
  }
  while (tm->tm_mon >= 12)
  {
    tm->tm_mon -= 12;
    tm->tm_year++;
  }
  while (tm->tm_mday <= 0)
  {
    if (tm->tm_mon)
    {
      tm->tm_mon--;
    }
    else
    {
      tm->tm_mon = 11;
      tm->tm_year--;
    }
    tm->tm_mday += DaysPerMonth[tm->tm_mon] + is_leap_year_feb(tm);
  }
  while (tm->tm_mday > (DaysPerMonth[tm->tm_mon] + (leap = is_leap_year_feb(tm))))
  {
    tm->tm_mday -= DaysPerMonth[tm->tm_mon] + leap;
    if (tm->tm_mon < 11)
    {
      tm->tm_mon++;
    }
    else
    {
      tm->tm_mon = 0;
      tm->tm_year++;
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_parse_date()

time_t mutt_date_parse_date	(	const char *	s,
		struct Tz *	tz_out
	)

Parse a date string in RFC822 format.

Parameters

[in]	s	String to parse
[out]	tz_out	Pointer to timezone (optional)

Return values

num	Unix time in seconds, or -1 on failure

Parse a date of the form: [ weekday , ] day-of-month month year hour:minute:second [ timezone ]

The 'timezone' field is optional; it defaults to +0000 if missing.

Definition at line 716 of file date.c.

{
  if (!s)
    return -1;
 
  const time_t strict_t = mutt_date_parse_rfc5322_strict(s, tz_out);
  if (strict_t != -1)
    return strict_t;
 
  const regmatch_t *match = mutt_prex_capture(PREX_RFC5322_DATE_LAX, s);
  if (!match)
  {
    mutt_debug(LL_DEBUG1, "Could not parse date: <%s>\n", s);
    return -1;
  }
  mutt_debug(LL_DEBUG2, "Fallback regex for date: <%s>\n", s);
 
  struct tm tm = { 0 };
 
  // clang-format off
  const regmatch_t *mday    = &match[PREX_RFC5322_DATE_LAX_MATCH_DAY];
  const regmatch_t *mmonth  = &match[PREX_RFC5322_DATE_LAX_MATCH_MONTH];
  const regmatch_t *myear   = &match[PREX_RFC5322_DATE_LAX_MATCH_YEAR];
  const regmatch_t *mhour   = &match[PREX_RFC5322_DATE_LAX_MATCH_HOUR];
  const regmatch_t *mminute = &match[PREX_RFC5322_DATE_LAX_MATCH_MINUTE];
  const regmatch_t *msecond = &match[PREX_RFC5322_DATE_LAX_MATCH_SECOND];
  const regmatch_t *mtz     = &match[PREX_RFC5322_DATE_LAX_MATCH_TZ];
  const regmatch_t *mtzobs  = &match[PREX_RFC5322_DATE_LAX_MATCH_TZ_OBS];
  // clang-format on
 
  /* Day */
  sscanf(s + mutt_regmatch_start(mday), "%d", &tm.tm_mday);
  if (tm.tm_mday > 31)
    return -1;
 
  /* Month */
  tm.tm_mon = mutt_date_check_month(s + mutt_regmatch_start(mmonth));
 
  /* Year */
  sscanf(s + mutt_regmatch_start(myear), "%d", &tm.tm_year);
  if (tm.tm_year < 50)
    tm.tm_year += 100;
  else if (tm.tm_year >= 1900)
    tm.tm_year -= 1900;
 
  /* Time */
  int hour = 0, min = 0, sec = 0;
  sscanf(s + mutt_regmatch_start(mhour), "%d", &hour);
  sscanf(s + mutt_regmatch_start(mminute), "%d", &min);
  if (mutt_regmatch_start(msecond) != -1)
    sscanf(s + mutt_regmatch_start(msecond), "%d", &sec);
  if ((hour > 23) || (min > 59) || (sec > 60))
    return -1;
  tm.tm_hour = hour;
  tm.tm_min = min;
  tm.tm_sec = sec;
 
  /* Time zone */
  int zhours = 0;
  int zminutes = 0;
  bool zoccident = false;
  if (mutt_regmatch_start(mtz) != -1)
  {
    char direction = '\0';
    sscanf(s + mutt_regmatch_start(mtz), "%c%02d%02d", &direction, &zhours, &zminutes);
    zoccident = (direction == '-');
  }
  else if (mutt_regmatch_start(mtzobs) != -1)
  {
    const struct Tz *tz = find_tz(s + mutt_regmatch_start(mtzobs),
                                  mutt_regmatch_len(mtzobs));
    if (tz)
    {
      zhours = tz->zhours;
      zminutes = tz->zminutes;
      zoccident = tz->zoccident;
    }
  }
 
  if (tz_out)
  {
    tz_out->zhours = zhours;
    tz_out->zminutes = zminutes;
    tz_out->zoccident = zoccident;
  }
 
  return add_tz_offset(mutt_date_make_time(&tm, false), zoccident, zhours, zminutes);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_parse_imap()

time_t mutt_date_parse_imap

(

const char *

s

)

Parse date of the form: DD-MMM-YYYY HH:MM:SS +ZZzz.

Parameters

s	Date in string form

Return values

num	Unix time
0	Error

Definition at line 854 of file date.c.

{
  const regmatch_t *match = mutt_prex_capture(PREX_IMAP_DATE, s);
  if (!match)
    return 0;
 
  const regmatch_t *mday = &match[PREX_IMAP_DATE_MATCH_DAY];
  const regmatch_t *mmonth = &match[PREX_IMAP_DATE_MATCH_MONTH];
  const regmatch_t *myear = &match[PREX_IMAP_DATE_MATCH_YEAR];
  const regmatch_t *mtime = &match[PREX_IMAP_DATE_MATCH_TIME];
  const regmatch_t *mtz = &match[PREX_IMAP_DATE_MATCH_TZ];
 
  struct tm tm = { 0 };
 
  sscanf(s + mutt_regmatch_start(mday), " %d", &tm.tm_mday);
  tm.tm_mon = mutt_date_check_month(s + mutt_regmatch_start(mmonth));
  sscanf(s + mutt_regmatch_start(myear), "%d", &tm.tm_year);
  tm.tm_year -= 1900;
  sscanf(s + mutt_regmatch_start(mtime), "%d:%d:%d", &tm.tm_hour, &tm.tm_min, &tm.tm_sec);
 
  char direction = '\0';
  int zhours = 0, zminutes = 0;
  sscanf(s + mutt_regmatch_start(mtz), "%c%02d%02d", &direction, &zhours, &zminutes);
  bool zoccident = (direction == '-');
 
  return add_tz_offset(mutt_date_make_time(&tm, false), zoccident, zhours, zminutes);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_date_sleep_ms()

void mutt_date_sleep_ms

(

size_t

ms

)

Sleep for milliseconds.

Parameters

ms	Number of milliseconds to sleep

Definition at line 983 of file date.c.

{
  const struct timespec sleep = {
    .tv_sec = ms / 1000,
    .tv_nsec = (ms % 1000) * 1000000UL,
  };
  nanosleep(&sleep, NULL);
}

Here is the caller graph for this function:

mutt_time_now()

void mutt_time_now

(

struct timespec *

tp

)

Set the provided time field to the current time.

Parameters

[out]

tp

Field to set

Uses nanosecond precision if available, if not we fallback to microseconds.

Definition at line 480 of file date.c.

{
#ifdef HAVE_CLOCK_GETTIME
  if (clock_gettime(CLOCK_REALTIME, tp) != 0)
    mutt_perror("clock_gettime");
#else
  struct timeval tv = { 0, 0 };
  if (gettimeofday(&tv, NULL) != 0)
    mutt_perror("gettimeofday");
  tp->tv_sec = tv.tv_sec;
  tp->tv_nsec = tv.tv_usec * 1000;
#endif
}

Here is the caller graph for this function: