## f_open

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

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

#### 引数

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

  値 | 意味
  --- | ---
  FA_READ | 読み出しモードで開きます。読み書きする場合は`FA_WRITE`と共に指定します。
  FA_WRITE | 書き込みモードで開きます。読み書きする場合は`FA_READ`と共に指定します。
  FA_OPEN_EXISTING | 既存のファイルを開きます。ファイルが無いときはエラーになります。(デフォルト)
  FA_OPEN_ALWAYS | 既存のファイルを開きます。ファイルが無いときはファイルを作成します。追記する場合は、この方法でオープンした後、`f_lseek()`でファイルの最後尾に移動してください。
  FA_CREATE_NEW | ファイルを作成します。同名のファイルがある場合は、エラーになります。
  FA_CREATE_ALWAYS | ファイルを作成します。同名のファイルがある場合は、サイズを0にしてから開きます。

#### 戻り値

FR_OK (0)
  正常終了。以降、`FileObject`構造体を使ってこのファイルを操作できます。
FR_NO_FILE
  ファイルが見つからない。
FR_NO_PATH
  パスが見つからない。
FR_INVALID_NAME
  ファイル名が不正。
FR_INVALID_DRIVE
  ドライブ番号が不正。
FR_EXIST
  同名のファイルが既にある。
FR_DENIED
  アクセスが拒否された。リード・オンリー・ファイルの書き込みモード・オープン、同名のディレクトリまたはリード・オンリー・ファイルがある状態でのファイル作成、ディスクまたはディレクトリ・テーブルが満杯でファイルを作成できないなど。
FR_NOT_READY
  メディアがセットされていないなど、物理ドライブが動作不能状態。
FR_WRITE_PROTECTED
  メディアが書き込み禁止状態で書き込み系オープンをした。
FR_DISK_ERR
  ディスク・エラーによる失敗。
FR_INT_ERR
  不正なFAT構造または内部エラーによる失敗。
FR_NOT_ENABLED
  その論理ドライブにワーク・エリアが割り当てられていない。
FR_NO_FILESYSTEM
  有効なFATボリュームが見つからない。
FR_LOCKED
  ファイル共有機能によるアクセス拒否。

#### 解説

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

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

#### 対応情報

全ての構成で使用可能です。`_FS_READONLY == 1`のときは、`FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW, FA_OPEN_ALWAYS`の各フラグはサポートされません。

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

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

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

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

        /* ドライブ0にデスティネーション・ファイルを作成する */
        res = f_open(&fdst, "0: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);

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

#### 参照

`f_read, f_write, f_close, FIL, FATFS`

戻る