timesync.library documentation...

Have a question about our Software Developer Kit? Ask them here.
Post Reply
chris
Posts: 562
Joined: Sat Jun 18, 2011 11:05 am
Contact:

timesync.library documentation...

Post by chris »

...is practically non-existant. Thankfully there is only one function and most of the tags are pretty self-explanatory.

However, this needs explanation (as I had to work it out by trial and error):
#define RS_UTCOFFSET (TAG_USER+4) // (LONG)
Should be documented as (something like) "This tag specifies the offset of the wanted timezone in seconds ahead of UTC. eg. GMT+1 is 3600. NB: this is not the same order of magnitude nor sign as the offset returned by timezone.library"

I would also like to know what values the following tag expects:
#define RS_PROTOCOL (TAG_USER+1) // (UBYTE)
I'd have thought it would be defined RS_PROTOCOL_NTP etc, but nothing like that exists in the header.

I'd like to know what the following tag actually does:
#define RS_DIFFTIME (TAG_USER+7) // (struct timeval *)
Difference between remote and local time, perhaps? Does that take into account RS_UTCOFFSET? How does it return time behind local time, as timeval.tv_secs is unsigned?

The below are obviously error codes, but the function itself returns error codes, so what exactly are these for?
#define RS_ERRSTR (TAG_USER+8) // (STRPTR *)
#define RS_ERRNO (TAG_USER+9) // (LONG *)
User avatar
gazelle
Posts: 102
Joined: Sun Mar 04, 2012 12:49 pm
Location: Frohnleiten, Austria

Re: timesync.library documentation...

Post by gazelle »

@chris:

I do have a "timesync.doc" in "SDK:Documentation/AutoDocs/"
RS_UTCOFFSET (LONG)

Specify the offset in seconds between local time and Coordinated Universal
Time (UTC, formerly referred to as "Greenwich Mean Time" GMT).
Defaults to using the offset from Timezone or Locale.
When RS_SERVER is set to 'PREFS' the UTC offset specified from the Time
prefs editor will be used.
RS_PROTOCOL (UBYTE)

Specify which protocol should be used.
Currently only the Network Time Protocol (NTP) can be used by default.
RS_DIFFTIME (struct timeval *)

Specify a pointer to a timeval which will hold the difference between
current system time and the time from the remote server.
Defaults to NULL.
RS_ERRSTR (STRPTR *)

Specify a pointer to a STRPTR which will contain an error message if the
time couldn't be retrieved successfully from the remote server.
Defaults to NULL.

RS_ERRNO (LONG *)

Specify a pointer to LONG which will contain a socket error code if the
time couldn't be retrieved successfully from the remote server.
Defaults to NULL.
Error codes are defined in <libraries/timesync.h>.
chris
Posts: 562
Joined: Sat Jun 18, 2011 11:05 am
Contact:

Re: timesync.library documentation...

Post by chris »

gazelle wrote:I do have a "timesync.doc" in "SDK:Documentation/AutoDocs/"
So do I, but it's 758 bytes long and pretty much says "look at the header". It doesn't contain any of what you've quoted.
RS_UTCOFFSET (LONG)
Defaults to using the offset from Timezone or Locale.
When RS_SERVER is set to 'PREFS' the UTC offset specified from the Time
prefs editor will be used.
That's interesting. That means RS_SERVER has some special function when set to PREFS (I'm guessing it's "use the prefs timeserver" - does it use the prefs port as well, or does RS_PORT need to be set to something special?). It also means I'm wasting my time getting/calculating the offset myself. Can you paste the RS_SERVER section here please?
RS_DIFFTIME (struct timeval *)

Specify a pointer to a timeval which will hold the difference between
current system time and the time from the remote server.
Defaults to NULL.
Right, I still don't like this one. I've just played around with it, after somebody mentioned the "remote time" section of Time Prefs was always running behind by a second.

I'm getting values like the following just after syncing:

Code: Select all

0, 1094
-1, 996573
0, 997
-1, 999909
-1, 996040
0, 3719
-1, 974539
-1, 999960
-1, 996974
0, 1107
The first value is tv_sec, the second is tv_usec, as produced by the following code:

Code: Select all

int timesync(void)
{
	int err;
	struct timeval timediff;

	err = RemoteSync(RS_SERVER, server,
					RS_PORT, port,
					RS_SETSYSTIME, savesys,
					RS_SAVETIME, savebc,
					RS_DIFFTIME, &timediff,
					TAG_DONE);

printf("%ld, %ld\n", timediff.tv_sec, timediff.tv_usec);

	return err;
}
Firstly: As I mentioned previously, timeval.tv_sec is supposed to be unsigned according to devices/timer.h:

Code: Select all

struct timeval
{
    ULONG tv_secs;
    ULONG tv_micro;
};

#else

#define tv_secs  tv_sec
#define tv_micro tv_usec
Secondly, what does that actually mean? I would interpret -1,999960 as "the system time is 1 second and 999960 microseconds behind the remote time". Whereas I think the correct interpretation is supposed to be "1 second behind, plus 999960 microseconds, ie. 40 microseconds behind the remote time". Or maybe it's how far the remote time is trailling behind system time.

This really ought to be returning a custom structure;
(a) I don't think the timeval structure should be abused in this way
(b) I think it is confusing and needs to be made clearer

struct rs_timeval{
BOOL negative
ULONG secs
ULONG microsecs
}

Then -1,999960 would be negative=TRUE, secs=0, microsecs=40

Besides this, Time Prefs needs fixing so it is interpreting the difference value correctly. It might even be ignoring the microseconds, I can't tell.
User avatar
gazelle
Posts: 102
Joined: Sun Mar 04, 2012 12:49 pm
Location: Frohnleiten, Austria

Re: timesync.library documentation...

Post by gazelle »

Can you paste the RS_SERVER section here please?
I send you my timesync.doc per PM, it's from the SDK 53.20 with 2530 bytes.

Can't help you with the RS_DIFFTIME problem, but using two ULONGs for a timediff seems not to be the best choice.

edit:
Another thought would be the new Amiga way is "struct TimeVal" and "struct timeval" is the Unix/POSIX way in which the two members are signed. The value makes sense if you look at SDK:newlib/include/sys/time.h:

Code: Select all

#define	timersub(a, b, result)						      \
  do {									      \
    (result)->tv_sec = (a)->tv_sec - (b)->tv_sec;			      \
    (result)->tv_usec = (a)->tv_usec - (b)->tv_usec;			      \
    if ((result)->tv_usec < 0) {					      \
      --(result)->tv_sec;						      \
      (result)->tv_usec += 1000000;					      \
    }									      \
  } while (0)
User avatar
salass00
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 530
Joined: Sat Jun 18, 2011 3:12 pm
Location: Finland
Contact:

Re: timesync.library documentation...

Post by salass00 »

@chris

Quoting from devices/timer.h:

Code: Select all

/* The 'struct timeval' definition used by AmigaOS since its introduction in
   the year 1985 was similar to a data structure of the same name as used in
   the Unix domain. Similar, but not identical. This had consequences when
   porting software to the Amiga which came from a Unix/POSIX system, as it
   clashed with the Amiga definition of the 'struct timeval'. Rather than
   use compatibility workarounds, the 'struct timeval' and 'struct timerequest'
   data structures were replaced with 'struct TimeVal' and 'struct TimeRequest',
   respectively.

   If you need to compile your software with the old AmigaOS 1.x/2.x/3.x
   compatible timeval/timerequest definitions, define the preprocessor
   symbol __USE_OLD_TIMEVAL__ in your header files, makefile or source code. */
So if you want to use old timeval structure with tv_secs and tv_micro fields you should define __USE_OLD_TIMEVAL__ otherwise you should use struct TimeVal which has fields called Seconds and Microseconds.
User avatar
gazelle
Posts: 102
Joined: Sun Mar 04, 2012 12:49 pm
Location: Frohnleiten, Austria

Re: timesync.library documentation...

Post by gazelle »

@salass00

You misunderstood chris. The "struct timeval" is specified by the timesync.library (RS_DIFFTIME (struct timeval *)) which is an OS4 component, AFAIK.

You should reread his second post.
User avatar
salass00
AmigaOS Core Developer
AmigaOS Core Developer
Posts: 530
Joined: Sat Jun 18, 2011 3:12 pm
Location: Finland
Contact:

Re: timesync.library documentation...

Post by salass00 »

gazelle wrote: You misunderstood chris. The "struct timeval" is specified by the timesync.library (RS_DIFFTIME (struct timeval *)) which is an OS4 component, AFAIK.
Which probably refers to "struct timeval" only because it was written before the timeval->TimeVal, timerequest->TimeRequest SDK change.

To reiterate unless you define "__USE_OLD_TIMEVAL__" timeval is a clib defined structure and the AmigaOS structure is called TimeVal, not timeval.
chris
Posts: 562
Joined: Sat Jun 18, 2011 11:05 am
Contact:

Re: timesync.library documentation...

Post by chris »

salass00 wrote:
gazelle wrote: You misunderstood chris. The "struct timeval" is specified by the timesync.library (RS_DIFFTIME (struct timeval *)) which is an OS4 component, AFAIK.
Which probably refers to "struct timeval" only because it was written before the timeval->TimeVal, timerequest->TimeRequest SDK change.

To reiterate unless you define "__USE_OLD_TIMEVAL__" timeval is a clib defined structure and the AmigaOS structure is called TimeVal, not timeval.
Which confirms that timesync.library is trying to plug signed values into unsigned variables, which is a bug. Unless it really is supposed to be UNIX-style struct timeval, which would be odd as it's an AmigaOS native component.
Post Reply