# FS_OpenFileEx[W]

## 構文

    #include <nitro/fs.h>

    BOOL FS_OpenFileEx(FSFile *file, const char *path, u32 mode);
    BOOL FS_OpenFileExW(FSFile *file, const u16 *path, u32 mode);

## 引数

file | ハンドルを格納すべきFSFile構造体
path | ファイルのパス名
mode | ファイルへのアクセスモード FS_FILEMODE_*のフラグを組み合わせて指定します。

## 返り値

ファイルハンドルが正しく開ければTRUEを、失敗すればFALSEを返します。
失敗時の詳細なエラーは`FS_GetResultCode()`で取得することができます。

## 説明

指定したファイルのハンドルを開きます。
パス名をShift_JISで指定する場合はFS_OpenFileEx()を、UTF16-LEで指定する場合はFS_OpenFileExW()を使用することができ、得られる結果は同じです。
開くことの出来るファイルにはいくつかの条件があります。

- ファイルは事前に存在している必要があり、FS_FILEMODE_Wを指定してこの関数を呼び出しても自動的に生成されることはありません。
  ファイルを生成新規するには`FS_CreateFile()`を使用する必要があります。
- FSライブラリがサポートしているファイル操作関数は2Gバイトまでであることから、意図せぬ誤動作を防止するため、2Gバイト以上のファイルを開こうとした場合は常に`FS_RESULT_PEMISSION_DENIED`を返して失敗します。
- NITROモードで動作しているときにTWL専用ファイルを開こうとした場合、`FS_RESULT_PEMISSION_DENIED`を返して失敗します。

得られたハンドルを使用してファイルアクセス用の各種関数を呼び出すことができます。
ハンドルを使用した後は`FS_CloseFile()`を呼び出して解放する必要があります。

## 注意

- この関数を割り込みハンドラ(IRQモード)から呼び出すことはできません。
  また、割り込みを禁止したままの状態にあると処理が完了しない場合がある点に注意して下さい。
- 開いたファイルの構造体はシステムリソースに関連付けられるため、 別の構造体にそのままコピーしても情報の移動や複製はできません。 詳細は`FSFile構造体`をご参照ください。

## 参照

`FSFile FSDirectoryEntryInfo
FS_ReadFile FS_WriteFile FS_SeekFile`

## 履歴

2009/07/14 構造体の値コピーが無保証である旨を追記
2009/06/08 TWL専用ファイルの説明へのリンクを追加。
2009/01/08 TWL専用ファイルに関する説明を追記。
2008/09/02 Unicode版の関数について追記。
2008/07/16 失敗時のエラーコード取得に関してFS_GetResultCode()を使用するよう記述を訂正。2Gバイトのサイズ制限に関して追記。
2008/06/10 ファイルが自動的に生成されない点について追記。
2007/09/18 初版