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 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 standard systems in matching condition.

"*.*" never matches any name without extension. (It matches all names at the standard systems)
Any pattern terminated with a period never matches any name. (It matches the names without extensiton at the standard 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 = _MAX_LFN + 1;
#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);
}