Document of c-modernization-kit (util) 1.0.0

Loading...
Searching...
No Matches
Macros | Typedefs | Enumerations | Functions
trace-util.h File Reference

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

`#include <stddef.h>`
`#include <inttypes.h>`
`#include <trace-syslog-util.h>`
Include dependency graph for trace-util.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros
#define | TRACE_UTIL_EXPORT
| DLL エクスポート/インポート制御マクロ。
#define | TRACE_UTIL_API
| 呼び出し規約マクロ。
#define | TRACE_MESSAGE_MAX_BYTES 1024
| trace_write が受け付けるメッセージの最大バイト数 (null 終端含む)。
#define | TRACE_HEX_MAX_DATA_BYTES 341
| trace_hex_write がラベルなしで HEX 出力できるバイナリデータの最大バイト数。
#define | TRACE_DEFAULT_OS_LEVEL TRACE_LV_INFO
| trace_init() が設定する OS トレース (ETW / syslog) のデフォルトレベル。
#define | TRACE_DEFAULT_FILE_LEVEL TRACE_LV_ERROR
| trace_init() が設定するファイルトレースのデフォルトレベル。
#define | TRACE_DEFAULT_STDERR_LEVEL TRACE_LV_NONE
| trace_init() が設定する stderr トレースのデフォルトレベル。

## Typedefs
typedef struct trace_provider | trace_provider_t
| トレースプロバイダハンドル (不透明型)。

## Enumerations
enum | trace_level { TRACE_LV_CRITICAL = 0 , TRACE_LV_ERROR = 1 , TRACE_LV_WARNING = 2 , TRACE_LV_INFO = 3 , TRACE_LV_VERBOSE = 4 , TRACE_LV_NONE = 5 }
| アプリケーション共通トレースレベル。 More...

## Functions
TRACE_UTIL_EXPORT trace_provider_t *TRACE_UTIL_API | trace_init (void)
| トレースプロバイダを初期化する。
TRACE_UTIL_EXPORT int TRACE_UTIL_API | trace_start (trace_provider_t *handle)
| トレースプロバイダを開始する。
TRACE_UTIL_EXPORT int TRACE_UTIL_API | trace_stop (trace_provider_t *handle)
| トレースプロバイダを停止する。
TRACE_UTIL_EXPORT int TRACE_UTIL_API | trace_write (trace_provider_t *handle, enum trace_level level, const char *message)
| トレースメッセージを書き込む。
TRACE_UTIL_EXPORT int TRACE_UTIL_API | trace_writef (trace_provider_t *handle, enum trace_level level, const char *format,...)
| printf 形式でトレースメッセージを書き込む。
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 テキスト形式でトレースに書き込む。
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_UTIL_EXPORT int TRACE_UTIL_API | trace_modify_name (trace_provider_t *handle, const char *name, int64_t identifier)
| トレースプロバイダの識別名と識別番号を設定する。
TRACE_UTIL_EXPORT int TRACE_UTIL_API | trace_modify_ostrc (trace_provider_t *handle, enum trace_level level)
| OS トレースのスレッショルドレベルを設定する。
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)
| ファイルトレースの出力先と設定を変更する。
TRACE_UTIL_EXPORT int TRACE_UTIL_API | trace_modify_stderrtrc (trace_provider_t *handle, enum trace_level level)
| stderr トレースのスレッショルドレベルを設定する。
TRACE_UTIL_EXPORT enum trace_level TRACE_UTIL_API | trace_get_ostrc (trace_provider_t *handle)
| OS トレースの現在のスレッショルドレベルを取得する。
TRACE_UTIL_EXPORT enum trace_level TRACE_UTIL_API | trace_get_filetrc (trace_provider_t *handle)
| ファイルトレースの現在のスレッショルドレベルを取得する。
TRACE_UTIL_EXPORT enum trace_level TRACE_UTIL_API | trace_get_stderrtrc (trace_provider_t *handle)
| stderr トレースの現在のスレッショルドレベルを取得する。
TRACE_UTIL_EXPORT void TRACE_UTIL_API | trace_dispose (trace_provider_t *handle)
| トレースプロバイダを終了し、リソースを解放する。

## Detailed Description

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

Author
  c-modernization-kit sample team

Date
  2026/03/05

Version
  1.0.0

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

アーキテクチャ
  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-util.h
  クロスプラットフォーム トレーシング API。
  TRACE_LV_INFO
  @ TRACE_LV_INFO
  情報。
  Definition trace-util.h:208
  trace_provider_t
  struct trace_provider trace_provider_t
  トレースプロバイダハンドル (不透明型)。
  Definition trace-util.h:243
  trace_dispose
  TRACE_UTIL_EXPORT void TRACE_UTIL_API trace_dispose(trace_provider_t *handle)
  トレースプロバイダを終了し、リソースを解放する。
  Definition trace-provider.c:779
  trace_init
  TRACE_UTIL_EXPORT trace_provider_t *TRACE_UTIL_API trace_init(void)
  トレースプロバイダを初期化する。
  Definition trace-provider.c:288
  trace_stop
  TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_stop(trace_provider_t *handle)
  トレースプロバイダを停止する。
  Definition trace-provider.c:395
  trace_start
  TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_start(trace_provider_t *handle)
  トレースプロバイダを開始する。
  Definition trace-provider.c:374
  trace_write
  TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_write(trace_provider_t *handle, enum trace_level level, const char *message)
  トレースメッセージを書き込む。
  Definition trace-provider.c:538
  trace_modify_name
  TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_modify_name(trace_provider_t *handle, const char *name, int64_t identifier)
  トレースプロバイダの識別名と識別番号を設定する。
  Definition trace-provider.c:817

使用例 (設定変更)
  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);
  TRACE_LV_VERBOSE
  @ TRACE_LV_VERBOSE
  詳細 (デバッグ)。
  Definition trace-util.h:209
  trace_modify_ostrc
  TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_modify_ostrc(trace_provider_t *handle, enum trace_level level)
  OS トレースのスレッショルドレベルを設定する。
  Definition trace-provider.c:869

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

Definition in file trace-util.h.

## Macro Definition Documentation

## ◆ 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)

Definition at line 123 of file trace-util.h.

## ◆ TRACE_UTIL_API

#define TRACE_UTIL_API

呼び出し規約マクロ。

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

Definition at line 133 of file trace-util.h.

## ◆ 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) バイトです。

Definition at line 172 of file trace-util.h.

Referenced by hex_write_impl(), trace_hex_writef(), trace_write(), and trace_writef().

## ◆ TRACE_HEX_MAX_DATA_BYTES

#define TRACE_HEX_MAX_DATA_BYTES 341

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

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

Definition at line 184 of file trace-util.h.

## ◆ TRACE_DEFAULT_OS_LEVEL

#define TRACE_DEFAULT_OS_LEVEL TRACE_LV_INFO

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

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

Definition at line 221 of file trace-util.h.

Referenced by trace_init().

## ◆ TRACE_DEFAULT_FILE_LEVEL

#define TRACE_DEFAULT_FILE_LEVEL TRACE_LV_ERROR

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

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

Definition at line 229 of file trace-util.h.

Referenced by trace_init().

## ◆ TRACE_DEFAULT_STDERR_LEVEL

#define TRACE_DEFAULT_STDERR_LEVEL TRACE_LV_NONE

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

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

Definition at line 238 of file trace-util.h.

Referenced by trace_init().

## Typedef Documentation

## ◆ trace_provider_t

typedef struct trace_provider trace_provider_t

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

Definition at line 243 of file trace-util.h.

## Enumeration Type Documentation

## ◆ trace_level

enum 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)

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

Definition at line 203 of file trace-util.h.

## Function Documentation

## ◆ trace_init()

TRACE_UTIL_EXPORT trace_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 を呼び出してください。

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

Postcondition
  戻り値のハンドルは 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);

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

Definition at line 288 of file trace-provider.c.

References trace_provider::config_rwlock, trace_provider::config_rwlock_initialized, trace_provider::file_handle, trace_provider::file_level, get_process_basename(), trace_provider::identifier, trace_provider::os_level, trace_provider::running, trace_provider::stderr_level, trace_provider::syslog_handle, syslog_provider_dispose(), syslog_provider_init(), TRACE_DEFAULT_FILE_LEVEL, TRACE_DEFAULT_OS_LEVEL, and TRACE_DEFAULT_STDERR_LEVEL.

Here is the call graph for this function:

## ◆ 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 を返します (冪等)。

Parameters

  [in] | handle | trace_init の戻り値。

Returns
  成功 0 / 失敗 -1。

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

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

See also
  trace_stop

Definition at line 374 of file trace-provider.c.

References config_lock_exclusive(), config_unlock_exclusive(), and trace_provider::running.

Here is the call graph for this function:

## ◆ 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 を返します (冪等)。

Parameters

  [in] | handle | trace_init の戻り値。

Returns
  成功 0 / 失敗 -1。

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

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

See also
  trace_start

Definition at line 395 of file trace-provider.c.

References config_lock_exclusive(), config_unlock_exclusive(), and trace_provider::running.

Referenced by trace_dispose().

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ 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 に マッピングして書き込みます。

Parameters

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

Returns
  成功 0 / 失敗 -1。

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

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

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

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

Definition at line 538 of file trace-provider.c.

References config_lock_shared_timed(), config_unlock_shared(), MAX_BODY, trace_provider::running, TRACE_MESSAGE_MAX_BYTES, utf8_safe_truncate(), and write_dual().

Here is the call graph for this function:

## ◆ 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) バイトの バッファにフォーマットします。バッファを超える部分は切り詰められます。

Parameters

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

Returns
  成功 0 / 失敗 -1。

使用例
  trace_writef(logger, TRACE_LV_INFO, "user=%s count=%d", username, count);
  trace_writef
  TRACE_UTIL_EXPORT int TRACE_UTIL_API trace_writef(trace_provider_t *handle, enum trace_level level, const char *format,...)
  printf 形式でトレースメッセージを書き込む。
  Definition trace-provider.c:578

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

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

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

Definition at line 578 of file trace-provider.c.

References config_lock_shared_timed(), config_unlock_shared(), trace_provider::running, TRACE_MESSAGE_MAX_BYTES, and write_dual().

Here is the call graph for this function:

## ◆ 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 バイト) 分だけ出力可能なデータ量が減少します。
データが収まらない場合は切り詰め、末尾に `"..."` を付与します。

Parameters

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

Returns
  成功 0 / 失敗 -1。

出力フォーマット
  // message 指定あり (全データ表示):
  "Received data: 48 65 6C 6C 6F"
  // message が NULL (全データ表示):
  "48 65 6C 6C 6F"
  // データが収まらない場合 (切り詰め):
  "Received data: 48 65 6C ..."

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

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

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

Definition at line 712 of file trace-provider.c.

References config_lock_shared_timed(), config_unlock_shared(), hex_write_impl(), and trace_provider::running.

Here is the call graph for this function:

## ◆ 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 形式の フォーマット文字列と可変長引数で指定できます。

Parameters

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

Returns
  成功 0 / 失敗 -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);
  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 形式ラベル)。
  Definition trace-provider.c:739

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

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

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

See also
  trace_hex_write

Definition at line 739 of file trace-provider.c.

References config_lock_shared_timed(), config_unlock_shared(), hex_write_impl(), trace_provider::running, and TRACE_MESSAGE_MAX_BYTES.

Here is the call graph for this function:

## ◆ 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" フィールド値のみが変更されます。

Parameters

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

Returns
  成功 0 / 失敗 (無効な引数・メモリ確保失敗等) -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);

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

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

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

Definition at line 817 of file trace-provider.c.

References build_effective_name(), config_lock_exclusive(), config_unlock_exclusive(), trace_provider::identifier, trace_provider::running, trace_provider::syslog_handle, and syslog_provider_rename().

Here is the call graph for this function:

## ◆ 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 トレース出力を完全に抑止します。

Parameters

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

Returns
  成功 0 / 失敗 -1。

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

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

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

Definition at line 869 of file trace-provider.c.

References config_lock_exclusive(), config_unlock_exclusive(), trace_provider::os_level, and trace_provider::running.

Here is the call graph for this function:

## ◆ 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 の直後は無効 (パス未指定) です。

Parameters

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

Returns
  成功 0 / 失敗 -1。

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

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

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

Definition at line 890 of file trace-provider.c.

References config_lock_exclusive(), config_unlock_exclusive(), trace_provider::file_handle, trace_provider::file_level, trace_provider::running, trace_file_provider_dispose(), and trace_file_provider_init().

Here is the call graph for this function:

## ◆ 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 出力を完全に抑止します。

Parameters

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

Returns
  成功 0 / 失敗 -1。

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

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

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

Definition at line 933 of file trace-provider.c.

References config_lock_exclusive(), config_unlock_exclusive(), trace_provider::running, and trace_provider::stderr_level.

Here is the call graph for this function:

## ◆ trace_get_ostrc()

TRACE_UTIL_EXPORT enum trace_level TRACE_UTIL_API trace_get_ostrc | ( | trace_provider_t * | handle | ) |

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

Parameters

  [in] | handle | trace_init の戻り値。

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

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

Definition at line 954 of file trace-provider.c.

References config_lock_shared_timed(), config_unlock_shared(), trace_provider::os_level, and TRACE_LV_NONE.

Here is the call graph for this function:

## ◆ trace_get_filetrc()

TRACE_UTIL_EXPORT enum trace_level TRACE_UTIL_API trace_get_filetrc | ( | trace_provider_t * | handle | ) |

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

Parameters

  [in] | handle | trace_init の戻り値。

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

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

Definition at line 972 of file trace-provider.c.

References config_lock_shared_timed(), config_unlock_shared(), trace_provider::file_level, and TRACE_LV_NONE.

Here is the call graph for this function:

## ◆ trace_get_stderrtrc()

TRACE_UTIL_EXPORT enum trace_level TRACE_UTIL_API trace_get_stderrtrc | ( | trace_provider_t * | handle | ) |

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

Parameters

  [in] | handle | trace_init の戻り値。

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

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

Definition at line 990 of file trace-provider.c.

References config_lock_shared_timed(), config_unlock_shared(), trace_provider::stderr_level, and TRACE_LV_NONE.

Here is the call graph for this function:

## ◆ trace_dispose()

TRACE_UTIL_EXPORT void TRACE_UTIL_API trace_dispose | ( | trace_provider_t * | handle | ) |

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

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

Parameters

  [in] | handle | trace_init の戻り値。

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

Definition at line 779 of file trace-provider.c.

References trace_provider::config_rwlock, trace_provider::config_rwlock_initialized, trace_provider::file_handle, trace_provider::syslog_handle, syslog_provider_dispose(), trace_file_provider_dispose(), and trace_stop().

Here is the call graph for this function: