HomeGEMDOSFile functionsProcess functions

5.10 Date and Time

Talarm     Alarm function.
Tgetdate   Obtains date.
Tgettime   Obtains time.
Tgettimeofday Interrogates the state of the internal, high resolution system clock.
Tmalarm    Reads/sets a process alarm for the current process.
Tsetdate   Sets date.
Tsetitimer Sets a periodical timer.
Tsettime   Sets time.
Tsettimeofday Sets the state of the internal, high resolution system clock.

See also: Date and Time in XBIOS

5.10.1 Talarm

Name: »Talarm« - Reads/sets a process alarm for the current process.
Opcode: 288 (0x0120)
Syntax: int32_t Talarm ( int32_t time );
Description: The function Talarm sends a SIGALRM signal to the calling process after time seconds.

If no signal-handler was installed for this signal with Psignal, then the process will be terminated immediately (i.e. on receiving the signal).

By setting the value of time = 0, an earlier set alarm can be cancelled. If time is negative, then the function has no effect and only the return value is delivered.
Return value: The function returns the time (in seconds) remaining before the SIGALRM signal is triggered (if an alarm has been activated), or otherwise the value 0 if no alarm was scheduled before this call.
Availability: As of the first in MultiTOS integrated MiNT version 1.04.

The call was introduced in the MiNT version 0.8pl8, but prior to the version 1.12 the code contained a bug that affected its functionality.
Group: Date and Time
See also: Binding   Tmalarm   Pause   Psignal   Signale

5.10.1.1 Bindings for Talarm

C: int32_t Talarm ( int32_t time );
Assembler:
move.l    time,-(sp)   ; Offset 2
move.w    #288,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.10.2 Tgetdate

Name: »get date« - Obtain date.
Opcode: 42
Syntax: uint32_t Tgetdate ( void );
Description: The GEMDOS routine Tgetdate obtains the current date.
Return value: The function returns a uint32_t number with the date, which is coded as follows:
Bits Meaning
   
0-4 Day (1-31)
5-8 Month (1-12)
9-15 Year (0-119, 0= 1980)
Availability: All GEMDOS versions.
Group: Date and Time
See also: Binding   Tsetdate

5.10.2.1 Bindings for Tgetdate

C: uint32_t Tgetdate ( void );
Assembler:
move.w    #42,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.10.3 Tgettime

Name: »Get time« - Obtain the time.
Opcode: 44
Syntax: uint32_t Tgettime ( void );
Description: The GEMDOS routine Tgettime obtains the system time.
Return value: The function returns the system time, coded as follows:
Bits Meaning
   
0-4 Seconds in units of two (0-29)
5-10 Minutes (0-59)
11-15 Hours (0-23)
Availability: All GEMDOS versions.
Group: Date and Time
See also: Binding   Tsettime

5.10.3.1 Bindings for Tgettime

C: uint32_t Tgettime ( void );
Assembler:
move.w    #44,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #2,sp        ; Correct stack

5.10.4 Tgettimeofday

Name: »Tgettimeofday« - Interrogate the state of the internal, high resolution system clock.
Opcode: 341 (0x0155)
Syntax: int32_t Tgettimeofday ( timeval *tv, timezone *tzp );
Description: The function Tgettimeofday interrogates the state of the internal, high resolution system clock.

The argument tv is a pointer to the timeval structure.

The argument tzp is a pointer to timezone structure.

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

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 long). 16-bit libraries will have to copy the contents of the structure that tzp points to.

The Ssystem() call has a command S_CLOCKMODE. 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.
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.
Return value: The function can never fail. It always returns E_OK.
Availability: Available when a MiNT kernel of a version at least 1.15.0 release is detected.
Group: Date and Time
See also: Binding   Ssystem   Tsettimeofday

5.10.4.1 Bindings for Tgettimeofday

C: int32_t Tgettimeofday ( timeval *tv, timezone *tzp );
Assembler:
pea       tzp          ; Offset 6
pea       tv           ; Offset 2
move.w    #341,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $0a(sp),sp   ; Correct stack

5.10.5 Tmalarm

Name: »Tmalarm« - Interrogates the state of the internal, high resolution system clock.
Opcode: 317 (0x013d)
Syntax: int32_t Tmalarm( int32_t time );
Description: This function reads/sets a process alarm for the current process.

time specifies the length of time (in milliseconds) to wait before a SIGALRM signal is delivered. If time is 0 then any previously set alarm is cancelled. If time is negative the function does not modify any alarm currently set.

If no SIGALRM signal handler has been set up when the alarm is triggered, the process will be killed.
Return value: Returns 0 if no alarm was scheduled prior to this call or the amount of time remaining (in milliseconds) before the alarm is triggered.
Availability: Available when a 'MiNT' cookie with a version of at least 1.10 exists.
Group: Date and Time
See also: Binding   Talarm   Pause   Psignal

5.10.5.1 Bindings for Tmalarm

C: int32_t Tmalarm( int32_t time );
Assembler:
move.l    time,-(sp)   ; Offset 2
move.w    #341,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
addq.l    #6,sp        ; Correct stack

5.10.6 Tsetdate

Name: »Set date« - Set the date.
Opcode: 43
Syntax: int16_t Tsetdate ( uint16_t date );
Description: The GEMDOS routine Tsetdate sets the current date. The parameter date is coded as follows:
Bits Meaning
   
0-4 Day (1-31)
5-8 Month (1-12)
9-15 Year (0-119, 0= 1980)


Note: From Blitter-TOS onwards the date is set in the hardware clock as well (if present).
Return value: A return value 0 if the setting was successful, or -1 if the date format was invalid.
Availability: All GEMDOS versions.
Group: Date and Time
See also: Binding   Tgetdate

5.10.6.1 Bindings for Tsetdate

C: uint32_t Tsetdate ( uint16_t date );
Assembler:
move.w    date,-(sp)   ; Offset 2
move.w    #43,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.10.7 Tsetitimer

Name: »Tsetitimer« - Control a periodic timer.
Opcode: 329 (0x0149)
Syntax: int32_t Tsetitimer ( int16_t which, int32_t *interval, int32_t *value, int32_t *ointerval, int32_t *ovalue );
Description: The GEMDOS routine Tsetitimer controls one of three possible periodic timers. The following apply:
Parameter Meaning
   
which Desired timer
0 = This timer works in real time, and sends the signal SIGALRM on expiry
1 = This timer works in 'virtual process time' and sends the signal SIGVTALRM on expiry. The timer in this case runs only when the process that is controlling the timer currently owns the CPU.
2 = This timer works both in 'virtual process time' as well as when the operating system itself is active. On expiry of the timer the signal SIGPROF is sent.
interval Address of an int32_t which holds the value to which the timer is to be set on expiry. A NULL-pointer means that the corresponding old value should not be changed. If the int32_t holds the value 0, the timer will be deactivated after its expiry.
value Address of an int32_t which holds the initial value of the timer in milliseconds. A NULL-pointer leaves the current timer unaffected. If the int32_t holds the value 0, the timer will be deactivated.
ointerval Address of an int32_t which holds the current intervall of the timer, or NULL if this value is of no interest.
ovalue Address of an int32_t which holds the current value of the timer, or NULL if this value is of no interest.


As all internal calculations are measured in miliseconds, it is not possible to set a timer to (very large, future) arbitrary values.

Setting new interval values needs root privileges.
Return value: The function returns 0 when executed correctly, or a a negative value in case of error.
Availability: This function is optional, so a call may be answered with EINVFN. Available when a 'MiNT' cookie with a version of at least 1.11 exists.
Group: Date and Time
See also: Binding   Pause   Psignal   Talarm

5.10.7.1 Bindings for Tsetitimer

C: int32_t Tsetitimer ( int16_t which, int32_t *interval, int32_t *value, int32_t *ointerval, int32_t *ovalue );
Assembler:
move.l    ovalue,-(sp)    ; Offset 16
move.l    ointerval,-(sp) ; Offset 12
move.l    value,-(sp)     ; Offset  8
move.l    interval,-(sp)  ; Offset  4
move.w    which,-(sp)     ; Offset  2
move.w    #329,-(sp)      ; Offset  0
trap      #1              ; GEMDOS
lea       $12(sp),sp      ; Correct stack

5.10.8 Tsettime

Name: »Set time« - Set the time.
Opcode: 45
Syntax: int16_t Tsettime ( uint16_t time );
Description: The GEMDOS routine Tsettime sets the time. The parameter time must be coded as follows:
Bits Meaning
   
0-4 Seconds in units of two (0-29)
5-10 Minutes (0-59)
11-15 Hours (0-23)


Note: From Blitter-TOS 1.02 onwards the time is set in the hardware clock as well (if present).
Return value: A return value 0 if the setting was successful, or -1 if the time format was invalid.
Availability: All GEMDOS versions.
Group: Date and Time
See also: Binding   Tgettime

5.10.8.1 Bindings for Tsettime

C: int16_t Tsettime ( uint16_t time );
Assembler:
move.w    time,-(sp)   ; Offset 2
move.w    #45,-(sp)    ; Offset 0
trap      #1           ; GEMDOS
addq.l    #4,sp        ; Correct stack

5.10.9 Tsettimeofday

Name: »Tsettimeofday« - Sets the state of the internal, high resolution system clock.
Opcode: 342 (0x0156)
Syntax: int32_t Tsettimeofday ( timeval *tv, timezone *tzp );
Description: The function Tsettimeofday sets the state of the internal, high resolution system clock.

The argument tv is a pointer to the timeval structure.

The argument tzp is a pointer to the timezone structure.

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

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 long). 16-bit libraries will have to copy the contents of the structure that tzp points to.

The tz_dsttime member of timezone is stored, but not evaluated within the kernel. Beware not to misunderstand its meaning: if non-zero it simply signifies that daylight savings time applies 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 command S_CLOCKMODE. This command allows retrieval or setting of the kernel clock mode, i.e. to specify whether the hardware clock is meant to run in UTC or in local time.(!nl) It is planned to make MiNT compliant with the kernel timekeeping 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.
Return value: The following error conditions are defined:

EPERM - an attempt was made by a user without super-user privileges to change the system time or system time zone information.

EBADARG - one of the arguments is out of range. Note that the kernel time cannot be set to dates before Jan 1 1980 00:00:00 and after some day in 2038 (yep, MAX_LONG seconds since the epoch). Timezone offsets must be in the range of +/- 720 minutes.
Availability: Available when a MiNT kernel of a version at least 1.15.0 release is detected.
Group: Date and Time
See also: Binding   Ssystem   Tgettimeofday

5.10.9.1 Bindings for Tsettimeofday

C: int32_t Tsettimeofday ( timeval *tv, timezone *tzp );
Assembler:
pea       tzp          ; Offset 6
pea       tv           ; Offset 2
move.w    #342,-(sp)   ; Offset 0
trap      #1           ; GEMDOS
lea       $0a(sp),sp   ; Correct stack

HomeGEMDOSFile functionsProcess functions