+++ /dev/null
-.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
-.\" drawing on material by Justin Pryzby <pryzbyj@justinpryzby.com>
-.\"
-.\" %%%LICENSE_START(PERMISSIVE_MISC)
-.\" Permission is hereby granted, free of charge, to any person obtaining
-.\" a copy of this software and associated documentation files (the
-.\" "Software"), to deal in the Software without restriction, including
-.\" without limitation the rights to use, copy, modify, merge, publish,
-.\" distribute, sublicense, and/or sell copies of the Software, and to
-.\" permit persons to whom the Software is furnished to do so, subject to
-.\" the following conditions:
-.\"
-.\" The above copyright notice and this permission notice shall be
-.\" included in all copies or substantial portions of the Software.
-.\"
-.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-.\" %%%LICENSE_END
-.\"
-.\" References:
-.\" glibc manual and source
-.\"*******************************************************************
-.\"
-.\" This file was generated with po4a. Translate the source file.
-.\"
-.\"*******************************************************************
-.\"
-.\" Japanese Version Copyright (c) 2007 Akihiro MOTOKI
-.\" all rights reserved.
-.\" Translated 2007-10-16, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.66
-.\"
-.TH BACKTRACE 3 2008\-06\-14 GNU "Linux Programmer's Manual"
-.SH 名前
-backtrace, backtrace_symbols, backtrace_symbols_fd \- アプリケーション自身でのデバッグのサポート
-.SH 書式
-\fB#include <execinfo.h>\fP
-
-\fBint backtrace(void\fP \fB**\fP\fIbuffer\fP\fB,\fP \fBint\fP \fIsize\fP\fB);\fP
-
-\fBchar **backtrace_symbols(void *const\fP \fB*\fP\fIbuffer\fP\fB,\fP \fBint\fP
-\fIsize\fP\fB);\fP
-
-\fBvoid backtrace_symbols_fd(void *const\fP \fB*\fP\fIbuffer\fP\fB,\fP \fBint\fP
-\fIsize\fP\fB,\fP \fBint\fP \fIfd\fP\fB);\fP
-.SH 説明
-\fBbacktrace\fP() は、呼び出したプログラムのバックトレースを \fIbuffer\fP が指す配列に入れて返す。バックトレースは、プログラムで
-現在動作中の関数呼び出しの並びである。 \fIbuffer\fP が指す配列の個々の要素は \fIvoid\ *\fP 型で、
-対応するスタックフレームからのリターンアドレスである。 \fIsize\fP 引き数は \fIbuffer\fP に格納できるアドレスの最大個数を指定する。
-バックトレースが \fIsize\fP より大きい場合、 \fIsize\fP 個の直近の関数呼び出しに対応するアドレスが返される。
-完全なバックトレースを取得するためには、確実に \fIbuffer\fP と \fIsize\fP が十分大きくなるようにすること。
-
-\fBbacktrace\fP() によって \fIbuffer\fP にアドレスの集合が得られたら、 \fBbacktrace_symbols\fP()
-によって、アドレス集合を、そのアドレスをシンボルで表した文字列の配列 に翻訳できる。 \fIsize\fP 引き数は \fIbuffer\fP
-に格納されたアドレスの数を指定する。 個々のアドレスのシンボル表現は、関数名 (特定できた場合)、 関数へのオフセット
-(16進表記)、実際のリターンアドレス (16進表記) から構成される。 \fBbacktrace_symbols\fP() の実行結果としては、
-文字列ポインターの配列のアドレスが返される。 この配列は \fBbacktrace_symbols\fP() によって \fBmalloc\fP(3)
-され、呼び出し側で free しなければならない (ポインターの配列が指す個々の文字列は free する必要はないし、 free すべきでもない)。
-
-\fBbacktrace_symbols_fd\fP() は、 \fBbacktrace_symbols\fP() と同じ引き数 \fIbuffer\fP と
-\fIsize\fP をとるが、呼び出し側に文字列の配列を返す代わりに、 文字列をファイルディスクリプター \fIfd\fP に 1 行に 1
-エントリーの形で書き込む。 \fBbacktrace_symbols_fd\fP() は \fBmalloc\fP(3) を呼び出さない。
-そのため、これに続く関数が失敗する可能性がある状況でも利用できる。
-.SH 返り値
-\fBbacktrace\fP() は \fIbuffer\fP に格納したアドレスの個数を返す。その個数は \fIsize\fP より大きくなることはない。 返り値が
-\fIsize\fP より小さい場合、バックトレース全体が格納されている。返り値が \fIsize\fP
-と等しい場合、バックトレースは切り詰められているかもしれない。 切り詰められた場合、最も古いスタックフレームのアドレスは 返されないことになる。
-
-\fBbacktrace_symbols\fP() は、成功すると、この呼び出しで \fBmalloc\fP(3) された配列へのポインターを返す。
-エラーの場合、 NULL を返す。
-.SH バージョン
-\fBbacktrace\fP(), \fBbacktrace_symbols\fP(), \fBbacktrace_symbols_fd\fP() はバージョン
-2.1 以降の glibc で提供されている。
-.SH 準拠
-これらの関数は GNU による拡張である。
-.SH 注意
-これらの関数は、関数のリターンアドレスがスタック上でどのように格納されるか に関してある仮定を置いている。 以下の点に注意。
-.IP * 3
-(\fBgcc\fP(1) の 0 以外の最適化レベルで暗黙のうちに行われる) フレームポインターの省略を行うと、これらの前提が崩れる可能性がある。
-.IP *
-インライン関数はスタックフレームを持たない。
-.IP *
-末尾呼び出しの最適化 (tail\-call optimization) を行うと、 あるスタックフレームが別のスタックフレームを置き換える可能性がある。
-.PP
-シンボル名は特別なリンカーオプションを使用しないと利用できない場合がある。 GNU リンカーを使用するシステムでは、 \fI\-rdynamic\fP
-リンカーオプションを使う必要がある。 "static" な関数のシンボル名は公開されず、 バックトレースでは利用できない点に注意すること。
-.SH 例
-以下のプログラムは、 \fBbacktrace\fP() と \fBbacktrace_symbols\fP() の使用例を示したものである。
-以下に示すシェルのセッションは、 このプログラムを動かした際の実行例である。
-.nf
-.in +4n
-
-$\fB cc \-rdynamic prog.c \-o prog\fP
-$\fB ./prog 3\fP
-backtrace() returned 8 addresses
-\&./prog(myfunc3+0x5c) [0x80487f0]
-\&./prog [0x8048871]
-\&./prog(myfunc+0x21) [0x8048894]
-\&./prog(myfunc+0x1a) [0x804888d]
-\&./prog(myfunc+0x1a) [0x804888d]
-\&./prog(main+0x65) [0x80488fb]
-\&/lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
-\&./prog [0x8048711]
-.in
-.fi
-.SS プログラムのソース
-\&
-.nf
-#include <execinfo.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <unistd.h>
-
-void
-myfunc3(void)
-{
- int j, nptrs;
-#define SIZE 100
- void *buffer[100];
- char **strings;
-
- nptrs = backtrace(buffer, SIZE);
- printf("backtrace() returned %d addresses\en", nptrs);
-
- /* backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO) を
- 呼び出しても、以下と同様の出力が得られる。 */
-
- strings = backtrace_symbols(buffer, nptrs);
- if (strings == NULL) {
- perror("backtrace_symbols");
- exit(EXIT_FAILURE);
- }
-
- for (j = 0; j < nptrs; j++)
- printf("%s\en", strings[j]);
-
- free(strings);
-}
-
-static void /* "static" はシンボルを公開しないことを意味する */
-myfunc2(void)
-{
- myfunc3();
-}
-
-void
-myfunc(int ncalls)
-{
- if (ncalls > 1)
- myfunc(ncalls \- 1);
- else
- myfunc2();
-}
-
-int
-main(int argc, char *argv[])
-{
- if (argc != 2) {
- fprintf(stderr, "%s num\-calls\en", argv[0]);
- exit(EXIT_FAILURE);
- }
-
- myfunc(atoi(argv[1]));
- exit(EXIT_SUCCESS);
-}
-.fi
-.SH 関連項目
-\fBgcc\fP(1), \fBld\fP(1), \fBdlopen\fP(3), \fBmalloc\fP(3)
-.SH この文書について
-この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
-である。プロジェクトの説明とバグ報告に関する情報は
-http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
