[Previous]
[Contents]
[Next]

Global Data and the TZ Environment Variable

This chapter discusses:

Global data

Certain data items are used by the Watcom C/C++ runtime library and may be inspected (or changed in some cases) by a program. The defined items are:

unsigned int _amblksiz
Prototype in <stdlib.h>. The increment by which the "break" pointer for memory allocation is advanced when there's no freed block large enough to satisfy a request to allocate a block of memory. This value may be changed by a program at any time.
int __argc
Prototype in <stdlib.h>. The number of arguments passed to main().
char ** item __argv
Prototype in <stdlib.h>. A pointer to a vector containing the actual arguments passed to main(). The prototype isn't in a header file either; like _argc, you'll have to create your own extern declaration.
unsigned int daylight
Prototype in <time.h>. This variable has a value of one when daylight saving time is supported in this locale, and zero otherwise. Whenever a time function is called, the tzset() function is called to set the value of the variable. The value is determined from the value of the TZ environment variable.
char ** __near environ
Prototype in <stdlib.h>. This A pointer to an array of character pointers to the environment strings.
int errno
Prototype in <errno.h>. The number of the last error that was detected. The runtime library never resets errno to 0. Symbolic names for these errors are found in the <errno.h> header file. For more information, see
_fltused_
The C compiler places a reference to the _fltused_ symbol into any module that uses a floating-point library routine or library routine that requires floating-point support (for example, the use of a float or double as an argument to the printf() function).
unsigned char _osmajor
Prototype in <stdlib.h>. The major number for the version of QNX executing on the computer. If the current version is 4.10, the value is 4.
unsigned char _osminor
Prototype in <stdlib.h>. The minor number for the version of QNX executing on the computer. If the current version is 4.10, the value is 10.
FILE * stderr
Prototype in <stdio.h>. The standard error stream (set to the console by default).
FILE * stdin
Prototype in <stdio.h>. The standard input stream (set to the console by default).
FILE * stdout
Prototype in <stdio.h>. The standard output stream (set to the console by default).
int _threadid
int __threadid()
Prototype in <stddef.h>. This variable/function can be used to obtain the ID of the current thread.
Note: The QNX libraries aren't completely thread-safe. Before calling a function in a thread, check its Classification section to make sure it's safe to do so.
long int timezone
Prototype in <time.h>. The number of seconds of time that the local time zone is earlier than Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time (GMT)). Whenever a time function is called, the tzset() function is called to set the value of the variable. The value is determined from the value of the TZ environment variable.
char *tzname[2]
Prototype in <time.h>. This array of two pointers to character strings indicates the name of the standard abbreviation for the time zone and the name of the abbreviation for the time zone when daylight saving time is in effect. Whenever a time function is called, the tzset() function is called to set the values in the array. These values are determined from the value of the TZ environment variable.

The TZ environment variable

The TZ environment variable is used to establish the local time zone. The value of the variable is used by various time functions to compute times relative to Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time (GMT)).

The time on the computer should be set to UTC. Use the date command if the time isn't automatically maintained by the computer hardware.

The TZ environment variable can be set (before the program is executed) by using

or (during the program execution) by using the setenv() or putenv() library functions: 

    setenv( "TZ", "PST8PDT", 1 );
    putenv( "TZ=PST8PDT" );

The value of the variable can be obtained by using the getenv() function: 

    char *tzvalue;
      ...
    tzvalue = getenv( "TZ" );

The tzset() function processes the TZ environment variable, and sets the following global variables:

daylight
indicates if daylight saving time is supported in the locale
timezone
contains the number of seconds of time difference between the local time zone and Coordinated Universal Time (UTC)
tzname
a vector of two pointers to character strings containing the standard and daylight time-zone names

The value of the TZ environment variable should be set as follows (spaces are for clarity only):

std offset dst offset, rule

The expanded format is as follows:

stdoffset[dst[offset][,start[/time],end[/time]]]

where

std, dst
are three or more letters that are the designation for the standard (std) or summer (dst) time zone. Only std is required. If dst is omitted, summer time doesn't apply in this locale. Upper- and lowercase letters are allowed. Any characters except for a leading colon (:), digits, comma (,), minus (-), plus (+), and ASCII NUL (\0) are allowed.
offset
indicates the value one must add to the local time to arrive at Coordinated Universal Time (UTC). The offset has the form:

hh[:mm[:ss]]

The minutes (mm) and seconds (ss) are optional. The hour (hh) is required, and may be a single digit.

The offset following std is required. If no offset follows dst, summer time is assumed to be one hour ahead of standard time.

One or more digits may be used; the value is always interpreted as a decimal number. The hour may be between 0 and 24, and the minutes (and seconds) - if present - between 0 and 59. If preceded by a "-", the time zone is east of the Prime Meridian; otherwise it's west (which may be indicated by an optional preceding "+").

rule
indicates when to change to and back from summer time. The rule has the form:

date/time,date/time

where the first date describes when the change from standard to summer time occurs, and the second date describes when the change back happens. Each time field describes when, in current local time, the change to the other time is made.

The format of date may be one of the following:

Jn
The Julian day n (1 <= n <= 365). Leap days aren't counted. That is, in all years - including leap years - February 28 is day 59 and March 1 is day 60. It's impossible to refer explicitly to the occasional February 29.
n
The zero-based Julian day (0 <= n <= 365). Leap years are counted, and it is possible to refer to February 29.
Mm.n.d
The dth day (0 <= d <= 6) of week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means "the last d day in month m", which may occur in the fourth or fifth week). Week 1 is the first week in which the dth day occurs. Day zero is Sunday.

The time has the same format as offset, except that no leading sign ("+" or "-") is allowed. The default, if time is omitted, is 02:00:00.

Whenever ctime(), _ctime(), localtime(), _localtime() or mktime() is called, the time zone names contained in the external variable tzname are set as if the tzset() function had been called. The same is true if the %Z directive of strftime() is used.

Some examples are given below.

TZ=EST5EDT
This is the default when the TZ variable isn't set.
TZ=EST5EDT4,M4.1.0/02:00:00,M10.5.0/02:00:00
This is the full specification for the default when the TZ variable isn't set.
TZ=PST8PDT
TZ=NST3:30NDT1:30
TZ=Central Europe Time-2:00
TZ=JST-9
[Previous]
[Contents]
[Next]