Merge pull request #20023 from kfessel/p-nativ-TZ-UTC

board/native: set TZ to UTC by default

Author: mguetschow

boards/common/native/board_init.c

@@ -14,6 +14,7 @@
  * @}
  */
 #include <stdio.h>
+#include <stdlib.h>
 #include "board.h"
 
 #include "board_internal.h"
@@ -79,5 +80,9 @@ VFS_AUTO_MOUNT(native, { .hostpath = FS_NATIVE_DIR }, VFS_DEFAULT_NVM(0), 0);
  */
 void board_init(void)
 {
+    if (!getenv("TZ")) {
+        puts("TZ not set, setting UTC");
+    }
+    setenv("TZ", "UTC", 0);
     puts("RIOT " RIOT_BOARD " board initialized.");
 }

boards/common/native/doc.md

@@ -26,6 +26,8 @@ and @ref boards_native64. Using `BOARD=native` will automatically select the rig
 - Network: Tap Interface
 - UART: Runtime configurable - `/dev/tty*` are supported
 - Timers: Host timer
+- RTC: host time at `UTC` for consistent behavior with embedded systems.
+  The environment variable `TZ` can be used to explicitly set a specific or hosts timezone (see [below](#setting-a-timezone)).
 - LEDs: One red and one green LED - state changes are printed to the UART
 - PWM: Dummy PWM
 - QDEC: Emulated according to PWM
@@ -77,5 +79,26 @@ Options:
 As with any platform, you can specify the sizes of your stacks, i.e. the amount of space your application can use.
 You may wish to use a more realistic stack size than native's `THREAD_STACKSIZE_DEFAULT` to increase realism.
 
+# Setting a timezone                                      {#setting-a-timezone}
+
+RIOT native defaults to `UTC` timezone if `TZ` is not set in the environment,
+to keep behavior of `time.h` functions like `mktime` consistent with embedded setups,
+which usually do not use timezones.
+If your application requires the same timezone as host, the `TZ` environment variable should be set accordingly.
+There are several ways to achieve that:
+- execute `export TZ=":/etc/localtime"` prior `make term`
+  in the very shell you intend to run `make term` in
+- add `export TZ=":/etc/localtime"` to your `~/.profile`
+- run `TZ=":/etc/localtime" make term`
+
+The timezone can also be set at runtime by the application for both native and embedded devices using `setenv("TZ", <timezonestring>, 1)`. `picolibc` and `newlibc` expect `<timezonestring>` to have the form `NAME+/-hh:mm:ss<DST-handling>` (`+` pointing west -> `CET-1` adds 1 hour to UTC, see `man timezone`)
+e.g., `ACST-9:30ACDT-10:30,M10.1.0,M4.1.0`.
+If the `TZ`-string can not be interpreted by the used `libc` (`newlib`,`picolibc`,`glibc`),
+they default back to `UTC`.
+
+@warning Some things will behave faulty, since the assumption of most pkgs and
+        system modules is to run on a embedded system with no timezone set.
+        One often used function that respect timezone setting is `mktime`
+
 # Known Issues
 Check the list of open issues labeled native in the [github issue tracker](https://github.com/RIOT-OS/RIOT/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22Platform%3A%20native%22)