FatFs - f_open

## f_open

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

    FRESULT f_open (
      FIL* fp,           /* [OUT] 空のファイル オブジェクト構造体へのポインタ */
      const TCHAR* path, /* [IN] ファイル名へのポインタ */
      BYTE mode          /* [IN] モードフラグ */
    );

#### 引数

fp
  新しく作成するファイル オブジェクト構造体へのポインタを指定します。以降、そのファイルを閉じるまでこのファイル オブジェクトを使用してファイル操作をします。
path
  開くファイルのファイル名を示すヌル文字`'\0'`終端の文字列へのポインタを指定します。
mode
  ファイルのアクセス方法やオープン方法を決めるフラグです。このパラメータには次の組み合わせを指定します。

  値 | 意味
  --- | ---
  FA_READ | 読み出しモードで開きます。読み書きする場合は`FA_WRITE`と共に指定します。
  FA_WRITE | 書き込みモードで開きます。読み書きする場合は`FA_READ`と共に指定します。
  FA_OPEN_EXISTING | 既存のファイルを開きます。ファイルが無いときはエラーになります。(デフォルト)
  FA_CREATE_NEW | ファイルを作成します。同名のファイルがある場合は、`FR_EXIST`で失敗します。
  FA_CREATE_ALWAYS | ファイルを作成します。同名のファイルがある場合は、サイズを0にしてから開きます。
  FA_OPEN_ALWAYS | 既存のファイルを開きます。ファイルが無いときはファイルを作成します。
  FA_OPEN_APPEND | `FA_OPEN_ALWAYS`と同じですが、リード/ライト ポインタはファイルの最後尾にセットされます。

#### 戻り値

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_FILE, FR_NO_PATH, FR_INVALID_NAME, FR_DENIED, FR_EXIST, FR_INVALID_OBJECT, FR_WRITE_PROTECTED, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_LOCKED, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES

#### 解説

既存のファイルを開いたり、新しいファイルを作成します。関数が成功するとファイル オブジェクトが作成され、以降そのファイルに対するアクセスに使用します。ファイルを閉じるときは、`f_close`関数を使用します。何らかの変更が行われたファイルがその後正しく閉じられなかった場合、そのファイルが破損する場合があります。

既に開かれているファイルを開く必要がある場合は、多重アクセス制御を参照してください。しかし、一つのファイルに対する書き込みモードを含む重複オープンは常に禁止です。

ファイル アクセスを開始する前に、`f_mount`関数を使ってそれぞれの論理ドライブにワーク エリア(ファイル システム オブジェクト)を与える必要があります。この初期化の後、その論理ドライブに対して全てのファイル関数が使えるようになります。`f_mkfs`関数と`f_fdsk`関数は、ワークエリア無しでも使えます。

#### 対応情報

全ての構成で使用可能です。`_FS_READONLY == 1`のときは、`FA_READ`と`FA_OPEN_EXISTING`以外の各フラグはサポートされません。

#### 使用例

    /* テキストファイルを読み出して表示 */

    FATFS FatFs;   /* 論理ドライブのワーク エリア(ファイル システム オブジェクト) */

    int main (void)
    {
        FIL fil;       /* ファイル オブジェクト */
        char line[82]; /* 行バッファ */
        FRESULT fr;    /* 戻り値 */

        /* デフォルト ドライブにワークエリアを与える */
        f_mount(&FatFs, "", 0);

        /* テキスト ファイルを開く */
        fr = f_open(&fil, "message.txt", FA_READ);
        if (fr) return (int)fr;

        /* 1行ずつ読み出して表示 */
        while (f_gets(line, sizeof line, &fil))
            printf(line);

        /* ファイルを閉じる */
        f_close(&fil);

        return 0;
    }

    /* ドライブ1のファイル "file.bin" をドライブ0へコピー */

    int main (void)
    {
        FATFS fs[2];         /* 論理ドライブのワークエリア(ファイル システム オブジェクト) */
        FIL fsrc, fdst;      /* ファイル オブジェクト */
        BYTE buffer[4096];   /* File copy buffer */
        FRESULT fr;          /* FatFs function common result code */
        UINT br, bw;         /* File R/W count */

        /* ドライブ0,1にワーク エリアを与える */
        f_mount(&fs[0], "0:", 0);
        f_mount(&fs[1], "1:", 0);

        /* ドライブ1のコピー元ファイルを開く */
        res = f_open(&fsrc, "1:file.dat", FA_OPEN_EXISTING | FA_READ);
        if (fr) return (int)fr;

        /* ドライブ0にコピー先ファイルを作成する */
        res = f_open(&fdst, "0:file.dat", FA_CREATE_ALWAYS | FA_WRITE);
        if (fr) return (int)fr;

        /* コピー元からコピー先にデータ転送する */
        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);

        /* ワーク エリアを開放する */
        f_mount(NULL, "0:", 0);
        f_mount(NULL, "1:", 0);

        return (int)fr;
    }

#### 参照

`f_read, f_write, f_close, FIL, FATFS`

戻る