SFtpFile Zig Reference Documentation
SFtpFile
Current Version: 11.6.1
Chilkat.SFtpFile
Read
Access the entry size as a 32-bit integer, 64-bit integer, or decimal
string using
Inspect creation, last-access, and last-modified times as date/time
values or RFC822-formatted strings when supported by the server.
Read numeric user and group IDs, and when the server supports it, textual
owner and group names.
Inspect the POSIX-style permissions bit mask for read, write, execute,
set-user-ID, set-group-ID, and sticky-bit information.
Check server-provided flags such as hidden, read-only, archive,
immutable, encrypted, compressed, sparse, append-only, system, and sync.
Inspect metadata for a file, directory, symlink, or special item in an SFTP listing.
Chilkat.SFtpFile represents one entry returned from an SFTP
directory listing. It exposes the entry name, file type, size, ownership,
permissions, timestamps, and server-provided attribute flags such as hidden,
read-only, archive, immutable, encrypted, compressed, sparse, append-only,
system, and synchronization status. It is typically used together with
Chilkat.SFtpDir when iterating a remote directory and deciding
how each entry should be displayed, filtered, downloaded, skipped, or
processed.
Name and type
Filename and FileType, or use convenience
flags such as IsRegular, IsDirectory, and
IsSymLink.
File sizes
Size32, Size64, or
SizeStr.
Timestamps
Ownership
Permissions
Extended attributes
Chilkat.SFtp, iterate its
Chilkat.SFtpDir entries, and populate a
Chilkat.SFtpFile object for each item. Use the file type,
timestamps, size, permissions, and attribute flags to decide whether the
entry is a regular file, directory, symlink, or special item and how the
application should handle it.
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 s_ftp_file = try chilkat.SFtpFile.init();
defer s_ftp_file.deinit();Creates the underlying native Chilkat object. SFtpFile 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.
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.
Wraps a handle obtained from the C API (chilkat.c.CkSFtpFile), 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 = s_ftp_file.someMethod(allocator, ...) catch |err| {
const why = try s_ftp_file.getLastErrorText(allocator);
defer allocator.free(why);
std.debug.print("{s}\n", .{why});
return err;
};
defer allocator.free(text);Properties
CreateTimeStr
pub fn getCreateTimeStr(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Returns the file creation date and time as an RFC 822-formatted string, such as Fri, 21 Nov 1997 09:55:06 -0600.
Server requirement: Creation-time metadata is available only when the server supports SFTP version 4 or later and provides this attribute.
topDebugLogFilePath
pub fn getDebugLogFilePath(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
pub fn setDebugLogFilePath(self: SFtpFile, 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.
Filename
pub fn getFilename(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Returns the name of the directory entry. Depending on the entry type, this may be a regular filename, directory name, symbolic-link name, or the name of another special filesystem object.
topFileType
pub fn getFileType(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Identifies the type of directory entry. The returned value is one of the following:
| Value | Meaning |
|---|---|
regular | A regular file. |
directory | A directory. |
symLink | A symbolic link. |
special | A special file whose more specific type is not reported. |
unknown | The type is unknown or was not provided by the server. |
socket | A socket. |
charDevice | A character device. |
blockDevice | A block device. |
fifo | A FIFO (named pipe). |
The convenience properties IsRegular, IsDirectory, and IsSymLink may be used for the most common entry types.
Gid
pub fn getGid(self: SFtpFile) i32
Returns the numeric group ID associated with the file.
topGroup
pub fn getGroup(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Returns the textual group name associated with the file.
Server requirement: This attribute is available only when the server supports SFTP version 4 or later and provides owner/group names.
topIsAppendOnly
pub fn getIsAppendOnly(self: SFtpFile) bool
Returns true if the server marks the file as append-only. New data may be added only at the end of the file; existing data cannot be overwritten through normal file writes.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsArchive
pub fn getIsArchive(self: SFtpFile) bool
Returns true if the server marks the file for inclusion in backup or archive operations.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsCaseInsensitive
pub fn getIsCaseInsensitive(self: SFtpFile) bool
Applies to directories. Returns true when names within the directory should be compared without regard to letter case.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsCompressed
pub fn getIsCompressed(self: SFtpFile) bool
Returns true if the file is stored using transparent filesystem-level compression on the server.
This attribute describes how the server stores the file. It does not change the file bytes transferred through SFTP.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsDirectory
pub fn getIsDirectory(self: SFtpFile) bool
Returns true if the directory entry is a directory.
IsEncrypted
pub fn getIsEncrypted(self: SFtpFile) bool
Returns true if the file is stored using transparent filesystem-level encryption on the server.
This attribute describes storage at rest. It does not alter the file bytes returned by read operations or accepted by write operations.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsHidden
pub fn getIsHidden(self: SFtpFile) bool
Returns true if the server marks the entry as hidden. Hidden entries are normally omitted from user-facing displays unless the user specifically requests them.
IsImmutable
pub fn getIsImmutable(self: SFtpFile) bool
Returns true if the server marks the file as immutable. An immutable file cannot normally be deleted, renamed, modified, or used as the target of a new hard link.
Immutability is generally stronger than read-only status, the ordinary permission mask, or an access-control list. On many systems, only a privileged administrator can set or clear this attribute.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsReadOnly
pub fn getIsReadOnly(self: SFtpFile) bool
Returns true if the server marks the file as read-only.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsRegular
pub fn getIsRegular(self: SFtpFile) bool
Returns true if the directory entry is a regular file rather than a directory, symbolic link, device, socket, FIFO, or other special type.
IsSparse
pub fn getIsSparse(self: SFtpFile) bool
Returns true if the server identifies the file as sparse. A sparse file can contain unwritten regions, often called holes, that read as zero bytes without consuming equivalent physical disk space.
For example, writing data at an offset of 10 MB may leave the region between the previous end of file and that offset unallocated on disk.
Some servers store all files sparsely and may always set this flag. Other servers cannot reliably determine whether a file is sparse, so a file may be sparse even when this property is false.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsSymLink
pub fn getIsSymLink(self: SFtpFile) bool
Returns true if the directory entry is a symbolic link.
IsSync
pub fn getIsSync(self: SFtpFile) bool
Returns true if modifications to the file are committed synchronously to server storage.
Server requirement: This attribute is defined for SFTP version 6 or later.
topIsSystem
pub fn getIsSystem(self: SFtpFile) bool
Returns true if the server marks the file as part of the operating system.
Server requirement: This attribute is defined for SFTP version 6 or later.
topLastAccessTimeStr
pub fn getLastAccessTimeStr(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Returns the file's last-access date and time as an RFC 822-formatted string, such as Fri, 21 Nov 1997 09:55:06 -0600.
LastErrorHtml
pub fn getLastErrorHtml(self: SFtpFile, 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.
topLastErrorText
pub fn getLastErrorText(self: SFtpFile, 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.
LastErrorXml
pub fn getLastErrorXml(self: SFtpFile, 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.
topLastMethodSuccess
pub fn getLastMethodSuccess(self: SFtpFile) bool
pub fn setLastMethodSuccess(self: SFtpFile, 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.
LastModifiedTimeStr
pub fn getLastModifiedTimeStr(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Returns the file's last-modified date and time as an RFC 822-formatted string, such as Fri, 21 Nov 1997 09:55:06 -0600.
Use LastModifiedTime when a native date/time value is more convenient.
Owner
pub fn getOwner(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Returns the textual owner name associated with the file.
Server requirement: This attribute is available only when the server supports SFTP version 4 or later and provides owner/group names.
topPermissions
pub fn getPermissions(self: SFtpFile) i32
Returns the POSIX-style file-permission bit mask. The values correspond to the permission and special-mode bits in the POSIX st_mode field.
| Symbol | Octal value | Meaning |
|---|---|---|
S_IRUSR | 0400 | Owner read |
S_IWUSR | 0200 | Owner write |
S_IXUSR | 0100 | Owner execute |
S_IRGRP | 0040 | Group read |
S_IWGRP | 0020 | Group write |
S_IXGRP | 0010 | Group execute |
S_IROTH | 0004 | Others read |
S_IWOTH | 0002 | Others write |
S_IXOTH | 0001 | Others execute |
S_ISUID | 4000 | Set-user-ID |
S_ISGID | 2000 | Set-group-ID |
S_ISVTX | 1000 | Sticky bit |
Use bitwise AND operations to test individual permission bits.
topSize32
pub fn getSize32(self: SFtpFile) i32
Returns the file size in bytes as a 32-bit integer. Returns -1 when the size cannot be represented by a 32-bit integer. Use Size64 or SizeStr for larger values.
Size64
pub fn getSize64(self: SFtpFile) i64
Returns the file size in bytes as a 64-bit integer.
topSizeStr
pub fn getSizeStr(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8
Returns the file size in bytes as a base-10 string. This is the string representation of Size64 and is useful in environments where a 64-bit integer is inconvenient or unavailable.
Uid
pub fn getUid(self: SFtpFile) i32
Returns the numeric user ID associated with the file.
topVerboseLogging
pub fn getVerboseLogging(self: SFtpFile) bool
pub fn setVerboseLogging(self: SFtpFile, 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.
Version
pub fn getVersion(self: SFtpFile, allocator: Allocator) Allocator.Error![:0]u8