ssh_sftp(3)

MODULE
ssh_sftp - SFTP client.

DESCRIPTION

This module implements an SFTP (SSH FTP) client. SFTP is a secure, encrypted file transfer service available for SSH.

The errors returned are from the SFTP server, and are often not posix error codes.

EXPORTS

connect(CM) -> {ok, Pid} | {error, Reason}
connect(Host, Options) -> {ok, Pid} | {error, Reason}
connect(Host, Port, Options) -> {ok, Pid} | {error, Reason}

    Types
        Host = string()
        CM = pid()
        Port = integer()
        Options = [{Option, Value}]
        Option = atom()
        Value = term()
        Reason = term()

    Connects to an SFTP server. A gen_server is started and returned if connection is successful. This server is used to perform SFTP commands on the server.

    For options, see ssh_cm:connect.

read_file(Server, File) -> {ok, Data} | {error, Reason}

    Types
        Server = pid()
        File = string()
        Data = binary()
        Reason = term()

    Reads a file from the server, and returns the data in a binary, like file:read_file/1.

write_file(Server, File, Iolist) -> ok | {error, Reason}

    Types
        Server = pid()
        File = string()
        Data = binary()
        Reason = term()

    Writes a file to the server, like file:write_file/2. The file is created if it's not there.

list_dir(Server, Path) -> {ok, Filenames} | {error, Reason}

    Types
        Server = pid()
        Path = string()
        Filenames = [Filename]
        Filename = string()
        Reason = term()

    Lists the given directory on the server, returning the filenames as a list of strings.

open(Server, File, Mode) -> {ok, Handle} | {error, Reason}

    Types
        Server = pid()
        File = string()
        Mode = [Modeflag]
        Modeflag = read | write | creat | trunc | append | binary
        Handle = term()
        Reason = term()

    Opens a file on the server, and returns a handle that is used for reading or writing.

opendir(Server, Path) -> {ok, Handle} | {error, Reason}

    Types
        Server = pid()
        Path = string()
        Reason = term()

    Opens a handle to a directory on the server, the handle is used for reading directory contents.

close(Server, Handle) -> ok | {error, Reason}

    Types
        Server = pid()
        Handle = term()
        Reason = term()

    Closes a handle to an open file or directory on the server.

read(Server, Handle, Len) -> {ok, Data} | eof | {error, Error}
pread(Server, Handle, Position, Length) -> {ok, Data} | eof | {error, Error}

    Types
        Server = pid()
        Handle = term()
        Position = integer()
        Len = integer()
        Data = string() | binary()
        Reason = term()

    Reads Len bytes from the file referenced by Handle. Returns {ok, Data}, or eof, or {error, Reason}. If the file is opened with binary, Data is a binary, otherwise it is a string.

    If the file is read past eof, only the remaining bytes will be read and returned. If no bytes are read, eof is returned.

    The pread function reads from a specified position, combining the position and read functions.

aread(Server, Handle, Len) -> {async, N} | {error, Error}
apread(Server, Handle, Position, Length) -> {async, N} | {error, Error}

    Types
        Server = pid()
        Handle = term()
        Position = integer()
        Len = integer()
        N = term()
        Reason = term()

    Reads from an open file, without waiting for the result. If the handle is valid, the function returns {async, N}, where N is a term guaranteed to be unique between calls of aread. The actual data is sent as a message to the calling process. This message has the form {async_reply, N, Result}, where Result is the result from the read, either {ok, Data}, or eof, or {error, Error}.

    The apread function reads from a specified position, combining the position and aread functions.

write(Server, Handle, Data) -> ok | {error, Error}
pwrite(Server, Handle, Position, Data) -> ok | {error, Error}

    Types
        Server = pid()
        Handle = term()
        Position = integer()
        Data = iolist()
        Reason = term()

    Write data to the file referenced by Handle. The file should be opened with write or append flag. Returns ok if successful and {error, Reason} otherwise.

    Typical error reasons are:

        ebadf:
            The file is not opened for writing.

        enospc:
            There is a no space left on the device.

awrite(Server, Handle, Data) -> ok | {error, Error}
apwrite(Server, Handle, Position, Data) -> ok | {error, Error}

    Types
        Server = pid()
        Handle = term()
        Position = integer()
        Len = integer()
        Data = binary()
        Reason = term()

    Writes to an open file, without waiting for the result. If the handle is valid, the function returns {async, N}, where N is a term guaranteed to be unique between calls of awrite. The result of the write operation is sent as a message to the calling process. This message has the form {async_reply, N, Result}, where Result is the result from the write, either ok, or {error, Error}.

    The apwrite writes on a specified position, combining the position and awrite operations.

position(Server, Handle, Location) -> {ok, NewPosition | {error, Error}

    Types
        Server = pid()
        Handle = term()
        Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof
        Offset = int()
        NewPosition = integer()
        Reason = term()

    Sets the file position of the file referenced by Handle. Returns {ok, NewPosition (as an absolute offset) if successful, otherwise {error, Reason}. Location is one of the following:

        Offset:
            The same as {bof, Offset}.

        {bof, Offset}:
            Absolute offset.

        {cur, Offset}:
            Offset from the current position.

        {eof, Offset}:
            Offset from the end of file.

        bof | cur | eof:
            The same as above with Offset 0.

read_file_info(Server, Name) -> {ok, FileInfo} | {error, Reason}
get_file_info(Server, Handle) -> {ok, FileInfo} | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Handle = term()
        FileInfo = record()
        Reason = term()

    Returns a file_info record from the file specified by Name or Handle, like file:read_file_info/2.

read_link_info(Server, Name) -> {ok, FileInfo} | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Handle = term()
        FileInfo = record()
        Reason = term()

    Returns a file_info record from the symbolic link specified by Name or Handle, like file:read_link_info/2.

write_file_info(Server, Name, Info) -> ok | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Info = record()
        Reason = term()

    Writes file information from a file_info record to the file specified by Name, like file:write_file_info.

read_link(Server, Name) -> {ok, Target} | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Target = string()
        Reason = term()

    Read the link target from the symbolic link specified by name, like file:read_link/1.

make_symlink(Server, Name, Target) -> ok | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Target = string()
        Reason = term()

    Creates a symbolic link pointing to Target with the name Name, like file:make_symlink/2.

rename(Server, OldName, NewName) -> ok | {error, Reason}

    Types
        Server = pid()
        OldName = string()
        NewName = string()
        Reason = term()

    Renames a file named OldName, and gives it the name NewName, like file:rename/2

delete(Server, Name) -> ok | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Reason = term()

    Deletes the file specified by Name, like file:delete/1

make_dir(Server, Name) -> ok | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Reason = term()

    Creates a directory specified by Name. Name should be a full path to a new directory. The directory can only be created in an existing directory.

del_dir(Server, Name) -> ok | {error, Reason}

    Types
        Server = pid()
        Name = string()
        Reason = term()

    Deletes a directory specified by Name. The directory should be empty, and

stop(Server) -> ok

    Types
        Server = pid()

    Stops the sftp session, closing the connection. Any open files on the server will be closed.

AUTHOR
Jakob Cederlund - support@erlang.ericsson.se