f_open

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

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

パラメータ

FileObject
新しく作成するファイルオブジェクト構造体へのポインタを指定します。以降、このファイルを閉じるまでそのファイルオブジェクトを使用してファイル操作をします。構造体メンバのbufferは、オープン前または直後にそのファイルで使用するR/Wバッファへのアドレスで初期化しておく必要があります（FA_UNBUFFEREDを指定した場合はバッファは不要）。
FileName
作成する (またはオープンする) ファイルのフルパス名が入った'\0'で終わる文字列へのポインタを指定します。ディレクトリセパレータには'/'を使用します。FatFsモジュールにはカレントディレクトリの概念がないので、パスはルートディレクトリから辿る絶対パスとなります。文字列先頭のスペースはスキップされます。パス先頭の'/'はあってもなくてもかまいません。
ModeFlags
ファイルのアクセス方法やオープン方法を決めるフラグです。このパラメータには次の組み合わせを指定します。
値意味
FA_READ読み出しモードでオープンします。読み書きする場合はFA_WRITEと共に指定します。
FA_WRITE書き込みモードでオープンします。読み書きする場合はFA_READと共に指定します。
FA_UNBUFFERED FatFsでのみ指定可。指定するとファイルR/Wバッファを使用せず、メモリを節約できます。
read/write/seekは512の整数倍単位でなければなりません。指定しない場合は、ファイル
R/Wバッファ（ファイルオブジェクト構造体メンバのbufferで指定）を使用。
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 work area
    FIL fsrc, fdst;      // file structures
    BYTE fbuff[512*2];   // file r/w buffers (not required for Tiny-FatFs)
    BYTE buffer[4096];   // file copy buffer
    FRESULT res;         // FatFs function common result code
    WORD br, bw;         // File R/W count


    // Activate FatFs module
    memset(&fs, 0, sizeof(FATFS));
    FatFs = &fs;

    // Open source file
    fsrc.buffer = fbuff+0;	// (not required for Tiny-FatFs)
    res = f_open(&fsrc, "/srcfile.dat", FA_OPEN_EXISTING | FA_READ);
    if (res) die(res);

    // Create destination file
    fdst.buffer = fbuff+512;	// (not required for Tiny-FatFs)
    res = f_open(&fdst, "/dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
    if (res) die(res);

    // Copy source to destination
    for (;;) {
        res = f_read(&fsrc, buffer, sizeof(buffer), &br);
        if (res) die(res);
        if (br == 0) break;
        res = f_write(&fdst, buffer, br, &bw);
        if (res) die(res);
        if (bw < br) break;
    }

    // Close all files
    f_close(&fsrc);
    f_close(&fdst);

    // Deactivate FatFs module
    FatFs = NULL;
}

参照

f_read, f_write, f_close, FIL, FATFS

戻る