# 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

# 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_EXPORT

DLL エクスポート/インポート制御マクロ。

ビルド条件に応じて以下の値を取ります。

条件 | 値
--- | ---
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;

ファイルトレースプロバイダハンドル (不透明型)。