# FS_ReadFile

## 構文

    #include <nitro/fs.h>
    s32 FS_ReadFile( FSFile *p_file, void *dst, s32 len);

## 引数

file | 開いたファイルを指すFSFile構造体
dst | 転送先バッファ
len | 読み出すデータのバイト長

## 返り値

データが正しく読み出せればバイト数を, そうでないなら -1 を返します。

## 説明

ファイルポインタの現在位置から指定サイズのデータを読み出します。
終端を越えるようにサイズ指定した場合、終端まで読み出してそのサイズを返します。
ROM アーカイブを使用してカードデータを読み出す際には、 `CARD_ReadRomAsync()`の説明も参照ください。

この関数で実行される読み込み処理の詳細はアーカイブの実装によって異なり、 DMAやARM7コンポーネントなど外部メモリデバイスを利用する場合があります。 この関数の呼び出し前後におけるCPUキャッシュと実メモリとの整合性はFSライブラリが保証しますが、 関数が読み込み処理を完了するよりも前にアプリケーション側で読み込みバッファの内容を不用意に参照してしまうと CPUキャッシュと実メモリとの整合性が取れなくなってしまうため、 この関数に渡したバッファは処理が完了するまで参照すべきでありません。

## 注意

- この関数は処理の完了を待つためにスレッドを休止させることがあるため、割り込みハンドラ(IRQモード)から呼び出すことはできません。
- 割り込みを禁止したままの状態にあると処理が完了しない場合があります。
- 読み出したデータは、CPUキャッシュ上での同期は保証されていますが実メモリまで常にライトバックされている保証はありません。 DMAやDSP、ARM7など外部デバイスへのデータ転送のためのこのデータを使用する場合は明示的にキャッシュをストアする必要があります。

## 参照

`FSFile FS_OpenFileEx FS_OpenFileFast FS_CloseFile FS_GetFileLength FS_SeekFile FS_SeekFileToBegin FS_SeekFileToEnd`

## 履歴

2008/12/05 処理中のバッファを参照すべきでない旨を追記
2008/10/02 参照リストを一部更新
2008/02/27 読み出しデータのキャッシュ同期が無保証な点を追記。
2005/08/28 説明文に`CARD_ReadRomAsync()`へのリンクを追加
2004/09/24 呼び出し時および完了の条件についての注意を記述追加
2004/04/01 初版