1 files changed, 46 insertions, 40 deletions
diff --git a/contrib/tzcode/newstrftime.3 b/contrib/tzcode/newstrftime.3
index a9997a092d0a..e9a382240ed2 100644
--- a/contrib/tzcode/newstrftime.3
+++ b/contrib/tzcode/newstrftime.3
@@ -40,8 +40,6 @@
 strftime \- format date and time
 .SH SYNOPSIS
 .nf
-.ie \n(.g .ds - \f(CR-\fP
-.el .ds - \-
 .B #include <time.h>
 .PP
 .B "size_t strftime(char *restrict buf, size_t maxsize,"
@@ -93,7 +91,7 @@ If a bracketed member name is followed by
 .B strftime
 can use the named member even though POSIX.1-2024 does not list it;
 if the name is followed by
-.q \*- ,
+.q \- ,
 .B strftime
 ignores the member even though POSIX.1-2024 lists it
 which means portable code should set it.
@@ -139,11 +137,14 @@ is replaced by the locale's appropriate date and time representation.
 .IR tm_sec ,
 .IR tm_gmtoff ,
 .IR tm_zone ,
-.IR tm_isdst \*-].
+.IR tm_isdst \-].
 .TP
 %D
 is equivalent to
 .c %m/%d/%y .
+Although used in the United States for current dates,
+this format is ambiguous elsewhere
+and for dates that might involve other centuries.
 .RI [ tm_year ,
 .IR tm_mon ,
 .IR tm_mday ]
@@ -167,6 +168,8 @@ is equivalent to
 .TP
 %G
 is replaced by the ISO 8601 year with century as a decimal number.
+This is the year that includes the greater part of the week.
+(Monday as the first day of a week).
 See also the
 .c %V
 conversion specification.
@@ -176,11 +179,7 @@ conversion specification.
 .TP
 %g
 is replaced by the ISO 8601 year without century as a decimal number [00,99].
-This is the year that includes the greater part of the week.
-(Monday as the first day of a week).
-See also the
-.c %V
-conversion specification.
+Since it omits the century, it is ambiguous for dates.
 .RI [ tm_year ,
 .IR tm_yday ,
 .IR tm_wday ]
@@ -249,9 +248,22 @@ of leap seconds.
 is replaced by the number of seconds since the Epoch (see
 .BR ctime (3)).
 Although %s is reliable in this implementation,
-it can have glitches on other platforms (notably platforms lacking
-.IR tm_gmtoff ),
-so portable code should format a
+it can have glitches on other platforms
+(notably obsolescent platforms lacking
+.I tm_gmtoff
+or where
+.B time_t
+is no wider than int), and POSIX allows
+.B strftime
+to set
+.B errno
+to
+.B EINVAL
+or
+.B EOVERFLOW
+and return 0 if the number of seconds would be negative or out of range for
+.BR time_t .
+Portable code should therefore format a
 .B time_t
 value directly via something like
 .B sprintf
@@ -267,7 +279,7 @@ with "%s".
 .IR tm_min ,
 .IR tm_sec ,
 .IR tm_gmtoff +,
-.IR tm_isdst \*-].
+.IR tm_isdst \-].
 .TP
 %T
 is replaced by the time in the format
@@ -284,7 +296,7 @@ is replaced by the week number of the year (Sunday as the first day of
 the week) as a decimal number [00,53].
 .RI [ tm_wday ,
 .IR tm_yday ,
-.IR tm_year \*-]
+.IR tm_year \-]
 .TP
 %u
 is replaced by the weekday (Monday as the first day of the week)
@@ -318,31 +330,33 @@ as a decimal number [0,6].
 .TP
 %X
 is replaced by the locale's appropriate time representation.
-.RI [ tm_year \*-,
-.IR tm_yday \*-,
-.IR tm_mon \*-,
-.IR tm_mday \*-,
-.IR tm_wday \*-,
+.RI [ tm_year \-,
+.IR tm_yday \-,
+.IR tm_mon \-,
+.IR tm_mday \-,
+.IR tm_wday \-,
 .IR tm_hour ,
 .IR tm_min ,
 .IR tm_sec ,
 .IR tm_gmtoff ,
 .IR tm_zone ,
-.IR tm_isdst \*-].
+.IR tm_isdst \-].
 .TP
 %x
 is replaced by the locale's appropriate date representation.
+This format can be ambiguous for dates, e.g.,
+it can generate "01/02/03" in the C locale.
 .RI [ tm_year ,
 .IR tm_yday ,
 .IR tm_mon ,
 .IR tm_mday ,
 .IR tm_wday ,
-.IR tm_hour \*-,
-.IR tm_min \*-,
-.IR tm_sec \*-,
-.IR tm_gmtoff \*-,
-.IR tm_zone \*-,
-.IR tm_isdst \*-].
+.IR tm_hour \-,
+.IR tm_min \-,
+.IR tm_sec \-,
+.IR tm_gmtoff \-,
+.IR tm_zone \-,
+.IR tm_isdst \-].
 .TP
 %Y
 is replaced by the year with century as a decimal number.
@@ -350,28 +364,29 @@ is replaced by the year with century as a decimal number.
 .TP
 %y
 is replaced by the year without century as a decimal number [00,99].
+Since it omits the century, it is ambiguous for dates.
 .RI [ tm_year ]
 .TP
 %Z
 is replaced by the time zone abbreviation,
 or by the empty string if this is not determinable.
 .RI [ tm_zone ,
-.IR tm_isdst \*-]
+.IR tm_isdst \-]
 .TP
 %z
 is replaced by the offset from the Prime Meridian
-in the format +HHMM or \*-HHMM (ISO 8601) as appropriate,
+in the format +HHMM or \-HHMM (ISO 8601) as appropriate,
 with positive values representing locations east of Greenwich,
 or by the empty string if this is not determinable.
-The numeric time zone abbreviation \*-0000 is used when the time is
+The numeric time zone abbreviation \-0000 is used when the time is
 Universal Time
 but local time is indeterminate; by convention this is used for
 locations while uninhabited, and corresponds to a zero offset when the
 time zone abbreviation begins with
-.q "\*-" .
+.q "\-" .
 .RI [ tm_gmtoff ,
 .IR tm_zone +,
-.IR tm_isdst \*-]
+.IR tm_isdst \-]
 .TP
 %%
 is replaced by a single %.
@@ -418,15 +433,6 @@ This function fails if:
 The total number of resulting bytes, including the terminating
 NUL character, is more than
 .IR maxsize .
-.PP
-This function may fail if:
-.TP
-[EOVERFLOW]
-The format includes an
-.c %s
-conversion and the number of seconds since the Epoch cannot be represented
-in a
-.c time_t .
 .SH SEE ALSO
 .BR date (1),
 .BR getenv (3),