Time zones / daylight savings time?

[HunterZ]

Does croncpp operate relative to UTC, the system's local time zone, or something else? I'm not seeing anything about this in the documentation, and it's concerning because it absolutely matters when you're talking about scheduling against calendar-related attributes. I'm also seeing a lot of open issues regarding things like daylight savings time transitions (#8, #24, #30, #32) and/or time zones (#23).

I know a second-order dependency is probably undesirable, but I'm wondering if it might be worth using the Howard Hinnant date library (https://github.com/HowardHinnant/date) since it's meant to provide modern C++ tools that can help with these kinds of issues.

The C# Cronos library also has some good thoughts in the "Daylight Savings Time" section of its documentation: https://github.com/HangfireIO/Cronos/

[HunterZ]

Update: Looks like libcron also uses date, so there's an example for how to use it in a C++ cron library: https://github.com/PerMalmberg/libcron

[nminkov]

Hi devs. Can you please give us more info about UTC vs Local? Do you only work in UTC or can configure in both?

[cmorve-te]

croncpp works in local time.

Its problems with DST come from its add_to_field, set_field and reset_field functions, which manipulate std::tm structures.

The std::tm structure has a tm_isdst field that can be:

• Positive (DST in effect)
• Zero (DST not in effect)
• Negative... let functions like mktime() try to guess whether DST is in effect.

The problem is that croncpp doesn't know about timezones. After modifying a std::tm structure, it doesn't know whether it's in DST or not any more. So what it does is set the tm_isdst field of std::tm to "-1" after modifying a std::tm structure, and rely on e.g. mktime to then set tm_isdst to the correct value.
Functions like utils::tm_to_time don't only do the transformation, they also modify the input argument by normalizing it (including setting tm_isdst to 0 or 1).

The first problem is that croncpp doesn't always set tm_isdst to -1. It only does it when modifying the day_of_month or month fields. This is incorrect.

croncpp has a test suite. So let's go to https://github.com/mariusbancila/croncpp/blob/master/test/test_standard.cpp#L366 and add a few more.

check_next("30 55 5,11,17 * * *", "2023-03-25 21:55:30", "2023-03-26 05:55:30")

Remember that croncpp works in local time, so you should run this with a TZ value with a DST change within this period.

You could use, for example, CET-1CEST,M3.5.0,M10.5.0/3:

$ TZ='CET-1CEST,M3.5.0,M10.5.0/3' date -d '@1679792399'
Sun 26 Mar 01:59:59 CET 2023
$ TZ='CET-1CEST,M3.5.0,M10.5.0/3' date -d '@1679792400'
Sun 26 Mar 03:00:00 CEST 2023

If you run the test now, you will get

test_standard.cpp:58: FAILED:
  REQUIRE( value == expected )
with expansion:
  "2023-03-25 05:55:30"
  ==
  "2023-03-26 05:55:30"

As you can see it's not only returning an unexpected value, it's returning a value in the past!
The logic to find the next value in in find_next().

• It will first look at the second, and since it's already at second 30 it will be happy.
• It will then look at the minutes, and again it's already at minute 55. So far so good, we are at "2023-03-25 21:55:30" winter time.
  But then it will come to the hours... we are at 21, and we want to be at 5, we have already passed it. So it will:
• Increase the day
  • First step, so far so good. We are on the 26th, at 21:55:30, winter time (that's actually summer time!)
  • Second step. We have lost the DST information, so we are on 26th, at 21:55:30, unknown summer time.
  • Third step. mktime() has told us we are in summer time, so we are on 26th, at 21:55:30, summer time.
• Set the hour to zero
  • First step. We are at "2023-03-26 0:55:30", summer time (that's actually winter time!).
  • Second step. mktime() notices that this time is impossible, and normalizes it by setting is_dst to zero (from 1, not from -1)... and moving one hour to compensate. We are at "2023-03-25 23:55:30" winter time.

And here we have lost the game. The day has gone back to the 25th, when we were expecting it to stay on the 26th.

check_next("30 55 3,11,17 * * *", "2023-03-26 00:55:30", "2023-03-26 03:55:30")

If you run the test now, you will get

/home/cmorve/dev/tmp/croncpp/test/test_standard.cpp:58: FAILED:
  REQUIRE( value == expected )
with expansion:
  "2023-03-26 11:55:30"
  ==
  "2023-03-26 03:55:30"

People have been noticing it when cron_next() returns a time in the past. But notice that it can also skip events!

What happens here is that to make 00:55:30 reach 3:55:30 it changes the hour from 0 to 3. But then, mktime() normalizes "2023-03-26 03:55:30" winter time into "2023-03-26 04:55:30" summer time, making us skip the "3" hour.

I don't know why isdst is only set to -1 for day_of_month and month, but the problems above would be solved by always setting it to -1. In that way, mktime() would only set tm_isdst to the correct value, without actually changing the time.
It actually makes sense. No matter what are you changing, one second it may be winter time and the next summer time, so no matter what you change, you don't know whether the end result is DST or not, so always setting it to -1 makes sense.

So let's go ahead, and change add_to_field, set_field and reset_field so they always set is_dst to -1 before calling utils::tm_to_time()!.

check_next2("59 59 1 * * *", 1762066799, 1762070399);

There is an obvious problem with the check_next() as a function for testing... it doesn't allow you to specify whether it's DST or not. How can you test with these two different times?

$ TZ='CST6CDT,M3.2.0,M11.1.0' date -d '@1762066799'
Sun  2 Nov 01:59:59 CDT 2025
$ TZ='CST6CDT,M3.2.0,M11.1.0' date -d '@1762070399'
Sun  2 Nov 01:59:59 CST 2025

(let's use TZ='CST6CDT,M3.2.0,M11.1.0' from this point on)
If the only input is a string that doesn't specify whether it's DST or not?

So let's add check_next2, a variation of check_next().

void check_next2(CRONCPP_STRING_VIEW expr, std::time_t time, std::time_t expected)
{  
   auto cex = make_cron(expr);
   
   std::tm initial_time;
   utils::time_to_tm(&time, &initial_time);
   
   auto result1 = cron_next(cex, time);
   auto result2 = cron_next(cex, initial_time);
   
   std::tm result1_tm;
   utils::time_to_tm(&result1, &result1_tm);
   
   REQUIRE(result1_tm == result2);
   REQUIRE(result1 == expected);
}

Notice that's not even clear check_next2("59 59 1 * * *", 1762066799, 1762070399); is correct. https://github.com/HangfireIO/Cronos/?tab=readme-ov-file#non-interval-expression argues that 1762070399 should be skipped, since you don't one it to run twice one day just because the clock has gone backwards. But the actual result of the test is

  REQUIRE( result1 == expected )
with expansion:
  1762066799 (0x6907016f)
  ==
  1762070399 (0x69070f7f)

So check_next has returned... the current time. Notice that this actually didn't happen until we started always setting is_dst to -1. But this shouldn't have happened, the code explicitly redoes everything one second later to avoid it happening. If we would let it happen, people could end up running something N times in a loop.

The add_to_field(date, detail::cron_field::second, 1); actually works fine. We end up with "2025-11-02 01:00:00" winter time, so you could expect the test to succeed with cron_next reaching "2025-11-02 01:00:00" winter time

But then it will start by checking the seconds and, since they don't match, it will try to move forward to 59 seconds. Meaning,

• "2025-11-02 01:00:00" winter time
• "2025-11-02 01:00:59" unspecified DST (because we have patched it so it also does this when touching the seconds)
• "2025-11-02 01:00:59" summer time

meaning that we wanted to move 59 seconds forward, but actually moved on 59 minutes 59 seconds back in time.

Naturally, this ends up reaching "2025-11-02 01:59:59" summer time, which is "now", which should never happen.
The problem here is that we can't actually rely on mktime to know whether we are talking about summer or winter time when the clock moves backwards. You know that "2025-11-01" is summer time, you know that "2025-11-03" is winter time... but "2025-11-02 01:00:59" with tm_isdst set to -1? It could be either summer or winter time, when we set it to -1 we just lose that information.
Notice that this last test happens to work with musl 1.2.5. But that's purely luck. Other people were complaining musl behaviour was broken: https://www.openwall.com/lists/musl/2024/03/24/6