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 the items 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. When support of long file name is enabled, only fname[] is tested at _USE_FIND == 1 and also altname[] is tested at _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 names at the standard systems.
Any patterns terminated with a period never matches any name while it matches any 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 */

    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);
}