## f_readdir

The f_readdir function reads an item of the directory.

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

    FRESULT f_rewinddir (
      DIR* dp       /* [IN] Directory object */
    );

#### Parameters

dp
  Pointer to the open directory object.
fno
  Pointer to the file information structure to store the information about read item. A null pointer rewinds the read index of the directory.

#### Return Values

FR_OK, FR_DISK_ERR, FR_INT_ERR, FR_INVALID_OBJECT, FR_TIMEOUT, FR_NOT_ENOUGH_CORE

#### Description

The `f_readdir` function reads a directory item, informations about the object, from the open directory. Items in the directory can be read by `f_readdir` function calls in order of the directory table. When all items in the directory have been read and no item to read any more, a null string in `fno->fname[]` will be returned without an error. If a null pointer is given to the `fno`, the read index of the directory object will be rewound. The `f_rewinddir` function is implemented as a macro.

    #define f_rewinddir(dp) f_readdir((dp), 0)

When LFN is enabled, a member `altname[]` is defined in the file information structure to store the short file name of the object. If the long file name is not accessible due to any reason listed below, short file name is stored to the `fname[]` and the `altname[]` has a null string.

- The item has no LFN. (Not the case on the exFAT volume)
- `FF_MAX_LFN` is insufficient to handle the LFN. (Not the case when `FF_MAX_LFN == 255`)
- `FF_LFN_BUF` is insufficient to store the LFN.
- The LFN contains some character not defined in current CP. (Not the case when `FF_LFN_UNICODE != 0`)

There is an issue on read the directories on the exFAT volume. The exFAT does not support short file name. This means no name can be returned on the condition above. If it is the case, "?" is returned as the file name to indicate that the object is not accessible. To avoid this problem, configure FatFs `FF_LFN_UNICODE != 0` and `FF_MAX_LFN == 255` to support the full feature of LFN specification.

Dot entries (`"."` and `".."`) in the sub-directory of FAT volume are filtered out and they will never appear in the read items because of the consistency with exFAT which lacks dot entries in the sub-directory.

#### QuickInfo

Available when `FF_FS_MINIMIZE <= 1`.

#### Sample Code

    /* List contents of a directory */

    FRESULT list_dir (const char *path)
    {
        FRESULT res;
        DIR dir;
        FILINFO fno;
        int nfile, ndir;

        res = f_opendir(&dir, path);                       /* Open the directory */
        if (res == FR_OK) {
            nfile = ndir = 0;
            for (;;) {
                res = f_readdir(&dir, &fno);                   /* Read a directory item */
                if (res != FR_OK || fno.fname[0] == 0) break;  /* Error or end of dir */
                if (fno.fattrib & AM_DIR) {            /* Directory */
                    printf("   <DIR>   %s\n", fno.fname);
                    ndir++;
                } else {                               /* File */
                    printf("%10u %s\n", fno.fsize, fno.fname);
                    nfile++;
                }
            }
            f_closedir(&dir);
            printf("%d dirs, %d files.\n", ndir, nfile);
        } else {
            printf("Failed to open \"%s\". (%u)\n", path, res);
        }
        return res;
    }

    /* Recursive scan of all items in the directory */

    FRESULT scan_files (
        char* path        /* Start node to be scanned (***also used as work area***) */
    )
    {
        FRESULT res;
        DIR dir;
        UINT i;
        static FILINFO fno;

        res = f_opendir(&dir, path);                       /* Open the directory */
        if (res == FR_OK) {
            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.fattrib & AM_DIR) {                    /* It is a directory */
                    i = strlen(path);
                    sprintf(&path[i], "/%s", fno.fname);
                    res = scan_files(path);                    /* Enter the directory */
                    if (res != FR_OK) break;
                    path[i] = 0;
                } else {                                       /* It is a file. */
                    printf("%s/%s\n", path, fno.fname);
                }
            }
            f_closedir(&dir);
        }

        return res;
    }

    int main (void)
    {
        FATFS fs;
        FRESULT res;
        char buff[256];

        res = f_mount(&fs, "", 1);
        if (res == FR_OK) {
            strcpy(buff, "/");
            res = scan_files(buff);
        }

        return res;
    }

#### See Also

`f_opendir, f_closedir, f_stat, FILINFO, DIR`

Return