FatFs - f_readdir

## 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 */
    );

#### Parameters

dp
  Pointer to the open directory object or null pointer.
fno
  Pointer to the file information structure to store the information about read item.

#### 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. All items in the directory can be read in sequence by `f_readdir` function calls. Dot entries (`"."` and `".."`) in the sub-directory are filtered out and they will never appear in the read items. When all directory items have been read and no item to read, a nul string is stored into the `fno->fname[]` without any error. When a null pointer is given to the `fno`, the read index of the directory object is rewinded.

When support of long file name (LFN) is enabled, a member `altname[]` is defined in the file information structure to store the short file name of the object. In case of the some conditions listed below, short file name is stored into the `fname[]` and `altname[]` has a null string.

- The item has no long file name. (Not the case at exFAT volume)
- Setting of `_MAX_LFN` is insufficient for the long file name. (Not the case at `_MAX_LFN == 255`)
- The long file name contains any character not allowed in ANSI/OEM code. (Not the case at `_LFN_UNICODE == 1`)

There is a problem on reading a directory of 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, a "?" is returned as file name to indicate that the object is not accessible. To avoid this problem, configure FatFs `_LFN_UNICODE = 1` and `_MAX_LFN = 255` to support the full feature of LFN specification.

#### 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;
        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