File Transfer (SFTP)¶

SSHClient speaks SFTP version 3 over the sftp subsystem. Each operation opens an SFTP channel, performs the transfer, and closes the channel; the SSH connection stays up throughout.

Relative remote paths are relative to the remote user's home directory (that is where OpenSSH's SFTP server starts). Paths and filenames are UTF-8 end to end.

Downloading — GetFile¶

      r←c.GetFile '/var/log/app.log' '/tmp/app.log'   ⍝ (Remote Local)
      r←c.GetFile 'report.pdf'                        ⍝ local name = basename
      r.Data                                          ⍝ the local path written

The transfer is binary-exact; existing local files are overwritten. On failure (rc ¯1) no partial local file is left behind for a missing remote file.

Uploading — PutFile¶

      r←c.PutFile '/tmp/data.csv' 'uploads/data.csv'  ⍝ (Local Remote)
      r←c.PutFile 'data.csv'                          ⍝ remote name = basename

The remote file is created (or truncated) and written in 30,000-byte chunks. A missing local file is reported before anything touches the server.

Listing — ListDir¶

      r←c.ListDir 'projects'
      r.Data                      ⍝ vector of namespaces, one per entry
      {⍵.(name size)} ¨r.Data

Each entry namespace has name, longname (the ls -l-style line), and the numeric attributes size, uid, gid, permissions, atime, mtime. The . and .. entries are included, as the server sends them.

Attributes — Stat¶

      r←c.Stat 'projects/readme.md'
      r.Data.(size permissions mtime)
1042 33188 1756290000

permissions is the full POSIX mode word (e.g. 33188 = regular file, 0o644); mtime/atime are Unix timestamps. Fields the server does not send are 0.

Errors¶

SFTP failures come back as rc ¯1 with the server's own message:

      (c.Stat 'no-such-file').msg
SFTP stat failed: No such file

An SFTP error never kills the SSH connection — the same client can carry on with further Exec or SFTP calls.