draft/man3/backtrace.3

   1 .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com>
   3 .\"
   4 .\" Permission is hereby granted, free of charge, to any person obtaining
   5 .\" a copy of this software and associated documentation files (the
   6 .\" "Software"), to deal in the Software without restriction, including
   7 .\" without limitation the rights to use, copy, modify, merge, publish,
   8 .\" distribute, sublicense, and/or sell copies of the Software, and to
   9 .\" permit persons to whom the Software is furnished to do so, subject to
  10 .\" the following conditions:
  11 .\"
  12 .\" The above copyright notice and this permission notice shall be
  13 .\" included in all copies or substantial portions of the Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18 .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  19 .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  20 .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  21 .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .\" References:
  24 .\"   glibc manual and source
  25 .\"
  26 .\" Japanese Version Copyright (c) 2007  Akihiro MOTOKI
  27 .\"         all rights reserved.
  28 .\" Translated 2007-10-16, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.66
  29 .\"
  30 .TH BACKTRACE 3 2008-06-14 GNU "Linux Programmer's Manual"
  31 .\"O .SH NAME
  32 .SH 名前
  33 .\"O backtrace, backtrace_symbols, backtrace_symbols_fd \- support
  34 .\"O for application self-debugging
  35 backtrace, backtrace_symbols, backtrace_symbols_fd \-
  36 アプリケーション自身でのデバッグのサポート
  37 .\"O .SH SYNOPSIS
  38 .SH 書式
  39 .B #include <execinfo.h>
  40
  41 .B int backtrace(void
  42 .BI ** buffer ,
  43 .B int
  44 .IB size );
  45
  46 .B char **backtrace_symbols(void *const
  47 .BI * buffer ,
  48 .B int
  49 .IB size );
  50
  51 .B void backtrace_symbols_fd(void *const
  52 .BI * buffer ,
  53 .B int
  54 .IB size ,
  55 .B int
  56 .IB fd );
  57 .\"O .SH DESCRIPTION
  58 .SH 説明
  59 .\"O .BR backtrace ()
  60 .\"O returns a backtrace for the calling program,
  61 .\"O in the array pointed to by
  62 .\"O .IR buffer .
  63 .\"O A backtrace is the series of currently active function calls for
  64 .\"O the program.
  65 .\"O Each item in the array pointed to by
  66 .\"O .I buffer
  67 .\"O is of type \fIvoid *\fP, and is the return address from
  68 .\"O the corresponding stack frame.
  69 .BR backtrace ()
  70 は、呼び出したプログラムのバックトレースを
  71 .I buffer
  72 が指す配列に入れて返す。バックトレースは、プログラムで
  73 現在動作中の関数呼び出しの並びである。
  74 .I buffer
  75 が指す配列の個々の要素は \fIvoid *\fP 型で、
  76 対応するスタックフレームからのリターンアドレスである。
  77 .\"O The
  78 .\"O .I size
  79 .\"O argument specifies the maximum number of addresses
  80 .\"O that can be stored in
  81 .\"O .IR buffer .
  82 .\"O If the backtrace is larger than
  83 .\"O .IR size ,
  84 .\"O then the addresses corresponding to the
  85 .\"O .I size
  86 .\"O most recent function calls are returned;
  87 .\"O to obtain the complete backtrace, make sure that
  88 .\"O .I buffer
  89 .\"O and
  90 .\"O .I size
  91 .\"O are large enough.
  92 .I size
  93 引き数は
  94 .I buffer
  95 に格納できるアドレスの最大個数を指定する。
  96 バックトレースが
  97 .I size
  98 より大きい場合、
  99 .I size
 100 個の直近の関数呼び出しに対応するアドレスが返される。
 101 完全なバックトレースを取得するためには、確実に
 102 .I buffer
 103 と
 104 .I size
 105 が十分大きくなるようにすること。
 106
 107 .\"O Given the set of addresses returned by
 108 .\"O .BR backtrace ()
 109 .\"O in
 110 .\"O .IR buffer ,
 111 .\"O .BR backtrace_symbols ()
 112 .\"O translates the addresses into an array of strings that describe
 113 .\"O the addresses symbolically.
 114 .BR backtrace ()
 115 によって
 116 .I buffer
 117 にアドレスの集合が得られたら、
 118 .BR backtrace_symbols ()
 119 によって、アドレス集合を、そのアドレスをシンボルで表した文字列の配列
 120 に翻訳できる。
 121 .\"O The
 122 .\"O .I size
 123 .\"O argument specifies the number of addresses in
 124 .\"O .IR buffer .
 125 .I size
 126 引き数は
 127 .I buffer
 128 に格納されたアドレスの数を指定する。
 129 .\"O The symbolic representation of each address consists of the function name
 130 .\"O (if this can be determined), a hexadecimal offset into the function,
 131 .\"O and the actual return address (in hexadecimal).
 132 個々のアドレスのシンボル表現は、関数名 (特定できた場合)、
 133 関数へのオフセット (16進表記)、実際のリターンアドレス (16進表記)
 134 から構成される。
 135 .\"O The address of the array of string pointers is returned
 136 .\"O as the function result of
 137 .\"O .BR backtrace_symbols ().
 138 .\"O This array is
 139 .\"O .BR malloc (3)ed
 140 .\"O by
 141 .\"O .BR backtrace_symbols (),
 142 .\"O and must be freed by the caller.
 143 .\"O (The strings pointed to by the array of pointers
 144 .\"O need not and should not be freed.)
 145 .BR backtrace_symbols ()
 146 の実行結果としては、
 147 文字列ポインタの配列のアドレスが返される。
 148 この配列は
 149 .BR backtrace_symbols ()
 150 によって
 151 .BR malloc (3)
 152 され、呼び出し側で free しなければならない
 153 (ポインタの配列が指す個々の文字列は free する必要はないし、
 154 free すべきでもない)。
 155
 156 .\"O .BR backtrace_symbols_fd ()
 157 .\"O takes the same
 158 .\"O .I buffer
 159 .\"O and
 160 .\"O .I size
 161 .\"O arguments as
 162 .\"O .BR backtrace_symbols (),
 163 .\"O but instead of returning an array of strings to the caller,
 164 .\"O it writes the strings, one per line, to the file descriptor
 165 .\"O .IR fd .
 166 .\"O .BR backtrace_symbols_fd ()
 167 .\"O does not call
 168 .\"O .BR malloc (3),
 169 .\"O and so can be employed in situations where the latter function might fail.
 170 .BR backtrace_symbols_fd ()
 171 は、
 172 .BR backtrace_symbols ()
 173 と同じ引き数
 174 .I buffer
 175 と
 176 .I size
 177 をとるが、呼び出し側に文字列の配列を返す代わりに、
 178 文字列をファイルディスクリプタ
 179 .I fd
 180 に 1 行に 1 エントリの形で書き込む。
 181 .BR backtrace_symbols_fd ()
 182 は
 183 .BR malloc (3)
 184 を呼び出さない。
 185 そのため、これに続く関数が失敗する可能性がある状況でも利用できる。
 186 .\"O .SH "RETURN VALUE"
 187 .SH 返り値
 188 .\"O .BR backtrace ()
 189 .\"O returns the number of addresses returned in
 190 .\"O .IR buffer ,
 191 .\"O which is not greater than
 192 .\"O .IR size .
 193 .\"O If the return value is less than
 194 .\"O .IR size ,
 195 .\"O then the full backtrace was stored; if it is equal to
 196 .\"O .IR size ,
 197 .\"O then it may have been truncated, in which case the addresses of the
 198 .\"O oldest stack frames are not returned.
 199 .BR backtrace ()
 200 は
 201 .I buffer
 202 に格納したアドレスの個数を返す。その個数は
 203 .I size
 204 より大きくなることはない。
 205 返り値が
 206 .I size
 207 より小さい場合、バックトレース全体が格納されている。返り値が
 208 .I size
 209 と等しい場合、バックトレースは切り詰められているかもしれない。
 210 切り詰められた場合、最も古いスタックフレームのアドレスは
 211 返されないことになる。
 212
 213 .\"O On success,
 214 .\"O .BR backtrace_symbols ()
 215 .\"O returns a pointer to the array
 216 .\"O .BR malloc (3)ed
 217 .\"O by the call;
 218 .\"O on error, NULL is returned.
 219 .BR backtrace_symbols ()
 220 は、成功すると、この呼び出しで
 221 .BR malloc (3)
 222 された配列へのポインタを返す。
 223 エラーの場合、 NULL を返す。
 224 .\"O .SH VERSIONS
 225 .SH バージョン
 226 .\"O .BR backtrace (),
 227 .\"O .BR backtrace_symbols (),
 228 .\"O and
 229 .\"O .BR backtrace_symbols_fd ()
 230 .\"O are provided in glibc since version 2.1.
 231 .BR backtrace (),
 232 .BR backtrace_symbols (),
 233 .BR backtrace_symbols_fd ()
 234 はバージョン 2.1 以降の glibc で提供されている。
 235 .\"O .SH CONFORMING TO
 236 .SH 準拠
 237 .\"O These functions are GNU extensions.
 238 これらの関数は GNU による拡張である。
 239 .\"O .SH NOTES
 240 .SH 注意
 241 .\"O These functions make some assumptions about how a function's return
 242 .\"O address is stored on the stack.
 243 .\"O Note the following:
 244 これらの関数は、関数のリターンアドレスがスタック上でどのように格納されるか
 245 に関してある仮定を置いている。
 246 以下の点に注意。
 247 .IP * 3
 248 .\"O Omission of the frame pointers (as
 249 .\"O implied by any of
 250 .\"O .BR gcc (1)'s
 251 .\"O nonzero optimization levels) may cause these assumptions to be
 252 .\"O violated.
 253 .RB ( gcc (1)
 254 の 0 以外の最適化レベルで暗黙のうちに行われる)
 255 フレームポインタの省略を行うと、これらの前提が崩れる可能性がある。
 256 .IP *
 257 .\"O Inlined functions do not have stack frames.
 258 インライン関数はスタックフレームを持たない。
 259 .IP *
 260 .\"O Tail-call optimization causes one stack frame to replace another.
 261 末尾呼び出しの最適化 (tail-call optimization) を行うと、
 262 あるスタックフレームが別のスタックフレームを置き換える可能性がある。
 263 .PP
 264 .\"O The symbol names may be unavailable without the use of special linker
 265 .\"O options.
 266 .\"O For systems using the GNU linker, it is necessary to use the
 267 .\"O .I \-rdynamic
 268 .\"O linker option.
 269 .\"O Note that names of "static" functions are not exposed,
 270 .\"O and won't be available in the backtrace.
 271 シンボル名は特別なリンカ・オプションを使用しないと利用できない場合がある。
 272 GNU リンカを使用するシステムでは、
 273 .I \-rdynamic
 274 リンカ・オプションを使う必要がある。
 275 "static" な関数のシンボル名は公開されず、
 276 バックトレースでは利用できない点に注意すること。
 277 .\"O .SH EXAMPLE
 278 .SH 例
 279 .\"O The program below demonstrates the use of
 280 .\"O .BR backtrace ()
 281 .\"O and
 282 .\"O .BR backtrace_symbols ().
 283 .\"O The following shell session shows what we might see when running the
 284 .\"O program:
 285 以下のプログラムは、
 286 .BR backtrace ()
 287 と
 288 .BR backtrace_symbols ()
 289 の使用例を示したものである。
 290 以下に示すシェルのセッションは、
 291 このプログラムを動かした際の実行例である。
 292 .nf
 293 .in +4n
 294
 295 .RB "$" " cc \-rdynamic prog.c \-o prog"
 296 .RB "$" " ./prog 3"
 297 backtrace() returned 8 addresses
 298 \&./prog(myfunc3+0x5c) [0x80487f0]
 299 \&./prog [0x8048871]
 300 \&./prog(myfunc+0x21) [0x8048894]
 301 \&./prog(myfunc+0x1a) [0x804888d]
 302 \&./prog(myfunc+0x1a) [0x804888d]
 303 \&./prog(main+0x65) [0x80488fb]
 304 \&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
 305 \&./prog [0x8048711]
 306 .in
 307 .fi
 308 .\"O .SS Program source
 309 .SS プログラムのソース
 310 \&
 311 .nf
 312 #include <execinfo.h>
 313 #include <stdio.h>
 314 #include <stdlib.h>
 315 #include <unistd.h>
 316
 317 void
 318 myfunc3(void)
 319 {
 320     int j, nptrs;
 321 #define SIZE 100
 322     void *buffer[100];
 323     char **strings;
 324
 325     nptrs = backtrace(buffer, SIZE);
 326     printf("backtrace() returned %d addresses\\n", nptrs);
 327
 328 .\"O     /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
 329 .\"O        would produce similar output to the following: */
 330     /* backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO) を
 331        呼び出しても、以下と同様の出力が得られる。 */
 332
 333     strings = backtrace_symbols(buffer, nptrs);
 334     if (strings == NULL) {
 335         perror("backtrace_symbols");
 336         exit(EXIT_FAILURE);
 337     }
 338
 339     for (j = 0; j < nptrs; j++)
 340         printf("%s\\n", strings[j]);
 341
 342     free(strings);
 343 }
 344
 345 .\"O static void   /* "static" means don\(aqt export the symbol... */
 346 static void   /* "static" はシンボルを公開しないことを意味する */
 347 myfunc2(void)
 348 {
 349     myfunc3();
 350 }
 351
 352 void
 353 myfunc(int ncalls)
 354 {
 355     if (ncalls > 1)
 356         myfunc(ncalls \- 1);
 357     else
 358         myfunc2();
 359 }
 360
 361 int
 362 main(int argc, char *argv[])
 363 {
 364     if (argc != 2) {
 365         fprintf(stderr, "%s num\-calls\\n", argv[0]);
 366         exit(EXIT_FAILURE);
 367     }
 368
 369     myfunc(atoi(argv[1]));
 370     exit(EXIT_SUCCESS);
 371 }
 372 .fi
 373 .\"O .SH SEE ALSO
 374 .SH 関連項目
 375 .BR gcc (1),
 376 .BR ld (1),
 377 .BR dlopen (3),
 378 .BR malloc (3)