FatFs - f_findfirst

## 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 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 name specified by `pattern`. If the first item is 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. When support of long file name is enabled, only `fname[]` is tested at `FF_USE_FIND == 1` and also `altname[]` is tested at `FF_USE_FIND == 2`. In this revision, there are some differences listed below between FatFs and standard systems in matching condition.

- `"*.*"` never matches any name without extension while it matches any name with or without extension at the standard systems.
- Any pattern terminated with a period never matches any name while it matches any name without extensiton at the standard systems.
- DBCS extended characters are compared in case-sensitive at LFN with ANSI/OEM API.

#### 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 search object */
        FILINFO fno;    /* File information */

        fr = f_findfirst(&dj, &fno, "", "dsc*.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);                /* Display the object name */
            fr = f_findnext(&dj, &fno);               /* Search for next item */
        }

        f_closedir(&dj);
    }

#### See Also

`f_findnext, f_closedir, DIR, FILINFO`

Return