クロスプラットフォーム トレーシング API。
Windows (ETW) と Linux (syslog) の差異を抽象化し、 共通のトレースレベルとインターフェースを提供します。
内部で trace-etw-util.h (Windows) または trace-syslog-util.h (Linux) を 使用します。
c-modernization-kit sample team
1.0.0
2026/03/05
Application
|
v
trace-util.h (共通 API)
|
+-----+-----+------+--------+
| | | |
ETW syslog File stderr
(Windows) (Linux) (両OS) (両OS)#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);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);Copyright (C) CompanyName, Ltd. 2026. All rights reserved.
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 を呼び出してください。
成功時: ハンドル (stopped 状態)。失敗時: NULL。
戻り値のハンドルは stopped 状態です。 出力関数を使用するには trace_start を呼び出してください。
stopped 状態では設定関数 (trace_modify_name, trace_modify_ostrc, trace_modify_filetrc, trace_modify_stderrtrc) をスレッド安全に使用できます。
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);本関数はスレッドセーフです。
複数スレッドから独立したハンドルを取得するために並行して呼び出すことができます。
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 を返します (冪等)。
成功 0 / 失敗 -1。
handle が NULL の場合は -1 を返します。
本関数はスレッドセーフです。
内部で排他制御を行います。
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 を返します (冪等)。
成功 0 / 失敗 -1。
handle が NULL の場合は -1 を返します。
本関数はスレッドセーフです。
内部で排他制御を行います。
trace_start
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 に マッピングして書き込みます。
成功 0 / 失敗 -1。
メッセージが TRACE_MESSAGE_MAX_BYTES (1,024) バイト (null 終端含む) を超える場合、本関数は内部で 1,023 バイト以内に切り詰めて下層 API に渡します。
切り詰め時は UTF-8 マルチバイト文字の途中で切断しないよう バイト境界を調整します。
この上限は ETW (約 65,000 バイト) と syslog (RFC 3164: 1,024 バイト) の推奨値のうち小さい方に合わせています。
handle が NULL の場合は何もせず 0 を返します。
message が NULL の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。
ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。
本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。
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) バイトの バッファにフォーマットします。バッファを超える部分は切り詰められます。
成功 0 / 失敗 -1。
handle が NULL の場合は何もせず 0 を返します。
format が NULL の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。
ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。
trace_writef(logger, TRACE_LV_INFO, "user=%s count=%d", username, count);本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。
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 バイト) 分だけ出力可能なデータ量が減少します。
データが収まらない場合は切り詰め、末尾に "..." を付与します。
成功 0 / 失敗 -1。
handle が NULL の場合は何もせず 0 を返します。
data が NULL の場合は何もせず 0 を返します。
size が 0 の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。
ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。
// message 指定あり (全データ表示):
"Received data: 48 65 6C 6C 6F"
// message が NULL (全データ表示):
"48 65 6C 6C 6F"
// データが収まらない場合 (切り詰め):
"Received data: 48 65 6C ..."本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。
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 形式の フォーマット文字列と可変長引数で指定できます。
成功 0 / 失敗 -1。
handle が NULL の場合は何もせず 0 を返します。
data が NULL の場合は何もせず 0 を返します。
size が 0 の場合は何もせず 0 を返します。
stopped 状態では -1 を返します。
ハンドルが started 状態であること (trace_start 呼び出し済み)。 stopped 状態では -1 を返します。
// フォーマット済みラベル付き:
"packet[3]: 48 65 6C 6C 6F"
// データが収まらない場合:
"packet[3]: 48 65 6C ..."trace_hex_writef(logger, TRACE_LV_INFO, data, len, "packet[%d]", index);本関数はスレッドセーフです。
started 状態では複数スレッドから並行して呼び出すことができます。
trace_hex_write
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” フィールド値のみが変更されます。
name をそのまま使用します。"<name>-<identifier>" を識別名とします。成功 0 / 失敗 (無効な引数・メモリ確保失敗等) -1。
handle が NULL の場合は -1 を返します。
identifier に負の値を指定した場合は -1 を返します。
started 状態では -1 を返します。
ハンドルが stopped 状態であること。 started 状態では -1 を返します。
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);stopped 状態ではスレッドセーフです。
内部で排他制御を行います。
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 トレース出力を完全に抑止します。
成功 0 / 失敗 -1。
handle が NULL の場合は -1 を返します。
started 状態では -1 を返します。
ハンドルが stopped 状態であること。 started 状態では -1 を返します。
stopped 状態ではスレッドセーフです。
内部で排他制御を行います。
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 の直後は無効 (パス未指定) です。
成功 0 / 失敗 -1。
handle が NULL の場合は -1 を返します。
started 状態では -1 を返します。
path に指定したファイルが書き込み不可の場合は -1 を返します。
ハンドルが stopped 状態であること。 started 状態では -1 を返します。
stopped 状態ではスレッドセーフです。
内部で排他制御を行います。
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 出力を完全に抑止します。
成功 0 / 失敗 -1。
handle が NULL の場合は -1 を返します。
started 状態では -1 を返します。
ハンドルが stopped 状態であること。 started 状態では -1 を返します。
stopped 状態ではスレッドセーフです。
内部で排他制御を行います。
TRACE_UTIL_EXPORT enum trace_levelTRACE_UTIL_API trace_get_ostrc ( trace_provider_t *handle )OS トレースの現在のスレッショルドレベルを取得する。
現在のスレッショルドレベル。handle が NULL またはロック取得失敗時は TRACE_LV_NONE を返す。
本関数はスレッドセーフです。
started / stopped どちらの状態でも呼び出し可能です。
TRACE_UTIL_EXPORT enum trace_levelTRACE_UTIL_API trace_get_filetrc ( trace_provider_t *handle )ファイルトレースの現在のスレッショルドレベルを取得する。
現在のスレッショルドレベル。handle が NULL またはロック取得失敗時は TRACE_LV_NONE を返す。
本関数はスレッドセーフです。
started / stopped どちらの状態でも呼び出し可能です。
TRACE_UTIL_EXPORT enum trace_levelTRACE_UTIL_API trace_get_stderrtrc ( trace_provider_t *handle )stderr トレースの現在のスレッショルドレベルを取得する。
現在のスレッショルドレベル。handle が NULL またはロック取得失敗時は TRACE_LV_NONE を返す。
本関数はスレッドセーフです。
started / stopped どちらの状態でも呼び出し可能です。
TRACE_UTIL_EXPORT void TRACE_UTIL_API trace_dispose ( trace_provider_t *handle )トレースプロバイダを終了し、リソースを解放する。
ハンドルが NULL の場合は何もしません。
started 状態のハンドルに対しても呼び出し可能です (内部で自動的に停止してから解放します)。
本関数はスレッドセーフです。
本関数を呼び出した時点で進行中の trace_write 等が完了するまで待機してから リソースを解放します。
本関数呼び出し後、handle は無効となります。
#define TRACE_UTIL_EXPORTDLL エクスポート/インポート制御マクロ。
ビルド条件に応じて以下の値を取ります。
| 条件 | 値 |
|---|---|
| Linux (非 Windows) | (空) |
Windows / __INTELLISENSE__ 定義時 |
(空) |
Windows / TRACE_UTIL_STATIC 定義時 (静的リンク) |
(空) |
Windows / TRACE_UTIL_EXPORTS 定義時 (DLL ビルド) |
__declspec(dllexport) |
Windows / TRACE_UTIL_EXPORTS 未定義時 (DLL 利用側) |
__declspec(dllimport) |
#define TRACE_UTIL_API呼び出し規約マクロ。
Windows 環境では __stdcall 呼び出し規約を指定します。
Linux (非 Windows) 環境では空に展開されます。
既に定義済みの場合は再定義されません。
#define TRACE_MESSAGE_MAX_BYTES 1024trace_write が受け付けるメッセージの最大バイト数 (null 終端含む)。
ETW (約 65,000 バイト) と syslog (RFC 3164: 1,024 バイト) の 推奨上限のうち小さい方を採用し、クロスプラットフォームでの 安全な転送を保証します。
本文の最大長は TRACE_MESSAGE_MAX_BYTES``-``1 (= 1,023) バイトです。
#define TRACE_HEX_MAX_DATA_BYTES 341trace_hex_write がラベルなしで HEX 出力できるバイナリデータの最大バイト数。
1 バイトあたり 3 文字 (HH + スペース) を消費し、最終バイトは 2 文字です。
ラベル (message) を指定した場合はラベル長 + セパレータ (“:”) 分だけ 出力可能なバイナリデータ量が減少します。
データがこの上限を超える場合は切り詰めが行われ、 末尾に "..." が付与されます。
#define TRACE_DEFAULT_OS_LEVEL TRACE_LV_INFOtrace_init() が設定する OS トレース (ETW / syslog) のデフォルトレベル。
ユーザーが trace_modify_ostrc() で変更するまで有効な初期値です。
#define TRACE_DEFAULT_FILE_LEVEL TRACE_LV_ERRORtrace_init() が設定するファイルトレースのデフォルトレベル。
ユーザーが trace_modify_filetrc() で変更するまで有効な初期値です。
#define TRACE_DEFAULT_STDERR_LEVEL TRACE_LV_NONEtrace_init() が設定する stderr トレースのデフォルトレベル。
ユーザーが trace_modify_stderrtrc() で変更するまで有効な初期値です。
デフォルトは TRACE_LV_NONE (無効) です。
アプリケーション共通トレースレベル。
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 | 出力しない。 |
typedef struct trace_provider trace_provider_t;トレースプロバイダハンドル (不透明型)。