Document of c-modernization-kit (util) 1.0.0

Loading...
Searching...
No Matches
Data Structures | Macros | Functions | Variables
trace-provider.c File Reference
`#include <trace-util.h>`
`#include <trace-file-util.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <stdarg.h>`
`#include <stdio.h>`
`#include <inttypes.h>`
`#include <time.h>`
`#include <pthread.h>`
`#include <syslog.h>`
`#include <unistd.h>`
Include dependency graph for trace-provider.c:

Go to the source code of this file.

## Data Structures
struct | trace_provider
| トレースプロバイダハンドル構造体 (内部定義)。 More...

## Macros
#define | FALLBACK_NAME "unknown"
| プロセス名取得失敗時のフォールバック名。
#define | LOCK_TIMEOUT_MS 100
| 共有ロック取得のタイムアウト (ミリ秒)。
#define | MAX_BODY (TRACE_MESSAGE_MAX_BYTES - 1)
| 切り詰め後の本文最大バイト数 (null 終端を除く)。
#define | STDERR_TS_BUF_SIZE 24
| stderr タイムスタンプバッファサイズ ("YYYY-MM-DD HH:MM:SS.mmm\0" = 24)。
#define | ELLIPSIS_LEN 3
| "..." サフィックスの長さ。

## Functions
static int | to_syslog_level (enum trace_level lv)
| enum trace_level を syslog severity に変換する。
static const char * | get_process_basename (char *buf, size_t buf_size)
| 自プロセスの実行ファイル名 (ベースネーム) を取得する。
static void | config_lock_exclusive (trace_provider_t *handle)
| 設定・状態変更用の排他ロックを取得する。 trace_start / trace_stop / trace_modify_* / trace_dispose で使用する。
static void | config_unlock_exclusive (trace_provider_t *handle)
| 排他ロックを解放する。
static int | config_lock_shared_timed (trace_provider_t *handle)
| 書き込み系 API 用の共有ロックをタイムアウト付きで取得する。 複数スレッドが同時に取得できる。 排他ロック保持中はブロックするが、LOCK_TIMEOUT_MS 経過で諦める。
static void | config_unlock_shared (trace_provider_t *handle)
| 共有ロックを解放する。
static char * | build_effective_name (const char *name, int64_t identifier)
| name と identifier から有効識別名 (effective name) を生成する。
trace_provider_t *TRACE_UTIL_API | trace_init (void)
| トレースプロバイダを初期化する。
int TRACE_UTIL_API | trace_start (trace_provider_t *handle)
| トレースプロバイダを開始する。
int TRACE_UTIL_API | trace_stop (trace_provider_t *handle)
| トレースプロバイダを停止する。
static size_t | utf8_safe_truncate (const char *s, size_t pos)
| UTF-8 安全な切り詰め位置を返す。
static int | write_to_provider (trace_provider_t *handle, enum trace_level level, const char *msg)
| 下層プロバイダに文字列を書き込む (内部ヘルパー)。
static int | should_output (enum trace_level msg_level, enum trace_level threshold)
| メッセージレベルがスレッショルド以内かを判定する。
static void | write_stderr_entry (enum trace_level level, const char *msg)
| stderr にタイムスタンプ + レベル文字 + メッセージを 1 行書き込む。
static int | write_dual (trace_provider_t *handle, enum trace_level level, const char *msg)
| OS プロバイダとファイルプロバイダの両方へメッセージを書き込む。
int TRACE_UTIL_API | trace_write (trace_provider_t *handle, enum trace_level level, const char *message)
| トレースメッセージを書き込む。
int TRACE_UTIL_API | trace_writef (trace_provider_t *handle, enum trace_level level, const char *format,...)
| printf 形式でトレースメッセージを書き込む。
static int | hex_write_impl (trace_provider_t *handle, enum trace_level level, const void *data, size_t size, const char *label)
| HEX ダンプ出力の内部実装。
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 テキスト形式でトレースに書き込む。
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 形式ラベル)。
void TRACE_UTIL_API | trace_dispose (trace_provider_t *handle)
| トレースプロバイダを終了し、リソースを解放する。
int TRACE_UTIL_API | trace_modify_name (trace_provider_t *handle, const char *name, int64_t identifier)
| トレースプロバイダの識別名と識別番号を設定する。
int TRACE_UTIL_API | trace_modify_ostrc (trace_provider_t *handle, enum trace_level level)
| OS トレースのスレッショルドレベルを設定する。
int TRACE_UTIL_API | trace_modify_filetrc (trace_provider_t *handle, const char *path, enum trace_level level, size_t max_bytes, int generations)
| ファイルトレースの出力先と設定を変更する。
int TRACE_UTIL_API | trace_modify_stderrtrc (trace_provider_t *handle, enum trace_level level)
| stderr トレースのスレッショルドレベルを設定する。
enum trace_level TRACE_UTIL_API | trace_get_ostrc (trace_provider_t *handle)
| OS トレースの現在のスレッショルドレベルを取得する。
enum trace_level TRACE_UTIL_API | trace_get_filetrc (trace_provider_t *handle)
| ファイルトレースの現在のスレッショルドレベルを取得する。
enum trace_level TRACE_UTIL_API | trace_get_stderrtrc (trace_provider_t *handle)
| stderr トレースの現在のスレッショルドレベルを取得する。

## Variables
static const char | hex_chars [] = "0123456789ABCDEF"
| HEX 変換用テーブル。

## Macro Definition Documentation

## ◆ FALLBACK_NAME

#define FALLBACK_NAME "unknown"

プロセス名取得失敗時のフォールバック名。

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

Referenced by get_process_basename().

## ◆ LOCK_TIMEOUT_MS

#define LOCK_TIMEOUT_MS 100

共有ロック取得のタイムアウト (ミリ秒)。

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

Referenced by config_lock_shared_timed().

## ◆ MAX_BODY

#define MAX_BODY (TRACE_MESSAGE_MAX_BYTES - 1)

切り詰め後の本文最大バイト数 (null 終端を除く)。

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

Referenced by hex_write_impl(), and trace_write().

## ◆ STDERR_TS_BUF_SIZE

#define STDERR_TS_BUF_SIZE 24

stderr タイムスタンプバッファサイズ ("YYYY-MM-DD HH:MM:SS.mmm\0" = 24)。

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

Referenced by write_stderr_entry().

## ◆ ELLIPSIS_LEN

#define ELLIPSIS_LEN 3

"..." サフィックスの長さ。

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

Referenced by hex_write_impl().

## Function Documentation

## ◆ to_syslog_level()

int to_syslog_level | ( | enum trace_level | lv | ) |
| static

enum trace_level を syslog severity に変換する。

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

References TRACE_LV_CRITICAL, TRACE_LV_ERROR, TRACE_LV_INFO, TRACE_LV_NONE, TRACE_LV_VERBOSE, and TRACE_LV_WARNING.

Referenced by write_to_provider().

Here is the caller graph for this function:

## ◆ get_process_basename()

const char * get_process_basename | ( | char * | buf,
|  | size_t | buf_size )
| static

自プロセスの実行ファイル名 (ベースネーム) を取得する。

Parameters

  [out] | buf | パス格納バッファ。
  [in] | buf_size | バッファサイズ。

Returns
  ベースネームへのポインタ (buf 内または FALLBACK_NAME)。

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

References FALLBACK_NAME.

Referenced by build_effective_name(), and trace_init().

Here is the caller graph for this function:

## ◆ config_lock_exclusive()

void config_lock_exclusive | ( | trace_provider_t * | handle | ) |
| static

設定・状態変更用の排他ロックを取得する。 trace_start / trace_stop / trace_modify_* / trace_dispose で使用する。

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

References trace_provider::config_rwlock.

Referenced by trace_modify_filetrc(), trace_modify_name(), trace_modify_ostrc(), trace_modify_stderrtrc(), trace_start(), and trace_stop().

Here is the caller graph for this function:

## ◆ config_unlock_exclusive()

void config_unlock_exclusive | ( | trace_provider_t * | handle | ) |
| static

排他ロックを解放する。

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

References trace_provider::config_rwlock.

Referenced by trace_modify_filetrc(), trace_modify_name(), trace_modify_ostrc(), trace_modify_stderrtrc(), trace_start(), and trace_stop().

Here is the caller graph for this function:

## ◆ config_lock_shared_timed()

int config_lock_shared_timed | ( | trace_provider_t * | handle | ) |
| static

書き込み系 API 用の共有ロックをタイムアウト付きで取得する。 複数スレッドが同時に取得できる。 排他ロック保持中はブロックするが、LOCK_TIMEOUT_MS 経過で諦める。

Returns
  取得成功: 0 / タイムアウト: -1。

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

References trace_provider::config_rwlock, and LOCK_TIMEOUT_MS.

Referenced by trace_get_filetrc(), trace_get_ostrc(), trace_get_stderrtrc(), trace_hex_write(), trace_hex_writef(), trace_write(), and trace_writef().

Here is the caller graph for this function:

## ◆ config_unlock_shared()

void config_unlock_shared | ( | trace_provider_t * | handle | ) |
| static

共有ロックを解放する。

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

References trace_provider::config_rwlock.

Referenced by trace_get_filetrc(), trace_get_ostrc(), trace_get_stderrtrc(), trace_hex_write(), trace_hex_writef(), trace_write(), and trace_writef().

Here is the caller graph for this function:

## ◆ build_effective_name()

char * build_effective_name | ( | const char * | name,
|  | int64_t | identifier )
| static

name と identifier から有効識別名 (effective name) を生成する。

name == NULL の場合はプロセスのベースネームを使用する。
identifier == 0 の場合は name をそのままコピーして返す。
identifier > 0 の場合は "<name>-<identifier>" を生成して返す。
戻り値はヒープ上に確保されるため、呼び出し元が free する必要がある。

Returns
  ヒープ上に確保された有効識別名。失敗時 NULL。

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

References get_process_basename().

Referenced by trace_modify_name().

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

## ◆ trace_init()

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

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

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

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

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:

## ◆ utf8_safe_truncate()

size_t utf8_safe_truncate | ( | const char * | s,
|  | size_t | pos )
| static

UTF-8 安全な切り詰め位置を返す。

pos バイト目以前で、UTF-8 マルチバイトシーケンスの途中を 避けた安全な切断位置を返す。

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

Referenced by trace_write().

Here is the caller graph for this function:

## ◆ write_to_provider()

int write_to_provider | ( | trace_provider_t * | handle,
|  | enum trace_level | level,
|  | const char * | msg )
| static

下層プロバイダに文字列を書き込む (内部ヘルパー)。

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

References trace_provider::syslog_handle, syslog_provider_write(), and to_syslog_level().

Referenced by write_dual().

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

## ◆ should_output()

int should_output | ( | enum trace_level | msg_level,
|  | enum trace_level | threshold )
| static

メッセージレベルがスレッショルド以内かを判定する。

Returns
  出力すべき場合は 1、そうでなければ 0。

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

References TRACE_LV_NONE.

Referenced by write_dual().

Here is the caller graph for this function:

## ◆ write_stderr_entry()

void write_stderr_entry | ( | enum trace_level | level,
|  | const char * | msg )
| static

stderr にタイムスタンプ + レベル文字 + メッセージを 1 行書き込む。

ファイルトレースと同一フォーマット: "YYYY-MM-DD HH:MM:SS.mmm L msg\n"
タイムスタンプは UTC。fprintf(stderr) は MT-Safe のため追加ロック不要。

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

References STDERR_TS_BUF_SIZE, and TRACE_LV_NONE.

Referenced by write_dual().

Here is the caller graph for this function:

## ◆ write_dual()

int write_dual | ( | trace_provider_t * | handle,
|  | enum trace_level | level,
|  | const char * | msg )
| static

OS プロバイダとファイルプロバイダの両方へメッセージを書き込む。

レベルフィルタリングを行い、各出力先の条件に合致する場合のみ書き込む。 両方とも出力不要の場合は何もしない。

Returns
  成功 0 / いずれかの書き込み失敗 -1。

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

References trace_provider::file_handle, trace_provider::file_level, trace_provider::os_level, should_output(), trace_provider::stderr_level, trace_file_provider_write(), write_stderr_entry(), and write_to_provider().

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

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

## ◆ trace_write()

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

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:

## ◆ hex_write_impl()

int hex_write_impl | ( | trace_provider_t * | handle,
|  | enum trace_level | level,
|  | const void * | data,
|  | size_t | size,
|  | const char * | label )
| static

HEX ダンプ出力の内部実装。

ラベルは呼び出し元で事前にフォーマット済みの文字列を受け取る。 データが収まらない場合は切り詰めて "..." を付与する。 呼び出し元が共有ロックを保持した状態で呼ぶこと。

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

References ELLIPSIS_LEN, hex_chars, MAX_BODY, TRACE_MESSAGE_MAX_BYTES, and write_dual().

Referenced by trace_hex_write(), and trace_hex_writef().

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

## ◆ trace_hex_write()

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

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_dispose()

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:

## ◆ trace_modify_name()

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

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

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

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

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

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

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:

## Variable Documentation

## ◆ hex_chars

const char hex_chars[] = "0123456789ABCDEF"
| static

HEX 変換用テーブル。

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

Referenced by hex_write_impl().