use Net::FTP;
$ftp = Net::FTP->new("some.host.name", Debug => 0);
$ftp->login("anonymous",'-anonymous@');
$ftp->cwd("/pub");
$ftp->get("that.file");
$ftp->quit;
Net::FTPはPerlでRFC959に記述されているFTPの、簡単な
クライアントを実装するためのクラスです。RFC959コマンドのサブセットの
ためのラッパーを提供します。
FTP はFile Transfer Protocolの略です。これはネットワークで結ばれた マシン間でファイルを転送する手段です。プロトコルはクライアント（その コマンドは、このモジュールによって提供されます）とサーバー（このモジュールでは 実装されません）を定義しています。通信は常にクライアントから開始されます。 そしてサーバーはメッセージとステータスコードを（それに場合によってはデータも） つけて応答します。
FTPプロトコルはサーバーへファイルの送信や取得を可能にします。
それぞれの転送には(クライアント上の)ローカル・ファイルと
(サーバー上の)リモート・ファイルが含まれます。このモジュールでは
、１つしか指定されなければ、同じファイル名がローカルとリモートの両方で
使われます。これはローカル・ファイル名を指定しなければ、
リモート・ファイル/path/to/fileを転送することは、そのファイルを
ローカルの/path/to/fileに入れようとするということを意味します。
プロトコルは、ファイルを転送中にファイルが受ける、さまざまな標準の 変換も定義しています。これらはASCII, EBCDIC, binary,そして byteです。 ASCIIがデフォルトのタイプで、ファイルの送信者が行の末尾を標準の表現に 変換し、受信者はそのローカルな表現に変換しなおします。EBCDICはファイルが EBCDIC形式に変換されることを示します。Binary（imageとしても知られています） 形式は、データを切れ目のないビット・ストリームとして送信します。 Byte形式はデータをバイトで転送します。2つのマシン間でのバイト・サイズの大きさが 違うかどうかに関わらず、その値は同じままになります。（理論的には- 実際には、あなたが実際に何をするのかわかっている場合にのみ、これを使うべきです）
これはNet::FTPオブジェクトのためのコンストラクタです。HOSTは
FTP接続が必要とするリモート・ホストの名前です。
OPTIONSはキーと値の組というハッシュの形式で渡されます。
指定できるオプションは以下の通りです:
Firewall - FTPファイアウォールとして機能するマシンの名前。これは
環境変数FTP_FIREWALLによって上書きすることができます。
これが指定され与えられたホストに直接接続できなければ、
ファイアウォール・マシンへの接続が作られ、文字列@hostnameがログイン識別子に
追加されます。この種の設定はftpプロキシーとも呼ばれています。
FirewallType - Firewallによって示されたマシンで実行されているファイアウォールの
種類。これは環境変数FTP_FIREWALL_TYPEによって上書きすることができます。
許されるタイプの一覧については、Net::Configでのftp_firewall_typeの説明を
ご覧ください。
BlockSize - Net::FTPが転送のさいに利用するブロックサイズ。（デフォルトは10240)
Port - FTP接続のためのリモート・マシンに接続するためのポート番号
Timeout - タイムアウト値を設定します(デフォルトは120)
Debug - デバッグ・レベル(Net::Cmdでのdebugメソッドを、ご覧ください）
Passive - 0以外の値を設定すると、全てのデータ転送はパッシブモードを
使って行われます。いくつかのダム(dumb)サーバーといくつかのファイアウォールの
設定を除けば、通常、必要とされません。これは環境変数FTP_PASSIVEによって
設定することもできます。
Hash - ファイルハンドルへのリファレンス(e.g., \*STDERR)が与えられると、
1024バイト毎にハッシュ・マーク(#)を出力します。これは、全ての転送で
ハッシュ・マークが表示されるように、あなたに代わってhash()メソッドを
呼び出すだけです。もちろんいつでも好きなときに、明示的にhash()を呼ぶことが
できます。
コンストラクタが失敗すると、undefが返され、エラーメッセージが$@に入ります。
特に記述がなければ、全てのメソッドはtrueまたはfalseを返します。 trueが処理が成功したことを意味します。メソッドが値を返すと 宣言しているときには、失敗ではundefまたは空リストを返します。
与えられたログイン情報でリモートのFTPサーバーにログインします。何も
引数が与えられなければ、Net::FTPは、接続するホストのための
ログイン情報を検索するためNet::Netrcパッケージを使います。何も情報が
見つからなければ、anonymousログインが使われます。
何もパスワードが与えられず、ログインがanonymousであれば、パスワード
としてanonymous@が使われます。
接続がファイアウォールを通るのであれば、authorizeメソッドが引数なしで
呼ばれます。
これは、いくつかのファイアウォール ftpプロキシーによって使われるプロトコルです。
これはデータを外へ送信するユーザを認証するために使われます。
両方の引数が指定されないと、authorizeは検索を行うためNet::Netrcを使います。
リモート・サーバにSITEコマンドを送信し、応答を待ちます。
応答コードでの最も特徴的な数字を返します。
このメソッドは、データ転送の種類を変更するため、リモートのFTPサーバに TYPEコマンドを送信します。戻り値は前の値です。
先頭の引数が正しく設定されたtypeの同義語。
注意 ebcdic と byte は完全にはサポートされていません。
リモートのFTPサーバー上のファイルをOLDNAMEからNEWNAMEに変更します。
これはRNFR と RNTO コマンドを送信することによって行われます。
FILENAMEを削除する要求をサーバーに送信します。
与えられた$dirにディレクトリを変更しようとします。
もし$dirが".."であれば、ディレクトリを1つ上に移動しようとするため、
FTPのCDUP コマンドが使われます。ディレクトリが指定されなければ、
ルートディレクトリにディレクトリを変更しようとします。
現在のディレクトリの親にディレクトリを変更します。
現在のディレクトリのフルパス名を返します。
次のデータ転送を開始するバイト・オフセットを設定します。Net::FTPは単に この値を記録し、次のデータ転送のときに使うだけです。このため、このメソッドは エラーを返すことはありません。しかしこれを設定することによって 後のデータ転送が失敗するかもしれません。
DIRという名前のディレクトリを削除します。
DIRという名前のディレクトリを作成します。RECURSEがtrueであれば、
mkdirは与えられたパスでの全てのディレクトリを作成しようとします。
新しいディレクトリへのフルパス名を返します。
DIRあるいは現在のディレクトリのディレクトリ・リストを取得します。
配列コンテキストでは、サーバーから返される行のリストを返します。 スカラー・コンテキストでは、リストへのリファレンスを返します。
DIRあるいは現在のディレクトリのディレクトリ・リストを長い書式で取得します。
配列コンテキストではサーバーから返された行のリストを返します。 スカラーコンテキストではリストへのリファレンスを返します。
サーバーからREMOTE_FILEを取得し、ローカルに保存します。LOCAL_FILEは
ファイル名またはファイルハンドルにすることができます。指定されなければ、
現在のディレクトリに、リモートファイルと同じディレクトリ部分を除いた名前(leafname)
に保存されます。
WHEREが与えられると、そのファイルの最初のWHEREバイトは転送されません。
そして既にそれが存在すれば、残りのバイトがローカルファイルに追記されます。
LOCAL_FILEあるいはLOCAL_FILEが与えられなければ作成されたファイル名を
返します。エラーにぶつかればundefが返されます。
リモートサーバにファイルを出力します。LOCAL_FILEはファイル名あるいは
ファイルハンドルにすることができます。LOCAL_FILEがファイルハンドルであれば
REMOTE_FILEは指定されなければなりません。REMOTE_FILEが指定されなければ、
ファイルは現在の現在のディレクトリに、LOCAL_FILEと同じディレクトリ部分を
除いた名前(leafname)に保存されます。
REMOTE_FILEあるいはREMOTE_FILEが与えられなければ作成されたファイル名を
返します。
注意: 何らかの理由で転送が完了せず、エラーが返されたとき、 転送されてしまった内容は自動的には削除されません。
putと同じですが、STOUコマンドを使用します。
サーバー上のファイル名を返します。
putと同じ。しかしリモート・サーバー上のファイルに追記します。
REMOTE_FILEあるいはREMOTE_FILEが与えられなければ作成されたファイル名を
返します。
STOUコマンドを使ってサーバー上に格納された最後のファイルの名前を
返します。
与えられたファイルの更新時刻(modification time)を返します。
与えられたファイルの大きさを、リモート・サーバーに格納されている バイト単位で返します。
注意: 報告される大きさはリモートサーバー上に格納されたファイルの大きさです。 後でファイルがサーバーからASCIIモードで転送され、リモートサーバーとローカルマシンの "行末(End Of Line)"の考え方が違うならば、転送後のローカルマシン上のファイルの大きさ は違うかもしれません。
リモートサーバーが与えられたコマンドをサポートしていれば、TRUEを返します。
パラメータなし、あるいは最初の引数がfalseで呼ばれると、ハッシュ・マークは 出力されません。最初の引数がtrueであってもファイルハンドル・グロブへの リファレンスでなければ、\*STDERRが使われます。2番目の引数は 出力されるハッシュ・マーク毎のバイト数です。デフォルトは1024です。全てのケースで、 戻り値は2つの配列へのリファレンスです:ファイルハンドル・グロブ・リファレンスと ハッシュ・マーク毎のバイト数です。
以下のメソッドは、呼ばれ方によって異なる結果を返すかもしれません。
ユーザーが明示的にpasvあるいはportメソッドを呼び出せば、
これらのメソッドはtrueあるいはfalse値を返します。もし
ユーザーがこれらのメソッドのどちらも呼び出さなければ、
結果はNet::FTP::dataconnをベースとしたオブジェクトへのリファレンスに
なります。
オプションのパラメータをつけて、サーバーにNLSTコマンドを送信します。
nlstと同じですがLISTコマンドを利用します。
リモート・サーバーからFILEと呼ばれるファイルの取り出しを開始します。
サーバーにファイルを格納したいことを伝えます。FILEは作られるべき
新しいファイルの名前です。
storと同様ですがSTOUコマンドを利用します。サーバー上に作成された
一意なファイルの名前は、データコネクションが閉じた後、unique_nameメソッドを
通して取得することが出来ます。
サーバーにFILEというファイルの末尾にデータを追記したいことを伝えます。
そのファイルが存在しなければ、作成します。
何らかの理由で、それを生成し必要なときにはresponseメソッドを
呼び出すことを含めて、データコネクションを完全に制御したければ、
ユーザはこれらのメソッドを使ってそうすることができます。
しかしこれらのメソッドは単に、データコネクションを返すことが出来る上記の
メソッドの利用に影響を与えるだけです。get, put,put_uniqueそして
データコネクションを必要としないものには、なんら影響を与えません。
サーバーにPORTコマンドを送信します。PORTが指定されると、それはサーバーに
送信されます。指定されなければ、リスン・ソケットが作成され、正しい情報が
サーバーに送られます。
サーバーにパッシブ・モードでいくことを伝えます。サーバーがリスンしているポートを
表すテキストを返します。このテキストはportメソッドを使って他のftpサーバーに
送信するのに適した形式になっています。
以下のメソッドは、2つのサーバーがお互いに直接接続できるとき、これら2つの リモート・サーバー間でファイルを転送するために使うことが出来ます。
このメソッドは2つのリモートftpサーバー間でファイル転送を行います。もし
DEST_FILEが省略されると、SRC_FILEのディレクトリ部を除いたファイル名が
使われます。
pasv_xferと似ていますが、ファイルはSTOUコマンドを使って
リモート・サーバに格納されます。
このメソッドはパッシブ・サーバと非パッシブ・サーバとの間での転送の完了を
待つために利用することができます。このメソッドはパッシブ・サーバで
引数である非パッシブ・サーバ用のNet::FTPオブジェクトで、
呼び出されなければなりません。
現在のデータ転送を中止します。
リモートFTPサーバにQUITコマンドを送信し、ソケット接続を閉じます。
Net::FTPはNet::Cmdを継承しています。そのためNet::Cmdで定義
されているメソッドをリモートのFTPサーバーにコマンドを送信するために
使うことが出来ます。
Net::FTPが直接サポートしていないコマンドをリモート・サーバに送信し、 応答を待ちます。
応答コードでの最も特徴的な数字を返します。
警告 これはデータコネクションを必要としないコマンドに対してのみ使うべきです。 このメソッドを間違って使用すると接続がハングするかもしれません。
Net::FTPで定義されているメソッドのいくつかは、このクラスから派生した
オブジェクトを返します。dataconnクラスそのものはIO::Socket::INETクラス
から派生しています。そのため通常のIO操作のすべてを行うことが出来ます。
しかし以下のメソッドがdataconnクラスで定義されており、IOはこれらを使って
行われなければなりません。
サーバからデータのSIZEバイトを読み込み、それをBUFFERにいれます。
また必要であれば<CRLF>の変換も行います。TIMEOUTはオプションで、
与えられると、そのコマンド接続から、そのtimeout値が使われます。
CRLF変換前の読み込んだバイト数が返されます。
BUFFERからのデータのSIZEバイトをサーバーに書き込みます。
また必要であれば<CRLF>の変換も行います。TIMEOUTはオプションで、
与えられると、そのコマンド接続から、そのtimeout値が使われます。
CRLF変換前の書き込まれたバイト数が返されます。
それまでに読み込まれたバイト数を返します。
現在のデータ転送を中止します。
データコネクションをクローズし、FTPサーバーからの応答を取得します。接続が正常に クローズされ、サーバーからの応答の最初の数字が'2'であれば、trueを 返します。
以下のRFC959コマンドはまだ実装されていません:
転送されるファイルのための領域を確保します。
ログインやアカウント情報を変更することなく、 異なるファイルシステム構造をマウントします。
サーバーに、それが受け入れるコマンドについての (RFCが言うところの)"助けになるような情報"を求めます。
転送されるファイルのための転送モード(stream, blockあるいはcompressed)を 指定します。
リモート・サーバーのシステム識別子を要求します。
リモート・サーバーのステータスを要求します。
転送されるファイルのためのファイル構造体を指定します。
接続の再初期化。全てのI/Oとアカウント情報をフラッシュします。
バグ/障害を報告するときには、できる限り多くの情報を入れてください。 セットアップはほとんど全て、それぞれに異なるため、私には障害を再現させる ことが難しいかもしれません。
障害を起こす小さなスクリプトは、おそらく助けになるでしょう。このスクリプトを
特別なオプションDebug = 1>をコンストラクタに渡して実行し、
その出力をバグレポートにつけて送ることも有効でしょう。小さなスクリプトを
入れることが出来なければ、障害を起こすプログラムの実行からのDebugトレースを
入れてください。
Graham Barr <gbarr@pobox.com>
Net::Netrc Net::Cmd
ftp(1), ftpd(8), RFC 959 http://www.cis.ohio-state.edu/htbin/rfc/rfc959.html
Net::FTPの使用例については、これをご覧ください
autoftpは対話することなく、FTPプロトコルを通してファイルの
取得、送信、一覧をすることができるプログラムです。