# 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) -> {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.

### AUTHORS

Jakob Cederlund - support@erlang.ericsson.se

ssh 0.9.6
Copyright © 1991-2007 Ericsson AB