.\" Copyright (c) 1983, 1990, 1993
.\"	The Regents of the University of California.  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.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
.\"
.\"	@(#)gprof.1	8.1 (Berkeley) 6/6/93
.\" %FreeBSD: src/usr.bin/gprof/gprof.1,v 1.27 2004/07/03 00:24:41 ru Exp %
.\"
.\" $FreeBSD$
.\"
.Dd June 20, 2004
.Dt GPROF 1
.Os
.Sh 名称
.Nm gprof
.Nd 呼び出しグラフに基づくプロファイルデータを表示する
.Sh 書式
.Nm
.Op Fl abKlLsuz
.Op Fl C Ar count
.Op Fl e Ar name
.Op Fl E Ar name
.Op Fl f Ar name
.Op Fl F Ar name
.Op Fl k Ar fromname toname
.Op Ar a.out Op Ar a.out.gmon ...
.Sh 解説
.Nm
ユーティリティは、C や Pascal、Fortran77 の実行プロファイルを生成します。
.Nm
では、呼び出されたルーチンの実行時間は、呼び出した側の
ルーチンに加算されます。
プロファイルデータは、呼び出しグラフプロファイルファイル
(call graph profile file)
から読み出されます。
このファイルは、
.Xr cc 1 ,
.Xr pc 1 ,
.Xr f77 1
に
.Fl pg
をつけてコンパイル
されたプログラムによって生成されます。
.Fl pg
をつけると、コンパイラは
プロファイル用ライブラリをリンクします。
約束事として、これらのライブラリの名前の後には
.Pa _p
が付きます。
つまり、プロファイルされるバージョンの
.Pa libc.a
は
.Pa libc_p.a
であり、コンパイラや隣家に直接ライブラリを指定するときに
.Fl l Ns Ar c
の代りに
.Fl l Ns Ar c_p
を使用可能です。
与えられたオブジェクトファイル (デフォルトでは
.Pa a.out )
を読み込んで、そのオブジェクトのシンボルテーブルと
呼び出しグラフプロファイルとを結び付けます。
デフォルトのグラフプロファイルファイルの名前は、
実行形式名にサフィックス
.Pa .gmon
を付けたものです。
2 つ以上のプロファイルファイルが与えられると、
.Nm
は、それらの情報を合計して出力します。
.Pp
.Nm
ユーティリティは、各ルーチンが消費した時間を計算します。
次に、この時間は呼び出しグラフの辺にそって伝播されます。
サイクルが見つかると、サイクルに対する呼び出しが、サイクルの時間を
共有するものとされます。
最初のリストには、関数からの呼び出しグラフ全体の合計時間によって
ソートされた関数が表示されています。
各関数のエントリの下には、その関数の呼び出しグラフ
での (直接の) 子 (すなわち呼び出された関数名) が表示され、それらの
関数の消費時間がどれくらい親 (つまり呼び出した側の関数) に伝播されているかが
示されています。
同様に、各関数のエントリの上側には、
関数での消費時間が呼び出し元の関数にどのように伝播されているかが
示されています。
.Pp
サイクル全体とそのメンバのリストを示したエントリが、
サイクルの呼び出し回数や実行時間への各メンバの寄与を含めて表示されます。
.Pp
次のリストでは、
.Xr prof 1
(NetBSD, FreeBSDにはありません) と同様なフラットプロファイル (flat profile)
表示されます。
ここには、関数の合計実行時間や呼び出し回数、
その関数本体のみの実行時間 (ミリ秒またはマイクロ秒)、
その関数本体及びそこから呼び出された関数の実行時間 (ミリ秒またはマイクロ秒)、
が表示されます。
.Pp
最後に関数名の索引が表示されます。
.Pp
以下のオプションが利用可能です。
.Bl -tag -width indent
.It Fl a
静的に宣言された関数の表示を抑制します。
このオプションが指定されると、静的関数についてのすべての関連する情報
(実行時間、別の関数の呼び出し、他の関数からの呼び出しなど) が、
.Pa a.out
ファイル中の静的関数の直前に読み込まれるされる関数に含まれることになります。
.It Fl b
プロファイル中の各フィールドの説明文を抑制します。
.It Fl C Ar count
.Ar count
数以上の関数を含む (呼び出し関係の) サイクルを取り除くために、
切断すべきアーク (呼び出し関係) の最小集合を見つけます。
注意:サイクルを中断するために用いられるアルゴリズムは指数関数的な
ものです。
そのため、このオプションを指定すると、
.Nm
を実行するのに非常に長い時間がかかります。
.It Fl e Ar name
ルーチン
.Ar name
とそのすべての子孫 (それらの関数が表示抑制されていない親をほかに
持っていなければ) のグラフプロファイルエントリの表示を抑制
します。
2 つ以上の
.Fl e
を指定することができます。
各
.Fl e
には 1 つしか
.Ar name
を指定することができません。
.It Fl E Ar name
.Fl e
と同様、指定されたルーチン
.Ar name
のグラフプロファイル
エントリ表示を抑制します。
さらに、プログラムのトータルの時間と計算時間の
パーセンテージから
.Ar name
で使われている時間を取り除きます。
(たとえば、
.Fl E
.Ar mcount
.Fl E
.Ar mcleanup
がデフォルトです)
.It Fl f Ar name
指定されたルーチン
.Ar name
とその子孫のグラフプロファイルエントリ
のみを表示します。
.Fl f
オプションは、複数指定することができます。
各オプション
.Fl f
には、1 つしか
.Ar name
を指定することができません。
.It Fl F Ar name
.Fl f
と同様に、指定されたルーチン
.Ar name
とその子孫のグラフ
プロファイルエントリのみを表示します。
プログラムのトータルの時間と計算時間の割合
には、表示されたルーチンの時間のみが使われます。
.Fl F
は複数指定することができます。
各オプション
.Fl F
には、1 つしか
.Ar name
を指定することができません。
オプション
.Fl F
は、オプション
.Fl E
の効果を打ち消します。
.It Fl k Ar fromname Ar toname
.Ar fromname
から
.Ar toname
への関数呼び出し関係のアークを削除します。
このオプションによって、不必要だと思うサイクルを切断することができます。
オプション
.Fl k
は、複数指定することができます。
各オプション
.Fl k
には一対のルーチン名
.Pf ( Ar fromname
と
.Ar toname )
しか
指定することができません。
.It Fl K
.Xr sysctl 3
および
.Xr kldsym 2
のインタフェースを使用して、
現在実行中のカーネルからシンボル情報を収集します。
これは、
.Pa a.out
引数を無視させ、
.Xr kld 4
モジュール中のシンボルを使用できるようにします。
.It Fl l
呼び出しグラフプロファイルの表示を抑制します。
.It Fl L
フラットプロファイルの表示を抑制します。
.It Fl s
指定されたすべてのプロファイルファイル中のプロファイル情報の合計
を表すサマリプロファイルファイル
.Pa gmon.sum
が生成されます。
このサマリプロファイルファイルはこのあとの
.Nm
の実行に
対して与えられ (その際にも通常
.Fl s
が指定される)、一連の
.Pa a.out
実行の結果のプロファイルデータの合計を
求めることができます。
.It Fl u
C プログラムには見えない名前の関数の表示を抑制します。
ELF オブジェクト形式では、文字
.Ql .\&
を含む名前を意味します。
a.out オブジェクト形式では、文字
.Ql _
で開始しない名前を意味します。
それらの関数に関連する情報は、すぐ低位側のアドレスにある (表示が
抑制されていない) 関数に含まれます。
これにより関数内にあるただのラベルが関数と認識されてしまうのを
防ぐ事ができます。
.It Fl z
使用されていないルーチン (呼び出し回数と合計時間が 0 である) を表示します。
.Fl c
オプションとともに使うと、一度も呼ばれていないルーチンを発見する事ができます。
.El
.Sh 関連ファイル
.Bl -tag -width a.out.gmon -compact
.It Pa a.out
テキスト空間と名前リスト。
.It Pa a.out.gmon
動的な呼び出しグラフとプロファイル。
.It Pa gmon.sum
動的な呼び出しグラフとプロファイルのサマリ。
.El
.Sh 関連項目
.Xr cc 1 ,
.Xr profil 2 ,
.Xr clocks 7
.\" .Xr monitor 3 ,
.\" .Xr prof 1
.Rs
.%T "An Execution Profiler for Modular Programs"
.%A S. Graham
.%A P. Kessler
.%A M. McKusick
.%J "Software - Practice and Experience"
.%V 13
.%P pp. 671-685
.%D 1983
.Re
.Rs
.%T "gprof: A Call Graph Execution Profiler"
.%A S. Graham
.%A P. Kessler
.%A M. McKusick
.%J "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices"
.%V 17
.%N 6
.%P pp. 120-126
.%D June 1982
.Re
.Sh 歴史
.Nm
プロファイラは、
.Bx 4.2
から登場しました。
.Sh バグ
サンプリングの周期がリストの最初に表示されますが、
統計的な域を出ないものであるかもしれません。
我々は、各関数の実行時間はその関数が消費した時間の合計をその関数の
呼び出し回数で割ったものによって表現されると仮定しています。
したがって、呼び出しグラフの関係にそって関数の親に伝播される時間は、
その関係をたどる回数に直接比例しています。
.Pp
自身がプロファイルされていない親は、プロファイルしている子供から
伝播される時間を持っており、呼び出しグラフのリストのなかで
自動的に起動されるものとして現れます。
しかし、この関数が持つ時間は
それ以上伝播されません。
同様に、シグナルを捕捉する関数は、それらがプロファイルされていても、
自動的に起動されるものとして現れます (もう少し複雑な理由がありますが)。
プロファイルルーチンを実行している最中にシグナルを捕捉する
関数が呼出されたとき (この場合はすべてが失われてしまいます) を除いては、
シグナルを捕捉する関数の子供の実行時間は、その親に正しく
伝播されるべきです。
.Pp
プロファイルされているプログラムは、
グラフプロファイル
ファイルにプロファイル情報がセーブされるよう
.Xr exit 3
を呼ぶか、正常に終了しなければいけません。