#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:

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

Data Structures

Macros

Functions

Variables

Macro Definition Documentation

◆ FALLBACK_NAME

◆ LOCK_TIMEOUT_MS

◆ MAX_BODY

◆ STDERR_TS_BUF_SIZE

◆ ELLIPSIS_LEN

Function Documentation

◆ to_syslog_level()

◆ get_process_basename()

◆ config_lock_exclusive()

◆ config_unlock_exclusive()

◆ config_lock_shared_timed()

◆ config_unlock_shared()

◆ build_effective_name()

◆ trace_init()

◆ trace_start()

◆ trace_stop()

◆ utf8_safe_truncate()

◆ write_to_provider()

◆ should_output()

◆ write_stderr_entry()

◆ write_dual()

◆ trace_write()

◆ trace_writef()

◆ hex_write_impl()

◆ trace_hex_write()

◆ trace_hex_writef()

◆ trace_dispose()

◆ trace_modify_name()

◆ trace_modify_ostrc()

◆ trace_modify_filetrc()

◆ trace_modify_stderrtrc()

◆ trace_get_ostrc()

◆ trace_get_filetrc()

◆ trace_get_stderrtrc()

Variable Documentation

◆ hex_chars