# util/include/trace-util.h

# 1 ファイル

## 1.1 util/include/trace-util.h

クロスプラットフォーム トレーシング API。

Windows (ETW) と Linux (syslog) の差異を抽象化し、 共通のトレースレベルとインターフェースを提供します。
内部で `trace-etw-util.h` (Windows) または `trace-syslog-util.h` (Linux) を 使用します。

### 1.1.1 作者

c-modernization-kit sample team

### 1.1.2 バージョン

1.0.0

### 1.1.3 日付

2026/03/05

### 1.1.4 アーキテクチャ

    Application
          |
          v
    trace-util.h (共通 API)
          |
    +-----+-----+------+--------+
    |           |      |        |
    ETW        syslog File    stderr
    (Windows)  (Linux) (両OS)  (両OS)

### 1.1.5 使用例 (共通)

    #include <trace-util.h>

    trace_provider_t *logger = trace_init();
    trace_modify_name(logger, "myapp", 0);
    trace_start(logger);
    trace_write(logger, TRACE_LV_INFO, "application started");
    trace_stop(logger);
    trace_dispose(logger);

### 1.1.6 使用例 (設定変更)

    trace_provider_t *logger = trace_init();
    trace_modify_name(logger, "myapp", 0);
    trace_modify_ostrc(logger, TRACE_LV_VERBOSE);
    trace_start(logger);
    trace_write(logger, TRACE_LV_INFO, "running as myapp");
    trace_stop(logger);
    trace_modify_name(logger, "myapp", 1); // "myapp-1" として再開
    trace_start(logger);
    trace_write(logger, TRACE_LV_INFO, "running as myapp-1");
    trace_stop(logger);
    trace_dispose(logger);

### 1.1.7 著作権

Copyright (C) CompanyName, Ltd. 2026. All rights reserved.

# 2 関数

## 2.1 trace_init

    TRACE_UTIL_EXPORTtrace_provider_t *TRACE_UTIL_API trace_init ( void )

トレースプロバイダを初期化する。

自プロセスの実行ファイル名をデフォルト識別名として初期化します (例: Linux `/usr/bin/myapp` → `"myapp"`, Windows `C:\bin\myapp.exe` → `"myapp.exe"`)。
プロセス名の取得に失敗した場合は `"unknown"` を使用します。
Linux 環境では syslog を LOG_USER facility で初期化します。
Windows 環境ではライブラリ内蔵の ETW デフォルトプロバイダ (`TRACE_DEFAULT_PROVIDER_NAME`) を使用します。
識別名を変更するには trace_modify_name を呼び出してください。

### 2.1.1 戻り値

成功時: ハンドル (stopped 状態)。失敗時: NULL。

### 2.1.2 事後条件

戻り値のハンドルは stopped 状態です。 出力関数を使用するには trace_start を呼び出してください。
stopped 状態では設定関数 (trace_modify_name, trace_modify_ostrc, trace_modify_filetrc, trace_modify_stderrtrc) をスレッド安全に使用できます。

### 2.1.3 使用例

    trace_provider_t *logger = trace_init();
    trace_modify_name(logger, "myapp", 0);
    trace_start(logger);
    trace_write(logger, TRACE_LV_INFO, "application started");
    trace_stop(logger);
    trace_dispose(logger);

### 2.1.4 スレッド セーフティ

本関数はスレッドセーフです。
複数スレッドから独立したハンドルを取得するために並行して呼び出すことができます。

## 2.2 trace_start

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_start ( trace_provider_t *handle )

トレースプロバイダを開始する。

ハンドルを実行中 (started) 状態に遷移させます。
started 状態では出力関数 (trace_write 等) が有効になり、 設定関数 (trace_modify_name, trace_modify_ostrc, trace_modify_filetrc, trace_modify_stderrtrc) は使用できなくなります (-1 を返します)。
既に started 状態の場合は何もせず 0 を返します (冪等)。

### 2.2.1 引数

- handle [in] trace_init の戻り値。

### 2.2.2 戻り値

成功 0 / 失敗 -1。

### 2.2.3 警告

handle が NULL の場合は -1 を返します。

### 2.2.4 スレッド セーフティ

本関数はスレッドセーフです。
内部で排他制御を行います。

### 2.2.5 参照

trace_stop

## 2.3 trace_stop

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_stop ( trace_provider_t *handle )

トレースプロバイダを停止する。

ハンドルを停止中 (stopped) 状態に遷移させます。
stopped 状態では出力関数 (trace_write 等) は -1 を返し、 設定関数 (trace_modify_name, trace_modify_ostrc, trace_modify_filetrc, trace_modify_stderrtrc) がスレッド安全に使用できるようになります。
既に stopped 状態の場合は何もせず 0 を返します (冪等)。

### 2.3.1 引数

- handle [in] trace_init の戻り値。

### 2.3.2 戻り値

成功 0 / 失敗 -1。

### 2.3.3 警告

handle が NULL の場合は -1 を返します。

### 2.3.4 スレッド セーフティ

本関数はスレッドセーフです。
内部で排他制御を行います。

### 2.3.5 参照

trace_start

## 2.4 trace_write

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_write ( trace_provider_t *handle, enum trace_level level, const char *message )

トレースメッセージを書き込む。

指定されたトレースレベルでメッセージを書き込みます。
内部で enum trace_level を ETW Level または syslog severity に マッピングして書き込みます。

### 2.4.1 引数

- handle [in] trace_init の戻り値。
- level [in] トレースレベル (enum trace_level)。
- message [in] null 終端 UTF-8 文字列。

### 2.4.2 戻り値

成功 0 / 失敗 -1。

### 2.4.3 補足

メッセージが `TRACE_MESSAGE_MAX_BYTES` (1,024) バイト (null 終端含む) を超える場合、本関数は内部で 1,023 バイト以内に切り詰めて下層 API に渡します。
切り詰め時は UTF-8 マルチバイト文字の途中で切断しないよう バイト境界を調整します。
この上限は ETW (約 65,000 バイト) と syslog (RFC 3164: 1,024 バイト) の推奨値のうち小さい方に合わせています。

### 2.4.4 警告

handle が NULL の場合は何もせず 0 を返します。
message が NULL の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。

### 2.4.5 事前条件

ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。

### 2.4.6 スレッド セーフティ

本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。

## 2.5 trace_writef

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_writef ( trace_provider_t *handle, enum trace_level level, const char *format, ... )

printf 形式でトレースメッセージを書き込む。

フォーマット文字列と可変長引数で構成されたメッセージを書き込みます。
内部で `vsnprintf` を使用し、`TRACE_MESSAGE_MAX_BYTES` (1,024) バイトの バッファにフォーマットします。バッファを超える部分は切り詰められます。

### 2.5.1 引数

- handle [in] trace_init の戻り値。
- level [in] トレースレベル (enum trace_level)。
- format [in] printf 形式のフォーマット文字列。
- … [in] フォーマット文字列に対応する可変長引数。

### 2.5.2 戻り値

成功 0 / 失敗 -1。

### 2.5.3 警告

handle が NULL の場合は何もせず 0 を返します。
format が NULL の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。

### 2.5.4 事前条件

ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。

### 2.5.5 使用例

    trace_writef(logger, TRACE_LV_INFO, "user=%s count=%d", username, count);

### 2.5.6 スレッド セーフティ

本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。

## 2.6 trace_hex_write

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_hex_write ( trace_provider_t *handle, enum trace_level level, const void *data, size_t size, const char *message )

バイナリデータを HEX テキスト形式でトレースに書き込む。

バイナリデータを大文字スペース区切りの HEX 文字列に変換して トレースに書き込みます。`message` が非 NULL の場合はラベルとして 先頭に付与されます。
ラベルなしの場合、最大 `TRACE_HEX_MAX_DATA_BYTES` (341) バイトの バイナリデータを出力できます。ラベル指定時はラベル長 + セパレータ (“:”, 2 バイト) 分だけ出力可能なデータ量が減少します。
データが収まらない場合は切り詰め、末尾に `"..."` を付与します。

### 2.6.1 引数

- handle [in] trace_init の戻り値。
- level [in] トレースレベル (enum trace_level)。
- data [in] バイナリデータへのポインタ。
- size [in] バイナリデータのバイト数。
- message [in] HEX データの手前に付与するラベル文字列。 NULL の場合はラベルなしで HEX のみ出力します。

### 2.6.2 戻り値

成功 0 / 失敗 -1。

### 2.6.3 警告

handle が NULL の場合は何もせず 0 を返します。
data が NULL の場合は何もせず 0 を返します。
size が 0 の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。

### 2.6.4 事前条件

ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。

### 2.6.5 出力フォーマット

    // message 指定あり (全データ表示):
    "Received data: 48 65 6C 6C 6F"

    // message が NULL (全データ表示):
    "48 65 6C 6C 6F"

    // データが収まらない場合 (切り詰め):
    "Received data: 48 65 6C ..."

### 2.6.6 スレッド セーフティ

本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。

## 2.7 trace_hex_writef

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_hex_writef ( trace_provider_t *handle, enum trace_level level, const void *data, size_t size, const char *format, ... )

バイナリデータを HEX テキスト形式でトレースに書き込む (printf 形式ラベル)。

trace_hex_write と同等ですが、ラベル文字列を printf 形式の フォーマット文字列と可変長引数で指定できます。

### 2.7.1 引数

- handle [in] trace_init の戻り値。
- level [in] トレースレベル (enum trace_level)。
- data [in] バイナリデータへのポインタ。
- size [in] バイナリデータのバイト数。
- format [in] printf 形式のフォーマット文字列 (ラベル)。 NULL の場合はラベルなしで HEX のみ出力します。
- … [in] フォーマット文字列に対応する可変長引数。

### 2.7.2 戻り値

成功 0 / 失敗 -1。

### 2.7.3 警告

handle が NULL の場合は何もせず 0 を返します。
data が NULL の場合は何もせず 0 を返します。
size が 0 の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。

### 2.7.4 事前条件

ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。

### 2.7.5 出力フォーマット

    // フォーマット済みラベル付き:
    "packet[3]: 48 65 6C 6C 6F"

    // データが収まらない場合:
    "packet[3]: 48 65 6C ..."

### 2.7.6 使用例

    trace_hex_writef(logger, TRACE_LV_INFO, data, len, "packet[%d]", index);

### 2.7.7 スレッド セーフティ

本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。

### 2.7.8 参照

trace_hex_write

## 2.8 trace_modify_name

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_modify_name ( trace_provider_t *handle, const char *name, int64_t identifier )

トレースプロバイダの識別名と識別番号を設定する。

初期化済みのハンドルを維持したまま、識別名と識別番号を変更します。
内部識別名は `name` と `identifier` から以下のルールで生成します。

- `identifier``==``0` : 識別名 = `name` そのもの

- `identifier``>``0` : 識別名 = `"<name>-<identifier>"` (ハイフン区切り)

- `identifier``<``0` : -1 を返す (無効値)
  Linux 環境では内部で closelog / openlog が呼び出されます。
  Windows 環境では ETW イベントの “Service” フィールド値のみが変更されます。

### 2.8.1 引数

- handle [in] trace_init の戻り値。
- name [in] ベース識別名。
  NULL の場合は自プロセスの実行ファイル名を使用します (trace_init と同じ動作)。
- identifier [in] アプリケーション管理識別番号 (0 以上)。
  0 の場合は `name` をそのまま使用します。
  正の値の場合は `"<name>-<identifier>"` を識別名とします。
  負の値の場合は -1 を返します。

### 2.8.2 戻り値

成功 0 / 失敗 (無効な引数・メモリ確保失敗等) -1。

### 2.8.3 警告

handle が NULL の場合は -1 を返します。
identifier に負の値を指定した場合は -1 を返します。
started 状態では -1 を返します。

### 2.8.4 事前条件

ハンドルが stopped 状態であること。 started 状態では -1 を返します。

### 2.8.5 使用例

    trace_provider_t *logger = trace_init();
    trace_modify_name(logger, "worker", 2); // 識別名 = "worker-2"
    trace_start(logger);
    trace_write(logger, TRACE_LV_INFO, "running as worker-2");
    trace_dispose(logger);

### 2.8.6 スレッド セーフティ

stopped 状態ではスレッドセーフです。
内部で排他制御を行います。

## 2.9 trace_modify_ostrc

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_modify_ostrc ( trace_provider_t *handle, enum trace_level level )

OS トレースのスレッショルドレベルを設定する。

ETW (Windows) または syslog (Linux) に出力するメッセージの 最低重要度レベルを変更します。
デフォルト値は `TRACE_DEFAULT_OS_LEVEL` (TRACE_LV_INFO) です。
`TRACE_LV_NONE` を指定すると OS トレース出力を完全に抑止します。

### 2.9.1 引数

- handle [in] trace_init の戻り値。
- level [in] 新しいスレッショルドレベル (enum trace_level)。

### 2.9.2 戻り値

成功 0 / 失敗 -1。

### 2.9.3 警告

handle が NULL の場合は -1 を返します。
started 状態では -1 を返します。

### 2.9.4 事前条件

ハンドルが stopped 状態であること。 started 状態では -1 を返します。

### 2.9.5 スレッド セーフティ

stopped 状態ではスレッドセーフです。
内部で排他制御を行います。

## 2.10 trace_modify_filetrc

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_modify_filetrc ( trace_provider_t *handle, const char *path, enum trace_level level, size_t max_bytes, int generations )

ファイルトレースの出力先と設定を変更する。

ファイルトレースを有効化または再構成します。
`path` に NULL を指定するとファイルトレースを無効化します (既存のファイルプロバイダを解放して閉じます)。
既にファイルトレースが有効な場合は既存のプロバイダを解放してから 新しいプロバイダを初期化します。
デフォルトのファイルトレースレベルは `TRACE_DEFAULT_FILE_LEVEL` (TRACE_LV_ERROR) です。
ファイルトレースは trace_init の直後は無効 (パス未指定) です。

### 2.10.1 引数

- handle [in] trace_init の戻り値。
- path [in] 出力ファイルパス。NULL の場合はファイルトレースを無効化。
- level [in] ファイルトレースのスレッショルドレベル (enum trace_level)。
- max_bytes [in] 1 ファイルあたりの最大バイト数。0 で既定値 (TRACE_FILE_DEFAULT_MAX_BYTES = 10 MB) を使用。
- generations [in] 保持する旧世代数。0 以下で既定値 (TRACE_FILE_DEFAULT_GENERATIONS = 5) を使用。

### 2.10.2 戻り値

成功 0 / 失敗 -1。

### 2.10.3 警告

handle が NULL の場合は -1 を返します。
started 状態では -1 を返します。
path に指定したファイルが書き込み不可の場合は -1 を返します。

### 2.10.4 事前条件

ハンドルが stopped 状態であること。 started 状態では -1 を返します。

### 2.10.5 スレッド セーフティ

stopped 状態ではスレッドセーフです。
内部で排他制御を行います。

## 2.11 trace_modify_stderrtrc

    TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_modify_stderrtrc ( trace_provider_t *handle, enum trace_level level )

stderr トレースのスレッショルドレベルを設定する。

標準エラー出力 (stderr) に出力するメッセージの最低重要度レベルを変更します。
出力フォーマットはファイルトレースと同一です。

    2026-04-02 12:34:56.789 I メッセージテキスト

タイムスタンプは UTC です。
デフォルト値は `TRACE_DEFAULT_STDERR_LEVEL` (TRACE_LV_NONE: 無効) です。
`TRACE_LV_NONE` を指定すると stderr 出力を完全に抑止します。

### 2.11.1 引数

- handle [in] trace_init の戻り値。
- level [in] 新しいスレッショルドレベル (enum trace_level)。

### 2.11.2 戻り値

成功 0 / 失敗 -1。

### 2.11.3 警告

handle が NULL の場合は -1 を返します。
started 状態では -1 を返します。

### 2.11.4 事前条件

ハンドルが stopped 状態であること。 started 状態では -1 を返します。

### 2.11.5 スレッド セーフティ

stopped 状態ではスレッドセーフです。
内部で排他制御を行います。

## 2.12 trace_get_ostrc

    TRACE_UTIL_EXPORT enum trace_levelTRACE_UTIL_API trace_get_ostrc ( trace_provider_t *handle )

OS トレースの現在のスレッショルドレベルを取得する。

### 2.12.1 引数

- handle [in] trace_init の戻り値。

### 2.12.2 戻り値

現在のスレッショルドレベル。handle が NULL またはロック取得失敗時は `TRACE_LV_NONE` を返す。

### 2.12.3 スレッド セーフティ

本関数はスレッドセーフです。
started / stopped どちらの状態でも呼び出し可能です。

## 2.13 trace_get_filetrc

    TRACE_UTIL_EXPORT enum trace_levelTRACE_UTIL_API trace_get_filetrc ( trace_provider_t *handle )

ファイルトレースの現在のスレッショルドレベルを取得する。

### 2.13.1 引数

- handle [in] trace_init の戻り値。

### 2.13.2 戻り値

現在のスレッショルドレベル。handle が NULL またはロック取得失敗時は `TRACE_LV_NONE` を返す。

### 2.13.3 スレッド セーフティ

本関数はスレッドセーフです。
started / stopped どちらの状態でも呼び出し可能です。

## 2.14 trace_get_stderrtrc

    TRACE_UTIL_EXPORT enum trace_levelTRACE_UTIL_API trace_get_stderrtrc ( trace_provider_t *handle )

stderr トレースの現在のスレッショルドレベルを取得する。

### 2.14.1 引数

- handle [in] trace_init の戻り値。

### 2.14.2 戻り値

現在のスレッショルドレベル。handle が NULL またはロック取得失敗時は `TRACE_LV_NONE` を返す。

### 2.14.3 スレッド セーフティ

本関数はスレッドセーフです。
started / stopped どちらの状態でも呼び出し可能です。

## 2.15 trace_dispose

    TRACE_UTIL_EXPORT void TRACE_UTIL_API trace_dispose ( trace_provider_t *handle )

トレースプロバイダを終了し、リソースを解放する。

ハンドルが NULL の場合は何もしません。
started 状態のハンドルに対しても呼び出し可能です (内部で自動的に停止してから解放します)。

### 2.15.1 引数

- handle [in] trace_init の戻り値。

### 2.15.2 スレッド セーフティ

本関数はスレッドセーフです。
本関数を呼び出した時点で進行中の trace_write 等が完了するまで待機してから リソースを解放します。
本関数呼び出し後、handle は無効となります。

# 3 定数、マクロ

## 3.1 TRACE_UTIL_EXPORT

    #define TRACE_UTIL_EXPORT

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

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

条件 | 値
--- | ---
Linux (非 Windows) | (空)
Windows / `__INTELLISENSE__` 定義時 | (空)
Windows / `TRACE_UTIL_STATIC` 定義時 (静的リンク) | (空)
Windows / `TRACE_UTIL_EXPORTS` 定義時 (DLL ビルド) | `__declspec(dllexport)`
Windows / `TRACE_UTIL_EXPORTS` 未定義時 (DLL 利用側) | `__declspec(dllimport)`

## 3.2 TRACE_UTIL_API

    #define TRACE_UTIL_API

呼び出し規約マクロ。

Windows 環境では `__stdcall` 呼び出し規約を指定します。
Linux (非 Windows) 環境では空に展開されます。
既に定義済みの場合は再定義されません。

## 3.3 TRACE_MESSAGE_MAX_BYTES

    #define TRACE_MESSAGE_MAX_BYTES 1024

trace_write が受け付けるメッセージの最大バイト数 (null 終端含む)。

ETW (約 65,000 バイト) と syslog (RFC 3164: 1,024 バイト) の 推奨上限のうち小さい方を採用し、クロスプラットフォームでの 安全な転送を保証します。
本文の最大長は `TRACE_MESSAGE_MAX_BYTES``-``1` (= 1,023) バイトです。

## 3.4 TRACE_HEX_MAX_DATA_BYTES

    #define TRACE_HEX_MAX_DATA_BYTES 341

trace_hex_write がラベルなしで HEX 出力できるバイナリデータの最大バイト数。

1 バイトあたり 3 文字 (HH + スペース) を消費し、最終バイトは 2 文字です。
ラベル (`message`) を指定した場合はラベル長 + セパレータ (“:”) 分だけ 出力可能なバイナリデータ量が減少します。
データがこの上限を超える場合は切り詰めが行われ、 末尾に `"..."` が付与されます。

## 3.5 TRACE_DEFAULT_OS_LEVEL

    #define TRACE_DEFAULT_OS_LEVEL TRACE_LV_INFO

trace_init() が設定する OS トレース (ETW / syslog) のデフォルトレベル。

ユーザーが trace_modify_ostrc() で変更するまで有効な初期値です。

## 3.6 TRACE_DEFAULT_FILE_LEVEL

    #define TRACE_DEFAULT_FILE_LEVEL TRACE_LV_ERROR

trace_init() が設定するファイルトレースのデフォルトレベル。

ユーザーが trace_modify_filetrc() で変更するまで有効な初期値です。

## 3.7 TRACE_DEFAULT_STDERR_LEVEL

    #define TRACE_DEFAULT_STDERR_LEVEL TRACE_LV_NONE

trace_init() が設定する stderr トレースのデフォルトレベル。

ユーザーが trace_modify_stderrtrc() で変更するまで有効な初期値です。
デフォルトは TRACE_LV_NONE (無効) です。

# 4 型

## 4.1 trace_level

アプリケーション共通トレースレベル。

OS 非依存のトレースレベルを定義します。重大度は上から下へ低下します。
内部で ETW Level (1-5) および syslog severity へマッピングされます。

trace_level | ETW Level | syslog severity
--- | --- | ---
TRACE_LV_CRITICAL | Critical (1) | LOG_CRIT (2)
TRACE_LV_ERROR | Error (2) | LOG_ERR (3)
TRACE_LV_WARNING | Warning (3) | LOG_WARNING (4)
TRACE_LV_INFO | Informational (4) | LOG_INFO (6)
TRACE_LV_VERBOSE | Verbose (5) | LOG_DEBUG (7)

列挙子 | 値 | 説明
--- | --- | ---
TRACE_LV_CRITICAL | 0 | 致命的エラー。
TRACE_LV_ERROR | 1 | エラー。
TRACE_LV_WARNING | 2 | 警告。
TRACE_LV_INFO | 3 | 情報。
TRACE_LV_VERBOSE | 4 | 詳細 (デバッグ)。
TRACE_LV_NONE | 5 | 出力しない。

## 4.2 trace_provider_t

    typedef struct trace_provider trace_provider_t;

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