New: strftime man page incorrectly claims that TZ is used

https://bugzilla.kernel.org/show_bug.cgi?id=218711

Bug ID: 218711
Summary: strftime man page incorrectly claims that TZ is used
Product: Documentation
Version: unspecified
Hardware: All
OS: Linux
Status: NEW
Severity: normal
Priority: P3
Component: man-pages
Assignee: [email protected]
Reporter: [email protected]
Regression: No

The strftime man page says, in the ENVIRONMENT section, that "The environment variables TZ and LC_TIME are used."

strftime(), in Linux, does not use the TZ environment variable. It is passed a pointer to a struct tm, which contains a time stamp that can reflect either local time or UTC, and formats a string based on the values in that structure. If the structure reflects local time, there is no need for any conversion of POSIX time to local time, so TZ is not used. If the structure reflects UTC, the string will reflect UTC, meaning that, again, there is no need for any conversion to local time, so TZ is not used.

TZ is *indirectly* used, because, to quote the Single UNIX Specification page for strftime(), "Local timezone information is used as though strftime() called tzset().", and, to quote the Single UNIX Specification page for tzset(), "The tzset() function shall use the value of the environment variable TZ to set time conversion information used by ctime, localtime, mktime, and strftime."

The reason why strftime is mentioned is that the %Z format specifier is "Replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists." In systems in which struct tm includes the tm_zone member, %Z can use the tm_zone member as the timezone abbreviation, but, in systems where it does *not* include the tm_zone member, strftime() might, for example, have to fall back on using the tzname[] array and the tm_isdst member to select an element of that array.

https://bugzilla.kernel.org/show_bug.cgi?id=218711

Bug ID: 218711
Summary: strftime man page incorrectly claims that TZ is used
Product: Documentation
Version: unspecified
Hardware: All
OS: Linux
Status: NEW
Severity: normal
Priority: P3
Component: man-pages
Assignee: [email protected]
Reporter: [email protected]
Regression: No

The strftime man page says, in the ENVIRONMENT section, that "The environment variables TZ and LC_TIME are used."

strftime(), in Linux, does not use the TZ environment variable. It is passed a
pointer to a struct tm, which contains a time stamp that can reflect either local time or UTC, and formats a string based on the values in that structure.
If the structure reflects local time, there is no need for any conversion of POSIX time to local time, so TZ is not used. If the structure reflects UTC, the string will reflect UTC, meaning that, again, there is no need for any conversion to local time, so TZ is not used.

TZ is *indirectly* used, because, to quote the Single UNIX Specification page for strftime(), "Local timezone information is used as though strftime() called
tzset().", and, to quote the Single UNIX Specification page for tzset(), "The tzset() function shall use the value of the environment variable TZ to set time
conversion information used by ctime, localtime, mktime, and strftime."

The reason why strftime is mentioned is that the %Z format specifier is "Replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists." In systems in which struct tm includes the tm_zone member, %Z can use the tm_zone member as the timezone abbreviation, but, in systems where it does *not* include the tm_zone member, strftime() might, for example, have to fall back on using the tzname[] array and the tm_isdst member
to select an element of that array.

It would be wise to CC Paul Eggert <[email protected]>.