FatFs - f_readdir

## f_readdir

The f_readdir function reads directory entries.

    FRESULT f_readdir (
      DIR* DirObject,    /* Pointer to the open directory object */
      FILINFO* FileInfo  /* Pointer to the file information structure */
    );

#### Parameters

DirObject
  Pointer to the open directory object.
FileInfo
  Pointer to the file information structure to store the read item.

#### Return Values

FR_OK (0)
  The function succeeded.
FR_NOT_READY
  The disk drive cannot work due to no medium in the drive or any other reason.
FR_DISK_ERR
  The function failed due to an error in the disk function.
FR_INT_ERR
  The function failed due to a wrong FAT structure or an internal error.
FR_INVALID_OBJECT
  The directory object is invalid.

#### Description

The f_readdir function reads directory entries in sequence. All items in the directory can be read by calling f_readdir function repeatedly. When all directory entries have been read and no item to read, the function returns a null string into `f_name[]` member without any error. When a null pointer is given to the `FileInfo`, 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 the f_readdir function. 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 character. 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, any small capitals can be contained in the SFN.

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

#### QuickInfo

Available when `_FS_MINIMIZE <= 1`.

#### Sample Code

    FRESULT scan_files (char* path)
    {
        FRESULT res;
        FILINFO fno;
        DIR dir;
        int i;
        char *fn;
    #if _USE_LFN
        static char lfn[_MAX_LFN * (_DF1S ? 2 : 1) + 1];
        fno.lfname = lfn;
        fno.lfsize = sizeof(lfn);
    #endif

        res = f_opendir(&dir, path);
        if (res == FR_OK) {
            i = strlen(path);
            for (;;) {
                res = f_readdir(&dir, &fno);
                if (res != FR_OK || fno.fname[0] == 0) break;
                if (fno.fname[0] == '.') continue;
    #if _USE_LFN
                fn = *fno.lfname ? fno.lfname : fno.fname;
    #else
                fn = fno.fname;
    #endif
                if (fno.fattrib & AM_DIR) {
                    sprintf(&path[i], "/%s", fn);
                    res = scan_files(path);
                    if (res != FR_OK) break;
                    path[i] = 0;
                } else {
                    printf("%s/%s\n", path, fn);
                }
            }
        }

        return res;
    }

#### See Also

`f_opendir, f_stat, FILINFO, DIR`

Return