Sagittarius Users' Reference

(rfc sftp) - SFTP library

This library provides SFTP programmatic operations.

Following example code describes how to use in high level.

(import (rfc sftp) (pp) (srfi :26))

(call-with-sftp-connection 
  "localhost"    ;; hostname
  "23"           ;; port number
  (lambda (conn)
    ;; read directory
    (pp (sftp-readdir conn "."))
    ;; only short names
    (pp (sftp-readdir-as-filenames conn "."))
    ;; only long names (usually POSIX 'ls -l' format)
    (pp (sftp-readdir-as-longnames conn "."))

    ;; retrieve a file as a bytevector
    (print (utf8->string (sftp-read! conn "reading/file" 
                                    (sftp-binary-receiver))))
    ;; store a file to local file directly
    (sftp-read conn "/a/file/path"
	(sftp-file-receiver "where/to/store" :options (file-options no-fail)))

    ;; upload a file
    (let ((handle (sftp-open conn "boo" 
                    (bitwise-ior +ssh-fxf-creat+ +ssh-fxf-write+))))
     (call-with-input-file "a/local/file" (cut sftp-write! conn handle <>)
                           :transcoder #f))

    ;; rename a file
    (sftp-rename! conn "boo" "foo")
    ;; remove a file
    (sftp-remove! conn "foo")
    ;; create a directory
    (sftp-mkdir! conn "boo")
    ;; remove a directory
    (sftp-rmdir! conn "boo")

    ;; create a symbolic link
    (pp (sftp-symlink! conn "/tmp" "tmp"))
    ;; get a actual path of symbolic link
    (pp (sftp-readlink conn "tmp"))
    ;; get a real path. (usually an absolute path)
    (pp (sftp-realpath conn "../")))
  :username "username" :password "password")

High level APIs

Function call-with-sftp-connection server port proc . opts

server and port must be string, indicating hostname, port number/service name respectively. proc must accept one argument.

Creates a SFTP connection, executes given proc with the connection and closes it after the execution.

The opts will be passed to make-client-sftp-connection.

Function sftp-open conn filename pflags

conn must be a SFTP connection. filename must be a string. pflags must be an exact integer which value must be the result of inclusive or of following values;

Constant +ssh-fxf-read+

Open the given filename read mode.

Constant +ssh-fxf-write+

Open the given filename write mode.

Constant +ssh-fxf-append+

Open the given filename append mode.

Constant +ssh-fxf-creat+

Creates the given filename if it doesn't exist.

Constant +ssh-fxf-trunc+

Truncate the given filename if it exists. +ssh-fxf-creat+ must be specified as well.

Constant +ssh-fxf-excl+

Raises and error filename if it exists. +ssh-fxf-creat+ must be specified as well.

If filename opened successfully, the procedure will return a handle.

Function sftp-close conn handle

conn must be a SFTP connection.

Closes given handle created by sftp-open.

Function sftp-read conn handle/filename receiver :key (offset 0) buffer-size

conn must be a SFTP connection. handle/filename must be either a handle or string. receiver must be a procedure accepts 2 arguments, offset which is an integer and data which is a binary input port, respectively.

Reads the given handle/filename content from the server and call receiver with the returned value. When it reaches the end of file, then it will pass -1 as offset and eof value as data.

The keyword argument offset specifies starting where to read. It is useful to read only diff.

The keyword argument buffer-size specifies how many bytes it tries to read in one read call. The default value is 1048576 (1MB). This value is only an indication so that server can decide actual data length to send.

The return value of this procedure is the result value of receiver.

Receiver must return 2 values, one if processed octet count and the other one is result value. Following is the sftp-binary-receiver definition;

(define (sftp-binary-receiver)
  (let-values (((out extract) (open-bytevector-output-port)))
    (lambda (offset data)
      (if (< offset 0)
          (values -1 (extract))
          (values (copy-binary-port out data) #f)))))

Function sftp-binary-receiver

Creates a in memory receiver for sftp-read.

Function sftp-file-receiver filename :key options

Creates a file receiver for sftp-read.

The keyword argument option must be created by file-options. By default no option.

Function sftp-oport-receiver output-port

output-port must be a binary output port.

Creates a output port receiver for sftp-read.

Function sftp-write! conn handle input-port :key (offset 0) buffer-size

conn must be a SFTP connection. handle must be a handle. input-port must be a binary input port.

Reads the content from given input-port and writes it to given handle.

The keyword argument offset specifies where to write. This is useful to write a file separately or simply append.

The keyword argument buffer-size specifies how many bytes of data the procedure sends in one packet. The default value is 131072 (128KB). The RFC defines the minimum value 32768 (3KB) so it is safe to use the value. However too small buffer size makes writing extremely slow so we use a bit larger value to make performance better. If you meet a problem with writing a file, consider to change this size.

Function sftp-exists? conn filename

conn must be a SFTP connection. filename must be a string indicating existing filename.

Checks if the given filename exists.

Function sftp-remove! conn filename

conn must be a SFTP connection. filename must be a string indicating existing filename.

Removes the given filename. It is an error if the file doesn't exist or user doesn't have proper permission to remove.

The result value is raw SFTP status object.

Function sftp-rename! conn oldpath newpath

conn must be a SFTP connection. oldpath and newpath must be strings indicating existing path.

Renames the given oldpath to newpath. It is an error if the file doesn't exist or user doesn't have proper permission to rename.

The result value is raw SFTP status object.

Function sftp-mkdir! conn path

conn must be a SFTP connection. path must be a string.

Creates the given path directory. It is an error if the directory exists or user doesn't have proper permission to create.

The result value is raw SFTP status object.

Function sftp-rmdir! conn path

conn must be a SFTP connection. path must be a string.

Removes the given path directory. It is an error if the directory doesn't exists, user doesn't have proper permission to create or the directory isn't empty.

The result value is raw SFTP status object.

Function sftp-opendir conn path

conn must be a SFTP connection. path must be a string indicating existing path.

Opens the given path directory and returns its handle.

Function sftp-readdir conn handle/path

conn must be a SFTP connection. handle/path must be either a handle opened by sftp-opendir or a string indicating existing path.

Reads the given handle/path and returns the list of contents. The content is an object of <sftp-name> which has filename, longnameand attribute slots.

Function sftp-readdir-as-filenames conn handle/path

Function sftp-readdir-as-longnames conn handle/path

conn must be a SFTP connection. handle/path must be either a handle opened by sftp-opendir or a string indicating existing path.

Calls sftp-readdir and strips out the result object to string by calling (slot-ref _c_ 'filename) or (slot-ref _c_ 'longname) respectively.

Mid level APIs

Mid level APIs are changed since 0.7.8. The changes are not backward compatible, so if you are using 0.7.7 API and move to 0.7.8, please be aware.

Function make-client-sftp-connection server port

Creates a SFTP connection object.

Function open-client-sftp-connection! sftp-connection :key (authenticate #f