---
product: Chilkat
product_version: 11.7.0
language: tcl
language_label: Tcl
class: SFtpDir
license: bundle
deprecated: false
reference_html: https://www.chilkatsoft.com/refdoc/tclSFtpDirRef.html
---
# Chilkat SFtpDir — Tcl — v11.7.0

> Chilkat 11.7.0 · language=tcl · class=SFtpDir
> Other versions: replace `11.7.0` in this URL. Other languages: `https://www.chilkatsoft.com/ai-docs/v/11.7.0/<lang>/classes/SFtpDir.md`.
> Language-wide rules (install, unlock, error model, strings/bytes): `https://www.chilkatsoft.com/ai-docs/v/11.7.0/tcl/guide.md`.

## Purpose

**Inspect, sort, and iterate an SFTP directory listing.**

`Chilkat.SFtpDir` represents a directory listing returned by an SFTP operation. It provides the original path used to fetch the listing, the number of files and subdirectories found, methods for retrieving filenames or full `SFtpFile` entry details by index, sorting support, and a way to load a completed asynchronous directory-listing result.

**Directory listing object**

Holds the files and subdirectories returned from an SFTP directory-read operation.

**Original path tracking**

Use `OriginalPath` to see the remote path that was requested when the directory listing was created.

**Entry count**

Read `NumFilesAndDirs` to determine how many directory entries are available for iteration.

**Filename access**

Use `GetFilename` to retrieve the name of an entry by zero-based index.

**Full entry details**

Use `FileAt` to populate an `SFtpFile` object with metadata for a selected file or subdirectory.

**Sorting and async results**

Sort entries by filename, timestamps, or size, and load directory listings returned from completed async tasks.

**Common pattern:** Use a `Chilkat.SFtp` object to open or read a remote directory, then use the returned `SFtpDir` object to inspect `NumFilesAndDirs`, optionally call `Sort`, and loop from index `0` through the final entry. Use `GetFilename` when only names are needed, or `FileAt` when the application needs the full `SFtpFile` metadata for each entry.

## Object creation, unlocking and error handling

**Object Creation**

```tcl
# 'this' is not a keyword in Tcl. It can freely be used as a variable name.
set this [new CkSFtpDir]
```

Call `Global.UnlockBundle` once at the start of the program, before using this or any other Chilkat class. Any string unlocks a fully functional 30-day trial; a purchased unlock code is used in production. See `guide.md` for the exact code in Tcl.

How failure is reported depends on the method's return type and is stated in the note under each method below. In every case the diagnostic text is in the `LastErrorText` property of the object whose method was called.

## Members common to every Chilkat class

Documented once per language in `common-members.md`; listed here so this page is self-contained.

| Property | Signature | Access | Meaning |
|---|---|---|---|
| `DebugLogFilePath` | `string # ckStr is a CkString CkSFtpDir_get_DebugLogFilePath $this $ckStr set strVal [CkSFtpDir_get_debugLogFilePath $this] CkSFtpDir_put_DebugLogFilePath $this $strVal` | read/write | If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. |
| `LastErrorHtml` | `string # ckStr is a CkString CkSFtpDir_get_LastErrorHtml $this $ckStr set strVal [CkSFtpDir_get_lastErrorHtml $this]` | read-only | Provides HTML-formatted information about the last called method or property. |
| `LastErrorText` | `string # ckStr is a CkString CkSFtpDir_get_LastErrorText $this $ckStr set strVal [CkSFtpDir_get_lastErrorText $this]` | read-only | Provides plain text information about the last called method or property. |
| `LastErrorXml` | `string # ckStr is a CkString CkSFtpDir_get_LastErrorXml $this $ckStr set strVal [CkSFtpDir_get_lastErrorXml $this]` | read-only | Provides XML-formatted information about the last called method or property. |
| `LastMethodSuccess` | `boolean 1/0 set boolVal [CkSFtpDir_get_LastMethodSuccess $this] CkSFtpDir_put_LastMethodSuccess $this $boolVal` | read/write | Indicates the success or failure of the most recent method call: `1` means success, `0` means failure. |
| `Utf8` | `boolean 1/0 set boolVal [CkSFtpDir_get_Utf8 $this] CkSFtpDir_put_Utf8 $this $boolVal` | read/write | When set to `1`, all `string` arguments and return values are interpreted as UTF-8 strings. |
| `VerboseLogging` | `boolean 1/0 set boolVal [CkSFtpDir_get_VerboseLogging $this] CkSFtpDir_put_VerboseLogging $this $boolVal` | read/write | If set to `1`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. |
| `Version` | `string # ckStr is a CkString CkSFtpDir_get_Version $this $ckStr set strVal [CkSFtpDir_get_version $this]` | read-only | Version of the component/library, such as "10.1.0" |

## Member index

| Member | Kind | Signature |
|---|---|---|
| `NumFilesAndDirs` | property, read-only | `integer set intVal [CkSFtpDir_get_NumFilesAndDirs $this]` |
| `OriginalPath` | property, read-only | `string # ckStr is a CkString CkSFtpDir_get_OriginalPath $this $ckStr set strVal [CkSFtpDir_get_originalPath $this]` |
| `FileAt` | method | `# index is an integer # fileObj is a CkSFtpFile set status [CkSFtpDir_FileAt $this $index $fileObj]` |
| `GetFilename` | method | `# index is an integer # outStr is a CkString (output) set status [CkSFtpDir_GetFilename $this $index $outStr] set retStr [CkSFtpDir_getFilename $this $index]` |
| `LoadTaskResult` | method | `# task is a CkTask set status [CkSFtpDir_LoadTaskResult $this $task]` |
| `Sort` | method | `# field is a string # ascending is a boolean CkSFtpDir_Sort $this $field $ascending` |

Deprecated members are listed at the end of this file with their replacements; do not use them in new code.

## Properties

### SFtpDir.NumFilesAndDirs

`Chilkat 11.7.0 · tcl · SFtpDir · NumFilesAndDirs · property · read-only`

```tcl
integer
set intVal [CkSFtpDir_get_NumFilesAndDirs $this]
```

Returns the number of entries in this directory listing.

The count includes every item returned by the server, such as regular files, directories, symbolic links, and special entries. Valid zero-based indexes range from `0` through `NumFilesAndDirs - 1`.

### SFtpDir.OriginalPath

`Chilkat 11.7.0 · tcl · SFtpDir · OriginalPath · property · read-only`

```tcl
string
# ckStr is a CkString

CkSFtpDir_get_OriginalPath $this $ckStr

set strVal [CkSFtpDir_get_originalPath $this]
```

Returns the original remote path used to create this directory listing.

This is the same path string that was supplied to the SFTP directory-open operation. It identifies the requested directory and is retained with the listing for later reference.

## Methods

### SFtpDir.FileAt

`Chilkat 11.7.0 · tcl · SFtpDir · FileAt · method · since 11.0.0`

```tcl
# index is an integer

# fileObj is a CkSFtpFile

set status [CkSFtpDir_FileAt $this $index  $fileObj]
```

Copies the metadata for the directory entry at the zero-based `index` into `fileObj`.

The first entry is at index `0`. Use `NumFilesAndDirs` to determine the number of available entries.

The populated `SFtpFile` object provides the entry name, type, size, timestamps, ownership, permissions, and any additional attributes supplied by the SFTP server.

Use `GetFilename` when only the entry name is needed.

Returns 1 for success, 0 for failure.

### SFtpDir.GetFilename

`Chilkat 11.7.0 · tcl · SFtpDir · GetFilename · method`

```tcl
# index is an integer

# outStr is a CkString (output)

set status [CkSFtpDir_GetFilename $this $index $outStr]

set retStr [CkSFtpDir_getFilename $this $index]
```

Returns the filename of the directory entry at the zero-based `index`.

The first entry is at index `0`. Use `NumFilesAndDirs` to determine the number of available entries.

Use `FileAt` when the application needs the full `SFtpFile` metadata rather than only the entry name.

Returns 1 for success, 0 for failure.

### SFtpDir.LoadTaskResult

`Chilkat 11.7.0 · tcl · SFtpDir · LoadTaskResult · method · since 9.5.0.52`

```tcl
# task is a CkTask

set status [CkSFtpDir_LoadTaskResult $this $task]
```

Loads this `SFtpDir` object from the result of a completed asynchronous `Task`.

The task must represent an asynchronous SFTP operation whose result is a directory listing. Call this method after the task has finished to transfer the listing data into the current object.

Returns 1 for success, 0 for failure.

### SFtpDir.Sort

`Chilkat 11.7.0 · tcl · SFtpDir · Sort · method · since 9.5.0.79`

```tcl
# field is a string

# ascending is a boolean

CkSFtpDir_Sort $this $field  $ascending
```

Reorders the files and subdirectories in this listing according to `field`.

Set `ascending` to `1` for ascending order or `0` for descending order. The new order is used by index-based methods such as `GetFilename` and `FileAt`.

| field | Sort key |
| :--- | :--- |
| `filename` | Filename using the normal case-sensitive comparison. |
| `filenameNoCase` | Filename using a case-insensitive comparison. |
| `lastModifiedTime` | Last-modified date and time. |
| `lastAccessTime` | Last-access date and time. |
| `lastCreateTime` | Creation date and time. |
| `size` | Entry size in bytes. |

## Deprecated members — do not use in new code

| Member | Kind | Deprecated in | Use instead |
|---|---|---|---|
| `GetFileObject` | method | before 11.6.1 | `FileAt` |

## Related classes

[`SFtpFile`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/tcl/classes/SFtpFile.md), [`Task`](https://www.chilkatsoft.com/ai-docs/v/11.7.0/tcl/classes/Task.md)

