名称
libcrash ― クラッシュダンプへのアクセスライブラリ
構文
#include <libcrash.h>
int cr_open(const char *path, CRASH **cb, int flags);
int cr_verify(CRASH *crash_cb, int flags);
cr_info_t *cr_info(CRASH *crash_cb);
int cr_uncompress(CRASH *crash_cb, const char *pathname,
uint64_t size, int flags);
int cr_isaddr(CRASH *crash_cb, uint64_t pagenum, int *avail);
int cr_read(CRASH *crash_cb, void *buf, uint64_t mem_page,
int *num_pages);
int cr_set_node(CRASH *crash_cb, int node_num,
int *old_node_num);
void cr_perror(CRASH *crash_cb, int error);
int cr_close(CRASH *crash_cb);
説明
libcrash は、システムクラッシュ ダンプへのアクセスとして機能するライブラリです。
このライブラリを通してダンプにアクセスする場合は、クラッシュダンプのフォーマット
(以下に説明するように、いくつかあります) には依存しません。また、ダンプの位置にも依存しません。
ダンプは raw ダンプデバイス上にあっても、ファイルシステム内のファイルの中にあっても、またはその両方にあってもかまいません。
実行しているシステムのメモリは、 /dev/mem ドライバーを使って「ダンプ」として扱うこともできます。
このライブラリによるダンプへのアクセスはすべて、 cr_open() を呼び出して開始されます。この呼び出しによって戻されるクラッシュダンプ記述子は、他の libcrash を呼び出すときに必要なパラメータです。このような記述子には、次のものがあります。
| cr_verify() | | ダンプを構成するすべてのファイルのサイズとチェックサムを調べて、ダンプの整合性を検証します。 |
| cr_info() | | ダンプに関する情報と、それを生成したマシンおよびカーネルに関する情報の入っている構造体へのポインタを戻します。 |
| cr_uncompress() | | クラッシュダンプ内のファイルを圧縮解除し (必要な場合)、そのサイズとチェックサムを確認することによって、そのファイルが使用できるように準備します。この関数はライブラリが物理メモリイメージにアクセスするために内部的に使用されますが、呼び出し側がカーネルとカーネルモジュール
ファイルにアクセスする場合にも使用できます。 |
| cr_isaddr() | | ある物理メモリページがダンプしたマシン上で有効かどうか、また有効な場合には、そのページの内容がダンプ内に含まれているかどうかについて情報を提供します。 |
| cr_read() | | ダンプからページを読み取ります。 |
| cr_set_node() | | ノードのプライベートメモリ領域内のメモリにアクセスするために cr_read() および cr_isaddr() によって使用されるノード番号を設定します。 |
| cr_perror() | | 別のライブラリ呼び出しによって戻されたエラーコードまたは警告コードの
1 つに一致するエラーメッセージまたは警告メッセージを標準エラーに印刷します。 |
| cr_close() | | クラッシュダンプへのアクセスを終了して、ライブラリによって割り当てられたスペースをすべて解放します。 |
上記の呼び出しには、その使用法を詳しく説明したそれぞれ専用のマニュアルページがあります。
クラッシュダンプのフォーマット
システムクラッシュ ダンプには、次の 4 つのフォーマットがあります。
| COREFILE | | (バージョン 0) HP-UX 10.01 まで使われるこのフォーマットは、ファイルオフセットとメモリアドレスが
1 対 1 で対応している物理メモリイメージの入った単一ファイルで構成されます。通常は、カーネルイメージを含んだファイルが
1 つ関連付けられています。 |
| COREDIR | | (バージョン 1) このフォーマットは HP-UX 10.10、10.20
および 10.30 で使われており、1 つの core.n ディレクトリで構成されます。このディレクトリには、 INDEX ファイル、カーネル
(vmunix) ファイル、および物理メモリイメージの各部分を収めている多数の core.n.m ファイルが入っています。 |
| CRASHDIR | | (バージョン 2) このフォーマットは HP-UX 11.00 およびそれ以降で使われており、1
つの crash.n ディレクトリで構成されます。このディレクトリには、 INDEX ファイル、カーネルファイルおよび動的にロードされたすべてのカーネルモジュール
ファイル、および物理メモリイメージの各部分とメタデータ (どのメモリページをダンプし、どれをダンプしていないかを記述したもの)
を収めた多数の image.m.p ファイルが入っています。 |
| PARDIR | | (バージョン 5) このフォーマットは、 HP-UX 11i Version
1.0 以降のリリースで使用されます。 その構成は、 CRASHDIR とほぼ同じで、 INDEX ファイル、カーネルとすべての動的ロードされたカーネルモジュール
ファイル、 および、 物理メモリーイメージとメタデータ (ダンプされたメモリーページとダンプされなかったメモリーページが記述されている)
を含む多数の image.m.p ファイルが crash.n ディレクトリに置かれます。 プライマリ INDEX ファイルに加えて、メモリーページを含むイメージファイルを記述しているメタデータを含む補助インデクスファイルがあります。
ダンプデバイスが圧縮されたメモリーイメージを持つ場合に、この形式が使用されます。
詳細については、 crashconf(1M) を参照してください。 |
その他のフォーマット (例えば、テープアーカイブ用フォーマット)
は、将来追加される可能性があります。
キャッシュ
PARDIR フォーマットのクラッシュダンプの解析性能を改善するために、キャッシュ機能が実装されています。
キャッシュ機能によって、圧縮されていないページを保持し、その後の解析処理ではキャッシュデータが使用されます。
デフォルトでは、このキャッシュ機能は使用しないように設定されており、
環境変数 LIBCRASH_ENABLE_CACHE を設定すると、この機能を有効にできます。
キャッシュファイルは、クラッシュダンプディレクトリ内に作成されます。
戻り値
libcrash 内のほとんどの呼び出しは、整数ステータス値を戻します。戻り値ゼロは、正常に終了したことを意味します。正の戻り値は、要求した操作が完了したにもかかわらず、何らかの警告があったことを意味します。負の戻り値は、エラーが発生して、要求した操作が完了しなかったことを意味します。ライブラリによって戻される値には、次のものがあります。
| CR_OK | | 正常に終了しました。 |
| CRWARN_NOEXPECTED |
| | | クラッシュダンプ内の 1 つ、または複数のファイルの予想サイズまたはチェックサムが記録されなかったため、ダンプの整合性は検証できません。ダンプが破壊された可能性があります。 |
| CRWARN_NOACTUAL | | クラッシュダンプ内の 1 つ、または複数のファイルのチェックサムが計算できなかったため、チェックサムを予想値に照合させてチェックできませんでした。ダンプが破壊された可能性があります。 |
| CRWARN_SWAPPEDON |
| | | クラッシュダンプの 1 部分を含んでいる raw デバイスがスワップされたため、ダンプはおそらく破壊されました。 |
| CRWARN_MISMATCH | | クラッシュダンプ内の 1 つ、または複数のファイルのサイズまたはチェックサムが、予想されるものと一致しませんでした。ダンプはおそらく破壊されています。 |
| CRERR_NOPAGE | | ターゲットマシンに存在しないメモリアドレスに対する読み取り要求または書き込み要求が出されました。 |
| CRERR_READONLY | | クラッシュダンプに対して書き込み要求が出されました。書き込みがサポートされているのは、 /dev/mem ドライバーを通して実行しているシステムだけです。 |
| CRERR_WRONGDUMP | | ダンプの一部を含んでいるものと想定される raw ダンプデバイスに、それが含まれていません。raw
ダンプデバイスはスワップ操作によって、またはその後のダンプによって上書きされた可能性があります。 |
| CRERR_WRONGHOST | | クラッシュダンプの一部は、ダンプを実行したシステムのダンプデバイスにまだ常駐していますが、これは現在のシステムではありません。 |
| CRERR_NONODE | | 指定されたノード番号は存在しません。 |
| CRERR_ERRNO | | システムエラーが発生しました。特定のエラーについては、 errno を調べてください。 errno のいくつかの値は、ライブラリのコンテキストで特定の意味を持っています。これらの特定の値には、次のものがあります。 | [ENOEXEC] | | クラッシュダンプの一部が圧縮解除できませんでした。 | | [ENOTDIR] | | ダンプに対して指定されたパス名はプレーンファイルでも、INDEX
ファイルを含んでいるディレクトリでも、 /dev/mem 疑似ドライバーでもありません。 |
|
| \ | | errno のその他の値には、従来の意味が備わっています。 |
著者
libcrash は、HP で開発されました。
参照
cr_close(3), cr_info(3), cr_isaddr(3), cr_open(3), cr_perror(3),
cr_read(3), cr_set_node(3), cr_uncompress(3), cr_verify(3)