檢視原始碼 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。
開啟伺服器上的檔案，並返回一個可用於讀取或寫入的句柄。
開啟伺服器上 tar 檔案的句柄，並與 ChannelPid 關聯。該句柄可用於遠端 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()}.
開啟伺服器上 tar 檔案的句柄，並與 ChannelPid 關聯。該句柄可用於遠端 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- 與前面相同，但Offset為 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 以取得有關記錄的資訊。