Document of c-modernization-kit (util) 1.0.0

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

ファイルベーストレースプロバイダライブラリ。 More...

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

Go to the source code of this file.

## Macros
#define | TRACE_FILE_UTIL_EXPORT
| DLL エクスポート/インポート制御マクロ。
#define | TRACE_FILE_UTIL_API
| 呼び出し規約マクロ。
#define | TRACE_FILE_DEFAULT_MAX_BYTES ((size_t)(10 * 1024 * 1024))
| トレースファイル 1 世代あたりの既定最大サイズ (バイト)。
#define | TRACE_FILE_DEFAULT_GENERATIONS 5
| 保持するトレースファイル世代数の既定値。
TRACE_FILE_LV_* トレースレベル定数
#define | TRACE_FILE_LV_CRITICAL 0
| 致命的エラー (trace-util.h の TRACE_LV_CRITICAL と同値)。
#define | TRACE_FILE_LV_ERROR 1
| エラー (trace-util.h の TRACE_LV_ERROR と同値)。
#define | TRACE_FILE_LV_WARNING 2
| 警告 (trace-util.h の TRACE_LV_WARNING と同値)。
#define | TRACE_FILE_LV_INFO 3
| 情報 (trace-util.h の TRACE_LV_INFO と同値)。
#define | TRACE_FILE_LV_VERBOSE 4
| 詳細 / デバッグ (trace-util.h の TRACE_LV_VERBOSE と同値)。

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

## Functions
TRACE_FILE_UTIL_EXPORT trace_file_provider_t *TRACE_FILE_UTIL_API | trace_file_provider_init (const char *path, size_t max_bytes, int generations)
| ファイルトレースプロバイダを初期化する。
TRACE_FILE_UTIL_EXPORT int TRACE_FILE_UTIL_API | trace_file_provider_write (trace_file_provider_t *handle, int level, const char *message)
| ファイルへトレースメッセージを書き込む。
TRACE_FILE_UTIL_EXPORT void TRACE_FILE_UTIL_API | trace_file_provider_dispose (trace_file_provider_t *handle)
| ファイルトレースプロバイダを終了する。

## Detailed Description

ファイルベーストレースプロバイダライブラリ。

トレースメッセージをローテーション付きテキストファイルへ同期書き込みする クロスプラットフォームプロバイダです。
trace-etw-util (Windows ETW) および trace-syslog-util (Linux syslog) と 同じ init / write / dispose インターフェースを提供します。

出力フォーマット
  2026-03-31 12:34:56.789 I メッセージテキスト
  レベル文字: C=CRITICAL / E=ERROR / W=WARNING / I=INFO / V=VERBOSE

Definition in file trace-file-util.h.

## Macro Definition Documentation

## ◆ TRACE_FILE_UTIL_EXPORT

#define TRACE_FILE_UTIL_EXPORT

DLL エクスポート/インポート制御マクロ。

ビルド条件に応じて以下の値を取ります。

条件 | 値
--- | ---
Linux (非 Windows) | (空)
Windows / __INTELLISENSE__ 定義時 | (空)
Windows / TRACE_FILE_UTIL_STATIC 定義時 (静的リンク) | (空)
Windows / TRACE_FILE_UTIL_EXPORTS 定義時 (DLL ビルド) | __declspec(dllexport)
Windows / TRACE_FILE_UTIL_EXPORTS 未定義時 (DLL 利用側) | __declspec(dllimport)

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

## ◆ TRACE_FILE_UTIL_API

#define TRACE_FILE_UTIL_API

呼び出し規約マクロ。

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

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

## ◆ TRACE_FILE_DEFAULT_MAX_BYTES

#define TRACE_FILE_DEFAULT_MAX_BYTES ((size_t)(10 * 1024 * 1024))

トレースファイル 1 世代あたりの既定最大サイズ (バイト)。

この値を超えるとローテーションが実行されます。
trace_file_provider_init の max_bytes に 0 を指定した場合に使用されます。

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

Referenced by trace_file_provider_init().

## ◆ TRACE_FILE_DEFAULT_GENERATIONS

#define TRACE_FILE_DEFAULT_GENERATIONS 5

保持するトレースファイル世代数の既定値。

ローテーション時に path.1 〜 path.N のファイルを保持します。
trace_file_provider_init の generations に 0 以下を指定した場合に使用されます。

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

Referenced by trace_file_provider_init().

## ◆ TRACE_FILE_LV_CRITICAL

#define TRACE_FILE_LV_CRITICAL 0

致命的エラー (trace-util.h の TRACE_LV_CRITICAL と同値)。

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

Referenced by level_char().

## ◆ TRACE_FILE_LV_ERROR

#define TRACE_FILE_LV_ERROR 1

エラー (trace-util.h の TRACE_LV_ERROR と同値)。

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

Referenced by level_char().

## ◆ TRACE_FILE_LV_WARNING

#define TRACE_FILE_LV_WARNING 2

警告 (trace-util.h の TRACE_LV_WARNING と同値)。

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

Referenced by level_char().

## ◆ TRACE_FILE_LV_INFO

#define TRACE_FILE_LV_INFO 3

情報 (trace-util.h の TRACE_LV_INFO と同値)。

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

Referenced by level_char().

## ◆ TRACE_FILE_LV_VERBOSE

#define TRACE_FILE_LV_VERBOSE 4

詳細 / デバッグ (trace-util.h の TRACE_LV_VERBOSE と同値)。

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

## Typedef Documentation

## ◆ trace_file_provider_t

typedef struct trace_file_provider trace_file_provider_t

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

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

## Function Documentation

## ◆ trace_file_provider_init()

TRACE_FILE_UTIL_EXPORT trace_file_provider_t *TRACE_FILE_UTIL_API trace_file_provider_init | ( | const char * | path,
|  | size_t | max_bytes,
|  | int | generations )

ファイルトレースプロバイダを初期化する。

指定されたファイルパスへの書き込みを開始します。
ファイルが存在する場合は追記します。存在しない場合は新規作成します。
max_bytes に 0 を指定した場合は TRACE_FILE_DEFAULT_MAX_BYTES を使用します。
generations に 0 以下を指定した場合は TRACE_FILE_DEFAULT_GENERATIONS を使用します。

ローテーション動作
  書き込み後にファイルサイズが max_bytes に達すると、以下の名前でファイルを保持します。
  path ... 現在のトレースファイル (新規作成)
  path.1 ... 直前の世代
  path.2 ... 2 世代前
  path.N ... N 世代前 (N = generations)
  generations 世代を超えた古いファイルは削除されます。

Parameters

  [in] | path | 出力ファイルパス。NULL の場合は NULL を返します。
  [in] | max_bytes | 1 ファイルあたりの最大バイト数。0 でデフォルト値を使用。
  [in] | generations | 保持する旧世代数。0 以下でデフォルト値を使用。

Returns
  成功時: ハンドル。失敗時: NULL。

使用例
  trace_file_provider_t *h = trace_file_provider_init(
  "C:\\logs\\myapp.log", 0, 0);
  trace_file_provider_init
  TRACE_FILE_UTIL_EXPORT trace_file_provider_t *TRACE_FILE_UTIL_API trace_file_provider_init(const char *path, size_t max_bytes, int generations)
  ファイルトレースプロバイダを初期化する。
  Definition file-provider.c:309
  trace_file_provider_t
  struct trace_file_provider trace_file_provider_t
  ファイルトレースプロバイダハンドル (不透明型)。
  Definition trace-file-util.h:112

Definition at line 309 of file file-provider.c.

References trace_file_provider::current_bytes, trace_file_provider::fd, trace_file_provider::generations, trace_file_provider::max_bytes, trace_file_provider::mutex, trace_file_provider::mutex_initialized, open_file(), trace_file_provider::path, TRACE_FILE_DEFAULT_GENERATIONS, TRACE_FILE_DEFAULT_MAX_BYTES, TRACE_FILE_PATH_MAX, and TRACE_FILE_SUFFIX_MAX.

Referenced by trace_modify_filetrc().

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

## ◆ trace_file_provider_write()

TRACE_FILE_UTIL_EXPORT int TRACE_FILE_UTIL_API trace_file_provider_write | ( | trace_file_provider_t * | handle,
|  | int | level,
|  | const char * | message )

ファイルへトレースメッセージを書き込む。

タイムスタンプとトレースレベル文字を付加し 1 行で書き込みます。
書き込み後にファイルサイズが max_bytes に達した場合はローテーションします。
handle または message が NULL の場合は何もせず 0 を返します。
ファイルがロックされている等の I/O 失敗は呼び出し元をブロックせず -1 を返します。

Parameters

  [in] | handle | trace_file_provider_init の戻り値。NULL は無視。
  [in] | level | トレースレベル (TRACE_FILE_LV_* 定数)。
  [in] | message | null 終端 UTF-8 文字列。NULL は無視。

Returns
  成功 0 / 失敗 -1。

Definition at line 387 of file file-provider.c.

References trace_file_provider::current_bytes, trace_file_provider::fd, FILE_LOCK_TIMEOUT_MS, format_timestamp(), level_char(), trace_file_provider::max_bytes, trace_file_provider::mutex, rotate_file(), TRACE_FILE_LINE_BUF, and TRACE_FILE_TS_LEN.

Referenced by write_dual().

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

## ◆ trace_file_provider_dispose()

TRACE_FILE_UTIL_EXPORT void TRACE_FILE_UTIL_API trace_file_provider_dispose | ( | trace_file_provider_t * | handle | ) |

ファイルトレースプロバイダを終了する。

ファイルハンドルを閉じ、ロック / mutex を解放してメモリを解放します。
ハンドルが NULL の場合は何もしません。

Parameters

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

Definition at line 508 of file file-provider.c.

References close_file(), trace_file_provider::mutex, trace_file_provider::mutex_initialized, and trace_file_provider::path.

Referenced by trace_dispose(), and trace_modify_filetrc().

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