@c -*-texinfo-*-
@c This file is part of Guile-SSH Reference Manual.
@c Copyright (C) 2015-2022 Artyom V. Poptsov
@c See the file guile-ssh.texi for copying conditions.

@node SFTP
@section SFTP

@cindex SFTP
@cindex file transfer

The @code{(ssh sftp)} module provides procedures for working with @abbr{SFTP,
Secure File Transfer Protocol}.

@c -----------------------------------------------------------------------------
@subsection SFTP Session

@deffn {Scheme Procedure} make-sftp-session ssh-session
Make a new SFTP session using a @var{ssh-session}, initialize the session with
a server.  Return initialized SFTP session or throw @code{guile-ssh-error}
exception on an error.
@end deffn

@deffn {Scheme Procedure} sftp-session? x
Return @code{#t} if @var{x} is a SFTP session, @code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} sftp-get-session sftp-session
Get the parent SSH session for a @var{sftp-session}.
@end deffn

@deffn {Scheme Procedure} sftp-get-error sftp-session
Get the last SFTP error from a @var{sftp-session}.  Return the error name as a
symbol, or throw @code{guile-ssh-error} on if an error occurred in the
procedure itself.

The procedure returns one of the following values:

@table @samp
@item fx-ok
No error.
@item fx-eof
End-of-file encountered.
@item fx-no-such-file
File doesn't exist.
@item fx-permission-denied
Permission denied.
@item fx-failure
Generic failure.
@item fx-bad-message
Garbage received from the server.
@item fx-no-connection
No connection has been set up.
@item fx-connection-lost
There was a connection, but we lost it.
@item fx-op-unsupported
Operation not supported by the server.
@item fx-invalid-handle
Invalid file handle.
@item fx-no-such-path
No such file or directory path exists.
@item fx-file-already-exist
An attempt to create an already existing file or directory has been made.
@item fx-write-protect
We are trying to write on a write-protected filesystem.
@item fx-no-media
No media in remote drive.
@end table
@end deffn

@deffn {Scheme Procedure} sftp-mkdir sftp-session dirname [mode=#o777]
Create a directory @var{dirname} using a @var{sftp-session} with a @var{mode}.
If the @var{mode} is omitted, the current umask value is used.
@end deffn

@deffn {Scheme Procedure} sftp-rmdir sftp-session dirname
Remove a directory @var{dirname}.  Throw @code{guile-ssh-error} on an error.
Return value is undefined.
@end deffn

@deffn {Scheme Procedure} sftp-mv sftp-session source dest
Move or rename a file @var{source} into a @var{dest}.  Throw
@code{guile-ssh-error} on an error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} sftp-symlink sftp-session target dest
Create a symbolic link to a @var{target} in a @var{dest}.  Throw
@code{guile-ssh-error} on an error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} sftp-readlink sftp-session path
Read the value of a symbolic link pointed by a @var{path}.  Return the value
or @code{#f} on an error.
@end deffn

@deffn {Scheme Procedure} sftp-chmod sftp-session filename mode
Change permissions of a remote @var{filename} using @var{sftp-session}.
Permissions are set to @code{mode & ~umask}.  Throw @code{guile-ssh-error} on
an error.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} sftp-unlink sftp-session filename
Unlink (delete) a remote @var{filename} using @var{sftp-session}.  Throw
@code{guile-ssh-error} on an error.  Return value is undefined.
@end deffn

@c -----------------------------------------------------------------------------
@subsubsection Low-Level API

@deffn {Scheme Procedure} %make-sftp-session ssh-session
Make a new SFTP session using a @var{ssh-session} without initialization of
the session with a server.  Throw @code{guile-ssh-error} exception on an
error.

Note that you should call @code{%sftp-init} on the returned SFTP session before
using it.
@end deffn

@deffn {Scheme Procedure} %sftp-init sftp-session
Initialize a @var{sftp-session} with the server.  Throw @code{guile-ssh-error}
exception on an error, return value is undefined.
@end deffn

@c -----------------------------------------------------------------------------
@subsection SFTP File

Remote files are represented as regular Guile ports that allow random access
(@pxref{Input and Output,,, guile, The GNU Guile Reference Manual}.)

@deffn {Scheme Procedure} sftp-open sftp-session filename flags [mode=#o666]
Open a remote @var{filename} using an @var{sftp-session}, return an open file
port.  Throw @code{guile-ssh-error} on an error.
@end deffn

@deffn {Scheme Procedure} sftp-file? x
Return @code{#t} if @var{x} is an SFTP file port, @code{#f} otherwise.
@end deffn

@c -----------------------------------------------------------------------------
@subsection SFTP Directory
@cindex directory traversal

Those procedures allow to read directory contents on the remote side.

@deffn {Scheme Procedure} sftp-dir? x
Check if an @var{x} is an SFTP directory instance. Return @code{#t} if it is,
@code{#f} otherwise.
@end deffn

@deffn {Scheme Procedure} sftp-dir-open sftp-session path
Open a remote directory with the specified @var{path} using
@var{sftp-session}. Return an SFTP directory as opaque object.
@end deffn

@deffn {Scheme Procedure} sftp-dir-open-stream sftp-session path
Open a remote directory with the specified @var{path} using
@var{sftp-session}. Return an ice-9 stream of SFTP file attributes.

Usage example:

@lisp
(use-modules (ice-9 streams)
             (ice-9 pretty-print)
             (ssh session)
             (ssh auth)
             (ssh sftp))

(define (main args)
  (let ((session (make-session #:host "example.org"
                               #:user "avp")))
    (connect! session)
    (userauth-agent! session)
    (let* ((sftp-session (make-sftp-session session))
           (stream       (sftp-dir-open-stream sftp-session "/tmp/")))
      (stream-for-each (lambda (attrs)
                         (pretty-print attrs))
                       stream))))
@end lisp
@end deffn

@deffn {Scheme Procedure} sftp-dir-path sftp-directory
Get the path associated with an @var{sftp-directory}.
@end deffn

@deffn {Scheme Procedure} sftp-dir-session sftp-directory
Get the parent SFTP session for an @var{sftp-directory}.
@end deffn

@deffn {Scheme Procedure} sftp-dir-close sftp-directory
Close an @var{sftp-directory}.  Return value is undefined.
@end deffn

@deffn {Scheme Procedure} sftp-dir-eof? sftp-directory
CHeck if an @var{sftp-directory} pointed to an EOF object.
@end deffn

@deffn {Scheme Procedure} sftp-dir-read sftp-directory
Read an @var{sftp-directory}. Return an alist with the next directory
attributes.
@end deffn

@c -----------------------------------------------------------------------------
@subsection High-level operations on remote files

@deffn {Scheme Procedure} call-with-remote-input-file sftp-session filename proc
Call a @var{proc} with a remote file port opened for input using an
@var{sftp-session}.  @var{proc} should be a procedure of one argument,
@var{filename} should be a string naming a file.  The behaviour is unspecified
if a file already exists.

The procedure calls @var{proc} with one argument: the port obtained by opening
the named remote file for input.

If the procedure returns, then the port is closed automatically and the values
yielded by the procedure are returned.  If the procedure does not return, then
the port will not be closed automatically unless it is possible to prove that
the port will never again be used for a read or write operation.
@end deffn

@deffn {Scheme Procedure} call-with-remote-output-file sftp-session filename proc
Call a @var{proc} with a remote file port opened for output using an
@var{sftp-session}.  @var{proc} should be a procedure of one argument,
@var{filename} should be a string naming a file.  The behaviour is unspecified
if a file already exists.

The procedure calls @var{proc} with one argument: the port obtained by opening
the named remote file for output.

If the procedure returns, then the port is closed automatically and the values
yielded by the procedure are returned.  If the procedure does not return, then
the port will not be closed automatically unless it is possible to prove that
the port will never again be used for a read or write operation.
@end deffn

@deffn {Scheme Procedure} with-input-from-remote-file sftp-session filename thunk
@var{thunk} must be a procedure of no arguments, and @var{filename} must be a
string naming a file.  The file must already exist. The file is opened for
input, an input port connected to it is made the default value returned by
@code{current-input-port}, and the @var{thunk} is called with no arguments.
When the @var{thunk} returns, the port is closed and the previous default is
restored.  Returns the values yielded by @var{thunk}.  If an escape procedure
is used to escape from the continuation of these procedures, their behavior is
implementation dependent.

Example:

@lisp
(define (rcat user host filename)
  "Print contents of a remote file on a HOST pointed by a FILENAME to
stdout."
  (let ((session (make-session #:user user #:host host)))

    ;; Connect to an SSH server.
    (connect! session)

    (authenticate-server session)

    ;; Authenticate with an SSH server using a SSH agent.
    (userauth-agent! session)

    (let ((sftp-session (make-sftp-session session)))

      ;; Read read a file line-by-line and print it to stdout.
      (with-input-from-remote-file sftp-session filename
        (lambda ()
          (do ((line (read-line) (read-line)))
              ((eof-object? line))
            (write-line line)))))))
@end lisp

@end deffn

@deffn {Scheme Procedure} with-output-to-remote-file sftp-session filename thunk
@var{thunk} must be a procedure of no arguments, and @var{filename} must be a
string naming a file.  The effect is unspecified if the file already exists.
The file is opened for output, an output port connected to it is made the
default value returned by @code{current-output-port}, and the @var{thunk} is
called with no arguments.  When the @var{thunk} returns, the port is closed
and the previous default is restored.  Returns the values yielded by
@var{thunk}.  If an escape procedure is used to escape from the continuation
of these procedures, their behavior is implementation dependent.
@end deffn

@c Local Variables:
@c TeX-master: "guile-ssh.texi"
@c End: