release/man1/memusage.1

   1 .\" Copyright (c) 2013, Peter Schiffer <pschiffe@redhat.com>
   2 .\" and Copyright (C) 2014, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   5 .\" This is free documentation; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License as
   7 .\" published by the Free Software Foundation; either version 2 of
   8 .\" the License, or (at your option) any later version.
   9 .\"
  10 .\" The GNU General Public License's references to "object code"
  11 .\" and "executables" are to be interpreted as the output of any
  12 .\" document formatting or typesetting system, including
  13 .\" intermediate and printed output.
  14 .\"
  15 .\" This manual is distributed in the hope that it will be useful,
  16 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 .\" GNU General Public License for more details.
  19 .\"
  20 .\" You should have received a copy of the GNU General Public
  21 .\" License along with this manual; if not, see
  22 .\" <http://www.gnu.org/licenses/>.
  23 .\" %%%LICENSE_END
  24 .\"*******************************************************************
  25 .\"
  26 .\" This file was generated with po4a. Translate the source file.
  27 .\"
  28 .\"*******************************************************************
  29 .TH MEMUSAGE 1 2014\-09\-06 GNU "Linux user manual"
  30 .SH 名前
  31 memusage \- プログラムのメモリー使用量のプロファイルを行う
  32 .SH 書式
  33 \fBmemusage\fP [\fIoption\fP]... \fIprogram\fP [\fIprogramoption\fP]...
  34 .SH 説明
  35 \fBmemusage\fP は、 プログラム \fIprogram\fP のメモリー使用量のプロファイルを行う bash スクリプトである。 呼び出し元の環境に
  36 (\fBLD_PRELOAD\fP 環境変数を使って) \fBlibmemusage.so\fP ライブラリをプレロードする。 \fBld.so\fP(8) を参照。
  37 \fBlibmemusage.so\fP ライブラリは、 \fBmalloc\fP(3), \fBcalloc\fP(3), \fBfree\fP(3),
  38 \fBrealloc\fP(3) の呼び出しを横取りし、 メモリー割り当て状況の追跡を行う。 追加で、 \fBmmap\fP(2), \fBmremap\fP(2),
  39 \fBmunmap\fP(2) を追跡することもできる。
  40 .PP
  41 \fBmemusage\fP は収集したデータをテキスト形式で出力することもできるし、 \fBmemusagestat\fP(1)
  42 を使って収集したデータをグラフにした PNG ファイルを作成することもできる (以下の \fB\-p\fP オプションを参照)。
  43 .SS メモリー使用量概要
  44 \fBmemusage\fP が出力する "Memory usage summary" (メモリー使用量概要) の行には以下のフィールドが含まれる。
  45 .RS 4
  46 .TP
  47 \fBheap total\fP
  48 \fBmalloc\fP(3) のすべての呼び出しの \fIsize\fP 引き数の合計、 \fBcalloc\fP(3) のすべての呼び出しの引き数の積
  49 (\fInmemb\fP*\fIsize\fP)、 \fBmmap\fP(2) のすべての呼び出しの \fIlength\fP 引き数の合計。 \fBrealloc\fP(3) と
  50 \fBmremap\fP(2) の場合、 割り当ての新しいサイズが以前のサイズよりも大きい場合、 差分 (新しいサイズから古いサイズを引いた値)
  51 の合計が加算される。
  52 .TP
  53 \fBheap peak\fP
  54 \fBmalloc\fP(3) の \fIsize\fP 引き数、 \fBcalloc\fP(3) の \fInmemb\fP*\fIsize\fP の積、
  55 \fBrealloc\fP(3) の \fIsize\fP 引き数、 \fBmmap\fP(2) の \fIlength\fP 引き数、 \fBmremap\fP(2) の
  56 \fInew_size\fP 引き数、 の中の最大値。
  57 .TP
  58 \fBstack peak\fP
  59 監視される関数の最初の呼び出しが行われる前に、 スタックポインターアドレス (ベーススタックポインター) が保存される。
  60 関数のそれぞれの呼び出し後には、 実際のスタックポインターアドレスを読み込み、
  61 ベースポインターアドレスを元に差分を計算する。これらの差分の最大値がスタックのピーク値となる。
  62 .RE
  63 .PP
  64 この概要行の直後には、 監視対象の各関数の呼び出し回数、 割り当て・割り当て解除された全メモリー量、 失敗した回数がテーブルで表示される。
  65 \fBrealloc\fP(3) と \fBmremap\fP(2) の場合には、 フィールド "nomove" でブロックアドレスを変更した再割り当て数を、
  66 フィールド "dec" でブロックサイズが減少した再割り当て数が追加で表示される。 \fBrealloc\fP(3) の場合、 フィールド "free"
  67 でブロックの解放が行われた再割り当て (サイズが 0 の再割り当て) の数も追加で表示される。
  68
  69
  70 \fBmemusage\fP が出力するテーブルの "realloc/total memory" (再割り当てメモリー/全メモリー) には、
  71 \fBrealloc\fP(3) を使ってメモリーブロックをその前よりも小さいサイズに再割り当てされた場合は含まれない。 このため、 ("free" 以外の)
  72 すべての「総メモリー」のセルは "free/total memory" セルよりも大きくなることがある。
  73 .SS ブロックサイズのヒストグラム
  74 "Histogram for block sizes" (ブロックサイズのヒストグラム) は、
  75 メモリー割り当てをバケットサイズ単位に分割した情報である。
  76 .SH オプション
  77 .TP
  78 \fB\-n\ \fP\fIname\fP,\ \fB\-\-progname=\fP\fIname\fP
  79 プロファイル対象のプログラムファイル名。
  80 .TP
  81 \fB\-p\ \fP\fIfile\fP,\ \fB\-\-png=\fP\fIfile\fP
  82 PNG 画像を生成し、 \fIfile\fP に格納する。
  83 .TP
  84 \fB\-d\ \fP\fIfile\fP,\ \fB\-\-data=\fP\fIfile\fP
  85 バイナリーデータファイルを生成し、 \fIfile\fP に格納する。
  86 .TP
  87 \fB\-u\fP,\ \fB\-\-unbuffered\fP
  88 出力バッファリングを行わない。
  89 .TP
  90 \fB\-b\ \fP\fIsize\fP,\ \fB\-\-buffer=\fP\fIsize\fP
  91 出力する前に \fIsize\fP 個のエントリーの収集を行う。
  92 .TP
  93 \fB\-\-no\-timer\fP
  94 スタックポインター値の時間ベースのサンプリング (\fBSIGPROF\fP) を無効にする。
  95 .TP
  96 \fB\-m\fP,\ \fB\-\-mmap\fP
  97 \fBmmap\fP(2), \fBmremap\fP(2), \fBmmap\fP(2) も追跡対象とする。
  98 .TP
  99 \fB\-?\fP,\ \fB\-\-help\fP
 100 ヘルプを表示し、終了する。
 101 .TP
 102 \fB\-\-usage\fP
 103 簡潔な使用方法を表示して終了する。
 104 .TP
 105 \fB\-V\fP,\ \fB\-\-version\fP
 106 バージョン情報を表示して終了する。
 107 .TP
 108 以下のオプションは画像出力を行う場合にのみ適用される。
 109 .TP
 110 \fB\-t\fP,\ \fB\-\-time\-based\fP
 111 X 軸の目盛として (関数呼び出し数ではなく) 時間を使用する。
 112 .TP
 113 \fB\-T\fP,\ \fB\-\-total\fP
 114 メモリーの全使用量のグラフも生成する。
 115 .TP
 116 \fB\-\-title=\fP\fIname\fP
 117 グラフのタイトルとして \fIname\fP を使用する。
 118 .TP
 119 \fB\-x\ \fP\fIsize\fP,\ \fB\-\-x\-size=\fP\fIsize\fP
 120 グラフの幅を \fIsize\fP ピクセルにする。
 121 .TP
 122 \fB\-y\ \fP\fIsize\fP,\ \fB\-\-y\-size=\fP\fIsize\fP
 123 グラフの高さを \fIsize\fP ピクセルにする。
 124 .SH 終了ステータス
 125 終了ステータスはプロファイルしたプログラムの終了ステータスと同じになる。
 126 .SH 例
 127 以下の簡単なプログラムは、 ピークに達するまで繰り返しメモリーブロックの再割り当てを行い、 その後ブロックサイズが 0
 128 になるまで繰り返し順に小さなブロックに再割り当てを行う。 このプログラムをコンパイルして以下のコマンドを実行すると、
 129 このプログラムのメモリ使用量がファイル \fImemusage.png\fP に出力される。
 130
 131 .in +4n
 132 .nf
 133 $ \fBmemusage \-\-data=memusage.dat ./a.out\fP
 134 \&...
 135 Memory usage summary: heap total: 45200, heap peak: 6440, stack peak: 224
 136         total calls  total memory  failed calls
 137  malloc|         1           400             0
 138 realloc|        40         44800             0  (nomove:40, dec:19, free:0)
 139  calloc|         0             0             0
 140    free|         1           440
 141 Histogram for block sizes:
 142   192\-207             1   2% ================
 143 \&...
 144  2192\-2207            1   2% ================
 145  2240\-2255            2   4% =================================
 146  2832\-2847            2   4% =================================
 147  3440\-3455            2   4% =================================
 148  4032\-4047            2   4% =================================
 149  4640\-4655            2   4% =================================
 150  5232\-5247            2   4% =================================
 151  5840\-5855            2   4% =================================
 152  6432\-6447            1   2% ================
 153 $ \fBmemusagestat memusage.dat memusage.png\fP
 154 .fi
 155 .in
 156 .SS プログラムのソース
 157 .nf
 158 #include <stdio.h>
 159 #include <stdlib.h>
 160
 161 #define CYCLES 20
 162
 163 int
 164 main(int argc, char *argv[])
 165 {
 166      int i, j;
 167      int *p;
 168
 169      printf("malloc: %zd\en", sizeof(int) * 100);
 170      p = malloc(sizeof(int) * 100);
 171
 172      for (i = 0; i < CYCLES; i++) {
 173          if (i < CYCLES / 2)
 174              j = i;
 175          else
 176              j\-\-;
 177
 178          printf("realloc: %zd\en", sizeof(int) * (j * 50 + 110));
 179          p = realloc(p, sizeof(int) * (j * 50 + 100));
 180
 181          printf("realloc: %zd\en", sizeof(int) * ((j+1) * 150 + 110));
 182          p = realloc(p, sizeof(int) * ((j + 1) * 150 + 110));
 183      }
 184
 185      free(p);
 186      exit(EXIT_SUCCESS);
 187 }
 188 .fi
 189 .SH バグ
 190 バグ報告については
 191 .UR http://www.gnu.org/software/libc/bugs.html
 192 .UE
 193 を参照のこと。
 194 .SH 関連項目
 195 \fBmemusagestat\fP(1), \fBmtrace\fP(1)  \fBld.so\fP(8)
 196 .SH この文書について
 197 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
 198 である。プロジェクトの説明とバグ報告に関する情報は
 199 http://www.kernel.org/doc/man\-pages/ に書かれている。