Chilkat.FileAccess Class Overview

Chilkat.FileAccess provides file-system utilities for reading, writing, appending, seeking, comparing, copying, renaming, deleting, splitting, reassembling, and inspecting files. It also includes directory operations, path parsing helpers, timestamp functions, symbolic link support, temporary filename generation, block-based reading, fragment scanning, text replacement, and low-level open-file operations.

What the Class Is Used For

Use Chilkat.FileAccess when an application needs practical file and directory operations that work with both whole-file workflows and open-file streaming workflows. The class can read or write complete files, open a file and perform repeated reads/writes, append text or binary data, manage directories, inspect file metadata, and handle file-processing tasks such as splitting, reassembling, comparing, or scanning for marked text fragments.

Read and Write Files Read entire binary or text files, write entire files, or open files for repeated read/write operations.
Directory Management Create, ensure, delete, auto-create parent directories, and remove entire directory trees.
Path and Metadata Utilities Extract filenames, extensions, directory names, file sizes, file types, and timestamps.
Large File Helpers Compare files chunk-by-chunk, read blocks, split files, reassemble parts, and use 64-bit file sizes.

Typical Workflow

  1. Use existence and type checks such as FileExists, FileExists3, FileType, and DirExists before operating on paths.
  2. Ensure required folders exist with DirEnsureExists or DirAutoCreate.
  3. For whole-file operations, use methods such as ReadEntireFile, ReadEntireTextFile, WriteEntireFile, or WriteEntireTextFile.
  4. For streaming-style operations, open the file with OpenForRead, OpenForWrite, OpenForReadWrite, or OpenForAppend.
  5. Read, write, append, seek, truncate, or scan while the file is open.
  6. Close the file with FileClose when done.
  7. Check FileOpenError, FileOpenErrorMsg, and LastErrorText after failures.

Core Concepts

Concept Meaning Important Members
Whole-File Operation A method opens, reads or writes, and closes the file internally. ReadEntireFile, ReadEntireTextFile, WriteEntireFile, WriteEntireTextFile
Open-File Operation The application opens a file, performs one or more operations, then closes it explicitly. OpenForRead, FileRead, FileWrite, FileClose
File Pointer The current byte position in an open file. Reads and writes occur at this position. FileSeek, Truncate, EndOfFile
Character Encoding Text methods require a charset such as utf-8, ansi, or another supported character set. ReadEntireTextFile, WriteEntireTextFile, AppendText, AppendSb
Directory Preparation Parent directories can be created before writing a file. DirEnsureExists, DirAutoCreate, DirCreate
Open Error Details File-open failures provide a numeric reason and a text message. FileOpenError, FileOpenErrorMsg, LastErrorText

Core Properties

Property Purpose Important Detail
CurrentDir Returns the current working directory of the calling process. Use SetCurrentDir to change it.
EndOfFile Indicates whether the currently open file is at end-of-file. Applies to the current open-file workflow.
FileOpenError Numeric failure reason from file-open methods. Set by FileOpen, OpenForRead, OpenForWrite, OpenForReadWrite, and OpenForAppend.
FileOpenErrorMsg Text message associated with FileOpenError. Useful for user-facing or log-friendly diagnostics after open failures.
LockFileOnOpen On Windows, opens files for exclusive access when true. Applies to OpenForAppend, OpenForRead, OpenForReadWrite, and OpenForWrite. Default is false.
LastErrorText Detailed diagnostic text for the last method or property access. Check after failures or unexpected behavior.

Opening Files

Method Behavior Existing File Behavior
OpenForRead Opens an existing file for reading. The file must already exist.
OpenForWrite Opens a file for writing, creating it if needed. Existing content is overwritten. Opening and immediately closing an existing file leaves it empty.
OpenForReadWrite Opens a file for reading and writing, creating it if needed. Existing content is not overwritten. The file pointer starts at the beginning.
OpenForAppend Opens a file for appending, creating it if needed. Existing content is preserved. The file pointer starts at the end.
FileOpen Windows-only low-level open method mirroring CreateFile-style arguments. Use only on Windows when specific access mode, share mode, create disposition, or attributes are needed.
Windows-only note: FileOpen should only be called on Windows. For Linux, macOS, and other operating systems, use OpenForRead, OpenForWrite, OpenForReadWrite, or OpenForAppend.

Open-File Reading, Writing, Seeking, and Closing

Task Methods Guidance
Read bytes FileRead, FileReadBd Reads up to a maximum number of bytes from the currently open file. FileReadBd appends bytes to BinData.
Write bytes FileWrite, FileWriteBd, FileWrite2 Writes bytes to the currently open file. FileWriteBd can write all or part of a BinData object.
Seek FileSeek Moves the file pointer relative to the beginning, current position, or end of file.
Truncate Truncate Truncates the currently open file at the current file pointer position.
Check EOF EndOfFile Returns true when the current open file is at end-of-file.
Close FileClose Closes the currently open file and releases any associated lock.
Seek origin values: FileSeek uses 0 for beginning of file, 1 for current position, and 2 for end-of-file. Offsets from end-of-file may be negative.

Appending Text and Binary Data

Append Task Method Notes
Append ANSI text AppendAnsi Appends a string using ANSI character encoding.
Append text with charset AppendText Appends a string using the specified character encoding.
Append StringBuilder text AppendSb Appends StringBuilder content using the specified charset, such as utf-8.
Append BinData AppendBd Appends bytes from a BinData object.
Append Unicode BOM AppendUnicodeBOM Appends a 2-byte little-endian Unicode BOM.
Append UTF-8 BOM AppendUtf8BOM Appends a 3-byte UTF-8 BOM.

Whole-File Read and Write Methods

Task Method Behavior
Read binary file ReadEntireFile Reads an entire binary file and returns the bytes.
Read text file ReadEntireTextFile Reads an entire text file and decodes bytes using the specified charset.
Read binary file as encoded text ReadBinaryToEncoded Reads a binary file and returns encoded text such as base64, hex, qp, or url.
Write binary file WriteEntireFile Opens or creates the file, writes the bytes, and closes the file.
Write text file WriteEntireTextFile Writes text using the specified charset. Can include a BOM/preamble for Unicode or UTF-8 when requested.

Directory Operations

Task Method Behavior
Check directory existence DirExists Returns true if the directory path exists.
Create one directory DirCreate Creates the specified directory.
Create all missing directories in a directory path DirEnsureExists Creates all directories needed so the complete directory path exists.
Create parent directories for a file path DirAutoCreate Treats the last path part as a filename and creates missing parent directories.
Delete empty directory DirDelete Deletes a directory only when it contains no files or subdirectories.
Delete directory tree TreeDelete Deletes an entire directory tree, including files and subdirectories.
Change current process directory SetCurrentDir Sets the current working directory for the calling process.
Deletion caution: TreeDelete removes an entire directory tree. Use explicit paths and verify them before calling it.

File Management and Inspection

Need Methods Guidance
Check file existence FileExists, FileExists3 FileExists3 distinguishes exists, does not exist, and unable to check.
Check file type FileType Identifies regular files, directories, symbolic links, Windows shortcuts, missing paths, and error cases.
Copy file FileCopy Can fail if the destination already exists when failIfExists is true.
Rename file FileRename Renames or moves a file from one path to another.
Delete file FileDelete Deletes the specified file.
Compare files FileContentsEqual Compares files chunk-by-chunk and does not load entire files into memory.
Get file size FileSize, FileSize64, FileSizeStr Prefer FileSize64 or FileSizeStr for files larger than 2 GB.

Path Utility Methods

Need Method Example Result
Get directory portion GetDirectoryName C:\MyDir\MySubDir\myfile.ext → C:\MyDir\MySubDir\
Get filename with extension GetFileName C:\mydir\myfile.ext → myfile.ext
Get filename without extension GetFileNameWithoutExtension C:\mydir\myfile.ext → myfile
Get extension GetExtension C:\mydir.old\myfile.ext → .ext
Get temporary filename GetTempFilename Creates a non-existing temporary path using the requested directory and prefix.

File Size, Blocks, Splitting, and Reassembly

Task Method Use Case
Get file size FileSize, FileSize64, FileSizeStr Determine file length. Use 64-bit or string methods for large files.
Get block count GetNumBlocks Calculates how many blocks are needed for the currently open file at a specified block size.
Read a block ReadBlock, ReadBlockBd Reads the Nth block. The final block may be smaller than the requested block size.
Generate block ID GenBlockId Utility method for generating encoded fixed-width block IDs, originally useful for Azure Blob block uploads.
Split file SplitFile Splits a file into parts with a specified prefix, extension, size, and destination directory.
Reassemble file ReassembleFile Reassembles a file previously split by SplitFile.
Large-file friendly: FileContentsEqual compares chunk-by-chunk, and ReadBlock / ReadBlockBd support block-style processing without reading the entire file at once.

File Times

Task Method Details
Get file time GetFileTimeStr Returns last-modified, last-access, or creation time as an ISO 8601 timestamp: YYYY-MM-DDTHH:MM:SSZ.
Set last-modified time SetLastModified Sets the file’s last-modified date/time using CkDateTime.
Set creation, access, and modified times SetFileTimes Sets creation, last-access, and last-modified times. On filesystems without creation times, the creation time is ignored.
Filesystem note: Linux filesystems do not keep a file creation date/time in the same way. When creation time is requested, GetFileTimeStr returns the last-modified time in that case.

Text Processing Helpers

Need Method Behavior
Replace text in a file ReplaceStrings Replaces all occurrences of a string with another string using the specified charset.
Read next marked fragment ReadNextFragment Scans an open text file for text between a begin marker and end marker, appending the matched fragment to a StringBuilder.
XML-tag-aware begin marker ReadNextFragment A begin marker such as <abc> also matches <abc to support XML tags with attributes.
ReadNextFragment return values: 1 means a fragment was found, 0 means no match was found, and -1 means an error occurred while reading.

Symbolic Links and Shortcuts

Task Method Notes
Create symbolic link SymlinkCreate Creates a symbolic link from linkPath to targetPath.
Resolve symbolic link or Windows shortcut SymlinkTarget Returns the full pathname of the target. Also handles Windows shortcut files by returning the absolute path of the shortcut target.
Identify symbolic link or shortcut FileType Returns different values for symbolic links and Windows shortcuts.
Windows note: A Windows symbolic link is not the same as a Windows shortcut. Creating symbolic links on Windows may require administrator rights or the “Create symbolic links” user-right assignment.

File Type Return Values

Return Value Meaning
-1 Unable to check because of permissions or another error.
0 File or path does not exist.
1 Regular file.
2 Directory.
3 Symbolic link.
4 Windows shortcut.
99 Something else.

File Open Error Codes

Code Meaning Typical Cause
1 Success / no error. The file was opened successfully.
2 Access denied. Permissions, locks, or insufficient privileges.
3 File not found. The file or path does not exist.
4 General open error. Non-specific open failure.
5 File already exists. Create-new behavior requested but the destination already exists.
6 Path refers to a directory and write access was requested. A directory path was used where a writable file path was expected.
7 Too many symbolic links. Symlink loop or excessive symlink resolution.
8 Process has too many files open. The process file-handle limit was reached.
9 Pathname too long. Path exceeds operating-system limits.
10 System open-file limit reached. The OS-wide limit on open files was reached.
11 Device special file has no corresponding device. The path refers to a device that is not available.
12 Insufficient kernel memory. The operating system lacked memory for the operation.
13 No room on device. The destination filesystem is full.
14 Path component is not a directory. A path component expected to be a directory is actually something else.
15 Regular file too large to open. Operating-system limitation, not a Chilkat-imposed limit.
16 Read-only filesystem. Write access was requested on a read-only filesystem.
Open failure diagnostics: After an open method fails, check both FileOpenError and FileOpenErrorMsg. For broader method diagnostics, also check LastErrorText.

Diagnostics and Troubleshooting

Problem Area Member What to Check
General method failure LastErrorText Provides detailed information about the last method or property access.
Open failure FileOpenError, FileOpenErrorMsg Check the numeric reason and associated text message.
Path may not exist or may be inaccessible FileExists3, FileType These methods distinguish missing paths from permission or other error conditions.
Unexpected overwrite OpenForWrite Remember that OpenForWrite overwrites existing content.
Large file size issue FileSize64, FileSizeStr Avoid FileSize for files larger than 2 GB.
Text appears garbled ReadEntireTextFile, WriteEntireTextFile, AppendText Confirm the charset used for reading, writing, or appending text.
Symbolic link creation fails on Windows SymlinkCreate Check administrator rights or the Windows “Create symbolic links” user-right assignment.

Common Pitfalls

Pitfall Better Approach
Using OpenForWrite on an existing file when the content should be preserved. Use OpenForReadWrite to preserve content or OpenForAppend to append at the end.
Using FileSize for large files. Use FileSize64 or FileSizeStr for files greater than 2 GB.
Deleting a directory with DirDelete and expecting recursive deletion. DirDelete only deletes empty directories. Use TreeDelete for recursive deletion.
Forgetting to close an open file. Call FileClose when finished, especially when file locking or repeated open-file operations are involved.
Using FileOpen on non-Windows platforms. Use the portable open methods: OpenForRead, OpenForWrite, OpenForReadWrite, or OpenForAppend.
Assuming Windows shortcuts and symbolic links are the same. They are different. SymlinkTarget can resolve both, but SymlinkCreate creates symbolic links.

Best Practices

Recommendation Reason
Use whole-file methods for simple read/write operations. They are concise and handle open/write/read/close internally.
Use open-file methods for repeated, block-based, append, seek, or truncate workflows. They provide control over the file pointer and support incremental processing.
Call DirAutoCreate before writing to deep file paths. It creates missing parent directories for a target file path.
Use FileExists3 or FileType when failure details matter. They can distinguish missing paths from permission or access-check failures.
Use FileContentsEqual for large file comparisons. It compares chunk-by-chunk instead of loading entire files into memory.
Prefer FileSize64 or FileSizeStr for general file-size code. They avoid the 2 GB limitation of the 32-bit FileSize result.
Be explicit about character encoding for text operations. Correct charset selection prevents garbled text and incorrect byte output.
Check FileOpenErrorMsg and LastErrorText after failures. They provide the most useful diagnostic information for file access, permissions, paths, and operating-system errors.

Summary

Chilkat.FileAccess is a general-purpose file-system utility class for applications that need reliable file and directory operations. It supports whole-file and open-file read/write patterns, appending text or binary data, path parsing, directory creation and deletion, file copying, renaming, deleting, comparing, size checks, timestamps, temporary filenames, symbolic links, block processing, file splitting and reassembly, text replacement, and fragment scanning.

The most important usage distinction is between whole-file methods, which open and close internally, and open-file methods, which require the application to call FileClose. For diagnostics, file-open failures should be checked with FileOpenError and FileOpenErrorMsg, while general method details are in LastErrorText.