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 _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 name with or without extension at the standard systems.
Any patterns 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 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);
}