Net::FTP

(來源, CPAN)

版本 3.15

內容

名稱
語法
說明
匯出
已知錯誤
- 回報錯誤
另請參閱
致謝
作者
版權
授權
版本
日期
歷史

#名稱

Net::FTP - FTP 客户端類別

#語法

use Net::FTP;

$ftp = Net::FTP->new("some.host.name", Debug => 0)
  or die "Cannot connect to some.host.name: $@";

$ftp->login("anonymous",'-anonymous@')
  or die "Cannot login ", $ftp->message;

$ftp->cwd("/pub")
  or die "Cannot change working directory ", $ftp->message;

$ftp->get("that.file")
  or die "get failed ", $ftp->message;

$ftp->quit;

#說明

Net::FTP 是一個類別，在 Perl 中實作一個簡單的 FTP 客户端，如 RFC959 所述。它提供 RFC959 指令中常用子集的包裝函式。如果已安裝 IO::Socket::IP 或 IO::Socket::INET6，它也會提供 RFC2428 中定義的 IPv6 支援。而安裝 IO::Socket::SSL 後，它會提供 RFC4217 中定義的隱式 FTPS 和明確 FTPS 支援。

Net::FTP 類別是 Net::Cmd 的子類別，以及（視可用性而定）IO::Socket::IP、IO::Socket::INET6 或 IO::Socket::INET 的子類別。

#概述

FTP 的意思是檔案傳輸通訊協定。它是一種在網路機器之間傳輸檔案的方式。此通訊協定定義了客戶端（其指令由這個模組提供）和伺服器（未在此模組中實作）。通訊總是是由客戶端發起的，而伺服器會以訊息和狀態碼（有時還會加上資料）回應。

FTP 通訊協定允許檔案傳送至伺服器或從伺服器擷取。每次傳輸都涉及一個本機檔案（在客戶端）和一個遠端檔案（在伺服器）。在此模組中，如果只指定一個檔案，則本機和遠端檔案將使用同一個檔案名稱。這表示傳輸遠端檔案 /path/to/file 會嘗試將該檔案放在本機的 /path/to/file，除非您指定了本機檔案名稱。

此通訊協定也定義了檔案在傳輸期間可以進行的數個標準轉譯。這些轉譯包括 ASCII、EBCDIC、二進位和位元組。ASCII 是預設類型，表示檔案傳送者會將行尾轉譯成標準表示法，然後接收者會再將其轉譯回其本機表示法。EBCDIC 表示傳輸的檔案是 EBCDIC 格式。二進位（也稱為影像）格式會將資料傳送為連續的位元串流。位元組格式會將資料傳送為位元組，其值不論兩台機器之間的位元組大小差異為何，都會保持不變（理論上如此，實際上您只有在真的知道自己在做什麼時才應該使用這個格式）。這個類別不支援 EBCDIC 或位元組格式，如果嘗試使用這些格式，預設會改用二進位格式。

#類別方法

#new([$host][, %options])

這是新的 Net::FTP 物件的建構函式。$host 是需要與其建立 FTP 連線的遠端主機名稱。

$host 是選用的。如果未提供 $host，則可以改為將其傳遞為下方所述的 Host 選項。

%options 以雜湊方式傳遞，使用鍵值對。可能的選項有

Host - 要連線的 FTP 主機。它可以是單一純量，如 IO::Socket::INET 中的 PeerAddr 選項所定義，或參考嘗試連線的主機陣列。 "host" 方法會傳回用於連線至主機的值。

防火牆 - 作為 FTP 防火牆的機器名稱。這可以被環境變數 FTP_FIREWALL 覆寫。如果指定，且無法直接連接到給定的主機，則連線會建立到防火牆機器，且字串 @hostname 會附加到登入識別碼。這種設定也稱為 ftp 代理。

FirewallType - Firewall 指出的機器上執行的防火牆類型。這可以被環境變數 FTP_FIREWALL_TYPE 覆寫。有關允許類型清單，請參閱 Net::Config 中 ftp_firewall_type 的說明。

BlockSize - 這是 Net::FTP 在執行傳輸時將使用的區塊大小。（預設為 10240）

Port - 要在遠端機器上連線的 FTP 連線埠號

SSL - 如果連線應從開始就透過 SSL 進行，與稍後使用 starttls 升級相反。

SSL_* - 在將控制或資料連線升級到 SSL 時套用的 SSL 引數。您可以使用 IO::Socket::SSL 中記載的 SSL 引數，但通常會使用正確的引數。

Timeout - 設定逾時值（秒）（預設為 120）

Debug - 除錯等級（請參閱 Net::Cmd 中的除錯方法）

被動 - 如果設定為非零值，則所有資料傳輸都將使用被動模式進行。如果設定為零，則資料傳輸將使用主動模式進行。如果機器直接連線到網際網路，則被動模式和主動模式都應該可以正常運作。在大部分防火牆和 NAT 組態中，被動模式有較高的機率可以正常運作。不過，在某些罕見的防火牆組態中，當被動模式無法運作時，主動模式反而可以正常運作。有些非常舊的 FTP 伺服器可能未實作被動傳輸。如果未指定，則傳輸模式會由環境變數 FTP_PASSIVE 設定，或如果未設定，則由 libnetcfg 工具執行的設定設定。如果以上皆不適用，則會使用被動模式。

雜湊 - 如果給定檔案控制代號的參考 (例如：\*STDERR)，則每 1024 位元組在該檔案控制代號上列印雜湊標記 (#)。這只是為您呼叫 hash() 方法，以便為所有傳輸顯示雜湊標記。當然，您可以在任何時候明確呼叫 hash()。

LocalAddr - 用於所有 Socket 連線的本機位址。這個引數會傳遞給超類別，例如：IO::Socket::INET 或 IO::Socket::IP。

Domain - 要使用的網域，例如：AF_INET 或 AF_INET6。這個引數會傳遞給 IO::Socket 超類別。這可以用來強制使用 IPv4，即使是 IO::Socket::IP，其預設值也會是 IPv6。Family 可作為 Domain 的替代名稱。

如果建構函式失敗，則會傳回未定義，且錯誤訊息會在 $@ 中。

#物件方法

除非另有說明，否則所有方法都傳回 true 或 false 值，其中 true 表示操作成功。當方法指出它傳回值時，失敗會傳回 undef 或空清單。

Net::FTP 繼承自 Net::Cmd，因此除了此處記載的方法外，也可以使用 Net::Cmd 中定義的方法來傳送指令至遠端 FTP 伺服器。

#login([$login[, $password[, $account]]])

使用指定的登入資訊登入遠端 FTP 伺服器。如果未提供任何引數，則 Net::FTP 會使用 Net::Netrc 套件來查詢已連線主機的登入資訊。如果找不到任何資訊，則會使用 anonymous 登入。如果未提供密碼且登入為 anonymous，則會將 anonymous@ 用於密碼。

如果連線是透過防火牆，則會呼叫 authorize 方法，且不帶任何引數。

#starttls()

將現有的純文字連線升級至 SSL。SSL 參數必須在 new 中提供，因為資料連線也需要這些參數。

#stoptls()

將現有的 SSL 連線降級回純文字。這對於防火牆中的一些 FTP 輔助程式來說是必要的，這些輔助程式需要看到 PORT 和 PASV 命令及回應，才能動態開啟必要的連接埠。在這種情況下，starttls 通常只用於保護授權。

#prot($level)

設定用戶端和伺服器將使用的資料通道保護類型。僅支援 $level「C」（清除）和「P」（私人）。

#host()

傳回建構函式使用的值，並傳遞給 IO::Socket 超級類別以連線至主機。

#account($acct)

設定識別使用者帳戶的字串。

#authorize([$auth[, $resp]])

這是一個由某些防火牆 ftp 代理程式使用的協定。它用於授權使用者傳送資料。如果未指定兩個參數，則 authorize 會使用 Net::Netrc 進行查詢。

#site($args)

傳送 SITE 命令至遠端伺服器，並等待回應。

傳回回應代碼的最顯著位元。

#ascii()

以 ASCII 傳輸檔案。如果需要，將進行 CRLF 轉換

#binary()

以二進位模式傳輸檔案。不會進行任何轉換。

提示：如果伺服器和用戶端機器對文字檔案使用相同的行尾，則以二進位模式傳輸所有檔案會比較快。

#type([$type])

設定或取得檔案將以 ASCII 或二進位模式傳輸。

#rename($oldname, $newname)

將遠端 FTP 伺服器上的檔案從 $oldname 重新命名為 $newname。這會透過傳送 RNFR 和 RNTO 指令來執行。

#delete($filename)

傳送請求至伺服器，以刪除 $filename。

#cwd([$dir])

嘗試將目錄變更為 $dir 中指定的目錄。如果 $dir 為 ".."，則會使用 FTP CDUP 指令嘗試向上移動一個目錄。如果未指定目錄，則會嘗試將目錄變更為根目錄。

#cdup()

#passive([$passive])

設定或取得是否會以被動模式啟動資料連線。

#pwd()

傳回目前目錄的完整路徑名稱。

#restart($where)

設定開始下一次資料傳輸的位元組偏移量。Net::FTP 僅記錄此值，並在下一次資料傳輸時使用它。因此，此方法不會傳回錯誤，但設定它可能會導致後續資料傳輸失敗。

#rmdir($dir[, $recurse])

移除名稱為 $dir 的目錄。如果 $recurse 為 true，則 rmdir 會嘗試刪除目錄中的所有內容。

#mkdir($dir[, $recurse])

建立一個名稱為 $dir 的新目錄。如果 $recurse 為 true，則 mkdir 會嘗試建立指定路徑中的所有目錄。

傳回新目錄的完整路徑名稱。

#alloc($size[, $record_size])

alloc 指令讓您可以使用 ALLO ftp 指令，向 ftp 伺服器提供有關即將傳輸檔案大小的提示。有些儲存系統會使用此資訊來做出明智的決定，以決定如何儲存檔案。$size 參數表示檔案大小（以位元組為單位）。$record_size 參數表示使用記錄或頁面結構傳送的檔案的最大記錄或頁面大小。

對於一般檔案，檔案大小會自動判斷並傳送至伺服器，因此只有在您從套接字、命名管線或其他未與一般檔案關聯的串流傳輸資料時，才需要呼叫此方法。

#ls([$dir])

在陣列內容中，傳回伺服器傳回的行清單。在純量內容中，傳回清單參考。

#dir([$dir])

取得目錄清單 $dir，或目前目錄，使用長格式。

在陣列內容中，傳回伺服器傳回的行清單。在純量內容中，傳回清單參考。

#get($remote_file[, $local_file[, $where]])

從伺服器取得 $remote_file 並儲存在本機。$local_file 可以是檔案名稱或檔案控制代碼。如果未指定，檔案將儲存在目前目錄中，其葉節點名稱與遠端檔案相同。

如果給定 $where，檔案的前 $where 位元組將不會傳輸，其餘位元組將會附加到本機檔案（如果已存在）。

傳回 $local_file，或如果未給定 $local_file，則傳回已產生的本機檔案名稱。如果遇到錯誤，則傳回未定義。

#put($local_file[, $remote_file])

將檔案放到遠端伺服器上。$local_file 可以是名稱或檔案控制代碼。如果 $local_file 是檔案控制代碼，則必須指定 $remote_file。如果未指定 $remote_file，檔案將儲存在目前目錄中，其葉節點名稱與 $local_file 相同。

傳回 $remote_file，或如果未給定 $remote_file，則傳回已產生的遠端檔案名稱。

注意：如果因為某些原因傳輸未完成，且傳回錯誤，則已傳輸的內容將不會自動移除。

#put_unique($local_file[, $remote_file])

與 put 相同，但使用 STOU 指令。

傳回伺服器上檔案的名稱。

#append($local_file[, $remote_file])

與 put 相同，但會附加到遠端伺服器上的檔案。

傳回 $remote_file，或如果未給定 $remote_file，則傳回已產生的遠端檔案名稱。

#unique_name()

傳回使用 STOU 指令儲存在伺服器上的最後一個檔案名稱。

#mdtm($file)

傳回指定檔案的修改時間

#size($file)

傳回儲存在遠端伺服器上指定檔案的位元組大小。

注意：所報告的大小是遠端伺服器上儲存的檔案大小。如果檔案隨後以 ASCII 模式從伺服器傳輸，而遠端伺服器和本機電腦對於「行尾」有不同的概念，則傳輸後本機電腦上檔案的大小可能不同。

#supported($cmd)

如果遠端伺服器支援指定的指令，則傳回 TRUE。

#hash([$filehandle_glob_ref[, $bytes_per_hash_mark]])

在沒有參數或第一個參數為 false 的情況下呼叫，雜湊標記會被抑制。如果第一個參數為 true 但不是檔案處理常式 glob 的參考，則會使用 \*STDERR。第二個參數是每個雜湊標記列印的位元組數，預設為 1024。在所有情況下，傳回值都是兩個陣列的參考：檔案處理常式 glob 參考和每個雜湊標記的位元組數。

#feature($name)

判斷伺服器是否支援指定的特色。傳回值是伺服器用來描述其支援的給定特色選項的回應行清單。如果特色不受支援，則傳回空清單。

if ($ftp->feature( 'MDTM' )) {
  # Do something
}

if (grep { /\bTLS\b/ } $ftp->feature('AUTH')) {
  # Server supports TLS
}

下列方法可以根據呼叫方式傳回不同的結果。如果使用者明確呼叫 pasv 或 port 方法，則這些方法會傳回true 或 false 值。如果使用者沒有呼叫這些方法，則結果將是基於 Net::FTP::dataconn 的物件的參考。

#nlst([$dir]): 傳送 NLST 指令到伺服器，並附帶一個選用參數。
#list([$dir]): 與 nlst 相同，但使用 LIST 指令
#retr($file): 開始從遠端伺服器擷取名為 $file 的檔案。
#stor($file): 告訴伺服器您希望儲存檔案。$file 是應建立的新檔案名稱。
#stou($file): 與 stor 相同，但使用 STOU 指令。在資料連線關閉後，可透過 unique_name 方法取得在伺服器上建立的唯一檔案名稱。
#appe($file): 告訴伺服器我們想要將一些資料附加到名為 $file 的檔案尾端。如果此檔案不存在，則建立它。

如果您因為某些原因想要完全控制資料連線，這包括產生資料連線和在需要時呼叫 response 方法，那麼使用者可以使用這些方法來執行此操作。

但是，呼叫這些方法只會影響上述可傳回資料連線的方法。它們對 get、put、put_unique 和不需要資料連線的方法沒有影響。

#port([$port])
#eprt([$port]): 將 PORT (IPv4) 或 EPRT (IPv6) 指令傳送至伺服器。如果指定 $port，則將其傳送至伺服器。如果沒有，則建立一個監聽 socket，並將正確的資訊傳送至伺服器。
#pasv()
#epsv(): 指示伺服器進入被動模式（IPv4 為 pasv，IPv6 為 epsv）。傳回代表伺服器正在監聽的埠的文字，此文字的格式適合使用 port 或 eprt 方法傳送至其他 ftp 伺服器。

下列方法可於兩個遠端伺服器之間傳輸檔案，前提是這兩個伺服器可直接彼此連線。

#pasv_xfer($src_file, $dest_server[, $dest_file ]): 此方法將在兩個遠端 ftp 伺服器之間傳輸檔案。如果省略 $dest_file，則會使用 $src_file 的葉狀節點名稱。
#pasv_xfer_unique($src_file, $dest_server[, $dest_file ]): 類似於 pasv_xfer，但檔案會使用 STOU 指令儲存在遠端伺服器上。
#pasv_wait($non_pasv_server): 此方法可於被動伺服器和非被動伺服器之間等待傳輸完成。應在被動伺服器上呼叫此方法，並將非被動伺服器的 Net::FTP 物件傳遞為引數。
#abort(): 中止目前的資料傳輸。
#quit(): 將 QUIT 指令傳送至遠端 FTP 伺服器，並關閉 socket 連線。

#冒險者的方法

#quot($cmd[, $args])

將 Net::FTP 不直接支援的指令傳送至遠端伺服器，並等待回應。

傳回回應代碼的最顯著位元。

警告此呼叫僅應使用在不需要資料連線的指令上。錯誤使用此方法可能會使連線中斷。

#can_inet6()

傳回我們是否可以使用 IPv6。

#can_ssl()

傳回我們是否可以使用 SSL。

#dataconn 類別

Net::FTP 中定義的一些方法會傳回一個物件，該物件會從 Net::FTP::dataconn 類別衍生。有關更多詳細資料，請參閱 Net::FTP::dataconn。

#未實作

尚未實作下列 RFC959 指令

#SMNT: 掛載不同的檔案系統結構，而不變更登入或會計資訊。
#HELP: 詢問伺服器有關其接受指令的「有用資訊」（這是 RFC 所說的）。
#MODE: 指定要傳輸的檔案的傳輸模式（串流、區塊或壓縮）。
#SYST: 要求遠端伺服器系統識別。
#STAT: 要求遠端伺服器狀態。
#STRU: 指定要傳輸的檔案的檔案結構。
#REIN: 重新初始化連線，清除所有 I/O 和帳戶資訊。

#匯出

無.

#已知錯誤

請參閱 https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet。

#回報錯誤

報告錯誤/問題時，請盡可能提供越多資訊越好。由於幾乎每個設定都不同，我可能很難重現問題。

產生問題的小腳本可能會有所幫助。如果使用傳遞給建構函式的額外選項 Debug => 1 執行此腳本，並將輸出與錯誤報告一起傳送，也會很有用。如果您無法提供小腳本，請提供會產生問題的程式執行後的除錯追蹤。

#另請參閱

Net::Netrc、Net::Cmd、IO::Socket::SSL；

ftp(1)、ftpd(8)；

https://www.ietf.org/rfc/rfc959.txt、https://www.ietf.org/rfc/rfc2428.txt、https://www.ietf.org/rfc/rfc4217.txt。

#致謝

Henry Gabryjelski <henryg@WPI.EDU> - 建議遞迴建立目錄。

Nathan Torkington <gnat@frii.com> - 提供文件說明的意見。

Roderick Schertler <roderick@gate.net> - 提供各種意見

#作者

Graham Barr <gbarr@pobox.com>。

從 1.22_02 版開始，Steve Hay <shay@cpan.org> 開始維護 libnet。

#著作權

#授權

此模組為自由軟體；您可以根據 Perl 本身的條款重新散布或修改它，亦即根據 LICENCE 檔案中指定的 GNU 通用公共授權或 Artistic 授權條款。

#版本

版本 3.15

#日期

2023 年 3 月 20 日

#歷程

請參閱 Changes 檔案。