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.

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

See Also

f_findnext, f_closedir, DIR, FILINFO

Return