.\"
.\" 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.
.\"
.\" %FreeBSD: src/lib/libc/gen/dladdr.3,v 1.3.2.3 2001/12/14 18:33:50 ru Exp %
.\" $FreeBSD$
.\"
.Dd February 5, 1998
.Os
.Dt DLADDR 3
.Sh 名称
.Nm dladdr
.Nd 指定のアドレスが含まれる共有オブジェクトを検出する
.Sh ライブラリ
.Lb libc
.Sh 書式
.In 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
成功時には、0 でない値が返されます。
.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