5.10 Date and Time

• Tadjtime	Correct the time to synchronize the system clock.
• 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.

5.10.1 Tadjtime

Name:	»Adjust time« - correct the time to synchronize the system clock.
Opcode:	343 (0x157)
Syntax:	int Tadjtime ( const struct timeval delta, struct timeval olddelta );
Description:	The Tadjtime() function gradually adjusts the system clock (as returned by Tgettimeofday). The amount of time by which the clock is to be adjusted is specified in the structure pointed to by delta. If the adjustment in delta is positive, then the system clock is speeded up by some small percentage (i.e., by adding a small amount of time to the clock value in each second) until the adjustment has been completed. If the adjustment in delta is negative, then the clock is slowed down in a similar fashion. If a clock adjustment from an earlier Tadjtime() call is already in progress at the time of a later Tadjtime() call, and delta is not NULL for the later call, then the earlier adjustment is stopped, but any already completed part of that adjustment is not undone. If olddelta is not NULL, then the buffer that it points to is used to return the amount of time remaining from any previous adjustment that has not yet been completed.
Return value:	A return value 0 if the setting was successful, otherwise a negative error code is returned.
Notes:	The adjustment that Tadjtime() makes to the clock is carried out in such a manner that the clock is always monotonically increasing. Using Tadjtime() to adjust the time prevents the problems that can be caused for certain applications (e.g., make(1)) by abrupt positive or negative jumps in the system time.
Availability:	This function is available as of FreeMiNT 1.16.
Group:	Date and Time
See also:	Binding Tsetdate Tsettime

5.10.1.1 Bindings for Tadjtime

C:	int Tadjtime ( const struct timeval delta, struct timeval olddelta );
Assembler:	move.l olddelta,-(sp) ; Offset 6 move.l delta,-(sp) ; Offset 2 move.w #343,-(sp) ; Offset 0 trap #1 ; GEMDOS lea 10(sp),sp ; Correct stack

5.10.2 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.2.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.3 Tgetdate

Name:

»get date« - Obtain date.

Opcode:

Syntax:

uint16_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.3.1 Bindings for Tgetdate

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

5.10.4 Tgettime

Name:

»Get time« - Obtain the time.

Opcode:

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.4.1 Bindings for Tgettime

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

5.10.5 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.5.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.6 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.6.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.7 Tsetdate

Name:

»Set date« - Set the date.

Opcode:

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 Tadjtime

5.10.7.1 Bindings for Tsetdate

C:	int32_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

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.

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.8.1 Bindings for Tsetitimer

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       20(sp),sp       ; Correct stack

5.10.9 Tsettime

Name:

»Set time« - Set the time.

Opcode:

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.9.1 Bindings for Tsettime

C:	int32_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.10 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. 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.10.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

GEMDOS

File functions

Process functions