How to migrate to posix_time.h

[yashi]

With #94612 and #95226 merged, what should we do to migrage to new posix_time.h?

It seems replacing #include <zephyr/posix/time.h> with #include <time.h> works. but as the PR says I can't make posix_time.h work. IOW, if we replace #include <zephyr/posix/time.h> with #include <zephyr/posix/posix_time.h> I get the following error:

v4.2.0-4875-g2d72d86ba2d5 with the following change:

diff --git a/samples/hello_world/src/main.c b/samples/hello_world/src/main.c
index c550ab461cb..37b24a33453 100644
--- a/samples/hello_world/src/main.c
+++ b/samples/hello_world/src/main.c
@@ -5,6 +5,7 @@
  */
 
 #include <stdio.h>
+#include <zephyr/posix/posix_time.h>
 
 int main(void)
 {

❯ west build -p -b mps2/an385 zephyr/samples/hello_world
-- west build: making build dir /home/yashi/src/zephyr-project/build pristine
-- west build: generating a build system
Loading Zephyr default modules (Zephyr base).
-- Application: /home/yashi/src/zephyr-project/zephyr/samples/hello_world
-- CMake version: 3.31.6
-- Found Python3: /home/yashi/src/zephyr-project/.venv/bin/python (found suitable version "3.13.7", minimum required is "3.10") found components: Interpreter
-- Cache files will be written to: /home/yashi/.cache/zephyr
-- Zephyr version: 4.2.99 (/home/yashi/src/zephyr-project/zephyr)
-- Found west (found suitable version "1.4.0", minimum required is "0.14.0")
-- Board: mps2, qualifiers: an385
-- ZEPHYR_TOOLCHAIN_VARIANT not set, trying to locate Zephyr SDK
-- Found host-tools: zephyr 0.17.4 (/home/yashi/zephyr-sdk-0.17.4)
-- Found toolchain: zephyr 0.17.4 (/home/yashi/zephyr-sdk-0.17.4)
-- Found Dtc: /usr/bin/dtc (found suitable version "1.7.2", minimum required is "1.4.6")
-- Found BOARD.dts: /home/yashi/src/zephyr-project/zephyr/boards/arm/mps2/mps2_an385.dts
-- Generated zephyr.dts: /home/yashi/src/zephyr-project/build/zephyr/zephyr.dts
-- Generated pickled edt: /home/yashi/src/zephyr-project/build/zephyr/edt.pickle
-- Generated devicetree_generated.h: /home/yashi/src/zephyr-project/build/zephyr/include/generated/zephyr/devicetree_generated.h
Parsing /home/yashi/src/zephyr-project/zephyr/Kconfig
Loaded configuration '/home/yashi/src/zephyr-project/zephyr/boards/arm/mps2/mps2_an385_defconfig'
Merged configuration '/home/yashi/src/zephyr-project/zephyr/samples/hello_world/prj.conf'
Configuration saved to '/home/yashi/src/zephyr-project/build/zephyr/.config'
Kconfig header saved to '/home/yashi/src/zephyr-project/build/zephyr/include/generated/zephyr/autoconf.h'
-- Found GnuLd: /home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/arm-zephyr-eabi/bin/ld.bfd (found version "2.38")
-- The C compiler identification is GNU 12.2.0
-- The CXX compiler identification is GNU 12.2.0
-- The ASM compiler identification is GNU
-- Found assembler: /home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc
-- Using ccache: /usr/bin/ccache
-- Found gen_kobject_list: /home/yashi/src/zephyr-project/zephyr/scripts/build/gen_kobject_list.py
-- Configuring done (3.6s)
-- Generating done (0.1s)
-- Build files have been written to: /home/yashi/src/zephyr-project/build
-- west build: building application
[1/130] Preparing syscall dependency handling

[3/130] Generating include/generated/zephyr/version.h
-- Zephyr version: 4.2.99 (/home/yashi/src/zephyr-project/zephyr), build: v4.2.0-4875-g2d72d86ba2d5
[40/130] Building C object CMakeFiles/app.dir/src/main.c.obj
FAILED: CMakeFiles/app.dir/src/main.c.obj 
ccache /home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/bin/arm-zephyr-eabi-gcc -DKERNEL -DK_HEAP_MEM_POOL_SIZE=0 -DPICOLIBC_LONG_LONG_PRINTF_SCANF -D_POSIX_C_SOURCE=200809L -D__LINUX_ERRNO_EXTENSIONS__ -D__PROGRAM_START -D__ZEPHYR__=1 -I/home/yashi/src/zephyr-project/build/zephyr/include/generated/zephyr -I/home/yashi/src/zephyr-project/zephyr/include -I/home/yashi/src/zephyr-project/build/zephyr/include/generated -I/home/yashi/src/zephyr-project/zephyr/soc/arm -I/home/yashi/src/zephyr-project/zephyr/lib/libc/picolibc/include -I/home/yashi/src/zephyr-project/zephyr/soc/arm/mps2/. -I/home/yashi/src/zephyr-project/modules/hal/cmsis_6/CMSIS/Core/Include -I/home/yashi/src/zephyr-project/zephyr/modules/cmsis_6/. -I/home/yashi/src/zephyr-project/modules/hal/microchip/include -I/home/yashi/src/zephyr-project/modules/hal/ti/mspm0/source/ti/devices/msp/. -I/home/yashi/src/zephyr-project/modules/hal/ti/mspm0/source/ti/devices/msp/m0p -I/home/yashi/src/zephyr-project/modules/hal/ti/mspm0/source/ti/devices/msp/peripherals -I/home/yashi/src/zephyr-project/modules/hal/ti/mspm0/source/ti/devices/msp/peripherals/m0p -I/home/yashi/src/zephyr-project/modules/hal/ti/mspm0/source/ti/devices/msp/peripherals/m0p/sysctl -isystem /home/yashi/src/zephyr-project/zephyr/lib/libc/common/include -fno-strict-aliasing -Os -imacros /home/yashi/src/zephyr-project/build/zephyr/include/generated/zephyr/autoconf.h -fno-printf-return-value -fno-common -g -gdwarf-4 -fdiagnostics-color=always -mcpu=cortex-m3 -mthumb -mabi=aapcs -mfp16-format=ieee -mtp=soft --sysroot=/home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/arm-zephyr-eabi -imacros /home/yashi/src/zephyr-project/zephyr/include/zephyr/toolchain/zephyr_stdint.h -Wall -Wformat -Wformat-security -Wno-format-zero-length -Wdouble-promotion -Wno-pointer-sign -Wpointer-arith -Wexpansion-to-defined -Wno-unused-but-set-variable -Werror=implicit-int -fno-pic -fno-pie -fno-asynchronous-unwind-tables -ftls-model=local-exec -fno-reorder-functions --param=min-pagesize=0 -fno-defer-pop -fmacro-prefix-map=/home/yashi/src/zephyr-project/zephyr/samples/hello_world=CMAKE_SOURCE_DIR -fmacro-prefix-map=/home/yashi/src/zephyr-project/zephyr=ZEPHYR_BASE -fmacro-prefix-map=/home/yashi/src/zephyr-project=WEST_TOPDIR -ffunction-sections -fdata-sections -specs=picolibc.specs -std=c99 -MD -MT CMakeFiles/app.dir/src/main.c.obj -MF CMakeFiles/app.dir/src/main.c.obj.d -o CMakeFiles/app.dir/src/main.c.obj -c /home/yashi/src/zephyr-project/zephyr/samples/hello_world/src/main.c
In file included from /home/yashi/src/zephyr-project/zephyr/samples/hello_world/src/main.c:8:
/home/yashi/src/zephyr-project/zephyr/include/zephyr/posix/posix_time.h:42:15: error: conflicting types for 'locale_t'; have 'void *'
   42 | typedef void *locale_t;
      |               ^~~~~~~~
In file included from /home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/picolibc/include/string.h:50,
                 from /home/yashi/src/zephyr-project/zephyr/include/zephyr/sys/util.h:31,
                 from /home/yashi/src/zephyr-project/zephyr/include/zephyr/sys/time_units.h:11,
                 from /home/yashi/src/zephyr-project/zephyr/include/zephyr/sys/clock.h:22,
                 from /home/yashi/src/zephyr-project/zephyr/include/zephyr/posix/posix_time.h:14:
/home/yashi/zephyr-sdk-0.17.4/arm-zephyr-eabi/picolibc/include/sys/_locale.h:7:13: note: previous declaration of 'locale_t' with type 'locale_t' {aka 'int'}
    7 | typedef int locale_t;
      |             ^~~~~~~~
/home/yashi/src/zephyr-project/zephyr/include/zephyr/posix/posix_time.h:65:9: error: unknown type name 'time_t'
   65 |         time_t tv_sec;
      |         ^~~~~~
/home/yashi/src/zephyr-project/zephyr/include/zephyr/posix/posix_time.h:75:25: error: field 'it_interval' has incomplete type
   75 |         struct timespec it_interval;
      |                         ^~~~~~~~~~~
/home/yashi/src/zephyr-project/zephyr/include/zephyr/posix/posix_time.h:76:25: error: field 'it_value' has incomplete type
   76 |         struct timespec it_value;
      |                         ^~~~~~~~
/home/yashi/src/zephyr-project/zephyr/include/zephyr/posix/posix_time.h:167:64: error: type defaults to 'int' in declaration of 'locale' [-Werror=implicit-int]
  167 |                   const struct tm *ZRESTRICT timeptr, locale_t locale);
      |                                                                ^~~~~~
/home/yashi/src/zephyr-project/zephyr/include/zephyr/posix/posix_time.h:167:32: warning: 'struct tm' declared inside parameter list will not be visible outside of this definition or declaration
  167 |                   const struct tm *ZRESTRICT timeptr, locale_t locale);
      |                                ^~
cc1: some warnings being treated as errors
[65/130] Building C object zephyr/arch/arch/arm/core/mpu/CMakeFiles/arch__arm__core__mpu.dir/arm_mpu.c.obj
ninja: build stopped: subcommand failed.
FATAL ERROR: command exited with status 1: /usr/bin/cmake --build /home/yashi/src/zephyr-project/build

With v4.2.0-4778-g9b9e834890d8 (which is right before 5db2b58), the following change can be built:

diff --git a/samples/hello_world/src/main.c b/samples/hello_world/src/main.c
index c550ab461cb..8e911634402 100644
--- a/samples/hello_world/src/main.c
+++ b/samples/hello_world/src/main.c
@@ -5,6 +5,7 @@
  */
 
 #include <stdio.h>
+#include <zephyr/posix/time.h>
 
 int main(void)
 {

#94612 is a breaking change but I don't see migration document is updated.

[jukkar]

cc: @cfriedt

[cfriedt]

With #94612 and #95226 merged, what should we do to migrage to new posix_time.h?

Use #include <time.h>

[yashi]

Thanks. I'm marking this as the answer.

Can you also confirm that this means include/zephyr/posix/posix_time.h is not a user-facing file and that users should never include it in their app?

If so, wouldn't it be nice if we add somehitng line

#ifndef ZEPHYR_LIB_LIBC_PICOLIBC_INCLUDE_TIME_H_
# error "Never use <zephyr/posix/time.h> directly; include <time.h> instead."
#endif

If you agree, I can make a PR for it.

[cfriedt]

I can definitely add a note in the migration guide - sorry for my short response earlier, I think it was in the elevator at work 😅

It would be great if we could have a direct inclusion error, but the issue is that there are many C libraries that could potentially include that file, and only one of them is Picolibc :-/

[cfriedt]

#96999

[yashi]

Thanks.

What I did in my module is

/* https://github.com/zephyrproject-rtos/zephyr/discussions/96911 */
#if __has_include(<zephyr/posix/posix_time.h>)
  #include <time.h>
#else
  #include <zephyr/posix/time.h>
#endif

It might also be nice for users if we can keep zephyr/posix/time.h and let it warn for users. I just created a PR for it. WDYT?
#97031