FatFs - f_findfirst

## f_findfirst

ディレクトリ内のオブジェクトの検索を開始します。

    FRESULT f_findfirst (
      DIR* dp,              /* [OUT] ディレクトリ オブジェクト構造体へのポインタ */
      FILINFO* fno,         /* [OUT] ファイル情報構造体へのポインタ */
      const TCHAR* path,    /* [IN] ディレクトリ名へのポインタ */
      const TCHAR* pattern  /* [IN] マッチ パターン文字列へのポインタ */
    );

#### 引数

dp
  空のディレクトリ オブジェクト構造体へのポインタを指定します。
fno
  最初にマッチしたディレクトリ項目を格納するファイル情報構造体へのポインタを指定します。
path
  オープンするディレクトリのパス名を示すヌル文字`'\0'`終端の文字列へのポインタを指定します。
pattern
  検索する名前を示すヌル文字`'\0'`終端の文字列へのポインタを指定します。この文字列は、続く`f_findnext`関数でも参照されるため、一連の処理が終了するまで有効でなければなりません。

#### 戻り値

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_NO_PATH, FR_INVALID_NAME, FR_INVALID_OBJECT, FR_INVALID_DRIVE, FR_NOT_ENABLED, FR_NO_FILESYSTEM, FR_TIMEOUT, FR_NOT_ENOUGH_CORE, FR_TOO_MANY_OPEN_FILES

#### 解説

`path`で指定されるディレクトリを開き、そのディレクトリ内の項目の検索を開始します。正常終了すると、ディレクトリ オブジェクト構造体が作成され、最初に検索名文字列に名前がマッチした項目の情報が`fno`の指定するファイル情報構造体にストアされます。名前のマッチする項目が見つからなかった場合は、`fno->fname[]`にヌル文字列が返されます。ファイル情報構造体の使い方については、`f_readdir`関数を参照してください。

マッチ パターン文字列は、ワイルドカード文字(`?`と`*`)を含むことができます。`?`は任意の1文字に、`*`は0文字以上の任意の文字列にマッチします。LFN構成では、`_USE_FIND = 1`のとき`fname[]`のみテストし、`_USE_FIND = 2`のときは`altname[]`もテストします。現リビジョンではパターン マッチングにおいて次の点で標準システムとは異なる動作となります。

- `"*.*"`は拡張子なしの名前にマッチしない。(標準システムでは全ての名前にマッチ)
- ピリオドで終わるパターンは、どの名前にもマッチしない。(標準システムでは拡張子無しの名前にマッチ)
- DBCS拡張文字については、LFN構成でも非Unicode API構成ではケース センシティブとなる。

#### 対応情報

この関数は、`f_opendir`関数および`f_readdir`関数のラッパー関数です。`_USE_FIND >= 1`で、かつ`_FS_MINIMIZE <= 1`のとき使用可能になります。

#### 使用例

    /* ディレクトリ内のjpegファイルの検索 */

    void find_image_file (void)
    {
        FRESULT fr;     /* API戻り値 */
        DIR dj;         /* ディレクトリ オブジェクト */
        FILINFO fno;    /* ファイル情報 */

        fr = f_findfirst(&dj, &fno, "", "dsc*.jpg");  /* "dsc"で始まるJPEGファイルを検索 */

        while (fr == FR_OK && fno.fname[0]) {         /* 見つかる間繰り返し */
            printf("%s\n", fno.fname);                /* 見つけた項目の名前を表示 */
            fr = f_findnext(&dj, &fno);               /* 次を検索 */
        }

        f_closedir(&dj);
    }

#### 参照

`f_findnext, f_closedir, DIR, FILINFO`

戻る