diff options
Diffstat (limited to 'newtzset.3')
| -rw-r--r-- | newtzset.3 | 206 |
1 files changed, 123 insertions, 83 deletions
diff --git a/newtzset.3 b/newtzset.3 index 78b6b6ce67c4..b1384f32df0b 100644 --- a/newtzset.3 +++ b/newtzset.3 @@ -9,9 +9,9 @@ tzset \- initialize time conversion information .el .ds - \- .B #include <time.h> .PP -.B timezone_t tzalloc(char const *TZ); +.BI "timezone_t tzalloc(char const *" TZ ); .PP -.B void tzfree(timezone_t tz); +.BI "void tzfree(timezone_t " tz ); .PP .B void tzset(void); .PP @@ -31,62 +31,30 @@ The .B tzalloc function allocates and returns a timezone object described by -.BR TZ . -If -.B TZ -is not a valid timezone description, or if the object cannot be allocated, -.B tzalloc -returns a null pointer and sets -.BR errno . -.PP -The -.B tzfree -function -frees a timezone object -.BR tz , -which should have been successfully allocated by -.BR tzalloc . -This invalidates any -.B tm_zone -pointers that -.B tz -was used to set. -.PP -The -.B tzset -function -acts like -.BR tzalloc(getenv("TZ")) , -except it saves any resulting timezone object into internal -storage that is accessed by -.BR localtime , -.BR localtime_r , -and -.BR mktime . -The anonymous shared timezone object is freed by the next call to -.BR tzset . -If the implied call to -.B tzalloc -fails, -.B tzset -falls back on Universal Time (UT). +.IR TZ . .PP If -.B TZ -is null, the best available approximation to local (wall +.I TZ +is a null pointer, +.B tzalloc +uses the best available approximation to local (wall clock) time, as specified by the .BR tzfile (5)-format file .B localtime -in the system time conversion information directory, is used. +in the system time conversion information directory. +.PP If -.B TZ +.I TZ is the empty string, -UT is used, with the abbreviation "UTC" +.B tzalloc +uses Universal Time (UT), with the abbreviation "UTC" and without leap second correction; please see .BR newctime (3) -for more about UT, UTC, and leap seconds. If -.B TZ +for more about UT, UTC, and leap seconds. +.PP +If +.I TZ is nonnull and nonempty: .IP if the value begins with a colon, it is used as a pathname of a file @@ -98,24 +66,25 @@ and, if that file cannot be read, is used directly as a specification of the time conversion information. .PP When -.B TZ -is used as a pathname, if it begins with a slash, -it is used as an absolute pathname; otherwise, -it is used as a pathname relative to a system time conversion information +.I TZ +contents are used as a pathname, a pathname beginning with +.q "/" +is used as-is; otherwise +the pathname is relative to a system time conversion information directory. The file must be in the format specified in .BR tzfile (5). .PP When -.B TZ +.I TZ is used directly as a specification of the time conversion information, -it must have the following syntax (spaces inserted for clarity): +it must have the following syntax: .IP \fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]] .PP Where: .RS -.TP 15 +.TP .IR std " and " dst Three or more bytes that are the designation for the standard .RI ( std ) @@ -196,7 +165,7 @@ describes when the change back happens. Each .I time field describes when, in current local time, the change to the other time is made. -As an extension to POSIX, daylight saving is assumed to be in effect +As an extension to POSIX.1-2017, daylight saving is assumed to be in effect all year if it begins January 1 at 00:00 and ends December 31 at 24:00 plus the difference between daylight saving and standard time, leaving no room for standard time in the calendar. @@ -205,7 +174,7 @@ The format of .I date is one of the following: .RS -.TP 10 +.TP .BI J n The Julian day .I n @@ -238,16 +207,16 @@ first week in which the .IR d' th day occurs. Day zero is Sunday. .RE -.IP "" 15 +.IP The .I time has the same format as .I offset -except that POSIX does not allow a leading sign (\c +except that POSIX.1-2017 does not allow a leading sign (\c .q "\*-" or .q "+" ). -As an extension to POSIX, the hours part of +As an extension to POSIX.1-2017, the hours part of .I time can range from \-167 through 167; this allows for unusual rules such as @@ -259,9 +228,9 @@ is not given, is .RE .LP Here are some examples of -.B TZ +.I TZ values that directly specify the timezone; they use some of the -extensions to POSIX. +extensions to POSIX.1-2017. .TP .B EST5 stands for US Eastern Standard @@ -306,43 +275,114 @@ The abbreviations for standard and daylight saving time are and .q "\*-02". .PP -If no -.I rule -is present in -.BR TZ , -the rules specified -by the +If +.I TZ +specifies daylight saving time but does not specify a +.IR rule , +and the optional .BR tzfile (5)-format file .B posixrules -in the system time conversion information directory are used, with the -standard and daylight saving time offsets from UT replaced by those specified by -the +is present in the system time conversion information directory, the +rules in +.B posixrules +are used, with the +.B posixrules +standard and daylight saving time offsets from UT +replaced by those specified by the .I offset values in -.BR TZ . +.IR TZ . +However, the +.B posixrules +file is obsolete: if it is present it is only for backward compatibility, +and it does not work reliably. +Therefore, if a +.I TZ +string directly specifies a timezone with daylight saving time, +it should specify the daylight saving rules explicitly. .PP For compatibility with System V Release 3.1, a semicolon .RB ( ; ) may be used to separate the .I rule -from the rest of the specification. +from the rest of the specification; +this is an extension to POSIX. +.PP +The +.B tzfree +function +frees a timezone object +.IR tz , +which should have been successfully allocated by +.BR tzalloc . +This invalidates any +.B tm_zone +pointers that +.I tz +was used to set. +.PP +The +.B tzset +function +acts like +.BR tzalloc(getenv("TZ")) , +except it saves any resulting timezone object into internal +storage that is accessed by +.BR localtime , +.BR localtime_r , +and +.BR mktime . +The anonymous shared timezone object is freed by the next call to +.BR tzset . +If the implied call to +.B getenv +fails, +.B tzset +acts like +.BR tzalloc(nullptr) ; +if the implied call to +.B tzalloc +fails, +.B tzset +falls back on UT. +.SH "RETURN VALUE" +If successful, the +.B tzalloc +function returns a nonnull pointer to the newly allocated object. +Otherwise, it returns a null pointer and sets +.IR errno . +.SH ERRORS +.TP +.B EOVERFLOW +.I TZ +directly specifies time conversion information, +and contains an integer out of machine range +or a time zone abbreviation that is too long for this platform. +.PP +The +.B tzalloc +function may also fail and set +.I errno +for any of the errors specified for the routines +.BR access (2), +.BR close (2), +.BR malloc (3), +.BR open (2), +and +.BR read (2). .SH FILES .ta \w'/usr/share/zoneinfo/posixrules\0\0'u -/usr/share/zoneinfo timezone information directory +/etc/localtime local timezone file .br -/usr/share/zoneinfo/localtime local timezone file +/usr/share/zoneinfo timezone directory .br -/usr/share/zoneinfo/posixrules default DST rules (obsolete, - and can cause bugs if present) +/usr/share/zoneinfo/posixrules default DST rules (obsolete) .br /usr/share/zoneinfo/GMT for UTC leap seconds -.sp -If -.B /usr/share/zoneinfo/GMT -is absent, -UTC leap seconds are loaded from -.BR /usr/share/zoneinfo/posixrules . +.PP +If /usr/share/zoneinfo/GMT is absent, +UTC leap seconds are loaded from /usr/share/zoneinfo/GMT0 if present. .SH SEE ALSO getenv(3), newctime(3), |