libnet-1.12

名前
概要
説明
概要
コンストラクタ
メソッド
- 冒険のためのメソッド
dataconnクラス
未実装
バグの報告
作者
参考資料
使用例
謝辞(CREDITS)
著作権(COPYRIGHT)

名前¶

Net::FTP - FTPクライアント・オブジェクト

概要¶

    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つのマシン間でのバイト・サイズの大きさが違うかどうかに関わらず、その値は同じままになります。（理論的には- 実際には、あなたが実際に何をするのかわかっている場合にのみ、これを使うべきです）

コンストラクタ¶

new (HOST [,OPTIONS])

これは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または空リストを返します。

login ([LOGIN [,PASSWORD [, ACCOUNT] ] ])

与えられたログイン情報でリモートのFTPサーバーにログインします。何も引数が与えられなければ、Net::FTPは、接続するホストのためのログイン情報を検索するためNet::Netrcパッケージを使います。何も情報が見つからなければ、anonymousログインが使われます。何もパスワードが与えられず、ログインがanonymousであれば、パスワードとしてanonymous@が使われます。

接続がファイアウォールを通るのであれば、authorizeメソッドが引数なしで呼ばれます。

authorize ( [AUTH [, RESP]])

これは、いくつかのファイアウォール ftpプロキシーによって使われるプロトコルです。これはデータを外へ送信するユーザを認証するために使われます。両方の引数が指定されないと、authorizeは検索を行うためNet::Netrcを使います。

site (ARGS)

リモート・サーバにSITEコマンドを送信し、応答を待ちます。

応答コードでの最も特徴的な数字を返します。

type (TYPE [, ARGS])

このメソッドは、データ転送の種類を変更するため、リモートのFTPサーバに TYPEコマンドを送信します。戻り値は前の値です。

ascii ([ARGS]) binary([ARGS]) ebcdic([ARGS]) byte([ARGS])

先頭の引数が正しく設定されたtypeの同義語。

注意 ebcdic と byte は完全にはサポートされていません。

rename ( OLDNAME, NEWNAME )

リモートのFTPサーバー上のファイルをOLDNAMEからNEWNAMEに変更します。これはRNFR と RNTO コマンドを送信することによって行われます。

delete ( FILENAME )

FILENAMEを削除する要求をサーバーに送信します。

cwd ( [ DIR ] )

与えられた$dirにディレクトリを変更しようとします。もし$dirが".."であれば、ディレクトリを1つ上に移動しようとするため、 FTPのCDUP コマンドが使われます。ディレクトリが指定されなければ、ルートディレクトリにディレクトリを変更しようとします。

cdup ()

現在のディレクトリの親にディレクトリを変更します。

pwd ()

現在のディレクトリのフルパス名を返します。

restart ( WHERE )

次のデータ転送を開始するバイト・オフセットを設定します。Net::FTPは単にこの値を記録し、次のデータ転送のときに使うだけです。このため、このメソッドはエラーを返すことはありません。しかしこれを設定することによって後のデータ転送が失敗するかもしれません。

rmdir ( DIR )

DIRという名前のディレクトリを削除します。

mkdir ( DIR [, RECURSE ])

DIRという名前のディレクトリを作成します。RECURSEがtrueであれば、 mkdirは与えられたパスでの全てのディレクトリを作成しようとします。

新しいディレクトリへのフルパス名を返します。

ls ( [ DIR ] )

DIRあるいは現在のディレクトリのディレクトリ・リストを取得します。

配列コンテキストでは、サーバーから返される行のリストを返します。スカラー・コンテキストでは、リストへのリファレンスを返します。

dir ( [ DIR ] )

DIRあるいは現在のディレクトリのディレクトリ・リストを長い書式で取得します。

配列コンテキストではサーバーから返された行のリストを返します。スカラーコンテキストではリストへのリファレンスを返します。

get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] )

サーバーからREMOTE_FILEを取得し、ローカルに保存します。LOCAL_FILEはファイル名またはファイルハンドルにすることができます。指定されなければ、現在のディレクトリに、リモートファイルと同じディレクトリ部分を除いた名前(leafname) に保存されます。

WHEREが与えられると、そのファイルの最初のWHEREバイトは転送されません。そして既にそれが存在すれば、残りのバイトがローカルファイルに追記されます。

LOCAL_FILEあるいはLOCAL_FILEが与えられなければ作成されたファイル名を返します。エラーにぶつかればundefが返されます。

put ( LOCAL_FILE [, REMOTE_FILE ] )

リモートサーバにファイルを出力します。LOCAL_FILEはファイル名あるいはファイルハンドルにすることができます。LOCAL_FILEがファイルハンドルであれば REMOTE_FILEは指定されなければなりません。REMOTE_FILEが指定されなければ、ファイルは現在の現在のディレクトリに、LOCAL_FILEと同じディレクトリ部分を除いた名前(leafname)に保存されます。

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 )

与えられたファイルの更新時刻(modification time)を返します。

size ( FILE )

与えられたファイルの大きさを、リモート・サーバーに格納されているバイト単位で返します。

注意: 報告される大きさはリモートサーバー上に格納されたファイルの大きさです。後でファイルがサーバーからASCIIモードで転送され、リモートサーバーとローカルマシンの "行末(End Of Line)"の考え方が違うならば、転送後のローカルマシン上のファイルの大きさは違うかもしれません。

supported ( CMD )

リモートサーバーが与えられたコマンドをサポートしていれば、TRUEを返します。

hash ( [FILEHANDLE_GLOB_REF],[ BYTES_PER_HASH_MARK] )

パラメータなし、あるいは最初の引数がfalseで呼ばれると、ハッシュ・マークは出力されません。最初の引数がtrueであってもファイルハンドル・グロブへのリファレンスでなければ、\*STDERRが使われます。2番目の引数は出力されるハッシュ・マーク毎のバイト数です。デフォルトは1024です。全てのケースで、戻り値は2つの配列へのリファレンスです:ファイルハンドル・グロブ・リファレンスとハッシュ・マーク毎のバイト数です。

以下のメソッドは、呼ばれ方によって異なる結果を返すかもしれません。ユーザーが明示的に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 ] ): サーバーにPORTコマンドを送信します。PORTが指定されると、それはサーバーに送信されます。指定されなければ、リスン・ソケットが作成され、正しい情報がサーバーに送られます。
pasv (): サーバーにパッシブ・モードでいくことを伝えます。サーバーがリスンしているポートを表すテキストを返します。このテキストはportメソッドを使って他のftpサーバーに送信するのに適した形式になっています。

以下のメソッドは、2つのサーバーがお互いに直接接続できるとき、これら2つのリモート・サーバー間でファイルを転送するために使うことが出来ます。

pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ): このメソッドは2つのリモート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 (): リモートFTPサーバにQUITコマンドを送信し、ソケット接続を閉じます。

冒険のためのメソッド¶

Net::FTPはNet::Cmdを継承しています。そのためNet::Cmdで定義されているメソッドをリモートのFTPサーバーにコマンドを送信するために使うことが出来ます。

quot (CMD [,ARGS])

Net::FTPが直接サポートしていないコマンドをリモート・サーバに送信し、応答を待ちます。

応答コードでの最も特徴的な数字を返します。

警告これはデータコネクションを必要としないコマンドに対してのみ使うべきです。このメソッドを間違って使用すると接続がハングするかもしれません。

dataconnクラス¶

Net::FTPで定義されているメソッドのいくつかは、このクラスから派生したオブジェクトを返します。dataconnクラスそのものはIO::Socket::INETクラスから派生しています。そのため通常のIO操作のすべてを行うことが出来ます。しかし以下のメソッドがdataconnクラスで定義されており、IOはこれらを使って行われなければなりません。

read ( BUFFER, SIZE [, TIMEOUT ] )

サーバからデータのSIZEバイトを読み込み、それをBUFFERにいれます。また必要であれば<CRLF>の変換も行います。TIMEOUTはオプションで、与えられると、そのコマンド接続から、そのtimeout値が使われます。

CRLF変換前の読み込んだバイト数が返されます。

write ( BUFFER, SIZE [, TIMEOUT ] )

BUFFERからのデータのSIZEバイトをサーバーに書き込みます。また必要であれば<CRLF>の変換も行います。TIMEOUTはオプションで、与えられると、そのコマンド接続から、そのtimeout値が使われます。

CRLF変換前の書き込まれたバイト数が返されます。

bytes_read ()

それまでに読み込まれたバイト数を返します。

abort ()

現在のデータ転送を中止します。

close ()

データコネクションをクローズし、FTPサーバーからの応答を取得します。接続が正常にクローズされ、サーバーからの応答の最初の数字が'2'であれば、trueを返します。

未実装¶

以下のRFC959コマンドはまだ実装されていません:

ALLO: 転送されるファイルのための領域を確保します。
SMNT: ログインやアカウント情報を変更することなく、異なるファイルシステム構造をマウントします。
HELP: サーバーに、それが受け入れるコマンドについての (RFCが言うところの)"助けになるような情報"を求めます。
MODE: 転送されるファイルのための転送モード(stream, blockあるいはcompressed)を指定します。
SYST: リモート・サーバーのシステム識別子を要求します。
STAT: リモート・サーバーのステータスを要求します。
STRU: 転送されるファイルのためのファイル構造体を指定します。
REIN: 接続の再初期化。全ての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の使用例については、これをご覧ください

http://www.csh.rit.edu/~adam/Progs/autoftp-2.0.tar.gz: autoftpは対話することなく、FTPプロトコルを通してファイルの取得、送信、一覧をすることができるプログラムです。

謝辞(CREDITS)¶

Henry Gabryjelski <henryg@WPI.EDU> - 再帰的にディレクトリを作るという提案に対して

Nathan Torkington <gnat@frii.com> - ドキュメントでのいくつかの入力に対して

Roderick Schertler <roderick@gate.net> - いくつかの入力に対して

著作権(COPYRIGHT)¶

$Id$