.\"
.\" Copyright (c) 1998 John D. Polstra
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	%Id: dladdr.3,v 1.2 1998/08/31 16:40:59 wosch Exp %
.\"
.\" $FreeBSD$
.Dd February 5, 1998
.Os FreeBSD
.Dt DLADDR 3
.Sh 名称
.Nm dladdr
.Nd 指定のアドレスが入った共有オブジェクトを検出する
.Sh 書式
.Fd #include <dlfcn.h>
.Ft int
.Fn dladdr "const void *addr" "Dl_info *info"
.Sh 解説
.Nm
は、アドレス
.Fa addr
が入った共有オブジェクトについての情報を動的リンカ
で照会します。情報は、
.Fa info
によって指定される構造体内に返されます。構造には
少なくとも次のメンバが入っています。
.Bl -tag -width "XXXconst char *dli_fname"
.It Li "const char *dli_fname"
アドレスが入った共有オブジェクトのパス名。
.It Li "void *dli_fbase"
共有オブジェクトが呼び出し元プロセスのアドレス空間にマップ
されるベースアドレス。
.It Li "const char *dli_sname"
値が
.Fa addr
以下の最も近いランタイムシンボルの名前。
可能なときは、シンボル名が、C ソースコードで表示されるように返されます。
.Pp
適切な値のシンボルが見つからない場合は、このフィールドと
.Va dli_saddr
の両方が
.Dv NULL
に設定されます。
.It Li "void *dli_saddr"
.Li dli_sname
で返されたシンボルの値。
.El
.Pp
.Nm
は動的にリンクされるプログラムでだけ利用できます。
.Sh エラー
.Fa addr
が入っているマップされた共有オブジェクトが見つからない場合、
.Nm
は
0 を返します。この場合、障害を説明するメッセージが
.Fn dlerror
を呼び出すことで取り出せます。
.Pp
成功の場合、ゼロでない値が返されます。
.Sh 関連項目
.Xr rtld 1 ,
.Xr dlopen 3
.Sh 歴史
.Nm
関数は Solaris オペレーティングシステムで最初に現れました。
.Sh バグ
この関数は Solaris とバグに互換性があります。特に、
次のバグが存在します。
.Bl -bullet
.It
.Fa addr
が共有ライブラリではなくメインの実行可能モジュールにある場合、
.Va dli_fname
で返されるパス名は正しくない可能性があります。パス名は呼び出し
プロセスの
.Va argv[0]
から直接取り出されます。フルパス名で指定されたプログラム
を実行するとき、ほとんどのシェルは
.Va argv[0]
をパス名に設定します。しかし、
これはシェルの必要条件ではありませんし、オペレーティングシステムによって
保証されてもいません。
.It
.Fa addr
が形式
.Va &func
であり、
.Va func
がグローバル関数の場合、その値が意外に
良くない可能性があります。動的にリンクされたプログラムでは、
グローバル関数のアドレスは、関数自体の開始点ではなく、
プログラムリンクテーブルのエントリを指すと考えられます。これによって、
ほとんどのグローバル関数が、実際にコードが常駐する共有ライブラリではなく、
メインの実行可能モジュール内部で定義されるように見えます。
.It
処理失敗の印として 0 を返すのは、Unix の長い伝統に反します。
.El