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
正常終了。以降、FileObject構造体を使ってこのファイルを操作できます。ファイルを閉じるときは、f_close()を使用します。
FR_NOFILE
ファイルが見つからない。
FR_NOPATH
パスが見つからない。
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）を割り当てます。確保したワークエリアを0で初期化したあと、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のワークエリアを確保する
    memset(&fs, 0, sizeof(FATFS));
    FatFs = &fs;

    // ソース・ファイルを開く
    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;
        res = f_write(&fdst, buffer, br, &bw);
        if (res || bw < br) break;
    }

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

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

参照

f_read, f_write, f_close, FIL, FATFS

戻る