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_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

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

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

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: