NAME
      SiMH::HTTPmirror - FTPによるミラーリング

SYNOPSIS
      use SiMH::FTPmirror;

      %info = ();
      SiMH::FTPmirror::local_to_remote($rhost,$userid,$passwd,\%info)
          or die($info{'//error'});

DESCRIPTION
      FTPによるミラーリング機能を提供する。
      (現在の版はローカルからリモート方向のミラーリング機能のみ提供)

      以下のサブルーチンを使用することができる。

    local_to_remote(《RHOST》,《USER》,《PASS》,《INFO》,《OPTION》...)
      ローカルからリモート方向のミラーリングを行う。
      サブディレクトリの配下も再帰的にミラーリングする。
      《RHOST》にはリモートマシンのホスト名またはIPアドレスを指定する。
      《USER》にはリモートマシンにFTPで接続するためのユーザIDを指定する。
      《PASS》にはリモートマシンにFTPで接続するためのパスワードを指定する。
      《INFO》にはミラーリング処理の内容を返すハッシュへのリファレンスを
      指定する。ハッシュにはファイル/ディレクトリのパス名をキーにして処理
      内容が以下の値で記録される。省略(undefの指定)してもよい。
        '*N' : ファイルを新規コピーした。
        '*U' : ファイルを更新コピーした。
        '*R' : ファイルを削除した。
        '*ND': ディレクトリを新規作成した。
        '*RD': ディレクトリを削除した。
      ここで、最初の1文字は、'O' が未処理を、'X' が処理済を意味する。
      なお、エラー終了時には、このハッシュの '//error' をキーとする要素に
      エラーメッセージ(文字列)が格納される。
      第5パラメタ以降にはオプションを key=>$value の形で指定できる。
      オプションとしては以下のようなものを受け付ける。
        ldir : ローカルマシンの対象ディレクトリ(既定値 '.')
        lopt : ローカルマシンのlsコマンドオプション(既定値 '-alTR')
        rdir : リモートマシンの対象ディレクトリ(既定値 '.')
        ropt : リモートマシンのLISTコマンドオプション(既定値 '-alTR')
        rtz  : リモートマシンのFTPサーバのタイムゾーン(既定値 'GMT')
        exbn : 除外ファイル名(basename)の正規表現(既定値 '~$|,v$')
        expn : 除外ファイル名(パス名)の正規表現(既定値 undef)
        retry : エラーが発生した際のリトライ回数(既定値 3)
        no_copy : この値が真ならミラーリング処理はしないで、《INFO》の情
               報を生成するだけで終了する。
        debug_trace : デバッグ用トレースの出力レベル(既定値:0)。
      上記以外のオプションは、SiMH::FTPクラスのコンストラクタ new() に渡
      しているので、それが受け付ける様々なオプションも指定できる。
      全ての処理が成功した時には真(1)が、エラー時には偽(undef)が返される。

    remote_to_local(《RHOST》,《USER》,《PASS》,《INFO》,《OPTION》...)
      リモートからローカル方向のミラーリングを行う。
      転送方向が異なるだけで、パラメタ等は local_to_remote と同じ。

NOTE
      リモートマシンのファイル情報の取得にはFTPのLISTコマンドを利用してい
      るが、それが返すデータのフォーマットはFTPの仕様としては規定されてな
      いので、FTPサーバの仕様に依存している。UNIX系OSの多くの場合、それは
      /bin/ls -l コマンドの出力と同一になっている。本プログラムはそれを前
      提としてデータを解析している。また、
        更新日時の情報を秒単位まで取得するため、および、
        サブディレクトリのファイルの情報を再帰的に取得するため、
      オプション -alTR を指定している。従って、FTPサーバのLISTコマンドが
      このオプションをサポートしているのが望ましい。このオプションはBSD系
      仕様であり、リモートマシンのOSがlinuxの場合には、オプションを
      -alR --full-time に変更すればよいと思われる(未確認)。
      なお、-T (更新日時の情報を秒単位まで取得)オプションが未サポートの場
      合には、サブディレクトリを対象にしてLISTコマンドを実行して情報を取
      得するようにしている。これは所要時間が掛かるが同じ結果が得られる。
      -R (サブディレクトリのファイルの情報を再帰的に取得)オプションが未サ
      ポートの場合には、不完全な時刻情報で判定するようにしている。この判
      定は不正確で、完全なミラーリングができない可能性がある。

      ローカルマシンのファイル情報の取得は /bin/ls -alTR コマンドで行って
      いる。このオプションについてはリモートマシンの場合と同様。

      FTPのLISTコマンドが返す更新日時の情報に関しては、タイムゾーンについ
      ても規定されていない。FTPサーバの仕様/設定に依存し、ローカルマシン
      からその設定を変えることはできない。そのため、本プログラムでは、
      ローカルマシンのファイル情報を取得する際に、FTPサーバと同一のタイム
      ゾーンに合わせて処理するようにしている。既定値は GMT になっているの
      で、必要に応じて変更する必要がある。その値はローカルマシンで有効な
      ものである必要がある。

      漢字や記号、空白、制御コード等を含むファイル名は想定していないので、
      含まれていると正常に動作ない可能性が高い。日本語ロケールの使用によ
      り更新日時の情報に漢字が含まれている場合も同様。

COPYRIGHT
      Copyright 2003, HIRANO Kiyoshi <hirano-k@tokyo.email.ne.jp>.

      このソフトウェアのソースコードおよびバイナリー形式の利用、複製、
      再配布を、変更の有無に関わらず、以下の3つの条件の下で許可します。

      1. ソースコードの再配布においては、上記著作権表示および許諾条件の
         列挙を含めること。

      2. バイナリー形式の再配布においては、上記著作権表示および許諾条件
         の列挙を、配布物に附属した文書等に記載すること。

      3. このソフトウェアの提供に際して、HIRANO Kiyoshi は一切の保証を
         しません。 理由のいかんを問わず、このソフトウェアの利用、複製、
         再配布に伴い発生したいかなる損害も補償しません。