=encoding euc-jp =head1 名前 Net::FTP - FTPクライアント・オブジェクト =head1 概要 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; =head1 説明 CはPerlでRFC959に記述されているFTPの、簡単な クライアントを実装するためのクラスです。RFC959コマンドのサブセットの ためのラッパーを提供します。 =head1 概要 FTP はFile Transfer Protocolの略です。これはネットワークで結ばれた マシン間でファイルを転送する手段です。プロトコルはクライアント（その コマンドは、このモジュールによって提供されます）とサーバー（このモジュールでは 実装されません）を定義しています。通信は常にクライアントから開始されます。 そしてサーバーはメッセージとステータスコードを（それに場合によってはデータも） つけて応答します。 FTPプロトコルはサーバーへファイルの送信や取得を可能にします。 それぞれの転送には(クライアント上の)B<ローカル・ファイル>と (サーバー上の)B<リモート・ファイル>が含まれます。このモジュールでは 、１つしか指定されなければ、同じファイル名がローカルとリモートの両方で 使われます。これはローカル・ファイル名を指定しなければ、 リモート・ファイルCを転送することは、そのファイルを ローカルのCに入れようとするということを意味します。 プロトコルは、ファイルを転送中にファイルが受ける、さまざまな標準の B<変換>も定義しています。これらはASCII, EBCDIC, binary,そして byteです。 ASCIIがデフォルトのタイプで、ファイルの送信者が行の末尾を標準の表現に 変換し、受信者はそのローカルな表現に変換しなおします。EBCDICはファイルが EBCDIC形式に変換されることを示します。Binary（imageとしても知られています） 形式は、データを切れ目のないビット・ストリームとして送信します。 Byte形式はデータをバイトで転送します。2つのマシン間でのバイト・サイズの大きさが 違うかどうかに関わらず、その値は同じままになります。（理論的には- 実際には、あなたが実際に何をするのかわかっている場合にのみ、これを使うべきです） =head1 コンストラクタ =over 4 =item new (HOST [,OPTIONS]) これはNet::FTPオブジェクトのためのコンストラクタです。Cは FTP接続が必要とするリモート・ホストの名前です。 Cはキーと値の組というハッシュの形式で渡されます。 指定できるオプションは以下の通りです: B - FTPファイアウォールとして機能するマシンの名前。これは 環境変数Cによって上書きすることができます。 これが指定され与えられたホストに直接接続できなければ、 ファイアウォール・マシンへの接続が作られ、文字列C<@hostname>がログイン識別子に 追加されます。この種の設定はftpプロキシーとも呼ばれています。 B - Bによって示されたマシンで実行されているファイアウォールの 種類。これは環境変数Cによって上書きすることができます。 許されるタイプの一覧については、Lでのftp_firewall_typeの説明を ご覧ください。 B - Net::FTPが転送のさいに利用するブロックサイズ。（デフォルトは10240) B - FTP接続のためのリモート・マシンに接続するためのポート番号 B - タイムアウト値を設定します(デフォルトは120) B - デバッグ・レベル(Lでのdebugメソッドを、ご覧ください） B - 0以外の値を設定すると、全てのデータ転送はパッシブモードを 使って行われます。いくつかのI<ダム(dumb)>サーバーといくつかのファイアウォールの 設定を除けば、通常、必要とされません。これは環境変数Cによって 設定することもできます。 B - ファイルハンドルへのリファレンス(e.g., C<\*STDERR>)が与えられると、 1024バイト毎にハッシュ・マーク(#)を出力します。これは、全ての転送で ハッシュ・マークが表示されるように、あなたに代わってCメソッドを 呼び出すだけです。もちろんいつでも好きなときに、明示的にCを呼ぶことが できます。 コンストラクタが失敗すると、undefが返され、エラーメッセージが$@に入ります。 =back =head1 メソッド 特に記述がなければ、全てのメソッドはIまたはIを返します。 Iが処理が成功したことを意味します。メソッドが値を返すと 宣言しているときには、失敗ではIまたは空リストを返します。 =over 4 =item login ([LOGIN [,PASSWORD [, ACCOUNT] ] ]) 与えられたログイン情報でリモートのFTPサーバーにログインします。何も 引数が与えられなければ、Cは、接続するホストのための ログイン情報を検索するためCパッケージを使います。何も情報が 見つからなければ、Iログインが使われます。 何もパスワードが与えられず、ログインがIであれば、パスワード としてIが使われます。 接続がファイアウォールを通るのであれば、Cメソッドが引数なしで 呼ばれます。 =item authorize ( [AUTH [, RESP]]) これは、いくつかのファイアウォール ftpプロキシーによって使われるプロトコルです。 これはデータを外へ送信するユーザを認証するために使われます。 両方の引数が指定されないと、Cは検索を行うためCを使います。 =item site (ARGS) リモート・サーバにSITEコマンドを送信し、応答を待ちます。 応答コードでの最も特徴的な数字を返します。 =item type (TYPE [, ARGS]) このメソッドは、データ転送の種類を変更するため、リモートのFTPサーバに TYPEコマンドを送信します。戻り値は前の値です。 =item ascii ([ARGS]) binary([ARGS]) ebcdic([ARGS]) byte([ARGS]) 先頭の引数が正しく設定されたCの同義語。 B<注意> ebcdic と byte は完全にはサポートされていません。 =item rename ( OLDNAME, NEWNAME ) リモートのFTPサーバー上のファイルをCからCに変更します。 これはRNFR と RNTO コマンドを送信することによって行われます。 =item delete ( FILENAME ) Cを削除する要求をサーバーに送信します。 =item cwd ( [ DIR ] ) 与えられたC<$dir>にディレクトリを変更しようとします。 もしC<$dir>がC<"..">であれば、ディレクトリを1つ上に移動しようとするため、 FTPのC コマンドが使われます。ディレクトリが指定されなければ、 ルートディレクトリにディレクトリを変更しようとします。 =item cdup () 現在のディレクトリの親にディレクトリを変更します。 =item pwd () 現在のディレクトリのフルパス名を返します。 =item restart ( WHERE ) 次のデータ転送を開始するバイト・オフセットを設定します。Net::FTPは単に この値を記録し、次のデータ転送のときに使うだけです。このため、このメソッドは エラーを返すことはありません。しかしこれを設定することによって 後のデータ転送が失敗するかもしれません。 =item rmdir ( DIR ) Cという名前のディレクトリを削除します。 =item mkdir ( DIR [, RECURSE ]) Cという名前のディレクトリを作成します。CがIであれば、 Cは与えられたパスでの全てのディレクトリを作成しようとします。 新しいディレクトリへのフルパス名を返します。 =item ls ( [ DIR ] ) Cあるいは現在のディレクトリのディレクトリ・リストを取得します。 配列コンテキストでは、サーバーから返される行のリストを返します。 スカラー・コンテキストでは、リストへのリファレンスを返します。 =item dir ( [ DIR ] ) Cあるいは現在のディレクトリのディレクトリ・リストを長い書式で取得します。 配列コンテキストではサーバーから返された行のリストを返します。 スカラーコンテキストではリストへのリファレンスを返します。 =item get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] ) サーバーからCを取得し、ローカルに保存します。Cは ファイル名またはファイルハンドルにすることができます。指定されなければ、 現在のディレクトリに、リモートファイルと同じディレクトリ部分を除いた名前(leafname) に保存されます。 Cが与えられると、そのファイルの最初のCバイトは転送されません。 そして既にそれが存在すれば、残りのバイトがローカルファイルに追記されます。 CあるいはCが与えられなければ作成されたファイル名を 返します。エラーにぶつかればundefが返されます。 =item put ( LOCAL_FILE [, REMOTE_FILE ] ) リモートサーバにファイルを出力します。Cはファイル名あるいは ファイルハンドルにすることができます。Cがファイルハンドルであれば Cは指定されなければなりません。Cが指定されなければ、 ファイルは現在の現在のディレクトリに、Cと同じディレクトリ部分を 除いた名前(leafname)に保存されます。 CあるいはCが与えられなければ作成されたファイル名を 返します。 B<注意>: 何らかの理由で転送が完了せず、エラーが返されたとき、 転送されてしまった内容は自動的には削除されません。 =item put_unique ( LOCAL_FILE [, REMOTE_FILE ] ) putと同じですが、Cコマンドを使用します。 サーバー上のファイル名を返します。 =item append ( LOCAL_FILE [, REMOTE_FILE ] ) putと同じ。しかしリモート・サーバー上のファイルに追記します。 CあるいはCが与えられなければ作成されたファイル名を 返します。 =item unique_name () Cコマンドを使ってサーバー上に格納された最後のファイルの名前を 返します。 =item mdtm ( FILE ) 与えられたファイルのI<更新時刻(modification time)>を返します。 =item size ( FILE ) 与えられたファイルの大きさを、リモート・サーバーに格納されている バイト単位で返します。 B<注意>: 報告される大きさはリモートサーバー上に格納されたファイルの大きさです。 後でファイルがサーバーからASCIIモードで転送され、リモートサーバーとローカルマシンの "行末(End Of Line)"の考え方が違うならば、転送後のローカルマシン上のファイルの大きさ は違うかもしれません。 =item supported ( CMD ) リモートサーバーが与えられたコマンドをサポートしていれば、TRUEを返します。 =item hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] ) パラメータなし、あるいは最初の引数がfalseで呼ばれると、ハッシュ・マークは 出力されません。最初の引数がtrueであってもファイルハンドル・グロブへの リファレンスでなければ、\*STDERRが使われます。2番目の引数は 出力されるハッシュ・マーク毎のバイト数です。デフォルトは1024です。全てのケースで、 戻り値は2つの配列へのリファレンスです:ファイルハンドル・グロブ・リファレンスと ハッシュ・マーク毎のバイト数です。 =back 以下のメソッドは、呼ばれ方によって異なる結果を返すかもしれません。 ユーザーが明示的にCあるいはCメソッドを呼び出せば、 これらのメソッドはIあるいはI値を返します。もし ユーザーがこれらのメソッドのどちらも呼び出さなければ、 結果はCをベースとしたオブジェクトへのリファレンスに なります。 =over 4 =item nlst ( [ DIR ] ) オプションのパラメータをつけて、サーバーにCコマンドを送信します。 =item list ( [ DIR ] ) Cと同じですがCコマンドを利用します。 =item retr ( FILE ) リモート・サーバーからCと呼ばれるファイルの取り出しを開始します。 =item stor ( FILE ) サーバーにファイルを格納したいことを伝えます。Cは作られるべき 新しいファイルの名前です。 =item stou ( FILE ) Cと同様ですがCコマンドを利用します。サーバー上に作成された 一意なファイルの名前は、データコネクションが閉じた後、Cメソッドを 通して取得することが出来ます。 =item appe ( FILE ) サーバーにCというファイルの末尾にデータを追記したいことを伝えます。 そのファイルが存在しなければ、作成します。 =back 何らかの理由で、それを生成し必要なときにはCメソッドを 呼び出すことを含めて、データコネクションを完全に制御したければ、 ユーザはこれらのメソッドを使ってそうすることができます。 しかしこれらのメソッドは単に、データコネクションを返すことが出来る上記の メソッドの利用に影響を与えるだけです。C, C,Cそして データコネクションを必要としないものには、なんら影響を与えません。 =over 4 =item port ( [ PORT ] ) サーバーにCコマンドを送信します。Cが指定されると、それはサーバーに 送信されます。指定されなければ、リスン・ソケットが作成され、正しい情報が サーバーに送られます。 =item pasv () サーバーにパッシブ・モードでいくことを伝えます。サーバーがリスンしているポートを 表すテキストを返します。このテキストはCメソッドを使って他のftpサーバーに 送信するのに適した形式になっています。 =back 以下のメソッドは、2つのサーバーがお互いに直接接続できるとき、これら2つの リモート・サーバー間でファイルを転送するために使うことが出来ます。 =over 4 =item pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ) このメソッドは2つのリモートftpサーバー間でファイル転送を行います。もし Cが省略されると、Cのディレクトリ部を除いたファイル名が 使われます。 =item pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ) Cと似ていますが、ファイルはSTOUコマンドを使って リモート・サーバに格納されます。 =item pasv_wait ( NON_PASV_SERVER ) このメソッドはパッシブ・サーバと非パッシブ・サーバとの間での転送の完了を 待つために利用することができます。このメソッドはパッシブ・サーバで 引数である非パッシブ・サーバ用のCオブジェクトで、 呼び出されなければなりません。 =item abort () 現在のデータ転送を中止します。 =item quit () リモートFTPサーバにQUITコマンドを送信し、ソケット接続を閉じます。 =back =head2 冒険のためのメソッド CはCを継承しています。そのためCで定義 されているメソッドをリモートのFTPサーバーにコマンドを送信するために 使うことが出来ます。 =over 4 =item quot (CMD [,ARGS]) Net::FTPが直接サポートしていないコマンドをリモート・サーバに送信し、 応答を待ちます。 応答コードでの最も特徴的な数字を返します。 B<警告> これはデータコネクションを必要としないコマンドに対してのみ使うべきです。 このメソッドを間違って使用すると接続がハングするかもしれません。 =back =head1 dataconnクラス Cで定義されているメソッドのいくつかは、このクラスから派生した オブジェクトを返します。dataconnクラスそのものはCクラス から派生しています。そのため通常のIO操作のすべてを行うことが出来ます。 しかし以下のメソッドがdataconnクラスで定義されており、IOはこれらを使って 行われなければなりません。 =over 4 =item read ( BUFFER, SIZE [, TIMEOUT ] ) サーバからデータのCバイトを読み込み、それをCにいれます。 また必要であればの変換も行います。Cはオプションで、 与えられると、そのコマンド接続から、そのtimeout値が使われます。 C変換前の読み込んだバイト数が返されます。 =item write ( BUFFER, SIZE [, TIMEOUT ] ) CからのデータのCバイトをサーバーに書き込みます。 また必要であればの変換も行います。Cはオプションで、 与えられると、そのコマンド接続から、そのtimeout値が使われます。 C変換前の書き込まれたバイト数が返されます。 =item bytes_read () それまでに読み込まれたバイト数を返します。 =item abort () 現在のデータ転送を中止します。 =item close () データコネクションをクローズし、FTPサーバーからの応答を取得します。接続が正常に クローズされ、サーバーからの応答の最初の数字が'2'であれば、Iを 返します。 =back =head1 未実装 以下のRFC959コマンドはまだ実装されていません: =over 4 =item B 転送されるファイルのための領域を確保します。 =item B ログインやアカウント情報を変更することなく、 異なるファイルシステム構造をマウントします。 =item B サーバーに、それが受け入れるコマンドについての (RFCが言うところの)"助けになるような情報"を求めます。 =item B 転送されるファイルのための転送モード(stream, blockあるいはcompressed)を 指定します。 =item B リモート・サーバーのシステム識別子を要求します。 =item B リモート・サーバーのステータスを要求します。 =item B 転送されるファイルのためのファイル構造体を指定します。 =item B 接続の再初期化。全てのI/Oとアカウント情報をフラッシュします。 =back =head1 バグの報告 バグ/障害を報告するときには、できる限り多くの情報を入れてください。 セットアップはほとんど全て、それぞれに異なるため、私には障害を再現させる ことが難しいかもしれません。 障害を起こす小さなスクリプトは、おそらく助けになるでしょう。このスクリプトを 特別なオプションC 1>をコンストラクタに渡して実行し、 その出力をバグレポートにつけて送ることも有効でしょう。小さなスクリプトを 入れることが出来なければ、障害を起こすプログラムの実行からのDebugトレースを 入れてください。 =head1 作者 Graham Barr =head1 参考資料 L L ftp(1), ftpd(8), RFC 959 http://www.cis.ohio-state.edu/htbin/rfc/rfc959.html =head1 使用例 Net::FTPの使用例については、これをご覧ください =over 4 =item http://www.csh.rit.edu/~adam/Progs/autoftp-2.0.tar.gz Cは対話することなく、FTPプロトコルを通してファイルの 取得、送信、一覧をすることができるプログラムです。 =back =head1 謝辞(CREDITS) Henry Gabryjelski - 再帰的にディレクトリを作るという提案に対して Nathan Torkington - ドキュメントでのいくつかの入力に対して Roderick Schertler - いくつかの入力に対して =head1 著作権(COPYRIGHT) Copyright (c) 1995-1998 Graham Barr. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =for html
I<$Id: FTP.pod,v 1.2 2011/01/27 13:15:11 iwai Exp $>