.TH ssh_sftp 3 "ssh  0.9.9.6" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
ssh_sftp \- SFTP client\&.
.SH DESCRIPTION
.LP
This module implements an SFTP (SSH FTP) client\&. SFTP is a secure, encrypted file transfer service available for SSH\&.
.LP
The errors returned are from the SFTP server, and are often not posix error codes\&.

.SH EXPORTS
.LP
.B
connect(CM) -> {ok, Pid} | {error, Reason}
.br
.B
connect(Host, Options) -> {ok, Pid} | {error, Reason}
.br
.B
connect(Host, Port, Options) -> {ok, Pid} | {error, Reason}
.br
.RS
.TP
Types
Host = string()
.br
CM = pid()
.br
Port = integer()
.br
Options = [{Option, Value}]
.br
Option = atom()
.br
Value = term()
.br
Reason = term()
.br
.RE
.RS
.LP
Connects to an SFTP server\&. A \fIgen_server\fR is started and returned if connection is successful\&. This server is used to perform SFTP commands on the server\&.
.LP
For options, see \fIssh_cm:connect\fR\&.
.RE
.LP
.B
read_file(Server, File) -> {ok, Data} | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
File = string()
.br
Data = binary()
.br
Reason = term()
.br
.RE
.RS
.LP
Reads a file from the server, and returns the data in a binary, like \fIfile:read_file/1\fR\&.
.RE
.LP
.B
write_file(Server, File, Iolist) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
File = string()
.br
Data = binary()
.br
Reason = term()
.br
.RE
.RS
.LP
Writes a file to the server, like \fIfile:write_file/2\fR\&. The file is created if it\&'s not there\&.
.RE
.LP
.B
list_dir(Server, Path) -> {ok, Filenames} | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Path = string()
.br
Filenames = [Filename]
.br
Filename = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Lists the given directory on the server, returning the filenames as a list of strings\&.
.RE
.LP
.B
open(Server, File, Mode) -> {ok, Handle} | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
File = string()
.br
Mode = [Modeflag]
.br
Modeflag = read | write | creat | trunc | append | binary
.br
Handle = term()
.br
Reason = term()
.br
.RE
.RS
.LP
Opens a file on the server, and returns a handle that is used for reading or writing\&.
.RE
.LP
.B
opendir(Server, Path) -> {ok, Handle} | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Path = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Opens a handle to a directory on the server, the handle is used for reading directory contents\&.
.RE
.LP
.B
close(Server, Handle) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Handle = term()
.br
Reason = term()
.br
.RE
.RS
.LP
Closes a handle to an open file or directory on the server\&.
.RE
.LP
.B
read(Server, Handle, Len) -> {ok, Data} | eof | {error, Error}
.br
.B
pread(Server, Handle, Position, Length) -> {ok, Data} | eof | {error, Error}
.br
.RS
.TP
Types
Server = pid()
.br
Handle = term()
.br
Position = integer()
.br
Len = integer()
.br
Data = string() | binary()
.br
Reason = term()
.br
.RE
.RS
.LP
Reads \fILen\fR bytes from the file referenced by \fIHandle\fR\&. Returns \fI{ok, Data}\fR, or \fIeof\fR, or \fI{error, Reason}\fR\&. If the file is opened with \fIbinary\fR, \fIData\fR is a binary, otherwise it is a string\&.
.LP
If the file is read past eof, only the remaining bytes will be read and returned\&. If no bytes are read, \fIeof\fR is returned\&.
.LP
The \fIpread\fR function reads from a specified position, combining the \fIposition\fR and \fIread\fR functions\&.
.RE
.LP
.B
aread(Server, Handle, Len) -> {async, N} | {error, Error}
.br
.B
apread(Server, Handle, Position, Length) -> {async, N} | {error, Error}
.br
.RS
.TP
Types
Server = pid()
.br
Handle = term()
.br
Position = integer()
.br
Len = integer()
.br
N = term()
.br
Reason = term()
.br
.RE
.RS
.LP
Reads from an open file, without waiting for the result\&. If the handle is valid, the function returns \fI{async, N}\fR, where N is a term guaranteed to be unique between calls of \fIaread\fR\&. The actual data is sent as a message to the calling process\&. This message has the form \fI{async_reply, N, Result}\fR, where \fIResult\fR is the result from the read, either \fI{ok, Data}\fR, or \fIeof\fR, or \fI{error, Error}\fR\&.
.LP
The \fIapread\fR function reads from a specified position, combining the \fIposition\fR and \fIaread\fR functions\&.
.RE
.LP
.B
write(Server, Handle, Data) -> ok | {error, Error}
.br
.B
pwrite(Server, Handle, Position, Data) -> ok | {error, Error}
.br
.RS
.TP
Types
Server = pid()
.br
Handle = term()
.br
Position = integer()
.br
Data = iolist()
.br
Reason = term()
.br
.RE
.RS
.LP
Write \fIdata\fR to the file referenced by \fIHandle\fR\&. The file should be opened with \fIwrite\fR or \fIappend\fR flag\&. Returns \fIok\fR if successful and \fI{error, Reason}\fR otherwise\&.
.LP
Typical error reasons are:
.RS 2
.TP 4
.B
\fIebadf\fR:
The file is not opened for writing\&.
.TP 4
.B
\fIenospc\fR:
There is a no space left on the device\&.
.RE
.RE
.LP
.B
awrite(Server, Handle, Data) -> ok | {error, Error}
.br
.B
apwrite(Server, Handle, Position, Data) -> ok | {error, Error}
.br
.RS
.TP
Types
Server = pid()
.br
Handle = term()
.br
Position = integer()
.br
Len = integer()
.br
Data = binary()
.br
Reason = term()
.br
.RE
.RS
.LP
Writes to an open file, without waiting for the result\&. If the handle is valid, the function returns \fI{async, N}\fR, where N is a term guaranteed to be unique between calls of \fIawrite\fR\&. The result of the \fIwrite\fR operation is sent as a message to the calling process\&. This message has the form \fI{async_reply, N, Result}\fR, where \fIResult\fR is the result from the write, either \fIok\fR, or \fI{error, Error}\fR\&.
.LP
The \fIapwrite\fR writes on a specified position, combining the \fIposition\fR and \fIawrite\fR operations\&.
.RE
.LP
.B
position(Server, Handle, Location) -> {ok, NewPosition | {error, Error}
.br
.RS
.TP
Types
Server = pid()
.br
Handle = term()
.br
Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof
.br
Offset = int()
.br
NewPosition = integer()
.br
Reason = term()
.br
.RE
.RS
.LP
Sets the file position of the file referenced by \fIHandle\fR\&. Returns \fI{ok, NewPosition\fR (as an absolute offset) if successful, otherwise \fI{error, Reason}\fR\&. \fILocation\fR is one of the following:
.RS 2
.TP 4
.B
\fIOffset\fR:
The same as \fI{bof, Offset}\fR\&.
.TP 4
.B
\fI{bof, Offset}\fR:
Absolute offset\&.
.TP 4
.B
\fI{cur, Offset}\fR:
Offset from the current position\&.
.TP 4
.B
\fI{eof, Offset}\fR:
Offset from the end of file\&.
.TP 4
.B
\fIbof | cur | eof\fR:
The same as above with \fIOffset\fR 0\&.
.RE
.RE
.LP
.B
read_file_info(Server, Name) -> {ok, FileInfo} | {error, Reason}
.br
.B
get_file_info(Server, Handle) -> {ok, FileInfo} | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Handle = term()
.br
FileInfo = record()
.br
Reason = term()
.br
.RE
.RS
.LP
Returns a \fIfile_info\fR record from the file specified by \fIName\fR or \fIHandle\fR, like \fIfile:read_file_info/2\fR\&.
.RE
.LP
.B
read_link_info(Server, Name) -> {ok, FileInfo} | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Handle = term()
.br
FileInfo = record()
.br
Reason = term()
.br
.RE
.RS
.LP
Returns a \fIfile_info\fR record from the symbolic link specified by \fIName\fR or \fIHandle\fR, like \fIfile:read_link_info/2\fR\&.
.RE
.LP
.B
write_file_info(Server, Name, Info) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Info = record()
.br
Reason = term()
.br
.RE
.RS
.LP
Writes file information from a \fIfile_info\fR record to the file specified by \fIName\fR, like \fIfile:write_file_info\fR\&.
.RE
.LP
.B
read_link(Server, Name) -> {ok, Target} | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Target = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Read the link target from the symbolic link specified by \fIname\fR, like \fIfile:read_link/1\fR\&.
.RE
.LP
.B
make_symlink(Server, Name, Target) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Target = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Creates a symbolic link pointing to \fITarget\fR with the name \fIName\fR, like \fIfile:make_symlink/2\fR\&.
.RE
.LP
.B
rename(Server, OldName, NewName) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
OldName = string()
.br
NewName = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Renames a file named \fIOldName\fR, and gives it the name \fINewName\fR, like \fIfile:rename/2\fR
.RE
.LP
.B
delete(Server, Name) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Deletes the file specified by \fIName\fR, like \fIfile:delete/1\fR
.RE
.LP
.B
make_dir(Server, Name) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Creates a directory specified by \fIName\fR\&. \fIName\fR should be a full path to a new directory\&. The directory can only be created in an existing directory\&.
.RE
.LP
.B
del_dir(Server, Name) -> ok | {error, Reason}
.br
.RS
.TP
Types
Server = pid()
.br
Name = string()
.br
Reason = term()
.br
.RE
.RS
.LP
Deletes a directory specified by \fIName\fR\&. The directory should be empty, and 
.RE
.LP
.B
stop(Server) -> ok
.br
.RS
.TP
Types
Server = pid()
.br
.RE
.RS
.LP
Stops the \fIsftp\fR session, closing the connection\&. Any open files on the server will be closed\&.
.RE