SysUtils – File Name Handling Routines

AnsiCompareFileName

function AnsiCompareFileName(const S1: string; const S2: string): SizeInt;

Compares two filenames S1 and S2 and returns a value less than, equal to, or greater than zero, using either case-sensitive or case-insensitive comparison depending on the platform's FileNameCaseSensitive setting.

AnsiLowerCaseFileName

function AnsiLowerCaseFileName(const s: string): string;

Converts a filename to its lowercase representation, taking locale-aware character handling into account.

AnsiUpperCaseFileName

function AnsiUpperCaseFileName(const s: string): string;

Converts a filename to its uppercase representation, taking locale-aware character handling into account.

AddDisk

function AddDisk(const path: string): Byte;

Unix-only function that registers an additional drive path (beyond the four preset entries) so that DiskFree and DiskSize can query it, and returns the assigned drive number.

ChangeFileExt

function ChangeFileExt(const FileName: UNICODESTRING; const Extension: UNICODESTRING): UNICODESTRING;
function ChangeFileExt(const FileName: RAWBYTESTRING; const Extension: RAWBYTESTRING): RAWBYTESTRING;

Replaces the extension of FileName (everything after and including the last dot) with Extension, which must itself include the leading dot; if FileName has no extension, Extension is simply appended.

CreateDir

function CreateDir(const NewDir: RawByteString): Boolean;
function CreateDir(const NewDir: UnicodeString): Boolean;

Creates a new directory named NewDir (relative to the current working directory if no absolute path is given) and returns True on success, False otherwise.

DeleteFile

function DeleteFile(const FileName: UnicodeString): Boolean;
function DeleteFile(const FileName: RawByteString): Boolean;

Deletes the file FileName from disk, returning True if the removal succeeded and False otherwise.

DiskFree

function DiskFree(drive: Byte): Int64;

Returns the number of free bytes on the specified disk drive (0 = current drive, 1/2 = floppy drives, 3 = first hard-disk partition, 4-26 = other drives/partitions); returns -1 on error.

DiskSize

function DiskSize(drive: Byte): Int64;

Returns the total capacity in bytes of the specified disk drive, using the same drive-numbering scheme as DiskFree; returns -1 on error.

ExpandFileName

function ExpandFileName(const FileName: UNICODESTRING): UNICODESTRING;
function ExpandFileName(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Expands a relative FileName to an absolute path relative to the current directory, normalizing directory separators to the platform's convention; an empty input expands to the current directory.

ExpandFileNameCase

function ExpandFileNameCase(const FileName: UNICODESTRING; out MatchFound: TFilenameCaseMatch): UNICODESTRING;
function ExpandFileNameCase(const FileName: RAWBYTESTRING; out MatchFound: TFilenameCaseMatch): RAWBYTESTRING;

Behaves like ExpandFileName but additionally resolves the case of the final path segment to match what actually exists on disk, reporting via MatchFound whether a unique match was located.

ExpandUNCFileName

function ExpandUNCFileName(const FileName: UNICODESTRING): UNICODESTRING;
function ExpandUNCFileName(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Expands FileName like ExpandFileName and then attempts to replace the drive letter with the corresponding network share name, returning an empty string if the share name cannot be determined.

ExtractFileDir

function ExtractFileDir(const FileName: UNICODESTRING): UNICODESTRING;
function ExtractFileDir(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Returns the drive and directory portion of FileName without a trailing directory separator, unlike ExtractFilePath.

ExtractFileDrive

function ExtractFileDrive(const FileName: UNICODESTRING): UNICODESTRING;
function ExtractFileDrive(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Returns only the drive letter portion of FileName; returns an empty string on platforms or paths without drive letters.

ExtractFileExt

function ExtractFileExt(const FileName: UNICODESTRING): UNICODESTRING;
function ExtractFileExt(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Returns the extension of FileName including the leading dot character.

ExtractFileName

function ExtractFileName(const FileName: UNICODESTRING): UNICODESTRING;
function ExtractFileName(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Returns the filename portion of FileName, i.e. all characters following the last directory separator or drive letter; concatenating ExtractFilePath and ExtractFileName reconstructs the full path.

ExtractFilePath

function ExtractFilePath(const FileName: UNICODESTRING): UNICODESTRING;
function ExtractFilePath(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Returns the path portion of FileName (including drive letter and the trailing directory separator), i.e. everything up to and including the last directory separator.

ExtractRelativePath

function ExtractRelativePath(const BaseName: UNICODESTRING; const DestName: UNICODESTRING): UNICODESTRING;
function ExtractRelativePath(const BaseName: RAWBYTESTRING; const DestName: RAWBYTESTRING): RAWBYTESTRING;

Constructs a relative path leading from BaseName to DestName; if DestName resides on a different drive (non-Unix platforms) the full DestName is returned unchanged, and both directory arguments must end with a path separator.

FileAge

function FileAge(const FileName: UnicodeString): LongInt;
function FileAge(const FileName: UnicodeString; out FileDateTime: TDateTime; FollowLink: Boolean = True): Boolean;
function FileAge(const FileName: RawByteString; out FileDateTime: TDateTime; FollowLink: Boolean = True): Boolean;
function FileAge(const FileName: RawByteString): LongInt;

Returns the last-modification timestamp of FileName; the LongInt overloads return -1 on error or when FileName is a directory, while the TDateTime overloads return a success flag and can optionally follow symbolic links.

FileDateToDateTime

function FileDateToDateTime(Filedate: LongInt): TDateTime;

Converts a DOS-style file date/time value, such as one returned by FileAge or FindFirst/FindNext, into a TDateTime value.

FileExists

function FileExists(const FileName: UnicodeString; FollowLink: Boolean = True): Boolean;
function FileExists(const FileName: RawByteString; FollowLink: Boolean = True): Boolean;

Returns True if a file (not a wildcard pattern) named FileName exists on disk; on Windows this returns False for directories, and FollowLink controls whether symbolic links are resolved.

FileGetAttr

function FileGetAttr(const FileName: UnicodeString): LongInt;
function FileGetAttr(const FileName: RawByteString): LongInt;

Returns the attribute flags of FileName as an OR-ed combination of constants such as faReadOnly, faHidden, faSysFile, faVolumeId, faDirectory and faArchive; returns -1 on error.

FileGetDate

function FileGetDate(Handle: THandle): LongInt;

Returns the modification timestamp of a file that is already open, identified by its file Handle, analogous to FileAge but operating on a handle instead of a filename; returns -1 on error.

FileSearch

function FileSearch(const Name: UnicodeString; const DirList: UnicodeString; Options: TFileSearchOptions = [sfoImplicitCurrentDir]): UnicodeString;
function FileSearch(const Name: UnicodeString; const DirList: UnicodeString; ImplicitCurrentDir: Boolean): UnicodeString;
function FileSearch(const Name: RawByteString; const DirList: RawByteString; Options: TFileSearchOptions = [sfoImplicitCurrentDir]): RawByteString;
function FileSearch(const Name: RawByteString; const DirList: RawByteString; ImplicitCurrentDir: Boolean): RawByteString;

Searches for file Name across the semicolon- or colon-separated directory list DirList and returns the full path of the first match; Options controls whether the current directory is searched implicitly and whether quotes are stripped from path components, returning an empty string if nothing is found.

FileSetAttr

function FileSetAttr(const Filename: UnicodeString; Attr: LongInt): LongInt;
function FileSetAttr(const Filename: RawByteString; Attr: LongInt): LongInt;

Sets the attribute flags of Filename to the OR-ed combination Attr, returning 0 on success and -1 on failure; this function is not implemented on Unix-like systems.

FileSetDate

function FileSetDate(const FileName: UnicodeString; Age: LongInt): LongInt;
function FileSetDate(const FileName: RawByteString; Age: LongInt): LongInt;
function FileSetDate(Handle: THandle; Age: LongInt): LongInt;

Sets the modification timestamp of a file, identified either by FileName or by an open Handle, to the DOS date/time value Age; returns 0 on success (the Handle variant always fails on Unix since it has no OS support for that operation).

FindFirst

function FindFirst(const Path: UnicodeString; Attr: LongInt; out Rslt: TUnicodeSearchRec): LongInt;
function FindFirst(const Path: RawByteString; Attr: LongInt; out Rslt: TRawbyteSearchRec): LongInt;

Begins a wildcard file search matching Path with additional attribute filter Attr, filling Rslt with data about the first match and returning 0 on success; every successful call must eventually be paired with a FindClose call on the same Rslt record to avoid memory leaks.

FindNext

function FindNext(var Rslt: TUnicodeSearchRec): LongInt;
function FindNext(var Rslt: TRawbyteSearchRec): LongInt;

Continues a search started by FindFirst, filling Rslt with the next matching entry and returning 0 while matches remain, or a nonzero value once the search is exhausted.

GetCurrentDir

function GetCurrentDir: AnsiString;

Returns the current working directory of the running application.

RemoveDir

function RemoveDir(const Dir: RawByteString): Boolean;
function RemoveDir(const Dir: UnicodeString): Boolean;

Removes directory Dir from disk (resolved relative to the current working directory if not absolute), returning True on success and False if, for example, the directory is not empty.

RenameFile

function RenameFile(const OldName: UnicodeString; const NewName: UnicodeString): Boolean;
function RenameFile(const OldName: RawByteString; const NewName: RawByteString): Boolean;

Renames (or moves) a file from OldName to NewName, returning True on success; whether the operation can cross disks or partitions depends on the underlying OS (it works on Windows, but typically fails across partitions on Unix-like systems).

SameFileName

function SameFileName(const S1: string; const S2: string): Boolean;

Returns True if S1 and S2 refer to the same filename, i.e. if AnsiCompareFileName(S1, S2) returns 0.

SetCurrentDir

function SetCurrentDir(const NewDir: RawByteString): Boolean;
function SetCurrentDir(const NewDir: UnicodeString): Boolean;

Sets the application's current working directory to NewDir, returning True on success and False otherwise.

SetDirSeparators

function SetDirSeparators(const FileName: UNICODESTRING): UNICODESTRING;
function SetDirSeparators(const FileName: RAWBYTESTRING): RAWBYTESTRING;

Returns FileName with every recognized directory separator character replaced by the platform's own OSDirSeparator.

FindClose

procedure FindClose(var F: TUnicodeSearchRec);
procedure FindClose(var F: TRawbyteSearchRec);

Terminates a FindFirst/FindNext search sequence and frees the memory associated with the search record F; omitting this call after a successful FindFirst causes memory leaks.

DoDirSeparators

procedure DoDirSeparators(var FileName: UNICODESTRING);
procedure DoDirSeparators(var FileName: RAWBYTESTRING);

Replaces, in place, every directory separator character in FileName that is listed in AllowDirectorySeparators with the current system's directory separator.