## 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.
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 null-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 the item with a name specified by `pattern`. If found, the information about the object is stored into the file information structure. For more information about file information structure, refer to `f_readdir` function.

The matching pattern can contain wildcard characters (`?` and `*`). A `?` matches an any character and an `*` matches an any string in length of zero or longer. At LFN configuration, both names of the item, SFN and LFN (if exist), are tested. In this revision, there are some differences listed below between FatFs and reference systems in matching condition.

- `"*.*"` never matches any name without extension. (It matches all names at the reference systems)
- Any pattern terminated with a period never matche any name. (It matches any names without extensiton at the reference systems)
- DBCS extended characters are compared in case-sensitive at LFN with non-Unicode configuration.

#### QuickInfo

This is a wrapper function of `f_opendir` and `f_readdir` function. Available when `_USE_FIND == 1` and `_FS_MINIMIZE <= 1`.

#### Examples

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

    void find_image (void)
    {
        FRESULT fr;     /* Return value */
        DIR dj;         /* Directory search object */
        FILINFO fno;    /* File information */
    #if _USE_LFN
        char lfn[_MAX_LFN + 1];
        fno.lfname = lfn;
        fno.lfsize = sizeof lfn;
    #endif

        fr = f_findfirst(&dj, &fno, "", "dsc*.jpg");  /* Start to search for JPEG files with the name started by "dsc" */

        while (fr == FR_OK && fno.fname[0]) {         /* Repeat while an item is found */
    #if _USE_LFN
            printf("%-12s  %s\n", fno.fname, fno.lfname);/* Display the item name */
    #else
            printf("%s\n", fno.fname);
    #endif
            fr = f_findnext(&dj, &fno);               /* Search for next item */
        }
        f_closedir(&dj);
    }

#### See Also

`f_findnext, f_closedir, DIR, FILINFO`

Return