From cc4996c9b3ad5294d3c3e6bb2435baaabec3f319 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Wed, 22 Apr 2015 14:51:34 +0200 Subject: ssh: Align to alphabetic order --- lib/ssh/doc/src/ssh_sftp.xml | 545 ++++++++++++++++++++++++------------------- 1 file changed, 311 insertions(+), 234 deletions(-) (limited to 'lib/ssh/doc/src') diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index 95869befb8..c2a86f3821 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -59,98 +59,132 @@ + + apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error} + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + N = term() + Reason = term() + +

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

+

ssh_sftp:apread/3

 + + + + aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error} + Reads 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 .

+ + + - start_channel(ConnectionRef) -> - start_channel(ConnectionRef, Options) -> - start_channel(Host, Options) -> - start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | - {error, Reason} - Starts an SFTP client. + apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} + Writes asynchronously to an open file. - Host = string() - ConnectionRef = ssh_connection_ref() - Port = integer() - Options = [{Option, Value}] + ChannelPid = pid() + Handle = term() + Position = integer() + Len = integer() + Data = binary() + Timeout = timeout() Reason = term() -

If no connection reference is provided, a connection is set - up, and the new connection is returned. An SSH channel process - is started to handle the communication with the SFTP server. - The returned pid for this process is to be used as input to - all other API functions in this module.

+

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

+

ssh_sftp:awrite/3

+ -

Options:

- - - -

The time-out is passed to the ssh_channel start function, - and defaults to infinity.

- - - - - -

- Desired SFTP protocol version. - The actual version is the minimum of - the desired version and the maximum supported - versions by the SFTP server. -

- - -

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

+ + awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} + Writes 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 .

 - stop_channel(ChannelPid) -> ok - Stops the SFTP client channel. + close(ChannelPid, Handle) -> + close(ChannelPid, Handle, Timeout) -> ok | {error, Reason} + Closes an open handle. ChannelPid = pid() + Handle = term() + Timeout = timeout() + Reason = term() -

Stops an SFTP channel. Does not close the SSH connection. - Use ssh:close/1 to close it.

+

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

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

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

+

Deletes the file specified by , like + .

 + - write_file(ChannelPid, File, Iolist) -> - write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason} - Writes a file. + del_dir(ChannelPid, Name) -> + del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + Deletes an empty directory. ChannelPid = pid() - File = string() - Iolist = iolist() + Name = string() Timeout = timeout() Reason = term() -

Writes a file to the server, like - . The file is created if - it does not exist. The file is overwritten if it exists.

+

Deletes a directory specified by . + The directory must be empty before it can be successfully deleted. +

- + + list_dir(ChannelPid, Path) -> list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason} Lists the directory. @@ -167,7 +201,41 @@ filenames as a list of strings.

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

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

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

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

+ + + + open(ChannelPid, File, Mode) -> open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason} Opens a file and returns a handle. @@ -228,10 +296,11 @@

Opens a handle to a tar file on the server, associated with ChannelPid. The handle can be used for remote tar creation and extraction, as defined by the - erl_tar:init/3 function. + erl_tar:init/3 function.

+

Example of writing and then reading a tar file follows:

- + {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]), ok = erl_tar:add(HandleWrite, .... ), ok = erl_tar:add(HandleWrite, .... ), @@ -263,7 +332,7 @@ DecryptFun. The value can be changed between pos_integer() and undefined.

The previous write and read example can be extended with encryption and decryption as follows:

- + %% First three parameters depending on which crypto type we select: Key = <<"This is a 256 bit key. abcdefghi">>, Ivec0 = crypto:rand_bytes(16), @@ -313,22 +382,52 @@ - close(ChannelPid, Handle) -> - close(ChannelPid, Handle, Timeout) -> ok | {error, Reason} - Closes an open handle. + position(ChannelPid, Handle, Location) -> + position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error} + Sets the file position of a file. ChannelPid = pid() Handle = term() + Location = Offset + | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof + Offset = integer() Timeout = timeout() + NewPosition = integer() Reason = term() -

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

+

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 eariler with 0, + that is, . +

+ + + - 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} Reads from an open file. @@ -342,44 +441,13 @@ Reason = term() -

Reads bytes from the file referenced by - . Returns , , 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 - are 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} - Reads 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 .

-

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

+

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

+

ssh_sftp:read/4

 + - 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} Writes to an open file. @@ -392,94 +460,55 @@ Reason = term() -

Writes to the file referenced by . - The file is to be opened with or - flag. Returns if successful or - otherwise.

-

Typical error reasons:

- - - -

File is not opened for writing.

- - - -

No space is left on the device.

- - +

The function writes to a specified position, + combining the and functions.

+

ssh_sftp:write/3

 - - awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} - apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} - Writes asynchronously to an open file. + + + + read(ChannelPid, Handle, Len) -> + read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error} + Reads from an open file. ChannelPid = pid() Handle = term() Position = integer() Len = integer() - Data = binary() Timeout = timeout() + Data = string() | binary() 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 .

-

writes on a specified position, combining - the and operations.

+

Reads bytes from the file referenced by + . Returns , , 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 + are read and returned. If no bytes are read, + is returned.

 - - position(ChannelPid, Handle, Location) -> - position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error} - Sets the file position of a file. + + + read_file(ChannelPid, File) -> + read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason} + Reads a file. - ChannelPid = pid() - Handle = term() - Location = Offset - | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof - Offset = integer() + ChannelPid = pid() + File = string() + Data = binary() Timeout = timeout() - NewPosition = integer() - Reason = term() + 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 eariler with 0, - that is, . -

- - +

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

 - + + read_file_info(ChannelPid, Name) -> read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} Gets information about a file. @@ -497,7 +526,24 @@ like .

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

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

+ + + + read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason} read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} Gets information about a symbolic link. @@ -515,116 +561,147 @@ .

 + - write_file_info(ChannelPid, Name, Info) -> - write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} - Writes information for a file. + rename(ChannelPid, OldName, NewName) -> + rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason} + Renames a file. ChannelPid = pid() - Name = string() - Info = record() + OldName = string() + NewName = string() 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} - Reads symbolic link. - - ChannelPid = pid() - Name = string() - Target = string() - Reason = term() - - -

Reads the link target from the symbolic link specified - by , like .

+

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

 + - make_symlink(ChannelPid, Name, Target) -> - make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason} - Creates a symbolic link. + start_channel(ConnectionRef) -> + start_channel(ConnectionRef, Options) -> + start_channel(Host, Options) -> + start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | + {error, Reason} + Starts an SFTP client. - ChannelPid = pid() - Name = string() - Target = string() + Host = string() + ConnectionRef = ssh_connection_ref() + Port = integer() + Options = [{Option, Value}] Reason = term() -

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

+

If no connection reference is provided, a connection is set + up, and the new connection is returned. An SSH channel process + is started to handle the communication with the SFTP server. + The returned pid for this process is to be used as input to + all other API functions in this module.

+ +

Options:

+ + + +

The time-out is passed to the ssh_channel start function, + and defaults to infinity.

+ + + + + +

+ Desired SFTP protocol version. + The actual version is the minimum of + the desired version and the maximum supported + versions by the SFTP server. +

+ + +

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

 - - rename(ChannelPid, OldName, NewName) -> - rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason} - Renames a file. + + + stop_channel(ChannelPid) -> ok + Stops the SFTP client channel. ChannelPid = pid() - OldName = string() - NewName = string() - Timeout = timeout() - Reason = term() -

Renames a file named and gives it the name - , like .

+

Stops an SFTP channel. Does not close the SSH connection. + Use ssh:close/1 to close it.

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

Deletes the file specified by , like - .

+

Writes a file to the server, like + . The file is created if + it does not exist. The file is overwritten if it exists.

 + - make_dir(ChannelPid, Name) -> - make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Creates a directory. + write(ChannelPid, Handle, Data) -> + write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error} + Writes to an open file. ChannelPid = pid() - Name = string() + Handle = term() + Position = integer() + Data = iolist() Timeout = timeout() Reason = term() -

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

+

Writes to the file referenced by . + The file is to be opened with or + flag. Returns if successful or + otherwise.

+

Typical error reasons:

+ + + +

File is not opened for writing.

+ + + +

No space is left on the device.

+ + + - del_dir(ChannelPid, Name) -> - del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} - Deletes an empty directory. + write_file_info(ChannelPid, Name, Info) -> + write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} + Writes information for a file. ChannelPid = pid() Name = string() + Info = record() Timeout = timeout() Reason = term() -

Deletes a directory specified by . - The directory must be empty before it can be successfully deleted. -

+

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

 - -- cgit v1.2.3