Document __useTimeTool and add a declaration for it.

ORCACDefs/time.h

@@ -53,6 +53,8 @@ clock_t         __clocks_per_sec(void);
 typedef unsigned long size_t;
 #endif
 
+extern int      __useTimeTool;
+
 char           *asctime(const struct tm *);
 clock_t         clock(void);
 char           *ctime(const time_t *);

cc.notes

@@ -1052,7 +1052,7 @@ Some conversion specifiers can also include an "E" or "O" modifier (e.g. "%Ec").
 
 The %g, %G, and %V specifiers are based on the ISO 8601 week-based year, in which weeks begin on a Monday and week 01 of a year is the week that includes January 4.  According to this system, the first few days of some years are considered to be in week 52 or 53 of the previous year, and the last few days of some years are considered to be in week 01 of the next year.
 
-If the Time Tool Set by Geoff Weiss is installed and active, the %z and %Z specifiers will use it to obtain the time zone offset.  (In ORCA/C, the %Z specifier currently represents the time zone in the same numeric format as %z.)  If the Time Tool Set is not installed or has not been started, those specifiers will not produce any output.  For more information on using the Time Tool Set, see the discussion of gmtime() below.
+If the __useTimeTool variable (described below) has been set to a non-zero value, the %z and %Z specifiers will use the Time Tool Set to obtain the time zone offset.  (In ORCA/C, the %Z specifier currently represents the time zone in the same numeric format as %z.)  Otherwise, those specifiers will not produce any output.
 
 If strftime() is able to write the full formatted date/time string to s, it returns the total number of characters written, not including the terminating null.  If it is not able to do so because the full size exceeds maxsize, then it returns 0 and the contents of s are unspecified.
 
@@ -1396,9 +1396,18 @@ long double strtold(const char * restrict str, char ** restrict ptr);
 
 As currently implemented in ORCA/C, strtof and strtold behave identically to strtod, all giving values with the precision and range of long double.
 
-20. If the Time Tool Set by Geoff Weiss is installed and active, then the gmtime() function will use it to determine the difference between the system's local time and UTC, and the structure produced will reflect the UTC time.  If the Time Tool Set is not installed or has not been started, then gmtime() will assume that the system's local time is equal to UTC, as it did previously.
+20. Several <time.h> functions can now use the Time Tool Set by Geoff Weiss to determine the time zone.  This behavior is controlled by a new variable:
 
-Note that the ORCA/C run-time libraries will not start up the Time Tool Set.  If you want library functions to use it, your program will need to include code to load it and start it up before you make any library calls that would use it, and then to shut it down and unload it before the program exits.  See the Time Tool Set website for more information and downloads:
+#include <time.h>
+extern int __useTimeTool;
+
+The affected functions are gmtime(), strftime() (described above), and timespec_get() (described below).
+
+If __useTimeTool is set to 0 (the default), gmtime() and timespec_get() will behave as if the system's local time is equal to UTC, and strftime()'s %z and %Z conversion specifiers will produce no output because time zone information is not available.
+
+If __useTimeTool is set to a non-zero value, gmtime() and timespec_get() will give the UTC time, using the Time Tool Set to determine the offset between local time and UTC, and strftime()'s %z and %Z conversion specifiers will produce a string representation of that offset.  The __useTimeTool variable must only be set to a non-zero value if the Time Tool Set is active.  Your program will need to include code to load it and start it up before you make any library calls that would use it, and then to shut it down and unload it before the program exits.  The ORCA libraries will not do this for you.
+
+See the Time Tool Set website for more information and downloads:
 
 https://timetool.gwlink.net
 
@@ -1413,7 +1422,7 @@ int timespec_get(struct timespec *ts, int base);
 
 This function sets the structure *ts to a representation of the current time based on a specified time base determined by the base parameter (which should be a macro value defined in <time.h>).  If it completes successfully, it returns the value of base; otherwise, it returns 0.
 
-The only time base supported by ORCA/C is TIME_UTC.  This gives the time in seconds and nanoseconds since an implementation-defined time known as the epoch.  In ORCA/C, the epoch is 13 Nov 1969 00:00:00.  If the Time Tool Set is installed and active, timespec_get will use it to determine the time zone offset from UTC and provide a representation of the current UTC time; otherwise, it provides a representation of the current local time, assuming it is equal to UTC.  For more information on using the Time Tool Set, see the discussion of gmtime() above.
+The only time base supported by ORCA/C is TIME_UTC.  This gives the time in seconds and nanoseconds since an implementation-defined time known as the epoch.  In ORCA/C, the epoch is 13 Nov 1969 00:00:00.  If the __useTimeTool variable (described above) has been set to a non-zero value, timespec_get will use the Time Tool Set to determine the time zone offset from UTC and provide a representation of the current UTC time; otherwise, it provides the current local time, assuming it is equal to UTC.
 
 Although struct timespec can represent a time with nanosecond resolution, ORCA/C currently only reports the time with a resolution of one second, so ts->tv_nsec is always set to 0.