f_open

ファイルをオープンまたは作成します。

FRESULT f_open (
  FIL* FileObject,      // 空のファイルオブジェクト構造体へのポインタ
  const char* FileName, // ファイルのフルパス名へのポインタ
  BYTE ModeFlags        // モードフラグ
);

パラメータ

FileObject
新しく作成するファイルオブジェクト構造体へのポインタを指定します。以降、そのファイルを閉じるまでこのファイルオブジェクトを使用してファイル操作をします。
FileName
作成する (またはオープンする) ファイルのフルパス名が入った'\0'で終わる文字列へのポインタを指定します。ディレクトリセパレータには'/'を使用します。FatFsモジュールにはカレントディレクトリの概念がないので、パスはルートディレクトリから辿る絶対パスとなります。文字列先頭のスペースはスキップされます。パス先頭の'/'はあってもなくてもかまいません。
ModeFlags
ファイルのアクセス方法やオープン方法を決めるフラグです。このパラメータには次の組み合わせを指定します。
値意味
FA_READ読み出しモードでオープンします。読み書きする場合はFA_WRITEと共に指定します。
FA_WRITE書き込みモードでオープンします。読み書きする場合はFA_READと共に指定します。
FA_OPEN_EXISTING既存のファイルを開きます。ファイルが無いときはエラーになります。
FA_CREATE_ALWAYSファイルを作成します。既存のファイルがある場合は、サイズを0にしてから開きます。
FA_OPEN_ALWAYS既存のファイルを開きます。ファイルが無いときはファイルを作成します。

戻り値

FR_OK (0)
正常終了。以降、FileObject構造体を使ってこのファイルを操作できます。ファイルを閉じるときは、f_close()を使用します。
FR_NO_FILE
ファイルが見つからない。
FR_NO_PATH
パスが見つからない。
FR_INVALID_NAME
ファイル名が不正。
FR_DENIED
アクセスが拒否された。リードオンリーファイルの書き込みモードオープン、同名のディレクトリまたはリードオンリファイルがある状態でのファイル作成、ディスクまたはディレクトリテーブルが満杯でファイルを作成できないなど。
FR_NOT_READY
メディアがセットされていないなど、ディスクドライブが動作不能状態。
FR_WRITE_PROTECTED
メディアが書き込み禁止状態で書き込みオープンまたはファイル作成をした。
FR_RW_ERROR
ディスクアクセスでエラーが発生した。
FR_INCORRECT_DISK_CHANGE
不正なメディアの取り外しがあった。ファイルを開いたままのメディア交換など。
FR_NOT_ENABLED
FatFsモジュールが停止状態。
FR_NO_FILESYSTEM
ディスク上に有効なFATパーテーションが見つからない。

解説

FatFsモジュールの使用を開始するにはまず、FatFsモジュールのグローバル変数FatFsにゼロクリアしたワークエリア(FATFS構造体)のアドレスを代入します。このようにしてFatFsモジュールにワークエリアを割り当てるとモジュールは動作可能状態になり、ファイル関数が使えるようになります。ゼロクリアの代わりにf_mountdrv()でもOKですが、少なくともその時点で物理ドライブが動作可能になっていなければなりません。FatFsモジュールの使用を終了するには、全てのファイルを閉じたあとFatFsをクリアします。その後、ワークエリアは破棄できます。

リードオンリー構成では、FA_WRITE, FA_CREATE_ALWAYS, FA_OPEN_ALWAYSの各フラグはサポートされません。

使用例（ファイルコピー）

void main ()
{
    FATFS fs;            // FatFsワークエリア
    FIL fsrc, fdst;      // ファイルオブジェクト
    BYTE buffer[4096];   // file copy buffer
    FRESULT res;         // FatFs function common result code
    WORD br, bw;         // File R/W count


    // FatFsのワークエリアを確保する
    FatFs = &fs;
    memset(&fs, 0, sizeof(FATFS));      // ワークエリアの初期化。代わりに f_mountdrv() でもよい

    // ソース・ファイルを開く
    res = f_open(&fsrc, "srcfile.dat", FA_OPEN_EXISTING | FA_READ);
    if (res) die(res);

    // デスティネーション・ファイルを作成する
    res = f_open(&fdst, "dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
    if (res) die(res);

    // ソースからデスティネーションにコピーする
    for (;;) {
        res = f_read(&fsrc, buffer, sizeof(buffer), &br);
        if (res || br == 0) break;   // error or eof
        res = f_write(&fdst, buffer, br, &bw);
        if (res || bw < br) break;   // error or disk full
    }

    // 全てのファイルを閉じる
    f_close(&fsrc);
    f_close(&fdst);

    // FatFsのワークエリアを開放する
    FatFs = NULL;
}

参照

f_read, f_write, f_close, FIL, FATFS

戻る