DYNALOADER(3)            USER COMMANDS              DYNALOADER(3)



NAME
     DynaLoader - C ライブラリを Perl のコードに動的ロードする

     dl_error()、dl_findfile()、dl_expandspec()、dl_load_file()、
     dl_find_symbol()、dl_undef_symbols()、dl_install_xsub()、
     boostrap() - DynaLoader モジュールで使用されるルーティン

SYNOPSIS
         require DynaLoader;
         push (@ISA, 'DynaLoader');


DESCRIPTION
     このモジュールは、多くのプラットホームで利用可能な、動的リン
     クの仕組みとの標準的で一般的なインタフェースを定義するもので
     す。 その当初の目的は、Perl モジュールの自動的な動的ロード
     をインプリメントすることです。

     DynaLoader は、とても単純で高レベルのインタフェースとなるよ
     う設計され、このインタフェースは、SunOS、HP-UX、NeXT、Linux、
     VMS その他のプラットホームの要求をカバーするため、十分かつ一
     般的なものです。

     このインタフェースが、OS/2 や NT などの要求もカバーし、(実行
     時に ld -A を使って) 擬似的な動的リンクを許すものとなること
     が望まれます。

     このドキュメントは、新しいプラットホームの DynaLoader をイン
     プリメントする方のための仕様としてと、アプリケーションで直接
     DynaLoader を使いたい方のためのガイドとして提供されるもので
     す。

     DynaLoader 自身は、Perl から C への「グルー」を提供するもの
     ではありませんから、Perl 以外のライブラリをアクセスするもの
     としては実用的なものでないことは確かです。 たとえば、C のラ
     イブラリ関数を呼んだり、引数を与える機能は用意されていません。
     将来、開発されるであろうグルーが、個別の動的ロードモジュール
     としてインプリメントされるものと見込んでいます。

     DynaLoader インタフェースの要約

       @dl_library_path
       @dl_resolve_using
       @dl_require_symbols
       $dl_debug
                                                    インプリメント言語:
       bootstrap($modulename)                               Perl
       @filepaths = dl_findfile(@names)                     Perl







Perl module manpages Last change: Release 5.0 Patchlevel 00     1






DYNALOADER(3)            USER COMMANDS              DYNALOADER(3)



       $libref  = dl_load_file($filename)                   C
       $symref  = dl_find_symbol($libref, $symbol)          C
       @symbols = dl_undef_symbols()                        C
       dl_install_xsub($name, $symref [, $filename])        C
       $message = dl_error                                  C


     @dl_library_path
         dl_findfile() がライブラリなどを検索する標準/デフォルト
         のディレクトリのリストです。 $dl_library_path[0]、[1]、
         ... の順にディレクトリが検索されます。

         @dl_library_path は、Configure ($Config{'libpth'}) で決
         定される「通常の」ディレクトリ (/usr/lib など) のリスト
         が初期値となります。 これは、多くのプラットホームの間で
         の可搬性を保つようにしておくべきです。

         @dl_library_path はまた、(SunOS の LD_LIBRARY_PATH のよ
         うな) 実行時の環境変数から決まるディレクトリも初期値とし
         て取り込むべきです。

         初期化の後は、@dl_library_path は、dl_findfile() を呼ぶ
         前に、アプリケーション側で pushunshift を使って操作
         できます。 検索時間を短縮したり、「通常の」ディレクトリ
         にあるものと同じ名前のライブラリをオーバライドしたりする
         ため、検索順序が前の方になるように、ディレクトリを付け加
         えるために unshift を使うことができます。

         dl_load_file() が呼び出すロード関数は、絶対パスを必要と
         するかもしません。 dl_findfile() 関数と @dl_library_path
         は、ロードしたいライブラリ/オブジェクトを探すために使う
         ことができ、その絶対パスを返します。

     @dl_resolve_using
         後に load_file() の呼び出しで生成される可能性のある、未
         定義シンボルを解決するために使うことができる追加のライブ
         ラリや他の共有オブジェクトのリストです。

         これは、依存ライブラリを自動的に扱うことのできない、いく
         つかのプラットホームでのみ必要となるものです。 たとえば、
         Perl の拡張ライブラリ Socket (auto/Socket/Socket.so) に
         は、ロードされたときに解決する必要のある多くのソケット関
         数へのリファレンスが含まれます。 多くのプラットホームで
         は、「依存する」ライブラリ (たとえば、/usr/lib/libsocket.so)
         がどこにあるかが自動的にわかるようになっています。 ごく
         少数のプラットホームで、依存するライブラリの位置を明示す
         る必要があるのです。 そのために、@dl_resolve_using を使
         ってください。

         使用例:

             @dl_resolve_using = dl_findfile('-lsocket');



Perl module manpages Last change: Release 5.0 Patchlevel 00     2






DYNALOADER(3)            USER COMMANDS              DYNALOADER(3)



     @dl_require_symbols
         動的ロードされるライブラリ/オブジェクトファイル内のシン
         ボル名のリストです。 いくつかの特定のプラットホームでの
         み必要となります。

     dl_error()
         構文:

             $message = dl_error();

         最後に DynaLoader 関数が出したエラーの、メッセージ内容で
         す。 UNIX の errno と同じく、エラーの後にうまく行った関
         数があっても、このメッセージをクリアすることはありません。

         インプリメンテーションの方では、他の関数でエラーが起こっ
         たら、できる限り早期に検出し、あとで参照できるように、対
         応するメッセージを保存するようにしなくてはなりません。
         これは、(SunOS のような) いくつかのプラットホームで、エ
         ラーメッセージが瞬時に無くなってしまう問題を避けることに
         なります (たとえば、dlerror())。

     $dl_debug
         $dl_debug を真に設定すると、内部のデバッグメッセージが、
         有効になります。 現在、$dl_debug の設定は、DynaLoader
         の Perl 側にだけ影響を与えます。 これらのメッセージは、
         アプリケーションの開発者が、DynaLoader の使用上の問題を
         解決する手助けするものでなければなりません。

         $ENV{'PERL_DL_DEBUG'} が定義されていれば、$dl_debug はこ
         れによって設定されます。

         -DDEBUGGING フラグを付けて Perl を構築したときには、
         DynaLoader の開発者/移植者には、同様のデバッグ変数が、C
         のコードに追加され (dlutils.c を参照)、有効となります。
         これも、PERL_DL_DEBUG 環境変数によって設定されます。 1
         で最低限の情報が得られ、大きくすることにより情報が増えま
         す。

     dl_findfile()
         構文:

             @filepaths = dl_findfile(@names)

         ロード可能なファイルの一般的なファイル名前と、場合によっ
         ては、ディレクトリも与えて、(サフィクスを含む) フルパス
         名を決定します。 デフォルトでは、@dl_library_path のデ
         ィレクトリを検索し、ファイルが見つからなかった場合には、
         空リストを返します。

         名前は、さまざまな、プラットホームに依存しない形式で指定
         することができます。 -lname という形式の名前は、.* をそ
         のプラットホームのための適切なサフィクスとして、libname.*



Perl module manpages Last change: Release 5.0 Patchlevel 00     3






DYNALOADER(3)            USER COMMANDS              DYNALOADER(3)



         に変換されます。

         名前に、適切なプリフィクスやサフィクスが付いていないとき
         には、プラットホームに合わせて、プリフィクスやサフィクス
         を組み合わせを試しながら、対応するファイルを探します: 
         "$name.o"、"lib$name.*"、"$name"

         @name にディレクトリが含まれる場合には、@dl_library_path
         の前にそちらで検索を行ないます。 ディレクトリは、-Ldir
         という形で示すことができます。 その他の形式の名前は、フ
         ァイル名として検索されます。

         -Ldir と -lname という形式の引数を使うことを推奨します。

         例:

             @dl_resolve_using = dl_findfile(qw(-L/usr/5lib -lposix));


     dl_expandspec()
         構文:

             $filepath = dl_expandspec($spec)

         VMS のような、変わったシステムでは、ファイルのシンボル名
         を扱うために特別なファイル名が必要になります (VMS の論理
         名です)。

         こういったシステムをサポートするために、dl_expandspec()
         関数は、dl_*.xs 内か、DynaLoader.pm 内の自動ロード可能な
         dl_expandspec() 関数として追加されるコードとしてインプリ
         メントすることができます。 詳しくは、DynaLoader.pm を参
         照してください。

     dl_load_file()
         構文:

             $libref = dl_load_file($filename)

         $filename を動的にロードします。 $filename は、共有オブ
         ジェクトかライブラリのパスでなければなりません。 多少解
         りづらい「ライブラリリファレンス」が、ロードされたオブジ
         ェクトのためのハンドルとして返されます。 エラー時には、
         undef が返されます。

         (SunOS や HP-UX のように、ロードされたオブジェクトのため
         のハンドルを用意しているシステムでは、$libref は、そのハ
         ンドルになります。 その他のシステムでは、$libref は、
         $filename か、$filename を含むバッファへのポインタになる
         のが普通です。 アプリケーション側では、いかなる方法でも
         $libref を調べることも、変更することもしてはなりません。)




Perl module manpages Last change: Release 5.0 Patchlevel 00     4






DYNALOADER(3)            USER COMMANDS              DYNALOADER(3)



         これが、実際に作業を行なう関数です。 必要ならば、その時
         点の @dl_require_symbols と @dl_resolve_using の値を使う
         ようにしなければなりません。

             SunOS: dlopen($filename)
             HP-UX: shl_load($filename)
             Linux: dld_create_reference(@dl_require_symbols); dld_link($filename)
             NeXT:  rld_load($filename, @dl_resolve_using)
             VMS:   lib$find_image_symbol($filename,$dl_require_symbols[0])


     dl_find_symbol()
         構文:

             $symref = dl_find_symbol($libref, $symbol)

         シンボル $symbol のアドレスか、見つからなければ undef を
         返します。 ターゲットシステムに、異なる型のシンボルを探
         すための独立した関数が存在するときには、dl_find_symbol()
         は、まず、関数シンボルを検索してから、他の型を探すように
         しておくべきです。

         アドレスを $symref に返す、厳密な方法は、現在定義されて
         いません。 $symref を dl_install_xsub() に渡すことがで
         き、内容が通じることだけが要求されています。

             SunOS: dlsym($libref, $symbol)
             HP-UX: shl_findsym($libref, $symbol)
             Linux: dld_get_func($symbol) and/or dld_get_symbol($symbol)
             NeXT:  rld_lookup("_$symbol")
             VMS:   lib$find_image_symbol($libref,$symbol)


     dl_undef_symbols()
         例:

             @symbols = dl_undef_symbols()

         load_file() の後で、未定義のままとなっているシンボル名の
         リストを返します。 不明なときには、() を返します。 お
         使いのプラットホームで、このための機構が用意されていなく
         ても、心配しないでください。 多くは、必要無いから用意し
         ていないのです。

     dl_install_xsub()
         構文:

             dl_install_xsub($perl_name, $symref [, $filename])

         $perl_name で示す名前の新しい Perl の外部サブルーティン
         を、これをインプリメントする関数へのポインタ $symref を
         使って生成します。 これは、単純に newXSUB() を直接呼ぶ



Perl module manpages Last change: Release 5.0 Patchlevel 00     5






DYNALOADER(3)            USER COMMANDS              DYNALOADER(3)



         だけです。 インストールされた関数へのリファレンスを返し
         ます。

         パラメータ $filename は、die() や caller() やデバッガが
         必要なときに、その関数のソースファイルを識別するために
         Perl が使います。 $filename が定義されていないときには、
         "DynaLoader" が使われます。

     boostrap()
         構文:

         bootstrap($module)

         これは、Perl での自動的な動的ロードの通常のエントリポイ
         ントです。

         これは、以下の動作を行ないます:

     +       @INC を検索することにより、auto/$module ディレクトリ
             の場所を特定します

     +       ロードするファイル名を決定するために dl_findfile()
             を使います

     +       ("boot_$module") を @dl_require_symbols に設定します

     +       存在すれば auto/$module/$module.bs を実行します (特
             に、現在のプラットホームでモジュールをロードするため
             に、必要なファイルを @dl_resolve_using に追加するた
             めに使われます)

     +       そのファイルをロードするために dl_load_file() を呼び
             ます

     +       dl_undef_symbols() を呼び、未定義のシンボルがあれば、
             警告を出します

     +       "boot_$module" のため、dl_find_symbol() を呼びます

     +       それを "${module}::bootstrap" としてインストールする
             ために dl_install_xsub() を呼びます

     +       モジュールをブートストラップするために
             &{"${module}::bootstrap"} を呼びます

AUTHOR
     このインタフェースは、(順不同で) Larry Wall, Robert Sanders,
     Dean Roehrich, Jeff Okamoto, Anno Siegel, Thomas Neumann,
     Paul Marquess, Charles Bailey 他の方の作業とコメントに基づい
     ています。

     Larry Wall は、エレガントな継承によるブートストラップの機構



Perl module manpages Last change: Release 5.0 Patchlevel 00     6






DYNALOADER(3)            USER COMMANDS              DYNALOADER(3)



     を設計し、それを使った最初の Perl 5 動的ローダをインプリメン
     トしました。

     Tim Bunce, 11 August 1994.



















































Perl module manpages Last change: Release 5.0 Patchlevel 00     7