GL CHOCO ENGINE
Loading...
Searching...
No Matches
Data Structures | Functions
filesystem.c File Reference
Engine » Core » File System

ファイルシステムモジュールAPIの実装 More...

#include <stddef.h>
#include <stdio.h>
#include <stdbool.h>
#include "engine/core/filesystem/filesystem.h"
#include "engine/base/choco_macros.h"
#include "engine/base/choco_message.h"
#include "engine/core/memory/choco_memory.h"
Include dependency graph for filesystem.c:

Data Structures

struct  filesystem
 ファイルシステムモジュール内部状態管理構造体 More...
 

Functions

filesystem_result_t filesystem_create (filesystem_t **filesystem_)
 filesystem_t構造体インスタンスを生成し、初期化する
 
void filesystem_destroy (filesystem_t **filesystem_)
 filesystem_が管理しているメモリと自身のメモリを解放し、*filesystem_=NULLにする
 
filesystem_result_t filesystem_open (filesystem_t *filesystem_, const char *fullpath_, filesystem_open_mode_t mode_)
 filesystem_が保持するファイルハンドルをオープンする
 
filesystem_result_t filesystem_close (filesystem_t *filesystem_)
 filesystem_が保持するファイルハンドルをクローズする
 
filesystem_result_t filesystem_byte_read (filesystem_t *filesystem_, size_t read_bytes_, size_t *result_n_, char *buffer_)
 ファイルからバイト単位でデータを読み込む
 
const char * filesystem_open_mode_c_str (filesystem_open_mode_t mode_)
 ファイルオープンモードを文字列に変換する
 

Detailed Description

ファイルシステムモジュールAPIの実装

Author
chocolate-pie24
Version
0.1
Date
2025-12-23
Copyright
Copyright (c) 2025 chocolate-pie24
License
MIT License. See LICENSE file in the project root for full license text.

Function Documentation

◆ filesystem_byte_read()

filesystem_result_t filesystem_byte_read ( filesystem_t *  filesystem_,
size_t  read_bytes_,
size_t *  result_n_,
char *  buffer_ 
)

ファイルからバイト単位でデータを読み込む

Note
  • 本APIは、成功した場合のみ引数のポインタにデータを書き込むのではなく、失敗した場合でもデータが書き込まれる。 これは、ロールバックするためには本API内部でread_bytes_サイズの一時バッファを確保しなければならず、パフォーマンスが低下するため、 readの結果は引数のbuffer_に直接書き込むことにする。このため、返り値がエラーとなった場合にはbuffer_の中身を利用してはいけない。 なお、result_n_については、エラー発生時は値に0が代入される。
  • ファイルが末尾に到達し、指定したバイト数に満たないバイト数を読み込んだ場合でも、FILESYSTEM_SUCCESSを出力する。 このため、呼び出し側は必ず実行結果コードと合わせて実際に読み込んだバイト数を見て処理を行うこと。
  • 本APIを使用するためには、下記のいずれかのモードでfilesystem_openを行ったファイルハンドルを使用すること。
    • FILESYSTEM_MODE_READ
    • FILESYSTEM_MODE_READ_PLUS
    • FILESYSTEM_MODE_WRITE_PLUS
    • FILESYSTEM_MODE_APPEND_PLUS
    • FILESYSTEM_MODE_READ_BINARY
    • FILESYSTEM_MODE_READ_PLUS_BINARY
    • FILESYSTEM_MODE_WRITE_PLUS_BINARY
    • FILESYSTEM_MODE_APPEND_PLUS_BINARY
filesystem_t* filesystem = NULL;
filesystem_result_t ret = filesystem_create(&filesystem);
// エラー処理
ret = filesystem_open(filesystem, "/path/to/file", FILESYSTEM_MODE_READ);
// エラー処理
size_t read_size = 64;
size_t result = 0;
char buffer[128] = { 0 };
ret = filesystem_byte_read(filesystem, read_size, &result, buffer);
if(FILESYSTEM_SUCCESS == ret) {
if(result == read_size) {
// 正常読み込み
} else {
// ファイル末尾に到達し、指定バイト数未満を読み込み
}
} else {
// エラー処理
}
FILESYSTEM_MODE_READ
@ FILESYSTEM_MODE_READ
Definition: filesystem.h:60
filesystem_byte_read
filesystem_result_t filesystem_byte_read(filesystem_t *filesystem_, size_t read_bytes_, size_t *result_n_, char *buffer_)
ファイルからバイト単位でデータを読み込む
Definition: filesystem.c:249
filesystem_result_t
filesystem_result_t
ファイルシステムモジュールの実行結果コード定義
Definition: filesystem.h:42
FILESYSTEM_SUCCESS
@ FILESYSTEM_SUCCESS
Definition: filesystem.h:43
filesystem_open
filesystem_result_t filesystem_open(filesystem_t *filesystem_, const char *fullpath_, filesystem_open_mode_t mode_)
filesystem_が保持するファイルハンドルをオープンする
Definition: filesystem.c:185
filesystem_create
filesystem_result_t filesystem_create(filesystem_t **filesystem_)
filesystem_t構造体インスタンスを生成し、初期化する
Definition: filesystem.c:116
filesystem
ファイルシステムモジュール内部状態管理構造体
Definition: filesystem.c:31
Parameters
filesystem_読み込み対象ファイルハンドルを持つ構造体インスタンスへのポインタ
read_bytes_読み込みバイト数
result_n_実際に読み込みに成功したバイト数
buffer_データ格納先バッファ(バッファサイズはread_bytes_以上であること)
Return values
FILESYSTEM_INVALID_ARGUMENT以下のいずれか
  • filesystem_がNULL
  • result_n_がNULL
  • buffer_がNULL
  • read_bytes_が0
FILESYSTEM_RUNTIME_ERROR以下のいずれか
  • 無効なファイルハンドル(== NULL)が渡された
  • ファイル読み込みでエラーが発生
  • ファイルオープンモードが読み込み可能モードではない(本APIのnoteを参照)
FILESYSTEM_EOF読み込んだ結果EOFで読み取りバイト数ゼロ
FILESYSTEM_SUCCESS以下のいずれか
  • 読み込んだ結果EOFとなり指定バイト数未満を読み込み
  • 指定したバイト数の読み込みに成功し、正常終了

◆ filesystem_close()

filesystem_result_t filesystem_close ( filesystem_t *  filesystem_)

filesystem_が保持するファイルハンドルをクローズする

Note
  • FILESYSTEM_FILE_CLOSE_ERRORまたはFILESYSTEM_SUCCESSとなった場合、file_handleはNULL, modeはFILESYSTEM_MODE_NONEにリセットされる。
  • ファイルハンドルクローズには標準ライブラリのfcloseを使用する。 fcloseに失敗する事例として、NASとの接続断等によりファイルの変更内容のフラッシュに失敗した場合がある。 この場合、クローズ後のファイルハンドルは再利用不可となりFILESYSTEM_FILE_CLOSE_ERRORを返す。
filesystem_t* filesystem = NULL;
filesystem_result_t ret = filesystem_create(&filesystem);
// エラー処理
ret = filesystem_open(filesystem, "/path/to/file", FILESYSTEM_MODE_READ);
// エラー処理
ret = filesystem_close(filesystem);
// エラー処理
filesystem_close
filesystem_result_t filesystem_close(filesystem_t *filesystem_)
filesystem_が保持するファイルハンドルをクローズする
Definition: filesystem.c:220
Parameters
filesystem_クローズ対象構造体インスタンスへのポインタ
Return values
FILESYSTEM_INVALID_ARGUMENTfilesystem_がNULL
FILESYSTEM_RUNTIME_ERROR既にクローズ済のファイルハンドルが渡された
FILESYSTEM_FILE_CLOSE_ERRORファイルハンドルのクローズに失敗
FILESYSTEM_SUCCESSファイルハンドルのクローズに成功し、正常終了
Todo:
既にクローズ済のファイルハンドルが渡された場合の実行結果コードをBAD_OPERATIONに変更する

◆ filesystem_create()

filesystem_result_t filesystem_create ( filesystem_t **  filesystem_)

filesystem_t構造体インスタンスを生成し、初期化する

Note
filesystem_は下記の状態で初期化される
  • ファイルオープンモード: FILESYSTEM_MODE_NONE
  • ファイルハンドル(FILE*): NULL
生成したインスタンスは filesystem_destroy を使用して破棄する
filesystem_t* filesystem = NULL;
filesystem_result_t ret = filesystem_create(&filesystem);
// エラー処理
Parameters
filesystem_ファイルシステム内部状態管理構造体へのダブルポインタ
Return values
FILESYSTEM_INVALID_ARGUMENT以下のいずれか
  • filesystem_がNULL
  • *filesystem_が非NULL
  • memory_system_allocateがMEMORY_SYSTEM_INVALID_ARGUMENTを返した(これより前の処理で弾かれるため、基本的には起こり得ない)
FILESYSTEM_NO_MEMORYメモリ不足によりfilesystem_tのメモリ確保に失敗
FILESYSTEM_LIMIT_EXCEEDEDメモリシステムの管理変数がシステム使用可能範囲を超過
FILESYSTEM_UNDEFINED_ERROR未定義のエラーが発生
FILESYSTEM_SUCCESSfilesystem_のメモリ確保と初期化に成功し、正常終了

◆ filesystem_destroy()

void filesystem_destroy ( filesystem_t **  filesystem_)

filesystem_が管理しているメモリと自身のメモリを解放し、*filesystem_=NULLにする

Note
  • 2重デストロイ許可
  • filesystem_ == NULLの場合はno-op
  • *filesystem_ == NULLの場合はno-op
  • open済のファイルハンドルを持つ構造体インスタンスが渡された場合は、filesystem_close によるクローズ処理を行ってからメモリを解放する。 なお、クローズ処理は、エラーが発生した場合でも正常終了した場合でも、共にファイルハンドルが再利用不可となる。 そのため、filesystem_destroyでは、クローズ処理の成否に関わらず、メモリを解放する(ただしワーニングメッセージを出力する)。
filesystem_t* filesystem = NULL;
filesystem_result_t ret = filesystem_create(&filesystem);
// エラー処理
filesystem_destroy(&filesystem); // filesystem == NULLになる
filesystem_destroy(&filesystem); // 2重デストロイ許可
filesystem_destroy
void filesystem_destroy(filesystem_t **filesystem_)
filesystem_が管理しているメモリと自身のメモリを解放し、*filesystem_=NULLにする
Definition: filesystem.c:164
Parameters
filesystem_メモリ解放対象構造体インスタンスへのダブルポインタ

◆ filesystem_open()

filesystem_result_t filesystem_open ( filesystem_t *  filesystem_,
const char *  fullpath_,
filesystem_open_mode_t  mode_ 
)

filesystem_が保持するファイルハンドルをオープンする

filesystem_t* filesystem = NULL;
filesystem_result_t ret = filesystem_create(&filesystem);
// エラー処理
ret = filesystem_open(filesystem, "/path/to/file", FILESYSTEM_MODE_READ);
// エラー処理
Parameters
filesystem_オープン対象ファイルシステムモジュール構造体インスタンスへのポインタ
fullpath_オープンするファイルのフルパス
mode_ファイルオープンモード filesystem_open_mode_t
Return values
FILESYSTEM_INVALID_ARGUMENT以下のいずれか
  • filesystem_がNULL
  • fullpath_がNULL
  • mode_が未定義の値
FILESYSTEM_RUNTIME_ERROR既にオープン済のファイルハンドルが渡された
FILESYSTEM_FILE_OPEN_ERRORファイルオープン失敗
FILESYSTEM_SUCCESSファイルオープンに成功し、正常終了
Todo:
既にオープン済のファイルハンドルが渡された場合の実行結果コードをBAD_OPERATIONに変更する

◆ filesystem_open_mode_c_str()

const char * filesystem_open_mode_c_str ( filesystem_open_mode_t  mode_)

ファイルオープンモードを文字列に変換する

Note
不明なモードが入力された場合は文字列"undefined"が返される
Parameters
mode_ファイルオープンモード
Returns
const char* オープンモード文字列