## f_findfirst

The f_findfirst function searches a directroy for an item.

    FRESULT f_findfirst (
      DIR* dp,              /* [OUT] Poninter to the directory object */
      FILINFO* fno,         /* [OUT] Pointer to the file information structure */
      const TCHAR* path,    /* [IN] Pointer to the directory name to be opened */
      const TCHAR* pattern  /* [IN] Pointer to the matching pattern string */
    );

#### Parameters

dp
  Pointer to the blank directory object. If a null pointer is given, the function fails with `FR_INVALID_OBJECT`.
fno
  Pointer to the file information structure to store the information about the found item.
path
  Pointer to the null-terminated string that specifies the directory name to be opened.
pattern
  Pointer to the nul-terminated string that specifies the name matching pattern to be searched for. It is referred by also subsequent `f_findnext` function, so that the string must be valid while the successive function calls.

#### Return Values

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

#### Description

After the directory specified by `path` could be opened, it starts to search the directory for items with the matching pattern specified by `pattern`. If the first item is found, the information about the item is stored into the file information structure `fno`. If not found, `fno->fname[]` has a null string.

The matching pattern string can contain wildcards. For example:

- `?` - An any character.
- `???` - An any string in length of three characters.
- `*` - An any string in length of zero or longer.
- `????*` - An any string in length of four characters or longer.

Since the matching algorithm uses recursion, number of wildcards in the matching pattern is limited to four to limit the stack usage. Any pattern with too many wildcards does not match any name. In LFN configuration, only `fname[]` is tested when `FF_USE_FIND == 1` and also `altname[]` is tested when `FF_USE_FIND == 2`. There are some differences listed below between FatFs and standard systems in matching condition.

- `"*.*"` does not match any name without extension while it matches any name with or without extension in standard systems.
- Any pattern terminated with a dot does not match any name while it matches the name without extensiton in standard systems.
- DBCS extended characters are compared in case-sensitive when LFN is enabled with `!FF_LFN_UNICODE`.

#### QuickInfo

This is a wrapper function of `f_opendir` and `f_readdir` function. Available when `FF_USE_FIND >= 1` and `FF_FS_MINIMIZE <= 1`.

#### Examples

    /* Search a directory for objects and display it */

    void find_image_file (void)
    {
        FRESULT fr;     /* Return value */
        DIR dj;         /* Directory object */
        FILINFO fno;    /* File information */

        fr = f_findfirst(&dj, &fno, "", "????????.JPG"); /* Start to search for photo files */

        while (fr == FR_OK && fno.fname[0]) {         /* Repeat while an item is found */
            printf("%s\n", fno.fname);                /* Print the object name */
            fr = f_findnext(&dj, &fno);               /* Search for next item */
        }

        f_closedir(&dj);
    }

#### See Also

`f_findnext, f_closedir, DIR, FILINFO`

Return