bertos/fs/fatfs/doc/en/readdir.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r
   2 <html lang="en">\r
   3 <head>\r
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">\r
   5 <meta http-equiv="Content-Style-Type" content="text/css">\r
   6 <link rel="up" title="FatFs" href="../00index_e.html">\r
   7 <link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r
   8 <title>FatFs - f_readdir</title>\r
   9 </head>\r
  10 \r
  11 <body>\r
  12 \r
  13 <div class="para">\r
  14 <h2>f_readdir</h2>\r
  15 <p>The f_readdir function reads directory entries.</p>\r
  16 <pre>\r
  17 FRESULT f_readdir (\r
  18   DIR* <em>DirObject</em>,    /* Pointer to the open directory object */\r
  19   FILINFO* <em>FileInfo</em>  /* Pointer to the file information structure */\r
  20 );\r
  21 </pre>\r
  22 </div>\r
  23 \r
  24 <div class="para">\r
  25 <h4>Parameters</h4>\r
  26 <dl class="par">\r
  27 <dt>DirObject</dt>\r
  28 <dd>Pointer to the open directory object.</dd>\r
  29 <dt>FileInfo</dt>\r
  30 <dd>Pointer to the file information structure to store the read item.</dd>\r
  31 </dl>\r
  32 </div>\r
  33 \r
  34 \r
  35 <div class="para">\r
  36 <h4>Return Values</h4>\r
  37 <dl class="ret">\r
  38 <dt>FR_OK (0)</dt>\r
  39 <dd>The function succeeded.</dd>\r
  40 <dt>FR_NOT_READY</dt>\r
  41 <dd>The disk drive cannot work due to no medium in the drive or any other reason.</dd>\r
  42 <dt>FR_DISK_ERR</dt>\r
  43 <dd>The function failed due to an error in the disk function.</dd>\r
  44 <dt>FR_INT_ERR</dt>\r
  45 <dd>The function failed due to a wrong FAT structure or an internal error.</dd>\r
  46 <dt>FR_INVALID_OBJECT</dt>\r
  47 <dd>The directory object is invalid.</dd>\r
  48 </dl>\r
  49 </div>\r
  50 \r
  51 \r
  52 <div class="para">\r
  53 <h4>Description</h4>\r
  54 <p>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 items have been read and no item to read, the function returns a null string into <tt>f_name[]</tt> member without any error. When a null pointer is given to the <tt>FileInfo</tt>, the read index of the directory object will be rewinded.</p>\r
  55 <p>When LFN feature is enabled, <tt>lfname</tt> and <tt>lfsize</tt> in the file information structure must be initialized with valid value prior to calling the f_readdir function. The <tt>lfname</tt> is a pointer to the string buffer to return the long file name. The <tt>lfsize</tt> is the size of the string buffer. When either the size of specified buffer or LFN working buffer is insufficient to store the LFN or LFN is not exist, a null string will be returned. When <tt>lfname</tt> is a NULL, nothing is returned.</p>\r
  56 <p>For details on the file informations, refer to the <tt>FILINFO</tt>. This function is not supported in minimization level of &gt;=2.</p>\r
  57 </div>\r
  58 \r
  59 \r
  60 <div class="para">\r
  61 <h4>Sample Code</h4>\r
  62 <pre>\r
  63 FRESULT scan_files (char* path)\r
  64 {\r
  65     FRESULT res;\r
  66     FILINFO fno;\r
  67     DIR dir;\r
  68     int i;\r
  69     char *fn;\r
  70 #if _USE_LFN\r
  71     static char lfn[_MAX_LFN * (_DF1S ? 2 : 1) + 1];\r
  72     fno.lfname = lfn;\r
  73     fno.lfsize = sizeof(lfn);\r
  74 #endif\r
  75 \r
  76 \r
  77     res = f_opendir(&amp;dir, path);\r
  78     if (res == FR_OK) {\r
  79         i = strlen(path);\r
  80         for (;;) {\r
  81             res = f_readdir(&amp;dir, &amp;fno);\r
  82             if (res != FR_OK || fno.fname[0] == 0) break;\r
  83 #if _USE_LFN\r
  84             fn = *fno.lfname ? fno.lfname : fno.fname;\r
  85 #else\r
  86             fn = fno.fname;\r
  87 #endif\r
  88             if (fno.fattrib &amp; AM_DIR) {\r
  89                 sprintf(&amp;path[i], "/%s", fn);\r
  90                 res = scan_files(path);\r
  91                 if (res != FR_OK) break;\r
  92                 path[i] = 0;\r
  93             } else {\r
  94                 printf("%s/%s\n", path, fn);\r
  95             }\r
  96         }\r
  97     }\r
  98 \r
  99     return res;\r
 100 }\r
 101 </pre>\r
 102 </div>\r
 103 \r
 104 \r
 105 <div class="para">\r
 106 <h4>References</h4>\r
 107 <p><tt><a href="opendir.html">f_opendir</a>, <a href="stat.html">f_stat</a>, <a href="sfileinfo.html">FILINFO</a>, <a href="sdir.html">DIR</a></tt></p>\r
 108 </div>\r
 109 \r
 110 <p class="foot"><a href="../00index_e.html">Return</a></p>\r
 111 </body>\r
 112 </html>\r