MiNT time management

If you are not a programmer or not particularly interested in the internals you can skip this file.

7. Obsoleted system calls

TOS provides four time related system calls:

• Tgettime Get the time of the day.
• Tgetdate Get the current date.
• Tsettime Set the time of the day. Under MiNT this call is reserved to the super-user.
• Tsetdate Set the current date. This is of course also reserved to the super-use under MiNT.

It was common understanding among software developers that these facilities return the time and date in local time representation and that time and date values passed to the time setting functions also expect the time in local representation.

These facilities are still supported by the MiNT kernel for compatibility reasons but their use is deprecated now. Yet, software that still uses these calls can rely on the old behavior, i.e. Tsettime and Tsetdate still expect local times, and Tgettime and Tgetdate still return local times.

8. New system calls

With MiNT 1.14.8 two new system calls are introduced in the kernel:

    long Tgettimeofday (long tv, long tzp);
    long Tsettimeofday (long tv, long tzp);

The opcode for Tgettimeofday is 0x155, the opcode for Tsettimeofday is 0x156. Please change your library binding if you want to use them.

The argument TV is actually a pointer to the following structure:

    struct timeval {
      long int tv_sec;
      long int tv_usec;
    };

The argument TZP is a pointer to the structure

    struct timezone {
      long int tz_minuteswest;
      long int tz_dsttime; 
    };

The member TV_SEC of the TV argument holds the number of seconds elapsed since the epoch. The epoch is "Thu, Jan 1 1970 00:00:00 UTC". The member TV_USEC of TV holds the fractional part of TV_SEC measured in microseconds.

The member TZ_MINUTESWEST of TZ holds the offset to UTC in second. Timezones east of the zero-meridian (e.g. Eastern Europe) have a negative value, timezones west of the zero-meridian (e.g. America) have a positive value. The member TZ_DSTTIME is non-zero if daylight savings time applies during some part of the year.

Implementors of library bindings should be aware that the definition of struct timezone is non-standard. The members are actually int and not long int (this applies only to struct timezone; the members of struct timeval are always longs). 16-bit libraries will have to copy the contents of the structure that TZP points to.

You may safely pass NULL for either arguments. This isn't considered an error.

Both functions return zero for success or a negative error value for failure (in fact Tgettimeofday can never fail). The following error conditions are defined:

The TZ_DSTTIME member of TZP is stored but not evaluated within the kernel. Beware not to misunderstand its meaning: If non-zero it simply signifies that daylight savings time apply during some part of the year, not necessarily now. In other words: If it is non-zero someday it should be non-zero during the entire year.

The Ssystem call has a new command CLOCK_MODE (see the file ssystem.doc for details). This command allows to retrieve or set the kernel clock mode, i.e. to specify whether the hardware clock is meant to run in UTC or in local time.

9. Future enhancements

It is planned to make MiNT compliant with the kernel time keeping model described in RFC1305. This model is already successfully implemented in operating systems such as SunOS, Ultrix, OSF/1, HP-UX and Linux. Please expect the internal realization to change in the future.

10. Bugs

Many, many time-keeping variables inside the kernel use the old TOS format (which is more or less derived from MS-DOS). This was probably short-sighted and it causes difficulties now: You can really confuse the system if you keep on changing the system timezone or the kernel clock mode too often. Timestamps can get corrupted and processes that rely on precise timing can get confused. Thus, you are strongly discouraged to change the system timezone or the kernel clock mode from somewhere else than mint.cnf. In mint.cnf you should call the tzinit program as soon as possible.