HARDWARECLOCK="localtime" does not work when TIMEZONE is unset

从/etc/runit/core-services/03-console-setup.sh开始，检查变量未设置时它如何将TIMEZONE传递给hwclock。将行为与报告的TZ为空和TZ有效的复现情况进行对照，然后验证在设置HARDWARECLOCK="localtime"且未配置TIMEZONE时对RTC和系统时间的处理。

TZ=$TIMEZONE prevents HARDWARECLOCK="localtime" from working correctly

Environment

I am using a dual-boot system with Windows and Void Linux.

Windows treats the hardware RTC as local time, while Void Linux defaults to treating the RTC as UTC. Since I am using the Asia/Shanghai timezone (UTC+8), this causes an 8-hour time difference when switching between the two operating systems.

This is a common issue with Windows/Linux dual-boot systems. The Void Linux documentation documents the HARDWARECLOCK option and states that it can be set to localtime when the RTC stores local time.

Following the documentation, I configured /etc/rc.conf as follows:

...

# Set RTC to UTC or localtime.

HARDWARECLOCK="localtime"

# Set timezone, availables timezones can be found at /usr/share/zoneinfo.
#
# NOTE: it's preferred to set the timezone in /etc/localtime instead:
#  - ln -sf /usr/share/zoneinfo/<timezone> /etc/localtime
# Setting the timezone here requires a reboot to apply any changes/fixes
# and read-write access to the filesystem.
#
#TIMEZONE="Europe/Madrid"

...

However, the system does not behave as expected.

Expected behavior

With:

HARDWARECLOCK="localtime"

the RTC should be interpreted as local time without applying an additional timezone offset.

Therefore, hwclock --localtime and date should report approximately the same time:

$ sudo hwclock --localtime
2026-10-06 14:07:27.608389+08:00

$ date
Tue Oct  6 14:07:32 CST 2026

Actual behavior

Instead, the system applies an additional timezone offset to the RTC:

$ sudo hwclock --localtime
2026-10-06 14:14:30.649538+08:00

$ date
Tue Oct  6 22:14:35 CST 2026

The result is an 8-hour difference.

Investigation

I traced the boot process and found the following code in /etc/runit/core-services/03-console-setup.sh:

if [ -n "$HARDWARECLOCK" ]; then

    msg "Setting up RTC to '${HARDWARECLOCK}'..."

    TZ=$TIMEZONE hwclock --systz \
        ${HARDWARECLOCK:+--$(echo $HARDWARECLOCK |tr A-Z a-z) --noadjfile} || emergency_shell
fi

When I set:

HARDWARECLOCK="localtime"

the command effectively becomes:

TZ=$TIMEZONE hwclock --systz --localtime --noadjfile

The problem appears to be that TIMEZONE is normally not set in /etc/rc.conf. In that case, the command is executed with an empty TZ environment variable:

TZ= hwclock --systz --localtime --noadjfile

With an empty or invalid TZ, hwclock --systz appears to behave differently and applies a timezone offset even though --localtime was explicitly specified.

As a workaround, I have to manually set TIMEZONE in /etc/rc.conf:

...

# Set RTC to UTC or localtime.

HARDWARECLOCK="localtime"

# Set timezone, availables timezones can be found at /usr/share/zoneinfo.
#
# NOTE: it's preferred to set the timezone in /etc/localtime instead:
#  - ln -sf /usr/share/zoneinfo/<timezone> /etc/localtime
# Setting the timezone here requires a reboot to apply any changes/fixes
# and read-write access to the filesystem.

TIMEZONE="Asia/Shanghai"

...

After setting TIMEZONE, the command becomes:

TZ=Asia/Shanghai hwclock --systz --localtime --noadjfile

and the RTC is handled as expected.

Minimal reproduction

1. System-level reproduction

1. Edit /etc/rc.conf.

2. Set:

   HARDWARECLOCK="localtime"
   

3. Do not set TIMEZONE.

4. Reboot.

5. Compare:

   hwclock --localtime
   date
   

On a system using a non-UTC timezone, the two commands show a timezone offset.

If TIMEZONE is explicitly set to a valid timezone, for example:

TIMEZONE="Asia/Shanghai"

the problem does not occur.

2. hwclock reproduction

First, check the RTC time:

hwclock --localtime

Then run:

TZ=Asia/Shanghai hwclock --hctosys --localtime

With a valid TZ, hwclock --hctosys --localtime sets the system time directly from the RTC without applying an additional offset.

However, when TZ is empty:

TZ= hwclock --hctosys --localtime

hwclock still applies a timezone offset despite --localtime being explicitly specified.

This behavior can be reproduced with an empty or otherwise invalid TZ value.

Question

I am not sure whether this is a bug in the Void Linux startup script or expected behavior of hwclock from util-linux.

A possible workaround in the Void Linux startup script might be to only set TZ when $TIMEZONE is non-empty, rather than unconditionally using:

TZ=$TIMEZONE hwclock ...

Additional information

$ hwclock -v

hwclock from util-linux 2.41.4
System Time: 1791268704.280299