Merge branch 'ia/ssh/improve_docs'

* ia/ssh/improve_docs:
  ssh: Move code example to Users Guide
  ssh: Keep dependency info in only one place
  ssh: Add links
  ssh: Align to alphabetic order
  ssh: Change wording to become accurate
  ssh: Remove extra whitespace
  ssh: Corrected information about error and event logging
  ssh: Remove legacy statement
  ssh: Technically correct description
  Editorial updates

1 files changed, 371 insertions, 335 deletions

diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
index ab111562f9..4ed5a38de4 100644
--- a/lib/ssh/doc/src/ssh_sftp.xml
+++ b/lib/ssh/doc/src/ssh_sftp.xml
@@ -23,131 +23,171 @@
 
     <title>ssh_sftp</title>
     <prepared>OTP</prepared>
+    <docno></docno>
     <date>2005-09-22</date>
+    <rev></rev>
     <file>ssh_sftp.sgml</file>
   </header>
   <module>ssh_sftp</module>
   <modulesummary>SFTP client.</modulesummary>
   <description>
-    <p>This module implements an SFTP (SSH FTP) client. SFTP is a
+    <p>This module implements an SSH FTP (SFTP) client. SFTP is a
     secure, encrypted file transfer service available for
     SSH.</p>
   </description>
   
  <section>
-    <title>DATA TYPES </title>
-    <p>Type definitions that are used more than once in this module
-    and/or abstractions to indicate the intended use of the data type:
+    <title>DATA TYPES</title>
+    <p>Type definitions that are used more than once in this module,
+    or abstractions to indicate the intended use of the data type, or both:
     </p>
-    <p><c>ssh_connection_ref() - opaque to the user
-    returned by ssh:connect/3</c></p>
-    <p><c>timeout() =  infinity | integer() - in milliseconds.</c></p>    
+
+    <taglist>
+      <tag><c>ssh_connection_ref()</c></tag>
+      <item><p>Opaque to the user, returned by <c>ssh:connect/3</c></p></item>
+      <tag><c>timeout()</c></tag>
+      <item><p>= <c>infinity | integer() in milliseconds</c></p></item>
+    </taglist>
    </section>
 
  <section>
-    <title>TIMEOUTS </title>
-    <p>If the request functions for the SFTP channel return {error, timeout}
-    it does not guarantee 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.</p>
+    <title>Time-outs</title>
+    <p>If the request functions for the SFTP channel return <c>{error, timeout}</c>,
+    it does not guarantee that the request never reached the server and was
+    not performed. It only means that no answer was received from the
+    server within the expected time.</p>
    </section>
 
   <funcs>
+     <func>
+      <name>apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error}</name>
+      <v>ChannelPid = pid()</v>
+        <v>Handle = term()</v>
+        <v>Position = integer()</v>
+        <v>Len = integer()</v>
+        <v>N = term()</v>
+        <v>Reason = term()</v>
+
+	<desc><p>The <c><![CDATA[apread]]></c> function reads from a specified position,
+	combining the <c><![CDATA[position]]></c> and <c><![CDATA[aread]]></c> functions.</p>
+	<p><seealso marker="#apread-3">ssh_sftp:apread/3</seealso></p> </desc>
+      </func>
+
+      <func>
+	<name>aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error}</name>
+	<fsummary>Reads asynchronously from an open file.</fsummary>
+	<type>
+	  <v>ChannelPid = pid()</v>
+	  <v>Handle = term()</v>
+	  <v>Position = integer()</v>
+	  <v>Len = integer()</v>
+	  <v>N = term()</v>
+	  <v>Reason = term()</v>
+	</type>
+	<desc>
+	  <p>Reads from an open file, without waiting for the result. If the
+          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where <c>N</c>
+          is a term guaranteed to be unique between calls of <c><![CDATA[aread]]></c>.
+          The actual data is sent as a message to the calling process. This
+          message has the form <c><![CDATA[{async_reply, N, Result}]]></c>, where
+          <c><![CDATA[Result]]></c> is the result from the read, either <c><![CDATA[{ok, Data}]]></c>,
+          <c><![CDATA[eof]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
+      </desc>
+    </func>
+
     <func>
-      <name>start_channel(ConnectionRef) -> </name>
-      <name>start_channel(ConnectionRef, Options) -> </name>
-      <name>start_channel(Host, Options) -></name>
-      <name>start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} |
-      {error, Reason}</name>
-      <fsummary>Starts a SFTP client</fsummary>
+      <name>apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason}</name>
+      <fsummary>Writes asynchronously to an open file.</fsummary>
       <type>
-        <v>Host = string()</v>
-        <v>ConnectionRef = ssh_connection_ref()</v>
-        <v>Port = integer()</v>
-        <v>Options = [{Option, Value}]</v>
+        <v>ChannelPid = pid()</v>
+        <v>Handle = term()</v>
+        <v>Position = integer()</v>
+        <v>Len = integer()</v>
+        <v>Data = binary()</v>
+	<v>Timeout = timeout()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-	<p>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 should be used as input to
-	all other API functions in this module.</p>
+	  <p><c><![CDATA[apwrite]]></c> writes on a specified position, combining
+          the <c><![CDATA[position]]></c> and <c><![CDATA[awrite]]></c> operations.</p>
+	  <p><seealso marker="#awrite-3">ssh_sftp:awrite/3</seealso> </p></desc>
+      </func>
 
-	<p>Options are:</p>
-	<taglist>
-          <tag><c><![CDATA[{timeout, timeout()}]]></c></tag>
-	  <item>
-	    <p>The timeout is passed to the ssh_channel start function,
-	    and defaults to infinity.</p>
-	  </item>
-	  <tag>
-	    <p><c><![CDATA[{sftp_vsn, integer()}]]></c></p>
-	  </tag>
-	  <item>
-	    <p>
-	      Desired SFTP protocol version.
-	      The actual version will be the minimum of
-	      the desired version and the maximum supported
-	      versions by the SFTP server.
-	    </p>
-	  </item>
-	</taglist>
-	<p>All other options are  directly passed to
-	<seealso marker="ssh">ssh:connect/3</seealso> or ignored if a
-	connection is already provided. </p>
+    <func>
+      <name>awrite(ChannelPid, Handle, Data) -> ok | {error, Reason}</name>
+      <fsummary>Writes asynchronously to an open file.</fsummary>
+      <type>
+        <v>ChannelPid = pid()</v>
+        <v>Handle = term()</v>
+        <v>Position = integer()</v>
+        <v>Len = integer()</v>
+        <v>Data = binary()</v>
+	<v>Timeout = timeout()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Writes to an open file, without waiting for the result. If the
+          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where <c>N</c>
+          is a term guaranteed to be unique between calls of
+          <c><![CDATA[awrite]]></c>. The result of the <c><![CDATA[write]]></c> operation is sent
+          as a message to the calling process. This message has the form
+          <c><![CDATA[{async_reply, N, Result}]]></c>, where <c><![CDATA[Result]]></c> is the result
+          from the write, either <c><![CDATA[ok]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
       </desc>
     </func>
 
     <func>
-      <name>stop_channel(ChannelPid) -> ok</name>
-      <fsummary>Stops the SFTP client channel.</fsummary>
+      <name>close(ChannelPid, Handle) -></name>
+      <name>close(ChannelPid, Handle, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Closes an open handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
+        <v>Handle = term()</v>
+	<v>Timeout = timeout()</v>
+        <v>Reason = term()</v>
       </type>
       <desc>
-	<p>Stops an SFTP channel. Does not close the SSH connetion.
-	Use <seealso marker="ssh">ssh:close/1</seealso> to close it.</p>
+        <p>Closes a handle to an open file or directory on the server.</p>
       </desc>
     </func>
-  
+
     <func>
-      <name>read_file(ChannelPid, File) -> </name>
-      <name>read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason}</name>
-      <fsummary>Read a file</fsummary>
+      <name>delete(ChannelPid, Name) -></name>
+      <name>delete(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Deletes a file.</fsummary>
       <type>
-	<v>ChannelPid = pid()</v>
-	<v>File = string()</v>
-        <v>Data = binary()</v>
+        <v>ChannelPid = pid()</v>
+        <v>Name = string()</v>
 	<v>Timeout = timeout()</v>
-	<v>Reason = term()</v>
+        <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Reads a file from the server, and returns the data in a binary,
-          like <c><![CDATA[file:read_file/1]]></c>.</p>
+        <p>Deletes the file specified by <c><![CDATA[Name]]></c>, like
+	   <seealso marker="file#delete-1">file:delete/1</seealso></p>
       </desc>
     </func>
+
     <func>
-      <name>write_file(ChannelPid, File, Iolist) -> </name>
-      <name>write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Write a file</fsummary>
+      <name>del_dir(ChannelPid, Name) -></name>
+      <name>del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Deletes an empty directory.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
-        <v>File = string()</v>
-        <v>Iolist = iolist()</v>
+        <v>Name = string()</v>
 	<v>Timeout = timeout()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Writes a file to the server, like
-        <c><![CDATA[file:write_file/2]]></c>.  The file is created if
-        it does not exist or is owerwritten if it does.</p>
+	<p>Deletes a directory specified by <c><![CDATA[Name]]></c>.
+	The directory must be empty before it can be successfully deleted.
+	</p>
       </desc>
     </func>
-    <func>
-      <name>list_dir(ChannelPid, Path) -> </name>
+
+     <func>
+      <name>list_dir(ChannelPid, Path) -></name>
       <name>list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason}</name>
-      <fsummary>List directory</fsummary>
+      <fsummary>Lists the directory.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Path = string()</v>
@@ -161,10 +201,45 @@
           filenames as a list of strings.</p>
       </desc>
     </func>
+
+    <func>
+      <name>make_dir(ChannelPid, Name) -></name>
+      <name>make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Creates a directory.</fsummary>
+      <type>
+        <v>ChannelPid = pid()</v>
+        <v>Name = string()</v>
+	<v>Timeout = timeout()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Creates a directory specified by <c><![CDATA[Name]]></c>. <c><![CDATA[Name]]></c>
+          must be a full path to a new directory. The directory can only be
+	created in an existing directory.</p>
+      </desc>
+    </func>
+
     <func>
-      <name>open(ChannelPid, File, Mode) -> </name>
+      <name>make_symlink(ChannelPid, Name, Target) -></name>
+      <name>make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Creates a symbolic link.</fsummary>
+      <type>
+        <v>ChannelPid = pid()</v>
+        <v>Name = string()</v>
+        <v>Target = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Creates a symbolic link pointing to <c><![CDATA[Target]]></c> with the
+          name <c><![CDATA[Name]]></c>, like
+	   <seealso marker="file#make_symlink-2">file:make_symlink/2</seealso></p>
+      </desc>
+    </func>
+
+       <func>
+      <name>open(ChannelPid, File, Mode) -></name>
       <name>open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason}</name>
-      <fsummary>Open a file and return a handle</fsummary>
+      <fsummary>Opens a file and returns a handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>File = string()</v>
@@ -175,14 +250,14 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Opens a file on the server, and returns a handle that
+        <p>Opens a file on the server and returns a handle, which
           can be used for reading or writing.</p>
       </desc>
     </func>
     <func>
-      <name>opendir(ChannelPid, Path) -> </name>
+      <name>opendir(ChannelPid, Path) -></name>
       <name>opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason}</name>
-      <fsummary>Open a directory and return a handle</fsummary>
+      <fsummary>Opens a directory and returns a handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Path = string()</v>
@@ -190,7 +265,7 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Opens a handle to a directory on the server, the handle
+        <p>Opens a handle to a directory on the server. The handle
           can be used for reading directory contents.</p>
       </desc>
     </func>
@@ -198,14 +273,15 @@
     <func>
       <name>open_tar(ChannelPid, Path, Mode) -></name>
       <name>open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, Reason}</name>
-      <fsummary>Opens a tar file on the server to which <v>ChannelPid</v> is connected and returns a handle</fsummary>
+      <fsummary>Opens a tar file on the server to which <c>ChannelPid</c>
+      is connected and returns a handle.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Path = string()</v>
-	<v>Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt] </v>
+	<v>Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt]</v>
 	<v>EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}}</v>
 	<v>DecryptOpt = {crypto,{InitFun,DecryptFun}}</v>
-	<v>InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize}) </v>
+	<v>InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize})</v>
 	<v>CryptoState = any()</v>
 	<v>ChunkSize = undefined | pos_integer()</v>
 	<v>EncryptFun = (fun(PlainBin,CryptoState) -> EncryptResult)</v>
@@ -219,113 +295,86 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Opens a handle to a tar file on the server associated with <c>ChannelPid</c>. The handle
-	can be used for remote tar creation and extraction as defined by the
-	<seealso marker="stdlib:erl_tar#init/3">erl_tar:init/3</seealso> function.
+        <p>Opens a handle to a tar file on the server, associated with <c>ChannelPid</c>.
+	The handle can be used for remote tar creation and extraction, as defined by the
+	<seealso marker="stdlib:erl_tar#init-3">erl_tar:init/3</seealso> function.
 	</p>
-	<p>An example of writing and then reading a tar file:</p>
-        <code type="none">
-          {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]),
-          ok = erl_tar:add(HandleWrite, .... ),
-          ok = erl_tar:add(HandleWrite, .... ),
-              ...
-          ok = erl_tar:add(HandleWrite, .... ),
-          ok = erl_tar:close(HandleWrite),
-
-          %% And for reading
-          {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read]),
-          {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]),
-          ok = erl_tar:close(HandleRead),
-        </code>
-
-	<p>The <c>crypto</c> mode option is applied to the generated stream of bytes just prior to sending
-	them to the sftp server.  This is intended for encryption but could of course be used for other
+
+	<p> For code exampel see Section
+	<seealso marker="using_ssh">SFTP Client with TAR Compression and Encryption</seealso> in
+	the ssh Users Guide. </p>
+
+	<p>The <c>crypto</c> mode option is applied to the generated stream of bytes prior to sending
+	them to the SFTP server. This is intended for encryption but can be used for other
 	purposes.
 	</p>
 	<p>The <c>InitFun</c> is applied once
-	prior to any other crypto operation. The returned <c>CryptoState</c> is then folded into
-	repeated applications of the <c>EncryptFun</c> or <c>DecryptFun</c>.  The binary returned
-	from those Funs are sent further to the remote sftp server. Finally - if doing encryption
-	- the <c>CloseFun</c> is applied to the last piece of data.  The <c>CloseFun</c> is
+	prior to any other <c>crypto</c> operation. The returned <c>CryptoState</c> is then folded into
+	repeated applications of the <c>EncryptFun</c> or <c>DecryptFun</c>. The binary returned
+	from those funs are sent further to the remote SFTP server. Finally, if doing encryption,
+	the <c>CloseFun</c> is applied to the last piece of data. The <c>CloseFun</c> is
 	responsible for padding (if needed) and encryption of that last piece.
 	</p>
 	<p>The <c>ChunkSize</c> defines the size of the <c>PlainBin</c>s that <c>EncodeFun</c> is applied
-	to. If the <c>ChunkSize</c> is <c>undefined</c> the size of the <c>PlainBin</c>s varies because
-	this is	inteded for stream crypto while a fixed  <c>ChunkSize</c> is intended for block crypto. It
-	is possible to change the  <c>ChunkSize</c>s in the return from the <c>EncryptFun</c> or
-	<c>DecryptFun</c>. It is in fact possible to change the value between <c>pos_integer()</c> and
-	<c>undefined</c>.
+	to. If the <c>ChunkSize</c> is <c>undefined</c>, the size of the <c>PlainBin</c>s varies,
+	because this is	intended for stream crypto, whereas a fixed <c>ChunkSize</c> is intended for block crypto.
+	<c>ChunkSize</c>s can be changed in the return from the <c>EncryptFun</c> or
+	<c>DecryptFun</c>. The value can be changed between <c>pos_integer()</c> and <c>undefined</c>.
 	</p>
-	<p>The write and read example above can be extended with encryption and decryption:</p>
-        <code type="none">
-          %% First three parameters depending on which crypto type we select:
-          Key = &lt;&lt;"This is a 256 bit key. abcdefghi">>,
-          Ivec0 = crypto:rand_bytes(16),
-          DataSize = 1024,  % DataSize rem 16 = 0 for aes_cbc
-
-          %% Initialization of the CryptoState, in this case it is the Ivector.
-          InitFun = fun() -> {ok, Ivec0, DataSize} end,
-
-          %% How to encrypt:
-          EncryptFun = 
-              fun(PlainBin,Ivec) -> 
-                   EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec, PlainBin),
-                   {ok, EncryptedBin, crypto:next_iv(aes_cbc,EncryptedBin)}
-              end,
-
-          %% What to do with the very last block:
-          CloseFun = 
-              fun(PlainBin, Ivec) ->
-                    EncryptedBin = crypto:block_encrypt(aes_cbc256, Key, Ivec, 
-                                                     pad(16,PlainBin) %% Last chunk
-                                                     ),
-                    {ok, EncryptedBin} 
-            end,
-
-          Cw = {InitFun,EncryptFun,CloseFun},
-          {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write,{crypto,Cw}]),
-          ok = erl_tar:add(HandleWrite, .... ),
-          ok = erl_tar:add(HandleWrite, .... ),
-              ...
-          ok = erl_tar:add(HandleWrite, .... ),
-          ok = erl_tar:close(HandleWrite),
-
-          %% And for decryption (in this crypto example we could use the same InitFun
-          %% as for encryption):
-          DecryptFun = 
-              fun(EncryptedBin,Ivec) ->
-                   PlainBin = crypto:block_decrypt(aes_cbc256, Key, Ivec, EncryptedBin),
-                   {ok, PlainBin, crypto:next_iv(aes_cbc,EncryptedBin)}
-              end,
-
-          Cr = {InitFun,DecryptFun},
-          {ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cw}]),
-          {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]),
-          ok = erl_tar:close(HandleRead),
-        </code>
+
       </desc>
     </func>
 
     <func>
-      <name>close(ChannelPid, Handle) -> </name>
-      <name>close(ChannelPid, Handle, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Close an open handle</fsummary>
+      <name>position(ChannelPid, Handle, Location) -></name>
+      <name>position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error}</name>
+      <fsummary>Sets the file position of a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
+        <v>Location = Offset
+ | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
+        <v>Offset = integer()</v>
 	<v>Timeout = timeout()</v>
+        <v>NewPosition = integer()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Closes a handle to an open file or directory on the server.</p>
+        <p>Sets the file position of the file referenced by <c><![CDATA[Handle]]></c>.
+          Returns <c><![CDATA[{ok, NewPosition}]]></c> (as an absolute offset) if
+          successful, otherwise <c><![CDATA[{error, Reason}]]></c>. <c><![CDATA[Location]]></c> is
+          one of the following:</p>
+        <taglist>
+          <tag><c><![CDATA[Offset]]></c></tag>
+          <item>
+            <p>The same as <c><![CDATA[{bof, Offset}]]></c>.</p>
+          </item>
+          <tag><c><![CDATA[{bof, Offset}]]></c></tag>
+          <item>
+            <p>Absolute offset.</p>
+          </item>
+          <tag><c><![CDATA[{cur, Offset}]]></c></tag>
+          <item>
+            <p>Offset from the current position.</p>
+          </item>
+          <tag><c><![CDATA[{eof, Offset}]]></c></tag>
+          <item>
+            <p>Offset from the end of file.</p>
+          </item>
+          <tag><c><![CDATA[bof | cur | eof]]></c></tag>
+          <item>
+            <p>The same as eariler with <c><![CDATA[Offset]]></c> 0,
+	    that is, <c><![CDATA[{bof, 0} | {cur, 0} | {eof, 0}]]></c>.
+	    </p>
+          </item>
+        </taglist>
       </desc>
     </func>
+
     <func>
-      <name>read(ChannelPid, Handle, Len) -> </name>
-      <name>read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error}</name>
-      <name>pread(ChannelPid, Handle, Position, Len) -> </name>
+      <name>pread(ChannelPid, Handle, Position, Len) -></name>
       <name>pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error}</name>
-      <fsummary>Read from an open file</fsummary>
+      <fsummary>Reads from an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
@@ -336,47 +385,16 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Reads <c><![CDATA[Len]]></c> bytes from the file referenced by
-          <c><![CDATA[Handle]]></c>. Returns <c><![CDATA[{ok, Data}]]></c>, <c><![CDATA[eof]]></c>, or
-          <c><![CDATA[{error, Reason}]]></c>. If the file is opened with <c><![CDATA[binary]]></c>,
-          <c><![CDATA[Data]]></c> is a binary, otherwise it is a string.</p>
-        <p>If the file is read past eof, only the remaining bytes
-          will be read and returned. If no bytes are read, <c><![CDATA[eof]]></c>
-          is returned.</p>
-        <p>The <c><![CDATA[pread]]></c> function reads from a specified position,
-          combining the <c><![CDATA[position]]></c> and <c><![CDATA[read]]></c> functions.</p>
-      </desc>
-    </func>
-    <func>
-      <name>aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error}</name>
-      <name>apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error}</name>
-      <fsummary>Read asynchronously from an open file</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Position = integer()</v>
-        <v>Len = integer()</v>
-        <v>N = term()</v>
-        <v>Reason = term()</v>
-      </type>
-      <desc>
-        <p>Reads from an open file, without waiting for the result. If the
-          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where N
-          is a term guaranteed to be unique between calls of <c><![CDATA[aread]]></c>. 
-          The actual data is sent as a message to the calling process. This
-          message has the form <c><![CDATA[{async_reply, N, Result}]]></c>, where
-          <c><![CDATA[Result]]></c> is the result from the read, either <c><![CDATA[{ok, Data}]]></c>,
-          or <c><![CDATA[eof]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
-        <p>The <c><![CDATA[apread]]></c> function reads from a specified position,
-          combining the <c><![CDATA[position]]></c> and <c><![CDATA[aread]]></c> functions.</p>
+	<p>The <c><![CDATA[pread]]></c> function reads from a specified position,
+	combining the <c><![CDATA[position]]></c> and <c><![CDATA[read]]></c> functions.</p>
+	<p><seealso marker="#read-4">ssh_sftp:read/4</seealso></p>
       </desc>
     </func>
+
     <func>
-      <name>write(ChannelPid, Handle, Data) -></name>
-      <name>write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error}</name>
-      <name>pwrite(ChannelPid, Handle, Position, Data) -> ok </name>
+      <name>pwrite(ChannelPid, Handle, Position, Data) -> ok</name>
       <name>pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error}</name>
-      <fsummary>Write to an open file</fsummary>
+      <fsummary>Writes to an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
@@ -386,94 +404,59 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Writes<c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
-          The file should be opened with <c><![CDATA[write]]></c> or <c><![CDATA[append]]></c>
-          flag. Returns <c><![CDATA[ok]]></c> if successful or S<c><![CDATA[{error, Reason}]]></c>
-          otherwise.</p>
-        <p>Typical error reasons are:</p>
-        <taglist>
-          <tag><c><![CDATA[ebadf]]></c></tag>
-          <item>
-            <p>The file is not opened for writing.</p>
-          </item>
-          <tag><c><![CDATA[enospc]]></c></tag>
-          <item>
-            <p>There is a no space left on the device.</p>
-          </item>
-        </taglist>
+	<p>The <c><![CDATA[pread]]></c> function writes to a specified position,
+	combining the <c><![CDATA[position]]></c> and <c><![CDATA[write]]></c> functions.</p>
+	<p><seealso marker="#write-3">ssh_sftp:write/3</seealso></p>
       </desc>
     </func>
-    <func>
-      <name>awrite(ChannelPid, Handle, Data) -> ok | {error, Reason} </name>
-      <name>apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason}</name>
-      <fsummary>Write asynchronously to an open file</fsummary>
+
+
+     <func>
+      <name>read(ChannelPid, Handle, Len) -></name>
+      <name>read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error}</name>
+      <fsummary>Reads from an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Handle = term()</v>
         <v>Position = integer()</v>
         <v>Len = integer()</v>
-        <v>Data = binary()</v>
 	<v>Timeout = timeout()</v>
+        <v>Data = string() | binary()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Writes to an open file, without waiting for the result. If the
-          handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where N
-          is a term guaranteed to be unique between calls of
-          <c><![CDATA[awrite]]></c>. The result of the <c><![CDATA[write]]></c> operation is sent
-          as a message to the calling process. This message has the form
-          <c><![CDATA[{async_reply, N, Result}]]></c>, where <c><![CDATA[Result]]></c> is the result
-          from the write, either <c><![CDATA[ok]]></c>, or <c><![CDATA[{error, Error}]]></c>.</p>
-        <p>The <c><![CDATA[apwrite]]></c> writes on a specified position, combining
-          the <c><![CDATA[position]]></c> and <c><![CDATA[awrite]]></c> operations.</p>
+        <p>Reads <c><![CDATA[Len]]></c> bytes from the file referenced by
+          <c><![CDATA[Handle]]></c>. Returns <c><![CDATA[{ok, Data}]]></c>, <c><![CDATA[eof]]></c>, or
+          <c><![CDATA[{error, Reason}]]></c>. If the file is opened with <c><![CDATA[binary]]></c>,
+          <c><![CDATA[Data]]></c> is a binary, otherwise it is a string.</p>
+        <p>If the file is read past <c>eof</c>, only the remaining bytes
+          are read and returned. If no bytes are read, <c><![CDATA[eof]]></c>
+          is returned.</p>
       </desc>
     </func>
-    <func>
-      <name>position(ChannelPid, Handle, Location) -> </name>
-      <name>position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error}</name>
-      <fsummary>Seek position in open file</fsummary>
+
+      <func>
+      <name>read_file(ChannelPid, File) -></name>
+      <name>read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason}</name>
+      <fsummary>Reads a file.</fsummary>
       <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
-        <v>Offset = integer()</v>
+	<v>ChannelPid = pid()</v>
+	<v>File = string()</v>
+        <v>Data = binary()</v>
 	<v>Timeout = timeout()</v>
-        <v>NewPosition = integer()</v>
-        <v>Reason = term()</v>
+	<v>Reason = term()</v>
       </type>
       <desc>
-        <p>Sets the file position of the file referenced by <c><![CDATA[Handle]]></c>.
-          Returns <c><![CDATA[{ok, NewPosition}]]></c> (as an absolute offset) if
-          successful, otherwise <c><![CDATA[{error, Reason}]]></c>. <c><![CDATA[Location]]></c> is
-          one of the following:</p>
-        <taglist>
-          <tag><c><![CDATA[Offset]]></c></tag>
-          <item>
-            <p>The same as <c><![CDATA[{bof, Offset}]]></c>.</p>
-          </item>
-          <tag><c><![CDATA[{bof, Offset}]]></c></tag>
-          <item>
-            <p>Absolute offset.</p>
-          </item>
-          <tag><c><![CDATA[{cur, Offset}]]></c></tag>
-          <item>
-            <p>Offset from the current position.</p>
-          </item>
-          <tag><c><![CDATA[{eof, Offset}]]></c></tag>
-          <item>
-            <p>Offset from the end of file.</p>
-          </item>
-          <tag><c><![CDATA[bof | cur | eof]]></c></tag>
-          <item>
-            <p>The same as above with <c><![CDATA[Offset]]></c> 0.</p>
-          </item>
-        </taglist>
+        <p>Reads a file from the server, and returns the data in a binary,
+          like
+	   <seealso marker="file#read_file-1">file:read_file/1</seealso></p>
       </desc>
     </func>
-    <func>
-      <name>read_file_info(ChannelPid, Name) -> </name>
+
+      <func>
+      <name>read_file_info(ChannelPid, Name) -></name>
       <name>read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}</name>
-      <fsummary>Get information about a file</fsummary>
+      <fsummary>Gets information about a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
@@ -484,137 +467,190 @@
       </type>
       <desc>
         <p>Returns a <c><![CDATA[file_info]]></c> record from the file specified by
-          <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>, like <c><![CDATA[file:read_file_info/2]]></c>.</p>
+          <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>,
+	like <seealso marker="file#read_file_info-2">file:read_file_info/2</seealso></p>
       </desc>
     </func>
-    <func>
-      <name>read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason}</name>
-      <name>read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}</name>
-      <fsummary>Get information about a symbolic link</fsummary>
+
+     <func>
+      <name>read_link(ChannelPid, Name) -></name>
+      <name>read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason}</name>
+      <fsummary>Reads symbolic link.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
-        <v>Handle = term()</v>
-	<v>Timeout = timeout()</v>
-        <v>FileInfo = record()</v>
+        <v>Target = string()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Returns a <c><![CDATA[file_info]]></c> record from the symbolic
-          link specified by <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>, like
-          <c><![CDATA[file:read_link_info/2]]></c>.</p>
+        <p>Reads the link target from the symbolic link specified
+          by <c><![CDATA[name]]></c>, like
+	  <seealso marker="file#read_link-1">file:read_link/1</seealso></p>
       </desc>
     </func>
-    <func>
-      <name>write_file_info(ChannelPid, Name, Info) -> </name>
-      <name>write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Write information for a file</fsummary>
+
+     <func>
+      <name>read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason}</name>
+      <name>read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}</name>
+      <fsummary>Gets information about a symbolic link.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
-        <v>Info = record()</v>
+        <v>Handle = term()</v>
 	<v>Timeout = timeout()</v>
+        <v>FileInfo = record()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Writes file information from a <c><![CDATA[file_info]]></c> record to the
-          file specified by <c><![CDATA[Name]]></c>, like <c><![CDATA[file:write_file_info]]></c>.</p>
+        <p>Returns a <c><![CDATA[file_info]]></c> record from the symbolic
+          link specified by <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>, like
+	<seealso marker="file#read_link_info-2">file:read_link_info/2</seealso></p>
       </desc>
     </func>
+
     <func>
-      <name>read_link(ChannelPid, Name) -> </name>
-      <name>read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason}</name>
-      <fsummary>Read symbolic link</fsummary>
+      <name>rename(ChannelPid, OldName, NewName) -> </name>
+      <name>rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Renames a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-        <v>Target = string()</v>
+        <v>OldName = string()</v>
+        <v>NewName = string()</v>
+	<v>Timeout = timeout()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Reads the link target from the symbolic link specified
-          by <c><![CDATA[name]]></c>, like <c><![CDATA[file:read_link/1]]></c>.</p>
+        <p>Renames a file named <c><![CDATA[OldName]]></c> and gives it the name
+          <c><![CDATA[NewName]]></c>, like
+	    <seealso marker="file#rename-2">file:rename/2</seealso></p>
       </desc>
     </func>
+
     <func>
-      <name>make_symlink(ChannelPid, Name, Target) -> </name>
-      <name>make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Create symbolic link</fsummary>
+      <name>start_channel(ConnectionRef) -></name>
+      <name>start_channel(ConnectionRef, Options) -></name>
+      <name>start_channel(Host, Options) -></name>
+      <name>start_channel(Host, Port, Options) -> {ok, Pid} | {ok, Pid, ConnectionRef} |
+      {error, Reason}</name>
+      <fsummary>Starts an SFTP client.</fsummary>
       <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-        <v>Target = string()</v>
+        <v>Host = string()</v>
+        <v>ConnectionRef = ssh_connection_ref()</v>
+        <v>Port = integer()</v>
+        <v>Options = [{Option, Value}]</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Creates a symbolic link pointing to <c><![CDATA[Target]]></c> with the
-          name <c><![CDATA[Name]]></c>, like <c><![CDATA[file:make_symlink/2]]></c>.</p>
+	<p>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 <c>pid</c> for this process is to be used as input to
+	all other API functions in this module.</p>
+
+	<p>Options:</p>
+	<taglist>
+          <tag><c><![CDATA[{timeout, timeout()}]]></c></tag>
+	  <item>
+	    <p>The time-out is passed to the <c>ssh_channel</c> start function,
+	    and defaults to <c>infinity</c>.</p>
+	  </item>
+	  <tag>
+	    <c><![CDATA[{sftp_vsn, integer()}]]></c>
+	  </tag>
+	  <item>
+	    <p>
+	      Desired SFTP protocol version.
+	      The actual version is the minimum of
+	      the desired version and the maximum supported
+	      versions by the SFTP server.
+	    </p>
+	  </item>
+	</taglist>
+	<p>All other options are directly passed to
+	<seealso marker="ssh">ssh:connect/3</seealso> or ignored if a
+	connection is already provided.</p>
       </desc>
     </func>
-    <func>
-      <name>rename(ChannelPid, OldName, NewName) ->  </name>
-      <name>rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Rename a file</fsummary>
+
+     <func>
+      <name>stop_channel(ChannelPid) -> ok</name>
+      <fsummary>Stops the SFTP client channel.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
-        <v>OldName = string()</v>
-        <v>NewName = string()</v>
-	<v>Timeout = timeout()</v>
-        <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Renames a file named <c><![CDATA[OldName]]></c>, and gives it the name
-          <c><![CDATA[NewName]]></c>, like <c><![CDATA[file:rename/2]]></c></p>
+	<p>Stops an SFTP channel. Does not close the SSH connection.
+	Use <seealso marker="ssh#close-1">ssh:close/1</seealso> to close it.</p>
       </desc>
     </func>
+
     <func>
-      <name>delete(ChannelPid, Name) -> </name>
-      <name>delete(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Delete a file</fsummary>
+      <name>write_file(ChannelPid, File, Iolist) -></name>
+      <name>write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Writes a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
+        <v>File = string()</v>
+        <v>Iolist = iolist()</v>
 	<v>Timeout = timeout()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Deletes the file specified by <c><![CDATA[Name]]></c>, like
-          <c><![CDATA[file:delete/1]]></c></p>
+        <p>Writes a file to the server, like <seealso
+        marker="file#write_file-2">file:write_file/2</seealso> The
+        file is created if it does not exist. The file is overwritten
+        if it exists.</p>
       </desc>
     </func>
+
     <func>
-      <name>make_dir(ChannelPid, Name) -> </name>
-      <name>make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Create a directory</fsummary>
+      <name>write(ChannelPid, Handle, Data) -></name>
+      <name>write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error}</name>
+      <fsummary>Writes to an open file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
+        <v>Handle = term()</v>
+        <v>Position = integer()</v>
+        <v>Data = iolist()</v>
 	<v>Timeout = timeout()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>Creates a directory specified by <c><![CDATA[Name]]></c>. <c><![CDATA[Name]]></c> should
-          be a full path to a new directory. The directory can only be
-          created in an existing directory.</p>
+        <p>Writes <c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
+          The file is to be opened with <c><![CDATA[write]]></c> or <c><![CDATA[append]]></c>
+          flag. Returns <c><![CDATA[ok]]></c> if successful or <c><![CDATA[{error, Reason}]]></c>
+          otherwise.</p>
+        <p>Typical error reasons:</p>
+        <taglist>
+          <tag><c><![CDATA[ebadf]]></c></tag>
+          <item>
+            <p>File is not opened for writing.</p>
+          </item>
+          <tag><c><![CDATA[enospc]]></c></tag>
+          <item>
+            <p>No space is left on the device.</p>
+          </item>
+        </taglist>
       </desc>
     </func>
+
     <func>
-      <name>del_dir(ChannelPid, Name) -> </name>
-      <name>del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}</name>
-      <fsummary>Delete an empty directory</fsummary>
+      <name>write_file_info(ChannelPid, Name, Info) -></name>
+      <name>write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason}</name>
+      <fsummary>Writes information for a file.</fsummary>
       <type>
         <v>ChannelPid = pid()</v>
         <v>Name = string()</v>
+        <v>Info = record()</v>
 	<v>Timeout = timeout()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-	<p>Deletes a directory specified by <c><![CDATA[Name]]></c>.
-	Note that the directory must be empty before it can be successfully deleted
-	</p>
+        <p>Writes file information from a <c><![CDATA[file_info]]></c> record to the
+          file specified by <c><![CDATA[Name]]></c>, like
+	   <seealso marker="file#write_file_info-2">file:write_file_info/[2,3]</seealso></p>
       </desc>
     </func>
-  
   </funcs>
    
 </erlref>