util/include/trace-file-util.h
1 ファイル
1.1 util/include/trace-file-util.h
ファイルベーストレースプロバイダライブラリ。
トレースメッセージをローテーション付きテキストファイルへ同期書き込みする クロスプラットフォームプロバイダです。
trace-etw-util (Windows ETW) および trace-syslog-util (Linux syslog) と 同じ init / write / dispose インターフェースを提供します。
1.1.1 出力フォーマット
2026-03-31 12:34:56.789 I メッセージテキストレベル文字: C=CRITICAL / E=ERROR / W=WARNING / I=INFO / V=VERBOSE
1.1.2 インクルード元
2 関数
2.1 trace_file_provider_init
TRACE_FILE_UTIL_EXPORTtrace_file_provider_t *TRACE_FILE_UTIL_API trace_file_provider_init ( const char *path, size_t max_bytes, int generations )ファイルトレースプロバイダを初期化する。
指定されたファイルパスへの書き込みを開始します。
ファイルが存在する場合は追記します。存在しない場合は新規作成します。
max_bytes に 0 を指定した場合は TRACE_FILE_DEFAULT_MAX_BYTES を使用します。
generations に 0 以下を指定した場合は TRACE_FILE_DEFAULT_GENERATIONS を使用します。
2.1.1 引数
- path [in] 出力ファイルパス。NULL の場合は NULL を返します。
- max_bytes [in] 1 ファイルあたりの最大バイト数。0 でデフォルト値を使用。
- generations [in] 保持する旧世代数。0 以下でデフォルト値を使用。
2.1.2 戻り値
成功時: ハンドル。失敗時: NULL。
2.1.3 ローテーション動作
書き込み後にファイルサイズが max_bytes に達すると、以下の名前でファイルを保持します。
path ... 現在のトレースファイル (新規作成)
path.1 ... 直前の世代
path.2 ... 2 世代前
path.N ... N 世代前 (N = generations)generations 世代を超えた古いファイルは削除されます。
2.1.4 使用例
trace_file_provider_t *h = trace_file_provider_init(
"C:\\logs\\myapp.log", 0, 0);2.2 trace_file_provider_write
TRACE_FILE_UTIL_EXPORT int TRACE_FILE_UTIL_API trace_file_provider_write ( trace_file_provider_t *handle, int level, const char *message )ファイルへトレースメッセージを書き込む。
タイムスタンプとトレースレベル文字を付加し 1 行で書き込みます。
書き込み後にファイルサイズが max_bytes に達した場合はローテーションします。
handle または message が NULL の場合は何もせず 0 を返します。
ファイルがロックされている等の I/O 失敗は呼び出し元をブロックせず -1 を返します。
2.2.1 引数
- handle [in] trace_file_provider_init の戻り値。NULL は無視。
- level [in] トレースレベル (TRACE_FILE_LV_* 定数)。
- message [in] null 終端 UTF-8 文字列。NULL は無視。
2.2.2 戻り値
成功 0 / 失敗 -1。
2.3 trace_file_provider_dispose
TRACE_FILE_UTIL_EXPORT void TRACE_FILE_UTIL_API trace_file_provider_dispose ( trace_file_provider_t *handle )ファイルトレースプロバイダを終了する。
ファイルハンドルを閉じ、ロック / mutex を解放してメモリを解放します。
ハンドルが NULL の場合は何もしません。
2.3.1 引数
- handle [in] trace_file_provider_init の戻り値。
3 定数、マクロ
3.1 TRACE_FILE_LV_CRITICAL
#define TRACE_FILE_LV_CRITICAL 0致命的エラー (trace-util.h の TRACE_LV_CRITICAL と同値)。
3.2 TRACE_FILE_LV_ERROR
#define TRACE_FILE_LV_ERROR 1エラー (trace-util.h の TRACE_LV_ERROR と同値)。
3.3 TRACE_FILE_LV_WARNING
#define TRACE_FILE_LV_WARNING 2警告 (trace-util.h の TRACE_LV_WARNING と同値)。
3.4 TRACE_FILE_LV_INFO
#define TRACE_FILE_LV_INFO 3情報 (trace-util.h の TRACE_LV_INFO と同値)。
3.5 TRACE_FILE_LV_VERBOSE
#define TRACE_FILE_LV_VERBOSE 4詳細 / デバッグ (trace-util.h の TRACE_LV_VERBOSE と同値)。
3.6 TRACE_FILE_UTIL_EXPORT
#define TRACE_FILE_UTIL_EXPORTDLL エクスポート/インポート制御マクロ。
ビルド条件に応じて以下の値を取ります。
| 条件 | 値 |
|---|---|
| Linux (非 Windows) | (空) |
Windows / __INTELLISENSE__ 定義時 |
(空) |
Windows / TRACE_FILE_UTIL_STATIC 定義時 (静的リンク) |
(空) |
Windows / TRACE_FILE_UTIL_EXPORTS 定義時 (DLL ビルド) |
__declspec(dllexport) |
Windows / TRACE_FILE_UTIL_EXPORTS 未定義時 (DLL 利用側) |
__declspec(dllimport) |
3.7 TRACE_FILE_UTIL_API
#define TRACE_FILE_UTIL_API呼び出し規約マクロ。
Windows 環境では __stdcall 呼び出し規約を指定します。
Linux (非 Windows) 環境では空に展開されます。
既に定義済みの場合は再定義されません。
3.8 TRACE_FILE_DEFAULT_MAX_BYTES
#define TRACE_FILE_DEFAULT_MAX_BYTES ((size_t)(10 * 1024 * 1024))トレースファイル 1 世代あたりの既定最大サイズ (バイト)。
この値を超えるとローテーションが実行されます。
trace_file_provider_init の max_bytes に 0 を指定した場合に使用されます。
3.9 TRACE_FILE_DEFAULT_GENERATIONS
#define TRACE_FILE_DEFAULT_GENERATIONS 5保持するトレースファイル世代数の既定値。
ローテーション時に path.1 〜 path.N のファイルを保持します。
trace_file_provider_init の generations に 0 以下を指定した場合に使用されます。
4 型
4.1 trace_file_provider_t
typedef struct trace_file_provider trace_file_provider_t;ファイルトレースプロバイダハンドル (不透明型)。