AmigaDOS Date and Time

AmigaOS carries two incompatible date/time representations: the timer.device counts seconds+microseconds since 1 January 1970, while dos.library uses the DateStamp structure (inherited from Tripos). This article, drawn from the 2024 ROM Kernel Reference Manual (Ch. 3), documents the DOS side and the conversion functions.

The DateStamp structure

struct DateStamp {
    LONG ds_Days;     /* days since 1 January 1978 (includes leap days) */
    LONG ds_Minute;   /* minutes past midnight */
    LONG ds_Tick;     /* ticks past the minute */
};
  • ds_Days counts days since 1 January 1978 (the DOS epoch), including leap days.
  • ds_Minute counts minutes since the start of the day.
  • ds_Tick counts ticks since the start of the minute. Divide by TICKS_PER_SECOND (defined in dos/dos.h) to get seconds.

A system "tick" is always 1/50th of a second, regardless of NTSC or PAL. AmigaDOS detects the clock basis at setup and scales so the tick definition is independent of video refresh.

Range limit. The DOS↔timer conversion functions currently cannot handle dates after 31th December 2045. Leap seconds cannot be represented; the clock then requires manual adjustment.

There is no dos.library function to set the date — that must go through timer.device with TR_SETSYSTIME. At boot, Kickstart reads the real-time clock if present; otherwise all RootNode time fields stay 0 (= 1 Jan 1978) and the boot filesystem supplies an approximation (the FFS uses the boot volume's root-block creation time).

Elementary functions

struct DateStamp *DateStamp(struct DateStamp *ds);          /* fills ds, returns ds; cannot fail */
LONG   CompareDates(struct DateStamp *date1, struct DateStamp *date2);  /* V36 */
void   Delay(ULONG ticks);                                  /* suspend caller; 1 tick = 1/50 s */
  • DateStamp() does not require ds to be longword-aligned (unlike most DOS structures).
  • CompareDates() returns negative if date1 is later, positive if date2 is later, 0 if identical — note this is the opposite sign convention from strcmp(). It assumes the day difference does not exceed 2³¹ days and does not validate the dates.
  • Delay() is CPU-friendly (the process is suspended, not busy-waiting); it is the preferred way to sleep. Avoid passing 0 — V34 and below misbehave.

String conversion — the DateTime structure

DateToStr() and StrToDate() work through struct DateTime (dos/datetime.h):

struct DateTime {
    struct DateStamp dat_Stamp;   /* input/output date */
    UBYTE   dat_Format;           /* FORMAT_DOS / INT / USA / CDN / DEF */
    UBYTE   dat_Flags;            /* DTF_SUBST, DTF_FUTURE */
    UBYTE  *dat_StrDay;           /* filled with weekday, e.g. "Saturday" */
    UBYTE  *dat_StrDate;          /* date string (in/out) */
    UBYTE  *dat_StrTime;          /* time string (in/out), 24h HH:MM:SS */
};

Date formats

Format Example Notes
FORMAT_DOS 30-Sep-23 DOS default (day-mon-yy)
FORMAT_INT 23-09-30 International/ISO (yy-mm-dd)
FORMAT_USA 09-30-23 USA (mm-dd-yy)
FORMAT_CDN 30-09-23 Canadian/European (dd-mm-yy)
FORMAT_DEF locale-dependent Uses locale if loaded; prefers 4-digit years

FORMAT_DEF is not defined in the official NDK includes but is handled correctly. Define it manually:

#ifndef FORMAT_DEF
# define FORMAT_DEF 4
#endif

Output buffers should be at least LEN_DATSTRING bytes. StrToDate() in ROM accepts only two-digit years (78–99 → 1978–1999, 00–45 → 2000–2045); the locale.library patch adds four-digit year support.

Flags

  • DTF_SUBST — when converting to a string, replace nearby dates with relative words: "Today", "Tomorrow", "Yesterday", a weekday name (past week), or "Future". Used by the List command.
  • DTF_FUTURE — when parsing a string, interpret weekday names as "next" rather than "last".

Both conversion functions are patched by locale.library once it loads, replacing English output with localized strings.

utility.library conversions

Amiga2Date() and Date2Amiga() (in utility.library, not dos.library) bridge the seconds-since-1978 count and a struct ClockData:

struct ClockData {
    UWORD sec, min, hour;   /* time of day */
    UWORD mday, month;      /* calendar date */
    UWORD year;             /* full year (not an offset) */
    UWORD wday;             /* day of week */
};

If locale.library is available, prefer its FormatDate() and ParseDate() over the DOS string functions — they are more powerful.

See Also

Sources: Thomas Richter, "ROM Kernel Reference Manual: AmigaDOS" (First Edition, 2024), Chapter 3 — Date and Time. Raw: raw/rkm/rkm-dos-book.md Updated: 2026-08-08