FileAccess Zig Reference Documentation

FileAccess

Current Version: 11.6.1

Chilkat.FileAccess

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

Load or save text and binary files, append data, replace file contents, and work with explicit character encodings when needed.

File management

Copy, rename, delete, compare, split, reassemble, and inspect files using straightforward file-system utility methods.

Directories and paths

Create, remove, check, and work with directories, and use path helpers to extract filenames, extensions, directory names, and related path parts.

Open-file operations

Open files for lower-level reading or writing, seek within files, read blocks, and process large files without loading everything at once.

Timestamps and metadata

Get or set file times, inspect sizes and existence, and use metadata helpers when coordinating file processing workflows.

Special file utilities

Generate temporary filenames, work with symbolic links, scan for byte fragments, and perform text replacement in files.

Common pattern: Use 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.

For an extended overview, see FileAccess Class Overview.

Object Creation

// Add the package once:
//     zig fetch --save https://chilkatdownload.com/11.6.1/chilkat-zig-11.6.1.tar.gz
// and in build.zig:
//     const chilkat = b.dependency("chilkat", .{ .target = target, .optimize = optimize });
//     exe.root_module.addImport("chilkat", chilkat.module("chilkat"));
const chilkat = @import("chilkat");

// Once per process, before any other Chilkat call:
try chilkat.unlockBundle("Anything for 30-day trial");

const file_access = try chilkat.FileAccess.init();
defer file_access.deinit();
pub fn init() Allocator.Error!FileAccess

Creates the underlying native Chilkat object. FileAccess is a one-pointer struct passed by value; copying it copies the handle (two names for one object). Returns error.OutOfMemory if the library could not allocate the object. Use an object from one thread at a time; it may be handed from one thread to another.

pub fn deinit(self: FileAccess) void

Releases the native object. Call it exactly once per object (usually with defer); the handle is invalid afterwards. Objects returned by methods are owned by the caller too and are released the same way.

pub fn fromHandle(h: *chilkat.c.CkFileAccess.HCkFileAccess) FileAccess

Wraps a handle obtained from the C API (chilkat.c.CkFileAccess), taking ownership of it. The struct's handle field goes the other way, for anything the Zig API does not cover.

Errors and memory

Methods that can fail return an error union: a method whose only outcome is success or failure returns Error!void; a method producing a string returns (Error || Allocator.Error)![:0]u8; a method producing an object returns Error!T. chilkat.Error is error{ChilkatFailed}; the reason for a failure is in getLastErrorText, and the object remains usable. Properties never fail, and methods that answer a question (hasMember, isUnlocked, ...) return a plain bool.

String arguments are [:0]const u8 (UTF-8; string literals can be passed as is). String results are copies allocated with the allocator argument and owned by the caller, so they stay valid across later calls on the same object.

const text = file_access.someMethod(allocator, ...) catch |err| {
    const why = try file_access.getLastErrorText(allocator);
    defer allocator.free(why);
    std.debug.print("{s}\n", .{why});
    return err;
};
defer allocator.free(text);

Properties

CurrentDir
// read-only
pub fn getCurrentDir(self: FileAccess, allocator: Allocator) Allocator.Error![:0]u8

Returns the current working directory of the calling process. Relative file and directory paths are resolved against this process-wide working directory.

Process-wide setting: The working directory belongs to the process, not to an individual FileAccess object. Changing it can therefore affect relative-path behavior elsewhere in the application.

top
DebugLogFilePath
// read/write
pub fn getDebugLogFilePath(self: FileAccess, allocator: Allocator) Allocator.Error![:0]u8
pub fn setDebugLogFilePath(self: FileAccess, value: [:0]const u8) void

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.

More Information and Examples
Example showing how to use DebugLogFilePath.
top
EndOfFile
// read-only
pub fn getEndOfFile(self: FileAccess) bool

Returns true when the currently open file is positioned at end-of-file; otherwise returns false.

Open-file state: This property applies to the file opened by OpenForRead, OpenForWrite, OpenForReadWrite, OpenForAppend, or FileOpen.

top
FileOpenError
// read-only
pub fn getFileOpenError(self: FileAccess) i32

Provides the detailed open-error code from the most recent call to FileOpen, OpenForRead, OpenForWrite, OpenForReadWrite, or OpenForAppend.

CodeMeaning
0Success; no open error.
1Access denied.
2File not found.
3General, non-specific open error.
4File already exists.
5The path refers to a directory and the requested access involves writing.
6Too many symbolic links were encountered while resolving the path.
7The process already has the maximum number of files open.
8The pathname is too long.
9The system-wide limit on open files has been reached.
10The pathname refers to a device special file for which no corresponding device exists.
11Insufficient kernel memory was available.
12A file was to be created, but the containing device has no space available.
13A pathname component expected to be a directory is not a directory.
14The regular file is too large to be opened because of an operating-system limitation.
15The path is on a read-only filesystem and write access was requested.
Use with FileOpenErrorMsg: FileOpenError is useful for programmatic handling; FileOpenErrorMsg provides the corresponding human-readable message.

top
FileOpenErrorMsg
// read-only
pub fn getFileOpenErrorMsg(self: FileAccess, allocator: Allocator) Allocator.Error![:0]u8

Returns the human-readable message corresponding to FileOpenError for the most recent file-open attempt.

top
LastErrorHtml
// read-only
pub fn getLastErrorHtml(self: FileAccess, allocator: Allocator) Allocator.Error![:0]u8

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.

top
LastErrorText
// read-only
pub fn getLastErrorText(self: FileAccess, allocator: Allocator) Allocator.Error![:0]u8

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.

More Information and Examples
Concept of LastErrorTextLastErrorText Standard Information
top
LastErrorXml
// read-only
pub fn getLastErrorXml(self: FileAccess, allocator: Allocator) Allocator.Error![:0]u8

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.

top
LastMethodSuccess
// read/write
pub fn getLastMethodSuccess(self: FileAccess) bool
pub fn setLastMethodSuccess(self: FileAccess, value: bool) void

Indicates the success or failure of the most recent method call: true means success, false 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.

top
LockFileOnOpen
// read/write
pub fn getLockFileOnOpen(self: FileAccess) bool
pub fn setLockFileOnOpen(self: FileAccess, value: bool) void
Introduced in version 9.5.0.80

Windows only. If true, 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 false.

File sharing: Windows file sharing is established when the file handle is opened. Set this property before calling an OpenFor* method.

top
VerboseLogging
// read/write
pub fn getVerboseLogging(self: FileAccess) bool
pub fn setVerboseLogging(self: FileAccess, value: bool) void

If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
// read-only
pub fn getVersion(self: FileAccess, allocator: Allocator) Allocator.Error![:0]u8

Version of the component/library, such as "10.1.0"

More Information and Examples
How to get the Chilkat version at runtime.
top

Methods

AppendAnsi
pub fn appendAnsi(self: FileAccess, text: [:0]const u8) Error!void

Appends text to the currently open file after converting the string to the legacy ANSI character encoding used by Chilkat for the platform.

Character encoding: Use AppendText or AppendSb when an explicit encoding such as utf-8 is preferred.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
AppendBd
pub fn appendBd(self: FileAccess, bd: chilkat.BinData) Error!void
Introduced in version 9.5.0.76

Appends all bytes contained in bd to the currently open file without text conversion.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
AppendSb
pub fn appendSb(self: FileAccess, sb: chilkat.StringBuilder, charset: [:0]const u8) Error!void
Introduced in version 9.5.0.76

Appends the text contained in sb to the currently open file using the character encoding specified by charset.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
AppendText
pub fn appendText(self: FileAccess, str: [:0]const u8, charset: [:0]const u8) Error!void

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 error.ChilkatFailed on failure; getLastErrorText explains why.

top
AppendUnicodeBOM
pub fn appendUnicodeBOM(self: FileAccess) Error!void

Appends the UTF-16 little-endian byte-order mark to the currently open file. The two bytes written are FF FE.

BOM placement: A BOM normally belongs at the beginning of a text file. This method appends bytes at the current write position, so call it before writing text when creating a new UTF-16LE file.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
AppendUtf8BOM
pub fn appendUtf8BOM(self: FileAccess) Error!void

Appends the UTF-8 byte-order mark to the currently open file. The three bytes written are EF BB BF.

UTF-8 BOM: A UTF-8 BOM is optional. Some software uses it as an encoding signature, while other software expects BOM-less UTF-8.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
DirAutoCreate
pub fn dirAutoCreate(self: FileAccess, file_path: [:0]const u8) Error!void

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.

Difference from DirEnsureExists: Use DirAutoCreate when you have a file path. Use DirEnsureExists when the argument itself is a directory path.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
DirCreate
pub fn dirCreate(self: FileAccess, dir_path: [:0]const u8) Error!void

Creates the directory specified by dirPath. Parent directories must already exist; use DirEnsureExists when missing parent directories should also be created.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
DirDelete
pub fn dirDelete(self: FileAccess, dir_path: [:0]const u8) Error!void

Deletes the directory specified by dirPath. The directory must be empty; use TreeDelete to recursively delete a directory and its contents.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
DirEnsureExists
pub fn dirEnsureExists(self: FileAccess, dir_path: [:0]const u8) Error!void

Ensures that the complete directory path dirPath exists, creating missing directories along the path as needed.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
DirExists
pub fn dirExists(self: FileAccess, dir_path: [:0]const u8) bool
Introduced in version 10.0.0

Returns true if dirPath exists as a directory; otherwise returns false.

top
FileClose
pub fn fileClose(self: FileAccess) void

Closes the currently open file and releases its operating-system file handle. Any exclusive lock obtained through LockFileOnOpen is released at this time.

top
FileContentsEqual
pub fn fileContentsEqual(self: FileAccess, file_path1: [:0]const u8, file_path2: [:0]const u8) bool

Compares filePath1 and filePath2 byte-for-byte and returns true 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.

Binary comparison: The comparison is byte-oriented. Text encodings, line-ending conventions, and Unicode normalization are not interpreted or normalized.
top
FileCopy
pub fn fileCopy(self: FileAccess, existing_filepath: [:0]const u8, new_filepath: [:0]const u8, fail_if_exists: bool) Error!void

Copies existingFilepath to newFilepath. If failIfExists is true and the destination already exists, the copy fails instead of overwriting it.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
FileDelete
pub fn fileDelete(self: FileAccess, file_path: [:0]const u8) Error!void

Deletes the file specified by filePath.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
FileExists
pub fn fileExists(self: FileAccess, file_path: [:0]const u8) bool

Returns true if filePath exists; otherwise returns false. Use FileExists3 when the application must distinguish "does not exist" from "could not determine because of an error."

top
FileExists3
pub fn fileExists3(self: FileAccess, path: [:0]const u8) i32
Introduced in version 9.5.0.45

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.

top
FileOpen
pub fn fileOpen(self: FileAccess, file_path: [:0]const u8, access_mode: u32, share_mode: u32, create_disposition: u32, attributes: u32) Error!void

Windows-specific low-level open. Opens filePath using arguments modeled after the Win32 CreateFile API. For portable code, prefer OpenForRead, OpenForWrite, OpenForReadWrite, or OpenForAppend.

CategoryCommon values
AccessGENERIC_READ = 0x80000000, GENERIC_WRITE = 0x40000000
SharingFILE_SHARE_READ = 0x1, FILE_SHARE_WRITE = 0x2
DispositionCREATE_NEW=1, CREATE_ALWAYS=2, OPEN_EXISTING=3, OPEN_ALWAYS=4, TRUNCATE_EXISTING=5
Open failures: When this method fails, inspect FileOpenError and FileOpenErrorMsg for the reason.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
FileReadBd
pub fn fileReadBd(self: FileAccess, max_num_bytes: i32, bin_data: chilkat.BinData) Error!void
Introduced in version 9.5.0.64

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.

Destination behavior: Existing bytes already present in binData are preserved; newly read bytes are appended.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

More Information and Examples
Determine File Type from Binary Content of FileLoad Entire File into BinData
top
FileRename
pub fn fileRename(self: FileAccess, existing_filepath: [:0]const u8, new_filepath: [:0]const u8) Error!void

Renames or moves existingFilepath to newFilepath using the local filesystem.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
FileSeek
pub fn fileSeek(self: FileAccess, offset: i32, origin: i32) Error!void

Moves the current file position by offset bytes relative to origin.

0Offset from the beginning of the file.
1Offset from the current file position.
2Offset from end-of-file; negative offsets are commonly used.
Random access: Seeking changes where the next read or write occurs; it does not itself read, write, or resize the file.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
FileSize
pub fn fileSize(self: FileAccess, file_path: [:0]const u8) i32

Returns the file size in bytes as a signed 32-bit integer, or -1 on failure.

Large files: A signed 32-bit result cannot represent files larger than approximately 2 GB. Use FileSize64 or FileSizeStr for large files.
top
FileSize64
pub fn fileSize64(self: FileAccess, file_path: [:0]const u8) i64
Introduced in version 9.5.0.88

Returns the size of filePath in bytes as a signed 64-bit integer, or -1 on failure.

top
FileSizeStr
pub fn fileSizeStr(self: FileAccess, allocator: Allocator, file_path: [:0]const u8) (Error || Allocator.Error)![:0]u8
Introduced in version 9.5.0.80

Returns the size of filePath in bytes as a decimal string. This avoids the range limitation of a 32-bit integer return value.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

top
FileType
pub fn fileType(self: FileAccess, path: [:0]const u8) i32
Introduced in version 9.5.0.77

Examines path and classifies the filesystem entry.

-1Unable to determine because of permissions or another error.
0Does not exist.
1Regular file.
2Directory.
3Symbolic link.
4Windows shortcut.
99Another filesystem type.
Future values: Additional file-type codes may be added in future versions as needed.
More Information and Examples
Determine File Type
top
FileWrite2
pub fn fileWrite2(self: FileAccess, byte_data: []const u8) Error!void
Introduced in version 9.5.0.82

Writes exactly szByteData bytes beginning at pByteData to the currently open file at the current file position.

C++ buffer contract: The caller must supply a valid readable buffer containing at least szByteData bytes.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
FileWriteBd
pub fn fileWriteBd(self: FileAccess, bin_data: chilkat.BinData, offset: i32, num_bytes: i32) Error!void
Introduced in version 9.5.0.64

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 error.ChilkatFailed on failure; getLastErrorText explains why.

top
GenBlockId
pub fn genBlockId(self: FileAccess, allocator: Allocator, index: i32, length: i32, encoding: [:0]const u8) (Error || Allocator.Error)![:0]u8
Introduced in version 9.5.0.58

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.

Ordering: Fixed-width decimal identifiers preserve numeric ordering when identifiers are compared lexically, provided the chosen width is large enough for all indexes.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

top
GetDirectoryName
pub fn getDirectoryName(self: FileAccess, allocator: Allocator, path: [:0]const u8) (Error || Allocator.Error)![:0]u8
Introduced in version 9.5.0.64

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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

More Information and Examples
Demonstrate Directory Path Functions
top
GetExtension
pub fn getExtension(self: FileAccess, allocator: Allocator, path: [:0]const u8) (Error || Allocator.Error)![:0]u8
Introduced in version 9.5.0.64

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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

More Information and Examples
Demonstrate Directory Path Functions
top
GetFileName
pub fn getFileName(self: FileAccess, allocator: Allocator, path: [:0]const u8) (Error || Allocator.Error)![:0]u8
Introduced in version 9.5.0.64

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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

More Information and Examples
Demonstrate Directory Path Functions
top
GetFileNameWithoutExtension
pub fn getFileNameWithoutExtension(self: FileAccess, allocator: Allocator, path: [:0]const u8) (Error || Allocator.Error)![:0]u8
Introduced in version 9.5.0.64

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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

More Information and Examples
Demonstrate Directory Path Functions
top
GetFileTimeStr
pub fn getFileTimeStr(self: FileAccess, allocator: Allocator, path: [:0]const u8, which: i32) (Error || Allocator.Error)![:0]u8
Introduced in version 11.0.0

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.

Portability: Creation/birth time is not available on every filesystem. The documented Chilkat behavior on Linux is to return the last-modified time when creation time is unavailable.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

top
GetNumBlocks
pub fn getNumBlocks(self: FileAccess, block_size: i32) i32
Introduced in version 9.5.0.58

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.

Calculation: Conceptually this is ceil(fileSize / blockSize) for a non-empty file.
More Information and Examples
SFTP Upload Large File in Parts
top
GetTempFilename
pub fn getTempFilename(self: FileAccess, allocator: Allocator, dir_path: [:0]const u8, prefix: [:0]const u8) (Error || Allocator.Error)![:0]u8

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 error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

top
OpenForAppend
pub fn openForAppend(self: FileAccess, file_path: [:0]const u8) Error!void

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.

Open failures: If the open/create operation fails, inspect FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
OpenForRead
pub fn openForRead(self: FileAccess, file_path: [:0]const u8) Error!void

Opens an existing filePath for reading. The file may contain text or binary data and must already exist.

Open failures: If the open/create operation fails, inspect FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

More Information and Examples
Load Entire File into BinData
top
OpenForReadWrite
pub fn openForReadWrite(self: FileAccess, file_path: [:0]const u8) Error!void

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.

Open failures: If the open/create operation fails, inspect FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
OpenForWrite
pub fn openForWrite(self: FileAccess, file_path: [:0]const u8) Error!void

Opens filePath for writing. The file is created if necessary; if it already exists, it is truncated to zero length when opened.

Open failures: If the open/create operation fails, inspect FileOpenError and FileOpenErrorMsg. On Windows, LockFileOnOpen can request exclusive access for this method.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
ReadBinaryToEncoded
pub fn readBinaryToEncoded(self: FileAccess, allocator: Allocator, file_path: [:0]const u8, encoding: [:0]const u8) (Error || Allocator.Error)![:0]u8

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.

Encoding is not encryption: These encodings transform bytes into text; they do not provide confidentiality.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

More Information and Examples
Base64 Encode a File
top
ReadBlockBd
pub fn readBlockBd(self: FileAccess, block_index: i32, block_size: i32, bd: chilkat.BinData) Error!void
Introduced in version 9.5.0.79

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.

Destination behavior: Existing contents of bd are preserved; the block bytes are appended.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

More Information and Examples
Dropbox Content HashSFTP Upload Large File in Parts
top
ReadEntireTextFile
pub fn readEntireTextFile(self: FileAccess, allocator: Allocator, file_path: [:0]const u8, charset: [:0]const u8) (Error || Allocator.Error)![:0]u8

Reads the entire file at filePath, decodes its bytes using charset, and returns the resulting text.

Charset matters: The charset controls byte-to-character conversion. Use the encoding that actually represents the file; incorrect charset selection can produce incorrect text or conversion failure.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

top
ReadNextFragment
pub fn readNextFragment(self: FileAccess, start_at_beginning: bool, begin_marker: [:0]const u8, end_marker: [:0]const u8, charset: [:0]const u8, sb: chilkat.StringBuilder) i32
Introduced in version 9.5.0.80

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 true, scanning restarts at the beginning of the file; otherwise it continues after the previously matched fragment.

1A fragment was found and appended.
0No matching fragment was found.
-1An error occurred while reading.
More Information and Examples
Efficiently Process a Huge XML File
top
ReassembleFile
pub fn reassembleFile(self: FileAccess, parts_dir_path: [:0]const u8, part_prefix: [:0]const u8, part_extension: [:0]const u8, reassembled_filename: [:0]const u8) Error!void

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.

Byte-for-byte reconstruction: Reassembly is a binary operation; no text decoding or newline conversion is performed.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

More Information and Examples
Example: Reassemble a Previously Split File
top
ReplaceStrings
pub fn replaceStrings(self: FileAccess, file_path: [:0]const u8, charset: [:0]const u8, existing_string: [:0]const u8, replacement_string: [:0]const u8) i32

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.

Text operation: This is character-based replacement after decoding the file. It is not suitable for arbitrary binary files.
top
SetCurrentDir
pub fn setCurrentDir(self: FileAccess, dir_path: [:0]const u8) Error!void

Changes the current working directory of the calling process to dirPath.

Process-wide effect: The current directory is normally process-wide, so changing it can affect relative paths used by other code or threads. Absolute paths avoid that dependency.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
SetFileTimes
pub fn setFileTimes(self: FileAccess, file_path: [:0]const u8, create_time: chilkat.DateTime, last_access_time: chilkat.DateTime, last_mod_time: chilkat.DateTime) Error!void

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.

Filesystem differences: Timestamp availability and precision are filesystem- and operating-system-dependent.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
SetLastModified
pub fn setLastModified(self: FileAccess, file_path: [:0]const u8, last_modified: chilkat.DateTime) Error!void

Sets the last-modified timestamp of filePath from lastModified. The precision actually stored depends on the underlying filesystem.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
SplitFile
pub fn splitFile(self: FileAccess, file_to_split: [:0]const u8, part_prefix: [:0]const u8, part_extension: [:0]const u8, part_size: i32, dest_dir: [:0]const u8) Error!void

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 error.ChilkatFailed on failure; getLastErrorText explains why.

More Information and Examples
Example: Split File into Chunks
top
SymlinkCreate
pub fn symlinkCreate(self: FileAccess, target_path: [:0]const u8, link_path: [:0]const u8) Error!void
Introduced in version 9.5.0.77

Creates a symbolic link at linkPath that refers to targetPath.

Windows note: A Windows symbolic link is not the same as a Windows shortcut. Windows may require elevated privileges or an operating-system configuration such as Developer Mode that permits unprivileged symbolic-link creation, depending on system policy and how the application is launched.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

More Information and Examples
Create Symbolic Link
top
SymlinkTarget
pub fn symlinkTarget(self: FileAccess, allocator: Allocator, link_path: [:0]const u8) (Error || Allocator.Error)![:0]u8
Introduced in version 9.5.0.77

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.

Link vs. target: A symbolic link is a filesystem object that refers to another path. A Windows shortcut is a separate shell-file format; Chilkat supports both here even though they are different mechanisms.

Returns error.ChilkatFailed on failure; getLastErrorText explains why. The string is allocated with allocator and owned by the caller (defer allocator.free(s)).

More Information and Examples
Get the Target of a Symbolic LinkGet the Target of a Windows Shortcut
top
TreeDelete
pub fn treeDelete(self: FileAccess, path: [:0]const u8) Error!void

Recursively deletes the directory tree rooted at path, including contained files and subdirectories.

Destructive operation: This operation is recursive and destructive. Ensure path identifies the intended tree before calling it.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
Truncate
pub fn truncate(self: FileAccess) Error!void
Introduced in version 9.5.0.80

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.

Use with FileSeek: A common pattern is to seek to the desired new length and then call Truncate.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

top
WriteEntireTextFile
pub fn writeEntireTextFile(self: FileAccess, file_path: [:0]const u8, text_data: [:0]const u8, charset: [:0]const u8, included_preamble: bool) Error!void

Creates or opens filePath, encodes textData using charset, writes the resulting bytes, and closes the file. Existing file content is replaced. If includePreamble is true, an appropriate preamble/BOM is included for encodings such as UTF-8 or UTF-16.

BOM terminology: A BOM is part of the byte representation of the text file; it is not part of the application string itself.

Returns error.ChilkatFailed on failure; getLastErrorText explains why.

More Information and Examples
Base64 Encode a File
top