# ssh_sftp

### MODULE

ssh_sftp

### MODULE SUMMARY

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) ->
connect(Host, Options) ->
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: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.

ssh 1.0
Copyright © 1991-2008 Ericsson AB