# FatFs - f_readdir

## f_readdir

The f_readdir function reads directory entries.

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

#### Parameters

dp
  Pointer to the directory object created by `f_opendir` function.
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 directory items, informations about file and directory, in sequence. All items in the directory can be read by calling `f_readdir` function repeatedly. When relative path feature is enabled (`_FS_RPATH >= 1`), dot entries (`"."` and `".."`) are not filtered out and they will appear in the read items. When all directory items have been read and no item to read, a null 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 LFN feature is enabled, `fno->lfname` and `fno->lfsize` in the file information structure must be initialized with valid value prior to use it. The `lfname` points the LFN read buffer. The `lfsize` is size of the LFN read buffer in unit of `TCHAR`. If the LFN is not needed, set a null pointer to the `lfname` and the LFN is not returned. A null string will be returned into the LFN read buffer in case of following conditions.

- The directory item has no LFN information. In this case, lower case characters can be contained in the `fname[]`.
- Either the size of read buffer or LFN working buffer is insufficient for the LFN.
- The LFN contains any Unicode character that cannot be converted to OEM code. (Not the case at Unicode API configuration)

#### 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 assumes non-Unicode configuration */
    #if _USE_LFN
        static char lfn[_MAX_LFN + 1];   /* Buffer to store the LFN */
        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);
                    path[i] = 0;
                    if (res != FR_OK) break;
                } else {                                       /* It is a file. */
                    printf("%s/%s\n", path, fn);
                }
            }
            f_closedir(&dir)
        }

        return res;
    }

#### See Also

`f_opendir, f_closedir, f_stat, FILINFO, DIR`

Return