diff options
Diffstat (limited to 'manual/time.texi')
| -rw-r--r-- | manual/time.texi | 88 |
1 files changed, 63 insertions, 25 deletions
diff --git a/manual/time.texi b/manual/time.texi index ff31e284fd..e7e8647ee2 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -687,9 +687,8 @@ The return value is the null pointer if @var{time} cannot be represented as a broken-down time; typically this is because the year cannot fit into an @code{int}. -Calling @code{localtime} has one other effect: it sets the variable -@code{tzname} with information about the current time zone. @xref{Time -Zone Functions}. +Calling @code{localtime} also sets the current time zone as if +@code{tzset} were called. @xref{Time Zone Functions}. @end deftypefun Using the @code{localtime} function is a big problem in multi-threaded @@ -739,25 +738,28 @@ object the result was written into, i.e., it returns @var{resultp}. @comment time.h @comment ISO @deftypefun time_t mktime (struct tm *@var{brokentime}) -The @code{mktime} function is used to convert a broken-down time structure -to a simple time representation. It also ``normalizes'' the contents of -the broken-down time structure, by filling in the day of week and day of -year based on the other date and time components. +The @code{mktime} function converts a broken-down time structure to a +simple time representation. It also normalizes the contents of the +broken-down time structure, and fills in some components based on the +values of the others. The @code{mktime} function ignores the specified contents of the -@code{tm_wday} and @code{tm_yday} members of the broken-down time +@code{tm_wday}, @code{tm_yday}, @code{tm_gmtoff}, and @code{tm_zone} +members of the broken-down time structure. It uses the values of the other components to determine the calendar time; it's permissible for these components to have unnormalized values outside their normal ranges. The last thing that @code{mktime} does is adjust the components of the @var{brokentime} -structure (including the @code{tm_wday} and @code{tm_yday}). +structure, including the members that were initally ignored. If the specified broken-down time cannot be represented as a simple time, @code{mktime} returns a value of @code{(time_t)(-1)} and does not modify the contents of @var{brokentime}. -Calling @code{mktime} also sets the variable @code{tzname} with -information about the current time zone. @xref{Time Zone Functions}. +Calling @code{mktime} also sets the current time zone as if +@code{tzset} were called; @code{mktime} uses this information instead +of @var{brokentime}'s initial @code{tm_gmtoff} and @code{tm_zone} +members. @xref{Time Zone Functions}. @end deftypefun @comment time.h @@ -1053,8 +1055,8 @@ rather than in broken-down local time format. It is equivalent to asctime (localtime (@var{time})) @end smallexample -@code{ctime} sets the variable @code{tzname}, because @code{localtime} -does so. @xref{Time Zone Functions}. +Calling @code{ctime} also sets the current time zone as if +@code{tzset} were called. @xref{Time Zone Functions}. @end deftypefun @comment time.h @@ -1081,7 +1083,8 @@ This function is similar to the @code{sprintf} function (@pxref{Formatted Input}), but the conversion specifications that can appear in the format template @var{template} are specialized for printing components of the date and time @var{brokentime} according to the locale currently specified for -time conversion (@pxref{Locales}). +time conversion (@pxref{Locales}) and the current time zone +(@pxref{Time Zone Functions}). Ordinary characters appearing in the @var{template} are copied to the output string @var{s}; this can include multibyte character sequences. @@ -1392,9 +1395,10 @@ if (len == 0 && buf[0] != '\0') If @var{s} is a null pointer, @code{strftime} does not actually write anything, but instead returns the number of characters it would have written. -According to POSIX.1 every call to @code{strftime} implies a call to -@code{tzset}. So the contents of the environment variable @code{TZ} -is examined before any output is produced. +Calling @code{strftime} also sets the current time zone as if +@code{tzset} were called; @code{strftime} uses this information +instead of @var{brokentime}'s @code{tm_gmtoff} and @code{tm_zone} +members. @xref{Time Zone Functions}. For an example of @code{strftime}, see @ref{Time Functions Example}. @end deftypefun @@ -2037,7 +2041,7 @@ to get a Coordinated Universal Time value. It has syntax like [@code{+}|@code{-}]@var{hh}[@code{:}@var{mm}[@code{:}@var{ss}]]. This is positive if the local time zone is west of the Prime Meridian and negative if it is east. The hour must be between @code{0} and -@code{23}, and the minute and seconds between @code{0} and @code{59}. +@code{24}, and the minute and seconds between @code{0} and @code{59}. For example, here is how we would specify Eastern Standard Time, but without any Daylight Saving Time alternative: @@ -2082,17 +2086,51 @@ between @code{1} and @code{12}. The @var{time} fields specify when, in the local time currently in effect, the change to the other time occurs. If omitted, the default is -@code{02:00:00}. - -For example, here is how you would specify the Eastern time zone in the -United States, including the appropriate Daylight Saving Time and its dates -of applicability. The normal offset from UTC is 5 hours; since this is +@code{02:00:00}. The hours part of the time fields can range from +@minus{}167 through 167; this is an extension to POSIX.1, which allows +only the range 0 through 24. + +Here are some example @code{TZ} values, including the appropriate +Daylight Saving Time and its dates of applicability. In North +American Eastern Standard Time (EST) and Eastern Daylight Time (EDT), +the normal offset from UTC is 5 hours; since this is west of the prime meridian, the sign is positive. Summer time begins on -the first Sunday in April at 2:00am, and ends on the last Sunday in October +March's second Sunday at 2:00am, and ends on November's first Sunday at 2:00am. @smallexample -EST+5EDT,M4.1.0/2,M10.5.0/2 +EST+5EDT,M3.2.0/2,M11.1.0/2 +@end smallexample + +Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours +ahead of the prime meridian in winter, springing forward an hour on +March's fourth Tuesday at 26:00 (i.e., 02:00 on the first Friday on or +after March 23), and falling back on October's last Sunday at 02:00. + +@smallexample +IST-2IDT,M3.4.4/26,M10.5.0 +@end smallexample + +Western Argentina Summer Time (WARST) is 3 hours behind the prime +meridian all year. There is a dummy fall-back transition on December +31 at 25:00 daylight saving time (i.e., 24:00 standard time, +equivalent to January 1 at 00:00 standard time), and a simultaneous +spring-forward transition on January 1 at 00:00 standard time, so +daylight saving time is in effect all year and the initial @code{WART} +is a placeholder. + +@smallexample +WART4WARST,J1/0,J365/25 +@end smallexample + +Western Greenland Time (WGT) and Western Greenland Summer Time (WGST) +are 3 hours behind UTC in the winter. Its clocks follow the European +Union rules of springing forward by one hour on March's last Sunday at +01:00 UTC (@minus{}02:00 local time) and falling back on October's +last Sunday at 01:00 UTC (@minus{}01:00 local time). + +@smallexample +WGT3WGST,M3.5.0/-2,M10.5.0/-1 @end smallexample The schedule of Daylight Saving Time in any particular jurisdiction has |