日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
DLOPEN(3) FreeBSD ライブラリ関数マニュアル DLOPEN(3)
名称
dlopen, fdlopen, dlsym, dlfunc, dlerror, dlclose -- 動的リンカへのプログ
ラムのインタフェース
ライブラリ
標準 C ライブラリ (libc, -lc)
書式
#include <dlfcn.h>
void *
dlopen(const char *path, int mode);
void *
fdlopen(int fd, int mode);
void *
dlsym(void * restrict handle, const char * restrict symbol);
dlfunc_t
dlfunc(void * restrict handle, const char * restrict symbol);
char *
dlerror(void);
int
dlclose(void *handle);
解説
これらの関数は、動的なリンカのサービスへの簡単なプログラムのインタフェー
スを提供しています。プログラムのアドレス空間に新しい共有オブジェクトを追
加し、そのようなオブジェクトによって定義されるシンボルのアドレスのバイン
ドを取得するために、そしてそれらの使用がもはや必要ではないとき、そのよう
なオブジェクトを削除するために、操作は、提供されています。
dlopen() 関数は、path の共有オブジェクトへのアクセスを提供し、dlsym() と
dlclose() への呼び出しでオブジェクトに後で参照のために使用することができ
る記述子を返します。path が dlopen() への呼び出しの前にアドレス空間にな
かったなら、それは、アドレス空間に置かれます。オブジェクトがこの方法でア
ドレス空間に最初にロードされるとき、その関数 _init() は、もしあるなら、動
的なリンカによって呼び出されます。path が、既に dlopen() への以前の呼び出
しでアドレス空間に置かれていたなら、それは、2 度目に追加されませんが、
path の dlopen() 操作の参照カウントは、維持されます。path に供給される
NULL ポインタは、プロセスの主要な実行形式への参照として解釈されます。mode
引数は、ロードされたオブジェクトから外部関数の参照がそれらの参照にバイン
ドされる方法を制御します。それは、たぶん後で説明される追加のフラグで論理
和 (OR) される、次の値の 1 つを含んでいなければなりません:
RTLD_LAZY 各外部関数の参照は、関数が最初に呼び出されるとき、解決されま
す。
RTLD_NOW すべての外部関数の参照は、dlopen() によって直ちにバインドされ
ます。
RTLD_LAZY は、通常、効率の理由で好まれます。しかしながら、RTLD_NOW は、あ
らゆる未定義のシンボルが dlopen() への呼び出しの間に発見されることを保証
するために役に立ちます。
次のフラグの 1 つは、mode 引数に論理和 (OR) されます:
RTLD_GLOBAL この共有オブジェクトのシンボルと必要とされるオブジェクトの
有向非巡回グラフ (DAG) は、すべての他の共有オブジェクトの
未定義の参照を解決するために利用可能となります。
RTLD_LOCAL この共有オブジェクトのシンボルと必要とされるオブジェクトの
DAG は、同じ DAG の他のオブジェクトだけの未定義な参照を解
決するために利用可能となります。これは、デフォルトですが、
それは、このフラグで明示的に指定されます。
RTLD_TRACE 設定されるとき、動的リンカは、この共有オブジェクトによって
必要とされるすべてのオブジェクトをロードした後に終了し、す
べてのオブジェクトの絶対的なパス名を含む要約を標準出力に印
刷 (表示) します。このフラグで、dlopen() は、エラーの場合
のみ呼び出し側に返ります。
RTLD_NODELETE dlclose() でロードされたオブジェクトのアンロードを防止しま
す。同じ振る舞いは、静的なリンカ ld(1) の -z nodelete オプ
ションによって要求されます。
RTLD_NOLOAD プロセスアドレス空間のオブジェクトのための有効ハンドルが既
にロードされているなら、それが返され、そうでなければ、NULL
が返されます。オブジェクトを見つけるためにプロモーションに
適用される、他のモードフラグが、指定されます。
dlopen() が失敗するなら、それは、NULL ポインタを返し、dlerror() で問い合
わされるエラー条件を設定します。
fdlopen() 関数は、dlopen() に似ていますが、アドレス空間にオブジェクトを
ロードするために必要とされるファイル操作のために使用される、ファイル記述
子の引数 fd を取ります。ファイル記述子 fd は、実行の結果にかかわらず関数
によってクローズさませんが、複写されたファイル記述子は、クローズされま
す。これは、lockf(3) ロックが渡された記述子で保持されるなら、重要であるか
もしれません。fd 引数 -1 は、dlopen() への name 引数のに対する NULL 値に
似ている、プロセスのメインの実行形式を参照していると解釈されます。シンボ
リックリンクか、または名前が変更される競合を防ぐために、ロードされたオブ
ジェクトで追加のチェックを行なう必要のあるコードによって fdlopen() 関数を
使用することがでます。
dlsym() 関数は、handle によって識別される共有オブジェクトに存在するので、
ヌル文字で終了する文字列 symbol で記述されたシンボルのアドレスのバイン
ディングを返します。dlopen() によってアドレス空間に追加されたオブジェクト
によってエクスポートされたシンボルは、dlsym() への呼び出しを通してのみア
クセスできます。そのようなシンボルは、オブジェクトがロードされるとき、ア
ドレス空間にすでに存在する、それらのシンボルのあらゆる定義を入れ換えず、
それらは、通常の動的なリンク参照を満たすように利用可能でもありません。
dlsym() が特別な handle NULL で呼び出されるなら、呼び出しが行われる実行形
式または共有オブジェクトへの参照として解釈されます。したがって、共有オブ
ジェクトは、それ自体のシンボルを参照することができます。
dlsym() が特別な handle RTLD_DEFAULT で呼び出されるなら、シンボルのための
検索は、オブジェクトがロードされるとき、未定義のシンボルを解決するために
使用されるアルゴリズムに従います。検索されるオブジェクトは、与えられた順
序で、次の通りです:
1. そのオブジェクトが ld(1) への -Bsymbolic オプションを使用してリンク
されたなら、参照オブジェクトそれ自体 (または、dlsym() への呼び出しが
行われるオブジェクト)。
2. プログラムの起動にロードされたすべてのオブジェクト。
3. mode 引数に設定される RTLD_GLOBAL フラグをつけて dlopen() によって
ロードされるすべてのオブジェクト。
4. また、参照オブジェクトを含んでいる必要とされるオブジェクトの DAG で
ある dlopen() によってロードされるすべてのオブジェクト。
dlsym() が特別な handle RTLD_NEXT で呼び出されるなら、シンボルのための検
索は、dlsym() への呼び出しを発行しているものの後にロードされた共有オブ
ジェクトに制限されます。したがって、関数が main プログラムから呼び出され
るなら、すべての共有ライブラリが検索されます。それが、共有ライブラリから
呼び出されるなら、すべてのその後の共有ライブラリが検索されます。RTLD_NEXT
は、ライブラリ関数のまわりのラッパを実装するために役に立ちます。例えば、
ラッパ関数 getpid() は、dlsym(RTLD_NEXT, "getpid") を付けて ``real'' (実
際の) getpid() にアクセスできました。(実際、下記の dlfunc() インタフェー
スは、getpid() が、データオブジェクトではなく、関数であるので、使用される
べきです。)
dlsym() が特別な handle RTLD_SELF を付けて呼び出されるなら、シンボルのた
めの検索は、dlsym() への呼び出しを発行する共有オブジェクトとその後にロー
ドされた、それらの共有オブジェクトに制限されます。
dlsym() 関数は、シンボルを見つけることができないなら、NULL ポインタを返
し、dlerror() で問い合わされるエラー状態を設定します。
dlfunc() 関数は、dlsym() の振る舞いのすべてを実装しますが、コンパイラの診
断を誘発せずに関数ポインタにキャスト (cast) することができる返りタイプが
あります。(dlsym() 関数は、データポインタを返します。C 標準では、データと
関数ポインタのタイプの間の変換は、未定義です。いくつかのコンパイラと
lint(1) ユーティリティは、そのようなキャスト (cast) に関して警告します。)
dlfunc() の正確な返りタイプは、特定されていません。アプリケーションは、そ
れを適切な関数ポインタのタイプにキャスト (cast) しなければなりません。
dlerror() 関数は、dlopen(), dladdr(), dlinfo(), dlsym(), dlfunc() または
dlclose() への呼び出しの間に起こった最後のエラーを記述しているヌル文字で
終了する文字列を返します。そのようなエラーが起こらなかったなら、dlerror()
は、NULL ポインタを返します。dlerror() への各呼び出しで、エラーの指示は、
リセットされます。したがって、2 番目の呼び出しが最初の直後に続いていると
ころで、dlerror() への 2 つの呼び出しの場合に、2 番目の呼び出しには、常に
NULL ポインタを返します。
dlclose() 関数は、handle によって参照される共有オブジェクトへの参照を削除
します。参照カウントが 0 に減少するなら、オブジェクトは、アドレス空間から
削除され、handle は、無効にされます。このような方法で、共有オブジェクトを
削除する直前に、動的なリンカは、そのような関数がオブジェクトによって定義
されるなら、オブジェクトの _fini() 関数を呼び出します。dlclose() が成功す
るなら、0 の値を返します。そうでなければ、-1 を返し、dlerror() で問い合わ
せすることができすrエラー状態を設定します。
オブジェクト固有の関数 _init() と _fini() は、引数なしで呼び出され、値を
返すことは期待されていません。
注
ELF 実行形式は、dlsym() に、見えるようなる実行形式で定義されたシンボルの
ために ld(1) への -export-dynamic オプションを使用してリンクされる必要が
あります。
他の ELF プラットフォームは、dlopen() と他の関数を提供するためにライブラ
リ ``libdl'' とリンクすることを必要とします。FreeBSD は、ライブラリとリン
クすることを必要としませんが、互換性のためにそれをサポートしています。
以前の実装で、C 言語からコンパイルされたオブジェクトコードとのシンボルの
互換性を得るために、すべての外部のシンボルの先頭に下線を追加する必要があ
りました。これは、いまだに、C 言語コンパイラに (時代遅れの) -aout オプ
ションを使用するときです。
エラー
dlopen(), fdlopen(), dlsym(), と dlfunc() 関数は、エラーの場合に NULL ポ
インタを返します。dlclose() 関数は、成功すると、0 を返し、エラーが起こっ
たなら、-1 を返します。エラーが検出されるときはいつでも、それを詳述してい
るメッセージを dlerror() への呼び出しによって取り出すことができます。
関連項目
ld(1), rtld(1), dladdr(3), dlinfo(3), link(5)
FreeBSD 11.2 July 7, 2017 FreeBSD 11.2