aboutsummaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorHans Nilsson <[email protected]>2019-06-27 16:29:19 +0200
committerHans Nilsson <[email protected]>2019-08-12 17:09:16 +0200
commit42a916716671d6f553f5c25d8a8c98d34a7f1da5 (patch)
tree943256f65e1b33772e9179276e5a620b2944bdc0 /lib
parent8bf1bd07face1af84fbded1281e4877f28e0e9fa (diff)
downloadotp-42a916716671d6f553f5c25d8a8c98d34a7f1da5.tar.gz
otp-42a916716671d6f553f5c25d8a8c98d34a7f1da5.tar.bz2
otp-42a916716671d6f553f5c25d8a8c98d34a7f1da5.zip
ssh: The ssh_sftp documentation is now generated
Diffstat (limited to 'lib')
-rw-r--r--lib/ssh/doc/src/ssh_sftp.xml436
-rw-r--r--lib/ssh/doc/src/using_ssh.xml14
-rw-r--r--lib/ssh/src/ssh_sftp.erl326
3 files changed, 485 insertions, 291 deletions
diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
index c89092798d..76d2b21946 100644
--- a/lib/ssh/doc/src/ssh_sftp.xml
+++ b/lib/ssh/doc/src/ssh_sftp.xml
@@ -37,60 +37,106 @@
SSH.</p>
</description>
- <section>
- <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>
-
- <taglist>
- <tag><c>reason()</c></tag>
- <item>
- <p>= <c>atom() | string() | tuple() </c>A description of the reason why an operation failed.</p>
- <p>
- The <c>atom()</c> value is formed from the sftp error codes in the protocol-level responses as defined in
- <url href="https://tools.ietf.org/id/draft-ietf-secsh-filexfer-13.txt">draft-ietf-secsh-filexfer-13.txt</url>
- section 9.1.
- </p>
- <p>
+ <datatypes>
+ <datatype_title>Error cause</datatype_title>
+ <datatype>
+ <name name="reason"/>
+ <desc>
+ <p>A description of the reason why an operation failed.</p>
+ <p>The <c>atom()</c> value is formed from the sftp error codes in the protocol-level responses as defined in
+ <url href="https://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#page-49">draft-ietf-secsh-filexfer-13</url>
+ section 9.1.
The codes are named as <c>SSH_FX_*</c> which are transformed into lowercase of the star-part.
E.g. the error code <c>SSH_FX_NO_SUCH_FILE</c>
will cause the <c>reason()</c> to be <c>no_such_file</c>.
</p>
<p>The <c>string()</c> reason is the error information from the server in case of an exit-signal. If that information is empty, the reason is the exit signal name.
</p>
- <p>The <c>tuple()</c> reason are other errors like the <c>{exit_status,integer()}</c> if the exit status is not 0.
+ <p>The <c>tuple()</c> reason are other errors like for example <c>{exit_status,1}</c>.
+ </p>
+ </desc>
+ </datatype>
+
+ <datatype_title>Crypto operations for open_tar</datatype_title>
+ <datatype>
+ <name name="tar_crypto_spec"/>
+ <name name="encrypt_spec"/>
+ <name name="decrypt_spec"/>
+ <desc>
+ <p>Specifies the encryption or decryption applied to tar files when using
+ <seealso marker="#open_tar/3">open_tar/3</seealso> or
+ <seealso marker="#open_tar/4">open_tar/4</seealso>.
+ </p>
+ <p>The encryption or decryption is applied to the generated stream of
+ bytes prior to sending the resulting stream to the SFTP server.
+ </p>
+ <p>For code examples see Section
+ <seealso marker="using_ssh#example-with-encryption">Example with encryption</seealso>
+ in the ssh Users Guide.
</p>
- </item>
+ </desc>
+ </datatype>
- <tag><c>connection_ref() =</c></tag>
- <item><p><c>opaque()</c> - as returned by
- <seealso marker="ssh#connect-3"><c>ssh:connect/3</c></seealso></p></item>
+ <datatype>
+ <name name="init_fun"/>
+ <name name="chunk_size"/>
+ <name name="crypto_state"/>
+ <desc>
+ <p>The <c>init_fun()</c> in the
+ <seealso marker="#type-tar_crypto_spec">tar_crypto_spec</seealso>
+ is applied once prior to any other <c>crypto</c>
+ operation. The intention is that this function initiates the encryption or
+ decryption for example by calling
+ <seealso marker="crypto:crypto#crypto_init/4">crypto:crypto_init/4</seealso>
+ or similar. The <c>crypto_state()</c> is the state such a function may return.
+ </p>
+ <p>If the selected cipher needs to have the input data partioned into
+ blocks of a certain size, the <c>init_fun()</c> should return the second
+ form of return value with the <c>chunk_size()</c> set to the block size.
+ If the <c>chunk_size()</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>chunk_size()</c> is intended for block crypto.
+ A <c>chunk_size()</c> can be changed in the return from the <c>crypto_fun()</c>.
+ The value can be changed between <c>pos_integer()</c> and <c>undefined</c>.
+ </p>
+ </desc>
+ </datatype>
- <tag><c>timeout()</c></tag>
- <item><p>= <c>infinity | integer()</c> in milliseconds. Default infinity.</p></item>
- </taglist>
- </section>
+ <datatype>
+ <name name="crypto_fun"/>
+ <name name="crypto_result"/>
+ <desc>
+ <p>The initial <c>crypto_state()</c> returned from the
+ <seealso marker="#type-init_fun">init_fun()</seealso>
+ is folded into repeated applications of the <c>crypto_fun()</c> in the
+ <seealso marker="#type-tar_crypto_spec">tar_crypto_spec</seealso>.
+ The binary returned from that fun is sent to the remote SFTP server and
+ the new <c>crypto_state()</c> is used in the next call of the
+ <c>crypto_fun()</c>.
+ </p>
+ <p>If the <c>crypto_fun()</c> reurns a <c>chunk_size()</c>, that value
+ is as block size for further blocks in calls to <c>crypto_fun()</c>.
+ </p>
+ </desc>
+ </datatype>
- <section>
- <title>Time-outs</title>
- <p>If the request functions for the SFTP channel return <c>{error, timeout}</c>,
- no answer was received from the server within the expected time.</p>
- <p>The request may have reached the server and may have been performed.
- However, no answer was received from the server within the expected time.</p>
- </section>
+ <datatype>
+ <name name="final_fun"/>
+ <desc>
+ <p>If doing encryption,
+ the <c>final_fun()</c> in the
+ <seealso marker="#type-tar_crypto_spec">tar_crypto_spec</seealso>
+ is applied to the last piece of data.
+ The <c>final_fun()</c> is responsible for padding (if needed) and
+ encryption of that last piece.
+ </p>
+ </desc>
+ </datatype>
+ </datatypes>
<funcs>
<func>
- <name since="">apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, reason()}</name>
+ <name name="apread" arity="4" since=""/>
<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>
- </type>
<desc><p>The <c><![CDATA[apread/4]]></c> function reads from a specified position,
combining the <seealso marker="#position-3"><c>position/3</c></seealso> and
<seealso marker="#aread-3"><c>aread/3</c></seealso> functions.</p>
@@ -98,17 +144,8 @@
</func>
<func>
- <name since="">apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | {error, reason()}</name>
+ <name name="apwrite" arity="4" since=""/>
<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>N = term()</v>
- </type>
<desc><p>The <c><![CDATA[apwrite/4]]></c> function writes to a specified position,
combining the <seealso marker="#position-3"><c>position/3</c></seealso> and
<seealso marker="#awrite-3"><c>awrite/3</c></seealso> functions.</p>
@@ -116,15 +153,8 @@
</func>
<func>
- <name since="">aread(ChannelPid, Handle, Len) -> {async, N} | {error, reason()}</name>
+ <name name="aread" arity="3" since=""/>
<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>
- </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>
@@ -137,16 +167,8 @@
</func>
<func>
- <name since="">awrite(ChannelPid, Handle, Data) -> {async, N} | {error, reason()}</name>
+ <name name="awrite" arity="3" since=""/>
<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>
- </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>
@@ -159,28 +181,18 @@
</func>
<func>
- <name since="">close(ChannelPid, Handle) -></name>
- <name since="">close(ChannelPid, Handle, Timeout) -> ok | {error, reason()}</name>
+ <name name="close" arity="2" since=""/>
+ <name name="close" arity="3" since=""/>
<fsummary>Closes an open handle.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Handle = term()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Closes a handle to an open file or directory on the server.</p>
</desc>
</func>
<func>
- <name since="">delete(ChannelPid, Name) -></name>
- <name since="">delete(ChannelPid, Name, Timeout) -> ok | {error, reason()}</name>
+ <name name="delete" arity="2" since=""/>
+ <name name="delete" arity="3" since=""/>
<fsummary>Deletes a file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Deletes the file specified by <c><![CDATA[Name]]></c>.
</p>
@@ -188,14 +200,9 @@
</func>
<func>
- <name since="">del_dir(ChannelPid, Name) -></name>
- <name since="">del_dir(ChannelPid, Name, Timeout) -> ok | {error, reason()}</name>
+ <name name="del_dir" arity="2" since=""/>
+ <name name="del_dir" arity="3" since=""/>
<fsummary>Deletes an empty directory.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Deletes a directory specified by <c><![CDATA[Name]]></c>.
The directory must be empty before it can be successfully deleted.
@@ -204,16 +211,9 @@
</func>
<func>
- <name since="">list_dir(ChannelPid, Path) -></name>
- <name since="">list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, reason()}</name>
+ <name name="list_dir" arity="2" since=""/>
+ <name name="list_dir" arity="3" since=""/>
<fsummary>Lists the directory.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Path = string()</v>
- <v>Filenames = [Filename]</v>
- <v>Filename = string()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Lists the given directory on the server, returning the
filenames as a list of strings.</p>
@@ -221,14 +221,9 @@
</func>
<func>
- <name since="">make_dir(ChannelPid, Name) -></name>
- <name since="">make_dir(ChannelPid, Name, Timeout) -> ok | {error, reason()}</name>
+ <name name="make_dir" arity="2" since=""/>
+ <name name="make_dir" arity="3" since=""/>
<fsummary>Creates a directory.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Timeout = timeout()</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
@@ -237,14 +232,9 @@
</func>
<func>
- <name since="">make_symlink(ChannelPid, Name, Target) -></name>
- <name since="">make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, reason()}</name>
+ <name name="make_symlink" arity="3" since=""/>
+ <name name="make_symlink" arity="4" since=""/>
<fsummary>Creates a symbolic link.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Target = string()</v>
- </type>
<desc>
<p>Creates a symbolic link pointing to <c><![CDATA[Target]]></c> with the
name <c><![CDATA[Name]]></c>.
@@ -252,32 +242,19 @@
</desc>
</func>
- <func>
- <name since="">open(ChannelPid, File, Mode) -></name>
- <name since="">open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, reason()}</name>
+ <func>
+ <name name="open" arity="3" since=""/>
+ <name name="open" arity="4" since=""/>
<fsummary>Opens a file and returns a handle.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>File = string()</v>
- <v>Mode = [Modeflag]</v>
- <v>Modeflag = read | write | creat | trunc | append | binary</v>
- <v>Timeout = timeout()</v>
- <v>Handle = term()</v>
- </type>
<desc>
<p>Opens a file on the server and returns a handle, which
can be used for reading or writing.</p>
</desc>
</func>
<func>
- <name since="">opendir(ChannelPid, Path) -></name>
- <name since="">opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, reason()}</name>
+ <name name="opendir" arity="2" since=""/>
+ <name name="opendir" arity="3" since=""/>
<fsummary>Opens a directory and returns a handle.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Path = string()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Opens a handle to a directory on the server. The handle
can be used for reading directory contents.</p>
@@ -285,72 +262,36 @@
</func>
<func>
- <name since="OTP 17.4">open_tar(ChannelPid, Path, Mode) -></name>
- <name since="OTP 17.4">open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, reason()}</name>
+ <name name="open_tar" arity="3" since="OTP 17.4"/>
+ <name name="open_tar" arity="4" since="OTP 17.4"/>
<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>EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}}</v>
- <v>DecryptOpt = {crypto,{InitFun,DecryptFun}}</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>
- <v>EncryptResult = {ok,EncryptedBin,CryptoState} | {ok,EncryptedBin,CryptoState,ChunkSize}</v>
- <v>PlainBin = binary()</v>
- <v>EncryptedBin = binary()</v>
- <v>DecryptFun = (fun(EncryptedBin,CryptoState) -> DecryptResult)</v>
- <v>DecryptResult = {ok,PlainBin,CryptoState} | {ok,PlainBin,CryptoState,ChunkSize}</v>
- <v>CloseFun = (fun(PlainBin,CryptoState) -> {ok,EncryptedBin})</v>
- <v>Timeout = timeout()</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>
-
- <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.
+ The handle can be used for remote tar creation and extraction. The actual writing
+ and reading is performed by calls to
+ <seealso marker="stdlib:erl_tar#add-3">erl_tar:add/3,4</seealso> and
+ <seealso marker="stdlib:erl_tar#extract-2">erl_tar:extract/2</seealso>.
+ Note: The
+ <seealso marker="stdlib:erl_tar#init-3">erl_tar:init/3</seealso> function should not
+ be called, that one is called by this open_tar function.
</p>
- <p>The <c>InitFun</c> is applied once
- 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>For code examples see Section
+ <seealso marker="using_ssh#sftp-client-with-tar-compression">SFTP Client with TAR Compression</seealso>
+ in the ssh Users Guide.
</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 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>The <c>crypto</c> mode option is explained in the data types section above, see
+ <seealso marker="#Crypto operations for open_tar">Crypto operations for open_tar</seealso>.
+ Encryption is assumed if the <c>Mode</c> contains <c>write</c>, and
+ decryption if the <c>Mode</c> contains <c>read</c>.
</p>
-
</desc>
</func>
<func>
- <name since="">position(ChannelPid, Handle, Location) -></name>
- <name since="">position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, reason()}</name>
+ <name name="position" arity="3" since=""/>
+ <name name="position" arity="4" since=""/>
<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>
- </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
@@ -384,17 +325,9 @@
</func>
<func>
- <name since="">pread(ChannelPid, Handle, Position, Len) -></name>
- <name since="">pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, reason()}</name>
+ <name name="pread" arity="4" since=""/>
+ <name name="pread" arity="5" since=""/>
<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>Timeout = timeout()</v>
- <v>Data = string() | binary()</v>
- </type>
<desc><p>The <c><![CDATA[pread/3,4]]></c> function reads from a specified position,
combining the <seealso marker="#position-3"><c>position/3</c></seealso> and
<seealso marker="#read-3"><c>read/3,4</c></seealso> functions.</p>
@@ -402,16 +335,9 @@
</func>
<func>
- <name since="">pwrite(ChannelPid, Handle, Position, Data) -> ok</name>
- <name since="">pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, reason()}</name>
+ <name name="pwrite" arity="4" since=""/>
+ <name name="pwrite" arity="5" since=""/>
<fsummary>Writes to an open file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Handle = term()</v>
- <v>Position = integer()</v>
- <v>Data = iolist()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc><p>The <c><![CDATA[pwrite/3,4]]></c> function writes to a specified position,
combining the <seealso marker="#position-3"><c>position/3</c></seealso> and
<seealso marker="#write-3"><c>write/3,4</c></seealso> functions.</p>
@@ -419,16 +345,9 @@
</func>
<func>
- <name since="">read(ChannelPid, Handle, Len) -></name>
- <name since="">read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, reason()}</name>
+ <name name="read" arity="3" since=""/>
+ <name name="read" arity="4" since=""/>
<fsummary>Reads from an open file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Handle = term()</v>
- <v>Len = integer()</v>
- <v>Timeout = timeout()</v>
- <v>Data = string() | binary()</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
@@ -440,32 +359,19 @@
</desc>
</func>
- <func>
- <name since="">read_file(ChannelPid, File) -></name>
- <name since="">read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, reason()}</name>
+ <func>
+ <name name="read_file" arity="2" since=""/>
+ <name name="read_file" arity="3" since=""/>
<fsummary>Reads a file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>File = string()</v>
- <v>Data = binary()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Reads a file from the server, and returns the data in a binary.</p>
</desc>
</func>
- <func>
- <name since="">read_file_info(ChannelPid, Name) -></name>
- <name since="">read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, reason()}</name>
+ <func>
+ <name name="read_file_info" arity="2" since=""/>
+ <name name="read_file_info" arity="3" since=""/>
<fsummary>Gets information about a file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Handle = term()</v>
- <v>Timeout = timeout()</v>
- <v>FileInfo = record()</v>
- </type>
<desc>
<p>Returns a <c><![CDATA[file_info]]></c> record from the file system object specified by
<c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>. See
@@ -474,38 +380,26 @@
</p>
<p>
Depending on the underlying OS:es links might be followed and info on the final file, directory
- etc is returned. See <seealso marker="#read_link_info-2">ssh_sftp::read_link_info/2</seealso>
+ etc is returned. See <seealso marker="#read_link_info-2">read_link_info/2</seealso>
on how to get information on links instead.
</p>
</desc>
</func>
<func>
- <name since="">read_link(ChannelPid, Name) -></name>
- <name since="">read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, reason()}</name>
+ <name name="read_link" arity="2" since=""/>
+ <name name="read_link" arity="3" since=""/>
<fsummary>Reads symbolic link.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Target = string()</v>
- </type>
<desc>
<p>Reads the link target from the symbolic link specified by <c><![CDATA[name]]></c>.
</p>
</desc>
</func>
- <func>
- <name since="">read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, reason()}</name>
- <name since="">read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, reason()}</name>
+ <func>
+ <name since="" name="read_link_info" arity="2"/>
+ <name since="" name="read_link_info" arity="3"/>
<fsummary>Gets information about a symbolic link.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Handle = term()</v>
- <v>Timeout = timeout()</v>
- <v>FileInfo = record()</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>.
@@ -517,15 +411,9 @@
</func>
<func>
- <name since="">rename(ChannelPid, OldName, NewName) -> </name>
- <name since="">rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, reason()}</name>
+ <name since="" name="rename" arity="3"/>
+ <name since="" name="rename" arity="4"/>
<fsummary>Renames a file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>OldName = string()</v>
- <v>NewName = string()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Renames a file named <c><![CDATA[OldName]]></c> and gives it the name
<c><![CDATA[NewName]]></c>.
@@ -594,11 +482,8 @@
</func>
<func>
- <name since="">stop_channel(ChannelPid) -> ok</name>
+ <name since="" name="stop_channel" arity="1"/>
<fsummary>Stops the SFTP client channel.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- </type>
<desc>
<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>
@@ -606,16 +491,9 @@
</func>
<func>
- <name since="">write(ChannelPid, Handle, Data) -></name>
- <name since="">write(ChannelPid, Handle, Data, Timeout) -> ok | {error, reason()}</name>
+ <name since="" name="write" arity="3"/>
+ <name since="" name="write" arity="4"/>
<fsummary>Writes to an open file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Handle = term()</v>
- <v>Position = integer()</v>
- <v>Data = iolist()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<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>
@@ -625,15 +503,9 @@
</func>
<func>
- <name since="">write_file(ChannelPid, File, Iolist) -></name>
- <name since="">write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, reason()}</name>
+ <name since="" name="write_file" arity="3"/>
+ <name since="" name="write_file" arity="4"/>
<fsummary>Writes a file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>File = string()</v>
- <v>Iolist = iolist()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Writes a file to the server. The file is created if it does not exist
but overwritten if it exists.</p>
@@ -641,15 +513,9 @@
</func>
<func>
- <name since="">write_file_info(ChannelPid, Name, Info) -></name>
- <name since="">write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, reason()}</name>
+ <name since="" name="write_file_info" arity="3"/>
+ <name since="" name="write_file_info" arity="4"/>
<fsummary>Writes information for a file.</fsummary>
- <type>
- <v>ChannelPid = pid()</v>
- <v>Name = string()</v>
- <v>Info = record()</v>
- <v>Timeout = timeout()</v>
- </type>
<desc>
<p>Writes file information from a <c><![CDATA[file_info]]></c> record to the
file specified by <c><![CDATA[Name]]></c>. See
diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml
index 4455d5ecc5..5c56dee81d 100644
--- a/lib/ssh/doc/src/using_ssh.xml
+++ b/lib/ssh/doc/src/using_ssh.xml
@@ -232,9 +232,10 @@
</section>
<section>
- <title>SFTP Client with TAR Compression and Encryption</title>
-
- <p>Example of writing and then reading a tar file follows:</p>
+ <title>SFTP Client with TAR Compression</title>
+ <section>
+ <title>Basic example</title>
+ <p>This is an example of writing and then reading a tar file:</p>
<code type="erl">
{ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]),
ok = erl_tar:add(HandleWrite, .... ),
@@ -248,8 +249,12 @@
{ok,NameValueList} = erl_tar:extract(HandleRead,[memory]),
ok = erl_tar:close(HandleRead),
</code>
+ </section>
- <p>The previous write and read example can be extended with encryption and decryption as follows:</p>
+ <section>
+ <title>Example with encryption</title>
+ <p>The previous <seealso marker="using_ssh#basic-example">Basic example</seealso>
+ can be extended with encryption and decryption as follows:</p>
<code type="erl">
%% First three parameters depending on which crypto type we select:
Key = &lt;&lt;"This is a 256 bit key. abcdefghi">>,
@@ -297,6 +302,7 @@ Cr = {InitFun,DecryptFun},
ok = erl_tar:close(HandleRead),
</code>
</section>
+ </section>
<section>
<marker id="usersguide_creating_a_subsystem"/>
diff --git a/lib/ssh/src/ssh_sftp.erl b/lib/ssh/src/ssh_sftp.erl
index 1b2ba5a50b..9162de3487 100644
--- a/lib/ssh/src/ssh_sftp.erl
+++ b/lib/ssh/src/ssh_sftp.erl
@@ -92,16 +92,26 @@
-define(XF(S), S#state.xf).
-define(REQID(S), S#state.req_id).
+
+-type reason() :: atom() | string() | tuple() .
+
%%====================================================================
%% API
%%====================================================================
start_channel(Cm) when is_pid(Cm) ->
start_channel(Cm, []);
+
start_channel(Socket) when is_port(Socket) ->
start_channel(Socket, []);
+
start_channel(Host) when is_list(Host) ->
start_channel(Host, []).
+
+-spec start_channel(ssh:connection_ref() | gen_tcp:socket() | string(),
+ ssh:client_options()
+ ) -> {ok,pid()} | {ok,pid(),ssh:connection_ref()} | {error,term()}.
+
start_channel(Socket, UserOptions) when is_port(Socket) ->
{SshOpts, _ChanOpts, SftpOpts} = handle_options(UserOptions),
Timeout = % A mixture of ssh:connect and ssh_sftp:start_channel:
@@ -144,6 +154,10 @@ start_channel(Cm, UserOptions) when is_pid(Cm) ->
start_channel(Host, UserOptions) ->
start_channel(Host, 22, UserOptions).
+
+-spec start_channel(string(), integer(), ssh:client_options()) ->
+ {ok,pid(),ssh:connection_ref()} | {error,term()}.
+
start_channel(Host, Port, UserOptions) ->
{SshOpts, ChanOpts, SftpOpts} = handle_options(UserOptions),
Timeout = % A mixture of ssh:connect and ssh_sftp:start_channel:
@@ -168,6 +182,10 @@ start_channel(Host, Port, UserOptions) ->
Error
end.
+
+-spec stop_channel(ChannelPid) -> ok when
+ ChannelPid :: pid().
+
stop_channel(Pid) ->
case is_process_alive(Pid) of
true ->
@@ -188,17 +206,62 @@ stop_channel(Pid) ->
wait_for_version_negotiation(Pid, Timeout) ->
call(Pid, wait_for_version_negotiation, Timeout).
+-spec open(ChannelPid, Name, Mode) -> {ok, Handle} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Mode :: [read | write | append | binary | raw],
+ Handle :: term(),
+ Error :: {error, reason()} .
open(Pid, File, Mode) ->
open(Pid, File, Mode, ?FILEOP_TIMEOUT).
+-spec open(ChannelPid, Name, Mode, Timeout) -> {ok, Handle} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Mode :: [read | write | append | binary | raw],
+ Timeout :: timeout(),
+ Handle :: term(),
+ Error :: {error, reason()} .
open(Pid, File, Mode, FileOpTimeout) ->
call(Pid, {open, false, File, Mode}, FileOpTimeout).
+
+-type tar_crypto_spec() :: encrypt_spec() | decrypt_spec() .
+
+-type encrypt_spec() :: {init_fun(), crypto_fun(), final_fun()} .
+-type decrypt_spec() :: {init_fun(), crypto_fun()} .
+
+-type init_fun() :: fun(() -> {ok,crypto_state()})
+ | fun(() -> {ok,crypto_state(),chunk_size()}) .
+
+-type crypto_fun() :: fun((TextIn::binary(), crypto_state()) -> crypto_result()) .
+-type crypto_result() :: {ok,TextOut::binary(),crypto_state()}
+ | {ok,TextOut::binary(),crypto_state(),chunk_size()} .
+
+-type final_fun() :: fun((FinalTextIn::binary(),crypto_state()) -> {ok,FinalTextOut::binary()}) .
+
+-type chunk_size() :: undefined | pos_integer().
+-type crypto_state() :: any() .
+
+
+-spec open_tar(ChannelPid, Path, Mode) -> {ok, Handle} | Error when
+ ChannelPid :: pid(),
+ Path :: string(),
+ Mode :: [read | write | {crypto, tar_crypto_spec()} ],
+ Handle :: term(),
+ Error :: {error, reason()} .
open_tar(Pid, File, Mode) ->
open_tar(Pid, File, Mode, ?FILEOP_TIMEOUT).
+-spec open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | Error when
+ ChannelPid :: pid(),
+ Path :: string(),
+ Mode :: [read | write | {crypto, tar_crypto_spec()} ],
+ Timeout :: timeout(),
+ Handle :: term(),
+ Error :: {error, reason()} .
open_tar(Pid, File, Mode, FileOpTimeout) ->
case {lists:member(write,Mode),
lists:member(read,Mode),
- Mode -- [read,write]} of
+ Mode -- [write,read]} of
{true,false,[]} ->
{ok,Handle} = open(Pid, File, [write], FileOpTimeout),
erl_tar:init(Pid, write,
@@ -264,13 +327,33 @@ open_tar(Pid, File, Mode, FileOpTimeout) ->
end.
+-spec opendir(ChannelPid, Path) -> {ok, Handle} | Error when
+ ChannelPid :: pid(),
+ Path :: string(),
+ Handle :: term(),
+ Error :: {error, reason()} .
opendir(Pid, Path) ->
opendir(Pid, Path, ?FILEOP_TIMEOUT).
+-spec opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | Error when
+ ChannelPid :: pid(),
+ Path :: string(),
+ Timeout :: timeout(),
+ Handle :: term(),
+ Error :: {error, reason()} .
opendir(Pid, Path, FileOpTimeout) ->
call(Pid, {opendir, false, Path}, FileOpTimeout).
+-spec close(ChannelPid, Handle) -> ok | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Error :: {error, reason()} .
close(Pid, Handle) ->
close(Pid, Handle, ?FILEOP_TIMEOUT).
+-spec close(ChannelPid, Handle, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Timeout :: timeout(),
+ Error :: {error, reason()} .
close(Pid, Handle, FileOpTimeout) ->
call(Pid, {close,false,Handle}, FileOpTimeout).
@@ -279,47 +362,149 @@ readdir(Pid,Handle) ->
readdir(Pid,Handle, FileOpTimeout) ->
call(Pid, {readdir,false,Handle}, FileOpTimeout).
+-spec pread(ChannelPid, Handle, Position, Len) -> {ok, Data} | eof | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Position :: integer(),
+ Len :: integer(),
+ Data :: string() | binary(),
+ Error :: {error, reason()}.
pread(Pid, Handle, Offset, Len) ->
pread(Pid, Handle, Offset, Len, ?FILEOP_TIMEOUT).
+
+-spec pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Position :: integer(),
+ Len :: integer(),
+ Timeout :: timeout(),
+ Data :: string() | binary(),
+ Error :: {error, reason()}.
pread(Pid, Handle, Offset, Len, FileOpTimeout) ->
call(Pid, {pread,false,Handle, Offset, Len}, FileOpTimeout).
+
+-spec read(ChannelPid, Handle, Len) -> {ok, Data} | eof | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Len :: integer(),
+ Data :: string() | binary(),
+ Error :: {error, reason()}.
read(Pid, Handle, Len) ->
read(Pid, Handle, Len, ?FILEOP_TIMEOUT).
+
+-spec read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Len :: integer(),
+ Timeout :: timeout(),
+ Data :: string() | binary(),
+ Error :: {error, reason()}.
read(Pid, Handle, Len, FileOpTimeout) ->
call(Pid, {read,false,Handle, Len}, FileOpTimeout).
+
%% TODO this ought to be a cast! Is so in all practical meaning
%% even if it is obscure!
+-spec apread(ChannelPid, Handle, Position, Len) -> {async, N} | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Position :: integer(),
+ Len :: integer(),
+ Error :: {error, reason()},
+ N :: term() .
apread(Pid, Handle, Offset, Len) ->
call(Pid, {pread,true,Handle, Offset, Len}, infinity).
%% TODO this ought to be a cast!
+-spec aread(ChannelPid, Handle, Len) -> {async, N} | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Len :: integer(),
+ Error :: {error, reason()},
+ N :: term() .
aread(Pid, Handle, Len) ->
call(Pid, {read,true,Handle, Len}, infinity).
+
+-spec pwrite(ChannelPid, Handle, Position, Data) -> ok | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Position :: integer(),
+ Data :: iolist(),
+ Error :: {error, reason()}.
pwrite(Pid, Handle, Offset, Data) ->
pwrite(Pid, Handle, Offset, Data, ?FILEOP_TIMEOUT).
+
+-spec pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Position :: integer(),
+ Data :: iolist(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
pwrite(Pid, Handle, Offset, Data, FileOpTimeout) ->
call(Pid, {pwrite,false,Handle,Offset,Data}, FileOpTimeout).
+
+-spec write(ChannelPid, Handle, Data) -> ok | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Data :: iodata(),
+ Error :: {error, reason()}.
write(Pid, Handle, Data) ->
write(Pid, Handle, Data, ?FILEOP_TIMEOUT).
+
+-spec write(ChannelPid, Handle, Data, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Data :: iodata(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
write(Pid, Handle, Data, FileOpTimeout) ->
call(Pid, {write,false,Handle,Data}, FileOpTimeout).
%% TODO this ought to be a cast! Is so in all practical meaning
%% even if it is obscure!
+-spec apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Position :: integer(),
+ Data :: binary(),
+ Error :: {error, reason()},
+ N :: term() .
apwrite(Pid, Handle, Offset, Data) ->
call(Pid, {pwrite,true,Handle,Offset,Data}, infinity).
%% TODO this ought to be a cast! Is so in all practical meaning
%% even if it is obscure!
+-spec awrite(ChannelPid, Handle, Data) -> {async, N} | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Data :: binary(),
+ Error :: {error, reason()},
+ N :: term() .
awrite(Pid, Handle, Data) ->
call(Pid, {write,true,Handle,Data}, infinity).
+-spec position(ChannelPid, Handle, Location) -> {ok, NewPosition} | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Location :: Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof,
+ Offset :: integer(),
+ NewPosition :: integer(),
+ Error :: {error, reason()}.
position(Pid, Handle, Pos) ->
position(Pid, Handle, Pos, ?FILEOP_TIMEOUT).
+
+-spec position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition} | Error when
+ ChannelPid :: pid(),
+ Handle :: term(),
+ Location :: Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof,
+ Timeout :: timeout(),
+ Offset :: integer(),
+ NewPosition :: integer(),
+ Error :: {error, reason()}.
position(Pid, Handle, Pos, FileOpTimeout) ->
call(Pid, {position, Handle, Pos}, FileOpTimeout).
@@ -328,8 +513,21 @@ real_path(Pid, Path) ->
real_path(Pid, Path, FileOpTimeout) ->
call(Pid, {real_path, false, Path}, FileOpTimeout).
+
+-spec read_file_info(ChannelPid, Name) -> {ok, FileInfo} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ FileInfo :: file:file_info(),
+ Error :: {error, reason()}.
read_file_info(Pid, Name) ->
read_file_info(Pid, Name, ?FILEOP_TIMEOUT).
+
+-spec read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Timeout :: timeout(),
+ FileInfo :: file:file_info(),
+ Error :: {error, reason()}.
read_file_info(Pid, Name, FileOpTimeout) ->
call(Pid, {read_file_info,false,Name}, FileOpTimeout).
@@ -338,18 +536,57 @@ get_file_info(Pid, Handle) ->
get_file_info(Pid, Handle, FileOpTimeout) ->
call(Pid, {get_file_info,false,Handle}, FileOpTimeout).
+
+-spec write_file_info(ChannelPid, Name, FileInfo) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ FileInfo :: file:file_info(),
+ Error :: {error, reason()}.
write_file_info(Pid, Name, Info) ->
write_file_info(Pid, Name, Info, ?FILEOP_TIMEOUT).
+
+-spec write_file_info(ChannelPid, Name, FileInfo, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ FileInfo :: file:file_info(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
write_file_info(Pid, Name, Info, FileOpTimeout) ->
call(Pid, {write_file_info,false,Name, Info}, FileOpTimeout).
+
+-spec read_link_info(ChannelPid, Name) -> {ok, FileInfo} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ FileInfo :: file:file_info(),
+ Error :: {error, reason()}.
read_link_info(Pid, Name) ->
read_link_info(Pid, Name, ?FILEOP_TIMEOUT).
+
+-spec read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ FileInfo :: file:file_info(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
read_link_info(Pid, Name, FileOpTimeout) ->
call(Pid, {read_link_info,false,Name}, FileOpTimeout).
+
+-spec read_link(ChannelPid, Name) -> {ok, Target} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Target :: string(),
+ Error :: {error, reason()}.
read_link(Pid, LinkName) ->
read_link(Pid, LinkName, ?FILEOP_TIMEOUT).
+
+-spec read_link(ChannelPid, Name, Timeout) -> {ok, Target} | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Target :: string(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
read_link(Pid, LinkName, FileOpTimeout) ->
case call(Pid, {read_link,false,LinkName}, FileOpTimeout) of
{ok, [{Name, _Attrs}]} ->
@@ -358,28 +595,79 @@ read_link(Pid, LinkName, FileOpTimeout) ->
ErrMsg
end.
+-spec make_symlink(ChannelPid, Name, Target) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Target :: string(),
+ Error :: {error, reason()} .
make_symlink(Pid, Name, Target) ->
make_symlink(Pid, Name, Target, ?FILEOP_TIMEOUT).
+-spec make_symlink(ChannelPid, Name, Target, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Target :: string(),
+ Timeout :: timeout(),
+ Error :: {error, reason()} .
make_symlink(Pid, Name, Target, FileOpTimeout) ->
call(Pid, {make_symlink,false, Name, Target}, FileOpTimeout).
+
+-spec rename(ChannelPid, OldName, NewName) -> ok | Error when
+ ChannelPid :: pid(),
+ OldName :: string(),
+ NewName :: string(),
+ Error :: {error, reason()}.
rename(Pid, FromFile, ToFile) ->
rename(Pid, FromFile, ToFile, ?FILEOP_TIMEOUT).
+
+-spec rename(ChannelPid, OldName, NewName, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ OldName :: string(),
+ NewName :: string(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
rename(Pid, FromFile, ToFile, FileOpTimeout) ->
call(Pid, {rename,false,FromFile, ToFile}, FileOpTimeout).
+-spec delete(ChannelPid, Name) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Error :: {error, reason()} .
delete(Pid, Name) ->
delete(Pid, Name, ?FILEOP_TIMEOUT).
+-spec delete(ChannelPid, Name, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Timeout :: timeout(),
+ Error :: {error, reason()} .
delete(Pid, Name, FileOpTimeout) ->
call(Pid, {delete,false,Name}, FileOpTimeout).
+-spec make_dir(ChannelPid, Name) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Error :: {error, reason()} .
make_dir(Pid, Name) ->
make_dir(Pid, Name, ?FILEOP_TIMEOUT).
+-spec make_dir(ChannelPid, Name, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Timeout :: timeout(),
+ Error :: {error, reason()} .
make_dir(Pid, Name, FileOpTimeout) ->
call(Pid, {make_dir,false,Name}, FileOpTimeout).
+-spec del_dir(ChannelPid, Name) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Error :: {error, reason()} .
del_dir(Pid, Name) ->
del_dir(Pid, Name, ?FILEOP_TIMEOUT).
+-spec del_dir(ChannelPid, Name, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ Name :: string(),
+ Timeout :: timeout(),
+ Error :: {error, reason()} .
del_dir(Pid, Name, FileOpTimeout) ->
call(Pid, {del_dir,false,Name}, FileOpTimeout).
@@ -396,9 +684,21 @@ recv_window(Pid, FileOpTimeout) ->
call(Pid, recv_window, FileOpTimeout).
+-spec list_dir(ChannelPid, Path) -> {ok,FileNames} | Error when
+ ChannelPid :: pid(),
+ Path :: string(),
+ FileNames :: [FileName],
+ FileName :: string(),
+ Error :: {error, reason()} .
list_dir(Pid, Name) ->
list_dir(Pid, Name, ?FILEOP_TIMEOUT).
-
+-spec list_dir(ChannelPid, Path, Timeout) -> {ok,FileNames} | Error when
+ ChannelPid :: pid(),
+ Path :: string(),
+ Timeout :: timeout(),
+ FileNames :: [FileName],
+ FileName :: string(),
+ Error :: {error, reason()} .
list_dir(Pid, Name, FileOpTimeout) ->
case opendir(Pid, Name, FileOpTimeout) of
{ok,Handle} ->
@@ -429,9 +729,20 @@ do_list_dir(Pid, Handle, FileOpTimeout, Acc) ->
end.
+-spec read_file(ChannelPid, File) -> {ok, Data} | Error when
+ ChannelPid :: pid(),
+ File :: string(),
+ Data :: binary(),
+ Error :: {error, reason()}.
read_file(Pid, Name) ->
read_file(Pid, Name, ?FILEOP_TIMEOUT).
+-spec read_file(ChannelPid, File, Timeout) -> {ok, Data} | Error when
+ ChannelPid :: pid(),
+ File :: string(),
+ Data :: binary(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
read_file(Pid, Name, FileOpTimeout) ->
case open(Pid, Name, [read, binary], FileOpTimeout) of
{ok, Handle} ->
@@ -453,9 +764,20 @@ read_file_loop(Pid, Handle, PacketSz, FileOpTimeout, Acc) ->
Error
end.
+-spec write_file(ChannelPid, File, Data) -> ok | Error when
+ ChannelPid :: pid(),
+ File :: string(),
+ Data :: iodata(),
+ Error :: {error, reason()}.
write_file(Pid, Name, List) ->
write_file(Pid, Name, List, ?FILEOP_TIMEOUT).
+-spec write_file(ChannelPid, File, Data, Timeout) -> ok | Error when
+ ChannelPid :: pid(),
+ File :: string(),
+ Data :: iodata(),
+ Timeout :: timeout(),
+ Error :: {error, reason()}.
write_file(Pid, Name, List, FileOpTimeout) when is_list(List) ->
write_file(Pid, Name, list_to_binary(List), FileOpTimeout);
write_file(Pid, Name, Bin, FileOpTimeout) ->