lazarus/docs/xml/lazutils/lazfileutils.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
=======================================================================
LazFileUtils
=======================================================================
-->
<module name="LazFileUtils">
<short>
Contains types, procedures, and functions used for file and directory 
operations.
</short>
<descr>
<p>
<file>lazfileutils.pas</file> contains types, procedures, and functions used 
for file and directory operations. <file>lazfileutils.pas</file> is part of 
the <file>LazUtils</file> package.
</p>
<remark>
All functions are thread-safe unless explicitly stated.
</remark>
</descr>

<element name="CompareFilenames">
<short>
Gets the relative sort order for the specified file names.
</short>
<descr>
<p>
<var>CompareFilenames</var> 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.
</p>
<p>
The return value indicates the relative order in a sort operation, and can 
contain the following values:
</p>
<dl>
<dt>&lt;0</dt>
<dd>Filename1 comes before Filename2</dd>
<dt>0</dt>
<dd>Filename1 and Filename2 to have the same value</dd>
<dt>&gt;0</dt>
<dd>Filename1 comes after Filename2</dd>
</dl>
</descr>
<seealso>
<link id="CompareFilenamesIgnoreCase"/>
</seealso>
</element>

<element name="CompareFilenames.Result">
<short>Relative sort order for the specified file names.</short>
</element>

<element name="CompareFilenames.Filename1">
<short>First file name for the comparison.</short>
</element>

<element name="CompareFilenames.Filename2">
<short>Second file name for the comparison.</short>
</element>

<element name="CompareFilenamesIgnoreCase">
<short>
Gets the relative sort order for case-insensitive file names.
</short>
<descr>
<p>
<var>CompareFilenamesIgnoreCase</var> 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.
</p>
<p>
The return value indicates the relative order in a case-insensitive sort 
operation, and can contain the following values:
</p>
<dl>
<dt>&lt;0</dt>
<dd>Filename1 comes before Filename2</dd>
<dt>0</dt>
<dd>Filename1 and Filename2 to have the same value</dd>
<dt>&gt;0</dt>
<dd>Filename1 comes after Filename2</dd>
</dl>
</descr>
<seealso>
<link id="CompareFilenames"/>
</seealso>
</element>
<element name="CompareFilenamesIgnoreCase.Result">
<short>Relative sort order for the file names.</short>
</element>
<element name="CompareFilenamesIgnoreCase.Filename1">
<short>First file name for the comparison.</short>
</element>
<element name="CompareFilenamesIgnoreCase.Filename2">
<short>Second file name for the comparison.</short>
</element>

<element name="CompareFileExt">
<short>
Compares the extension in a file name to a given value and returns the 
relative order.
</short>
<descr>
<p>
<var>CompareFileExt</var> is an overloaded <var>Integer</var> function used 
to compare the file extension in Filename to the value in Ext.
</p>
<p>
<var>FilenameM</var> contains the file name with the extension compared in 
the routine.
</p>
<p>
<var>Ext</var> contains the file extension for the comparison. It may contain 
the '.' character, but it is not required and will be removed for the 
comparison.
</p>
<p>
<var>CaseSensitive</var> indicates whether case is used in the comparison. 
When CaseSensitive contains <b>True</b>, CompareStr is called to perform the 
comparison. Otherwise, CompareText is called to compare the values.
</p>
<p>
The return value indicates the order for the file name extension relative to 
the specified extension. It may contain one of the following values:
</p>
<dl>
<dt>-1</dt>
<dd>
Filename value has a lower sort order value than Ext
</dd>
<dt>0</dt>
<dd>
Filename and Ext have the same sort order values
</dd>
<dt>1</dt>
<dd>
Filename value has a higher sort order value than Ext
</dd>
</dl>
<p>
The return value is 1 if Filename does not contain a file extension.
</p>
<p>
The overloaded variant which omits the CaseSensitive argument defaults to 
the setting for the <var>CaseInsensitiveFilenames</var> compiler define on 
the platform. When defined, the CaseSensitive argument defaults to 
<b>False</b>. Otherwise, <b>True</b> is used in the parameter value.
</p>
</descr>
<seealso/>
</element>
<element name="CompareFileExt.Result">
<short>Relative sort order for the compared values.</short>
</element>
<element name="CompareFileExt.Filename">
<short>File name for the comparison.</short>
</element>
<element name="CompareFileExt.Ext">
<short>File extension for the comparison.</short>
</element>
<element name="CompareFileExt.CaseSensitive">
<short><b>True</b> if case sensitive comparison is needed.</short>
</element>

<element name="CompareFilenameStarts">
<short>
Compares file names using the number characters in common.
</short>
<descr>
<p>
<var>CompareFilenameStarts</var> is an <var>Integer</var> 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.
</p>
<p>
See CompareFilenames for more information about the numeric return value and 
its meaning.
</p>
</descr>
<seealso>
<link id="CompareFileNames"/>
</seealso>
</element>
<element name="CompareFilenameStarts.Result">
<short>Relative sort order for the compared values.</short>
</element>
<element name="CompareFilenameStarts.Filename1">
<short>First file name for the comparison.</short>
</element>
<element name="CompareFilenameStarts.Filename2">
<short>Second file name for the comparison.</short>
</element>
<element name="CompareFilenames.Len1">
<short>Length of the first file name.</short>
</element>
<element name="CompareFilenames.Len2">
<short>Length of the seconds file name.</short>
</element>

<element name="CompareFilenamesP">
<short>
Compares file names to determine their relative sort order.
</short>
<descr>
<p>
<var>CompareFilenamesP</var> is an <var>Integer</var> function used to 
compare the specified file names to determine their relative sort order.
</p>
<p>
<var>Filename1</var> and <var>Filename2</var> are the PChar arguments 
containing the file names examined in the routine.
</p>
<p>
<var>IgnoreCase</var> indicates if upper- or lower-case differences are 
ignored in the file name comparison; the default value for the parameter 
is <b>False</b> (indicating that case differences are <b>not</b> ignored). 
For platforms where <b>CaseInsensitiveFilenames</b> is defined, the value 
in IgnoreCase defaults to <b>True</b>. When IgnoreCase is <b>True</b>, 
the <var>UTF8CompareText</var> 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.
</p>
<p>
If either Filename1 or Filename2 are unassigned (contain <b>Nil</b>) or begin 
with a Null character (<b>Decimal 0</b>), the return value is set <b>0</b> 
(<b>zero</b>) 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.
</p>
</descr>
<seealso>
<link id="CompareFilenames"/>
<link id="UTF8CompareText"/>
</seealso>
</element>
<element name="CompareFilenamesP.Result">
<short>Relative sort order for the compared values.</short>
</element>
<element name="CompareFilenamesP.Filename1">
<short>File name used in the comparison.</short>
</element>
<element name="CompareFilenamesP.Filename2">
<short>File name used in the comparison.</short>
</element>
<element name="CompareFilenamesP.IgnoreCase">
<short>
Indicates if case differences in file name comparisons are ignored.
</short>
</element>

<element name="FilenameExtIs">
<short>
Determines if Filename has the specified file extension.
</short>
<descr>
<p>
<var>FilenameExtIs</var> is a <var>Boolean</var> function used to determine 
if the file in the <var>Filename</var> parameter has the specified file 
extension in <var>Ext</var>.
</p>
<p>
Ext can contain the '<b>.</b>' (<b>Period</b>) character in the extension, 
but it is not required.
</p>
<p>
<var>CaseSensitive</var> indicates if case-sensitivity is used when comparing 
parameter values. When set to <b>True</b>, the comparison is limited to 
values in the ASCII character set. <var>StrLComp</var> or <var>StrLIComp</var> 
is called to compare the values in Filename to the values in Ext.
</p>
<p>
The return value is <b>True</b> when Filename uses the file extension in Ext. 
The return value is <b>False</b> for the following conditions:
</p>
<ul>
<li>
Filename is an empty string (<b>''</b>).
</li>
<li>
Filename does not have a '<b>.</b>' character that marks the start of the 
file extension.
</li>
<li>
The extension in Filename has a different length than Ext.
</li>
<li>
Filename has a different file extension than Ext.
</li>
</ul>
</descr>
<seealso>
<link id="FilenameExtIn"/>
</seealso>
</element>
<element name="FilenameExtIs.Result">
<short>
Returns <b>True</b> if Filename has the specified file extension.
</short>
</element>
<element name="FilenameExtIs.Filename">
<short>File name examined in the routine.</short>
</element>
<element name="FilenameExtIs.Ext">
<short>File extension expected in the file name.</short>
</element>
<element name="FilenameExtIs.CaseSensitive">
<short><b>True</b> to use case-sensitive comparison in the routine.</short>
</element>

<element name="FilenameExtIn">
<short>
Determines if the file name uses one of the specified file extensions.
</short>
<descr>
<p>
<var>FilenameExtIn</var> is a <var>Boolean</var> function used to determine 
if the file name in the <var>Filename</var> parameter uses one of the file 
extension in <var>Exts</var>.
</p>
<p>
Exts is an array type with the file extensions expected in the routine. 
Values in Exts can contain the '<b>.</b>' (<b>Period</b>) character in the 
extension, but it is not required.
</p>
<p>
<var>CaseSensitive</var> indicates if case-sensitivity is used when comparing 
the parameter values. When set to <b>True</b>, the comparison is limited to 
characters in the ASCII character set. <var>StrLComp</var> or 
<var>StrLIComp</var> is called to compare the value in Filename to the values 
in Exts.
</p>
<p>
The return value is <b>True</b> when Filename uses one the file extension in 
Exts. The return value is <b>False</b> when Filename is an empty string 
(<b>''</b>), does not include a '<b>.</b>' character that marks the start of 
the file extension, or does not use one of the values in Exts.
</p>
</descr>
<seealso>
<link id="FilenameExtIs"/>
</seealso>
</element>
<element name="FilenameExtIn.Result">
<short>
Returns <b>True</b> if Filename has one of the specified file extensions.
</short>
</element>
<element name="FilenameExtIn.Filename">
<short>File name examined in the routine.</short>
</element>
<element name="FilenameExtIn.Exts">
<short>File extensions expected in the file name.</short>
</element>
<element name="FilenameExtIn.CaseSensitive">
<short><b>True</b> to use case-sensitive comparison in the routine.</short>
</element>

<element name="DirPathExists">
<short>
Indicates if the specified directory name exists on the local file system.
</short>
<descr>
<p>
<var>DirPathExists</var> is a <var>Boolean</var> 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.
</p>
</descr>
<seealso>
<link id="DirectoryExistsUTF8"/>
</seealso>
</element>
<element name="DirPathExists.Result">
<short>
<b>True</b> when the specified directory exists in the file system.
</short>
</element>
<element name="DirPathExists.DirectoryName">
<short>Directory Name to locate.</short>
</element>

<element name="DirectoryIsWritable">
<short>
Indicates if the specified directory name is writable.
</short>
<descr>
<p>
<var>DirectoryIsWritable</var> is a <var>Boolean</var> 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 <b>False</b> if a directory with the specified name does not 
exist.
</p>
<p>
The return value is <b>True</b> 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 <b>True</b> when FileWrite completes successfully.
</p>
<remark>
DirectoryIsWritable calls InvalidateFileStateCache with the temporary file 
name if DeleteFileUTF8 cannot remove the file.
</remark>
</descr>
<seealso>
<link id="FileCreateUTF8"/>
<link id="DeleteFileUTF8"/>
<link id="InvalidateFileStateCache"/>
<link id="#rtl.sysutils.FileWrite">FileWrite</link>
<link id="#rtl.sysutils.FileClose">FileClose</link>
</seealso>
</element>
<element name="DirectoryIsWritable.Result">
<short><b>True</b> if the specified directory is writable.</short>
</element>
<element name="DirectoryIsWritable.DirectoryName">
<short>Directory name to examine in the function.</short>
</element>

<element name="ExtractFileNameOnly">
<short>
Gets the base file name (without the file extension) in the specified path.
</short>
<descr>
<p>
<var>ExtractFileNameOnly</var> is a <var>String</var> function used to 
extract the base file name (without the file extension) from the value in 
<var>AFilename</var>. Path information, up to the last directory separator 
('<b>/</b>' or '<b>\</b>') or device separator ('<b>:</b>') character, in 
AFileName is ignored. The file extension, starting at the '<b>.</b>' 
character, is also omitted.
</p>
</descr>
<seealso/>
</element>
<element name="ExtractFileNameOnly.Result">
<short>Base file name in the file path.</short>
</element>
<element name="ExtractFileNameOnly.AFilename">
<short>File path and name to examine in the function.</short>
</element>

<element name="ExtractFileNameWithoutExt">
<short>
Gets the value from AFilename prior to the '.' character that starts the file 
extension.
</short>
<descr>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="ExtractFileNameWithoutExt.Result">
<short>
File name (including path) after the file extension has been removed.
</short>
</element>
<element name="ExtractFileNameWithoutExt.AFilename">
<short>Qualified path and file name examined in the method.</short>
</element>

<element name="FilenameIsAbsolute">
<short>
Determines if the specified value is an absolute file path (not a 
relative one).
</short>
<descr>
<p>
<var>FilenameIsAbsolute</var> is a <var>Boolean</var> 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.
</p>
<p>
In UNIX-like environments, the FilenameIsUnixAbsolute function is used in the 
implementation. The return value is <b>False</b> if TheFilename is an empty 
string (''), or does not start with the directory separator for the 
environment.
</p>
<p>
On Windows, the FilenameIsWinAbsolute function is called in the 
implementation. FilenameIsWinAbsolute takes Device identifiers into 
consideration when examining the value in TheFilename. For example:
</p>
<code>
D:\db\employee.fdb
</code>
<p>
The return value is <b>False</b> if TheFilename (without the optional device 
identifier) is an empty string (''), or does not start with the directory 
separator for the environment.
</p>
</descr>
<seealso/>
</element>
<element name="FilenameIsAbsolute.Result">
<short><b>True</b> when the file name is not a relative path.</short>
</element>
<element name="FilenameIsAbsolute.TheFilename">
<short>Path and file name to use in the function.</short>
</element>

<element name="FilenameIsWinAbsolute">
<short>
Determines if the specified value is an absolute file path (not a 
relative one).
</short>
<descr>
<p>
<var>FilenameIsWinAbsolute</var> is a <var>Boolean</var> function used to 
determine if the value in TheFilename contains an absolute file path (and not 
a relative one).
</p>
<p>
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:
</p>
<code>
D:\db\employee.fdb
</code>
<p>
The return value is <b>False</b> if TheFilename (without the optional device 
identifier) is an empty string (''), or does not start with the directory 
separator for the environment.
</p>
</descr>
<seealso/>
</element>
<element name="FilenameIsWinAbsolute.Result">
<short><b>True</b> when the file name is not a relative path.</short>
</element>
<element name="FilenameIsWinAbsolute.TheFilename">
<short>Path and file name to use in the function.</short>
</element>

<element name="FilenameIsUnixAbsolute">
<short>
Determines if the specified value is an absolute file path (not a 
relative one).
</short>
<descr>
<p>
<var>FilenameIsUnixAbsolute</var> is a <var>Boolean</var> function used to 
determine if the value in TheFilename contains an absolute file path (and not 
a relative one).
</p>
<p>
In UNIX-like environments, the FilenameIsUnixAbsolute function is used in the 
implementation of FilenameIsAbsolute. The return value is <b>False</b> if 
TheFilename is an empty string (''), or does not start with the directory 
separator for the environment.
</p>
</descr>
<seealso/>
</element>
<element name="FilenameIsUnixAbsolute.Result">
<short><b>True</b> when the file name is not a relative path.</short>
</element>
<element name="FilenameIsUnixAbsolute.TheFilename">
<short>Path and file name to use in the function.</short>
</element>

<element name="ForceDirectory">
<short>
Creates the specified directory if it does not already exist.
</short>
<descr>
<p>
<var>ForceDirectory</var> is a Boolean function which creates the specified 
directory if it does not already exist. ForceDirectory ensures that a 
trailing path delimiter exists in <var>DirectoryName</var> 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.
</p>
<p>
Each directory in the specified path is validated by calling 
<var>DirPathExists</var>. ForceDirectory calls <var>CreateDirUTF8</var> if a 
directory does not exist, and may exit with a return value of <b>False</b> if 
directory creation is not successful.
</p>
<p>
The return value is <b>True</b> if all directories in the path information 
already exist, or are successfully created in the function.
</p>
</descr>
<seealso>
<link id="ForceDirectoriesUTF8"/>
<link id="DirPathExists"/>
<link id="CreateDirUtf8"/>
</seealso>
</element>
<element name="ForceDirectory.Result">
<short>
Returns <b>True</b> if directory exists or if it was successfully created.
</short>
</element>
<element name="ForceDirectory.DirectoryName">
<short>Path information for the operation.</short>
</element>

<element name="CheckIfFileIsExecutable">
<short>
Examines the specified file to see if it is executable.
</short>
<descr>
<p>
<var>CheckIfFileIsExecutable</var> 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.
</p>
<p>
CheckIfFileIsExecutable raises an exception with a specific message when the 
platform or OS facilities indicate it is necessary.
</p>
<p>
Use FileIsExecutable to determine of a file is executable without raising an 
exception.
</p>
</descr>
<errors>
<p>
The Exception contains the following messages (from string resources):
</p>
<dl>
<dt>lrsFileDoesNotExist</dt>
<dd>
Raised when FileExistsUTF8 returns <b>False</b>
</dd>
<dt>lrsFileIsADirectoryAndNotAnExecutable</dt>
<dd>
Raised when DirPathExists indicates the file is actually a directory name
</dd>
<dt>lrsReadAccessDeniedFor</dt>
<dd>
Raised when fpGetErrno() returns ESysEAcces
</dd>
<dt>lrsADirectoryComponentInDoesNotExistOrIsADanglingSyml</dt>
<dd>
Raised when fpGetErrno() returns ESysENoEnt
</dd>
<dt>lrsADirectoryComponentInIsNotADirectory</dt>
<dd>
Raised when fpGetErrno() returns ESysENotDir
</dd>
<dt>lrsInsufficientMemory</dt>
<dd>
Raised when fpGetErrno() returns ESysENoMem
</dd>
<dt>lrsHasACircularSymbolicLink</dt>
<dd>
Raised when fpGetErrno() returns ESysELoop
</dd>
<dt>lrsIsNotExecutable</dt>
<dd>
Raised when fpGetErrno() has a value other than the above
</dd>
</dl>
</errors>
</element>
<element name="CheckIfFileIsExecutable.AFilename">
<short>File name to examine.</short>
</element>

<element name="CheckIfFileIsSymlink">
<short>
Checks whether the specified file name is a symbolic link on the local file 
system.
</short>
<descr>
<p>
<var>CheckIfFileIsSymlink</var> is a routine used to ensure that the file 
name specified in <var>AFilename</var> is a valid symbolic link on the local 
file system. It acts as an assert for the pre-condition.
</p>
<p>
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.
</p>
<p>
For the Windows platform, the file name must be a link create using mklink on 
the local file system.
</p>
<p>
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:
</p>
<dl>
<dt>ESysEAcces</dt>
<dd>Read access is denied for the symbolic link.</dd>
<dt>ESysENoEnt</dt>
<dd>A directory does not exist or is a dangling symbolic link.</dd>
<dt>ESysENotDir</dt>
<dd>A value in the file name is not a directory.</dd>
<dt>ESysENoMem</dt>
<dd>Insufficient memory to a access the symbolic link.</dd>
<dt>ESysELoopy</dt>
<dd>A circular reference was detected in the symbolic link.</dd>
</dl>
<p>
Calling CheckIfFileIsSymlink on the Amiga platform will always result in an 
exception. Symbolic links are not supported on the Amiga platform.
</p>
</descr>
<errors>
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.
</errors>
<seealso/>
</element>
<element name="CheckIfFileIsSymlink.AFilename">
<short>File name examined in the routine.</short>
</element>

<element name="FileIsExecutable">
<short>
Determines if the specified file name is executable.
</short>
<descr>
<p>
<var>FileIsExecutable</var> is a <var>Boolean</var> 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.
</p>
</descr>
<seealso/>
</element>
<element name="FileIsExecutable.Result">
<short><b>True</b> if the file is executable on the platform or OS.</short>
</element>
<element name="FileIsExecutable.AFilename">
<short>File name to examine.</short>
</element>

<element name="FileIsSymlink">
<short>
Indicates if the specified file is a symbolic link in the file system.
</short>
<descr>
<p>
<var>FileIsSymlink</var> is a <var>Boolean</var> function used to determine 
if the specified file name is a symbolic link on the local file system.
</p>
<p>
The implementation of FileIsSymlink is platform-specific. For UNIX-like 
environments, the <var>FpReadLink</var> 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, <var>FileGetAttrUTF8</var> is called to get 
and examine the file attributes for the specified file name. The file 
attributes must include the value <b>FILE_ATTRIBUTE_REPARSE_POINT</b>, and 
one of the Windows API values such as <b>IO_REPARSE_TAG_SYMLINK</b> or 
<b>IO_REPARSE_TAG_MOUNT_POINT</b> for the corresponding file handle. For the 
Amiga platform, FileIsSymLink always returns <b>False</b>.
</p>
</descr>
<seealso>
<link id="FileGetAttrUTF8"/>
<link id="#rtl.baseunix.FpReadLink">FpReadLink</link>
</seealso>
</element>
<element name="FileIsSymlink.Result">
<short><b>True</b> when the specified file name is a symbolic link.</short>
</element>
<element name="FileIsSymlink.AFilename">
<short>File name examined in the routine`</short>
</element>

<element name="FileIsHardLink">
<short>
Indicates if the specified file has a descriptor or handle on the local file 
system.
</short>
<descr>
<p>
<var>FileIsHardLink</var> is a <var>Boolean</var> function used to determine 
if the specified file name is represented by a file descriptor or handle on 
the local file system.
</p>
<p>
The implementation of FileIsHardLink is platform- or OS-specific. For 
UNIX-like environments, a file handle is retrieved by calling the 
<var>FileOpenUTF8</var> function and passed to the <var>FpFStat</var> 
function to access the file information. For the Windows platform (excluding 
WinCE and Windows XP), the <var>GetFileInformationByHandle</var> Windows API 
routine is called to get information for the file handle. For the Amiga 
platform, FileIsHardLink always returns <b>False</b>.
</p>
<p>
The return value is <b>False</b> 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.
</p>
</descr>
<seealso>
<link id="FileOpenUTF8"/>
<link id="#rtl.BaseUnix.FpFstat">FpFstat</link>
</seealso>
</element>
<element name="FileIsHardLink.Result">
<short>
<b>True</b> when file information can be accessed by its descriptor or handle.
</short>
</element>
<element name="FileIsHardLink.AFilename">
<short>File name examined in the routine.</short>
</element>

<element name="FileIsReadable">
<short>
Indicates if the specified file name is readable.
</short>
<descr>
<p>
<var>FileIsReadable</var> is a <var>Boolean</var> 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.
</p>
</descr>
<seealso>
<link id="FileExistsUTF8"/>
<link id="#rtl.baseunix.FpAccess">FpAccess</link>
</seealso>
</element>
<element name="FileIsReadable.Result">
<short><b>True</b> when the specified file name is readable.</short>
</element>
<element name="FileIsReadable.AFilename">
<short>File name to examine.</short>
</element>

<element name="FileIsWritable">
<short>
Indicates if the specified file name is writable.
</short>
<descr>
<p>
<var>FileIsWritable</var> is a <var>Boolean</var> 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.
</p>
</descr>
<seealso/>
</element>
<element name="FileIsWritable.Result">
<short><b>True</b> when the specified file name is writable.</short>
</element>
<element name="FileIsWritable.AFilename">
<short>File name to examine.</short>
</element>

<element name="FileIsText">
<short>
Determines if the specified file contains plain text content.
</short>
<descr>
<p>
<var>FileIsText</var> is a <var>Boolean</var> 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.
</p>
<p>
FileIsText calls FileOpenUtf8 for the specified file name. The return value 
is <b>False</b> is the file handle contains feInvalidHandle.
</p>
<p>
FileIsText checks for (and skips) common Byte Order Marks, such as:
</p>
<ul>
<li>UTF-8 BOM (Hex $EF $BB $BF)</li>
<li>UCS-2LE BOM (Hex $FF $FE)</li>
<li>UCS-2BE BOM (Hex $FE $FF)</li>
</ul>
<p>
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 
<b>True</b> when the specified file name exists in the local file system, and 
does not contain Null or Control characters.
</p>
</descr>
<seealso/>
</element>
<element name="FileIsText.Result">
<short><b>True</b> when the file contains plain text content.</short>
</element>
<element name="FileIsText.AFilename">
<short>File name to examine in the function.</short>
</element>
<element name="FileIsText.FileReadable">
<short>
Indicates if the specified file was successfully opened and read.
</short>
</element>

<element name="FilenameIsTrimmed">
<short>
<b>True</b> if the specified file name contains characters to remove or 
resolve before use.
</short>
<descr>
<p>
<var>FilenameIsTrimmed</var> is an overloaded <var>Boolean</var> 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 <b>False</b> when the file name is a 
candidate for use of TrimFilename to remove whitespace or special characters.
</p>
<p>
Use TrimFilename to remove leading or trailing whitespace, duplicate 
directory separators, or relative path symbols.
</p>
</descr>
<seealso/>
</element>
<element name="FilenameIsTrimmed.Result">
<short><b>False</b> when the file name needs to trimmed.</short>
</element>
<element name="FilenameIsTrimmed.TheFilename">
<short>File name to examine in the function.</short>
</element>
<element name="FilenameIsTrimmed.StartPos">
<short>PChar with the file name value.</short>
</element>
<element name="FilenameIsTrimmed.NameLen">
<short>Length of the file name.</short>
</element>

<element name="TrimFilename">
<short>
Removes leading and trailing spaces, and resolves special characters.
</short>
<descr>
<var>TrimFilename</var> is a <var>String</var> 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 '//').
</descr>
<seealso>
<link id="ResolveDots"/>
<link id="FileNameIsTrimmed"/>
<link id="CleanAndExpandFilename"/>
<link id="CleanAndExpandDirectory"/>
<link id="TrimAndExpandFilename"/>
<link id="TrimAndExpandDirectory"/>
</seealso>
</element>
<element name="TrimFilename.Result">
<short>New value for the path and file name.</short>
</element>
<element name="TrimFilename.AFilename">
<short>Path and file name for the operation.</short>
</element>

<element name="ResolveDots">
<short>
Resolves relative path references and removes duplicate path delimiters.
</short>
<descr>
<p>
<var>ResolveDots</var> is a <var>String</var> function used to convert 
relative path information in <var>AFilename</var> to an absolute path 
reference. A relative path includes characters like '.' (for current 
directory - not a file name extension) and '..' (parent directory). Duplicate 
path limiters ('\\' for Windows) ('//' for UNIX-like environments) are 
converted to a single instance of the <var>PathDelimiter</var> defined for 
the platform.
</p>
<p>
For Windows platforms, drive letter designations and delimiters like 'C:' are 
recognized. A path starting with the UNC naming convention ('\\?\') is not 
resolved in the method.
</p>
<p>
Windows-specific file system quirks handled in the routine include:
</p>
<dl>
<dt>C:..</dt>
<dd>Not resolved, it is copied.</dd>
<dt>C:\..</dt>
<dd>Resolved to C:\</dd>
<dt>\\..</dt>
<dd>Resolved to \\</dd>
<dt>c:/path/to/dir</dt>
<dd>
Resolved to C:\path\to\dir using the PathDelimiter for the platform.
</dd>
</dl>
<p>
For UNIX-like environments, the resolved path may be invalid if it references 
the parent directory and the initial directory in the path is a symbolic link.
</p>
<p>
When AFilename ends with a relative path ('/.' or '/..'), the path is resolved 
to the directory represented by the relative value. The current directory for 
'/.' or the parent directory for '/..'.
</p>
<p>
If a relative path reference cannot be resolved for the local file system, 
the original path information is retained.
</p>
<p>
Some common examples include:
</p>
<dl>
<dt>foo/bar/..</dt>
<dd>Resolved to foo</dd>
<dt>foo//..//</dt>
<dd>Resolved to .</dd>
<dt>foo/bar/./../baz</dt>
<dd>Resolved to foo/baz</dd>
<dt>/a/b/../..</dt>
<dd>Resolved to /</dd>
<dt>.//.//.</dt>
<dd>Resolved to .</dd>
</dl>
<p>
Macros found in the AFilename are retained in the resolved file name. For example:
</p>
<code>
'($LazarusDir)/../path/that/may/be/invalid/for/macro/filename.ext'
</code>
<p>
If AFilename ends with a path trailing path delimiter or a relative path 
reference, the return value will end with a trailing path delimiter.
</p>
</descr>
</element>
<element name="ResolveDots.Result">
<short>
File name with relative paths expanded and duplicate delimiters removed.
</short>
</element>
<element name="ResolveDots.AFilename">
<short>Qualified file name examined in the routine.</short>
</element>

<element name="CleanAndExpandFilename">
<short>
Removes whitespace and resolves special characters in the specified file name.
</short>
<descr>
<p>
<var>CleanAndExpandFilename</var> is a <var>String</var> 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 ('').
</p>
</descr>
<seealso/>
</element>
<element name="CleanAndExpandFilename.Result">
<short>
File name with whitespace removed and special characters resolved.
</short>
</element>
<element name="CleanAndExpandFilename.Filename">
<short>File name to examine in the function.</short>
</element>

<element name="CleanAndExpandDirectory">
<short>
Removes whitespace and resolves special characters in the specified path.
</short>
<descr>
<p>
<var>CleanAndExpandDirectory</var> is a <var>String</var> function used to 
remove whitespace and resolve special characters in the specified path. 
CleanAndExpandDirectory calls <var>CleanAndExpandFilename</var> to get the 
return value for the function. CleanAndExpandDirectory calls 
<var>AppendPathDelim</var> 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 (<b>''</b>).
</p>
</descr>
<seealso>
<link id="CleanAndExpandFilename"/>
<link id="AppendPathDelim"/>
</seealso>
</element>
<element name="CleanAndExpandDirectory.Result">
<short>
Path information after removing whitespace and resolving special characters.
</short>
</element>
<element name="CleanAndExpandDirectory.Filename">
<short>Path information for the function.</short>
</element>

<element name="TrimAndExpandFilename">
<short>
Cleans and resolves a file path to the specified base directory name.
</short>
<descr>
<p>
<var>TrimAndExpandFilename</var> is a <var>String</var> 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.
</p>
<p>
The return value is an empty string (<b>''</b>) if Filename contains an empty 
string (<b>''</b>).
</p>
</descr>
<seealso/>
</element>
<element name="TrimAndExpandFilename.Result">
<short>Cleaned and resolved file path.</short>
</element>
<element name="TrimAndExpandFilename.Filename">
<short>File name for the function.</short>
</element>
<element name="TrimAndExpandFilename.BaseDir">
<short>Base directory name used for a relative file path.</short>
</element>

<element name="TrimAndExpandDirectory">
<short>
Cleans and resolves a relative path to a base directory.
</short>
<descr>
<p>
<var>TrimAndExpandDirectory</var> is a <var>String</var> function used to 
remove whitespace and special characters in the path information, and to 
resolve a relative path to the specified base directory.
</p>
<p>
TrimAndExpandDirectory calls <var>ExpandFileNameUTF8</var> to resolve the 
relative path, and calls <var>TrimFilename</var> to get the return value for 
the function. The return value is an empty string (<b>''</b>) when 
TrimFilename returns an empty string (<b>''</b>).
</p>
</descr>
<seealso>
<link id="ExpandFileNameUTF8"/>
<link id="TrimFilename"/>
</seealso>
</element>
<element name="TrimAndExpandDirectory.Result">
<short>
Path information cleaned and resolved to the specified base directory.
</short>
</element>
<element name="TrimAndExpandDirectory.Filename">
<short>Path information for the function.</short>
</element>
<element name="TrimAndExpandDirectory.BaseDir">
<short>Base directory used to resolve a relative path.</short>
</element>

<element name="CreateAbsolutePath">
<short>
Returns an absolute path relative to the specified base directory 
(when needed).
</short>
<descr>
<p>
<var>CreateAbsolutePath</var> is a <var>String</var> function used to get the 
absolute path to the file specified in the <var>Filename</var> argument. A 
relative path reference in Filename is resolved to the path in the 
<var>BaseDir</var> argument. The return value contains the fully-qualified 
absolute path to the specified file name.
</p>
<p>
When Filename is an empty string ('') or already uses an absolute path 
reference, the value in Filename is used as the return value.
</p>
<p>
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.
</p>
<p>
CreateAbsolutePath calls TrimFileName to remove leading or trailing 
whitespace or duplicate path delimiters in the return value.
</p>
<remark>
CreateAbsolutePath does not validate path or file name information; the file 
or directory does not have to exist on the local file system.
</remark>
<p>
<b>Example:</b>
</p>
<code>
// 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));
</code>
</descr>
<seealso>
<link id="FilenameIsAbsolute"/>
<link id="TrimFileName"/>
<link id="AppendPathDelim"/>
<link id="#rtl.sysutils.ExtractFileDrive">ExtractFileDrive</link>
</seealso>
</element>
<element name="CreateAbsolutePath.Result">
<short>
Fully-qualified absolute path to the specified file relative to a given base 
directory.
</short>
</element>
<element name="CreateAbsolutePath.Filename">
<short>
File name with relative path references resolved in the routine.
</short>
</element>
<element name="CreateAbsolutePath.BaseDirectory">
<short>
Base directory used to resolve a relative path reference in the file name.
</short>
</element>

<element name="TryCreateRelativePath">
<short>
Attempts to create a path in Dest relative to the path in Source.
</short>
<descr>
<p>
Returns <b>True</b> if it is possible to create a relative path from Source 
to Dest. The function must be thread safe, so no expansion of filenames is done 
since this is not thread-safe (at least on Windows platform).
</p>
<ul>
<li>
Both Dest and Source must be either absolute filenames or relative file names.
</li>
<li>
Dest and Source cannot contain '..' since no expansion is done by design.
</li>
<li>
Dest and Source must be on same drive or UNC path (Windows).
</li>
<li>
If both Dest and Source are relative they must at least share their base 
directory.
</li>
<li>
Double PathDelims are ignored (unless they are part of the UNC convention).
</li>
<li>
If UsePointDirectory is <b>True</b> and RelPath is an empty string (''), 
RelPath is set to the current directory ('.').
</li>
<li>
If AlwaysRequireSharedBaseFolder is <b>False</b> then Absolute filenames need 
not share a base folder.
</li>
<li>
If the function succeeds, RelPath contains the relative path from Source to 
Dest. A PathDelimiter is not appended to the end of RelPath.
</li>
</ul>
<remark>
TryCreateRelativePath does not physically create any folders need for the 
derived relative path to Dest.
</remark>
<p>
<b>Examples:</b>
</p>
<code>
- 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
</code>
</descr>
<seealso/>
</element>
<element name="TryCreateRelativePath.Result">
<short>
Returns <b>True</b> if the path from Source to Dest is a relative path that can 
be derived using the arguments to the routine.
</short>
</element>
<element name="TryCreateRelativePath.Dest">
<short>
Path to the destination directory (relative or absolute).
</short>
</element>
<element name="TryCreateRelativePath.Source">
<short>
Path to the source directory (relative or absolute).
</short>
</element>
<element name="TryCreateRelativePath.UsePointDirectory">
<short>
<b>True</b> if RelPath is set to '.' when an empty relative path ('') is 
derived from Source to Dest.
</short>
</element>
<element name="TryCreateRelativePath.AlwaysRequireSharedBaseFolder">
<short>
<b>False</b> requires use of absolute paths in both Source and Dest.
</short>
</element>
<element name="TryCreateRelativePath.RelPath">
<short>
Returns the relative path from Source to Dest derived in the routine.
</short>
</element>

<element name="CreateRelativePath">
<short>
Gets the relative path from BaseDirectory to Filename.
</short>
<descr>
<p>
<var>CreateRelativePath</var> is a <var>String</var> function used to get the 
relative path from <var>BaseDirectory</var> to <var>Filename</var>. A 
trailing path delimiter in BaseDirectory is ignored. If there is no relative 
path, the value in Filename is returned.
</p>
<p>
When BaseDirectory and Filename contain the same value, and 
<var>UsePointDirectory</var> is <b>False</b>, an empty string (<b>''</b>) is 
used as the return value. If UsePointDirectory contains <b>True</b>, the 
return value is the '.' character. Duplicate path delimiters are removed.
</p>
<remark>
CreateRelativePath is thread safe, and therefore, does not guarantee that the 
current directory is correct for file names like 'D:test.txt'.
</remark>
</descr>
<seealso>
<link id="TryCreateRelativePath"/>
</seealso>
</element>
<element name="CreateRelativePath.Result">
<short>Relative path from the base directory for the file name.</short>
</element>
<element name="CreateRelativePath.Filename">
<short>File name for the operation.</short>
</element>
<element name="CreateRelativePath.BaseDirectory">
<short>Base directory for the relative path.</short>
</element>
<element name="CreateRelativePath.UsePointDirectory">
<short>
<b>True</b> if '.' (current directory symbol) is prepended to the relative 
path.
</short>
</element>

<element name="FileIsInPath">
<short>
Returns <b>True</b> if Filename exists in the specified Path.
</short>
<descr>
<p>
<var>FileIsInPath</var> is a <var>Boolean</var> 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: 
<b>'../filename.txt'</b>.
</p>
<p>
Path is the directory name used to locate the specified file. For example: 
<b>'/usr/lib/fpc'</b>.
</p>
<p>
The returns value is <b>True</b> 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 <b>False</b>. Please note: the return value 
is <b>False</b> when Path contains an empty string ('').
</p>
<p>
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.
</p>
<remark>
This is a logical test;  FileIsInPath does not expand or follow symbolic 
links.
</remark>
</descr>
<seealso/>
</element>
<element name="FileIsInPath.Result">
<short><b>True</b> when the file exists in the specified path.</short>
</element>
<element name="FileIsInPath.Filename">
<short>File name to locate.</short>
</element>
<element name="FileIsInPath.Path">
<short>Path used for the operation.</short>
</element>

<element name="PathIsInPath">
<short>
Checks whether the specified directory exists in a given path.
</short>
<descr>
<p>
<var>PathIsInPath</var> is a <var>Boolean</var> function used to determine if 
the specified <var>Directory</var> exists in the <var>Path</var> argument. 
The return value is <b>False</b> when Path contains an empty string (''), or 
when the Directory does not exist in Path.
</p>
<p>
PathIsInPath calls the <var>CompareFilenames</var> routine to determine the 
return value for the function.
</p>
<remark>
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:\'.
</remark>
</descr>
<seealso/>
</element>
<element name="PathIsInPath.Result">
<short><b>True</b> when Directory exists in Path.</short>
</element>
<element name="PathIsInPath.Path">
<short>Path examined in the routine.</short>
</element>
<element name="PathIsInPath.Directory">
<short>Directory name to locate in the specified path.</short>
</element>

<element name="ShortDisplayFilename">
<short>
Gets a shortened version of the specified file name up to a maximum length.
</short>
<descr>
<p>
<var>ShortDisplayFilename</var> is a <var>String</var> 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.
</p>
<remark>
These are three (3) Period characters and not an Ellipsis character.
</remark>
<p>
The return value is the same as the <var>aFileName</var> argument if the file 
name did not need to be shortened.
</p>
</descr>
<seealso/>
</element>
<element name="ShortDisplayFilename.Result">
<short>Shortened version of the specified file name.</short>
</element>
<element name="ShortDisplayFilename.aFileName">
<short>File name examined in the routine.</short>
</element>
<element name="ShortDisplayFilename.aLimit">
<short>Maximum number of characters for the shortened file name.</short>
</element>

<element name="TPathDelimSwitch">
<short>
Represents the platform- or OS-specific path delimiters available in the 
Lazarus LCL.
</short>
<descr>
<p>
<var>TPathDelimSwitch</var> 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.
</p>
</descr>
<seealso/>
</element>
<element name="TPathDelimSwitch.pdsNone">
<short>No path delimiter changes were used.</short>
</element>
<element name="TPathDelimSwitch.pdsSystem">
<short>
Path delimiter is switched to the default path delimiter for the system.
</short>
</element>
<element name="TPathDelimSwitch.pdsUnix">
<short>
Path delimiter is switched to the UNIX path delimiter (forward slash).
</short>
</element>
<element name="TPathDelimSwitch.pdsWindows">
<short>
Path delimiter is switched to the Windows path delimiter (Backslash '\').
</short>
</element>

<element name="PathDelimSwitchToDelim">
<short>
Constant array with characters used as path delimiters for supported 
platforms and OS's.
</short>
<descr>
<p>
<var>PathDelimSwitchToDelim</var> is an array constant with character values 
for path delimiters associated with <var>TPathDelimSwitch</var> enumeration 
values. The <var>DirectorySeparator</var> 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.
</p>
</descr>
<seealso>
<link id="TPathDelimSwitch"/>
<link id="SwitchPathDelims"/>
<link id="#rtl.system.DirectorySeparator">DirectorySeparator</link>
</seealso>
</element>

<element name="ForcePathDelims">
<short>
Ensures that path delimiters in the specified file name are correct for the 
current platform or OS.
</short>
<descr>
<p>
<var>ForcePathDelims</var> 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 <var>FileName</var> to ensure that 
path delimiters use the correct notation for the platform or OS defined in 
the LCL.
</p>
<p>
For Windows, this means any UNIX path delimiters (<b>/</b>) in FileName are 
converted into the Windows path delimiter (<b>\</b>). Conversely, for all 
other platforms and environments, the Windows path delimiter (<b>\</b>) is 
converted to the UNIX notation (<b>/</b>). All path delimiter substitutions 
in FileName occur inline.
</p>
</descr>
<seealso/>
</element>
<element name="ForcePathDelims.FileName">
<short>File name examined in the routine.</short>
</element>

<element name="GetForcedPathDelims">
<short>
Performs path delimiter substitutions for the specified file name.
</short>
<descr>
<p>
<var>GetForcedPathDelims</var> is a <var>String</var> function used to 
perform path delimiter substitutions on the specified file name for the 
current platform or OS. GetForcedPathDelims calls <var>ForcePathDelims</var> 
using a copy of <var>FileName</var> as an argument. This ensures that the 
original file name remains unchanged when path delimiter substitutions are 
needed.
</p>
</descr>
<seealso>
<link id="ForcePathDelims"/>
</seealso>
</element>
<element name="GetForcedPathDelims.Result">
<short>File name after any path delimiter substitutions.</short>
</element>
<element name="GetForcedPathDelims.FileName">
<short>File name examined in the function.</short>
</element>

<element name="AppendPathDelim">
<short>
Adds a trailing path delimiter to the specified path (when needed).
</short>
<descr>
<p>
<var>AppendPathDelim</var> is a <var>String</var> function used to ensure that 
a trailing path delimiter is included in the specified <var>Path</var>. 
AppendPathDelim adds the platform-specific character in PathDelim to the end of 
Path if it is not an empty string, and does not already end with one of the 
values in AllowDirectorySeparators.
</p>
<p>
The return value contains the path with the added trailing path delimiter 
character, or the unmodified value in Path if a path delimiter was not added in 
the routine.
</p>
<p>
AppendPathDelim does not perform any type of resolution, expansion, or 
validation of the value passed in Path. Use routines like ExpandFileName(), 
DirectoryExists(), or FileExists() to perform these actions for a given path 
value. For UTF-8-enabled paths use ExpandFileNameUTF8(), FileExistsUTF8(), or 
DirectoryExistsUTF8().
</p>
<p>
Use ChompPathDelim to remove a trailing path delimiter from a specified path.
</p>
<p>
<b>Windows</b>
</p>
<p>
Please note that a value like 'C:' in Path results in 'C:\' in the return 
value. AppendPathDelim does <b>not</b> access the disk device to determine the 
per-device current directory; it simply appends the trailing path delimiter to 
the return value.
</p>
</descr>
<seealso>
<link id="ChompPathDelim"/>
<link id="DirectoryExistsUTF8"/>
<link id="ExpandFileNameUTF8"/>
<link id="FileExistsUTF8"/>
<link id="#rtl.sysutils.DirectoryExists">DirectoryExists</link>
<link id="#rtl.sysutils.ExpandFileName">ExpandFileName</link>
<link id="#rtl.sysutils.ExtractFilePath">ExtractFilePath</link>
<link id="#rtl.sysutils.FileExists">FileExists</link>
<link id="#rtl.sysutils.PathDelim">PathDelim</link>
<link id="#rtl.system.DirectorySeparator">DirectorySeparator</link>
<link id="#rtl.system.AllowDirectorySeparators">AllowDirectorySeparators</link>
</seealso>
</element>
<element name="AppendPathDelim.Result">
<short>
A path value which includes a trailing path delimiter.
</short>
</element>
<element name="AppendPathDelim.Path">
<short>
Path value examined in the routine.
</short>
</element>

<element name="ChompPathDelim">
<short>
Removes a trailing path delimiter from the specified value.
</short>
<descr>
<p>
<var>ChompPathDelim</var> is a <var>String</var> 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.
</p>
</descr>
<seealso/>
</element>
<element name="ChompPathDelim.Result">
<short>Path information after removing the trailing path delimiter.</short>
</element>
<element name="ChompPathDelim.Path">
<short>Path information for the function.</short>
</element>

<element name="SwitchPathDelims">
<short>
Replaces path delimiters in a file path with the specified delimiter.
</short>
<descr>
<p>
<var>SwitchPathDelims</var> is an overloaded <var>String</var> function used 
to ensure that path delimiter characters in Filename use the required 
character.
</p>
<p>
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:
</p>
<dl>
<dt>pdsNone</dt>
<dd>
No path delimiter substitutions are performed. The original value in Filename 
is used as the return value for the function.
</dd>
<dt>pdsSystem</dt>
<dd>
Path delimiters use the character required for the current platform or 
environment running the application.
</dd>
<dt>pdsUnix</dt>
<dd>
Path delimiters use the UNIX forward slash (/) character.
</dd>
<dt>pdsWindows</dt>
<dd>
Path delimiters use the Windows backslash (\) character.
</dd>
</dl>
<p>
The function examines each character in Filename are replaces any path 
delimiters encountered with the value specified in Switch.
</p>
<p>
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.
</p>
<p>
The return value contains the value from Filename after any path delimiter 
substitutions have been applied.
</p>
</descr>
<seealso>
<link id="TPathDelimSwitch"/>
<link id="SwitchPathDelims"/>
</seealso>
</element>
<element name="SwitchPathDelims.Result">
<short>File path and name after any path delimiter substitutions.</short>
</element>
<element name="SwitchPathDelims.Filename">
<short>File path and name examined in the function.</short>
</element>
<element name="SwitchPathDelims.Switch">
<short>
Indicates the desired path delimiter to use in the return value.
</short>
</element>

<element name="CheckPathDelim">
<short>
Determines if the specified path delimiter character is not used on the 
system.
</short>
<descr>
<p>
<var>CheckPathDelim</var> is a <var>TPathDelimSwitch</var> 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.
</p>
<p>
CheckPathDelim compares the value in <var>OldPathDelim</var> to the current 
<var>PathDelim</var> 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 <b>pdsNone</b> 
indicating that path delimiter substitutions are not needed.
</p>
<p>
<var>Changed</var> is a <var>Boolean</var> 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 <b>False</b> when the 
current path delimiter matches the value in OldPathDelim.
</p>
</descr>
<seealso>
<link id="SwitchPathDelims"/>
<link id="ForcePathDelims"/>
<link id="IsCurrentPathDelim"/>
</seealso>
</element>
<element name="CheckPathDelim.Result">
<short>
Enumeration value indicating the path delimiter substitution required.
</short>
</element>
<element name="CheckPathDelim.OldPathDelim">
<short>Value to compare to the current path delimiter for the system.</short>
</element>
<element name="CheckPathDelim.Changed">
<short>
<b>True</b> if path delimiters were changed to match the platform.
</short>
</element>

<element name="IsCurrentPathDelim">
<short>
Determines if the current path delimiter matches the specified path delimiter 
notation.
</short>
<descr>
<p>
<var>IsCurrentPathDelim</var> is a <var>Boolean</var> function used to 
determine if the path delimiter notation specified in Switch matches the 
current path delimiter for the system.
</p>
<p>
<var>Switch</var> is a <var>TPathDelimSwitch</var> 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:
</p>
<dl>
<dt>pdsNone</dt>
<dd>
No comparison is performed since it is not required. Return value is set 
<b>True</b>.
</dd>
<dt>pdsSystem</dt>
<dd>
No comparison is performed since it will always match the current path 
delimiter for the system. Return value is set <b>True</b>.
</dd>
<dt>pdsUnix</dt>
<dd>
Return value is set to <b>True</b> when PathDelim contains the UNIX forward 
slash (/) character.
</dd>
<dt>pdsWindows</dt>
<dd>
Return value is set to <b>True</b> when PathDelim contains the Windows 
backslash (\) character.
</dd>
</dl>
</descr>
<seealso/>
</element>
<element name="IsCurrentPathDelim.Result">
<short>Boolean result of the path delimiter comparison.</short>
</element>
<element name="IsCurrentPathDelim.Switch">
<short>
Enumeration value specifying the character compared to the current path 
delimiter.
</short>
</element>

<element name="CreateAbsoluteSearchPath">
<short>
Concatenates <var>BaseDirectory</var> and <var>SearchPath</var> to form an 
absolute path to search for files.
</short>
<descr>
<p>
<var>CreateAbsoluteSearchPath</var> concatenates <var>BaseDirectory</var> and 
<var>SearchPath</var> to form an absolute path to search for files.
</p>
<p>
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.
</p>
<p>
If <var>BaseDirectory</var> is empty, the function exits with a return value 
equal to <var>SearchPath</var>. if <var>SearchPath</var> is empty, the 
function exits with empty string <b>('')</b> in the return value.
</p>
</descr>
</element>
<element name="CreateAbsoluteSearchPath.Result">
<short>
The absolute path formed by concatenating <var>BaseDirectory</var> and 
<var>SearchPath</var>.
</short>
</element>
<element name="CreateAbsoluteSearchPath.SearchPath">
<short>The search path (a relative path).</short>
</element>
<element name="CreateAbsoluteSearchPath.BaseDirectory">
<short>The base directory from which to form the absolute path.</short>
</element>

<element name="CreateRelativeSearchPath">
<short>
Resolves relative path value(s) in the specified search path.
</short>
<descr>
<p>
<var>CreateRelativeSearchPath</var> is a <var>String</var> function used to 
resolve one or more paths in <var>SearchPath</var> relative to the directory 
specified in <var>BaseDirectory</var>. 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.
</p>
<p>
SearchPath can contain multiple path values by using the semicolon character 
(<b>;</b>) to separate the paths.
</p>
<p>
BaseDirectory specifies the directory used as the anchor (or root) for each 
resolved search path.
</p>
<p>
Paths specified in SearchPath are resolved individually, and recombined with 
other path values in SearchPath. If either SearchPath or BaseDirectory 
contain an empty string (<b>''</b>), no actions are performed in the 
function. The return value contains a copy of the contents in SearchPath with 
relative paths resolved.
</p>
</descr>
<seealso>
<link id="FilenameIsAbsolute"/>
<link id="CreateRelativePath"/>
</seealso>
</element>
<element name="CreateRelativeSearchPath.Result">
<short>
Search path after resolving relative paths to the specified base directory.
</short>
</element>
<element name="CreateRelativeSearchPath.SearchPath">
<short>
Search path(s) examined in the function.
</short>
</element>
<element name="CreateRelativeSearchPath.BaseDirectory">
<short>
Directory used as the anchor for resolved relative paths.
</short>
</element>

<element name="MinimizeSearchPath">
<short>
Trims the specified path, and removes empty or duplicate paths.
</short>
<descr>
<p>
<var>MinimizeSearchPath</var> is a <var>String</var> function used to trim 
the path(s) specified in <var>SearchPath</var>, and to remove empty or 
duplicate paths in the argument. SearchPath can contain multiple path 
specifications separated by the semicolon (';') character.
</p>
<p>
MinimizeSearchPath iterates over the path specifications in SearchPath and 
calls TrimFilename as needed. ChompPathDelim is called as well to remove 
trailing path delimiters as needed. Duplicate occurrence of a search path are 
reduced to a single occurrence.
</p>
<p>
The return value contains the value in SearchPath after normalization and 
removal of duplicate and empty search path specifications.
</p>
</descr>
<seealso>
<link id="ChompPathDelim"/>
<link id="TrimFilename"/>
<link id="FileNameIsTrimmed"/>
<link id="FindPathInSearchPath"/>
</seealso>
</element>
<element name="MinimizeSearchPath.Result">
<short>Search path after normalization and removal of duplicates.</short>
</element>
<element name="MinimizeSearchPath.SearchPath">
<short>Search path(s) examined in the function.</short>
</element>

<element name="FindPathInSearchPath">
<short>
Locates the specified path in a delimited list of search paths.
</short>
<descr>
<p>
<var>FindPathInSearchPath</var> is an overloaded function used to locate the 
path specified in <var>APath</var> in a list of search paths.
</p>
<p>
<var>APath</var> contains the search path to locate in the delimited list of 
search paths. A trailing path delimiter specified in APath is ignored.
</p>
<p>
<var>SearchPath</var> 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 <b>Nil</b>) or contains an empty string (<b>''</b>).
</p>
<p>
The return value is either an <var>Integer</var> or a <var>PChar</var> 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.
</p>
<p>
Compiler defines determine the mechanism used to perform a comparison of the 
values in APath and SearchPath; i.e. <var>CaseInsensitiveFilenames</var> and 
<var>NotLiteralFilenames</var>. <var>CompareFilenames</var> is called to 
perform the comparison when inline comparison of string values in not 
supported.
</p>
</descr>
<seealso/>
</element>
<element name="FindPathInSearchPath.Result">
<short>Position or value for the located search path.</short>
</element>
<element name="FindPathInSearchPath.APath">
<short>Path to locate in the delimited list of search paths.</short>
</element>
<element name="FindPathInSearchPath.APathLen">
<short>Length in characters for the path to locate in the routine.</short>
</element>
<element name="FindPathInSearchPath.SearchPath">
<short>Delimited list of search paths examined in the routine.</short>
</element>
<element name="FindPathInSearchPath.SearchPathLen">
<short>Length in characters for the search paths list.</short>
</element>

<element name="FileExistsUTF8">
<short>
Indicates if the specified UTF-8-encoded file name exists.
</short>
<descr>
<p>
<var>FileExistsUTF8</var> is a <var>Boolean</var> function which indicates if 
the specified file name exists on the local file system. FileExistsUTF8 calls 
the <var>FileExists</var> function in <file>SysUtils</file> to get the return 
value for the routine.
</p>
</descr>
<seealso>
<link id="#rtl.sysutils.FileExists">FileExists</link>
</seealso>
</element>
<element name="FileExistsUTF8.Result">
<short><b>True</b> when the specified file name exists.</short>
</element>
<element name="FileExistsUTF8.Filename">
<short>UTF-8-encoded file name to locate on the local file system.</short>
</element>

<element name="FileAgeUTF8">
<short>
Returns the last modification time for the file in FileDate format.
</short>
<descr>
<p>
<var>FileAgeUTF8</var> is a <var>Longint</var> function which returns the 
last modification time for the file specified in <var>FileName</var>. 
FileAgeUTF8 should not be used on directories; it returns <b>-1</b> if 
FileName represents a directory instead of a file.
</p>
<p>
For UNIX-like environments, the return value is provided by the 
<var>FileAge</var> function in the <file>SysUtils</file> 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.
</p>
<p>
The return value is in FileDate format, and can be transformed to a TDateTime 
value with the FileDateToDateTime function.
</p>
</descr>
<seealso/>
</element>
<element name="FileAgeUTF8.Result">
<short>Last modification time for the file in FileDate format.</short>
</element>
<element name="FileAgeUTF8.FileName">
<short>File name examined in the function.</short>
</element>

<element name="DirectoryExistsUTF8">
<short>
Determine if the specified path exists on the local file system.
</short>
<descr>
<p>
<var>DirectoryExistsUTF8</var> is <var>Boolean</var> function used to 
determine if the specified path exists on the local file system. For the 
Windows environment, FileGetAttrUTF8 is called to see if <b>
FILE_ATTRIBUTE_DIRECTORY</b> is included in the file attributes for the 
specified Directory. For UNIX-like environments, the DirectoryExists function 
in the <file>SysUtils</file> unit is used to get the return value.
</p>
</descr>
<seealso/>
</element>
<element name="DirectoryExistsUTF8.Result">
<short><b>True</b> when the directory exists in the file system.</short>
</element>
<element name="DirectoryExistsUTF8.Directory">
<short>Directory name to locate in the file system.</short>
</element>

<element name="ExpandFileNameUTF8">
<short>
Expands the values in FileName and BaseDir to an absolute file name.
</short>
<descr>
<p>
<var>ExpandFileNameUTF8</var> is a <var>String</var> 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.
</p>
<p>
If an empty string ('') is passed in Filename, it is expanded to the current 
directory using GetCurrentDirUTF8. When FileName contains the tilde character 
(<b>~</b>), it is converted to the path to the home directory for the user 
using the <var>HOME</var> environment variable. Relative paths in FileName 
are resolved by calling ResolveDots.
</p>
</descr>
<seealso>
<link id="GetCurrentDirUTF8"/>
<link id="ResolveDots"/>
</seealso>
</element>
<element name="ExpandFileNameUTF8.Result">
<short>The file name with an absolute path.</short>
</element>
<element name="ExpandFileNameUTF8.FileName">
<short>File name examined in the function.</short>
</element>
<element name="ExpandFileNameUTF8.BaseDir">
<short>Base directory used to resolve a relative path.</short>
</element>

<element name="FindFirstUTF8">
<short>
Starts searching for files matching the specified path value.
</short>
<descr>
<p>
<var>FindFirstUTF8</var> 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.
</p>
<p>
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.
</p>
<p>
The return value contains the result from GetLastError; a non-zero value 
indicates that no files matching the criteria were found.
</p>
</descr>
<seealso>
<link id="#rtl.sysutils.FindFirst">FindFirst</link>
</seealso>
</element>
<element name="FindFirstUTF8.Result">
<short>Last error number encountered in the function.</short>
</element>
<element name="FindFirstUTF8.Path">
<short>Path and/or file name to locate.</short>
</element>
<element name="FindFirstUTF8.Attr">
<short>File attributes to include in the search.</short>
</element>
<element name="FindFirstUTF8.Rslt">
<short>Search record for the first matching file.</short>
</element>

<element name="FindNextUTF8">
<short>
Locates another file matching the search criteria.
</short>
<descr>
<p>
<var>FindNextUTF8</var> 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.
</p>
<p>
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.
</p>
<p>
The return value contains the result from GetLastError; a non-zero value 
indicates that an error was encountered.
</p>
</descr>
<seealso/>
</element>
<element name="FindNextUTF8.Result">
<short>Last error number.</short>
</element>
<element name="FindNextUTF8.Rslt">
<short>Search criteria for the function.</short>
</element>

<element name="FindCloseUTF8">
<short>
Frees resources allocated to the specified search record.
</short>
<descr>
<p>
<var>FindCloseUTF8</var> is a procedure used to free resources allocated to 
the search record in F by the <var>FindFirstUTF8</var> routine. FindCloseUTF8 
calls the FindClose function in the <file>SysUtils</file> unit.
</p>
</descr>
<seealso/>
</element>
<element name="FindCloseUTF8.F">
<short>Search record to free in the procedure.</short>
</element>

<element name="FileSetDateUTF8">
<short>
Sets the last modification time for the file.
</short>
<descr>
<p>
<var>FileSetDateUTF8</var> is a <var>Longint</var> 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.
</p>
<p>
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.
</p>
<p>
The return value is the value from GetLastError; a non-zero value indicates 
that an error has occurred.
</p>
</descr>
<seealso/>
</element>
<element name="FileSetDateUTF8.Result">
<short>Last error number in the function.</short>
</element>
<element name="FileSetDateUTF8.FileName">
<short>File name to update in the function.</short>
</element>
<element name="FileSetDateUTF8.Age">
<short>New value for the last modification time.</short>
</element>

<element name="FileGetAttrUTF8">
<short>
Gets the value of file attributes for the specified file name.
</short>
<descr>
<p>
<var>FileGetAttrUTF8</var> is a <var>Longint</var> 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 return value.
</p>
<p>
The return value contains a numeric value that can be OR-ed with the 
following constants to get a specific file attribute:
</p>
<dl>
<dt>faReadOnly</dt>
<dd>
The file is read-only
</dd>
<dt>faHidden</dt>
<dd>
The file is hidden (On UNIX, the file name starts with a dot)
</dd>
<dt>faSysFile</dt>
<dd>
The file is a system file (On UNIX, the file is a character, block or FIFO 
file).
</dd>
<dt>faVolumeId</dt>
<dd>
Volume Label (For DOS/Windows on a plain FAT - not VFAT or Fat32)
</dd>
<dt>faDirectory</dt>
<dd>
File is a directory
</dd>
<dt>faArchive</dt>
<dd>
File is ready to be archived (Not possible on UNIX)
</dd>
</dl>
</descr>
<seealso/>
</element>
<element name="FileGetAttrUTF8.Result">
<short>File attribute value for the specified file name.</short>
</element>
<element name="FileGetAttrUTF8.FileName">
<short>File name for the function.</short>
</element>

<element name="FileSetAttrUTF8">
<short>
Sets the file attribute value for the specified file name.
</short>
<descr>
<p>
<var>FileSetAttrUTF8</var> is a <var>Longint</var> 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:
</p>
<dl>
<dt>faReadOnly</dt>
<dd>
The file is read-only
</dd>
<dt>faHidden</dt>
<dd>
The file is hidden (On UNIX, the file name starts with a dot)
</dd>
<dt>faSysFile</dt>
<dd>
The file is a system file (On UNIX, the file is a character, block or FIFO 
file).
</dd>
<dt>faVolumeId</dt>
<dd>
Volume Label (For DOS/Windows on a plain FAT - not VFAT or Fat32)
</dd>
<dt>faDirectory</dt>
<dd>
File is a directory
</dd>
<dt>faArchive</dt>
<dd>
File is ready to be archived (Not possible on UNIX)
</dd>
</dl>
<p>
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.
</p>
<p>
The return value contains the result from GetLastError; a non-zero value 
indicates that an error has occurred.
</p>
</descr>
<seealso/>
</element>
<element name="FileSetAttrUTF8.Result">
<short>Last error number from the function.</short>
</element>
<element name="FileSetAttrUTF8.Filename">
<short>File name to update in the function.</short>
</element>
<element name="FileSetAttrUTF8.Attr">
<short>File attribute value for the specified file name.</short>
</element>

<element name="DeleteFileUTF8">
<short>
Deletes the specified file name.
</short>
<descr>
<p>
<var>DeleteFileUTF8</var> is a Boolean function used to delete the specified 
file name.
</p>
<p>
For the Windows environment, DeleteFileW in Windows is called to remove the 
specified file name. For UNIX-like environments, DeleteFile in the 
<file>SysUtils</file> unit is called to delete the specified file name. 
InvalidateFileStateCache is also called.
</p>
<p>
The return value contains <b>True</b> when Filename is successfully deleted 
from the local file system.
</p>
</descr>
<seealso/>
</element>
<element name="DeleteFileUTF8.Result">
<short><b>True</b> if the specified file name is deleted.</short>
</element>
<element name="DeleteFileUTF8.FileName">
<short>File name to delete in the function.</short>
</element>

<element name="RenameFileUTF8">
<short>
Renames a file to the specified value.
</short>
<descr>
<p>
<var>RenameFileUTF8</var> is a <var>Boolean</var> function used to rename a 
file to the value specified in NewName.
</p>
<p>
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.
</p>
<p>
The return value is <b>True</b> if the file is renamed successfully.
</p>
</descr>
<seealso/>
</element>
<element name="RenameFileUTF8.Result">
<short>
<b>True</b> if the file is successfully renamed to the new value.
</short>
</element>
<element name="RenameFileUTF8.OldName">
<short>Existing name for the file.</short>
</element>
<element name="RenameFileUTF8.NewName">
<short>New name for the file.</short>
</element>

<element name="FileSearchUTF8">
<short>
Searches for a file with the specified name in the list of directory paths.
</short>
<descr>
<p>
<var>FileSearchUTF8</var> is a <var>String</var> function used to search for 
files with the specified name in the list of directory paths.
</p>
<p>
<var>DirList</var> is a list of file paths to search in the function. Values 
in DirList are separated by the <var>PathSeparator</var> character for the 
environment. No additional directories are searched when DirList contains an 
empty string ('').
</p>
<p>
<var>ImplicitCurrentDir</var> controls whether the search is implicitly 
limited to the current directory. The default value for ImplicitCurrentDir is 
<b>True</b>. 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.
</p>
<p>
When ImplicitCurrentDir is <b>False</b>, 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.
</p>
</descr>
<seealso/>
</element>
<element name="FileSearchUTF8.Result">
<short>Path and file name for the matching file, or an empty string.</short>
</element>
<element name="FileSearchUTF8.Name">
<short>File name to locate in the list of directory paths.</short>
</element>
<element name="FileSearchUTF8.DirList">
<short>The delimited list of directory paths to search.</short>
</element>

<element name="FileIsReadOnlyUTF8">
<short>
Determines if the specified file is marked as read-only.
</short>
<descr>
<p>
<var>FileIsReadOnlyUTF8</var> is a <var>Boolean</var> 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 <b>True</b> when faReadOnly has been included in 
the file attributes.
</p>
</descr>
<seealso/>
</element>
<element name="FileIsReadOnlyUTF8.Result">
<short><b>True</b> when the file is marked as read-only.</short>
</element>
<element name="FileIsReadOnlyUTF8.FileName">
<short>File name to examine in the function.</short>
</element>

<element name="GetCurrentDirUTF8">
<short>
Gets the name for the current directory.
</short>
<descr>
<p>
<var>GetCurrentDirUTF8</var> is a <var>String</var> function used to get the 
name for the current directory in the local file system.
</p>
<p>
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.
</p>
<p>
For UNIX-like environments, GetCurrentDir in SysUtils is called to get the 
current directory name.
</p>
</descr>
<seealso>
<link id="#rtl.sysutils.GetCurrentDir">GetCurrentDir</link>
</seealso>
</element>
<element name="GetCurrentDirUTF8.Result">
<short>Name for the current directory.</short>
</element>

<element name="SetCurrentDirUTF8">
<short>
Sets the current directory to the specified name.
</short>
<descr>
<p>
<var>SetCurrentDirUTF8</var> is a <var>Boolean</var> function used to set the 
current directory in the local file system to the specified value.
</p>
<p>
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.
</p>
<p>
For UNIX-like environments, SetCurrentDir in SysUtils is used to set the 
current directory to the specified value.
</p>
<p>
The return value is <b>True</b> if the current directory is successfully 
changed to the new value.
</p>
</descr>
<errors>
<dl>
<dt>TException</dt>
<dd>
Raised for the Windows CE environment; exception message is: 
'[SetCurrentDirWide] The concept of the current directory doesn't exist in 
Windows CE'
</dd>
</dl>
</errors>
<seealso/>
</element>
<element name="SetCurrentDirUTF8.Result">
<short>
<b>True</b> if the current directory was successfully changed to the new 
value.
</short>
</element>
<element name="SetCurrentDirUTF8.NewDir">
<short>Directory name to use as the current directory.</short>
</element>

<element name="CreateDirUTF8">
<short>
Creates a new directory with the specified name.
</short>
<descr>
<p>
<var>CreateDirUTF8</var> is a <var>Boolean</var> 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.
</p>
<p>
The return value is <b>True</b> if the new directory is successfully created.
</p>
</descr>
<errors>
<p>
An error can occur if a directory with the specified name already exists in 
the local file system.
</p>
</errors>
<seealso/>
</element>
<element name="CreateDirUTF8.Result">
<short><b>True</b> if the new directory is successfully created.</short>
</element>
<element name="CreateDirUTF8.NewDir">
<short>Name for the new directory.</short>
</element>

<element name="RemoveDirUTF8">
<short>
Removes the directory with the specified name.
</short>
<descr>
<p>
<var>RemoveDirUTF8</var> is a <var>Boolean</var> function used to remove the 
directory with the specified name from the local file system.
</p>
<p>
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.
</p>
<p>
For UNIX-like environments, RemoveDir in SysUtils is called to remove the 
specified directory.
</p>
<p>
The return value is <b>True</b> when the specified directory is successfully 
removed.
</p>
</descr>
<seealso>
<link id="#rtl.sysutils.RemoveDir">RemoveDir</link>
</seealso>
</element>
<element name="RemoveDirUTF8.Result">
<short><b>True</b> when the directory is successfully removed.</short>
</element>
<element name="RemoveDirUTF8.Dir">
<short>Name of the directory to remove in the function.</short>
</element>

<element name="ForceDirectoriesUTF8">
<short>
Creates the directories specified in Dir if they do not already exist.
</short>
<descr>
<p>
<var>ForceDirectoriesUTF8</var> is a <var>Boolean</var> function which creates 
any missing directories specified in the UTF-8-encoded <var>Dir</var> argument. 
Dir can contain notation using the following conventions:
</p>
<dl>
<dt>Windows device and path</dt>
<dd>
A disk drive available on the local system, such as 'C:' or 'D:', and directory 
names. For example: 'C:\Windows\Fonts'.
</dd>
<dt>Universal Naming Convention identifier</dt>
<dd>
UNC notation like '\\server\share\path\to\dir' (for Windows) or 
'//hostname/path/to/dir' (for UNIX-like systems). Please note that UNC support
is not available on all platforms where LCL/LazUtils are hosted.
</dd>
<dt>
Path specification
</dt>
<dd>
A path specification as used on the local file systems For example: 
'/path/to/dir' or '\path\to\dir'. Relative paths, like './foo' or '.\foo', are 
resolved to the directory where the application executable is located.
</dd>
</dl>
<p>
ForceDirectoriesUTF8 calls ExtractFileDrive to get the disk or UNC host+share 
name used in Dir. No actions are performed if the return value from 
ExtractFileDrive is an empty device identifier, or the device does not have a 
valid root directory on the local file system. The return value is set to 
<b>False</b>.
</p>
<p>
ForceDirectories raises an <var>EInOutError</var> exception with the message 
in <var>SCannotCreateEmptyDir</var> when Dir contains an empty string ('').
</p>
<p>
ForceDirectoriesUTF8 converts path delimiters specified in Dir to the value 
required for the platform using ForcePathDelims (when needed).
</p>
<p>
Each directory found in Dir is checked using DirectoryExistsUTF8. CreateDirUTF8 
is called if a directory does not already exist, and may exit with a return 
value of <b>False</b> if directory creation is not successful.
</p>
<p>
The return value is <b>True</b> if all directories in the path information 
already exist, or are successfully created in the function.
</p>
<code>
var bOk: Boolean;
// ...
bOk := ForceDirectoriesUTF8('\\capcom\telemetry\eva\bio');
bOk := ForceDirectoriesUTF8('//capcom/telemetry/eva/gps');
bOk := ForceDirectoriesUTF8('/home/jsmith/capcom/telemetry/eva/camera');
bOk := ForceDirectoriesUTF8('C:\capcom\telemetry\eva\era');
</code>
</descr>
<errors>
<dl>
<dt>EIOnOutError</dt>
<dd>
Raised when the directory name is an empty string (''); Message is 
SCannotCreateEmptyDir, and ErrorCode is set to 3.
</dd>
</dl>
</errors>
<seealso>
<link id="DirectoryExistsUTF8"/>
<link id="CreateDirUTF8"/>
<link id="GetForcedPathDelims"/>
<link id="ForceDirectory"/>
<link id="#rtl.sysutils.ExtractFileDrive">ExtractFileDrive</link>
<link id="#rtl.sysutils.ExtractFilePath">ExtractFilePath</link>
<link id="#rtl.system.DirectorySeparator">DirectorySeparator</link>
</seealso>
</element>
<element name="ForceDirectoriesUTF8.Result">
<short>
<b>True</b> when directories exist or are successfully created in the 
function.
</short>
</element>
<element name="ForceDirectoriesUTF8.Dir">
<short>
Device and path information to examine the function.
</short>
</element>

<element name="FileOpenUTF8">
<short>
Opens the specified file name and returns its file handle.
</short>
<descr>
<p>
<var>FileOpenUTF8</var> is a <var>THandle</var> function used to open the 
UTF-8-encoded file name in <var>FileName</var>, and return its file handle. 
FileOpenUTF8 converts the file name to system format by calling 
<var>UTF8ToSys</var>, and calls the <var>FileOpen</var> routine in the 
<file>SysUtils</file> unit to get the file handle for the opened file.
</p>
</descr>
<seealso>
<link id="UTF8ToSys"/>
<link id="#rtl.sysutils.FileOpen">FileOpen</link>
</seealso>
</element>
<element name="FileOpenUTF8.Result">
<short>File handle for the specified file.</short>
</element>
<element name="FileOpenUTF8.FileName">
<short>File name opened in the function.</short>
</element>
<element name="FileOpenUTF8.Mode">
<short>File access mode requested for the opened file.</short>
</element>

<element name="FileCreateUTF8">
<short>Creates the specified file and returns its file handle.</short>
<descr>
<p>
<var>FileCreateUTF8</var> is a <var>THandle</var> function used to created 
the file specified in the UTF-8-encoded <var>FileName</var> 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.
</p>
<p>
FileCreateUTF8 calls <var>UTF8ToSys</var> to convert the file name to its 
system representation, and calls the <var>FileCreate</var> routine in the 
<file>SysUtils</file> unit to create the file and get its file handle.
</p>
</descr>
<seealso>
<link id="UTF8ToSys"/>
<link id="#rtl.sysutils.FileCreate">FileCreate</link>
</seealso>
</element>
<element name="FileCreateUTF8.Result">
<short>File handle for the file created in the function.</short>
</element>
<element name="FileCreateUTF8.FileName">
<short>File name created in the function.</short>
</element>
<element name="FileCreateUTF8.Rights">
<short>File access rights for the new file.</short>
</element>
<element name="FileCreateUTF8.ShareMode">
<short>File sharing mode for the new file.</short>
</element>

<element name="FileSizeUtf8">
<short>Gets the size for the specified file name.</short>
<descr>
<p>
<var>FileSizeUTF8</var> is an <var>Int64</var> function used to get the size 
for the file specified in the UTF-8-encoded <var>Filename</var> argument. 
FileSizeUTF8 calls <var>Utf8ToSys</var> to convert the value in Filename to 
the system string type type, and calls the <var>FindFirst</var> routine in 
the <file>SysUtils</file> unit to get the size for the specified file name.
</p>
</descr>
<seealso>
<link id="#rtl.sysutils.FindFirst">FindFirst</link>
</seealso>
</element>
<element name="FileSizeUtf8.Result">
<short>Size of the file on the local file system.</short>
</element>
<element name="FileSizeUtf8.Filename">
<short>File name examined in the function.</short>
</element>

<element name="GetFileDescription">
<short>Gets descriptive information for the specified file name.</short>
<descr>
<p>
<var>GetFileDescription</var> is a <var>String</var> 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.
</p>
<p>
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:
</p>
<code>
ld-rwxrwxrwx Owner: UID.GID Size: 99999 Modified: MM/DD/YYYY hh:nn
</code>
<dl>
<dt>l</dt>
<dd>File is a symbolic link</dd>
<dt>d</dt>
<dd>File is a directory in the file system</dd>
<dt>b,c, or -</dt>
<dd>
Device type for the entry. b is for block-level devices. c is for character 
devices. All others device types contain the - character.
</dd>
<dt>r or -</dt>
<dd>User read access permission</dd>
<dt>w or -</dt>
<dd>User write access permission</dd>
<dt>x or -</dt>
<dd>User executable permission</dd>
<dt>r or -</dt>
<dd>Group read access permission</dd>
<dt>w or -</dt>
<dd>Group write access permission</dd>
<dt>x or -</dt>
<dd>Group executable permission</dd>
<dt>r or -</dt>
<dd>Other read access permission</dd>
<dt>w or -</dt>
<dd>Other write access permission</dd>
<dt>x or -</dt>
<dd>Other executable permission</dd>
<dt>UID</dt>
<dd>User identifier number assigned as the owner of the file</dd>
<dt>GID</dt>
<dd>Group identifier number assigned to the group which owns the file</dd>
<dt>99999</dt>
<dd>
Size of the file. May indicate the total number of blocks or characters 
depending on the device type for the file.
</dd>
<dt>MM/DD/YYYY hh:nn or ?</dt>
<dd>
Creation/modification timestamp for the file. ? is included if an exception 
is raised when accessing the date/time value.
</dd>
</dl>
<p>
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:
</p>
<code>
asperwd
</code>
<dl>
<dt>a</dt>
<dd>File is an archived (unchanged) file</dd>
<dt>s</dt>
<dd>File is a script or executable file</dd>
<dt>p</dt>
<dd>File is command or program that can be made resident</dd>
<dt>e</dt>
<dd>File is used by the Shell</dd>
<dt>r</dt>
<dd>File is readable</dd>
<dt>w</dt>
<dd>File is writable</dd>
<dt>d</dt>
<dd>File <b>cannot</b> be deleted</dd>
</dl>
<p>
For Windows platforms, the return value contains only the modification date / 
time for the file using the format:
</p>
<code>Modified: MM/DD/YYYY hh:mm</code>
<p>
The return value can be 'Modified: ?' if an exception is encountered when 
getting the date/time value for the file.
</p>
</descr>
<seealso/>
</element>
<element name="GetFileDescription.Result">
<short>String with the file information for the platform or OS.</short>
</element>
<element name="GetFileDescription.AFilename">
<short>File name examined in the function.</short>
</element>

<element name="ReadAllLinks">
<short>
Resolves a symbolic link to an actual file name.
</short>
<descr>
<p>
<var>ReadAllLinks</var> is a <var>String</var> function used to resolve a 
symbolic link to an actual file name. The implementation is platform-specific.
</p>
<p>
For UNIX-like platforms, fpReadLink (RTL) is used to recursively follow 
symbolic links starting at FileName (to a maximum depth of 12) until it is 
resolved to a path on the local file system. No actions are performed in the 
routine if FileName is a regular file and not a symbolic link.
</p>
<p>
The return value contains the resolved path to the file on the local file 
system. This includes calling ResolveDots for a file name with a relative path.
If the return value is empty when an error is detected, the error message is 
captured and used in an EFOpenError exception raised when ExceptionOnError is 
enabled. If ExceptionOnError is <b>False</b>, the function returns an empty 
string ('') for an invalid link.
</p>
<p>
For the Windows platform, FileGetSymLinkTarget (RTL) is recursively called (to 
a maximum depth of 20) to get the reparse point with the target file name. The 
return value contains the UTF-8-encoded path to the file on the local file 
system, or an empty string if FileName is not a valid symbolic link. 
ExceptionOnError indicates whether an EFOpenError exception is raised for an 
invalid link in FileName. If ExceptionOnError is <b>False</b>, the function 
returns an empty string ('') and the exception is <b>not</b> raised for an 
invalid link.
</p>
<p>
For the Amiga platform, the return value is always an empty string ('').
</p>
</descr>
<version>
Modified in LazUtils version 3.6 to implement the routine on the Windows 
platform.
</version>
</element>
<element name="ReadAllLinks.Result">
<element name="#rtl.sysutils.FileGetSymLinkTarget">FileGetSymLinkTarget (RTL)</element>
<link id="#rtl.baseunix.fpReadLink">fpReadLnk (RTL)</link>
<short>
Resolved path to the specified file name, or an exception message when 
link(s) could not be resolved.
</short>
</element>
<element name="ReadAllLinks.Filename">
<short>Symbolic link resolved in the routine.</short>
</element>
<element name="ReadAllLinks.ExceptionOnError">
<short>
<b>True</b> to raise an exception for unresolved or broken links. <b>False</b> 
to handle the error internally without raising an exception.
</short>
</element>

<element name="TryReadAllLinks">
<short>
Resolves a symlink to a real file name.
</short>
<descr>
<p>
If a symlink can not be resolved it returns Filename. It calls the 
ReadAllLinks function in its implementation.
</p>
</descr>
<seealso>
<link id="ReadAllLinks"/>
</seealso>
</element>

<element name="GetShellLinkTarget">
<short>
Resolves a Shell Link to the file path for the shortcut.
</short>
<descr>
<p>
<var>GetShellLinkTarget</var> is a <var>String</var> function used to resolve 
the Shell Link file in the <var>FileName</var> parameter to a path on the 
local system. The return value contains the qualified path to the Shell 
object in the Link file.
</p>
<p>
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.
</p>
<p>
GetShellLinkTarget is implemented for UNIX-like platforms and Amiga, but 
simply returns the value in the FileName parameter.
</p>
<p>
The Windows CE platform does not have the IShellLinkW interface; the value in 
FileName is always used as the return value.
</p>
<p>
FileName must contain a file name that uses the <b>.lnk</b> 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.
</p>
<p>
GetShellLinkTarget uses the IShellLinkW interface to resolve the Shell Link 
to the path for the Shell object.
</p>
</descr>
<seealso/>
</element>
<element name="GetShellLinkTarget.Result">
<short>Path to the Shell object for the link.</short>
</element>
<element name="GetShellLinkTarget.FileName">
<short>Shell Link shortcut file to resolve in the routine.</short>
</element>

<element name="DbgSFileAttr">
<short>
Generates a debugger message with information about the specified file 
attributes.
</short>
<descr>
<p>
<var>Attr</var> contains the file attributes examined in the routine, with 
the following values displayed for the corresponding file attributes:
</p>
<dl>
<dt>-1</dt>
<dd>Invalid</dd>
<dt>faDirectory</dt>
<dd>D</dd>
<dt>faArchive</dt>
<dd>A</dd>
<dt>faSysFile</dt>
<dd>S</dd>
<dt>faReadOnly</dt>
<dd>R</dd>
<dt>faHidden</dt>
<dd>H</dd>
<dt>faVolumeId</dt>
<dd>V</dd>
<dt>faSymLink</dt>
<dd>L</dd>
</dl>
<p>
File attributes not found in Attrib are represented as '-' characters.
</p>
</descr>
<seealso/>
</element>
<element name="DbgSFileAttr.Result">
<short>String with information about the file attributes.</short>
</element>
<element name="DbgSFileAttr.Attr">
<short>File attributes examined in the routine.</short>
</element>

<element name="TPhysicalFilenameOnError">
<short>
Enumerated type representing actions performed for an unresolved file name.
</short>
<descr>
<p>
<var>TPhysicalFilenameOnError</var> 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.
</p>
<p>
TPhysicalFilenameOnError is the type used to represent the <var>OnError</var> 
argument passed to the <var>GetPhysicalFilename</var> function.
</p>
</descr>
<seealso>
<link id="GetPhysicalFilename"/>
</seealso>
</element>
<element name="TPhysicalFilenameOnError.pfeException">
<short>
Causes an exception to be raised for the missing file name.
</short>
</element>
<element name="TPhysicalFilenameOnError.pfeEmpty">
<short>
Causes the missing file name to be ignored.
</short>
</element>
<element name="TPhysicalFilenameOnError.pfeOriginal">
<short>
Causes the original (missing) file name to be retained.
</short>
</element>

<element name="GetPhysicalFilename">
<short>
Gets the physical file name for a symbolic link on the local file system.
</short>
<descr>
<p>
<var>GetPhysicalFilename</var> is a <var>String</var> function used to get 
the physical file name on the local file system for the specified symbolic 
link.
</p>
<p>
<var>Filename</var> contains the symbolic link to resolve in the function.
</p>
<p>
<var>OnError</var> is a <var>TPhysicalFilenameOnError</var> enumeration value 
that indicates the action performed if a physical file name cannot be 
determined for the symbolic link. When OnError contains <b>pfeException</b>, 
an exception is raised for the unresolved file name. When OnError contains 
<b>pfeOriginal</b>, the unresolved symlink is used as the return value.
</p>
<p>
The implementation of GetPhysicalFilename is platform- or OS-dependent. For 
UNIX-like environments (which support symbolic links), the 
<var>GetUnixPhysicalFilename</var> 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.
</p>
</descr>
<seealso>
<!-- link id="GetUnixPhysicalFilename"/ -->
</seealso>
</element>
<element name="GetPhysicalFilename.Result">
<short>Physical file name for the resolved symbolic link.</short>
</element>
<element name="GetPhysicalFilename.Filename">
<short>File name examined in the function.</short>
</element>
<element name="GetPhysicalFilename.OnError">
<short>
Indicates the action performed for a symbolic link that cannot be resolved to 
a physical file name.
</short>
</element>

<element name="GetUnixPhysicalFilename">
<short>
Resolves the symlink in Filename including omitted directories.
</short>
<descr>
<p>
If a symlink can not be resolved, and ExceptionOnError is <b>False</b>, the 
function returns an empty string (<b>''</b>). If ExceptionOnError is 
<b>True</b>, it raises an EFOpenError exception with a message containing 
more details.
</p>
<p>
GetUnixPhysicalFilename is used to implement the GetPhysicalFilename function 
for UNIX-like environments.
</p>
</descr>
<seealso>
<link id="GetPhysicalFilename"/>
</seealso>
</element>
<element name="GetUnixPhysicalFilename.Result">
<short>Physical file name for the resolved symbolic link.</short>
</element>
<element name="GetUnixPhysicalFilename.Filename">
<short>File name (or symlink) examined in the function.</short>
</element>
<element name="GetUnixPhysicalFilename.ExceptionOnError">
<short>
Indicates if an exception is raised for a symbolic link that cannot be 
resolved to a physical file name.
</short>
</element>

<element name="GetAppConfigDirUTF8">
<short>
Gets the directory for application configuration and data files.
</short>
<descr>
<p>
<var>GetAppConfigDirUTF8</var> is a <var>String</var> function used to get 
the directory on the local file system where application configuration and 
data files are stored.
</p>
<p>
<var>Global</var> is a <var>Boolean</var> argument that determines if the 
directory is user- or system- specific. When Global contains <b>False</b>, 
the home directory for the user is used as the path in the return value.
</p>
<p>
<var>Create</var> is a <var>Boolean</var> argument that indicates if the 
configuration directory should be created if not already present on the local 
file system.
</p>
<p>
The implementation of GetAppConfigDirUTF8 is platform- and/or OS-specific.
</p>
<p>
For the Amiga platform, the <var>GetAppConfigDir</var> in the 
<file>SysUtils</file> unit is called to get the return value.
</p>
<p>
For Windows environments, the <var>SHGetFolderPathUTF8</var> function is 
called to get the path information. The <b>CSIDL</b> (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 <var>DGetAppConfigDir</var> is used 
as the directory path.
</p>
<p>
For UNIX-like environments, the <var>GetAppConfigDir</var> function in the 
<file>SysUtils</file> unit is called to get the path information.
</p>
<p>
If the directory does not exist and Create contains <b>True</b>, the 
<var>ForceDirectoriesUTF8</var> routine is called to create any missing 
directories for the path. An <var>EInOutError</var> exception is raised if 
any missing directory in the path cannot be created.
</p>
<p>
GetAppConfigDirUTF8 is used in the implementation of the Lazarus IDE and help 
viewer (LHelp).
</p>
</descr>
<seealso>
<link id="ForceDirectoriesUTF8"/>
<link id="#rtl.sysutils.GetAppConfigDir">GetAppConfigDir</link>
</seealso>
</element>
<element name="GetAppConfigDirUTF8.Result">
<short>
Path to the directory used for application configuration or data files.
</short>
</element>
<element name="GetAppConfigDirUTF8.Global">
<short>
Indicates if the system-wide (not user specific) directory is used.
</short>
</element>
<element name="GetAppConfigDirUTF8.Create">
<short>
Indicates if missing directories in the path should be created.
</short>
</element>

<element name="GetAppConfigFileUTF8">
<short>
Gets a UTF-8-encoded configuration file name for the current application.
</short>
<descr>
<p>
<var>GetAppConfigFileUTF8</var> is a <var>String</var> function used to get a 
UTF-8-encoded configuration file name for the current application. 
GetAppConfigFileUTF8 calls the <var>GetAppConfigFile</var> function in the 
<file>SysUtils</file> unit to get the return value for the function. 
<var>SysToUTF8</var> is called for the file name to ensure that it is encoded 
using the UTF-8 encoding scheme.
</p>
<p>
<var>Global</var> is a <var>Boolean</var> which indicates whether system- or 
user-specific path information is used in the configuration file name. When 
Global contains <b>True</b>, the system-wide configuration path is used in 
the return value. Otherwise, a user-specific path is used in the return value.
</p>
<p>
<var>SubDir</var> is a <var>Boolean</var> value that indicates if a 
sub-directory for the application is included in the path for the 
configuration file. When SubDir is <b>True</b>, a "Config" sub-directory is 
included in the path information.
</p>
<p>
<var>CreateDir</var> is a <var>Boolean</var> argument that indicates if any 
missing directories in the configuration file path are created in the 
function. When CreateDir is <b>False</b>, no additional actions are performed 
in the function. Otherwise, the path information is passed to 
<var>ForceDirectoriesUTF8</var> to create any missing directories. If any of 
the directories are not successfully created, an <var>EInOutError</var> 
exception is raised with the message in 
<var>lrsUnableToCreateConfigDirectoryS</var>.
</p>
<p>
The return value contains the path to the configuration file including the 
requested path, configuration file name, and configuration file extension.
</p>
</descr>
<errors>
Raises an EInOutError exception when directories in the path cannot be 
created on the local file system.
</errors>
<seealso>
<link id="ForceDirectoriesUTF8"/>
<link id="#rtl.sysutils.GetAppConfigFile">GetAppConfigFile</link>
<link id="#lazutils.lazutf8.SysToUTF8">SysToUTF8</link>
</seealso>
</element>
<element name="GetAppConfigFileUTF8.Result">
<short>Path to the configuration file for the application.</short>
</element>
<element name="GetAppConfigFileUTF8.Global">
<short>
Indicates if system-wide settings are used in the configuration file name.
</short>
</element>
<element name="GetAppConfigFileUTF8.SubDir">
<short>
Indicates if a directory for the application is included in the configuration 
file name.
</short>
</element>
<element name="GetAppConfigFileUTF8.CreateDir">
<short>
Indicates if missing directories in the configuration file path are created.
</short>
</element>

<element name="GetTempFileNameUTF8">
<short>
Gets a temporary file name using the specified UTF-8-encoded path and prefix.
</short>
<descr>
<p>
<var>GetTempFileNameUTF8</var> is a <var>String</var> function used to get a 
temporary file name with the specified prefix located in the specified 
directory.
</p>
<p>
<var>Dir</var> contains the path on the local file system where the temporary 
file should be located.
</p>
<p>
<var>Prefix</var> contains the prefix for the temporary file name. In other 
words, the temporary file name must start with this sequence of characters.
</p>
<p>
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:
</p>
<code>
/usr/tmp/TMP0.tmp
</code>
<p>
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.
</p>
</descr>
<seealso/>
</element>
<element name="GetTempFileNameUTF8.Result">
<short>Temporary file name generated in the routine.</short>
</element>
<element name="GetTempFileNameUTF8.Dir">
<short>Directory path for the temporary file name.</short>
</element>
<element name="GetTempFileNameUTF8.Prefix">
<short>Prefix for the temporary file name.</short>
</element>

<element name="IsUNCPath">
<short>
Indicates if the specified path uses Universal Naming Convention (UNC).
</short>
<descr>
<p>
<var>IsUNCPath</var> is a <var>Boolean</var> function which indicates is the 
specified path uses Universal Naming Convention (UNC).
</p>
<p>
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:
</p>
<code>
\\C:\directory\
\\?\C:\directory\
\\?\UNC\volume\directory\
</code>
<p>
For UNIX-like environments, as well as the Amiga platform, the return value 
is always <b>False</b>. UNC paths are not used on those platforms.
</p>
<p>
Use ExtractUNCVolume to get host and path information from a file name 
expressed using UNC notation.
</p>
</descr>
<seealso/>
</element>
<element name="IsUNCPath.Result">
<short><b>True</b> when the path contains UNC notation.</short>
</element>
<element name="IsUNCPath.Path">
<short>Path examined in the function.</short>
</element>

<element name="ExtractUNCVolume">
<short>Gets UNC host and volume name used in the specified path.</short>
<descr>
<p>
<var>ExtractUNCVolume</var> is a <var>String</var> 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.
</p>
<p>
The return value contains information needed to access shared resources by 
their host and volume names, and contains one of the following formats:
</p>
<code>
\\server-name\shared-resource-path-name\
\\mypc\nas-drive\
\\?\c:\
\\?\UNC\c:\
</code>
<p>
ExtractUNCVolume calls the <var>IsUNCPath</var> function to determine if the 
value in <var>Path</var> starts with the UNC naming delimiters. The return 
value is an empty string (<b>''</b>), and no additional actions are performed 
in the function, when Path does not use UNC notation.
</p>
<p>
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 <b>'\\?\'</b> or <b>'\\?\UNC\'</b> 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 
<b>'\\mypc\nas-drive\'</b>.
</p>
</descr>
<seealso>
<link id="IsUncPath"/>
</seealso>
</element>
<element name="ExtractUNCVolume.Result">
<short>UNC host and volume name extracted from the specified path.</short>
</element>
<element name="ExtractUNCVolume.Path">
<short>Path information examined in the function.</short>
</element>

<element name="ExtractFileRoot">
<short>
Gets the root drive/path/directory for the specified file name.
</short>
<descr>
<p>
<var>ExtractFileRoot</var> is a <var>String</var> 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.
</p>
<p>
When FileName uses Universal Naming Convention (UNC), the return value will 
contain any server and share/volume information included in the parameter. 
For example:
</p>
<code>
\\server-name\share-name\
\\?\C:\
</code>
<p>
For UNIX-like environments (as well as WinCE), an initial path delimiter 
marks the root directory in the file system.
</p>
<p>
For the Amiga platform, any characters in FileName up to (but not including) 
the first ":" character are used as the root directory.
</p>
<p>
For the Windows platform, a drive designation up to and including the first 
path delimiter are used as the root directory. For example:
</p>
<code>
C:\
</code>
</descr>
<seealso/>
</element>
<element name="ExtractFileRoot.Result">
<short>Root directory on the file system for the specified file name.</short>
</element>
<element name="ExtractFileRoot.FileName">
<short>File name examined in the routine.</short>
</element>

<element name="GetDarwinSystemFilename">
<short>
Gets a file name using the Core Foundation CFStringGetFileSystemRepresentation 
API on macOS.
</short>
<descr>
<p>
Implemented when the platform or OS includes the <b>darwin</b> compiler 
define. Used in the implementation of TryCreateRelativePath for the Darwin 
platform.
</p>
</descr>
<seealso/>
</element>
<element name="GetDarwinSystemFilename.Result">
<short>
UTF-8-encoded file name from the Core Foundation API.
</short>
</element>
<element name="GetDarwinSystemFilename.Filename">
<short>
File name converted in the routine.
</short>
</element>

<element name="GetDarwinNormalizedFilename">
<short>
Gets a normalized file name using the Core Foundation CFStringNormalizationForm 
API on macOS.
</short>
<descr>
<p>
Normalizes the string in FileName into the specified form as described in 
Unicode Technical Report #15. Supported normalization forms include 
Compatibility Decomposition, and Canonical Decomposition followed by Canonical 
Composition (default).
</p>
<p>
Implemented when the platform or OS includes the <b>darwin</b> compiler 
define. Handles canonical string normalization forms for file names on the 
Darwin platform.
</p>
</descr>
<seealso/>
</element>
<element name="GetDarwinNormalizedFilename.Result">
<short>
UTF-8-encoded value for the normalized file name.
</short>
</element>
<element name="GetDarwinNormalizedFilename.Filename">
<short>
File name normalized in the routine.
</short>
</element>
<element name="GetDarwinNormalizedFilename.nForm">
<short>
Normalization form requested in the routine. Default value is 2 (Canonical 
Decomposition followed by Canonical Composition).
</short>
</element>

<element name="SHGetFolderPathUTF8">
<short>
Works like the WinAPI function SHGetFolderPathW, but returns a UTF-8-encoded 
string.
</short>
</element>
<element name="SHGetFolderPathUTF8.Result">
<short>UTF-8-encoded folder path for the identifier.</short>
</element>
<element name="SHGetFolderPathUTF8.ID">
<short>Identifier resolved in the function.</short>
</element>

<element name="SplitCmdLineParams">
<short>
Splits command line parameters separated by whitespace characters into the 
specified TStrings instance.
</short>
<descr>
<p>
Parameters are separated by one or more whitespace characters 
(#9,#10,#13,#32). Quoted values are parsed as a single parameter. If 
ReadBackslash contains <b>True</b>, then <var>\"</var> is replaced with 
<var>"</var> and not treated as a quoted value. #0 is always treated as the 
end of the Parameters value.
</p>
</descr>
</element>
<element name="SplitCmdLineParams.Params">
<short>Whitespace-delimited list of parameters handled in the routine.</short>
</element>
<element name="SplitCmdLineParams.ParamList">
<short>List where the separates parameters are stored.</short>
</element>
<element name="SplitCmdLineParams.ReadBackslash">
<short>
Indicates if backslash characters are consumed and removed in the routine.
</short>
</element>

<element name="StrToCmdLineParam">
<short>
Ensures that whitespace and quoting in the specified string are valid for 
use in command line parameters.
</short>
<descr>
<p>
The following actions are performed for values in the Param argument:
</p>
<ul>
<li>
An empty string is converted to ''.
</li>
<li>
Values separated by space characters are enclosed by Quote (') characters.
</li>
<li>
An existing Quote (') character causes the value to be enclosed by Double 
Quote (") characters.
</li>
<li>
An existing Double Quote character causes a value to be enclosed by Quote 
characters.
</li>
<li>
A null byte (#0) causes the remainder of the Param value to be discarded.
</li>
</ul>
</descr>
<seealso/>
</element>
<element name="StrToCmdLineParam.Result">
<short>
Value after normalizing whitespace and quote characters in the command line 
parameter.
</short>
</element>
<element name="StrToCmdLineParam.Param">
<short>Command line parameter examined in the function.</short>
</element>

<element name="MergeCmdLineParams">
<short>
Generates a string with the specified list of parameters.
</short>
<descr>
<p>
<var>MergeCmdLineParams</var> is a <var>String</var> function used to convert 
parameter values in the ParamList argument to a normalized string using the 
quoting needed for the parameter values.
</p>
<p>
MergeCmdLineParams iterates over the string values in ParamList, and calls 
StrToCmdLineParam to normalize the whitespace and quoting in each value. The 
sanitized parameters values are concatenated together, using the Space (' ') 
as the delimiter between the parameter values, and used as the return value 
for the function.
</p>
<p>
No actions are performed in the routine when ParamList is unassigned (Nil) 
or its Count property is 0 (zero).
</p>
</descr>
<seealso>
<link id="StrToCmdLineParam"/>
</seealso>
</element>
<element name="MergeCmdLineParams.Result">
<short>String representation for the list of parameters.</short>
</element>
<element name="MergeCmdLineParams.ParamList">
<short>
TStrings instance with the parameter values handled in the function.
</short>
</element>

<element name="SplitCmdLine">
<short>
Splits the specified command line into program and parameter values.
</short>
<descr>
<p>
SplitCmdLine is a routine used to separate values found in the CmdLine 
argument into the ProgamFilename and Params arguments. Outer single and 
double quote characters found in the CmdLine argument are removed in the 
method.
</p>
<p>
No actions are performed in the routine when CmdLine is an empty string (''); 
the output parameters are set to empty string values as well.
</p>
</descr>
<seealso/>
</element>
<element name="SplitCmdLine.CmdLine">
<short>Command line examined in the function.</short>
</element>
<element name="SplitCmdLine.ProgramFilename">
<short>Executable name found in the command line.</short>
</element>
<element name="SplitCmdLine.Params">
<short>Parameters found in the command line.</short>
</element>

<element name="PrepareCmdLineOption">
<short>
Ensures command line options are properly quoted (when needed).
</short>
<descr/>
<seealso/>
</element>
<element name="PrepareCmdLineOption.Result">
<short>Command line option after quoting has been applied.</short>
</element>
<element name="PrepareCmdLineOption.Option">
<short>Command line option examined in the function.</short>
</element>

<element name="TInvalidateFileStateCacheEvent">
<short>
Specifies the event signalled for an invalid file state in the file cache.
</short>
<descr>
<p>
<var>TInvalidateFileStateCacheEvent</var> is the type which specifies the 
event signalled for an invalid file state in the file cache. 
TInvalidateFileStateCacheEvent is the type used for the 
<var>OnInvalidateFileStateCache</var> event handler signalled in the 
<var>InvalidateFileStateCache</var> procedure.
</p>
</descr>
<seealso>
<link id="OnInvalidateFileStateCache"/>
<link id="InvalidateFileStateCache"/>
</seealso>
</element>

<element name="TInvalidateFileStateCacheEvent.Filename">
<short>File name for the event notification.</short>
</element>

<element name="OnInvalidateFileStateCache">
<short>
Implements the event handler for a file with an invalid file state.
</short>
<descr>
<p>
<var>OnInvalidateFileStateCache</var> is a 
<var>TInvalidateFileStateCacheEvent</var> 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.
</p>
<p>
OnInvalidateFileStateCache is significant for UNIX-like environments only, 
such as Linux and Amiga. OnInvalidateFileStateCache is not used in Windows 
environments.
</p>
</descr>
<seealso>
<link id="TInvalidateFileStateCacheEvent"/>
</seealso>
</element>

<element name="InvalidateFileStateCache">
<short>
Signals the OnInvalidateFileStateCache event handler.
</short>
<descr>
<p>
<var>InvalidateFileStateCache</var> is a procedure used to signal the 
<var>OnInvalidateFileStateCache</var> 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:
</p>
<ul>
<li>DeleteFileUTF8</li>
<li>FileSetAttrUTF8</li>
<li>FileSetDateUTF8</li>
<li>RenameFileUTF8</li>
</ul>
<p>
InvalidateFileStateCache is significant for UNIX-like environments only, such 
as Linux and Amiga. InvalidateFileStateCache is not used for the Windows 
platform.
</p>
</descr>
<seealso>
<link id="DeleteFileUTF8"/>
<link id="FileSetAttrUTF8"/>
<link id="FileSetDateUTF8"/>
<link id="RenameFileUTF8"/>
</seealso>
</element>
<element name="InvalidateFileStateCache.Filename">
<short>File name for the event notification.</short>
</element>

<element name="GetLazNormalizedFilename">
<short>Gets a normalized form of the Filename.</short>
<descr>
<p>
<var>GetLazNormalizedFilename </var> returns a normalized string for the filename 
for non-representative purposes (e.g. comparison). The normalization is platform- 
and/or OS-specific. It considers whether the file system is case sensitive or when 
UTF-8 encoding is supported.
</p>
</descr>
</element>
<element name="GetLazNormalizedFilename.Filename">
<short>File name examined in the routine.</short>
</element>
<element name="GetLazNormalizedFilename.Result">
<short>
File name after case conversion or composition / decomposition for the platform or OS.
</short>
</element>

</module>
<!-- LazFileUtils -->
</package>
</fpdoc-descriptions>