From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/ssh/doc/src/ssh_sftp.xml | 501 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 501 insertions(+) create mode 100644 lib/ssh/doc/src/ssh_sftp.xml (limited to 'lib/ssh/doc/src/ssh_sftp.xml') diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml new file mode 100644 index 0000000000..208b2b4e72 --- /dev/null +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -0,0 +1,501 @@ + + + + +
+ + 20052009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + ssh_sftp + Jakob Cederlund + + 1 + + + 2005-09-22 + PA1 + ssh_sftp.sgml +
+ ssh_sftp + SFTP client. + +

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

+ + +
+ COMMON DATA TYPES +

Type definitions that are used more than once in this module + and/or abstractions to indicate the intended use of the data type: +

+

ssh_connection_ref() - opaque to the user + returned by ssh:connect/3

+

timeout() = infinity | integer() - in milliseconds.

+
+ +
+ TIMEOUTS +

If the request functions for the sftp channel return {error, timeout} + it does not mean that the request did not reach the server and was + not performed, it only means that we did not receive an answer from the + server within the time that was expected.

+
+ + + + start_channel(ConnectionRef) -> + start_channel(ConnectionRef, Options) -> + start_channel(Host, Options) -> + start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | + {error, Reason} + Starts a sftp client + + Host = string() + ConnectionRef = ssh_connection_ref() + Port = integer() + Options = [{Option, Value}] + Reason = term() + + +

If not provided, setups a ssh connection in this case a + connection reference will be returned too. A ssh channel + process is started to handle the communication with the SFTP + server, the returned pid for this process should be used as + input to all other API functions in this module.

+ +

Options are:

+ + + +

The timeout is passed to the ssh_channel start function, + and defaults to infinity.

+ + +

All other options are directly passed to + ssh:connect/3 or ignored if a + connection is already provided.

+ + + + + stop_channel(ChannelPid) -> ok + Stops the sftp client channel. + + ChannelPid = pid() + + +

Stops a sftp channel. If the ssh connection should be closed + call ssh:close/1.

+ + + + + read_file(ChannelPid, File) -> + read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason} + Read a file + + ChannelPid = pid() + File = string() + Data = binary() + Timeout = timeout() + Reason = term() + + +

Reads a file from the server, and returns the data in a binary, + like .

+ + + + write_file(ChannelPid, File, Iolist) -> + write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason} + Write a file + + ChannelPid = pid() + File = string() + Iolist = iolist() + Timeout = timeout() + Reason = term() + + +

Writes a file to the server, like . + The file is created if it's not there.

+ + + + list_dir(ChannelPid, Path) -> + list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason} + List directory + + ChannelPid = pid() + Path = string() + Filenames = [Filename] + Filename = string() + Timeout = timeout() + Reason = term() + + +

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

+ + + + open(ChannelPid, File, Mode) -> + open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason} + Open a file and return a handle + + ChannelPid = pid() + File = string() + Mode = [Modeflag] + Modeflag = read | write | creat | trunc | append | binary + Timeout = timeout() + Handle = term() + Reason = term() + + +

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

+ + + + opendir(ChannelPid, Path) -> + opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason} + Open a directory and return a handle + + ChannelPid = pid() + Path = string() + Timeout = timeout() + Reason = term() + + +

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

+ + + + close(ChannelPid, Handle) -> + close(ChannelPid, Handle, Timeout) -> ok | {error, Reason} + Close an open handle + + ChannelPid = pid() + Handle = term() + Timeout = timeout() + Reason = term() + + +

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

+ + + + read(ChannelPid, Handle, Len) -> + read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error} + pread(ChannelPid, Handle, Position, Len) -> + pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error} + Read from an open file + + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + Timeout = timeout() + Data = string() | binary() + Reason = term() + + +

Reads bytes from the file referenced by + . Returns , or , or + . If the file is opened with , + 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, + is returned.

+

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

+ + + + aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error} + apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error} + Read asynchronously from an open file + + ChannelPid = 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 , where N + is a term guaranteed to be unique between calls of . + The actual data is sent as a message to the calling process. This + message has the form , where + is the result from the read, either , + or , or .

+

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

+ + + + write(ChannelPid, Handle, Data) -> + write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error} + pwrite(ChannelPid, Handle, Position, Data) -> ok + pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error} + Write to an open file + + ChannelPid = pid() + Handle = term() + Position = integer() + Data = iolist() + Timeout = timeout() + Reason = term() + + +

Write to the file referenced by . + The file should be opened with or + flag. Returns if successful and + otherwise.

+

Typical error reasons are:

+ + + +

The file is not opened for writing.

+ + + +

There is a no space left on the device.

+ + + + + + awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} + apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} + Write asynchronously to an open file + + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + Data = binary() + Timeout = timeout() + Reason = term() + + +

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

+

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

+ + + + position(ChannelPid, Handle, Location) -> + position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error} + Seek position in open file + + ChannelPid = pid() + Handle = term() + Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof + Offset = int() + Timeout = timeout() + NewPosition = integer() + Reason = term() + + +

Sets the file position of the file referenced by . + Returns (as an absolute offset) if + successful, otherwise . is + one of the following:

+ + + +

The same as .

+ + + +

Absolute offset.

+ + + +

Offset from the current position.

+ + + +

Offset from the end of file.

+ + + +

The same as above with 0.

+ + + + + + read_file_info(ChannelPid, Name) -> + read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} + Get information about a file + + ChannelPid = pid() + Name = string() + Handle = term() + Timeout = timeout() + FileInfo = record() + Reason = term() + + +

Returns a record from the file specified by + or , like .

+ + + + read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason} + read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} + Get information about a symbolic link + + ChannelPid = pid() + Name = string() + Handle = term() + Timeout = timeout() + FileInfo = record() + Reason = term() + + +

Returns a record from the symbolic + link specified by or , like + .

+ + + + write_file_info(ChannelPid, Name, Info) -> + write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} + Write information for a file + + ChannelPid = pid() + Name = string() + Info = record() + Timeout = timeout() + Reason = term() + + +

Writes file information from a record to the + file specified by , like .

+ + + + read_link(ChannelPid, Name) -> + read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason} + Read symbolic link + + ChannelPid = pid() + Name = string() + Target = string() + Reason = term() + + +

Read the link target from the symbolic link specified + by , like .

+ + + + make_symlink(ChannelPid, Name, Target) -> + make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason} + Create symbolic link + + ChannelPid = pid() + Name = string() + Target = string() + Reason = term() + + +

Creates a symbolic link pointing to with the + name , like .

+ + + + rename(ChannelPid, OldName, NewName) -> + rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason} + Rename a file + + ChannelPid = pid() + OldName = string() + NewName = string() + Timeout = timeout() + Reason = term() + + +

Renames a file named , and gives it the name + , like

+ + + + delete(ChannelPid, Name) -> + delete(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Delete a file + + ChannelPid = pid() + Name = string() + Timeout = timeout() + Reason = term() + + +

Deletes the file specified by , like +

+ + + + make_dir(ChannelPid, Name) -> + make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Create a directory + + ChannelPid = pid() + Name = string() + Timeout = timeout() + Reason = term() + + +

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

+ + + + del_dir(ChannelPid, Name) -> + del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Delete an empty directory + + ChannelPid = pid() + Name = string() + Timeout = timeout() + Reason = term() + + +

Deletes a directory specified by . The directory + should be empty.

+ + + + + + + -- cgit v1.2.3