GitHub

SFTP

A subset of the SFTP API is wrapped and available in LibSSH.jl. See the SFTP example for an example of basic usage.

Warning

When it comes to handling paths, the library currently assumes that the server is running on a *NIX system. Some functions will not work when connecting to a Windows server.

Unlike the rest of the API, the SFTP C functions are blocking and only work with blocking Session's. This means that the library has to lock the session while calling them and no other operations (blocking or unblocking) can occur while they're being called. In practice this restriction may not be too onerous since most calls shouldn't take long anyway, and the read/write implementations use SFTP's asynchronous IO API so they shouldn't block for long. If it's critical that SFTP operations don't interfere with other operations (e.g. port forwarding) a workaround would be to open a separate Session for SFTP.

Note that we call all blocking C functions using @threadcall so that they don't block the scheduler, hence as a programmer you don't need to worry about them hogging a whole thread until they complete.

SftpSession

LibSSH.SftpSession — Method
SftpSession(session::LibSSH.Session) -> LibSSH.SftpSession

Create a SftpSession from an existing Session.

Throws

  • ArgumentError: If session isn't open.
  • LibSSHException: If creating the SFTP session fails.
source
Base.close — Method
close(sftp::LibSSH.SftpSession)

Close an SftpSession. This will also close any open files.

source
Base.isopen — Method
isopen(sftp::LibSSH.SftpSession) -> Bool

Check if sftp is open.

source
Base.Filesystem.readdir — Method
readdir(
    dir::AbstractString,
    sftp::LibSSH.SftpSession;
    only_names,
    join,
    sort
) -> Union{Vector{String}, Vector{LibSSH.SftpAttributes}}

Read the contents of a remote directory. By default this will behave the same as Base.readdir() and return a list of names, but if only_names=false it will return a list of SftpAttributes. The join and sort arguments are the same as in Base.readdir() but only apply when only_names=true.

Throws

  • ArgumentError: If sftp is closed.
  • SftpException: If retrieving the directory contents failed.
source
Base.Filesystem.rm — Method
rm(
    path::AbstractString,
    sftp::LibSSH.SftpSession;
    attrs,
    recursive,
    force
)

Delete remote file and directories. This has the same behaviour as Base.rm(), and the recursive and force options mean the same thing.

Internally the function will call Base.stat(::String, ::SftpSession) to determine how to delete path, but if you already have the result of that it can be passed to the attrs keyword argument to avoid the extra blocking call.

Throws

  • ArgumentError: If sftp is closed.
  • Base.IOError: If path is a non-empty directory and recursive=false.
  • SftpException if deletion fails for some reason.
source
Base.Filesystem.mkdir — Method
mkdir(
    path::AbstractString,
    sftp::LibSSH.SftpSession;
    mode
) -> AbstractString

Make a remote directory. This behaves in exactly the same way as Base.mkdir().

Throws

  • ArgumentError: If sftp is closed.
  • SftpException: If making the directory fails.
source
Base.Filesystem.mkpath — Method
mkpath(
    path::AbstractString,
    sftp::LibSSH.SftpSession;
    mode
) -> AbstractString

Create a remote path. This behaves in exactly the same way as Base.mkpath().

Throws

  • ArgumentError: If sftp is closed.
  • SftpException: If making the path fails for some reason, such as part of path being an existing file.
source
Base.Filesystem.mv — Method
mv(
    src::AbstractString,
    dst::AbstractString,
    sftp::LibSSH.SftpSession;
    force
) -> AbstractString

Move src to dst remotely. Has the same behaviour as Base.mv().

Throws

  • ArgumentError: If sftp is closed.
  • SftpException: If the operation fails for some reason.
source
Base.stat — Method
stat(
    path::String,
    sftp::LibSSH.SftpSession
) -> LibSSH.SftpAttributes

Get information about the file object at path as a SftpAttributes.

Note: the Demo.DemoServer does not support setting all of these properties.

Throws

  • ArgumentError: If sftp is closed.
  • SftpException: If retrieving the file object information failed (e.g. if the path doesn't exist).
source
LibSSH.get_extensions — Method
get_extensions(
    sftp::LibSSH.SftpSession
) -> Dict{String, String}

Get a list of supported server extensions and their versions.

Throws

  • ArgumentError: If sftp is closed.
source
LibSSH.get_limits — Method
get_limits(
    sftp::LibSSH.SftpSession
) -> LibSSH.lib.sftp_limits_struct

Get the server limits. The returned object has the following fields:

  • max_packet_length
  • max_read_length
  • max_write_length
  • max_open_handles

Throws

  • ArgumentError: If sftp is closed.
  • SftpException: If getting the limits failed.
source
LibSSH.get_error — Method
get_error(sftp::LibSSH.SftpSession) -> LibSSH.SftpError

Get the current error code for sftp.

Throws

  • ArgumentError: If sftp is closed.
source

SftpFile

LibSSH.SftpFile — Type
mutable struct SftpFile

  • ptr::Union{Nothing, Ptr{LibSSH.lib.sftp_file_struct}}

  • sftp::LibSSH.SftpSession

  • path::String

  • fullpath::String

  • flags::@NamedTuple{read::Bool, write::Bool, create::Bool, truncate::Bool, append::Bool, exclusive::Bool}

Represents a remote file. This object must be explicitly closed with close() or it will leak memory. Don't create one of these yourself, use Base.open(::String, ::SftpSession).

source
Base.open — Method
open(
    path::String,
    sftp::LibSSH.SftpSession;
    read,
    write,
    create,
    truncate,
    append,
    exclusive,
    mode
) -> LibSSH.SftpFile

Open a remote file. Most of the keyword arguments behave in exactly the same way as their counterparts in Base.open(::String), except for exclusive and mode, which are unique to this method:

  • exclusive: Open a file with the O_EXCL flag.
  • mode: If create=true and the file doesn't exist, it will be created with permissions (mode & ~umask).

Throws

  • ArgumentError: If sftp is closed.
  • SftpException: If opening the file fails.
source
Base.open — Method
open(
    f::Function,
    path::String,
    sftp::LibSSH.SftpSession;
    kwargs...
) -> Any

Do-constructor for SftpFile's, the function f will be called like f(file).

source
Base.close — Method
close(file::LibSSH.SftpFile)

Close file. This must be called explicitly, and not in a finalizer because it may cause a task switch.

source
Base.read — Method
read(
    filename::AbstractString,
    sftp::LibSSH.SftpSession
) -> Vector{UInt8}
source
Base.read — Method
read(file::LibSSH.SftpFile, _::Type{String}) -> String

Read the whole file as a String.

source
Base.read — Method
read(
    filename::AbstractString,
    sftp::LibSSH.SftpSession,
    _::Type{String}
) -> String
source
Base.read! — Method
read!(
    file::LibSSH.SftpFile,
    out::Vector{UInt8}
) -> Vector{UInt8}

Read length(out) bytes from the remote SftpFile into out. This uses libssh's asynchronous IO functions under the hood so it may launch multiple parallel requests.

Throws

  • ArgumentError: If file is closed.
  • SftpException: If reading failed.
source
Base.write — Method
write(file::LibSSH.SftpFile, data::DenseVector) -> Any

Write data to the remote file and returns the number of bytes written. This uses libssh's asynchronous IO API so it may launch multiple parallel requests.

Throws

  • ArgumentError: If file is closed.
  • SftpException: If writing fails.
source
Base.isopen — Method
isopen(file::LibSSH.SftpFile) -> Bool

Check if file is open.

source
Base.isreadable — Method
isreadable(file::LibSSH.SftpFile) -> Bool

Check if file is open and readable.

source
Base.isreadonly — Method
isreadonly(file::LibSSH.SftpFile) -> Bool

Check if file is open and readonly.

source
Base.iswritable — Method
iswritable(file::LibSSH.SftpFile) -> Bool

Check if file is open and writable.

source
Base.position — Method
position(file::LibSSH.SftpFile) -> UInt64

Get the current position in file.

Throws

  • ArgumentError: If file is closed.
source
Base.seek — Method
seek(file::LibSSH.SftpFile, pos::Integer)

Go to position pos in file. Note that this will not validate pos.

Throws

  • ArgumentError: If file is closed.
source

File type helpers

Other types

LibSSH.SftpAttributes — Type
mutable struct SftpAttributes

Attributes of remote file objects. This has the following (read-only) properties:

  • name::String
  • longname::String
  • flags::UInt32
  • type::UInt8
  • size::UInt64
  • uid::UInt32
  • gid::UInt32
  • owner::String
  • group::String
  • permissions::UInt32
  • atime64::UInt64
  • atime::UInt32
  • atime_nseconds::UInt32
  • createtime::UInt64
  • createtime_nseconds::UInt32
  • mtime64::UInt64
  • mtime::UInt32
  • mtime_nseconds::UInt32
  • acl::String
  • extended_count::UInt32
  • extended_type::String
  • extended_data::String
source
LibSSH.SftpError — Type
primitive type SftpError <: Enum{Int32} 32

Enum for possible SFTP error codes. Note that despite its name, SftpError_Ok does not indicate an error.

  • SftpError_Ok
  • SftpError_Eof
  • SftpError_NoSuchFile
  • SftpError_PermissionDenied
  • SftpError_GenericFailure
  • SftpError_BadMessage
  • SftpError_NoConnection
  • SftpError_ConnectionLost
  • SftpError_OpUnsupported
  • SftpError_InvalidHandle
  • SftpError_NoSuchPath
  • SftpError_FileAlreadyExists
  • SftpError_WriteProtect
  • SftpError_NoMedia
source
LibSSH.SftpException — Type
struct SftpException <: Exception

  • msg::String

  • path::Union{Nothing, String}

  • error_code::LibSSH.SftpError

  • session_error::String

  • session_userhost::String

Represents an error from the SFTP subsystem.

source

When an SftpException is printed it will be displayed like this:

julia> import LibSSH as ssh
julia> ssh.SftpException("Failure", "/tmp/foo", ssh.SftpError_GenericFailure, "SFTP failed", "foo@bar")SftpException: Failure (SftpError_GenericFailure)
  Session error: 'SFTP failed'
  User/host: foo@bar
  Remote path: /tmp/foo

Note that the SFTP subsystem doesn't always set an error on the Session, so take the Session error with a grain of salt.