Date and time handling in Free Pascal (Part II).
In my tutorial Date and time handling in Free Pascal (Part I) I describe how to use the functions and procedures of the SysUtils unit to retrieve the current date and time, to decode and encode a given date, time or date/time value, how to convert a date, time or date/time value into a date, time or date/time string with a given format. I also describe there, how to use the procedures and functions of the DateUtils unit to do date/time arithmetic, to retrieve values like day of the week, month or year, as well as how to compare two dates, times or date/time values. This tutorial pre-supposes that the user is familiar with what I explain there, and what will not be repeated here. To note that all program samples have been written and tested on Windows; I suppose that at least a part of them will not work on Linux and macOS.
The Free Pascal SysUtils unit offers 3 different ways to code a date, time or date/time value:
- TDateTime: A double word that is used with most of the date and time related procedures and functions of the SysUtils and DateUtils units. TDateTime is described in detail in the first part of my date and time tutorial.
- TTimeStamp: A record, declared as:
- TSystemTime: A record, declared as:
type TSystemTime = record
Year, Month, Day: word;
Hour, Minute, Second, MilliSecond: word;
end;
Time: Integer; // number of milliseconds since midnight
Date: Integer; // number of days plus one since 01/01/0001
end;
The Free Pascal DOS unit includes the date/time type DateTime:
type DateTime = record
Year, Month, Day, Hour, Min, Sec: Word;
end;
And finally, the TWin32FindData structure, an item of the SysUtils TSearchRec record, contains information on file creation, modification and access date/times, declared as being of type TFileTime. This type actually is a 64-bit integer, containing the number of 100-nanosecond intervals since 01/01/1601 00:00:00, the date/time value corresponding to UTC (not local) time. We will see how to read out these date/time values at the end of the tutorial.
What date/time type to use depends on what you want to do. As I said above, most date/time manipulation may be done using TDateTime. However, if we want to manipulate file dates and times, things become more complicated.
Before learning how to retrieve a file's last modification, creation, or last access date/time, let's have a look at the date/time conversion routines of the SysUtils unit.
In the first part of the tutorial, we have seen the functions DateToStr, TimeToStr, and
DateTimeToStr, as well as FormatDateTime, that you should use rather than the 3 other ones. There is another
procedure, that does exactly the same; it is declared as:
procedure DateTimeToString(var ADateTimeString: string; const FormatStr: ADateTimeFormat; const ADateTime: TDateTime);
Example:
Writeln(FormatDateTime('dddd, dd. mmmm yyyy', Date));
DateTimeToString(S, 'dddd, dd. mmmm yyyy', Date); Writeln(S);
Output for both lines of code (on my system with locale = Luxembourg/Luxembourgish)
Sonndeg, 30, Mäerz 2025
The inverse conversion may be done using StrToDateTime and TryStrToDateTime (and similar), as explained in the first part of the tutorial.
To convert between the 3 SysUtils types described above, we can use:
procedure DateTimeToSystemTime(ADateTime: TDateTime; var ASystemTime: TSystemTime);
function DateTimeToTimeStamp(ADateTime: TDateTime): TTimeStamp;
function SystemTimeToDateTime(const ASystemTime: TSystemTime): TDateTime;
function TimeStampToDateTime(const ATimeStamp: TTimeStamp): TDateTime;
function TimeStampToMSecs(const ATimeStamp: TTimeStamp): Comp;
This last function returns the number of milliseconds since 1/1/0001. Use TTimeStamp variables if you need to keep very precise track of time.
The files related date/time functions of the SysUtils unit use a Longint value to store the date/time information. This value is actually called a DOS file timestamp. I am not sure if the internal format of this value is the same as for the DOS file timestamp values used with the routines of the DOS unit (cf. further down in the text); it might be that it's something totally different (?). Anyway, we must not bother about this, as the date/time value is normally retrieved using a conversion function that will return a TDateTime value.
The simplest way to retrieve the last modification date/time of a file is to use the SysUtils function
FileAge, declared as:
function FileAge(Const AFileName: string): Longint;
This function may be used on any file, without the necessity to open it. If there is an error, -1 is returned.
The Longint value, returned by FileAge can be converted to a TDateTime value, using the function
function FileDateToDateTime(AFiledate: Longint): TDateTime;
The inverse conversion is done using the function
function DateTimeToFileDate(ADateTime: TDateTime): Longint;
The following program reads and prints out the timestamp of a file and its backup file, as well as the information if the actual file is newer, older, or of the same date/time than the backup file.
program datetime4;
{$mode objfpc}{$H+}
uses
SysUtils;
const
Filename = 'dt1.lpr';
var
FD1, FD2: Longint;
File1, File2: string;
begin
File1 := GetCurrentDir + '\' + Filename;
File2 := GetCurrentDir + '\backup\' + Filename;
FD1 := FileAge(File1); FD2 := FileAge(File2);
Write('Actual file last modification date = ');
Writeln(FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(FD1)));
Write('Backup file last modification date = ');
Writeln(FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(FD2)));
if FD1 > FD2 then
Writeln('The actual file is newer than the bckup file')
else if FD1 < FD2 then
Writeln('The actual file is older than the bckup file')
else
Writeln('The actual file and the bckup file have the same timestamp');
Writeln;
Write('Hit ENTER to terminate '); Readln;
end.
Here is the program output on my computer (the actual file having been modified today, 31th March 2025, the backup file yesterday):
|
Another way to retrieve the last modification date/time of a file is to use the SysUtils function
FileGetDate, declared as:
function FileGetDate(AFileHandle: Longint): Longint;
It works exactly the same way than FileAge(), except that the file must be open. If there is an error, the function
returns -1.
There is a corresponding function to "manually" set the last modification date of a file:
function FileSetDate(AFileHandle, AFileAge: Longint): Longint;
The function returns 0 if successful; error codes have negative values.
The following program sample creates a new file, and displays its last modification date using FileGetDate. It then changes the last modification date and displays it using FileAge.
program datetime5;
{$mode objfpc}{$H+}
uses
SysUtils, DateUtils;
const
Filename = 'testfile';
var
FH, FD, Ret: Longint;
NewFile: string;
DT: TDateTime;
begin
NewFile := GetCurrentDir + '\' + Filename;
Writeln('Actual date/time = ', FormatDateTime('yyyy.mm.dd hh:nn:ss', Now));
FH := FileCreate(NewFile);
FD := FileGetDate(FH);
Write('File last modification date = ');
Writeln(FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(FD)));
FileClose (FH);
Writeln('Setting file last modification date to 1st January 2025');
DT := EncodeDateTime(2025, 1, 1, 0, 0, 0, 0);
FD := DateTimeToFileDate(DT);
FH := FileOpen(NewFile, fmOpenWrite);
Ret := FileSetDate(FH, FD);
if Ret <> 0 then
Writeln('Setting file date failed; return code = ', Ret);
FileClose (FH);
FD := FileAge(NewFile);
Write('File last modification date now = ');
Writeln(FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(FD)));
Writeln;
Write('Hit ENTER to terminate '); Readln;
end.
Here is the program output:
|
This seems to work all fine, however there is a problem: Whereas FileAge returns the date and time as set by FileSetDate, a different timestamp is reported in Windows File Manager, in fact this timestamp is 2024.12.41 23.00, i.e. 1 day and 1 hour less than the time that I had set. No idea why this is the case (?).
The DOS unit includes the following two procedures to read resp. write the last modification date/time of a file:
procedure GetFTime (var AFile; var ATime: Longint);
procedure SetFTime (var AFile; ATime: Longint);
where AFile is of type File, and has to be assigned and opened before using the procedures.
The DOS file timestamp is encoded in the bits of the Longint value as follows:
| Bits | Value |
|---|---|
| 0 - 4 | Seconds divided by 2 |
| 5 - 10 | Minutes |
| 11 - 15 | Hours |
| 16 - 20 | Day of month |
| 21 - 24 | Month |
| 25 - 31 | Number of elapsed years since 1980 |
This must however not bother us. In fact, the DOS unit includes procedures that convert the Longint value into a DOS
DateTime value and vice-versa.
procedure PackTime (ADateTime: DateTime; var ATime: Longint);
procedure UnPackTime (ATime: Longint; var ADateTime: DateTime);
The following program sample retrieves the last modification date/time of the file created in the previous example using GetFTime and displays it. Then it sets the modification date/time to the actual date and time using SetFTime. Finally, it retrieves the new modification date/time using FileAge.
program datetime6;
{$mode objfpc}{$H+}
uses
SysUtils, DOS;
const
Filename = 'testfile';
var
YY, MM, DD, WD, HH, NN, SS, S100: Word;
FD: Longint;
NewFile, DS: string;
DT: DateTime;
FH: File;
begin
NewFile := GetCurrentDir + '\' + Filename;
Assign(FH, NewFile); Reset(FH);
GetFTime(FH, FD); UnPackTime(FD, DT);
Write('File last modification date = ');
with DT do
Writeln(Year, '.', Month, '.', Day, ' ', Hour, ':', Min, ':', Sec);
Close(FH);
GetDate(YY, MM, DD ,WD); GetTime(HH, NN, SS, S100);
Write('Setting file last modification date/time to ');
Writeln(YY, '.', MM, '.', DD, ' ', HH, ':', NN, ':', SS);
with DT do begin
Year := YY;
Month := MM;
Day := DD;
Hour := HH;
Min := NN;
Sec := SS;
end;
Assign(FH, NewFile); Rewrite(FH);
PackTime(DT, FD); SetFTime(FH, FD);
Close(FH);
FD := FileAge(NewFile);
DateTimeToString(DS, 'yyyy.mm.dd hh:nn:ss', FileDateToDateTime(FD));
Writeln('File last modification date now = ', DS);
Writeln;
Write('Hit ENTER to terminate '); Readln;
end.
Here is the output, when I ran the program on 31th March 2025:
|
Surprisingly, these two procedures work all correctly. What I mean is that, as a difference with the corresponding SysUtils functions, the file last modification date/time set is correctly recognized in Windows File Manager (?).
Note: The program above uses two DOS procedures (to retrieve the actual date resp. time), that I haven't described yet:
procedure GetDate(var AYear, AMonth, ADay, AWeekDay: Word);
procedure GetTime(var AHour, AMinute, ASecond, ASec100: Word);
Both the SysUtils and the DOS units include file search related routines, and the information returned by these routines includes the file last modification date.
The SysUtils FindFirst and FindNext functions use the following types:
type
THandle = Longint;
TSearchRec = record
Time, Size, Attr: Longint;
Name: TFileName;
ExcludeAttr: Longint;
FindHandle: THandle;
{$ifdef Win32}
FindData: TWin32FindData;
{$endif}
end;
The record item Time contains the file last modified date/time as a Longint value, that we can convert to a
TDateTime value using FileDateToDateTime. Example:
if FindFirst('testfile', faAnyFile, FileInfo) = 0 then
Writeln('File date is ', FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(FileInfo.Time)));
FindClose(FileInfo);
with "FileInfo" being of type TSearchRec.
Note: It is mandatory to terminate a file search with a call to the FindClose() procedure. Failure to do so will result in memory loss.
The DOS FindFirst and FindNext functions use the following type:
type
SearchRec = packed record
Fill: array[1..21] of Byte;
Attr: Byte;
Time: LongInt;
Size: LongInt;
Reserved: Word;
Name: string[255];
SearchSpec: string[255];
NamePos: Word;
end;
The record item Time contains the file last modified date/time as a Longint value, that we can convert to a
DateTime value using UnpackTime. Example:
FindFirst('testfile', anyfile, FileInfo);
if DosError = 0 then begin
UnPackTime(FileInfo.Time, DT);
Write('File last modification date = ');
with DT do
Writeln(Year, '.', Month, '.', Day, ' ', Hour, ':', Min, ':', Sec);
end;
FindClose(FileInfo);
with "FileInfo" being of type SearchRec and DT of type DateTime.
Note: If your program includes the SysUtils unit and the DOS unit, identifiers like FindFirst, FindNext, and FindClose, are ambiguous, as the same routine name is used in both units. To make sure that the correct routine is used, prefix the routine name with the unit name; e.g. SysUtils.FindClose resp. Dos.FindClose.
The following program sample reads the files in the current directory and displays their names ordered by last modification date (subdirectories will be ignored). The file date is retrieved from the SysUtils TSearchRec structure, returned by FindFirst and FindNext.
program datetime7;
{$mode objfpc}{$H+}
uses
SysUtils;
type
TDirFile = record
FileName, FileDate: string;
end;
TDirFiles = array of TDirFile;
var
N, L, I, J: Integer;
FileInfo: TSearchRec;
DirFile: TDirFile;
DirFiles: TDirFiles;
// String format (add spaces to the right)
function SFormat(S0: string; L: Integer): string;
var
I: Integer;
S: string;
begin
S := S0;
for I := Length(S0) to L do
S += ' ';
Result := S;
end;
// Main program
begin
if FindFirst('*.*', faAnyFile and not faDirectory, FileInfo) = 0 then begin
N := 0; L := 0;
repeat
Inc(N); SetLength(DirFiles, N);
DirFiles[N - 1].FileName := FileInfo.Name;
if Length(DirFiles[N - 1].FileName) > L then
L := Length(DirFiles[N - 1].FileName);
DirFiles[N - 1].FileDate := FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(FileInfo.Time));
until FindNext(FileInfo) <> 0;
for I := 0 to Length(DirFiles) - 2 do begin
for J := I + 1 to Length(DirFiles) - 1 do begin
if DirFiles[I].FileDate < DirFiles[J].FileDate then begin
DirFile := DirFiles[I]; DirFiles[I] := DirFiles[J]; DirFiles[J] := DirFile;
end;
end;
end;
Writeln('Current directory listing:'); Writeln;
for I := 0 to Length(DirFiles) - 1 do
Writeln(SFormat(DirFiles[I].FileName, L), ' ', DirFiles[I].FileDate);
end;
FindClose(FileInfo);
Writeln;
Write('Hit ENTER to terminate '); Readln;
end.
Here is the output of the program on my computer.
|
On Windows systems, the SysUtils unit includes the structure FindData of type TWin32FindData, that contains supplementary information about the file, in particular the date/times of file creation, last modification and last access. As I said at the beginning of the tutorial, these time values are declared as being of type TFileTime, this type being a 64-bit integer, containing the number of 100-nanosecond intervals since 01/01/1601 00:00:00. Also, these date/time values do not correspond to local, but to UTC timestamps.
The conversion of TFileTime to TDateTime is rather complicated, requiring the 3 following steps:
- Converting the UTC date/time to local date/time, using FileTimeToLocalFileTime from the Windows unit,
- Converting the (local) TFileTime to a DOS file timestamp, using the procedure FileTimeToDosDateTime from the Windows unit.
- Converting the DOS file timestamp to a TDateTime, value using FileDateToDateTime from the SysUtils unit.
Here are the declarations of the 2 routines of the Windows unit:
function FileTimeToLocalFileTime(const AUtcFiletime: TFileTime; var ALocalFiletime: TFileTime): Boolean;
function FileTimeToDosDateTime(const AFileTime: TFileTime; var AFileDate, AFileTime: Word): Boolean;
AS the function FileTimeToDosDateTime returns date and time as two separate values, we'll have to use a LongRec variable and retrieving the date into its high, the time into its low bytes. To use the LongRec variable with the FileDateToDateTime function, we must convert it to a long integer using the Longint function.
All this is really not simple. But, no reason to worry if you don't understand it: Just use the code in the following program sample as template. The program is similar to the previous one, but displays creation, last modification and last access timestamps; also, the files are sorted by name rather than by date/time.
program datetime8;
{$mode objfpc}{$H+}
uses
SysUtils, Windows;
type
TDirFile = record
FileName, CreationDate, ModifDate, AccessDate: string;
end;
TDirFiles = array of TDirFile;
var
N, L, I, J: Integer;
FileInfo: TSearchRec;
DirFile: TDirFile;
DirFiles: TDirFiles;
FT: TFileTime;
LRFT: LongRec;
// String format (add spaces to the right)
function SFormat(S0: string; L: Integer): string;
var
I: Integer;
S: string;
begin
S := S0;
for I := Length(S0) to L do
S += ' ';
Result := S;
end;
// Main program
begin
if FindFirst('*.*', faAnyFile and not faDirectory, FileInfo) = 0 then begin
N := 0; L := 0;
repeat
Inc(N); SetLength(DirFiles, N);
DirFiles[N - 1].FileName := FileInfo.Name;
if Length(DirFiles[N - 1].FileName) > L then
L := Length(DirFiles[N - 1].FileName);
DirFiles[N - 1].CreationDate := ''; DirFiles[N - 1].ModifDate := ''; DirFiles[N - 1].AccessDate := '';
FileTimeToLocalFileTime(FileInfo.FindData.ftCreationTime, FT);
if FileTimeToDosDateTime(FT, LRFT.Hi, LRFT.Lo) then
DirFiles[N - 1].CreationDate := FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(Longint(LRFT)));
FileTimeToLocalFileTime(FileInfo.FindData.ftLastWriteTime, FT);
if FileTimeToDosDateTime(FT, LRFT.Hi, LRFT.Lo) then
DirFiles[N - 1].ModifDate := FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(Longint(LRFT)));
FileTimeToLocalFileTime(FileInfo.FindData.ftLastAccessTime, FT);
if FileTimeToDosDateTime(FT, LRFT.Hi, LRFT.Lo) then
DirFiles[N - 1].AccessDate := FormatDateTime('yyyy.mm.dd hh:nn:ss', FileDateToDateTime(Longint(LRFT)));
until FindNext(FileInfo) <> 0;
for I := 0 to Length(DirFiles) - 2 do begin
for J := I + 1 to Length(DirFiles) - 1 do begin
if DirFiles[I].FileName > DirFiles[J].FileName then begin
DirFile := DirFiles[I]; DirFiles[I] := DirFiles[J]; DirFiles[J] := DirFile;
end;
end;
end;
Writeln('Current directory listing:'); Writeln;
for I := 0 to Length(DirFiles) - 1 do begin
Write(SFormat(DirFiles[I].FileName, L), ' ');
Writeln(DirFiles[I].CreationDate, ' ', DirFiles[I].ModifDate, ' ', DirFiles[I].AccessDate);
end;
end;
SysUtils.FindClose(FileInfo);
Writeln;
Write('Hit ENTER to terminate '); Readln;
end.
Note: The usage of SysUtils.FindClose (instead of a simple FindClose) is necessary, because the Windows unit includes a find close procedure with the same name.
Here is the output of the program on my computer.
|
The Windows unit includes the two functions FindFirstFile and FindNextFile, that return a TWin32FindData structure, that may be used to retrieve the creation, last modification and last access time of a file in the same way as seen before. Here is the code of timestamp function, as published in Date and time handling in Object Pascal, by Michaël Van Canneyt (PDF available on the Internet). Note, that I did not test this function...
function FileTimeStamp(const AFileName: string): TDateTime;
var
H: THandle;
Info: TWin32FindData;
LFT: TFileTime;
DT: LongRec;
begin
Result := 0;
H := FindFirstFile(PChar(AFileName), Info);
if (H <> INVALID_HANDLE_VALUE) then
begin
Windows.FindClose(H);
FileTimeToLocalFileTime(Info.ftLastWriteTime, LFT);
if FileTimeToDosDateTime(LFT, DT.Hi, DT.Lo) then
Result := FileDateToDateTime(Longint(DT));
end;
end;
Programs on my site, that deal with file date/times:
dircmp is a Free Pascal command line program that compares the content of two directories. It uses the SysUtils TSearchrec.Time value to retrieve the file (last modification) date. Click the following link to visit the diromp documentation page.
DirList is a Free Pascal GUI application that lists the content of a Windows folder, with export possibility of the listing to text, CSV, or HTML. As dircmp, it uses the SysUtils TSearchrec.Time value to retrieve the file date. Click the following link to visit the DirList documentation page.
SearchMP3 is a Free Pascal GUI application that may be used to search for MP3 files on the local computer. Search criteria include MP3 tags, as well as file properties, among these latter ones, the file modification and creation dates. Click the following link to visit the SearchMP3 documentation page.
If you find this text helpful, please, support me and this website by signing my guestbook.