Added target docs on the clock_... functions.

diff --git a/doc/apple2.sgml b/doc/apple2.sgml
index aa3089957fa0ec183994cf4a072a7d6a4adbbb42..f61a8a68e2590d233f28ccf85fde273faa6267ea 100644 (file)
--- a/doc/apple2.sgml
+++ b/doc/apple2.sgml
@@ -469,25 +469,47 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
 
 <sect1>Direct console I/O<p>
 
-<descrip>
-
-  <tag/Color/
-  The Apple&nbsp;&rsqb;&lsqb; has no color text mode. Therefore the functions textcolor(),
-  bgcolor() and bordercolor() have no effect.
-
-</descrip><p>
+The Apple&nbsp;&rsqb;&lsqb; has no color text mode. Therefore the functions
+<tt/textcolor()/, <tt/bgcolor()/ and <tt/bordercolor()/ have no effect.
 
 
 <sect1>Random number generator<p>
 
-<descrip>
-
-  <tag/Random number seed/
-  The random number seed is generated from the time the program waits for user input.
-  Therefore it is necessary to wait for at least one user keypress either via Standard
-  I/O or via Direct console I/O before initializing the pseudo random number generator.
-
-</descrip><p>
+The random number seed is generated from the time the program waits for user input.
+Therefore it is necessary to wait for at least one user keypress either via Standard
+I/O or via Direct console I/O before initializing the pseudo random number generator.
+
+
+<sect1>Realtime clock<p>
+
+There are several types of realtime clocks. It's not desirable to have specific code
+for all of them. As ProDOS 8 supports file timestamps, realtime clock owners usually
+use ProDOS 8 drivers for their realtime clock. Those drivers read the realtime clock
+and write the result to the date/time location in RAM (&dollar;BF90 to &dollar;BF93).
+ProDOS 8 reads the date/time from that RAM location. If there's no realtime clock the
+RAM location keeps containing zeros. ProDOS 8 uses those zeros as timestamps and the
+files show up in a directory as <tt/&lt;NO DATE&gt;/.
+
+There's no common interface to set realtime clocks so if a realtme clock <bf/IS/
+present there's just nothing to do. However, if there's <bf/NO/ realtime clock present,
+the user might very well be interest to "manually" set the RAM location in order to
+have timestamps. But he surely doesn't want to manually set the RAM location over and
+over again. Rather he wants to set it just once after booting ProDOS 8.
+
+From that perspective it makes most sense to not set both the date and the time but
+rather only set the date and have the time just stay zero. Then files show up in a
+directory as <tt/DD-MON-YY  0:00/.
+
+So <tt/clock_settime()/ checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_settime()/ fails with
+<tt/ERANGE/. Otherwise <tt/clock_settime()/ sets the date - and completely ignores
+the time provided as parameter.
+
+<tt/clock_getres()/ too checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_getres()/ returns a time
+resolution of one minute. Otherwise <tt/clock_getres()/ presumes that the only one
+who sets the RAM location is <tt/clock_settime()/ and therefore returns a time
+resolution of one day.
 
 
 

diff --git a/doc/apple2enh.sgml b/doc/apple2enh.sgml
index fbdba908b76a3d7587a1b84a47167bff3f5289d7..649c6ef9f3cf596c257a620d1da09fe21de640b0 100644 (file)
--- a/doc/apple2enh.sgml
+++ b/doc/apple2enh.sgml
@@ -470,25 +470,47 @@ BASIC.SYSTEM) there are some limitations for DOS 3.3:
 
 <sect1>Direct console I/O<p>
 
-<descrip>
-
-  <tag/Color/
-  The enhanced&nbsp;Apple&nbsp;//e has no color text mode. Therefore the functions
-  textcolor(), bgcolor() and bordercolor() have no effect.
-
-</descrip><p>
+The enhanced&nbsp;Apple&nbsp;//e has no color text mode. Therefore the functions
+<tt/textcolor()/, <tt/bgcolor()/ and <tt/bordercolor()/ have no effect.
 
 
 <sect1>Random number generator<p>
 
-<descrip>
-
-  <tag/Random number seed/
-  The random number seed is generated from the time the program waits for user input.
-  Therefore it is necessary to wait for at least one user keypress either via Standard
-  I/O or via Direct console I/O before initializing the pseudo random number generator.
-
-</descrip><p>
+The random number seed is generated from the time the program waits for user input.
+Therefore it is necessary to wait for at least one user keypress either via Standard
+I/O or via Direct console I/O before initializing the pseudo random number generator.
+
+
+<sect1>Realtime clock<p>
+
+There are several types of realtime clocks. It's not desirable to have specific code
+for all of them. As ProDOS 8 supports file timestamps, realtime clock owners usually
+use ProDOS 8 drivers for their realtime clock. Those drivers read the realtime clock
+and write the result to the date/time location in RAM (&dollar;BF90 to &dollar;BF93).
+ProDOS 8 reads the date/time from that RAM location. If there's no realtime clock the
+RAM location keeps containing zeros. ProDOS 8 uses those zeros as timestamps and the
+files show up in a directory as <tt/&lt;NO DATE&gt;/.
+
+There's no common interface to set realtime clocks so if a realtme clock <bf/IS/
+present there's just nothing to do. However, if there's <bf/NO/ realtime clock present,
+the user might very well be interest to "manually" set the RAM location in order to
+have timestamps. But he surely doesn't want to manually set the RAM location over and
+over again. Rather he wants to set it just once after booting ProDOS 8.
+
+From that perspective it makes most sense to not set both the date and the time but
+rather only set the date and have the time just stay zero. Then files show up in a
+directory as <tt/DD-MON-YY  0:00/.
+
+So <tt/clock_settime()/ checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_settime()/ fails with
+<tt/ERANGE/. Otherwise <tt/clock_settime()/ sets the date - and completely ignores
+the time provided as parameter.
+
+<tt/clock_getres()/ too checks if the current time equals 0:00. If it does <bf/NOT/
+then a realtime clock is supposed to be active and <tt/clock_getres()/ returns a time
+resolution of one minute. Otherwise <tt/clock_getres()/ presumes that the only one
+who sets the RAM location is <tt/clock_settime()/ and therefore returns a time
+resolution of one day.
 
 
 

diff --git a/doc/c128.sgml b/doc/c128.sgml
index dd9af2d6b9c6510ad565e7ee34372e427899c2dd..84b601ab770293e117a4964f0b4b9b6f57a63152 100644 (file)
--- a/doc/c128.sgml
+++ b/doc/c128.sgml
@@ -339,6 +339,13 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c128-
 <sect>Limitations<p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 
 <sect>Other hints<p>
 

diff --git a/doc/c64.sgml b/doc/c64.sgml
index 328a77ab6ace6ba69b6efd6edee50e14d0876c23..8c910666cb0fb37ddc88d75d7cc9089c70b3cd8e 100644 (file)
--- a/doc/c64.sgml
+++ b/doc/c64.sgml
@@ -418,6 +418,13 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/c64-1
 <sect>Limitations<p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 
 <sect>Other hints<p>
 

diff --git a/doc/cbm510.sgml b/doc/cbm510.sgml
index 5c7c0f767015fb806eff9c08dc3302b956a931e8..5df8f06f6b3d03f843cbfe5bded8c154e389822f 100644 (file)
--- a/doc/cbm510.sgml
+++ b/doc/cbm510.sgml
@@ -242,6 +242,13 @@ The default drivers, <tt/mouse_stddrv (mouse_static_stddrv)/, point to <tt/cbm51
 <sect>Limitations<label id="limitations"><p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 <sect1>Kernal and hardware access<p>
 
 Since the program runs in bank 0, and the kernal and all I/O chips are located

diff --git a/doc/cbm610.sgml b/doc/cbm610.sgml
index c1faefd5115a8d0abadb5385259e779c61beb133..49313c4d2c0da6bc83e07dc2fc2fb0f9590db577 100644 (file)
--- a/doc/cbm610.sgml
+++ b/doc/cbm610.sgml
@@ -224,6 +224,13 @@ No mouse drivers are currently available for the Commodore 610.
 <sect>Limitations<label id="limitations"><p>
 
 
+<sect1>Realtime clock<p>
+
+The realtime clock functions use the CIA1 TOD clock. As that clock only stores
+the time but not the date, the date set by <tt/clock_settime()/ ist simply stored
+inside the C library for retrieval in the same program via <tt/clock_gettime()/.
+
+
 <sect1>Kernal and hardware access<p>
 
 Since the program runs in bank 1, and the kernal and all I/O chips are located