libnet-1.12 > Net::FTP

名前

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プロトコルはサーバーへファイルの送信や取得を可能にします。 それぞれの転送には(クライアント上の)ローカル・ファイルと (サーバー上の)リモート・ファイルが含まれます。このモジュールでは 、1つしか指定されなければ、同じファイル名がローカルとリモートの両方で 使われます。これはローカル・ファイル名を指定しなければ、 リモート・ファイル/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が返され、エ[email protected]

メソッド

特に記述がなければ、全てのメソッドは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という名前のディレクトリを作成します。RECURSEtrueであれば、 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::FTPNet::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 <[email protected]>

参考資料

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 <[email protected]> - 再帰的にディレクトリを作るという提案に対して

Nathan Torkington <[email protected]> - ドキュメントでのいくつかの入力に対して

Roderick Schertler <[email protected]> - いくつかの入力に対して

著作権(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.


$Id: FTP.pod,v 1.2 2011/01/27 13:15:11 iwai Exp $