# util/libsrc/util/file-provider.c

# 1 ファイル

## 1.1 util/libsrc/util/file-provider.c

# 2 関数

## 2.1 level_char

    static char level_char ( int level )

トレースレベル整数をレベル文字に変換する。

## 2.2 format_timestamp

    static void format_timestamp ( char *buf, int buf_size )

現在時刻を “YYYY-MM-DD HH:MM:SS.mmm” (UTC) 形式でバッファへ書き込む。

### 2.2.1 引数

- buf 書き込み先バッファ。
- buf_size バッファサイズ (TRACE_FILE_TS_LEN + 1 以上を推奨)。

## 2.3 open_file

    static int open_file ( trace_file_provider_t *p )

ファイルを追記モードで開き current_bytes を初期サイズで初期化する。

### 2.3.1 戻り値

成功 0 / 失敗 -1。

## 2.4 open_file_truncate

    static int open_file_truncate ( trace_file_provider_t *p )

ローテーション後の新規ファイルを空で作成して開く。 current_bytes は必ず 0 に設定される。

### 2.4.1 戻り値

成功 0 / 失敗 -1。

## 2.5 close_file

    static void close_file ( trace_file_provider_t *p )

開いているファイルを閉じる。未開の場合は何もしない (冪等)。

## 2.6 rotate_file

    static void rotate_file ( trace_file_provider_t *p )

トレースファイルをローテーションする。

ロック保持中から呼ばれる。
リネームに失敗した場合はその世代でカスケードを打ち切り、 呼び出し元をブロックせずに続行する (ベストエフォート)。

## 2.7 trace_file_provider_init

    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 を使用します。

### 2.7.1 引数

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

### 2.7.2 戻り値

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

### 2.7.3 ローテーション動作

書き込み後にファイルサイズが max_bytes に達すると、以下の名前でファイルを保持します。

    path     ... 現在のトレースファイル (新規作成)
    path.1   ... 直前の世代
    path.2   ... 2 世代前
    path.N   ... N 世代前 (N = generations)

generations 世代を超えた古いファイルは削除されます。

### 2.7.4 使用例

    trace_file_provider_t *h = trace_file_provider_init(
        "C:\\logs\\myapp.log", 0, 0);

## 2.8 trace_file_provider_write

    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 を返します。

### 2.8.1 引数

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

### 2.8.2 戻り値

成功 0 / 失敗 -1。

## 2.9 trace_file_provider_dispose

    void TRACE_FILE_UTIL_API trace_file_provider_dispose ( trace_file_provider_t *handle )

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

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

### 2.9.1 引数

- handle [in] trace_file_provider_init の戻り値。

# 3 定数、マクロ

## 3.1 TRACE_FILE_LINE_BUF

    #define TRACE_FILE_LINE_BUF 1100

1 行分のスタックバッファサイズ。

## 3.2 FILE_LOCK_TIMEOUT_MS

    #define FILE_LOCK_TIMEOUT_MS 100

ファイル書き込みロック取得のタイムアウト (ミリ秒)。

## 3.3 TRACE_FILE_TS_LEN

    #define TRACE_FILE_TS_LEN 23

タイムスタンプ部分の文字数 (“YYYY-MM-DD HH:MM:SS.mmm” = 23 文字)。

## 3.4 TRACE_FILE_SUFFIX_MAX

    #define TRACE_FILE_SUFFIX_MAX 5

ローテーションパスのサフィックス最大長 (“.999\0” = 5 文字)。

## 3.5 PATH_MAX

    #define PATH_MAX 4096

## 3.6 TRACE_FILE_PATH_MAX

    #define TRACE_FILE_PATH_MAX PATH_MAX

# 4 クラス/構造体

## 4.1 trace_file_provider

    struct trace_file_provider {
        char *path;
        size_t max_bytes;
        size_t current_bytes;
        int generations;
        int fd;
        pthread_mutex_t mutex;
        int mutex_initialized;
        int _pad_end;
    }

ファイルトレースプロバイダハンドル構造体 (内部定義)。

### 4.1.1 属性

#### 4.1.1.1 path

    char *path;

ヒープ確保済みファイルパス文字列。

#### 4.1.1.2 max_bytes

    size_t max_bytes;

ファイル 1 世代あたりの最大バイト数。

#### 4.1.1.3 current_bytes

    size_t current_bytes;

現ファイルへの書き込み済みバイト数 (インメモリ追跡)。

#### 4.1.1.4 generations

    int generations;

保持する旧世代数。

#### 4.1.1.5 fd

    int fd;

ファイルディスクリプタ。-1 = 未開。

#### 4.1.1.6 mutex

    pthread_mutex_t mutex;

スレッド安全のための mutex。

#### 4.1.1.7 mutex_initialized

    int mutex_initialized;

mutex が初期化済みかどうかのフラグ。

#### 4.1.1.8 _pad_end

    int _pad_end;

パディング (構造体サイズを 8 バイト境界に揃える)。