[z180-stamp.git] / fatfs / documents / doc / readdir.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">\r
<html lang="en">\r
<head>\r
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">\r
<meta http-equiv="Content-Style-Type" content="text/css">\r
<link rel="up" title="FatFs" href="../00index_e.html">\r
<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/readdir.html">\r
<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r
<title>FatFs - f_readdir</title>\r
</head>\r
\r
<body>\r
\r
<div class="para func">\r
<h2>f_readdir</h2>\r
<p>The f_readdir function reads an item of the directory.</p>\r
<pre>\r
FRESULT f_readdir (\r
  DIR* <span class="arg">dp</span>,      <span class="c">/* [IN] Directory object */</span>\r
  FILINFO* <span class="arg">fno</span>  <span class="c">/* [OUT] File information structure */</span>\r
);\r
</pre>\r
</div>\r
\r
<div class="para arg">\r
<h4>Parameters</h4>\r
<dl class="par">\r
<dt>dp</dt>\r
<dd>Pointer to the open directory object.</dd>\r
<dt>fno</dt>\r
<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>\r
</dl>\r
</div>\r
\r
\r
<div class="para ret">\r
<h4>Return Values</h4>\r
<p>\r
<a href="rc.html#ok">FR_OK</a>,\r
<a href="rc.html#de">FR_DISK_ERR</a>,\r
<a href="rc.html#ie">FR_INT_ERR</a>,\r
<a href="rc.html#io">FR_INVALID_OBJECT</a>,\r
<a href="rc.html#tm">FR_TIMEOUT</a>,\r
<a href="rc.html#nc">FR_NOT_ENOUGH_CORE</a>\r
</p>\r
</div>\r
\r
\r
<div class="para desc">\r
<h4>Description</h4>\r
<p>The <tt>f_readdir</tt> function reads a directory item, informations about the object. All items in the directory can be read in sequence by <tt>f_readdir</tt> function calls. Dot entries (<tt>"."</tt> and <tt>".."</tt>) 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 <tt>fno-&gt;fname[]</tt> without any error. When a null pointer is given to the <tt class="arg">fno</tt>, the read index of the directory object is rewinded.</p>\r
<p>When support of long file name (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 some reason listed below, short file name is stored to the <tt>fname[]</tt> and <tt>altname[]</tt> has a null string.</p>\r
<ul>\r
<li>The item has no LFN. (Not the case at exFAT volume)</li>\r
<li>Setting of <a href="config.html#max_lfn"><tt>FF_MAX_LFN</tt></a> is insufficient to handle the LFN. (Not the case at <tt>FF_MAX_LFN == 255</tt>)</li>\r
<li>Setting of <a href="config.html#lfn_buf"><tt>FF_LFN_BUF</tt></a> is insufficient to store the LFN.</li>\r
<li>The LFN contains any character not defined in current code page. (Not the case at <tt>FF_LFN_UNICODE &gt;= 1</tt>)</li>\r
</ul>\r
<p>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, "?" is returned into the <tt>fname[]</tt> 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> &gt;= 1</tt> and <tt>FF_MAX_LFN == 255</tt> to support the full feature of LFN specification.</p>\r
</div>\r
\r
\r
<div class="para comp">\r
<h4>QuickInfo</h4>\r
<p>Available when <tt><a href="config.html#fs_minimize">FF_FS_MINIMIZE</a> &lt;= 1</tt>.</p>\r
</div>\r
\r
\r
<div class="para use">\r
<h4>Sample Code</h4>\r
<pre>\r
FRESULT scan_files (\r
    char* path        <span class="c">/* Start node to be scanned (***also used as work area***) */</span>\r
)\r
{\r
    FRESULT res;\r
    DIR dir;\r
    UINT i;\r
    static FILINFO fno;\r
\r
\r
    res = f_opendir(&amp;dir, path);                       <span class="c">/* Open the directory */</span>\r
    if (res == FR_OK) {\r
        for (;;) {\r
            res = <em>f_readdir</em>(&amp;dir, &amp;fno);                   <span class="c">/* Read a directory item */</span>\r
            if (res != FR_OK || fno.fname[0] == 0) break;  <span class="c">/* Break on error or end of dir */</span>\r
            if (fno.fattrib &amp; AM_DIR) {                    <span class="c">/* It is a directory */</span>\r
                i = strlen(path);\r
                sprintf(&amp;path[i], "/%s", fno.fname);\r
                res = scan_files(path);                    <span class="c">/* Enter the directory */</span>\r
                if (res != FR_OK) break;\r
                path[i] = 0;\r
            } else {                                       <span class="c">/* It is a file. */</span>\r
                printf("%s/%s\n", path, fno.fname);\r
            }\r
        }\r
        f_closedir(&amp;dir)\r
    }\r
\r
    return res;\r
}\r
\r
\r
int main (void)\r
{\r
    FATFS fs;\r
    FRESULT res;\r
    char buff[256];\r
\r
\r
    res = f_mount(&amp;fs, "", 1);\r
    if (res == FR_OK) {\r
        strcpy(buff, "/");\r
        res = scan_files(buff);\r
    }\r
\r
    return res;\r
}\r
</pre>\r
</div>\r
\r
\r
<div class="para ref">\r
<h4>See Also</h4>\r
<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>\r
</div>\r
\r
<p class="foot"><a href="../00index_e.html">Return</a></p>\r
</body>\r
</html>\r
Commit	Line	Data
53668523 L	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
289f6a14	4	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">\r
53668523 L	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="alternate" hreflang="ja" title="Japanese" href="../ja/readdir.html">\r
	8	<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default">\r
	9	<title>FatFs - f_readdir</title>\r
	10	</head>\r
	11	\r
	12	<body>\r
	13	\r
	14	<div class="para func">\r
	15	<h2>f_readdir</h2>\r
70702af1	16	<p>The f_readdir function reads an item of the directory.</p>\r
53668523 L	17	<pre>\r
	18	FRESULT f_readdir (\r
	19	DIR* <span class="arg">dp</span>, <span class="c">/* [IN] Directory object */</span>\r
	20	FILINFO* <span class="arg">fno</span> <span class="c">/* [OUT] File information structure */</span>\r
	21	);\r
	22	</pre>\r
	23	</div>\r
	24	\r
	25	<div class="para arg">\r
	26	<h4>Parameters</h4>\r
	27	<dl class="par">\r
	28	<dt>dp</dt>\r
289f6a14	29	<dd>Pointer to the open directory object.</dd>\r
53668523	30	<dt>fno</dt>\r
289f6a14	31	<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>\r
53668523 L	32	</dl>\r
	33	</div>\r
	34	\r
	35	\r
	36	<div class="para ret">\r
	37	<h4>Return Values</h4>\r
	38	<p>\r
	39	<a href="rc.html#ok">FR_OK</a>,\r
	40	<a href="rc.html#de">FR_DISK_ERR</a>,\r
	41	<a href="rc.html#ie">FR_INT_ERR</a>,\r
53668523 L	42	<a href="rc.html#io">FR_INVALID_OBJECT</a>,\r
	43	<a href="rc.html#tm">FR_TIMEOUT</a>,\r
	44	<a href="rc.html#nc">FR_NOT_ENOUGH_CORE</a>\r
	45	</p>\r
	46	</div>\r
	47	\r
	48	\r
	49	<div class="para desc">\r
	50	<h4>Description</h4>\r
70702af1	51	<p>The <tt>f_readdir</tt> function reads a directory item, informations about the object. All items in the directory can be read in sequence by <tt>f_readdir</tt> function calls. Dot entries (<tt>"."</tt> and <tt>".."</tt>) 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 <tt>fno->fname[]</tt> without any error. When a null pointer is given to the <tt class="arg">fno</tt>, the read index of the directory object is rewinded.</p>\r
289f6a14	52	<p>When support of long file name (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 some reason listed below, short file name is stored to the <tt>fname[]</tt> and <tt>altname[]</tt> has a null string.</p>\r
53668523	53	<ul>\r
289f6a14 L	54	<li>The item has no LFN. (Not the case at exFAT volume)</li>\r
	55	<li>Setting of <a href="config.html#max_lfn"><tt>FF_MAX_LFN</tt></a> is insufficient to handle the LFN. (Not the case at <tt>FF_MAX_LFN == 255</tt>)</li>\r
	56	<li>Setting of <a href="config.html#lfn_buf"><tt>FF_LFN_BUF</tt></a> is insufficient to store the LFN.</li>\r
	57	<li>The LFN contains any character not defined in current code page. (Not the case at <tt>FF_LFN_UNICODE >= 1</tt>)</li>\r
53668523	58	</ul>\r
289f6a14	59	<p>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, "?" is returned into the <tt>fname[]</tt> 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> >= 1</tt> and <tt>FF_MAX_LFN == 255</tt> to support the full feature of LFN specification.</p>\r
53668523 L	60	</div>\r
	61	\r
	62	\r
	63	<div class="para comp">\r
	64	<h4>QuickInfo</h4>\r
289f6a14	65	<p>Available when <tt><a href="config.html#fs_minimize">FF_FS_MINIMIZE</a> <= 1</tt>.</p>\r
53668523 L	66	</div>\r
	67	\r
	68	\r
	69	<div class="para use">\r
	70	<h4>Sample Code</h4>\r
	71	<pre>\r
	72	FRESULT scan_files (\r
70702af1	73	char* path <span class="c">/* Start node to be scanned (*also used as work area) /</span>\r
53668523 L	74	)\r
	75	{\r
	76	FRESULT res;\r
53668523	77	DIR dir;\r
70702af1 L	78	UINT i;\r
70702af1 L	79	static FILINFO fno;\r
53668523 L	80	\r
	81	\r
	82	res = f_opendir(&dir, path); <span class="c">/* Open the directory */</span>\r
	83	if (res == FR_OK) {\r
53668523	84	for (;;) {\r
289f6a14	85	res = <em>f_readdir</em>(&dir, &fno); <span class="c">/* Read a directory item */</span>\r
53668523	86	if (res != FR_OK \|\| fno.fname[0] == 0) break; <span class="c">/* Break on error or end of dir */</span>\r
53668523	87	if (fno.fattrib & AM_DIR) { <span class="c">/* It is a directory */</span>\r
70702af1 L	88	i = strlen(path);\r
	89	sprintf(&path[i], "/%s", fno.fname);\r
	90	res = scan_files(path); <span class="c">/* Enter the directory */</span>\r
7b78a5a2	91	if (res != FR_OK) break;\r
70702af1	92	path[i] = 0;\r
53668523	93	} else { <span class="c">/* It is a file. */</span>\r
70702af1	94	printf("%s/%s\n", path, fno.fname);\r
53668523 L	95	}\r
	96	}\r
	97	f_closedir(&dir)\r
	98	}\r
	99	\r
	100	return res;\r
	101	}\r
70702af1 L	102	\r
	103	\r
	104	int main (void)\r
	105	{\r
	106	FATFS fs;\r
	107	FRESULT res;\r
	108	char buff[256];\r
	109	\r
	110	\r
	111	res = f_mount(&fs, "", 1);\r
	112	if (res == FR_OK) {\r
	113	strcpy(buff, "/");\r
	114	res = scan_files(buff);\r
	115	}\r
	116	\r
	117	return res;\r
	118	}\r
53668523 L	119	</pre>\r
	120	</div>\r
	121	\r
	122	\r
	123	<div class="para ref">\r
	124	<h4>See Also</h4>\r
	125	<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>\r
	126	</div>\r
	127	\r
	128	<p class="foot"><a href="../00index_e.html">Return</a></p>\r
	129	</body>\r
	130	</html>\r