util/include/fmtio-util.h

  • doxygen and doxybook2

  • Thu, 02 Apr 2026 21:25:28 +0900

util/include/fmtio-util.h

1 ファイル

1.1 util/include/fmtio-util.h

1.1.1 インクルード元

fmtio-util.h のインクルード元

2 関数

2.1 fopenf

FMTIO_UTIL_EXPORT FILE *FMTIO_UTIL_API fopenf ( const char *modes, int *errno_out, const char *format, ... )

printf 形式でファイル名を指定してファイルを開きます。

本関数は、呼び出し元が printf と同様の書式指定を用いてファイル名を組み立てられるようにするための fopen ラッパー関数です。

指定された書式文字列 (format) と可変引数 (…) からファイル名を生成し、その結果を用いてファイルをオープンします。

書式展開には vsnprintf を使用し、生成されたファイル名が OS の制限や内部バッファ長に収まらない場合、またはファイルのオープンに失敗した場合は NULL を返します。

失敗理由の取得が必要な場合は errno_out を指定してください。 指定された場合、環境に応じたエラーコードを格納します。

2.1.1 引数

  • modes [in] ファイルのオープン モード (“r”, “w”, “a”, “rb”, “wb” など)。
  • errno_out [out] エラー コードの格納先。 Linux では errno の値、Windows では fopen_s の戻り値を格納します。 NULL を指定した場合、エラー コードの取得は行いません。
  • format [in] ファイル名の書式文字列 (printf 形式)。
  • … [in] 書式文字列に対応する可変引数。

2.1.2 戻り値

成功した場合は FILE* を返します。失敗した場合は NULL を返します。

2.1.3 補足

ファイル名の最大長は OS の制限に従います (Windows: MAX_PATH=260, Linux: PATH_MAX=通常4096)。

2.1.4 使用例 (エラー コードの取得なし)

FILE *fp = fopenf("r", NULL, "data_%d.txt", 123);

2.1.5 使用例 (エラー コードの取得あり)

int err;
FILE *fp = fopenf("r", &err, "data_%d.txt", 123);

2.2 statf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API statf ( file_stat_t *buf, const char *format, ... )

printf 形式でファイル名を指定する stat ラッパー関数

この関数は、printf と同じ形式でファイル名を指定してファイル情報を取得します。 内部で vsnprintf を使用してファイル名をフォーマットし、stat を呼び出します。

2.2.1 引数

  • buf [out] ファイル情報を格納する構造体へのポインタ (file_stat_t 型)
  • format [in] ファイル名のフォーマット文字列 (printf 形式)
  • … [in] フォーマット文字列の可変引数

2.2.2 戻り値

成功時は 0、失敗時は -1

2.2.3 補足

2.2.3.1 ファイル名の最大長は OS の規定値です (Windows: MAX_PATH=260, Linux: PATH_MAX=通常4096)

2.2.3.2 file_stat_t は、Linux では struct stat、Windows では struct _stat64 の typedef です

2.2.3.3 Linux では stat()、Windows では _stat64() を使用します

2.2.4 警告

Linux と Windows では構造体のフィールドが異なるため、プラットフォーム固有のコードが必要です

  • Windows には st_blksize, st_blocks フィールドがありません
  • st_ctime は Linux ではメタデータ変更時刻、Windows では作成時刻を表します

2.2.5 使用例

file_stat_t st; int ret = statf(&st, "data_%d.txt", 123);

2.3 vfopenf

FMTIO_UTIL_EXPORT FILE *FMTIO_UTIL_API vfopenf ( const char *modes, int *errno_out, const char *format, va_list args )

printf 形式でファイル名を指定してファイルを開きます (va_list 版)。

fopenf() と同等ですが、可変引数リストの代わりに va_list を受け取ります。 上位のラッパー関数やマクロから va_list を転送する場合に使用します。

2.3.1 引数

  • modes [in] ファイルのオープン モード (“r”, “w”, “a”, “rb”, “wb” など)。
  • errno_out [out] エラー コードの格納先。NULL を指定した場合、エラー コードの取得は行いません。
  • format [in] ファイル名の書式文字列 (printf 形式)。
  • args [in] 書式文字列に対応する可変引数リスト。

2.3.2 戻り値

成功した場合は FILE* を返します。失敗した場合は NULL を返します。

2.3.3 参照

fopenf

2.4 vstatf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API vstatf ( file_stat_t *buf, const char *format, va_list args )

printf 形式でファイル名を指定する stat ラッパー関数 (va_list 版)。

statf() と同等ですが、可変引数リストの代わりに va_list を受け取ります。

2.4.1 引数

  • buf [out] ファイル情報を格納する構造体へのポインタ (file_stat_t 型)
  • format [in] ファイル名のフォーマット文字列 (printf 形式)
  • args [in] フォーマット文字列に対応する可変引数リスト

2.4.2 戻り値

成功時は 0、失敗時は -1

2.4.3 参照

statf

2.5 removef

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API removef ( const char *format, ... )

printf 形式でファイル名を指定してファイルを削除します。

本関数は、printf と同じ形式でファイル名を指定してファイルを削除するための remove ラッパー関数です。

指定された書式文字列 (format) と可変引数 (…) からファイル名を生成し、その結果を用いてファイルを削除します。

2.5.1 引数

  • format [in] ファイル名の書式文字列 (printf 形式)。
  • … [in] 書式文字列に対応する可変引数。

2.5.2 戻り値

成功時は 0、失敗時は非ゼロ値を返します。

2.5.3 補足

ファイル名の最大長は OS の制限に従います (Windows: MAX_PATH=260, Linux: PATH_MAX=通常4096)。

2.5.4 使用例

int ret = removef("data_%d.txt", 123);

2.5.5 参照

vremovef

2.6 vremovef

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API vremovef ( const char *format, va_list args )

printf 形式でファイル名を指定してファイルを削除します (va_list 版)。

removef() と同等ですが、可変引数リストの代わりに va_list を受け取ります。

2.6.1 引数

  • format [in] ファイル名の書式文字列 (printf 形式)。
  • args [in] 書式文字列に対応する可変引数リスト。

2.6.2 戻り値

成功時は 0、失敗時は非ゼロ値を返します。

2.6.3 参照

removef

2.7 openf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API openf ( int flags, int mode, const char *format, ... )

printf 形式でファイル名を指定してファイルを開きます (低レベル)。

本関数は、printf と同じ形式でファイル名を指定して低レベルファイルオープンを行うための open ラッパー関数です。

Linux では open()、Windows では _open() を使用します。

2.7.1 引数

  • flags [in] ファイルオープンフラグ (O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_TRUNC, O_APPEND など)。
  • mode [in] ファイル作成時のパーミッション (O_CREAT 指定時に使用)。 Linux では 0644 など、Windows では _S_IREAD | _S_IWRITE など。 O_CREAT を指定しない場合は 0 を渡してください。
  • format [in] ファイル名の書式文字列 (printf 形式)。
  • … [in] 書式文字列に対応する可変引数。

2.7.2 戻り値

成功時はファイルディスクリプタ (0 以上の整数)、失敗時は -1 を返します。

2.7.3 補足

2.7.3.1 ファイル名の最大長は OS の制限に従います (Windows: MAX_PATH=260, Linux: PATH_MAX=通常4096)。

2.7.3.2 Windows の CreateFileA が提供する FILE_SHARE_DELETE や FILE_FLAG_WRITE_THROUGH 等の 高度な機能は本関数ではサポートしません。

2.7.4 使用例

int fd = openf(O_WRONLY | O_CREAT | O_TRUNC, 0644, "log_%d.txt", pid);

2.7.5 参照

vopenf

2.8 vopenf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API vopenf ( int flags, int mode, const char *format, va_list args )

printf 形式でファイル名を指定してファイルを開きます (低レベル、va_list 版)。

openf() と同等ですが、可変引数リストの代わりに va_list を受け取ります。

2.8.1 引数

  • flags [in] ファイルオープンフラグ。
  • mode [in] ファイル作成時のパーミッション。
  • format [in] ファイル名の書式文字列 (printf 形式)。
  • args [in] 書式文字列に対応する可変引数リスト。

2.8.2 戻り値

成功時はファイルディスクリプタ、失敗時は -1 を返します。

2.8.3 参照

openf

2.9 accessf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API accessf ( int mode, const char *format, ... )

printf 形式でファイル名を指定してアクセス可否を確認します。

本関数は、printf と同じ形式でファイル名を指定してファイルの存在や アクセス権限を確認するための access ラッパー関数です。

Linux では access()、Windows では _access() を使用します。

2.9.1 引数

  • mode [in] 確認するアクセスモード。以下の定数を使用してください。
    • FMTIO_F_OK: ファイルの存在を確認
    • FMTIO_R_OK: 読み取り権限を確認
    • FMTIO_W_OK: 書き込み権限を確認
  • format [in] ファイル名の書式文字列 (printf 形式)。
  • … [in] 書式文字列に対応する可変引数。

2.9.2 戻り値

アクセス可能な場合は 0、不可の場合は -1 を返します。

2.9.3 補足

2.9.3.1 ファイル名の最大長は OS の制限に従います (Windows: MAX_PATH=260, Linux: PATH_MAX=通常4096)。

2.9.3.2 Windows の _access() は実行権限チェック (X_OK) をサポートしないため、 FMTIO_X_OK は提供しません。

2.9.4 使用例

if (accessf(FMTIO_F_OK, "config_%d.txt", instance_id) == 0)
{
    // ファイルが存在する
}

2.9.5 参照

vaccessf

2.10 vaccessf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API vaccessf ( int mode, const char *format, va_list args )

printf 形式でファイル名を指定してアクセス可否を確認します (va_list 版)。

accessf() と同等ですが、可変引数リストの代わりに va_list を受け取ります。

2.10.1 引数

  • mode [in] 確認するアクセスモード (FMTIO_F_OK, FMTIO_R_OK, FMTIO_W_OK)。
  • format [in] ファイル名の書式文字列 (printf 形式)。
  • args [in] 書式文字列に対応する可変引数リスト。

2.10.2 戻り値

アクセス可能な場合は 0、不可の場合は -1 を返します。

2.10.3 参照

accessf

2.11 mkdirf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API mkdirf ( const char *format, ... )

printf 形式でディレクトリ名を指定してディレクトリを作成します。

本関数は、printf と同じ形式でディレクトリ名を指定してディレクトリを作成するための mkdir ラッパー関数です。

Linux では mkdir() をパーミッション 0755 で呼び出します。 Windows では _mkdir() を呼び出します (パーミッション指定はありません)。

2.11.1 引数

  • format [in] ディレクトリ名の書式文字列 (printf 形式)。
  • … [in] 書式文字列に対応する可変引数。

2.11.2 戻り値

成功時は 0、失敗時は -1 を返します。

2.11.3 補足

2.11.3.1 ファイル名の最大長は OS の制限に従います (Windows: MAX_PATH=260, Linux: PATH_MAX=通常4096)。

2.11.3.2 親ディレクトリが存在しない場合は失敗します (再帰的なディレクトリ作成は行いません)。

2.11.4 使用例

int ret = mkdirf("logs_%04d", year);

2.11.5 参照

vmkdirf

2.12 vmkdirf

FMTIO_UTIL_EXPORT int FMTIO_UTIL_API vmkdirf ( const char *format, va_list args )

printf 形式でディレクトリ名を指定してディレクトリを作成します (va_list 版)。

mkdirf() と同等ですが、可変引数リストの代わりに va_list を受け取ります。

2.12.1 引数

  • format [in] ディレクトリ名の書式文字列 (printf 形式)。
  • args [in] 書式文字列に対応する可変引数リスト。

2.12.2 戻り値

成功時は 0、失敗時は -1 を返します。

2.12.3 参照

mkdirf

3 定数、マクロ

3.1 FMTIO_F_OK

#define FMTIO_F_OK 0

ファイルの存在を確認するモード定数。

accessf() の mode 引数に使用します。

3.2 FMTIO_R_OK

#define FMTIO_R_OK 4

ファイルの読み取り権限を確認するモード定数。

accessf() の mode 引数に使用します。

3.3 FMTIO_W_OK

#define FMTIO_W_OK 2

ファイルの書き込み権限を確認するモード定数。

accessf() の mode 引数に使用します。

3.4 FMTIO_UTIL_EXPORT

#define FMTIO_UTIL_EXPORT

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

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

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

3.5 FMTIO_UTIL_API

#define FMTIO_UTIL_API

呼び出し規約マクロ。

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

4 型

4.1 file_stat_t

typedef struct stat file_stat_t;