.\" 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$
.Dd September 24, 1989
.Os FreeBSD
.Dt DLOPEN 3
.Sh 名称
.Nm dlopen, dlsym, dlerror, dlclose
.Nd 動的リンカへのプログラムのインタフェース
.Sh 書式
.Fd #include <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
がある場合、この関数が
動的リンカによって呼び出されます
(
.Ql _init
は C 言語で表現される名前です。
アセンブリ言語からは、名前は代わりに
.Ql __init
として現れます)。
.Fn dlopen
の
直前の呼び出しでアドレス空間内に
.Fa path
が既に配置されている場合、2 度めには追加されません。ただし、
.Fa path
についての
.Fn dlopen
操作の参照カウントは
維持されます。
.Fa path
のために指定された NULL ポインタは、プロセスの
メイン実行可能モジュールへのリファレンスとして解釈されます。
.Fa mode
は、ロード
されたオブジェクトからの外部関数参照が、その参照に結合される方法を
制御します。これには次の値の 1 つが入っている必要があります。
.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
が便利です。
.Fn dlopen
は、処理が失敗すると NULL ポインタを返し、
.Fn dlerror
で問い合わせできるエラー条件を設定します。
.Pp
.Fn dlsym
は、ナル文字で終わるキャラクタストリング
.Fa symbol
で記述されたシンボル
のアドレス結合を返します。
.Fa symbol
が
.Fa handle
で識別される共有オブジェクト内で
発生したときです。
.Fa symbol
は、シンボル名のアセンブリ言語表現であることに
注意してください。
C 言語シンボルのアセンブリ言語表現には、先頭に追加の
アンダースコアが入っています。たとえば、
C でのシンボル
.Ql foo
は、
アセンブリ言語でおよび
.Fn dlsym
への
.Fa symbol
引数では
.Ql _foo
として現れます。
.Fn dlopen
によってアドレス空間に追加された、オブジェクトによってエクスポート
されるシンボルは、
.Fn dlsym
の呼び出しによってのみアクセスできます。
このようなシンボルは、オブジェクトがロードされるときにアドレス空間内に既に
存在するシンボルの定義に取って代わることはなく、通常の動的リンク参照を
満足させるために利用できることもありません。
.Fa handle
の値として与えられた NULL ポインタは、
実行可能モジュールの参照として解釈されます。この実行可能
モジュールから
.Fn dlsym
の呼び出しが行われます。このように共有オブジェクト
は、専用のシンボルを参照できます。
.Fn dlsym
は、シンボルが見つからない場合は
NULL ポインタを返し、エラー条件を設定します。エラー条件は
.Fn dlerror
で照会できます。
.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 dlerror
は、
.Fn dlopen ,
.Fn dlsym ,
または
.Fn dlclose
の呼び出しの間に発生した最後のエラーを記述する
ナル文字で終わるキャラクタストリングを返します。
このようなエラーが発生していない場合、
.Fn dlerror
は NULL ポインタを返します。
.Fn dlerror
を呼び出すたびに、エラー指示がリセットされます。
ですから、2 番めの呼び出しが最初の呼び出しの直後に続く
.Fn dlerror
呼び出しの 2 つのケースでは、
2 番めの呼び出しは必ず NULL ポインタを返します。
.Pp
.Fn dlclose
は、
.Fa handle
が参照する共有オブジェクトへの参照を削除します。参照
カウントが低下して
0 になると、そのオブジェクトはアドレス空間から除去され、
.Fa handle
は無効になります。この方法で共有オブジェクトを除去する直前に、動的
リンカはオブジェクトの
.Fn _fini
関数がオブジェクトによって定義されている
場合、これを呼び出します。
.Ql _init
と同じように、
.Ql _fini
は関数の C 言語名です。
.Fn dlclose
は、処理が成功すると値
0 を返します。そうでない場合は -1 を返し、
エラー条件を設定します。エラー条件は
.Fn dlerror
で問い合わせできます。
.Pp
オブジェクトに固有の関数
.Fn _init
と
.Fn _fini
は、引数なしに呼び出され、戻り
値を返さないと予測されます。
.Sh エラー
.Fn dlopen
と
.Fn dlsym
は、エラーが発生した場合に NULL ポインタを返します。
.Fn dlclose
は処理が成功すると 0 を返し、
エラーが発生した場合は -1 を
返します。エラーが検出されるたびに、それの詳細を説明するメッセージが
.Fn dlerror
の呼び出しによって取り出せます。
.Sh 関連項目
.Xr ld 1 ,
.Xr rtld 1 ,
.Xr link 5
