1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 2<html lang="en"> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5<meta http-equiv="Content-Style-Type" content="text/css"> 6<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> 7<title>FatFs - f_readdir</title> 8</head> 9 10<body> 11 12<div class="para func"> 13<h2>f_readdir</h2> 14<p>The f_readdir function reads an item of the directory.</p> 15<pre> 16FRESULT f_readdir ( 17 DIR* <span class="arg">dp</span>, <span class="c">/* [IN] Directory object */</span> 18 FILINFO* <span class="arg">fno</span> <span class="c">/* [OUT] File information structure */</span> 19); 20</pre> 21<pre> 22FRESULT f_rewinddir ( 23 DIR* <span class="arg">dp</span> <span class="c">/* [IN] Directory object */</span> 24); 25</pre> 26</div> 27 28<div class="para arg"> 29<h4>Parameters</h4> 30<dl class="par"> 31<dt>dp</dt> 32<dd>Pointer to the open directory object.</dd> 33<dt>fno</dt> 34<dd>Pointer to the <a href="sfileinfo.html">file information structure</a> to store the information about read item. A null pointer rewinds the read index of the directory.</dd> 35</dl> 36</div> 37 38 39<div class="para ret"> 40<h4>Return Values</h4> 41<p> 42<a href="rc.html#ok">FR_OK</a>, 43<a href="rc.html#de">FR_DISK_ERR</a>, 44<a href="rc.html#ie">FR_INT_ERR</a>, 45<a href="rc.html#io">FR_INVALID_OBJECT</a>, 46<a href="rc.html#tm">FR_TIMEOUT</a>, 47<a href="rc.html#nc">FR_NOT_ENOUGH_CORE</a> 48</p> 49</div> 50 51 52<div class="para desc"> 53<h4>Description</h4> 54<p>The <tt>f_readdir</tt> function reads a directory item, informations about the object, from the open directory. Items in the directory can be read by <tt>f_readdir</tt> 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 <tt>fno->fname[]</tt> will be returned without an error. If a null pointer is given to the <tt class="arg">fno</tt>, the read index of the directory object will be rewound. The <tt>f_rewinddir</tt> function is implemented as a macro.</p> 55<pre> 56#define <em>f_rewinddir</em>(dp) f_readdir((dp), 0) 57</pre> 58<p>When LFN is enabled, a member <tt>altname[]</tt> 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 <tt>fname[]</tt> and the <tt>altname[]</tt> has a null string.</p> 59<ul> 60<li>The item has no LFN. (Not the case on the exFAT volume)</li> 61<li><a href="config.html#max_lfn"><tt>FF_MAX_LFN</tt></a> is insufficient to handle the LFN. (Not the case when <tt>FF_MAX_LFN == 255</tt>)</li> 62<li><a href="config.html#lfn_buf"><tt>FF_LFN_BUF</tt></a> is insufficient to store the LFN.</li> 63<li>The LFN contains some character not defined in current CP. (Not the case when <tt>FF_LFN_UNICODE != 0</tt>)</li> 64</ul> 65<p>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 <tt><a href="config.html#lfn_unicode">FF_LFN_UNICODE</a> != 0</tt> and <tt>FF_MAX_LFN == 255</tt> to support the full feature of LFN specification.</p> 66<p>Dot entries (<tt>"."</tt> and <tt>".."</tt>) 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.</p> 67</div> 68 69 70<div class="para comp"> 71<h4>QuickInfo</h4> 72<p>Available when <tt><a href="config.html#fs_minimize">FF_FS_MINIMIZE</a> <= 1</tt>.</p> 73</div> 74 75 76<div class="para use"> 77<h4>Sample Code</h4> 78<pre> 79<span class="c">/* List contents of a directory */</span> 80 81FRESULT list_dir (const char *path) 82{ 83 FRESULT res; 84 DIR dir; 85 FILINFO fno; 86 int nfile, ndir; 87 88 89 res = <em>f_opendir</em>(&dir, path); <span class="c">/* Open the directory */</span> 90 if (res == FR_OK) { 91 nfile = ndir = 0; 92 for (;;) { 93 res = <em>f_readdir</em>(&dir, &fno); <span class="c">/* Read a directory item */</span> 94 if (res != FR_OK || fno.fname[0] == 0) break; <span class="c">/* Error or end of dir */</span> 95 if (fno.fattrib & AM_DIR) { <span class="c">/* Directory */</span> 96 printf(" <DIR> %s\n", fno.fname); 97 ndir++; 98 } else { <span class="c">/* File */</span> 99 printf("%10u %s\n", fno.fsize, fno.fname); 100 nfile++; 101 } 102 } 103 <em>f_closedir</em>(&dir); 104 printf("%d dirs, %d files.\n", ndir, nfile); 105 } else { 106 printf("Failed to open \"%s\". (%u)\n", path, res); 107 } 108 return res; 109} 110</pre> 111<pre> 112<span class="c">/* Recursive scan of all items in the directory */</span> 113 114FRESULT scan_files ( 115 char* path <span class="c">/* Start node to be scanned (***also used as work area***) */</span> 116) 117{ 118 FRESULT res; 119 DIR dir; 120 UINT i; 121 static FILINFO fno; 122 123 124 res = <em>f_opendir</em>(&dir, path); <span class="c">/* Open the directory */</span> 125 if (res == FR_OK) { 126 for (;;) { 127 res = <em>f_readdir</em>(&dir, &fno); <span class="c">/* Read a directory item */</span> 128 if (res != FR_OK || fno.fname[0] == 0) break; <span class="c">/* Break on error or end of dir */</span> 129 if (fno.fattrib & AM_DIR) { <span class="c">/* It is a directory */</span> 130 i = strlen(path); 131 sprintf(&path[i], "/%s", fno.fname); 132 res = scan_files(path); <span class="c">/* Enter the directory */</span> 133 if (res != FR_OK) break; 134 path[i] = 0; 135 } else { <span class="c">/* It is a file. */</span> 136 printf("%s/%s\n", path, fno.fname); 137 } 138 } 139 <em>f_closedir</em>(&dir); 140 } 141 142 return res; 143} 144 145 146int main (void) 147{ 148 FATFS fs; 149 FRESULT res; 150 char buff[256]; 151 152 153 res = <em>f_mount</em>(&fs, "", 1); 154 if (res == FR_OK) { 155 strcpy(buff, "/"); 156 res = scan_files(buff); 157 } 158 159 return res; 160} 161</pre> 162</div> 163 164 165<div class="para ref"> 166<h4>See Also</h4> 167<p><tt><a href="opendir.html">f_opendir</a>, <a href="closedir.html">f_closedir</a>, <a href="stat.html">f_stat</a>, <a href="sfileinfo.html">FILINFO</a>, <a href="sdir.html">DIR</a></tt></p> 168</div> 169 170 171<p class="foot"><a href="../00index_e.html">Return</a></p> 172</body> 173</html> 174