查看源代码 ssh_sftp (ssh v5.2.5)
SFTP 客户端。
此模块实现 SSH FTP (SFTP) 客户端。SFTP 是一种安全的加密文件传输服务，可用于 SSH。
概要
类型：Crypto open_tar
从 init_fun/0 返回的初始 crypto_state/0 被折叠到 tar_crypto_spec 中 crypto_fun/0 的重复应用中。从该函数返回的二进制数据会发送到远程 SFTP 服务器，新的 crypto_state/0 会用于下一次调用 crypto_fun/0。
tar_crypto_spec 中的 init_fun/0 在任何其他 crypto 操作之前应用一次。目的是此函数初始化加密或解密，例如通过调用 crypto:crypto_init/4 或类似函数。crypto_state/0 是此类函数可能返回的状态。
指定使用 open_tar/3 或 open_tar/4 时应用于 tar 文件的加密或解密。
如果进行加密，则 tar_crypto_spec 中的 final_fun/0 将应用于最后一块数据。final_fun/0 负责填充（如果需要）和最后一块数据的加密。
函数
apread/4 函数从指定位置读取，组合了 position/3 和 aread/3 函数。
apwrite/4 函数写入到指定位置，组合了 position/3 和 awrite/3 函数。
从打开的文件读取，无需等待结果。如果句柄有效，则该函数返回 {async, N}，其中 N 是一个项，保证在 aread 的调用之间是唯一的。实际数据作为消息发送到调用进程。此消息的格式为 {async_reply, N, Result}，其中 Result 是读取的结果，可以是 {ok, Data}、eof 或 {error, reason()}。
写入到打开的文件，无需等待结果。如果句柄有效，则该函数返回 {async, N}，其中 N 是一个项，保证在 awrite 的调用之间是唯一的。write 操作的结果作为消息发送到调用进程。此消息的格式为 {async_reply, N, Result}，其中 Result 是写入的结果，可以是 ok 或 {error, reason()}。
关闭服务器上打开的文件或目录的句柄。
删除由 Name 指定的目录。该目录必须为空才能成功删除。
删除由 Name 指定的文件。
列出服务器上的给定目录，将文件名作为字符串列表返回。
创建由 Name 指定的目录。Name 必须是新目录的完整路径。该目录只能在现有目录中创建。
创建一个指向 Target 的符号链接，名称为 Name。
打开服务器上的文件并返回一个句柄，该句柄可用于读取或写入。
打开与 ChannelPid 关联的服务器上 tar 文件的句柄。该句柄可用于远程 tar 创建和提取。实际的写入和读取通过调用 erl_tar:add/3,4 和 erl_tar:extract/2 来执行。注意：不应调用 erl_tar:init/3 函数，此 open_tar 函数会调用它。
打开服务器上目录的句柄。该句柄可用于读取目录内容。
设置由 Handle 引用的文件的文件位置。如果成功，则返回 {ok, NewPosition}（作为绝对偏移量），否则返回 {error, reason()}。Location 是以下之一
pread/3,4 函数从指定位置读取，组合了 position/3 和 read/3,4 函数。
pwrite/3,4 函数写入到指定位置，组合了 position/3 和 write/3,4 函数。
从 Handle 引用的文件中读取 Len 个字节。返回 {ok, Data}、eof 或 {error, reason()}。如果使用 binary 打开文件，则 Data 为二进制数据，否则为字符串。
从服务器读取文件，并将数据以二进制形式返回。
从由 Name 或 Handle 指定的文件系统对象返回 file_info 记录。有关该记录的信息，请参阅 file:read_file_info/2。
从由 name 指定的符号链接读取链接目标。
从由 Name 或 Handle 指定的符号链接返回 file_info 记录。有关该记录的信息，请参阅 file:read_link_info/2。
重命名名为 OldName 的文件，并将其命名为 NewName。
start_channel(Host, Port, Options) ->
停止 SFTP 通道。不关闭 SSH 连接。使用 ssh:close/1 关闭它。
将 data 写入由 Handle 引用的文件。该文件要使用 write 或 append 标志打开。如果成功，则返回 ok，否则返回 {error, reason()}。
将文件写入服务器。如果文件不存在则创建，如果存在则覆盖。
将 file_info 记录中的文件信息写入由 Name 指定的文件。有关该记录的信息，请参阅 file:write_file_info/2,3。
类型：Crypto open_tar
-type chunk_size() :: undefined | pos_integer().
-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()}.
从 init_fun/0 返回的初始 crypto_state/0 被折叠到 tar_crypto_spec 中 crypto_fun/0 的重复应用中。从该函数返回的二进制数据会发送到远程 SFTP 服务器，新的 crypto_state/0 会用于下一次调用 crypto_fun/0。
如果 crypto_fun/0 返回 chunk_size/0，则该值是在调用 crypto_fun/0 时进一步块的块大小。
-type crypto_state() :: any().
tar_crypto_spec 中的 init_fun/0 在任何其他 crypto 操作之前应用一次。目的是此函数初始化加密或解密，例如通过调用 crypto:crypto_init/4 或类似函数。crypto_state/0 是此类函数可能返回的状态。
如果选择的密码需要将输入数据分成特定大小的块，则 init_fun/0 应返回第二种形式的返回值，其中 chunk_size/0 设置为块大小。如果 chunk_size/0 为 undefined，则 PlainBin 的大小会变化，因为这是为流密码设计的，而固定的 chunk_size/0 是为块密码设计的。 chunk_size/0 的值可以在 crypto_fun/0 的返回值中更改。该值可以在 pos_integer/0 和 undefined 之间更改。
-type decrypt_spec() :: {init_fun(), crypto_fun()}.
指定使用 open_tar/3 或 open_tar/4 时应用于 tar 文件的加密或解密。
加密或解密应用于生成的字节流，然后再将生成的流发送到 SFTP 服务器。
有关代码示例，请参阅 ssh 用户指南中的 加密示例 部分。
-type encrypt_spec() :: {init_fun(), crypto_fun(), final_fun()}.
-type final_fun() :: fun((FinalTextIn :: binary(), crypto_state()) -> {ok, FinalTextOut :: binary()}).
如果进行加密，则 tar_crypto_spec 中的 final_fun/0 将应用于最后一块数据。final_fun/0 负责填充（如果需要）和最后一块数据的加密。
-type init_fun() :: fun(() -> {ok, crypto_state()}) | fun(() -> {ok, crypto_state(), chunk_size()}).
-type tar_crypto_spec() :: encrypt_spec() | decrypt_spec().
类型
描述操作失败的原因。
atom/0 值是由协议级别响应中的 sftp 错误代码形成的，如 draft-ietf-secsh-filexfer-13 第 9.1 节中定义的那样。这些代码被命名为 SSH_FX_*，它们被转换为星号部分的小写形式。例如，错误代码 SSH_FX_NO_SUCH_FILE 将导致 reason/0 为 no_such_file。
string/0 原因是在出现退出信号时，来自服务器的错误信息。如果该信息为空，则原因是退出信号的名称。
tuple/0 原因是其他错误，例如 {exit_status,1}。
-type sftp_option() :: {timeout, timeout()} | {sftp_vsn, pos_integer()} | {window_size, pos_integer()} | {packet_size, pos_integer()}.
函数
-spec apread(ChannelPid, Handle, Position, Len) -> {async, N} | Error when ChannelPid :: pid(), Handle :: term(), Position :: integer(), Len :: integer(), Error :: {error, reason()}, N :: term().
apread/4 函数从指定位置读取，组合了 position/3 和 aread/3 函数。
-spec apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | Error when ChannelPid :: pid(), Handle :: term(), Position :: integer(), Data :: binary(), Error :: {error, reason()}, N :: term().
apwrite/4 函数写入到指定位置，组合了 position/3 和 awrite/3 函数。
-spec aread(ChannelPid, Handle, Len) -> {async, N} | Error when ChannelPid :: pid(), Handle :: term(), Len :: integer(), Error :: {error, reason()}, N :: term().
从打开的文件读取，无需等待结果。如果句柄有效，则该函数返回 {async, N}，其中 N 是一个项，保证在 aread 的调用之间是唯一的。实际数据作为消息发送到调用进程。此消息的格式为 {async_reply, N, Result}，其中 Result 是读取的结果，可以是 {ok, Data}、eof 或 {error, reason()}。
-spec awrite(ChannelPid, Handle, Data) -> {async, N} | Error when ChannelPid :: pid(), Handle :: term(), Data :: binary(), Error :: {error, reason()}, N :: term().
写入到打开的文件，无需等待结果。如果句柄有效，则该函数返回 {async, N}，其中 N 是一个项，保证在 awrite 的调用之间是唯一的。write 操作的结果作为消息发送到调用进程。此消息的格式为 {async_reply, N, Result}，其中 Result 是写入的结果，可以是 ok 或 {error, reason()}。
-spec close(ChannelPid, Handle) -> ok | Error when ChannelPid :: pid(), Handle :: term(), Error :: {error, reason()}.
等同于 close/3。
-spec close(ChannelPid, Handle, Timeout) -> ok | Error when ChannelPid :: pid(), Handle :: term(), Timeout :: timeout(), Error :: {error, reason()}.
关闭服务器上打开的文件或目录的句柄。
-spec del_dir(ChannelPid, Name) -> ok | Error when ChannelPid :: pid(), Name :: string(), Error :: {error, reason()}.
等同于 del_dir/3。
-spec del_dir(ChannelPid, Name, Timeout) -> ok | Error when ChannelPid :: pid(), Name :: string(), Timeout :: timeout(), Error :: {error, reason()}.
删除由 Name 指定的目录。该目录必须为空才能成功删除。
-spec delete(ChannelPid, Name) -> ok | Error when ChannelPid :: pid(), Name :: string(), Error :: {error, reason()}.
等同于 delete/3。
-spec delete(ChannelPid, Name, Timeout) -> ok | Error when ChannelPid :: pid(), Name :: string(), Timeout :: timeout(), Error :: {error, reason()}.
删除由 Name 指定的文件。
-spec list_dir(ChannelPid, Path) -> {ok, FileNames} | Error when ChannelPid :: pid(), Path :: string(), FileNames :: [FileName], FileName :: string(), Error :: {error, reason()}.
等同于 list_dir/3。
-spec list_dir(ChannelPid, Path, Timeout) -> {ok, FileNames} | Error when ChannelPid :: pid(), Path :: string(), Timeout :: timeout(), FileNames :: [FileName], FileName :: string(), Error :: {error, reason()}.
列出服务器上的给定目录，将文件名作为字符串列表返回。
-spec make_dir(ChannelPid, Name) -> ok | Error when ChannelPid :: pid(), Name :: string(), Error :: {error, reason()}.
等同于 make_dir/3。
-spec make_dir(ChannelPid, Name, Timeout) -> ok | Error when ChannelPid :: pid(), Name :: string(), Timeout :: timeout(), Error :: {error, reason()}.
创建由 Name 指定的目录。Name 必须是新目录的完整路径。该目录只能在现有目录中创建。
-spec make_symlink(ChannelPid, Name, Target) -> ok | Error when ChannelPid :: pid(), Name :: string(), Target :: string(), Error :: {error, reason()}.
等同于 make_symlink/4。
-spec make_symlink(ChannelPid, Name, Target, Timeout) -> ok | Error when ChannelPid :: pid(), Name :: string(), Target :: string(), Timeout :: timeout(), Error :: {error, reason()}.
创建一个指向 Target 的符号链接，名称为 Name。
-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/4。
-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()}.
打开服务器上的文件并返回一个句柄，该句柄可用于读取或写入。
-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/4。
-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()}.
打开与 ChannelPid 关联的服务器上 tar 文件的句柄。该句柄可用于远程 tar 创建和提取。实际的写入和读取通过调用 erl_tar:add/3,4 和 erl_tar:extract/2 来执行。注意：不应调用 erl_tar:init/3 函数，此 open_tar 函数会调用它。
有关代码示例，请参阅 ssh 用户指南中的 使用 TAR 压缩的 SFTP 客户端 部分。
crypto 模式选项在上面的数据类型部分中进行了解释，请参阅 open_tar 的加密操作。如果 Mode 包含 write，则假定为加密；如果 Mode 包含 read，则假定为解密。
-spec opendir(ChannelPid, Path) -> {ok, Handle} | Error when ChannelPid :: pid(), Path :: string(), Handle :: term(), Error :: {error, reason()}.
等同于 opendir/3。
-spec opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | Error when ChannelPid :: pid(), Path :: string(), Timeout :: timeout(), Handle :: term(), Error :: {error, reason()}.
打开服务器上目录的句柄。该句柄可用于读取目录内容。
-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/4。
-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()}.
设置由 Handle 引用的文件的文件位置。如果成功，则返回 {ok, NewPosition}（作为绝对偏移量），否则返回 {error, reason()}。Location 是以下之一
Offset- 与{bof, Offset}相同。{bof, Offset}- 绝对偏移量。{cur, Offset}- 从当前位置的偏移量。{eof, Offset}- 从文件末尾的偏移量。bof | cur | eof- 与之前的相同，偏移量为 0，即{bof, 0} | {cur, 0} | {eof, 0}。
-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/5。
-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/3,4 函数从指定位置读取，组合了 position/3 和 read/3,4 函数。
-spec pwrite(ChannelPid, Handle, Position, Data) -> ok | Error when ChannelPid :: pid(), Handle :: term(), Position :: integer(), Data :: iolist(), Error :: {error, reason()}.
等同于 pwrite/5。
-spec pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | Error when ChannelPid :: pid(), Handle :: term(), Position :: integer(), Data :: iolist(), Timeout :: timeout(), Error :: {error, reason()}.
pwrite/3,4 函数写入到指定位置，组合了 position/3 和 write/3,4 函数。
-spec read(ChannelPid, Handle, Len) -> {ok, Data} | eof | Error when ChannelPid :: pid(), Handle :: term(), Len :: integer(), Data :: string() | binary(), Error :: {error, reason()}.
等同于 read/4。
-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()}.
从 Handle 引用的文件中读取 Len 个字节。返回 {ok, Data}、eof 或 {error, reason()}。如果使用 binary 打开文件，则 Data 为二进制数据，否则为字符串。
如果读取文件超过 eof，则仅读取并返回剩余的字节。如果没有读取任何字节，则返回 eof。
-spec read_file(ChannelPid, File) -> {ok, Data} | Error when ChannelPid :: pid(), File :: string(), Data :: binary(), Error :: {error, reason()}.
等同于 read_file/3。
-spec read_file(ChannelPid, File, Timeout) -> {ok, Data} | Error when ChannelPid :: pid(), File :: string(), Data :: binary(), Timeout :: timeout(), Error :: {error, reason()}.
从服务器读取文件，并将数据以二进制形式返回。
-spec read_file_info(ChannelPid, Name) -> {ok, FileInfo} | Error when ChannelPid :: pid(), Name :: string(), FileInfo :: file:file_info(), Error :: {error, reason()}.
等同于 read_file_info/3。
-spec read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | Error when ChannelPid :: pid(), Name :: string(), Timeout :: timeout(), FileInfo :: file:file_info(), Error :: {error, reason()}.
从由 Name 或 Handle 指定的文件系统对象返回 file_info 记录。有关该记录的信息，请参阅 file:read_file_info/2。
根据底层操作系统，可能会跟踪链接并返回有关最终文件、目录等的信息。有关如何获取有关链接的信息，请参阅 read_link_info/2。
-spec read_link(ChannelPid, Name) -> {ok, Target} | Error when ChannelPid :: pid(), Name :: string(), Target :: string(), Error :: {error, reason()}.
等同于 read_link/3。
-spec read_link(ChannelPid, Name, Timeout) -> {ok, Target} | Error when ChannelPid :: pid(), Name :: string(), Target :: string(), Timeout :: timeout(), Error :: {error, reason()}.
从由 name 指定的符号链接读取链接目标。
-spec read_link_info(ChannelPid, Name) -> {ok, FileInfo} | Error when ChannelPid :: pid(), Name :: string(), FileInfo :: file:file_info(), Error :: {error, reason()}.
等同于 read_link_info/3。
-spec read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | Error when ChannelPid :: pid(), Name :: string(), FileInfo :: file:file_info(), Timeout :: timeout(), Error :: {error, reason()}.
从由 Name 或 Handle 指定的符号链接返回 file_info 记录。有关该记录的信息，请参阅 file:read_link_info/2。
-spec rename(ChannelPid, OldName, NewName) -> ok | Error when ChannelPid :: pid(), OldName :: string(), NewName :: string(), Error :: {error, reason()}.
等同于 rename/4。
-spec rename(ChannelPid, OldName, NewName, Timeout) -> ok | Error when ChannelPid :: pid(), OldName :: string(), NewName :: string(), Timeout :: timeout(), Error :: {error, reason()}.
重命名名为 OldName 的文件，并将其命名为 NewName。
-spec start_channel(ssh:open_socket() | ssh:connection_ref() | ssh:host()) -> {ok, pid()} | {ok, pid(), ssh:connection_ref()} | {error, reason()}.
等同于 start_channel/3。
-spec start_channel(ssh:open_socket(), [ssh:client_option() | sftp_option()]) -> {ok, pid(), ssh:connection_ref()} | {error, reason()}; (ssh:connection_ref(), [sftp_option()]) -> {ok, pid()} | {ok, pid(), ssh:connection_ref()} | {error, reason()}; (ssh:host(), [ssh:client_option() | sftp_option()]) -> {ok, pid(), ssh:connection_ref()} | {error, reason()}.
等同于 start_channel/3。
-spec start_channel(ssh:host(), inet:port_number(), [ssh:client_option() | sftp_option()]) -> {ok, pid(), ssh:connection_ref()} | {error, reason()}.
start_channel(Host, Port, Options) ->
如果没有提供连接引用，则会建立一个连接，并返回新连接。启动 SSH 通道进程以处理与 SFTP 服务器的通信。此进程的返回 pid 将用作此模块中所有其他 API 函数的输入。
选项
{timeout, timeout()}- 有两种方法可以为底层 ssh 连接设置超时- 如果设置了连接超时选项
connect_timeout，则该值也用于协商超时，并且此选项 (timeout) 将被忽略。 - 否则，此选项 (
timeout) 仅用作协商超时，并且不设置连接超时
该值默认为
infinity。- 如果设置了连接超时选项
{sftp_vsn, integer()}- 所需的 SFTP 协议版本。实际版本是所需版本和 SFTP 服务器支持的最大版本的最小值。
所有其他选项都直接传递给 ssh:connect/3，如果已提供连接，则会被忽略。
-spec stop_channel(ChannelPid) -> ok when ChannelPid :: pid().
停止 SFTP 通道。不关闭 SSH 连接。使用 ssh:close/1 关闭它。
-spec write(ChannelPid, Handle, Data) -> ok | Error when ChannelPid :: pid(), Handle :: term(), Data :: iodata(), Error :: {error, reason()}.
等同于 write/4。
-spec write(ChannelPid, Handle, Data, Timeout) -> ok | Error when ChannelPid :: pid(), Handle :: term(), Data :: iodata(), Timeout :: timeout(), Error :: {error, reason()}.
将 data 写入由 Handle 引用的文件。该文件要使用 write 或 append 标志打开。如果成功，则返回 ok，否则返回 {error, reason()}。
-spec write_file(ChannelPid, File, Data) -> ok | Error when ChannelPid :: pid(), File :: string(), Data :: iodata(), Error :: {error, reason()}.
等同于 write_file/4。
-spec write_file(ChannelPid, File, Data, Timeout) -> ok | Error when ChannelPid :: pid(), File :: string(), Data :: iodata(), Timeout :: timeout(), Error :: {error, reason()}.
将文件写入服务器。如果文件不存在则创建，如果存在则覆盖。
-spec write_file_info(ChannelPid, Name, FileInfo) -> ok | Error when ChannelPid :: pid(), Name :: string(), FileInfo :: file:file_info(), Error :: {error, reason()}.
等同于 write_file_info/4。
-spec write_file_info(ChannelPid, Name, FileInfo, Timeout) -> ok | Error when ChannelPid :: pid(), Name :: string(), FileInfo :: file:file_info(), Timeout :: timeout(), Error :: {error, reason()}.
将 file_info 记录中的文件信息写入由 Name 指定的文件。有关该记录的信息，请参阅 file:write_file_info/2,3。