日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
LIBMEMSTAT(3) FreeBSD ライブラリ関数マニュアル LIBMEMSTAT(3)
名称
libmemstat -- カーネルメモリアロケータ統計値を検索するライブラリインタ
フェース
ライブラリ
カーネルメモリアロケータ統計ライブラリ (libmemstat, -lmemstat)
書式
#include <sys/types.h>
#include <memstat.h>
一般的関数
const char *
memstat_strerror(int error);
メモリタイプリスト管理関数
struct memory_type_list *
memstat_mtl_alloc(void);
struct memory_type *
memstat_mtl_first(struct memory_type_list *list);
struct memory_type *
memstat_mtl_next(struct memory_type *mtp);
struct memory_type *
memstat_mtl_find(struct memory_type_list *list, int allocator,
const char *name);
void
memstat_mtl_free(struct memory_type_list *list);
int
memstat_mtl_geterror(struct memory_type_list *list);
アロケータ問い合わせ関数
int
memstat_kvm_all(struct memory_type_list *list, void *kvm_handle);
int
memstat_kvm_malloc(struct memory_type_list *list, void *kvm_handle);
int
memstat_kvm_uma(struct memory_type_list *list, void *kvm_handle);
int
memstat_sysctl_all(struct memory_type_list *list, int flags);
int
memstat_sysctl_malloc(struct memory_type_list *list, int flags);
int
memstat_sysctl_uma(struct memory_type_list *list, int flags);
メモリタイプアクセサ方式
const char *
memstat_get_name(const struct memory_type *mtp);
int
memstat_get_allocator(const struct memory_type *mtp);
uint64_t
memstat_get_countlimit(const struct memory_type *mtp);
uint64_t
memstat_get_byteslimit(const struct memory_type *mtp);
uint64_t
memstat_get_sizemask(const struct memory_type *mtp);
uint64_t
memstat_get_size(const struct memory_type *mtp);
uint64_t
memstat_get_rsize(const struct memory_type *mtp);
uint64_t
memstat_get_memalloced(const struct memory_type *mtp);
uint64_t
memstat_get_memfreed(const struct memory_type *mtp);
uint64_t
memstat_get_numallocs(const struct memory_type *mtp);
uint64_t
memstat_get_numfrees(const struct memory_type *mtp);
uint64_t
memstat_get_bytes(const struct memory_type *mtp);
uint64_t
memstat_get_count(const struct memory_type *mtp);
uint64_t
memstat_get_free(const struct memory_type *mtp);
uint64_t
memstat_get_failures(const struct memory_type *mtp);
void *
memstat_get_caller_pointer(const struct memory_type *mtp, int index);
void
memstat_set_caller_pointer(struct memory_type *mtp, int index,
void *value);
uint64_t
memstat_get_caller_uint64(const struct memory_type *mtp, int index);
void
memstat_set_caller_uint64(struct memory_type *mtp, int index,
uint64_t value);
uint64_t
memstat_get_zonefree(const struct memory_type *mtp);
uint64_t
memstat_get_kegfree(const struct memory_type *mtp);
uint64_t
memstat_get_percpu_memalloced(const struct memory_type *mtp, int cpu);
uint64_t
memstat_get_percpu_memfreed(const struct memory_type *mtp, int cpu);
uint64_t
memstat_get_percpu_numallocs(const struct memory_type *mtp, int cpu);
uint64_t
memstat_get_percpu_numfrees(const struct memory_type *mtp, int cpu);
uint64_t
memstat_get_percpu_sizemask(const struct memory_type *mtp, int cpu);
void *
memstat_get_percpu_caller_pointer(const struct memory_type *mtp, int cpu,
int index);
void
memstat_set_percpu_caller_pointer(struct memory_type *mtp, int cpu,
int index, void *value);
uint64_t
memstat_get_percpu_caller_uint64(const struct memory_type *mtp, int cpu,
int index);
void
memstat_set_percpu_caller_uint64(struct memory_type *mtp, int cpu,
int index, uint64_t value);
uint64_t
memstat_get_percpu_free(const struct memory_type *mtp, int cpu);
解説
libmemstat は、デバッグとシステムの監視の目的のために、アロケータの実装細
部からアプリケーションを分離して、ツールが透過的に複数のアロケータをサ
ポートできる、カーネルメモリアロケータ統計を検索するためのインタフェース
を提供します。libmemstat は、長期のモニタで徐々に増える統計の更新と同様
に、単一の統計スナップショットの検索の両方をサポートします。
libmemstat は、ライブラリ中のアクセス関数を使用してアプリケーションによっ
てアクセスされる struct memory_type を使用して各メモリタイプを説明しま
す。libmemstat は、memstat_mtl_alloc() 呼び出すことによって割り付けられ
memstat_mtl_free() を使用して完全に解放される、struct memory_type_list を
通して struct memory_type のチェーンを返して更新します。メモリタイプのリ
ストは、統計情報をカーネルに問い合わせる呼び出しを通して使用できます、現
在は次の通りです: memstat_kvm_all(), memstat_kvm_malloc(),
memstat_kvm_uma(), memstat_sysctl_all(), memstat_sysctl_uma() と
memstat_sysctl_malloc()。繰り返される呼び出しは、すべてのリスト状態を再作
成することなしに、時間とともに追跡できる、メモリタイプのリストを増加して
更新します。エラーが問い合わせ呼び出しの間に検出されるなら、エラー条件情
報は、memstat_mtl_geterror() を使用して検索され、memstat_strerror() を使
用してユーザが読める文字列に変換されます。
リストを解放することは、リスト中のすべてのメモリタイプデータを解放するの
で、リスト中のエントリを指す任意の未解決のポインタを無効にします。リスト
中の struct memory_type は、それぞれ、リスト中の最初のエントリを返す
memstat_mtl_first() と、リスト中の次のエントリを返す memstat_mtl_next()
を使用して繰り返されます。memstat_mtl_find(), は、渡されたパラメータに適
合する最初のエントリへのポインタを返します。
呼び出し側に所有されているフィールドの設定と同様に、統計と特性 (プロパ
ティ) を検索することを含んで、構造体のフィールドにアクセスするための一連
のアクセス方式を提供します。アプリケーションがデータ構造体フィールドに直
接アクセスすることは、サポートされていません。
ライブラリ memory_type フィールド
各 struct memory_type は、使用時の現在の統計と同様に、それが管理される名
前とアロケータを含んで、メモリタイプの説明を保持しています。いくつかの統
計は直接測定され、他は直接測定された統計から得られます。特定のハイレベル
な統計は、割り付けと解放の操作の数のような、すべての利用可能なアロケータ
にわたって存在しています。CPU 毎のキャッシュにおける解放項目の量、または
割り付けの数における管理制限などの、他の測定値は、特定のアロケータだけで
利用可能です。
呼び出し側 memory_type フィールド
struct memory_type は、メモリタイプに従ってポインタと 64 ビットの整数の形
式で、アプリケーションがデータを格納することができるフィールドを含んでい
ます。例えば、アプリケーションの作者は、メモリタイプの長い期間の振る舞い
を追跡するより複雑なデータ構造体を参照する呼び出し側のポインタの 1 つ、ま
たはメモリタイプの状態をレンダリング (表示) するために使用されるウィンド
ウシステムオブジェクトを使用するかもしれません。一般的で CPU 毎の記憶域
は、ポインタと整数の配列の形式で、それぞれ struct memory_type で提供され
ます。配列エントリは、アクセス方式を取得して設定するための index 引数を通
してアクセスされます。index の取り得る値は、0 と MEMSTAT_MAXCALLER の間の
範囲です。
呼び出し側によって所有されているフィールドは、新しい struct memory_type
が割り付けられメモリタイプにアタッチされるとき、0 または NULL に初期化さ
れます。これらのフィールドは、ライブラリによって所有されているフィールド
を更新する問い合わせのあいだも、それらの値を持ち続けます。
アロケータタイプ
現在、libmemstat は、2 つのカーネルアロケータをサポートします: uma(9) の
ための ALLOCATOR_UMA、と malloc(9) のための ALLOCATOR_MALLOC です。これら
の値は、memstat_mtl_find() に渡され、memstat_get_allocator() によって返さ
れます。アロケータ名前スペースの 2 つの追加定数は、次のように定義されま
す: ライブラリエラーの結果として返されるだけの、ALLOCATOR_UNKNOWN と任意
のアロケータに適合する返されたタイプが、memstat_mtl_find() から許可可能で
あると指定するために使用することができる ALLOCATOR_ANY です。
アクセス方式リスト
与えられたメモリタイプのために有効となる次のアクセス方式が定義されていま
す:
memstat_get_name()
メモリタイプの名前を指すポインタを返します。名前のためのメモリ
は、libmemstat によって所有され、memstat_mtl_free() への呼び出し
で有効となります。名前は、単一のアロケータに関してユニークになり
ますが、同じ名前が異なったメモリアロケータによって所有されている
異なったメモリタイプによって使用されるかもしれないことに注意して
ください。
memstat_get_allocator()
メモリタイプを所有しているメモリアロケータのための整数識別子を返
します。
memstat_get_countlimit()
メモリタイプが同時に割り付ける数に管理制限があるなら、それを返し
ます。
memstat_get_byteslimit()
メモリタイプがメモリタイプのために同時に割り付けられるメモリのバ
イト数に管理制限があるなら、それを返します。
memstat_get_sizemask()
メモリタイプが可変の割り付けサイズをサポートするなら、メモリタイ
プのために割り付けられたサイズのビットマスクを返します。
memstat_get_size()
メモリタイプが固定の割り付けサイズをサポートするなら、そのサイズ
を返します。
memstat_get_rsize()
メモリタイプが固定された割り付けサイズをサポートするなら、割り付
けの実際のサイズを返します。実際のサイズは、整列制約または暗黙の
パディングのために要求されたサイズを越えることができます。
memstat_get_memalloced()
存続期間のうちにメモリタイプのために割り付けられたバイトの合計数
を返します。
memstat_get_memfreed()
存続期間のうちにメモリタイプのために解放されたバイトの合計数を返
します。
memstat_get_numallocs()
存続期間のうちにメモリタイプのための割り付けの合計数を返します。
memstat_get_numfrees()
存続期間のうちにメモリタイプのための解放の合計数を返します。
memstat_get_bytes()
メモリタイプに割り付けられた現在のバイト数を返します。
memstat_get_count()
メモリタイプのための割り付けの現在の数を返します。
memstat_get_free()
メモリアロケータがキャッシュをサポートするなら、キャッシュ中の項
目の数を返します。
memstat_get_failures()
メモリアロケータとタイプが割り付けの失敗を許すなら、測定された割
り付け失敗の数を返します。
memstat_get_caller_pointer()
メモリタイプのために呼び出し側によって所有されているポインタを返
します。
memstat_set_caller_pointer()
メモリタイプのために呼び出し側によって所有されているポインタを設
定します。
memstat_get_caller_uint64()
メモリタイプのために呼び出し側によって所有されている整数を返しま
す。
memstat_set_caller_uint64()
メモリタイプのために呼び出し側によって所有されている整数を設定し
ます。
memstat_get_zonefree()
メモリアロケータがマルチレベル割り付け構造体をサポートするなら、
ゾーン中にキャッシュされた項目の数を返します。これらの項目は、直
ちに使用するために完全に構築され利用可能な状態となります。
memstat_get_kegfree()
メモリアロケータがマルチレベル割り付け構造体をサポートするなら、
keg のキャッシュされた項目の数を返します。これらの項目は、部分的
に構築された状態になって、それらを利用可能にすることができる前
に、それ以上の処理を必要とします。
memstat_get_percpu_memalloced()
メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のう
ちに CPU のメモリタイプのために割り付けられたメモリのバイト数を返
します。
memstat_get_percpu_memfreed()
メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のう
ちに CPU のメモリタイプから解放されたメモリのバイト数を返します。
memstat_get_percpu_numallocs()
メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のう
ちに CPU のメモリタイプのための割り付けの数を返します。
memstat_get_percpu_numfrees()
メモリアロケータが CPU ごとの統計をサポートするなら、存続期間のう
ちに CPU のメモリタイプのための解放の数を返します。
memstat_get_percpu_sizemask()
メモリアロケータが可変サイズメモリ割り付けと CPU ごとの統計をサ
ポートするなら、CPU のメモリタイプのためのサイズビットマスクを返
します。
memstat_get_percpu_caller_pointer()
メモリタイプのための呼び出し側によって所有されている CPU ごとのポ
インタを返します。
memstat_set_percpu_caller_pointer()
メモリタイプのための呼び出し側によって所有されている CPU ごとのポ
インタを設定します。
memstat_get_percpu_caller_uint64()
メモリタイプのための呼び出し側によって所有されている CPU ごとの整
数を返します。
memstat_set_percpu_caller_uint64()
メモリタイプのための呼び出し側によって所有されている CPU ごとの整
数を設定します。
memstat_get_percpu_free()
メモリアロケータが CPU ごとのキャッシュをサポートするなら、指定さ
れた CPU の CPU ごとのキャッシュにおける解放項目の数を返します。
戻り値
libmemstat 関数は 3 つのカテゴリに分類されます: オブジェクトへのポインタ
を返す関数、整数の戻り値を返す関数、と struct memory_type からデータを返
すアクセス方式を実装する関数。
一般的に、オブジェクトへのポインタを返す関数は、失敗するとき NULL を返し
ます。memstat_mtl_alloc() は、値 ENOMEM から成る errno を通してエラー値を
返します。関数 memstat_mtl_first(), memstat_mtl_next() と
memstat_mtl_find() は、エントリがないか、または次のリストに適合するとき、
NULL を返します。しかしながら、これは失敗モードであるとみなされず、エラー
値は利用可能ではありません。
整数の戻り値を返す関数は、成功すれば 0 を返すか、または失敗すれば -1 を返
します。失敗が返えされるなら、リストエラーアクセス方式
memstat_mtl_geterror() は、エラー状態を検索するために使用されます。エラー
の文字列表現は、memstat_strerror() を使用して検索されます。起こり得るエ
ラー値は次の通りです:
MEMSTAT_ERROR_UNDEFINED 未定義エラー。memstat_mtl_geterror() がリス
トで呼び出されるなら、リストに関連しているエ
ラーが発生する前に、起こります。
MEMSTAT_ERROR_NOMEMORY メモリ不足。malloc(3) へのライブラリ呼び出し
が失敗するか、またはカーネル統計を検索するシ
ステムコールが ENOMEM で失敗するなら、起こり
ます。
MEMSTAT_ERROR_VERSION libmemstat の現在の版が明らかなバージョンの
ミスマッチか、調整することができないデータ構
造体の違いのために、カーネルによって返された
統計データを解釈することができないなら、返さ
れます。
MEMSTAT_ERROR_PERMISSION 統計ソースが EACCES または EPERM の errno 値
を返すなら、返されます。
MEMSTAT_ERROR_DATAERROR バージョン問題があるように見えないけれども、
libmemstat がデータソースによって返された統
計データを解釈することができないなら、返され
ます。
MEMSTAT_ERROR_KVM 統計データを問い合わせるために kvm(3) インタ
フェースを使用している間に libmemstat がエ
ラーに直面するなら、返ります。エラーの検索た
めには kvm_geterr(3) を使用してください。
MEMSTAT_ERROR_KVM_NOSYMBOL 動作しているカーネルから必要なシンボルを読み
込むことができないなら、libmemstat は返りま
す。
MEMSTAT_ERROR_KVM_SHORTREAD libmemstat が、生のメモリイメージまたはカー
ネルコアダンプからデータを読み込みを試みて、
不十分なデータを返すなら、返ります。
最終に、struct memory_type ポインタからデータを返す関数は、失敗することは
許されず、統計値か文字列へのポインタのいずれかを直接返します。
使用例
メモリタイプリストを作成し、利用可能な統計のための uma(9) メモリアロケー
タについて問い合わせをおこない、そして、mbuf ゾーンによって実行された割り
付けの数を印刷 (表示) します。
struct memory_type_list *mtlp;
struct memory_type *mtp;
uint64_t mbuf_count;
mtlp = memstat_mtl_alloc();
if (mtlp == NULL)
err(-1, "memstat_mtl_alloc");
if (memstat_sysctl_uma(mtlp, 0) < 0)
err(-1, "memstat_sysctl_uma");
mtp = memstat_mtl_find(mtlp, ALLOCATOR_UMA, "mbuf");
if (mtp == NULL)
errx(-1, "memstat_mtl_find: mbuf not found");
mbuf_count = memstat_get_count(mtp);
memstat_mtl_free(mtlp);
printf("mbufs: %llu\n", (unsigned long long)mbuf_count);
関連項目
malloc(9), uma(9)
歴史
libmemstat ライブラリは、FreeBSD 6.0 で登場しました。
作者
汎用のモニタリングライブラリをサポートするために必要なカーネルメモリアロ
ケータの変更は、ライブラリとともに、Robert Watson <rwatson@FreeBSD.org>
によって書かれました。
バグ
カーネルには、現在、libmemstat によってサポートされていない、VM ページア
ロケータや sf_buf アロケータなどのような、メモリアロケータがあります。
いったん、メモリタイプがメモリタイプリストに存在しているなら、カーネルが
インタフェースをモニタすることを通してタイプに情報がすでに存在しなくて
も、それを取り除きません。取り除かれたメモリタイプをフラッシュするため
に、全体のリストを解放して、新しいものを割り付けることが必要です。
FreeBSD 11.2 February 11, 2014 FreeBSD 11.2