diff --git a/boards/common/native/doc.md b/boards/common/native/doc.md index 0072d44574..0c0ca12e92 100644 --- a/boards/common/native/doc.md +++ b/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", , 1)`. `picolibc` and `newlibc` expect `` to have the form `NAME+/-hh:mm:ss` (`+` 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)