FileAccess Chilkat2 Perl Reference Documentation
Chilkat2::FileAccess
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.FileAccess
Load or save text and binary files, append data, replace file contents,
and work with explicit character encodings when needed.
Copy, rename, delete, compare, split, reassemble, and inspect files using
straightforward file-system utility methods.
Create, remove, check, and work with directories, and use path helpers to
extract filenames, extensions, directory names, and related path parts.
Open files for lower-level reading or writing, seek within files, read
blocks, and process large files without loading everything at once.
Get or set file times, inspect sizes and existence, and use metadata
helpers when coordinating file processing workflows.
Generate temporary filenames, work with symbolic links, scan for byte
fragments, and perform text replacement in files.
For an extended overview, see
FileAccess Class Overview.
Read, write, compare, copy, split, inspect, and manage files and paths.
Chilkat.FileAccess provides general-purpose file-system
utilities for applications that need direct control over files, directories,
paths, timestamps, and low-level file operations. It can read, write, append,
seek, compare, copy, rename, delete, split, reassemble, and inspect files,
and also includes helpers for directory operations, path parsing, symbolic
links, temporary filenames, block-based reading, fragment scanning, text
replacement, and open-file access.
Read and write files
File management
Directories and paths
Open-file operations
Timestamps and metadata
Special file utilities
FileAccess for local file-system tasks that are outside the
scope of a specific protocol class. It is especially useful for preparing
files before upload, saving downloaded data, comparing or splitting files,
reading large files in blocks, manipulating paths, or performing small
filesystem operations without using platform-specific APIs.
Object Creation
use Chilkat2;
my $fileAccess = Chilkat2::FileAccess->new;
# or set properties (and RaiseError) at creation:
# my $fileAccess = Chilkat2::FileAccess->new(VerboseLogging => 1, RaiseError => 1);Creates the object. The optional pairs set writable properties (and RaiseError) in order, as if set one by one; an unknown or read-only name croaks. use Chilkat2; loads every class; the Chilkat2/FileAccess.pm file holds only this class's documentation (perldoc Chilkat2::FileAccess).
Perl frees the object when its last reference goes (undef $fileAccess, or the variable going out of scope); there is nothing to close. Objects returned by methods are independent and freed the same way. The class may be subclassed (use parent -norequire, 'Chilkat2::FileAccess';): an object is a blessed hash reference whose hash is free for the subclass's own fields.
When false (the default), a method that fails returns false (or undef), and the reason is in LastErrorText. When true, it dies with a Chilkat2::Error instead, as DBI does with its RaiseError. Objects returned by a method inherit the value of the object that returned them.
Errors
A Chilkat2::Error stringifies to the failed call's full LastErrorText, and has the methods text, class ('Chilkat2::FileAccess'), method (the method name) and object. Methods that look something up and find nothing return undef without dying (each such method says so), methods that answer a question (HasMember, IsUnlocked, ...) return a plain boolean, and property reads and writes never fail for Chilkat reasons.
Misuse always croaks, with your file and line, whatever RaiseError is: a wrong number of arguments, a reference or undef where a string or number is expected, an object of the wrong class, an out-of-range integer, a string containing a NUL character, a wide character in a byte string, or a write to a read-only property.
Strings are Perl character strings in both directions (length, regexes and :encoding layers see characters); binary data (BinData) is a byte string. Unlocking: call Chilkat2::Global->new->UnlockBundle('...') once at startup.
Properties
CurrentDir
my $strVal = $fileAccess->CurrentDir;
Returns the current working directory of the calling process. Relative file and directory paths are resolved against this process-wide working directory.
FileAccess object. Changing it can therefore affect relative-path behavior elsewhere in the application.DebugLogFilePath
my $strVal = $fileAccess->DebugLogFilePath;
$fileAccess->DebugLogFilePath($strVal);
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
EndOfFile
my $boolVal = $fileAccess->EndOfFile;
Returns 1 when the currently open file is positioned at end-of-file; otherwise returns 0.
OpenForRead, OpenForWrite, OpenForReadWrite, OpenForAppend, or FileOpen.FileOpenError
my $intVal = $fileAccess->FileOpenError;
Provides the detailed open-error code from the most recent call to FileOpen, OpenForRead, OpenForWrite, OpenForReadWrite, or OpenForAppend.
| Code | Meaning |
|---|---|
0 | Success; no open error. |
1 | Access denied. |
2 | File not found. |
3 | General, non-specific open error. |
4 | File already exists. |
5 | The path refers to a directory and the requested access involves writing. |
6 | Too many symbolic links were encountered while resolving the path. |
7 | The process already has the maximum number of files open. |
8 | The pathname is too long. |
9 | The system-wide limit on open files has been reached. |
10 | The pathname refers to a device special file for which no corresponding device exists. |
11 | Insufficient kernel memory was available. |
12 | A file was to be created, but the containing device has no space available. |
13 | A pathname component expected to be a directory is not a directory. |
14 | The regular file is too large to be opened because of an operating-system limitation. |
15 | The path is on a read-only filesystem and write access was requested. |
FileOpenError is useful for programmatic handling; FileOpenErrorMsg provides the corresponding human-readable message.FileOpenErrorMsg
my $strVal = $fileAccess->FileOpenErrorMsg;
Returns the human-readable message corresponding to FileOpenError for the most recent file-open attempt.
LastErrorHtml
my $strVal = $fileAccess->LastErrorHtml;
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
my $strVal = $fileAccess->LastErrorText;
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
my $strVal = $fileAccess->LastErrorXml;
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
my $boolVal = $fileAccess->LastMethodSuccess;
$fileAccess->LastMethodSuccess($boolVal);
Indicates the success or failure of the most recent method call: 1 means success, 0 means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
LockFileOnOpen
my $boolVal = $fileAccess->LockFileOnOpen;
$fileAccess->LockFileOnOpen($boolVal);
Windows only. If 1, OpenForAppend, OpenForRead, OpenForReadWrite, and OpenForWrite request exclusive access to the file. Other processes are prevented from opening the file until FileClose releases the handle. The default is 0.
OpenFor* method.VerboseLogging
my $boolVal = $fileAccess->VerboseLogging;
$fileAccess->VerboseLogging($boolVal);
If set to 1, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is 0. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
Version
my $strVal = $fileAccess->Version;
Methods
AppendAnsi
# $success is true or false
my $success = $fileAccess->AppendAnsi($text);
Appends text to the currently open file after converting the string to the legacy ANSI character encoding used by Chilkat for the platform.
AppendText or AppendSb when an explicit encoding such as utf-8 is preferred.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AppendBd
Appends all bytes contained in bd to the currently open file without text conversion.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AppendSb
# $charset is a string
# $success is true or false
my $success = $fileAccess->AppendSb($sb, $charset);
Appends the text contained in sb to the currently open file using the character encoding specified by charset.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AppendText
# $charset is a string
# $success is true or false
my $success = $fileAccess->AppendText($str, $charset);
Appends str to the currently open file after encoding the text with the character set named by charset, such as utf-8 or iso-8859-1.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AppendUnicodeBOM
my $success = $fileAccess->AppendUnicodeBOM();
Appends the UTF-16 little-endian byte-order mark to the currently open file. The two bytes written are FF FE.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
AppendUtf8BOM
my $success = $fileAccess->AppendUtf8BOM();
Appends the UTF-8 byte-order mark to the currently open file. The three bytes written are EF BB BF.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DirAutoCreate
# $success is true or false
my $success = $fileAccess->DirAutoCreate($filePath);
Ensures that the directory portion of filePath exists. Any missing parent directories are created; the final path component is treated as a filename and is not created as a directory.
DirAutoCreate when you have a file path. Use DirEnsureExists when the argument itself is a directory path.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DirCreate
# $success is true or false
my $success = $fileAccess->DirCreate($dirPath);
Creates the directory specified by dirPath. Parent directories must already exist; use DirEnsureExists when missing parent directories should also be created.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DirDelete
# $success is true or false
my $success = $fileAccess->DirDelete($dirPath);
Deletes the directory specified by dirPath. The directory must be empty; use TreeDelete to recursively delete a directory and its contents.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DirEnsureExists
# $success is true or false
my $success = $fileAccess->DirEnsureExists($dirPath);
Ensures that the complete directory path dirPath exists, creating missing directories along the path as needed.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
DirExists
# $flag is true or false
my $flag = $fileAccess->DirExists($dirPath);
Returns 1 if dirPath exists as a directory; otherwise returns 0.
Never dies: false is an answer, not a failure.
topFileClose
Closes the currently open file and releases its operating-system file handle. Any exclusive lock obtained through LockFileOnOpen is released at this time.
Returns the object, so calls can be chained.
topFileContentsEqual
# $filePath2 is a string
# $flag is true or false
my $flag = $fileAccess->FileContentsEqual($filePath1, $filePath2);
Compares filePath1 and filePath2 byte-for-byte and returns 1 only when their contents are identical. File sizes are compared first; when sizes match, the files are compared incrementally rather than being loaded entirely into memory.
Never dies: false is an answer, not a failure.
topFileCopy
# $newFilepath is a string
# $failIfExists is a boolean
# $success is true or false
my $success = $fileAccess->FileCopy($existingFilepath, $newFilepath, $failIfExists);
Copies existingFilepath to newFilepath. If failIfExists is 1 and the destination already exists, the copy fails instead of overwriting it.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FileDelete
# $success is true or false
my $success = $fileAccess->FileDelete($filePath);
Deletes the file specified by filePath.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FileExists
# $flag is true or false
my $flag = $fileAccess->FileExists($filePath);
Returns 1 if filePath exists; otherwise returns 0. Use FileExists3 when the application must distinguish "does not exist" from "could not determine because of an error."
Never dies: false is an answer, not a failure.
topFileExists3
# $n is an integer
my $n = $fileAccess->FileExists3($path);
Checks whether path exists and returns a three-state result: 1 if it exists, 0 if it does not exist, and -1 if Chilkat could not determine the result because of permissions or another filesystem error.
FileOpen
# $accessMode is an integer
# $shareMode is an integer
# $createDisposition is an integer
# $attributes is an integer
# $success is true or false
my $success = $fileAccess->FileOpen($filePath, $accessMode, $shareMode, $createDisposition, $attributes);
Windows-specific low-level open. Opens filePath using arguments modeled after the Win32 CreateFile API. For portable code, prefer OpenForRead, OpenForWrite, OpenForReadWrite, or OpenForAppend.
| Category | Common values |
|---|---|
| Access | GENERIC_READ = 0x80000000, GENERIC_WRITE = 0x40000000 |
| Sharing | FILE_SHARE_READ = 0x1, FILE_SHARE_WRITE = 0x2 |
| Disposition | CREATE_NEW=1, CREATE_ALWAYS=2, OPEN_EXISTING=3, OPEN_ALWAYS=4, TRUNCATE_EXISTING=5 |
FileOpenError and FileOpenErrorMsg for the reason.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FileReadBd
# $binData is a Chilkat2::BinData
# $success is true or false
my $success = $fileAccess->FileReadBd($maxNumBytes, $binData);
Reads up to maxNumBytes bytes from the current file position and appends the bytes to binData. The file position advances by the number of bytes read.
binData are preserved; newly read bytes are appended.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FileRename
# $newFilepath is a string
# $success is true or false
my $success = $fileAccess->FileRename($existingFilepath, $newFilepath);
Renames or moves existingFilepath to newFilepath using the local filesystem.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FileSeek
# $origin is an integer
# $success is true or false
my $success = $fileAccess->FileSeek($offset, $origin);
Moves the current file position by offset bytes relative to origin.
0 | Offset from the beginning of the file. |
1 | Offset from the current file position. |
2 | Offset from end-of-file; negative offsets are commonly used. |
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FileSize
# $n is an integer
my $n = $fileAccess->FileSize($filePath);
Returns the file size in bytes as a signed 32-bit integer.
0, which is the same as for an empty file. To detect failure, use FileSizeStr, which fails instead of returning a size, or check first with FileExists3.FileSize64 or FileSizeStr for large files.FileSize64
# $n is an integer
my $n = $fileAccess->FileSize64($filePath);
Returns the size of filePath in bytes as a signed 64-bit integer.
0, which is the same as for an empty file. To detect failure, use FileSizeStr, which fails instead of returning a size, or check first with FileExists3.FileSizeStr
# $str is a string or undef
my $str = $fileAccess->FileSizeStr($filePath);
Returns the size of filePath in bytes as a decimal string. This avoids the range limitation of a 32-bit integer return value.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
FileType
# $n is an integer
my $n = $fileAccess->FileType($path);
Examines path and classifies the filesystem entry.
-1 | Unable to determine because of permissions or another error. |
0 | Does not exist. |
1 | Regular file. |
2 | Directory. |
3 | Symbolic link. |
4 | Windows shortcut. |
99 | Another filesystem type. |
FileWriteBd
# $offset is an integer
# $numBytes is an integer
# $success is true or false
my $success = $fileAccess->FileWriteBd($binData, $offset, $numBytes);
Writes bytes from binData to the currently open file. offset selects the starting byte within the BinData; numBytes selects how many bytes to write. Set both to 0 to write the entire BinData, or set numBytes to 0 to write all remaining bytes beginning at offset.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GenBlockId
# $length is an integer
# $encoding is a string
# $str is a string or undef
my $str = $fileAccess->GenBlockId($index, $length, $encoding);
Generates a fixed-width decimal block identifier from index, padded to length characters, and then encodes those bytes using encoding (for example base64, hex, or ascii). This utility was originally added for block-oriented uploads such as Azure Blob block uploads.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetDirectoryName
# $str is a string or undef
my $str = $fileAccess->GetDirectoryName($path);
Returns the directory portion of path according to Chilkat path-parsing rules.
GetDirectoryName('C:\MyDir\MySubDir\myfile.ext') -> 'C:\MyDir\MySubDir\'
GetDirectoryName('C:\MyDir\MySubDir') -> 'C:\MyDir\'
GetDirectoryName('C:\') -> 'C:\'Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetExtension
# $str is a string or undef
my $str = $fileAccess->GetExtension($path);
Returns the filename extension portion of path, including the leading period. A period appearing only in a directory name is not treated as the file extension.
GetExtension('C:\mydir.old\myfile.ext') -> '.ext'
GetExtension('C:\mydir.old\') -> ''Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetFileName
# $str is a string or undef
my $str = $fileAccess->GetFileName($path);
Returns the final filename component of path, including its extension. If the path ends with a directory separator, the returned filename is empty.
GetFileName('C:\mydir\myfile.ext') -> 'myfile.ext'
GetFileName('C:\mydir\') -> ''Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetFileNameWithoutExtension
# $str is a string or undef
my $str = $fileAccess->GetFileNameWithoutExtension($path);
Returns the final filename component of path with its extension removed. If path ends with a directory separator, the returned value is empty.
GetFileNameWithoutExtension('C:\mydir\myfile.ext') -> 'myfile'
GetFileNameWithoutExtension('C:\mydir\') -> ''Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetFileTimeStr
# $which is an integer
# $str is a string or undef
my $str = $fileAccess->GetFileTimeStr($path, $which);
Returns one file timestamp as an ISO 8601 UTC string in the form YYYY-MM-DDTHH:MM:SSZ. The which argument selects 0 = last-modified, 1 = last-access, or 2 = creation.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
GetNumBlocks
# $n is an integer
my $n = $fileAccess->GetNumBlocks($blockSize);
Returns how many blockSize-byte blocks are required to cover the currently open file. A partial final block counts as one block. Returns 0 for an empty file and -1 if no file is open.
ceil(fileSize / blockSize) for a non-empty file.GetTempFilename
# $prefix is a string
# $str is a string or undef
my $str = $fileAccess->GetTempFilename($dirPath, $prefix);
Generates a temporary pathname in dirPath using prefix and a random alphanumeric suffix, in the general form prefix_xxxx.TMP. The returned pathname is guaranteed not to already exist at the time it is generated.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
OpenForAppend
# $success is true or false
my $success = $fileAccess->OpenForAppend($filePath);
Opens filePath for writing at end-of-file. The file is created if it does not exist. Existing content is preserved, and the initial file position is at the end.
FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
OpenForRead
# $success is true or false
my $success = $fileAccess->OpenForRead($filePath);
Opens an existing filePath for reading. The file may contain text or binary data and must already exist.
FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
OpenForReadWrite
# $success is true or false
my $success = $fileAccess->OpenForReadWrite($filePath);
Opens filePath for both reading and writing. The file is created if necessary. Existing content is preserved, and the initial file position is at the beginning.
FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
OpenForWrite
# $success is true or false
my $success = $fileAccess->OpenForWrite($filePath);
Opens filePath for writing. The file is created if necessary; if it already exists, it is truncated to zero length when opened.
FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ReadBinaryToEncoded
# $encoding is a string
# $str is a string or undef
my $str = $fileAccess->ReadBinaryToEncoded($filePath, $encoding);
Reads the entire file at filePath as binary data and returns an encoded textual representation. Supported encoding names documented for this method include base64, hex, qp, and url.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ReadBlockBd
# $blockSize is an integer
# $bd is a Chilkat2::BinData
# $success is true or false
my $success = $fileAccess->ReadBlockBd($blockIndex, $blockSize, $bd);
Reads the zero-based block blockIndex from the currently open file, using blockSize bytes per block, and appends the bytes to bd. A partial final block is appended at its actual length.
bd are preserved; the block bytes are appended.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ReadEntireTextFile
# $charset is a string
# $str is a string or undef
my $str = $fileAccess->ReadEntireTextFile($filePath, $charset);
Reads the entire file at filePath, decodes its bytes using charset, and returns the resulting text.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ReadNextFragment
# $beginMarker is a string
# $endMarker is a string
# $charset is a string
# $sb is a Chilkat2::StringBuilder
# $n is an integer
my $n = $fileAccess->ReadNextFragment($startAtBeginning, $beginMarker, $endMarker, $charset, $sb);
Scans the currently open file for the next text fragment beginning with beginMarker and ending with endMarker. The matched fragment, including both markers, is decoded using charset and appended to sb. If startAtBeginning is 1, scanning restarts at the beginning of the file; otherwise it continues after the previously matched fragment.
1 | A fragment was found and appended. |
0 | No matching fragment was found. |
-1 | An error occurred while reading. |
ReassembleFile
# $partPrefix is a string
# $partExtension is a string
# $reassembledFilename is a string
# $success is true or false
my $success = $fileAccess->ReassembleFile($partsDirPath, $partPrefix, $partExtension, $reassembledFilename);
Reassembles a file previously divided by SplitFile. Parts are read from partsDirPath using the supplied partPrefix and partExtension, and the combined bytes are written to reassembledFilename.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
ReplaceStrings
# $charset is a string
# $existingString is a string
# $replacementString is a string
# $n is an integer
my $n = $fileAccess->ReplaceStrings($filePath, $charset, $existingString, $replacementString);
Reads the file at filePath as text using charset, replaces occurrences of existingString with replacementString, writes the updated text back to the file, and returns the number of replacements made.
SetCurrentDir
# $success is true or false
my $success = $fileAccess->SetCurrentDir($dirPath);
Changes the current working directory of the calling process to dirPath.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetFileTimes
# $createTime is a Chilkat2::DateTime
# $lastAccessTime is a Chilkat2::DateTime
# $lastModTime is a Chilkat2::DateTime
# $success is true or false
my $success = $fileAccess->SetFileTimes($filePath, $createTime, $lastAccessTime, $lastModTime);
Sets the creation, last-access, and last-modified timestamps for filePath from the supplied CkDateTime objects. On filesystems that do not support a creation/birth time, createTime is ignored.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SetLastModified
# $lastModified is a Chilkat2::DateTime
# $success is true or false
my $success = $fileAccess->SetLastModified($filePath, $lastModified);
Sets the last-modified timestamp of filePath from lastModified. The precision actually stored depends on the underlying filesystem.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SplitFile
# $partPrefix is a string
# $partExtension is a string
# $partSize is an integer
# $destDir is a string
# $success is true or false
my $success = $fileAccess->SplitFile($fileToSplit, $partPrefix, $partExtension, $partSize, $destDir);
Splits fileToSplit into sequential binary parts of up to partSize bytes and writes them to destDir using partPrefix and partExtension. Use ReassembleFile to reconstruct the original file.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SymlinkCreate
# $linkPath is a string
# $success is true or false
my $success = $fileAccess->SymlinkCreate($targetPath, $linkPath);
Creates a symbolic link at linkPath that refers to targetPath.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
SymlinkTarget
# $str is a string or undef
my $str = $fileAccess->SymlinkTarget($linkPath);
Returns the resolved target pathname for the symbolic link at linkPath. On Windows, this method also understands Windows shortcut (.lnk) files and returns the absolute target path.
Returns undef on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
TreeDelete
# $success is true or false
my $success = $fileAccess->TreeDelete($path);
Recursively deletes the directory tree rooted at path, including contained files and subdirectories.
path identifies the intended tree before calling it.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
Truncate
my $success = $fileAccess->Truncate();
Truncates the currently open file at the current file position. Bytes at and after that position are removed, making the current position the new end-of-file.
Truncate.Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.
WriteEntireTextFile
# $textData is a string
# $charset is a string
# $includedPreamble is a boolean
# $success is true or false
my $success = $fileAccess->WriteEntireTextFile($filePath, $textData, $charset, $includedPreamble);
Creates or opens filePath, encodes textData using charset, writes the resulting bytes, and closes the file. Existing file content is replaced. If includePreamble is 1, an appropriate preamble/BOM is included for encodings such as UTF-8 or UTF-16.
Returns true on success, false on failure; LastErrorText says why. With RaiseError on, a failure dies with a Chilkat2::Error instead (it stringifies to the LastErrorText); the object remains usable either way.