FatFs - f_readdir

## f_readdir

The f_readdir function reads directory entries.

    FRESULT f_readdir (
      DIR* dj,      /* [IN] Directory object */
      FILINFO* fno  /* [OUT] File information structure */
    );

#### Parameters

dj
  Pointer to the open directory object.
fno
  Pointer to the file information structure to store the read item.

#### Return Values

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_NOT_READY, FR_INVALID_OBJECT, FR_TIMEOUT, FR_NOT_ENOUGH_CORE

#### Description

The `f_readdir()` function reads directory items, file and directory, in sequence. All items in the directory can be read by calling `f_readdir()` function repeatedly. When all directory items have been read and no item to read, the function returns a null string into `fname[]` member without any error. When a null pointer is given to the `fno`, the read index of the directory object will be rewinded.

When LFN feature is enabled, `lfname` and `lfsize` in the file information structure must be initialized with valid value prior to use it. The `lfname` is a pointer to the string buffer to return the long file name. The `lfsize` is the size of the string buffer in unit of `TCHAR`. If either the size of read buffer or LFN working buffer is insufficient for the LFN or the object has no LFN, a null string will be returned to the LFN read buffer. If the LFN contains any charactrer that cannot be converted to OEM code, a null string will be returned but this is not the case on Unicode API configuration. When `lfname` is a null, nothing of the LFN is returned. When the object has no LFN, some small capitals can be contained in the SFN in the `fname[]`.

When relative path feature is enabled (`_FS_RPATH == 1`), dot entries ("." and "..") are not filtered out and they will appear in the read items.

#### QuickInfo

Available when `_FS_MINIMIZE <= 1`.

#### Sample Code

    FRESULT scan_files (
        char* path        /* Start node to be scanned (also used as work area) */
    )
    {
        FRESULT res;
        FILINFO fno;
        DIR dir;
        int i;
        char *fn;   /* This function is assuming non-Unicode cfg. */
    #if _USE_LFN
        static char lfn[_MAX_LFN + 1];
        fno.lfname = lfn;
        fno.lfsize = sizeof lfn;
    #endif

        res = f_opendir(&dir, path);                       /* Open the directory */
        if (res == FR_OK) {
            i = strlen(path);
            for (;;) {
                res = f_readdir(&dir, &fno);                   /* Read a directory item */
                if (res != FR_OK || fno.fname[0] == 0) break;  /* Break on error or end of dir */
                if (fno.fname[0] == '.') continue;             /* Ignore dot entry */
    #if _USE_LFN
                fn = *fno.lfname ? fno.lfname : fno.fname;
    #else
                fn = fno.fname;
    #endif
                if (fno.fattrib & AM_DIR) {                    /* It is a directory */
                    sprintf(&path[i], "/%s", fn);
                    res = scan_files(path);
                    if (res != FR_OK) break;
                    path[i] = 0;
                } else {                                       /* It is a file. */
                    printf("%s/%s\n", path, fn);
                }
            }
        }

        return res;
    }

#### See Also

`f_opendir, f_stat, FILINFO, DIR`

Return