From 4dd173e8355f0105a9a6cbc5d8243c44dc83a2e4 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Thu, 25 Feb 2016 19:09:32 +0100 Subject: ssh: ssh_sftp doc updated (error reason, no file: refs) --- lib/ssh/doc/src/ssh_sftp.xml | 162 +++++++++++++++++++------------------------ 1 file changed, 71 insertions(+), 91 deletions(-) (limited to 'lib/ssh') diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml index 1d37933369..ae9b914eba 100644 --- a/lib/ssh/doc/src/ssh_sftp.xml +++ b/lib/ssh/doc/src/ssh_sftp.xml @@ -44,8 +44,23 @@

+ reason() + +

= atom() A description of the reason why an operation failed.

+

+ The value is formed from the sftp error codes in the protocol-level responses as defined in + draft-ietf-secsh-filexfer-13.txt + section 9.1. +

+

+ The codes are named as SSH_FX_* which are transformed into lowercase(*), e.g. the error code ?SSH_FX_NO_SUCH_FILE + will cause the reason() to be no_such_file. +

+ + ssh_connection_ref() =

opaque() - as returned by ssh:connect/3

 + timeout()

= infinity | integer() in milliseconds. Default infinity.

 @@ -61,7 +76,7 @@ - apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Reason} + apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, reason()} Reads asynchronously from an open file. ChannelPid = pid() @@ -69,7 +84,6 @@ Position = integer() Len = integer() N = term() - Reason = term()

The function reads from a specified position, @@ -78,7 +92,7 @@ - apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason} + apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, reason()} Writes asynchronously to an open file. ChannelPid = pid() @@ -87,7 +101,6 @@ Len = integer() Data = binary() Timeout = timeout() - Reason = term()

writes on a specified position, combining @@ -96,7 +109,7 @@ - aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error} + aread(ChannelPid, Handle, Len) -> {async, N} | {error, reason()} Reads asynchronously from an open file. ChannelPid = pid() @@ -104,7 +117,6 @@ Position = integer() Len = integer() N = term() - Reason = term()

Reads from an open file, without waiting for the result. If the @@ -113,14 +125,14 @@ 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 .

 - awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} + awrite(ChannelPid, Handle, Data) -> ok | {error, reason()} Writes asynchronously to an open file. ChannelPid = pid() @@ -129,7 +141,6 @@ Len = integer() Data = binary() Timeout = timeout() - Reason = term()

Writes to an open file, without waiting for the result. If the @@ -138,19 +149,18 @@ . 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 .

+ from the write, either , or .

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

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

@@ -159,29 +169,27 @@ delete(ChannelPid, Name) -> - delete(ChannelPid, Name, Timeout) -> ok | {error, Reason} + delete(ChannelPid, Name, Timeout) -> ok | {error, reason()} Deletes a file. ChannelPid = pid() Name = string() Timeout = timeout() - Reason = term() -

Deletes the file specified by , like - file:delete/1

+

Deletes the file specified by . +

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

Deletes a directory specified by . @@ -192,7 +200,7 @@ list_dir(ChannelPid, Path) -> - list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason} + list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, reason()} Lists the directory. ChannelPid = pid() @@ -200,7 +208,6 @@ Filenames = [Filename] Filename = string() Timeout = timeout() - Reason = term()

Lists the given directory on the server, returning the @@ -210,13 +217,12 @@ make_dir(ChannelPid, Name) -> - make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason} + make_dir(ChannelPid, Name, Timeout) -> ok | {error, reason()} Creates a directory. ChannelPid = pid() Name = string() Timeout = timeout() - Reason = term()

Creates a directory specified by . @@ -227,24 +233,23 @@ make_symlink(ChannelPid, Name, Target) -> - make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason} + 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 - file:make_symlink/2

+ name . +

open(ChannelPid, File, Mode) -> - open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason} + open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, reason()} Opens a file and returns a handle. ChannelPid = pid() @@ -253,7 +258,6 @@ Modeflag = read | write | creat | trunc | append | binary Timeout = timeout() Handle = term() - Reason = term()

Opens a file on the server and returns a handle, which @@ -262,13 +266,12 @@ opendir(ChannelPid, Path) -> - opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason} + opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, reason()} Opens a directory and returns a handle. ChannelPid = pid() Path = string() Timeout = timeout() - Reason = term()

Opens a handle to a directory on the server. The handle @@ -278,7 +281,7 @@ open_tar(ChannelPid, Path, Mode) -> - open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, Reason} + open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, reason()} Opens a tar file on the server to which ChannelPid is connected and returns a handle. @@ -298,7 +301,6 @@ DecryptResult = {ok,PlainBin,CryptoState} | {ok,PlainBin,CryptoState,ChunkSize} CloseFun = (fun(PlainBin,CryptoState) -> {ok,EncryptedBin}) Timeout = timeout() - Reason = term()

Opens a handle to a tar file on the server, associated with ChannelPid. @@ -333,7 +335,7 @@ position(ChannelPid, Handle, Location) -> - position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition} | {error, Reason} + position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, reason()} Sets the file position of a file. ChannelPid = pid() @@ -343,12 +345,11 @@ Offset = integer() Timeout = timeout() NewPosition = integer() - Reason = term()

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

@@ -379,7 +380,7 @@ pread(ChannelPid, Handle, Position, Len) -> - pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error} + pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, reason()} Reads from an open file. ChannelPid = pid() @@ -388,7 +389,6 @@ Len = integer() Timeout = timeout() Data = string() | binary() - Reason = term()

The function reads from a specified position, @@ -399,7 +399,7 @@ pwrite(ChannelPid, Handle, Position, Data) -> ok - pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Reason} + pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, reason()} Writes to an open file. ChannelPid = pid() @@ -407,7 +407,6 @@ Position = integer() Data = iolist() Timeout = timeout() - Reason = term()

The function writes to a specified position, @@ -419,7 +418,7 @@ read(ChannelPid, Handle, Len) -> - read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error} + read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, reason()} Reads from an open file. ChannelPid = pid() @@ -428,12 +427,11 @@ Len = integer() Timeout = timeout() Data = string() | binary() - Reason = term()

Reads bytes from the file referenced by . Returns , , or - . If the file is opened with , + . 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, @@ -443,25 +441,22 @@ read_file(ChannelPid, File) -> - read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason} + read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, reason()} Reads 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 - file:read_file/1

+

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

 read_file_info(ChannelPid, Name) -> - read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} + read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, reason()} Gets information about a file. ChannelPid = pid() @@ -469,35 +464,34 @@ Handle = term() Timeout = timeout() FileInfo = record() - Reason = term()

Returns a record from the file specified by - or , - like file:read_file_info/2

+ or . See + file:read_file_info/2 + for information about the record. +

read_link(ChannelPid, Name) -> - read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason} + 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 - file:read_link/1

+

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

- read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason} - read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason} + 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. ChannelPid = pid() @@ -505,30 +499,31 @@ Handle = term() Timeout = timeout() FileInfo = record() - Reason = term()

Returns a record from the symbolic - link specified by or , like - file:read_link_info/2

+ link specified by or . + See + file:read_link_info/2 + for information about the record. +

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

Renames a file named and gives it the name - , like - file:rename/2

+ . +

@@ -537,14 +532,13 @@ start_channel(ConnectionRef, Options) -> start_channel(Host, Options) -> start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} | - {error, Reason} + {error, reason()|term()} Starts an SFTP client. Host = string() ConnectionRef = ssh_connection_ref() Port = integer() Options = [{Option, Value}] - Reason = term()

If no connection reference is provided, a connection is set @@ -592,7 +586,7 @@ write(ChannelPid, Handle, Data) -> - write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Reason} + write(ChannelPid, Handle, Data, Timeout) -> ok | {error, reason()} Writes to an open file. ChannelPid = pid() @@ -600,61 +594,47 @@ Position = integer() Data = iolist() Timeout = timeout() - Reason = term()

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

-

Typical error reasons:

- - - -

File is not opened for writing.

- - - -

No space is left on the device.

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

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

+

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

 write_file_info(ChannelPid, Name, Info) -> - write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason} + 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()

Writes file information from a record to the - file specified by , like - file:write_file_info/[2,3]

+ file specified by . See + file:write_file_info/[2,3] + for information about the record. +

-- cgit v1.2.3