Contains types, procedures, and functions used for file and directory operations.

lazfileutils.pas contains types, procedures, and functions used for file and directory operations. lazfileutils.pas is part of the LazUtils package.

All functions are thread-safe unless explicitly stated.
Gets the relative sort order for the specified file names.

CompareFilenames is an overloaded Integer function used to compare the specified file names to get their relative order for sorting operations. CompareFilenames provides implementations which accept String or PChar values (and their lengths) as arguments. The implementations are platform- and/or OS-specific; they consider whether the file system is case sensitive or when UTF-8 encoding is supported.

The return value indicates the relative order in a sort operation, and can contain the following values:

<0
  Filename1 comes before Filename2
0
  Filename1 and Filename2 to have the same value
>0
  Filename1 comes after Filename2

Relative sort order for the specified file names.
First file name for the comparison.
Second file name for the comparison.
Gets the relative sort order for case-insensitive file names.

CompareFilenamesIgnoreCase is an overloaded Integer function used to compare the specified file names to get their relative order in case-insensitive sorting operations. CompareFilenamesIgnoreCase provides alternate implementations which accept String or PChar values (and their lengths) as arguments. The implementations are platform- and/or OS-specific; they consider whether the file system is case sensitive, and when UTF-8 encoding is supported.

The return value indicates the relative order in a case-insensitive sort operation, and can contain the following values:

<0
  Filename1 comes before Filename2
0
  Filename1 and Filename2 to have the same value
>0
  Filename1 comes after Filename2

Relative sort order for the file names.
First file name for the comparison.
Second file name for the comparison.
Performs a sort order comparison for the specified file name and extension.

CompareFileExt is an Integer function used to compare the file extension in Filename to the value in Ext. Ext may contain the '.' character, but it is not required and will be removed for the comparison. CaseSensitive indicates whether case is ignored in the comparison. When CaseSensitive contains True, CompareStr is called to perform the comparison. Otherwise, UTF8CompareText is called to compare the values. The return value will contain one of the following:

-1
  Filename value has a lower sort order value than Ext
0
  Filename and Ext have the same sort order values
1
  Filename value has a higher sort order value than Ext

The return is 1 if Filename does not contain a file extension.

Relative sort order for the compared values.
File name for the comparison.
File extension for the comparison.
True if case sensitive comparison is needed.
Compares file names using the number characters in common.

CompareFilenameStarts is an Integer function used to compare the specified file names to determine their relative sort order. Arguments in Filename1 and Filename2 do not need to be the same length. When they have different lengths, the number of characters common to both are used in the comparison. CompareFilenameStarts calls CompareFileNames to perform the comparison, and get the return value for the function.

See CompareFilenames for more information about the numeric return value and its meaning.

Relative sort order for the compared values.
First file name for the comparison.
Second file name for the comparison.
Length of the first file name.
Length of the seconds file name.
Compares file names to determine their relative sort order.

CompareFilenamesP is an Integer function used to compare the specified file names to determine their relative sort order.

Filename1 and Filename2 are the PChar arguments containing the file names examined in the routine.

IgnoreCase indicates if upper- or lower-case differences are ignored in the file name comparison; the default value for the parameter is False (indicating that case differences are not ignored). For platforms where CaseInsensitiveFilenames is defined, the value in IgnoreCase defaults to True. When IgnoreCase is True, the UTF8CompareText function is called to perform a case-insensitive comparison of the specified file names. Otherwise, the ordinal byte values in the specified file names are compared until a difference is found, or the entire file name in Filename1 has been examined.

If either Filename1 or Filename2 are unassigned (contain Nil) or begin with a Null character (Decimal 0), the return value is set 0 (zero) and no additional actions are performed in the function. See CompareFilenames for more information about the numeric return value for the function and its meaning.

Relative sort order for the compared values.
File name used in the comparison.
File name used in the comparison.
Indicates if case differences in file name comparisons are ignored.
Determines if Filename has the specified file extension.

FilenameExtIs is a Boolean function used to determines if the file in the Filename parameter has the specified file extension in Ext.

Ext can contain the '.' (Period) character used in the extension, but it is not required.

CaseSensitive indicates if case-sensitivity is used when comparing parameter values. When set to True, the comparison is limited to values in the ASCII character set. StrLComp or StrLIComp is called to compare the values in Filename to the values in Ext.

The return value is True when Filename uses the file extension in Ext. The return value is False for the following conditions:

- Filename is an empty string ('').
- Filename does not have a '.' character that marks the start of the file extension.
- The extension in Filename has a different length than Ext.
- Filename has a different file extension than Ext.

Returns True if Filename has the specified file extension.
File name examined in the routine.
File extension expected in the file name.
True to use case-sensitive comparison in the routine.
Determines if the file name uses one of the specified file extensions.

FilenameExtIn is a Boolean function used to determine if the file name in the Filename parameter uses one of the file extension in Exts.

Exts is an array type with the file extensions expected in the routine. Values in Exts can contain the '.' (Period) character used in the extension, but it is not required.

CaseSensitive indicates if case-sensitivity is used when comparing the parameter values. When set to True, the comparison is limited to characters in the ASCII character set. StrLComp or StrLIComp is called to compare the value in Filename to the values in Exts.

The return value is True when Filename uses one the file extension in Exts. The return value is Falsewhen Filename is an empty string (''), does not include a '.' character that marks the start of the file extension, or does not use one of the values in Exts.

Returns True if Filename has one of the specified file extensions.
File name examined in the routine.
File extensions expected in the file name.
True to use case-sensitive comparison in the routine.
Indicates if the specified directory name exists on the local file system.

DirPathExists is a Boolean function which indicates if the specified directory name exists on the file system. DirectoryName can contain a trailing path delimiter, but it is removed in the function. DirPathExists calls DirectoryExistsUTF8 to get the return value.

True when the specified directory exists in the file system.
Directory Name to locate.
Indicates if the specified directory name is writable.

DirectoryIsWritable is a Boolean function used to determine if the specified directory name is writable in the file system. The path name in DirectoryName must already exist on the local file system. The return value is False if a directory with the specified name does not exist.

The return value is True when a file can be added, deleted, or modified in the specified path. To get the return value, DirectoryIsWritable creates a temporary file in DirectoryName, adds content to it, and deletes the temporary file. DirectoryIsWritable calls the FileCreateUTF8, FileWrite, FileClose, and DeleteFileUTF8 routines to perform the file operations. The return value is True when FileWrite completes successfully.

DirectoryIsWritable calls InvalidateFileStateCache with the temporary file name if DeleteFileUTF8 cannot remove the file.
FileWrite FileClose
True if the specified directory is writable.
Directory name to examine in the function.
Gets the base file name (without the file extension) in the specified path.

ExtractFileNameOnly is a String function used to extract the base file name (without the file extension) from the value in AFilename. Path information, up to the last directory separator ('/' or '\') or device separator (':') character, in AFileName is ignored. The file extension, starting at the '.' character, is also omitted.

Base file name in the file path.
File path and name to examine in the function.
Gets the value from AFilename prior to the '.' character that starts the file extension.

Processes characters in AFilename in reverse order to locate the '.' that starts the file extension. If a '.' character is not found, the process continues until a path or directory delimiter is found. The return value defaults to AFilename if a path or directory delimiter occurs before a '.' character.

File name (including path) after the file extension has been removed.
Qualified path and file name examined in the method.
Determines if the specified value is an absolute file path (not a relative one).

FilenameIsAbsolute is a Boolean function used to determine if the value in TheFilename contains an absolute file path (and not a relative one). The implementation for FilenameIsAbsolute is platform- and/or OS-specific.

In UNIX-like environments, the FilenameIsUnixAbsolute function is used in the implementation. The return value is False if TheFilename is an empty string (''), or does not start with the directory separator for the environment.

On Windows, the FilenameIsWinAbsolute function is called in the implementation. FilenameIsWinAbsolute takes Device identifiers into consideration when examining the value in TheFilename. For example:

D:\db\employee.fdb

The return value is False if TheFilename (without the optional device identifier) is an empty string (''), or does not start with the directory separator for the environment.

True when the file name is not a relative path.
Path and file name to use in the function.
Determines if the specified value is an absolute file path (not a relative one).

FilenameIsWinAbsolute is a Boolean function used to determine if the value in TheFilename contains an absolute file path (and not a relative one).

On Windows, the FilenameIsWinAbsolute function is called in the implementation of FilenameIsAbsolute. FilenameIsWinAbsolute takes Device identifiers into consideration when examine the value in TheFilename. For example:

D:\db\employee.fdb

The return value is False if TheFilename (without the optional device identifier)is an empty string (''), or does not start with the directory separator for the environment.

True when the file name is not a relative path.
Path and file name to use in the function.
Determines if the specified value is an absolute file path (not a relative one).

FilenameIsUnixAbsolute is a Boolean function used to determine if the value in TheFilename contains an absolute file path (and not a relative one).

In UNIX-like environments, the FilenameIsUnixAbsolute function is used in the implementation of FilenameIsAbsolute. The return value is False if TheFilename is an empty string (''), or does not start with the directory separator for the environment.

True when the file name is not a relative path.
Path and file name to use in the function.
Creates the specified directory if it does not already exist.

ForceDirectory is a Boolean function which creates the specified directory if it does not already exist. ForceDirectory ensures that a trailing path delimiter exists in DirectoryName prior to checking the file system. Duplicate adjacent path delimiters (like '//foo//bar/foobar/' or '\\foo\\bar\foobar\') are removed prior to checking the directory path.

Each directory in the specified path is validated by calling DirPathExists. ForceDirectory calls CreateDirUTF8 if a directory does not exist, and may exit with a return value of False if directory creation is not successful.

The return value is True if all directories in the path information already exist, or are successfully created in the function.

Returns True if directory exists or if it was successfully created.
Path information for the operation.
Examines the specified file to see if it is executable.

CheckIfFileIsExecutable is a procedure used to examine the specified file name to see if it is executable. CheckIfFileIsExecutable is implemented for UNIX-like environments, and allows a process to better determine if the file can be executed on the platform or OS, and to get better error messages when it cannot.

CheckIfFileIsExecutable raises an exception with a specific message when the platform or OS facilities indicate it is necessary.

Use FileIsExecutable to determine of a file is executable without raising an exception.

The Exception contains the following messages (from string resources):

lrsFileDoesNotExist
  Raised when FileExistsUTF8 returns False
lrsFileIsADirectoryAndNotAnExecutable
  Raised when DirPathExists indicates the file is actually a directory name
lrsReadAccessDeniedFor
  Raised when fpGetErrno() returns ESysEAcces
lrsADirectoryComponentInDoesNotExistOrIsADanglingSyml
  Raised when fpGetErrno() returns ESysENoEnt
lrsADirectoryComponentInIsNotADirectory
  Raised when fpGetErrno() returns ESysENotDir
lrsInsufficientMemory
  Raised when fpGetErrno() returns ESysENoMem
lrsHasACircularSymbolicLink
  Raised when fpGetErrno() returns ESysELoop
lrsIsNotExecutable
  Raised when fpGetErrno() has a value other than the above

File name to examine.
Checks whether the specified file name is a symbolc link on the local file system.

CheckIfFileIsSymlink is a routine used to ensure that the file name specified in AFilename is a valid symbolic link on the local file system. It acts as an assert for the pre-condition.

The implementation for the routine is platform- or OS-specific. In general, all of the platforms raise an exception if the file name does not exist on the local file system of when the file name is not a symbolic link. The mechanism used to check for a symbolic link is platform-dependent.

For the Windows platform, the file name must be a link create using mklink on the local file system.

For UNIX-like platforms, the FpReadLink routine is called to examine the file name. The value from fpGetErrNo is used to get specific error information that can be used in the exception. For example:

ESysEAcces
  Read access is denied for the symbolic link.
ESysENoEnt
  A directory does not exist or is a dangling symbolic link.
ESysENotDir
  A value in the file name is not a directory.
ESysENoMem
  Insufficient memory to a access the symbolic link.
ESysELoopy
  A circular reference was detected in the symbolic link.

Calling CheckIfFileIsSymlink on the Amiga platform will always result in an exception. Symbolic links are not supported on the Amiga platform.

Raises an exception if the specified file does not exist on the local file system, or the file is a regular file and not a symbolic link.
File name examined in the routine.
Determines if the specified file name is executable.

FileIsExecutable is a Boolean function used to determine if the specified file name is executable. For UNIX-like environments, a combination of FpStat, FPS_ISREG, and FpAccess are used to get the return value. For the Windows environment, the value from FileExistsUTF8 is used as the return value. In short, the function is not really useful in a Windows environment.

True if the file is executable on the platform or OS.
File name to examine.
Indicates if the specified file is a symbolic link in the file system.

FileIsSymlink is a Boolean function used to determine if the specified file name is a symbolic link on the local file system.

The implementation of FileIsSymlink is platform-specific. For UNIX-like environments, the FpReadLink function is used to determine if the symbolic link can be resolved to a physical file name in the local file system. For the Windows platform, FileGetAttrUTF8 is called to get and examine the file attributes for the specified file name. The file attributes must include the value FILE_ATTRIBUTE_REPARSE_POINT, and one of the Windows API values such as IO_REPARSE_TAG_SYMLINK or IO_REPARSE_TAG_MOUNT_POINT for the corresponding file handle. For the Amiga platform, FileIsSymLink always returns False.

FpReadLink
True when the specified file name is a symbolic link.
File name examined in the routine`
Indicates if the specified file has a descriptor or handle on the local file system.

FileIsHardLink is a Boolean function used to determine if the specified file name is represented by a file descriptor or handle on the local file system.

The implementation of FileIsHardLink is platform- or OS-specific. For UNIX-like environments, a file handle is retrieved by calling the FileOpenUTF8 function and passed to the FPFStat function to access the file information. For the Windows platform (excluding WinCE and Windows XP), the GetFileInformationByHandle Windows API routine is called to get information for the file handle. For the Amiga platform, FileIsHardLink always returns False.

The return value is False if a file handle could not be accessed for the specified file name or it is actually a symbolic link on the local file system.

FpFstat
True when file information can be accessed by its descriptor or handle.
File name examined in the routine.
Indicates if the specified file name is readable.

FileIsReadable is a Boolean function which indicates if the specified file name is readable. For UNIX-like environments, FpAccess is used to get the return value. On Windows, the return value is the result from FileExistsUTF8. In short, the function is not really useful on the Windows platform where a suitable file attribute does not exist for the purpose.

FpAccess
True when the specified file name is readable.
File name to examine.
Indicates if the specified file name is writable.

FileIsWritable is a Boolean function which indicates if the specified file name is writable. For UNIX-like environments, FpAccess is used to get the return value. For Windows, FileGetAttrUTF8 is used to determine if faReadOnly is omitted from the attributes for the file.

True when the specified file name is writable.
File name to examine.
Determines if the specified file contains plain text content.

FileIsText is a Boolean function used to determine if the specified file contains plain text content. The overloaded variant that includes the FileReadable argument is used to examine the content in the file.

FileIsText calls FileOpenUtf8 for the specified file name. The return value is False is the file handle contains feInvalidHandle.

FileIsText checks for (and skips) common Byte Order Marks, such as:

- UTF-8 BOM (Hex $EF $BB $BF)
- UCS-2LE BOM (Hex $FF $FE)
- UCS-2BE BOM (Hex $FE $FF)

Content in the file (up to 1024 characters) is checked to ensure that invalid Null and Control characters are not found in the file. The return value is True when the specified file name exists in the local file system, and does not contain Null or Control characters.

True when the file contains plain text content.
File name to examine in the function.
Indicates if the specified file was successfully opened and read.
True if the specified file name contains characters to remove or resolve before use.

FilenameIsTrimmed is an overloaded Boolean function used to determine if the specified file name contains characters to remove or resolve before use. The variant which uses PChar values performs the comparison. The return value is False when the file name is a candidate for use of TrimFilename to remove whitespace or special characters.

Use TrimFilename to remove leading or trailing whitespace, duplicate directory separators, or relative path symbols.

False when the file name needs to trimmed.
File name to examine in the function.
PChar with the file name value.
Length of the file name.
Removes leading and trailing spaces, and resolves special characters.
TrimFilename
is a String function used to remove leading and trailing spaces (Decimal 32) in the specified path and file name. In addition, ResolveDots is called to expand directory characters (like '.' and '..') and to remove duplicate path delimiters (like '//').
New value for the path and file name.
Path and file name for the operation.
Removes duplicate path delimiters and resolves relative path symbols.

This function shortens duplicate path delimiters to single path delimiters. It resolves 'A/../B' to 'B', which might be wrong under Unix if A is a symlink. The function does not check the local file system. The single dot './A' is resolved to 'A', but a single '.' is retained.

File name with duplicate delimiters and relative paths resolved.
File name examined in the routine.
Removes whitespace and resolves special characters in the specified file name.

CleanAndExpandFilename is a String function used to remove whitespace and to resolve special characters in the specified file name. CleanAndExpandFilename calls TrimFilename and ExpandFileNameUTF8 to get the return value for the function. The return value is the current directory when Filename contains an empty string ('').

File name with whitespace removed and special characters resolved.
File name to examine in the function.
Removes whitespace and resolves special characters in the specified path.

CleanAndExpandDirectory is a String function used to remove whitespace and resolve special characters in the specified path. CleanAndExpandDirectory calls CleanAndExpandFilename to get the return value for the function. CleanAndExpandDirectory calls AppendPathDelim to ensure that a trailing path delimiter is included in the return value. The return value is the current directory when the specified path contains an empty string ('').

Path information after removing whitespace and resolving special characters.
Path information for the function.
Cleans and resolves a file path to the specified base directory name.

TrimAndExpandFilename is a String function used to remove whitespace and special characters in Filename, and to resolve the relative file path to the directory in BaseDir. TrimAndExpandFilename removes a trailing path delimiter in Filename, and calls ExpandFileNameUTF8 and TrimFilename to get the return value for the function.

The return value is an empty string ('') if Filename contains an empty string ('').

Cleaned and resolved file path.
File name for the function.
Base directory name used for a relative file path.
Cleans and resolves a relative path to a base directory.

TrimAndExpandDirectory is a String function used to remove whitespace and special characters in the path information, and to resolve a relative path to the specified base directory.

TrimAndExpandDirectory calls ExpandFileNameUTF8 to resolve the relative path, and calls TrimFilename to get the return value for the function. The return value is an empty string ('') when TrimFilename returns an empty string ('').

Path information cleaned and resolved to the specified base directory.
Path information for the function.
Base directory used to resolve a relative path.
Returns an absolute path relative to the specified base directory (when needed).

CreateAbsolutePath is a String function used to get the absolute path to the file specified in the Filename argument. A relative path reference in Filename is resolved to the path in the BaseDir argument. The return value contains the fully-qualified absolute path to the specified file name.

When Filename is an empty string ('') or already uses an absolute path reference, the value in Filename is used as the return value.

For the Windows platform, a file name which starts with '\' (root directory on the current drive) is resolved to the drive letter and root directory in BaseDIr. For all other platforms, the values in BaseDir and PathDelim are prepended to the relative path information in FileName.

CreateAbsolutePath calls TrimFileName to remove leading or trailing whitespace or duplicate path delimiters in the return value.

CreateAbsolutePath does not validate path or file name information; the file or directory does not have to exist on the local file system.

Example:

// uses LazFileUtils; // var vFile, vBaseDir: String;

vFile := '.\foo\bar\baz.txt'; vBaseDir := 'c:\temp';

ShowMessage('File: ' + vFile + LineEnding + 'Base Directory: ' + vBaseDir + LineEnding + 'Absolute Path: ' + CreateAbsolutePath(vFile, vBaseDir));

vFile := '\foo\\bar\\baz.txt'; vBaseDir := 'c:\temp';

ShowMessage('File: ' + vFile + LineEnding + 'Base Directory: ' + vBaseDir + LineEnding + 'Absolute Path: ' + CreateAbsolutePath(vFile, vBaseDir));
ExtractFileDrive
Fully-qualified absolute path to the specified file relative to a given base directory.
File name with relative path references resolved in the routine.
Base directory used to resolve a relative path reference in the file name.
Attempts to create a path in Dest relative the path in Source.

Returns True if it is possible to create a relative path from Source to Dest Function must be thread safe, so no expanding of filenames is done, since this is not thread-safe (at least on Windows platform).

- Dest and Source must either be both absolute filenames, or relative
- Dest and Source cannot contain '..' since no expanding is done by design
- Dest and Source must be on same drive or UNC path (Windows)
- If both Dest and Source are relative they must at least share their base directory
- Double PathDelims are ignored (unless they are part of the UNC convention)
- If UsePointDirectory is True and Result is True then if RelPath is Empty string, RelPath becomes '.'
- If AlwaysRequireSharedBaseFolder is False then Absolute filenames need not share a basefolder
- if the function succeeds RelPath contains the relative path from Source to Dest, no PathDelimiter is appended to the end of RelPath

Examples:

- Dest = /foo/bar Source = /foo Result = True RelPath = bar - Dest = /foo///bar Source = /foo// Result = True RelPath = bar - Dest = /foo Source = /foo/bar Result = True RelPath = ../ - Dest = /foo/bar Source = /bar Result = True RelPath = ../foo/bar - Dest = foo/bar Source = foo/foo Result = True RelPath = ../bar - Dest = foo/bar Source = bar/foo Result = False (no shared base directory) - Dest = /foo Source = bar Result = False (mixed absolute and relative) - Dest = c:foo Source = c:bar Result = False (no expanding) - Dest = c:\foo Source = d:\bar Result is False (different drives) - Dest = \foo Source = foo (Windows) Result is False (too ambiguous to guess what this should mean) - Dest = /foo Source = /bar AlwaysRequireSharedBaseFolder = True Result = False - Dest = /foo Source = /bar AlwaysRequireSharedBaseFolder = False Result = True RelPath = ../foo
Creates a relative path from BaseDirectory to Filename.

CreateRelativePath is a String function used to get the relative path from BaseDirectory to Filename. A trailing path delimiter in BaseDirectory is ignored. If there is no relative path, the value in Filename is returned.

When BaseDirectory and Filename contain the same value, and UsePointDirectory is False, an empty string ('') is used as the return value. If UsePointDirectory contains True, the return value is the '.' character. Duplicate path delimiters are removed.

CreateRelativePath is thread safe, and therefore, does not guarantee that the current directory is correct for file names like 'D:test.txt'.
Relative path from the base directory for the file name.
File name for the operation.
Base directory for the relative path.
True if '.' (current directory symbol) is prepended to the relative path.
Returns True if Filename exists in the specified Path.

FileIsInPath is a Boolean function which indicates if the file name exists in the specified path. Filename is the file name to locate, and may include optional relative path information. For example: '../filename.txt'.

Path is the directory name used to locate the specified file. For example: '/usr/lib/fpc'.

The returns value is True when Filename is a file or directory somewhere below Path. For example, under UNIX the file name '/usr/lib/fpc' is below Path '/usr/lib', '/usr' and '/'. When Filename and Path contain the same value, the return value is False. Please note: the return value is False when Path contains an empty string ('').

FileIsInPath calls ResolveDots to resolve relative path information in both Filename and Path, and ensures that a trailing path delimiter is included in Path when needed. FileIsInPath calls CompareFileNames.

This is a logical test; FileIsInPath does not expand or follow symbolic links.
True when the file exists in the specified path.
File name to locate.
Path used for the operation.
Checks whether the specified directory exists in a given path.

PathIsInPath is a Boolean function used to determine if the specified Directory exists in the Path argument. The return value is False when Path contains an empty string (''), or when the Directory does not exist in Path.

PathIsInPath calls the CompareFilenames routine to determine the return value for the function.

PathIsInPath ensures that a trailing path delimiter is included in the Path and Directory arguments prior to performing its comparison. On Windows, this results in a Path like 'C:' being treated as if it contains 'C:\'.
True when Directory exists in Path.
Path examined in the routine.
Directory name to locate in the specified path.
Gets a shortened version of the specified file name up to a maximum length.

ShortDisplayFilename is a String function used to get a shortened version of the specified file name up to the specified maximum length. The characters '...' are appended to a shortened file name.

These are three (3) Period characters and not an Ellipsis character.

The return value is the same as the aFileName argument if the file name did not need to be shortened.

Shortened version of the specified file name.
File name examined in the routine.
Maximum number of characters for the shortened file name.
Represents the platform- or OS-specific path delimiters available in the Lazarus LCL.
TPathDelimSwitch
is an enumerated type with values that indicate how path delimiters in file names are handled in routines like SwitchPathDelims, CheckPathDelim, and IsCurrentPathDelim. Values in the enumeration represent the various platform- or OS-specific path delimiters available in the Lazarus LCL at run-time.
No path delimiter changes were used.
Path delimiter is switched to the default path delimiter for the system.
Path delimiter is switched to the UNIX path delimiter (forward slash).
Path delimiter is switched to the Windows path delimiter (backslash).
Constant array with characters used as path delimiters for supported platforms and OS's.
PathDelimSwitchToDelim
is an array constant with character values for path delimiters associated with TPathDelimSwitch enumeration values. The DirectorySeparator value is used for both pdsNone and pdsSystem enumeration values. For UNIX-like environments (pdsUnix), the Forward slash character ('/' ) is used for the path delimiter. For Windows platforms (pdsWindows) the backslash character ('\') is used for the path delimiter.
DirectorySeparator
Ensures that path delimiters in the specified file name are correct for the current platform or OS.

ForcePathDelims is a procedure used to ensure that path delimiters in the specified file name are correct for the current platform or OS. ForcePathDelims examines each character in FileName to ensure that path delimiters use the correct notation for the platform or OS defined in the LCL.

For Windows, this means any UNIX path delimiters (/) in FileName are converted into the Windows path delimiter (\). Conversely, for all other platforms and environments, the Windows path delimiter (\) is converted to the UNIX notation (/). All path delimiter substitutions in FileName occur inline.

File name examined in the routine.
Performs path delimiter substitutions for the specified file name.

GetForcedPathDelims is a String function used to perform path delimiter substitutions on the specified file name for the current platform or OS. GetForcedPathDelims calls ForcePathDelims using a copy of FileName as an argument. This ensures that the original file name remains unchanged when path delimiter substitutions are needed.

File name after any path delimiter substitutions.
File name examined in the function.
Adds a trailing path delimiter when needed.

AppendPathDelim is a String function used to ensure that a trailing path delimiter is included in the specified Path. The return value includes the value in Path and the trailing path delimiter (when needed).

Path value with a trailing path delimiter.
Path value to examine.
Removes a trailing path delimiter from the specified value.

ChompPathDelim is a String function used to remove a trailing path delimiter from the specified value in Path. For environments where UNC paths are allowed, ChompPathDelim ensures that the UNC path delimiters are retained. Windows Device identifiers, such as "D:" are also retained in Path.

Path information after removing the trailing path delimiter.
Path information for the function.
Replaces path delimiters in a file path with the specified delimiter.

SwitchPathDelims is an overloaded String function used to ensure that path delimiter characters in Filename use the required character.

One variant of the function uses the Switch argument to pass a TPathDelimSwitch enumeration value that identifies the path delimiter needed, and includes the following:

pdsNone
  No path delimiter substitutions are performed. The original value in Filename is used as the return value for the function.
pdsSystem
  Path delimiters use the character required for the current platform or environment running the application.
pdsUnix
  Path delimiters use the UNIX forward slash (/) character.
pdsWindows
  Path delimiters use the Windows backslash (\) character.

The function examines each character in Filename are replaces any path delimiters encountered with the value specified in Switch.

The other variant passes a Boolean value indicating if all occurrences of a path delimiter should use the character required for the platform or environment hosting the application. It calls the SwitchPathDelims function to perform the substitutions.

The return value contains the value from Filename after any path delimiter substitutions have been applied.

File path and name after any path delimiter substitutions.
File path and name examined in the function.
Indicates the desired path delimiter to use in the return value.
Determines if the specified path delimiter character is not used on the system.

CheckPathDelim is a TPathDelimSwitch function used to determine if a specified path delimiter character is not the one used for the platform or environment running the application. The return value contains an TPathDelimSwitch enumeration value that indicates the path delimiter character notation that does not meet the requirements for the host.

CheckPathDelim compares the value in OldPathDelim to the current PathDelim character for the system. When they are different, the return value is set to reflect the delimiter character in use in OldPathDelim. If they are the same, the return value is set to pdsNone indicating that path delimiter substitutions are not needed.

Changed is a Boolean output parameter that indicates if the value in OldPathDelim does not match the current path delimiter in use on the system running the application. Changed contains False when the current path delimiter matches the value in OldPathDelim.

Enumeration value indicating the path delimiter substitution required.
Value to compare to the current path delimiter for the system.
True if path delimiters were changed to match the platform.
Determines if the current path delimiter matches the specified path delimiter notation.

IsCurrentPathDelim is a Boolean function used to determine if the path delimiter notation specified in Switch matches the current path delimiter for the system.

Switch is a TPathDelimSwitch enumeration value that indicates the notation to compare to the current path delimiter on the system running the application. Switch can include the following values:

pdsNone
  No comparison is performed since it is not required. Return value is set True.
pdsSystem
  No comparison is performed since it will always match the current path delimiter for the system. Return value is set True.
pdsUnix
  Return value is set to True when PathDelim contains the UNIX forward slash (/) character.
pdsWindows
  Return value is set to True when PathDelim contains the Windows backslash (\) character.

Boolean result of the path delimiter comparison.
Enumeration value specifying the character compared to the current path delimiter.
CreateAbsoluteSearchPath
- concatenates BaseDirectory and SearchPath to form an absolute path to search for files.

CreateAbsoluteSearchPath - concatenates BaseDirectory and SearchPath to form an absolute path to search for files.

The routine adds the appropriate path delimiters to the BaseDirectory string, and adds the search path. Each directory in the search path is examined to ensure that each is also an absolute directory path. The return value contains the fully-formed absolute search path.

If BaseDirectory is empty, the function exits with a return value equal to SearchPath. if SearchPath is empty, the function exits with empty string ('') in the return value.

The absolute path formed by concatenating BaseDirectory and SearchPath.
The search path (a relative path).
The base directory from which to form the absolute path.
Resolves relative path value(s) in the specified search path.

CreateRelativeSearchPath is a String function used to resolve one or more paths in SearchPath relative to the directory specified in BaseDirectory. A relative search path is one that assumes the path starts at a given working directory, and could result in an error if that directory is not the current directory on the local file system. CreateRelativeSearchPath ensures that a relative search path is resolved relative to a given directory to provide access to resources in the directory path.

SearchPath can contain multiple path values by using the semicolon character (;) to separate the paths.

BaseDirectory specifies the directory used as the anchor (or root) for each resolved search path.

Paths specified in SearchPath are resolved individually, and recombined with other path values in SearchPath. If either SearchPath or BaseDirectory contain an empty string (''), no actions are performed in the function. The return value contains a copy of the contents in SearchPath with relative paths resolved.

Search path after resolving relative paths to the specified base directory.
Search path(s) examined in the function.
Directory used as the anchor for resolved relative paths.
Trims the specified path, and removes empty or duplicate paths.

MinimizeSearchPath is a String function used to trim the path(s) specified in SearchPath, and to remove empty or duplicate paths in the argument. SearchPath can contain multiple path specifications separated by the semicolon (';') character.

MinimizeSearchPath iterates over the path specifications in SearchPath and calls TrimFilename as needed. ChompPathDelim is calls as well to remove trailing path delimiters as needed. Duplicate occurrence of a search path are reduced to a single occurrence.

The return value contains the value in SearchPath after normalization and removal of duplicate and empty search path specifications.

Search path after normalization and removal of duplicates.
Search path(s) examined in the function.
Locates the specified path in a delimiters list of search paths.

FindPathInSearchPath is an overloaded function used to locate the path specified in APath in a list of search paths.

APath contains the search path to locate in the delimited list of search paths. A trailing path delimiter specified in APath is ignored.

SearchPath contains the delimited list of search paths examined in the function. No actions are performed in the routine when SearchPath has not been assigned (contains Nil) or contains an empty string ('').

The return value is either an Integer or a PChar value depending on the overloaded variant used in an application. An Integer value represents the position in SearchPath where the value in APath is located. A PChar value contains a pointer to the first character in SearchPath where APath is located. The variant which accepts PChar arguments and returns a PChar value has additional length arguments for the path and search path.

Compiler defines determine the mechanism used to perform a comparison of the values in APath and SearchPath; i.e. CaseInsensitiveFilenames and NotLiteralFilenames. CompareFilenames is called to perform the comparison when inline comparison of string values in not supported.

Position or value for the located search path.
Path to locate in the delimited list of search paths.
Length in characters for the path to locate in the routine.
Delimited list of search paths examined in the routine.
Length in characters for the search paths list.
Indicates if the specified UTF-8-encoded file name exists.

FileExistsUTF8 is a Boolean function which indicates if the specified file name exists on the local file system. FileExistsUTF8 calls the FileExists function in SysUtils to get the return value for the routine.

FileExists
True when the specified file name exists.
UTF-8-encoded file name to locate on the local file system.
Returns the last modification time for the file in FileDate format.

FileAgeUTF8 is a Longint function which returns the last modification time for the file specified in FileName. FileAgeUTF8 should not be used on directories; it returns -1 if FileName represents a directory instead of a file.

For UNIX-like environments, the return value is provided by the FileAge function in the SysUtils unit. For Windows, FindFirstFileW is used to get the TWin32FindDataW data for the specified file. Its ftLastWriteTime value is converted using WinToDosTime to get the return value for the function.

The return value is in FileDate format, and can be transformed to a TDateTime value with the FileDateToDateTime function.

Last modification time for the file in FileDate format.
File name examined in the function.
Determine if the specified path exists on the local file system.

DirectoryExistsUTF8 is Boolean function used to determine if the specified path exists on the local file system. For the Windows environment, FileGetAttrUTF8 is called to see if FILE_ATTRIBUTE_DIRECTORY is included in the file attributes for the specified Directory. For UNIX-like environments, the DirectoryExists function in the SysUtils unit is used to get the return value.

True when the directory exists in the file system.
Directory name to locate in the file system.
Expands the values in FileName and BaseDir to an absolute file name.

ExpandFileNameUTF8 is a String function which expands the UTF-8-encoded values in FileName and BaseDir to an absolute file name. It changes all directory separator characters to the one appropriate for the system.

If an empty string ('') is passed in Filename, it is expanded to the current directory using GetCurrentDirUTF8. When FileName contains the tilde character (~), it is converted to the path to the home directory for the user using the HOME environment variable. Relative paths in FileName are resolved by calling ResolveDots.

The file name with an absolute path.
File name examined in the function.
Base directory used to resolve a relative path.
Starts searching for files matching the specified path value.

FindFirstUTF8 searches the for file which match the value specified in Path. Normal files, as well as all special files which have the attributes specified in Attr will be returned.

It returns a SearchRec record for further searching in Rslt. Path can contain wildcard characters; ? (matches any single character) and * (matches 0 or more arbitrary characters). In this case FindFirstUTF8 will return the first file which matches the specified criteria.

The return value contains the result from GetLastError; a non-zero value indicates that no files matching the criteria were found.

FindFirst
Last error number encountered in the function.
Path and/or file name to locate.
File attributes to include in the search.
Search record for the first matching file.
Locates another file matching the search criteria.

FindNextUTF8 is a Longint function used to locate another file matching the TSearchRec value in Rslt. Rslt is populated in a prior call to FindFirstUTF8, and updated in FindNextUTF8.

For the Windows environment, FindNextFileW is called to compare the TWIN32FINDDATAW for the matching file. For UNIX-like environments, the FindNext function in SysUtils is used.

The return value contains the result from GetLastError; a non-zero value indicates that an error was encountered.

Last error number.
Search criteria for the function.
Frees resources allocated to the specified search record.

FindCloseUTF8 is a procedure used to free resources allocated to the search record in F by the FindFirstUTF8 routine. FindCloseUTF8 calls the FindClose function in the SysUtils unit.

Search record to free in the procedure.
Sets the last modification time for the file.

FileSetDateUTF8 is a Longint function used to set the last modification time for the file to the specified Age in FileDate format. Use DateTimeToFileDate to convert a TDateTime value to FileDate format.

For the Windows environment, a handle is created for the specified file name, and SetFileTime is called to store the updated file age. For UNIX-like environments, FileSetDate in SysUtils is called to set the file age. InvalidateFileStateCache is also called for the specified file name.

The return value is the value from GetLastError; a non-zero value indicates that an error has occurred.

Last error number in the function.
File name to update in the function.
New value for the last modification time.
Gets the value of file attributes for the specified file name.

FileGetAttrUTF8 is a Longint function used to get files attributes for the specified file name. For the Windows environment, GetFileAttributesW in Windows is called to the file attribute value for Filename. For UNIX-like environments, FileGetAttr in SysUtils is called to the the return value.

The return value contains a numeric value that can be OR-ed with the following constants to get a specific file attribute:

faReadOnly
  The file is read-only
faHidden
  The file is hidden (On UNIX, the file name starts with a dot)
faSysFile
  The file is a system file (On UNIX, the file is a character, block or FIFO file).
faVolumeId
  Volume Label (For DOS/Windows on a plain FAT - not VFAT or Fat32)
faDirectory
  File is a directory
faArchive
  File is ready to be archived (Not possible on UNIX)

File attribute value for the specified file name.
File name for the function.
Sets the file attribute value for the specified file name.

FileSetAttrUTF8 is a Longint function used to set the file attributes for the specified file name to the value in Attr. The value in Attr can be set by AND-ing predefined file attribute constants, such as:

faReadOnly
  The file is read-only
faHidden
  The file is hidden (On UNIX, the file name starts with a dot)
faSysFile
  The file is a system file (On UNIX, the file is a character, block or FIFO file).
faVolumeId
  Volume Label (For DOS/Windows on a plain FAT - not VFAT or Fat32)
faDirectory
  File is a directory
faArchive
  File is ready to be archived (Not possible on UNIX)

For UNIX-like environments, FileSetAttr in SysUtils is called to set the file attributes value. InvalidateFileStateCache is also called for the specified file name. For the Windows environment, SetFileAttributesW in Windows is called to set the attributes value for the specified file name.

The return value contains the result from GetLastError; a non-zero value indicates that an error has occurred.

Last error number from the function.
File name to update in the function.
File attribute value for the specified file name.
Deletes the specified file name.

DeleteFileUTF8 is a Boolean function used to delete the specified file name.

For the Windows environment, DeleteFileW in Windows is called to remove the specified file name. For UNIX-like environments, DeleteFile in the SysUtils unit is called to delete the specified file name. InvalidateFileStateCache is also called.

The return value contains True when Filename is successfully deleted from the local file system.

True if the specified file name is deleted.
File name to delete in the function.
Renames a file to the specified value.

RenameFileUTF8 is a Boolean function used to rename a file to the value specified in NewName.

For the Windows environment, MoveFileW is called to rename the file using the values specified in OldName and NewName. For UNIX-like environments, RenameFile in SysUtils is called to rename the file to the specified new value. InvalidateFileStateCache is also called.

The return value is True if the file is renamed successfully.

True if the file is successfully renamed to the new value.
Existing name for the file.
New name for the file.
Searches for a file with the specified name in the list of directory paths.

FileSearchUTF8 is a String function used to search for files with the specified name in the list of directory paths.

DirList is a list of file paths to search in the function. Values in DirList are separated by the PathSeparator character for the environment. No additional directories are searched when DirList contains an empty string ('').

ImplicitCurrentDir controls whether the search is implicitly limited to the current directory. The default value for ImplicitCurrentDir is True. When a file with the specified Name is located in the current directory, no additional searches are needed. The return value is the name of the file without any path information.

When ImplicitCurrentDir is False, each path in DirList is searched for a file with the specified name. The search is stopped when the first file with the specified file name is found. The return value contains the path in DirList where the file name was located along with the file name, or an empty string ('') if the specified file is not found in the search.

Path and file name for the matching file, or an empty string.
File name to locate in the list of directory paths.
The delimited list of directory paths to search.
Determines if the specified file is marked as read-only.

FileIsReadOnlyUTF8 is a Boolean function used to determine if the specified file is marked as read-only in the local file system. FileIsReadOnlyUTF8 calls FileGetAttrUTF8 for the specified file name and checks to see if faReadOnly has been included in the file attributes value. The return value is True when faReadOnly has been included in the file attributes.

True when the file is marked as read-only.
File name to examine in the function.
Gets the name for the current directory.

GetCurrentDirUTF8 is a String function used to get the name for the current directory in the local file system.

For the Windows environment, GetCurrentDirectoryW is called to get the current directory name. UTF8Encode is called to convert the WideString value to UTF-8, and used as the return value for the function.

For UNIX-like environments, GetCurrentDir in SysUtils is called to get the current directory name.

GetCurrentDir
Name for the current directory.
Sets the current directory to the specified name.

SetCurrentDirUTF8 is a Boolean function used to set the current directory in the local file system to the specified value.

For the Windows environment, UTFDecode is called to convert NewDir and passed to SetCurrentDirectoryW to set the current directory name. Windows CE raises an exception in SetCurrentDirUtf8; the concept of a current directory does not exist in Windows CE.

For UNIX-like environments, SetCurrentDir in SysUtils is used to set the current directory to the specified value.

The return value is True if the current directory is successfully changed to the new value.

TException
  Raised for the Windows CE environment; exception message is: '[SetCurrentDirWide] The concept of the current directory doesn't exist in Windows CE'

True if the current directory was successfully changed to the new value.
Directory name to use as the current directory.
Creates a new directory with the specified name.

CreateDirUTF8 is a Boolean function used to create a new directory in the local file system with the specified name. For the Windows environments, the value in NewDir is converted to wide string format and passed to the CreateDirectoryW function in the Windows unit. For UNIX-like environments, CreateDir in SysUtils is used to create the new directory with the specified name.

The return value is True if the new directory is successfully created.

An error can occur if a directory with the specified name already exists in the local file system.

True if the new directory is successfully created.
Name for the new directory.
Removes the directory with the specified name.

RemoveDirUTF8 is a Boolean function used to remove the directory with the specified name from the local file system.

For the Windows environment, UTF8Decode is called to convert the value in Dir to wide string format. The RemoveDirectoryW function in the Windows unit is called to remove the specified directory.

For UNIX-like environments, RemoveDir in SysUtils is called to remove the specified directory.

The return value is True when the specified directory is successfully removed.

RemoveDir
True when the directory is successfully removed.
Name of the directory to remove in the function.
Creates the specified directories if they do not already exist.

ForceDirectories is a Boolean function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.

ForceDirectories raises an EInOutError exception with the message in SCannotCreateEmptyDir when Dir contains an empty string ('').

Each directory in the specified path is checked using DirectoryExistsUTF8. ForceDirectories calls CreateDirUTF8 if a directory does not already exist, and may exit with a return value of False if directory creation is not successful. The return value is True if all directories in the path information already exist, or are successfully created in the function.

EIOnOutError
  Raised when the directory name is an empty string (''); Message is SCannotCreateEmptyDir, and ErrorCode is set to 3.

True when directories exist or are successfully created in the function.
Path information to examine the function.
Opens the specified file name and returns its file handle.

FileOpenUTF8 is a THandle function used to open the UTF-8-encoded file name in FileName, and return its file handle. FileOpenUTF8 converts the file name to system format by calling UTF8ToSys, and calls the FileOpen routine in the SysUtils unit to get the file handle for the opened file.

FileOpen
File handle for the specified file.
File name opened in the function.
File access mode requested for the opened file.
Creates the specified file and returns its file handle.

FileCreateUTF8 is a THandle function used to created the file specified in the UTF-8-encoded FileName argument, and returns the file handle for the newly created file. Overloaded variants of the function are provided which allow additional arguments that specify the file sharing mode, or access rights for the newly created file.

FileCreateUTF8 calls UTF8ToSys to convert the file name to its system representation, and calls the FileCreate routine in the SysUtils unit to create the file and get its file handle.

FileCreate
File handle for the file created in the function.
File name created in the function.
File access rights for the new file.
File sharing mode for the new file.
Gets the size for the specified file name.
FileSizeUTF8
is an Int64 function used to get the size for the file specified in the UTF-8-encoded Filename argument. FileSizeUTF8 calls Utf8ToSys to convert the value in Filename to the system string type type, and calls the FindFirst routine in the SysUtils unit to get the size for the specified file name.
FindFirst
Size of the file on the local file system.
File name examined in the function.
Gets descriptive information for the specified file name.

GetFileDescription is a String function used to get descriptive information for the file name specified in AFilename. The return value contains file information appropriate to the platform, environment, or file system. The implementation of GetFileDescription and the content of the return value are platform- or OS-specific.

For UNIX-like environments, the return value can contain information that indicates the permissions for the user, group, and owner of the file as returned from the FPStat routine. It also includes the file user and group IDs, file size, and modification timestamp. For example:

ld-rwxrwxrwx Owner: UID.GID Size: 99999 Modified: MM/DD/YYYY hh:nn

l
  File is a symbolic link
d
  File is a directory in the file system
b,c, or -
  Device type for the entry. b is for block-level devices. c is for character devices. All others device types contain the - character.
r or -
  User read access permission
w or -
  User write access permission
x or -
  User executable permission
r or -
  Group read access permission
w or -
  Group write access permission
x or -
  Group executable permission
r or -
  Other read access permission
w or -
  Other write access permission
x or -
  Other executable permission
UID
  User identifier number assigned as the owner of the file
GID
  Group identifier number assigned to the group which owns the file
99999
  Size of the file. May indicate the total number of blocks or characters depending on the device type for the file.
MM/DD/YYYY hh:nn or ?
  Creation/modification timestamp for the file. ? is included if an exception is raised when accessing the date/time value.

For the Amiga platform, the content in the return value is derived using a TFileInfoBlock for a shared lock on the file. The return value can be an empty string if the file could not be locked using a shared lock on the file system. It can contain values like the following:

asperwd

a
  File is an archived (unchanged) file
s
  File is a script or executable file
p
  File is command or program that can be made resident
e
  File is used by the Shell
r
  File is readable
w
  File is writable
d
  File cannot be deleted

For Windows platforms, the return value contains only the modification date/time for the file using the format:

Modified: MM/DD/YYYY hh:mm

The return value can be 'Modified: ?' if an exception is encountered when getting the date/time value for the file.

String with the file information for the platform or OS.
File name examined in the function.
Resolves a symbolic link to an actual file name.

ReadAllLinks is a String function used to resolve a symbolic link to an actual file name. It does not resolve symbolic links in parent (or ancestor) directories. If a symlink cannot be resolved, and ExceptionOnError is False, the function returns an empty string (''). If ExceptionOnError is True, it raises an EFOpenError with a message, containing more details. For the Windows platform, it simply returns the value in the Filename argument.

Resolves a symlink to the real file.

If a symlink can not be resolved it returns Filename. It calls the ReadAllLinks function.

Resolve a Shell Link to the file path for the shortcut.

GetShellLinkTarget is a String function used to resolve the Shell Link file in the FileName parameter to a path on the local system. The return value contains the qualified path to the Shell object in the Link file.

Shell links are a feature available in Windows desktop and server operating systems. It relies on the Shell Object namespace, and provides access to files, folders, disk drives and printers on the system. The Shell Link allows access to an object from anywhere in the Shell namespace, and does not need to know the current name and / or location for the object.

GetShellLinkTarget is implemented for UNIX-like platforms and Amiga, but simply returns the value in the FileName parameter.

The Windows CE platform does not have the IShellLinkW interface; the value in FileName is always used as the return value.

FileName must contain a file name that uses the .lnk file extension, as created using the Create Shortcut option in Windows Explorer. No actions are performed in the routine when FileName does not use the .lnk file extension; the return value contains the original value passed in the FileName parameter.

GetShellLinkTarget uses the IShellLinkW interface to resolve the Shell Link to the path for the Shell object.

Path to the Shell object for the link.
Shell Link shortcut file to resolve in the routine.
Displays information for file attributes in the debugger.

Attr contains the file attributes examined in the routine, with the following values displayed for the corresponding file attributes:

-1
  Invalid
faDirectory
  D
faArchive
  A
faSysFile
  S
faReadOnly
  R
faHidden
  H
faVolumeId
  V
faSymLink
  L

File attributes not found in Attrib are represented as '-' characters.

String with information about the file attributes.
File attributes examined in the routine.
Enumerated type representing actions performed for an unresolved file name.

TPhysicalFilenameOnError is an enumerated type with values that indicate the action taken when an error is encountered when retrieving the physical file name for a symbolic link on the local file system. TPhysicalFilenameOnError includes the following enumeration values and meanings:

pfeException
  Causes an exception to be raised for the missing file name.
pfeEmpty
  Causes the missing file name to be ignored.
pfeOriginal
  Causes the original (missing) file name to be retained.

TPhysicalFilenameOnError is the type used to represent the OnError argument passed to the GetPhysicalFilename function.

Causes an exception to be raised for the missing file name.
Causes the missing file name to be ignored.
Causes the original (missing) file name to be retained.
Gets the physical file name for a symbolic link on the local file system.

GetPhysicalFilename is a String function used to get the physical file name on the local file system for the specified symbolic link.

Filename contains the symbolic link to resolve in the function.

OnError is a TPhysicalFilenameOnError enumeration value that indicates the action performed if a physical file name cannot be determined for the symbolic link. When OnError contains pfeException, an exception is raised for the unresolved file name. When OnError contains pfeOriginal, the unresolved symlink is used as the return value.

The implementation of GetPhysicalFilename is platform- or OS-dependent. For UNIX-like environments (which support symbolic links), the GetUnixPhysicalFilename function is called to retrieve the file name for the symlink. For other platforms and environments, like Amiga and Windows, symbolic links are not supported and the return values always contains the value in Filename.

Physical file name for the resolved symbolic link.
File name examined in the function.
Indicates the action performed for a symbolic link that cannot be resolved to a physical file name.
Resolves the symlink in Filename, including omitted directories.

If a symlink can not be resolved, and ExceptionOnError is False, the function returns an empty string (''). If ExceptionOnError is True, it raises an EFOpenError exception with a message containing more details.

GetUnixPhysicalFilename is used to implement the GetPhysicalFilename function for UNIX-like environments.

Physical file name for the resolved symbolic link.
File name (or symlink) examined in the function.
Indicates if an exception is raised for a symbolic link that cannot be resolved to a physical file name.
Gets the directory for application configuration and data files.

GetAppConfigDirUTF8 is a String function used to get the directory on the local file system where application configuration and data files are stored.

Global is a Boolean argument that determines if the directory is user- or system- specific. When Global contains False, the home directory for the user is used as the path in the return value.

Create is a Boolean argument that indicates if the configuration directory should be created if not already present on the local file system.

The implementation of GetAppConfigDirUTF8 is platform- and/or OS-specific.

For the Amiga platform, the GetAppConfigDir in the SysUtils unit is called to get the return value.

For Windows environments, the SHGetFolderPathUTF8 function is called to get the path information. The CSIDL (Constant Special Item ID List) required for the setting in Global and the target platform is passed to the routine. When VendorName is provided, it is appended to the path information. ApplicationName is also appended to the path information. If the path cannot be determined, the value from DGetAppConfigDir is used as the directory path.

For UNIX-like environments, the GetAppConfigDir function in the SysUtils unit is called to get the path information.

If the directory does not exist and Create contains True, the ForceDirectoriesUTF8 routine is called to create any missing directories for the path. An EInOutError exception is raised if any missing directory in the path cannot be created.

GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help viewer (LHelp).

GetAppConfigDir
Path to the directory used for application configuration or data files.
Indicates if the system-wide (not user specific) directory is used.
Indicates if missing directories in the path should be created.
Gets a UTF-8-encoded configuration file name for the current application.

GetAppConfigFileUTF8 is a String function used to get a UTF-8-encoded configuration file name for the current application. GetAppConfigFileUTF8 calls the GetAppConfigFile function in the SysUtils unit to get the return value for the function. SysToUTF8 is called for the file name to ensure that it is encoded using the UTF-8 encoding scheme.

Global is a Boolean which indicates whether system- or user-specific path information is used in the configuration file name. When Global contains True, the system-wide configuration path is used in the return value. Otherwise, a user-specific path is used in the return value.

SubDir is a Boolean value that indicates if a sub-directory for the application is included in the path for the configuration file. When SubDir is True, a "Config" sub-directory is included in the path information.

CreateDir is a Boolean argument that indicates if any missing directories in the configuration file path are created in the function. When CreateDir is False, no additional actions are performed in the function. Otherwise, the path information is passed to ForceDirectoriesUTF8 to create any missing directories. If any of the directories are not successfully created, an EInOutError exception is raised with the message in lrsUnableToCreateConfigDirectoryS.

The return value contains the path to the configuration file including the requested path, configuration file name, and configuration file extension.

Raises an EInOutError exception when directories in the path cannot be created on the local file system.
GetAppConfigFile SysToUTF8
Path to the configuration file for the application.
Indicates if system-wide settings are used in the configuration file name.
Indicates if a directory for the application is included in the configuration file name.
Indicates if missing directories in the configuration file path are created.
Gets a temporary file name using the specified UTF-8-encoded path and prefix.

GetTempFileNameUTF8 is a String function used to get a temporary file name with the specified prefix located in the specified directory.

Dir contains the path on the local file system where the temporary file should be located.

Prefix contains the prefix for the temporary file name. In other words, the temporary file name must start with this sequence of characters.

GetTempFileNameUTF8 signals the OnGetTempFile event handler (when assigned) to get the value used as the temporary file name. When OnGetTempFile has not been assigned, a string is constructed using the path information in Dir and a numeric suffix to make the file name unique. For example:

/usr/tmp/TMP0.tmp

GetTempFileNameUTF8 examines the files in the specified directory to determine if a file already exists which starts with the value in Prefix. If a file is located in the directory, a numeric suffix (starting at 0) is appended to the base file name in Prefix to build a temporary file name which does not already exist in the directory.

Temporary file name generated in the routine.
Directory path for the temporary file name.
Prefix for the temporary file name.
Indicates if the specified path uses Universal Naming Convention (UNC).

IsUNCPath is a Boolean function which indicates is the specified path uses Universal Naming Convention (UNC).

The implementation of IsUNCPath is platform- and/or OS-specific. For the Windows platform, IsUNCPath checks Path to see if it begins with the double backslash notation used for a UNC path. For example:

\\C:\directory\ \\?\C:\directory\ \\?\UNC\volume\directory\

For UNIX-like environments, as well as the Amiga platform, the return value is always False. UNC paths are not used on those platforms.

Use ExtractUNCVolume to get host and path information from a file name expressed using UNC notation.

True when the path contains UNC notation.
Path examined in the function.
Gets UNC host and volume name used in the specified path.

ExtractUNCVolume is a String function used to get host and volume information from a path specified using Universal Naming Convention (UNC). UNC notation is recognized using both the long and short formats defined for the naming convention.

The return value contains information needed to access shared resources by their host and volume names, and contains one of the following formats:

\\server-name\shared-resource-path-name\ \\mypc\nas-drive\ \\?\c:\ \\?\UNC\c:\

ExtractUNCVolume calls the IsUNCPath function to determine if the value in Path starts with the UNC naming delimiters. The return value is an empty string (''), and no additional actions are performed in the function, when Path does not use UNC notation.

ExtractUNCVolume examines the characters in Path to determine if it uses the long or the short format for UNC notation. Long format notation begins with the characters '\\?\' or '\\?\UNC\' followed by a drive designation and optional path information such as 'c:\'. Short format notation uses a host name and a shared resource identifier such as '\\mypc\nas-drive\'.

UNC host and volume name extracted from the specified path.
Path information examined in the function.
Gets the root drive/path/directory for the specified file name.

ExtractFileRoot is a String function used to get the root directory for the specified file name. It is file system-aware and includes the drive and/or volume information needed for the file name specified in the FileName argument.

When FileName uses Universal Naming Convention (UNC), the return value will contain any server and share/volume information included in the parameter. For example:

\\server-name\share-name\ \\?\C:\

For UNIX-like environments (as well as WinCE), an initial path delimiter marks the root directory in the file system.

For the Amiga platform, any characters in FileName up to (but not including) the first ":" character are used as the root directory.

For the Windows platform, a drive designation up to and including the first path delimiter are used as the root directory. For example:

C:\
Root directory on the file system for the specified file name
File name specifier examined in the routine.
Implemented when the platform or OS includes the darwin compiler define. Used in the implementation of TryCreateRelativePath for the Darwin platform.
Implemented when the platform or OS includes the darwin compiler define. Handles canonical string normalization forms for file names on the Darwin platform.
Works like the WinAPI function SHGetFolderPathW, but returns a UTF-8-encoded string.
UTF-8-encoded folder path for the identifier.
Identifier resolved in the function.
Splits command line parameters separated by whitespace characters.

Parameters are separated by one or more whitespace characters (#9,#10,#13,#32). Quoted values are parsed as a single parameter. If ReadBackslash contains True, then \" is replaced with " and not treated as a quoted value. #0 is always treated as the end of the Parameters value.

Whitespace-delimited list of parameters handled in the routine.
List where parameter names and values are stored.
Indicates if backslash characters are consumed and removed in the routine.
Ensures that whitespace and quoting use the format required for command line parameters.
Value after normalizing whitespace and quote characters in the command line parameter.
Command line parameter examined in the function.
Generates a string with the specified list of parameters.
String representation for the list of parameters.
Parameter names and values handled in the function.
Splits the specified command line into program and parameter values.
Command line examined in the function.
Executable name found in the command line.
List of parameters and values found in the command line.
Ensures command line options are formatted properly.
Command line option after quoting has been applied.
Command line option examined in the function.
Specifies the event signalled for an invalid file state in the file cache.

TInvalidateFileStateCacheEvent is the type which specifies the event signalled for an invalid file state in the file cache. TInvalidateFileStateCacheEvent is the type used for the OnInvalidateFileStateCache event handler signalled in the InvalidateFileStateCache procedure.

File name for the event notification.
Implements the event handler for a file with an invalid file state.

OnInvalidateFileStateCache is a TInvalidateFileStateCacheEvent variable which implements the event handler signalled for a file with an invalid file state. OnInvalidateFileStateCache allows an application to respond to the event notification for a specific file. OnInvalidateFileStateCache is signalled when InvalidateFileStateCache is called by routines that perform file manipulation.

OnInvalidateFileStateCache is significant for UNIX-like environments only, such as Linux and Amiga. OnInvalidateFileStateCache is not used in Windows environments.

Signals the OnInvalidateFileStateCache event handler.

InvalidateFileStateCache is a procedure used to signal the OnInvalidateFileStateCache event handler for the specified file name. InvalidateFileStateCache is used when an invalid file state is detected in routines which perform file manipulation, such as:

- DeleteFileUTF8
- FileSetAttrUTF8
- FileSetDateUTF8
- RenameFileUTF8

InvalidateFileStateCache is significant for UNIX-like environments only, such as Linux and Amiga. InvalidateFileStateCache is not used for the Windows platform.

File name for the event notification.