mirror of
https://gitlab.com/freepascal.org/lazarus/lazarus.git
synced 2025-05-01 16:23:42 +02:00
2816 lines
134 KiB
XML
2816 lines
134 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<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><0</dt>
|
|
<dd>Filename1 comes before Filename2</dd>
|
|
<dt>0</dt>
|
|
<dd>Filename1 and Filename2 to have the same value</dd>
|
|
<dt>>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><0</dt>
|
|
<dd>Filename1 comes before Filename2</dd>
|
|
<dt>0</dt>
|
|
<dd>Filename1 and Filename2 to have the same value</dd>
|
|
<dt>>0</dt>
|
|
<dd>Filename1 comes after Filename2</dd>
|
|
</dl>
|
|
</descr>
|
|
<errors/>
|
|
<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>
|
|
Performs a sort order comparison for the specified file name and extension.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>CompareFileExt</var> is an <var>Integer</var> function used to compare the file extension in Filename to the value in Ext. Ext may contain the '.' character, but it is not required and will be removed for the comparison. CaseSensitive indicates whether case is ignored in the comparison. When CaseSensitive contains True, CompareStr is called to perform the comparison. Otherwise, UTF8CompareText is called to compare the values. The return value will contain one of the following:
|
|
</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 is 1 if Filename does not contain a file extension.
|
|
</p>
|
|
</descr>
|
|
<errors/>
|
|
<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>True 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 determines 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 used 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>True 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 used 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>True 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>True 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>
|
|
<errors>
|
|
</errors>
|
|
<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>True 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>True 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>True 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>True 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 False
|
|
</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>True 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>True 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>True 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>True 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>True 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>True 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>False 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>
|
|
<errors/>
|
|
<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>
|
|
</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 '/..'), an additional path delimiter is added to the return value.
|
|
</p>
|
|
<p>
|
|
If a relative path reference cannot be resolved for the local file system, the original path information is retained.
|
|
</p>
|
|
<p>
|
|
Macros found in the AFilename are retained if the relative path references a parent directory. For example:
|
|
</p>
|
|
<code>
|
|
'($LazarusDir)/../path/that/may/be/invalid/for/macro/filename.ext'
|
|
</code>
|
|
</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 the path in Source.</short>
|
|
<descr>
|
|
<p>
|
|
Returns <b>True</b> if it is possible to create a relative path from Source to Dest Function must be thread safe, so no expanding of filenames is done, since this is not thread-safe (at least on Windows platform).
|
|
</p>
|
|
<ul>
|
|
<li>Dest and Source must either be both absolute filenames, or relative</li>
|
|
<li>Dest and Source cannot contain '..' since no expanding 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 Result is <b>True</b> then if RelPath is Empty string, RelPath becomes '.'</li>
|
|
<li>If AlwaysRequireSharedBaseFolder is <b>False</b> then Absolute filenames need not share a basefolder</li>
|
|
<li>if the function succeeds RelPath contains the relative path from Source to Dest,
|
|
no PathDelimiter is appended to the end of RelPath</li>
|
|
</ul>
|
|
<p>
|
|
Examples:
|
|
</p>
|
|
<code>
|
|
- Dest = /foo/bar Source = /foo Result = <b>True</b> RelPath = bar
|
|
- Dest = /foo///bar Source = /foo// Result = <b>True</b> RelPath = bar
|
|
- Dest = /foo Source = /foo/bar Result = <b>True</b> RelPath = ../
|
|
- Dest = /foo/bar Source = /bar Result = <b>True</b> RelPath = ../foo/bar
|
|
- Dest = foo/bar Source = foo/foo Result = <b>True</b> RelPath = ../bar
|
|
- Dest = foo/bar Source = bar/foo Result = <b>False</b> (no shared base directory)
|
|
- Dest = /foo Source = bar Result = <b>False</b> (mixed absolute and relative)
|
|
- Dest = c:foo Source = c:bar Result = <b>False</b> (no expanding)
|
|
- Dest = c:\foo Source = d:\bar Result is <b>False</b> (different drives)
|
|
- Dest = \foo Source = foo (Windows) Result is <b>False</b> (too ambiguous to guess what this should mean)
|
|
- Dest = /foo Source = /bar AlwaysRequireSharedBaseFolder = <b>True</b> Result = False
|
|
- Dest = /foo Source = /bar AlwaysRequireSharedBaseFolder = <b>False</b> Result = <b>True</b> RelPath = ../foo
|
|
</code>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="TryCreateRelativePath.Result">
|
|
<short/>
|
|
</element>
|
|
<element name="TryCreateRelativePath.Dest">
|
|
<short/>
|
|
</element>
|
|
<element name="TryCreateRelativePath.Source">
|
|
<short/>
|
|
</element>
|
|
<element name="TryCreateRelativePath.UsePointDirectory">
|
|
<short/>
|
|
</element>
|
|
<element name="TryCreateRelativePath.AlwaysRequireSharedBaseFolder">
|
|
<short/>
|
|
</element>
|
|
<element name="TryCreateRelativePath.RelPath">
|
|
<short/>
|
|
</element>
|
|
|
|
<element name="CreateRelativePath">
|
|
<short>
|
|
Creates a 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 False, 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/>
|
|
</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: '/usr/lib/fpc'.
|
|
</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 False. 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>True 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>True 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>
|
|
<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 at run-time.
|
|
</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>
|
|
<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.
|
|
</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 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 Path. The return value includes the value in Path and the trailing path delimiter (when needed).
|
|
</p>
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="AppendPathDelim.Result">
|
|
<short>Path value with a trailing path delimiter.</short>
|
|
</element>
|
|
<element name="AppendPathDelim.Path">
|
|
<short>Path value to examine.</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>True 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 True.
|
|
</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 True.
|
|
</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>
|
|
<var>CreateAbsoluteSearchPath</var> - 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 calls 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 delimiters 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>True 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>True 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>
|
|
<errors/>
|
|
<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>
|
|
<errors/>
|
|
<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 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>True 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>
|
|
<errors/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="RenameFileUTF8.Result">
|
|
<short>True 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>True 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>True 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>True 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>True 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 specified directories if they do not already exist.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
<var>ForceDirectories</var> is a <var>Boolean</var> function which creates the specified directories if they do not already exist. ForceDirectories examines the value in Dir to determine if it contains a Windows device identifier or a UNC name. If a device identifier or UNC name is found, but not supported on the platform, no actions are performed in the function.
|
|
</p>
|
|
<p>
|
|
ForceDirectories raises an <var>EInOutError</var> exception with the message in <var>SCannotCreateEmptyDir</var> when Dir contains an empty string ('').
|
|
</p>
|
|
<p>
|
|
Each directory in the specified path is checked using <var>DirectoryExistsUTF8</var>. ForceDirectories calls <var>CreateDirUTF8</var> if a directory does not already exist, and may exit with a return value of <b>False</b> if directory creation is not successful. 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>
|
|
<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="ForceDirectory"/>
|
|
</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>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>
|
|
<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.
|
|
</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>
|
|
GetFileDescription is a String function used to get descriptive information for the file name specified in AFilename. The return value contains file information appropriate to the platform, environment, or file system. The implementation of GetFileDescription and the content of the return value are platform- or OS-specific.
|
|
</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. It does not resolve symbolic links in parent (or ancestor) directories. If a symlink cannot be resolved, and ExceptionOnError is False, the function returns an empty string (''). If ExceptionOnError is True, it raises an EFOpenError with a message, containing more details. For the Windows platform, it simply returns the value in the Filename argument.
|
|
</p>
|
|
</descr>
|
|
</element>
|
|
|
|
<element name="TryReadAllLinks">
|
|
<short>
|
|
Resolves a symlink to the real file.
|
|
</short>
|
|
<descr>
|
|
<p>
|
|
If a symlink can not be resolved it returns Filename. It calls the ReadAllLinks function.
|
|
</p>
|
|
</descr>
|
|
</element>
|
|
|
|
<element name="GetShellLinkTarget">
|
|
<short>Resolve 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>Displays information for file attributes in the debugger.</short>
|
|
<descr>
|
|
<p>
|
|
Attr 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. TPhysicalFilenameOnError includes the following enumeration values and meanings:
|
|
</p>
|
|
<dl>
|
|
<dt>pfeException</dt>
|
|
<dd>
|
|
Causes an exception to be raised for the missing file name.
|
|
</dd>
|
|
<dt>pfeEmpty</dt>
|
|
<dd>
|
|
Causes the missing file name to be ignored.
|
|
</dd>
|
|
<dt>pfeOriginal</dt>
|
|
<dd>
|
|
Causes the original (missing) file name to be retained.
|
|
</dd>
|
|
</dl>
|
|
<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 False, 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 True, 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 False. 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>True 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 specifier examined in the routine.</short>
|
|
</element>
|
|
|
|
<element name="GetDarwinSystemFilename">
|
|
<short/>
|
|
<descr>
|
|
Implemented when the platform or OS includes the <b>darwin</b> compiler define. Used in the implementation of TryCreateRelativePath for the Darwin platform.
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="GetDarwinSystemFilename.Result">
|
|
<short/>
|
|
</element>
|
|
<element name="GetDarwinSystemFilename.Filename">
|
|
<short/>
|
|
</element>
|
|
|
|
<element name="GetDarwinNormalizedFilename">
|
|
<short/>
|
|
<descr>
|
|
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.
|
|
</descr>
|
|
<seealso/>
|
|
</element>
|
|
<element name="GetDarwinNormalizedFilename.Result">
|
|
<short/>
|
|
</element>
|
|
<element name="GetDarwinNormalizedFilename.Filename">
|
|
<short/>
|
|
</element>
|
|
<element name="GetDarwinNormalizedFilename.nForm">
|
|
<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.
|
|
</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 True, 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 parameter names and values 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 use the format required for command line parameters.
|
|
</short>
|
|
<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/>
|
|
<seealso/>
|
|
</element>
|
|
<element name="MergeCmdLineParams.Result">
|
|
<short>String representation for the list of parameters.</short>
|
|
</element>
|
|
<element name="MergeCmdLineParams.ParamList">
|
|
<short>Parameter names and values handled in the function.</short>
|
|
</element>
|
|
|
|
<element name="SplitCmdLine">
|
|
<short>Splits the specified command line into program and parameter values.</short>
|
|
<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>List of parameters and values found in the command line.</short>
|
|
</element>
|
|
|
|
<element name="PrepareCmdLineOption">
|
|
<short>Ensures command line options are formatted properly.</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>
|
|
|
|
</module>
|
|
<!-- LazFileUtils -->
|
|
</package>
|
|
</fpdoc-descriptions>
|