draft/man3/dl_iterate_phdr.3

   1 .\" Copyright (c) 2003 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\"*******************************************************************
  26 .\"
  27 .\" This file was generated with po4a. Translate the source file.
  28 .\"
  29 .\"*******************************************************************
  30 .TH DL_ITERATE_PHDR 3 2007\-05\-18 GNU "Linux Programmer's Manual"
  31 .SH 名前
  32 dl_iterate_phdr \- 共有オブジェクトのリストを辿る
  33 .SH 書式
  34 .nf
  35 \fB#define _GNU_SOURCE\fP         /* feature_test_macros(7) 参照 */
  36 \fB#include <link.h>\fP
  37
  38 \fBint dl_iterate_phdr(\fP
  39 \fB          int (*\fP\fIcallback\fP\fB) (struct dl_phdr_info *\fP\fIinfo\fP\fB,\fP
  40 \fB                           size_t \fP\fIsize\fP\fB, void *\fP\fIdata\fP\fB,\fP
  41 \fB          void *\fP\fIdata\fP\fB;\fP
  42 .fi
  43 .SH 説明
  44 \fBdl_iterate_phdr\fP()  関数を使うと、アプリケーションは実行時に どの共有オブジェクトをロードしたかを見つけることができる。
  45
  46 \fBdl_iterate_phdr\fP()  関数はアプリケーションの共有オブジェクトのリストを辿り、 各オブジェクトに対して関数 \fIcallback\fP
  47 を 1 回ずつ呼び出す。 これは全ての共有オブジェクトが処理されるか、 \fIcallback\fP が 0 以外の値を返すまで行われる。
  48
  49 各々の \fIcallback\fP 呼び出しは 3 つの引き数を受け取る: \fIinfo\fP は共有オブジェクトの情報を保持する構造体へのポインタである。
  50 \fIsize\fP は \fIinfo\fP で指される構造体のサイズである。 \fIdata\fP は呼び出し元プログラムから
  51 \fBdl_iterate_phdr\fP()  の呼び出しの (同じく \fIdata\fP という名前の) 第 2 引き数として渡される値のコピーである。
  52
  53 \fIinfo\fP 引き数は、以下のような型の構造体である。
  54
  55 .in +4n
  56 .nf
  57 struct dl_phdr_info {
  58     ElfW(Addr)        dlpi_addr;  /* オブジェクトのベースアドレス */
  59     const char       *dlpi_name;  /* (null 文字で終端された)
  60                                      オブジェクト名 */
  61     const ElfW(Phdr) *dlpi_phdr;  /* このオブジェクトの
  62                                      ELF プログラムヘッダの
  63                                      配列へのポインタ */
  64     ElfW(Half)        dlpi_phnum; /* \fIdlpi_phdr\fP のアイテム数 */
  65 };
  66 .fi
  67 .in
  68
  69 (\fIElfW\fP()  マクロ定義は引き数をハードウェアアーキテクチャに適した ELF データ型の名前に変換する。 たとえば、32
  70 ビットプラットフォームでは ElfW(Addr) はデータ型名 Elf32_Addr を生成する。 これらの型についての更に詳細な情報は、ヘッダファイル
  71 \fI<elf.h>\fP と \fI<link.h>\fP にある。
  72
  73 \fIdlpi_addr\fP フィールドは共有オブジェクトのベースアドレス (つまり、共有オブジェクトの仮想メモリアドレスと、 ファイル
  74 (このファイルから共有オブジェクトがロードされる) における 共有オブジェクトのオフセットとの差分) を表す。 \fIdlpi_name\fP は null
  75 文字で終端された文字列であり、 このパス名のファイルから共有オブジェクトがロードされる。
  76
  77 \fIdlpi_phdr\fP と \fIdlpi_phnum\fP フィールドの意味を理解するには、 ELF
  78 共有オブジェクトが幾つかのセグメントから構成されていることと、 各セグメントがそれに対応するプログラムヘッダ (そのセグメントを説明する)
  79 を持っていることを知っている必要がある。 \fIdlpi_phdr\fP フィールドは、この共有オブジェクトのプログラムヘッダの配列へのポインタである。
  80 \fIdlpi_phnum\fP は、この配列のサイズを表す。
  81
  82 これらのプログラムヘッダは以下のような形式の構造体である:
  83 .in +4n
  84 .nf
  85
  86 typedef struct
  87 {
  88     Elf32_Word  p_type;    /* セグメントの型 */
  89     Elf32_Off   p_offset;  /* セグメントのファイルオフセット */
  90     Elf32_Addr  p_vaddr;   /* セグメントの仮想アドレス */
  91     Elf32_Addr  p_paddr;   /* セグメントの物理アドレス */
  92     Elf32_Word  p_filesz;  /* ファイルにおけるセグメントサイズ */
  93     Elf32_Word  p_memsz;   /* メモリにおけるセグメントサイズ */
  94     Elf32_Word  p_flags;   /* セグメントフラグ */
  95     Elf32_Word  p_align;   /* セグメントの配置 (alignment) */
  96 } Elf32_Phdr;
  97 .fi
  98 .in
  99
 100 特定のプログラムヘッダ \fIx\fP の仮想メモリにおける位置は、以下の式で計算できる点に注意すること:
 101
 102 .nf
 103   addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr;
 104 .fi
 105 .SH 返り値
 106 \fBdl_iterate_phdr\fP()  関数は最後の \fIcallback\fP の呼び出しで返された値を返す。
 107 .SH バージョン
 108 \fBdl_iterate_phdr\fP()  は glibc のバージョン 2.2.4 以降でサポートされている。
 109 .SH 準拠
 110 \fBdl_iterate_phdr\fP()  関数は Linux 固有であり、移植を考えたアプリケーションでは避けるべきである。
 111 .SH 例
 112 以下のプログラムは、共有オブジェクトがロードされた パス名の一覧を表示する。 各共有オブジェクトについて、このプログラムは オブジェクトの ELF
 113 セグメントがロードされた 仮想アドレスの一覧を表示する。
 114
 115 .nf
 116 #define _GNU_SOURCE
 117 #include <link.h>
 118 #include <stdlib.h>
 119 #include <stdio.h>
 120
 121 static int
 122 callback(struct dl_phdr_info *info, size_t size, void *data)
 123 {
 124     int j;
 125
 126     printf("name=%s (%d segments)\en", info\->dlpi_name,
 127         info\->dlpi_phnum);
 128
 129     for (j = 0; j < info\->dlpi_phnum; j++)
 130          printf("\et\et header %2d: address=%10p\en", j,
 131              (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr));
 132     return 0;
 133 }
 134
 135 int
 136 main(int argc, char *argv[])
 137 {
 138     dl_iterate_phdr(callback, NULL);
 139
 140     exit(EXIT_SUCCESS);
 141 }
 142 .fi
 143 .SH 関連項目
 144 \fBldd\fP(1), \fBobjdump\fP(1), \fBreadelf\fP(1), \fBdlopen\fP(3), \fBelf\fP(5),
 145 \fBld.so\fP(8)
 146
 147 オンラインのいろいろな場所で入手できる \fIExecutable and Linking Format Specification\fP
 148 .SH この文書について
 149 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.52 の一部
 150 である。プロジェクトの説明とバグ報告に関する情報は
 151 http://www.kernel.org/doc/man\-pages/ に書かれている。