303 lines
8.5 KiB
Groff
303 lines
8.5 KiB
Groff
.\" This source code is a product of Sun Microsystems, Inc. and is provided
|
|
.\" for unrestricted use provided that this legend is included on all tape
|
|
.\" media and as a part of the software program in whole or part. Users
|
|
.\" may copy or modify this source code without charge, but are not authorized
|
|
.\" to license or distribute it to anyone else except as part of a product or
|
|
.\" program developed by the user.
|
|
.\"
|
|
.\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC.
|
|
.\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY
|
|
.\" OF SUCH SOURCE CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT
|
|
.\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND. SUN MICROSYSTEMS, INC. DISCLAIMS
|
|
.\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED
|
|
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN
|
|
.\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT,
|
|
.\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
|
.\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY.
|
|
.\"
|
|
.\" This source code is provided with no support and without any obligation on
|
|
.\" the part of Sun Microsystems, Inc. to assist in its use, correction,
|
|
.\" modification or enhancement.
|
|
.\"
|
|
.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
|
|
.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
|
|
.\" SOURCE CODE OR ANY PART THEREOF.
|
|
.\"
|
|
.\" Sun Microsystems, Inc.
|
|
.\" 2550 Garcia Avenue
|
|
.\" Mountain View, California 94043
|
|
.\"
|
|
.\" Copyright (c) 1991 Sun Microsystems, Inc.
|
|
.\"
|
|
.\" @(#) dlopen.3 1.6 90/01/31 SMI
|
|
.\" %FreeBSD: src/lib/libc/gen/dlopen.3,v 1.8.2.7 2001/12/14 18:33:51 ru Exp %
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" WORD: directed acyclic graph 有向非巡回グラフ
|
|
.Dd September 24, 1989
|
|
.Os
|
|
.Dt DLOPEN 3
|
|
.Sh 名称
|
|
.Nm dlopen , dlsym , dlerror , dlclose
|
|
.Nd 動的リンカへのプログラムのインタフェース
|
|
.Sh ライブラリ
|
|
.Lb libc
|
|
.Sh 書式
|
|
.In dlfcn.h
|
|
.Ft void *
|
|
.Fn dlopen "const char *path" "int mode"
|
|
.Ft void *
|
|
.Fn dlsym "void *handle" "const char *symbol"
|
|
.Ft const char *
|
|
.Fn dlerror "void"
|
|
.Ft int
|
|
.Fn dlclose "void *handle"
|
|
.Sh 解説
|
|
これらの関数は、動的リンカサービスに対する単純なプログラムの
|
|
インタフェースを提供します。
|
|
プログラムのアドレス空間に新しい共有オブジェクトを追加する操作、
|
|
共有オブジェクトが定義するシンボルのアドレス結合を取得する操作、
|
|
および共有オブジェクトを使用する必要がなくなったときに
|
|
それを除去する操作が提供されています。
|
|
.Pp
|
|
.Fn dlopen
|
|
は、
|
|
.Fa path
|
|
内の共有オブジェクトへのアクセスを提供し、
|
|
.Fn dlsym
|
|
と
|
|
.Fn dlclose
|
|
の呼び出しにおいて、オブジェクトを後で参照するために使用可能な
|
|
記述子を返します。
|
|
.Fn dlopen
|
|
を呼び出す前に
|
|
.Fa path
|
|
がアドレス空間内になかった場合はアドレス空間に配置されます。
|
|
この方法で、オブジェクトが
|
|
初めてアドレス空間にロードされるとき、関数
|
|
.Fn _init
|
|
が存在すればそれが動的リンカによって呼び出されます。
|
|
先の
|
|
.Fn dlopen
|
|
呼び出しでアドレス空間内に
|
|
.Fa path
|
|
が既に配置されている場合、2 度目は追加されません。
|
|
しかし、
|
|
.Fa path
|
|
上での
|
|
.Fn dlopen
|
|
操作の参照カウント値は管理されます。
|
|
.Fa path
|
|
に指定されたものが NULL ポインタであれば、プロセスの
|
|
メイン実行可能モジュールへの参照として解釈されます。
|
|
.Fa mode
|
|
は、ロードされたオブジェクトからの外部関数への参照が、
|
|
どのようにその参照先と結合するか、その方法を制御します。
|
|
これには次の値のうちの 1 つが含まれていなくてはなりません。
|
|
おそらくは、後で述べる追加フラグとの OR をとった値に
|
|
なるでしょう。
|
|
.Bl -tag -width RTLD_LAZYX
|
|
.It Dv RTLD_LAZY
|
|
外部関数への参照はそれぞれ関数が最初に呼び出されるときに解決されます。
|
|
.It Dv RTLD_NOW
|
|
外部関数への参照はすべて
|
|
.Fn dlopen
|
|
によってただちに結合されます。
|
|
.El
|
|
.Pp
|
|
.Dv RTLD_LAZY
|
|
は、効率を良くするという理由で一般的に好ましいです。しかし、
|
|
.Fn dlopen
|
|
を呼び出している間に未定義シンボルを確実に発見するためには
|
|
.Dv RTLD_NOW
|
|
が便利です。
|
|
.Pp
|
|
次のフラグの 1 つを OR をとって
|
|
.Fa mode
|
|
引数の中に含めることができます。
|
|
.Bl -tag -width RTLD_GLOBALX
|
|
.It Dv RTLD_GLOBAL
|
|
この共有オブジェクトから得られるシンボルおよび
|
|
必要とされるオブジェクトの有向非巡回グラフ (DAG) が、
|
|
その他すべての共有オブジェクトからの未解決の参照を
|
|
解決するために利用可能になります。
|
|
.It Dv RTLD_LOCAL
|
|
この共有オブジェクトから得られるシンボルおよび
|
|
必要とされるオブジェクトの有向非巡回グラフ (DAG) が、
|
|
同一の共有オブジェクトからの未解決の参照を
|
|
解決するために利用可能になります。
|
|
こちらがデフォルトの動作ですが、このフラグを用いて
|
|
明示的に指定することができます。
|
|
.El
|
|
.Pp
|
|
.Fn dlopen
|
|
は、処理が失敗すると NULL ポインタを返し、
|
|
.Fn dlerror
|
|
で問い合わせできるエラー状態を設定します。
|
|
.Pp
|
|
.Fn dlsym
|
|
は、
|
|
.Fa symbol
|
|
が
|
|
.Fa handle
|
|
で識別される共有オブジェクト内で
|
|
発生したときと同様に、ヌル文字で終了する文字列
|
|
.Fa symbol
|
|
で記述されたシンボルのアドレス結合を返します。
|
|
.Fn dlopen
|
|
によってアドレス空間に追加されたオブジェクトによってエクスポートされる
|
|
シンボルは、
|
|
.Fn dlsym
|
|
呼び出しを通してのみアクセス可能です。
|
|
このようなシンボルは、オブジェクトがロードされる際に、すでに
|
|
アドレス空間に存在しているシンボルの定義に置き換わるものでは
|
|
ありませんし、通常の動的リンク参照を満たすために利用可能な
|
|
ものでもありません。
|
|
.Pp
|
|
.Fn dlsym
|
|
が特別な
|
|
.Fa handle
|
|
.Dv NULL
|
|
を使用して呼び出された場合は、
|
|
そのハンドルは呼び出しがされている実行ファイルあるいは
|
|
共有オブジェクトへの参照として解釈されます。このため、
|
|
共有オブジェクトは自分自身の持つシンボルを
|
|
参照できるのです。
|
|
.Pp
|
|
.Fn dlsym
|
|
が特別な
|
|
.Fa handle
|
|
.Dv RTLD_DEFAULT
|
|
を使用して呼び出された場合は、オブジェクトが
|
|
ロードされる際に未定義のシンボルを解決するために
|
|
使用されるアルゴリズムに従ってシンボルを探索します。
|
|
探索されるオブジェクトは次のように書かれた順番になります。
|
|
.Bl -enum
|
|
.It
|
|
参照しているオブジェクト自身 (あるいは
|
|
.Fn dlsym
|
|
への呼び出しがされているオブジェクト)。ただし、オブジェクトが
|
|
.Xr ld 1
|
|
に対して
|
|
.Fl Wsymbolic
|
|
オプションを使用してリンクされた場合。
|
|
.It
|
|
プログラムの起動時にロードされていた全オブジェクト
|
|
.It
|
|
.Fn dlopen
|
|
経由でロードされた全オブジェクト。これらのオブジェクトは、
|
|
参照を行っているオブジェクトも含んだ、必要とされるオブジェクトの
|
|
有向非巡回グラフに存在します。
|
|
.It
|
|
.Dv RTLD_GLOBAL
|
|
フラグを
|
|
.Fa mode
|
|
引数で設定して呼び出した
|
|
.Fn dlopen
|
|
経由でロードされた全オブジェクト
|
|
.El
|
|
.Pp
|
|
.Fn dlsym
|
|
が特別な
|
|
.Fa handle
|
|
.Dv RTLD_NEXT
|
|
を使用して呼び出された場合、シンボルの検索は、
|
|
.Fn dlsym
|
|
呼び出しを発行した後でロードされた共有オブジェクトに制限されます。
|
|
そのため、メインプログラムからこの関数が呼び出された場合、
|
|
すべての共有ライブラリが検索されます。この関数が共有ライブラリから
|
|
呼び出された場合、
|
|
その共有ライブラリより後でロードされる共有ライブラリすべてが
|
|
検索されます。
|
|
.Dv RTLD_NEXT
|
|
はライブラリ関数を包み込むラッパを実装するのに便利です。
|
|
例えば、ラッパ関数
|
|
.Fn getpid
|
|
がある場合、関数内で
|
|
.Li dlsym(RTLD_NEXT, \&"getpid\&")
|
|
を使用すれば
|
|
.Dq 本物の
|
|
.Fn getpid
|
|
にアクセスできるでしょう。
|
|
.Pp
|
|
シンボルが見つけられなかった場合、
|
|
.Fn dlsym
|
|
は null ポインタを返し、エラー状態を設定します。
|
|
エラー状態は
|
|
.Fn dlerror
|
|
を使用して問い合わせることができます。
|
|
.Pp
|
|
.Fn dlerror
|
|
は、
|
|
.Fn dlopen ,
|
|
.Fn dlsym ,
|
|
または
|
|
.Fn dlclose
|
|
呼び出しの間に発生した最後のエラーを記述する
|
|
ヌル文字で終了する文字列を返します。
|
|
このようなエラーが発生していない場合、
|
|
.Fn dlerror
|
|
は NULL ポインタを返します。
|
|
.Fn dlerror
|
|
を呼び出すたびに、エラー指示がリセットされます。
|
|
そのため、後の呼び出しが先の呼び出しの直後にくるような
|
|
.Fn dlerror
|
|
呼び出しを行った場合、後の呼び出しでは必ず NULL ポインタが
|
|
返ってきます。
|
|
.Pp
|
|
.Fn dlclose
|
|
は
|
|
.Fa handle
|
|
が参照する共有オブジェクトへの参照を削除します。
|
|
参照カウント値が減らされ 0 になると、そのオブジェクトはアドレス空間から
|
|
削除され
|
|
.Fa handle
|
|
は無効になります。この方法で共有オブジェクトを除去する直前に、
|
|
.Fn _fini
|
|
関数がこのオブジェクトで定義されている場合には
|
|
それを呼び出します。
|
|
.Fn dlclose
|
|
は、処理が成功すると値 0 を返します。
|
|
そうでない場合は -1 を返し、
|
|
エラー状態を設定します。エラー状態は
|
|
.Fn dlerror
|
|
で問い合わせできます。
|
|
.Pp
|
|
オブジェクトに固有の関数
|
|
.Fn _init
|
|
と
|
|
.Fn _fini
|
|
は、引数なしに呼び出され、戻り値は期待されていません。
|
|
.Sh 注
|
|
ELF 実行可能ファイルの場合、
|
|
ファイル中で定義されているシンボルを
|
|
.Fn dlsym
|
|
で見えるようにするには
|
|
.Xr ld 1
|
|
に対して
|
|
.Fl export-dynamic
|
|
オプションを使用してリンクを行う必要があります。
|
|
.Pp
|
|
以前の実装では、C 言語からコンパイルしたオブジェクトコードと
|
|
シンボルの互換性を持たせることができるように、
|
|
外部シンボルにはすべてアンダースコアを先頭につける必要が
|
|
ありました。現在でも、
|
|
C 言語のコンパイラに対して (非推奨ですが)
|
|
.Fl aout
|
|
オプションを使用した場合には当てはまります。
|
|
.Sh エラー
|
|
.Fn dlopen
|
|
と
|
|
.Fn dlsym
|
|
は、エラーが発生した場合には NULL ポインタを返します。
|
|
.Fn dlclose
|
|
は処理が成功すると 0 を返し、
|
|
エラーが発生した場合は -1 を返します。
|
|
エラーが検出されるたびに、エラーの詳細を説明するメッセージが
|
|
.Fn dlerror
|
|
呼び出しによって取り出せます。
|
|
.Sh 関連項目
|
|
.Xr ld 1 ,
|
|
.Xr rtld 1 ,
|
|
.Xr dladdr 3 ,
|
|
.Xr link 5
|