1e6865dcdSopenharmony_ci<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> 2e6865dcdSopenharmony_ci<html lang="en"> 3e6865dcdSopenharmony_ci<head> 4e6865dcdSopenharmony_ci<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 5e6865dcdSopenharmony_ci<meta http-equiv="Content-Style-Type" content="text/css"> 6e6865dcdSopenharmony_ci<link rel="up" title="FatFs" href="../00index_e.html"> 7e6865dcdSopenharmony_ci<link rel="alternate" hreflang="ja" title="Japanese" href="../ja/findfirst.html"> 8e6865dcdSopenharmony_ci<link rel="stylesheet" href="../css_e.css" type="text/css" media="screen" title="ELM Default"> 9e6865dcdSopenharmony_ci<title>FatFs - f_findfirst</title> 10e6865dcdSopenharmony_ci</head> 11e6865dcdSopenharmony_ci 12e6865dcdSopenharmony_ci<body> 13e6865dcdSopenharmony_ci 14e6865dcdSopenharmony_ci<div class="para func"> 15e6865dcdSopenharmony_ci<h2>f_findfirst</h2> 16e6865dcdSopenharmony_ci<p>The f_findfirst function searches a directroy for an item.</p> 17e6865dcdSopenharmony_ci<pre> 18e6865dcdSopenharmony_ciFRESULT f_findfirst ( 19e6865dcdSopenharmony_ci DIR* <span class="arg">dp</span>, <span class="c">/* [OUT] Poninter to the directory object */</span> 20e6865dcdSopenharmony_ci FILINFO* <span class="arg">fno</span>, <span class="c">/* [OUT] Pointer to the file information structure */</span> 21e6865dcdSopenharmony_ci const TCHAR* <span class="arg">path</span>, <span class="c">/* [IN] Pointer to the directory name to be opened */</span> 22e6865dcdSopenharmony_ci const TCHAR* <span class="arg">pattern</span> <span class="c">/* [IN] Pointer to the matching pattern string */</span> 23e6865dcdSopenharmony_ci); 24e6865dcdSopenharmony_ci</pre> 25e6865dcdSopenharmony_ci</div> 26e6865dcdSopenharmony_ci 27e6865dcdSopenharmony_ci<div class="para arg"> 28e6865dcdSopenharmony_ci<h4>Parameters</h4> 29e6865dcdSopenharmony_ci<dl class="par"> 30e6865dcdSopenharmony_ci<dt>dp</dt> 31e6865dcdSopenharmony_ci<dd>Pointer to the blank directory object.</dd> 32e6865dcdSopenharmony_ci<dt>fno</dt> 33e6865dcdSopenharmony_ci<dd>Pointer to the <a href="sfileinfo.html">file information structure</a> to store the information about the found item.</dd> 34e6865dcdSopenharmony_ci<dt>path</dt> 35e6865dcdSopenharmony_ci<dd>Pointer to the null-terminated string that specifies the <a href="filename.html">directory name</a> to be opened.</dd> 36e6865dcdSopenharmony_ci<dt>pattern</dt> 37e6865dcdSopenharmony_ci<dd>Pointer to the nul-terminated string that specifies the name matching pattern to be searched for. It is referred by also subsequent <tt>f_findnext</tt> function, so that the string must be valid while the successive function calls.</dd> 38e6865dcdSopenharmony_ci</dl> 39e6865dcdSopenharmony_ci</div> 40e6865dcdSopenharmony_ci 41e6865dcdSopenharmony_ci 42e6865dcdSopenharmony_ci<div class="para ret"> 43e6865dcdSopenharmony_ci<h4>Return Values</h4> 44e6865dcdSopenharmony_ci<p> 45e6865dcdSopenharmony_ci<a href="rc.html#ok">FR_OK</a>, 46e6865dcdSopenharmony_ci<a href="rc.html#de">FR_DISK_ERR</a>, 47e6865dcdSopenharmony_ci<a href="rc.html#ie">FR_INT_ERR</a>, 48e6865dcdSopenharmony_ci<a href="rc.html#nr">FR_NOT_READY</a>, 49e6865dcdSopenharmony_ci<a href="rc.html#np">FR_NO_PATH</a>, 50e6865dcdSopenharmony_ci<a href="rc.html#in">FR_INVALID_NAME</a>, 51e6865dcdSopenharmony_ci<a href="rc.html#io">FR_INVALID_OBJECT</a>, 52e6865dcdSopenharmony_ci<a href="rc.html#id">FR_INVALID_DRIVE</a>, 53e6865dcdSopenharmony_ci<a href="rc.html#ne">FR_NOT_ENABLED</a>, 54e6865dcdSopenharmony_ci<a href="rc.html#ns">FR_NO_FILESYSTEM</a>, 55e6865dcdSopenharmony_ci<a href="rc.html#tm">FR_TIMEOUT</a>, 56e6865dcdSopenharmony_ci<a href="rc.html#nc">FR_NOT_ENOUGH_CORE</a>, 57e6865dcdSopenharmony_ci<a href="rc.html#tf">FR_TOO_MANY_OPEN_FILES</a> 58e6865dcdSopenharmony_ci</p> 59e6865dcdSopenharmony_ci</div> 60e6865dcdSopenharmony_ci 61e6865dcdSopenharmony_ci 62e6865dcdSopenharmony_ci<div class="para desc"> 63e6865dcdSopenharmony_ci<h4>Description</h4> 64e6865dcdSopenharmony_ci<p>After the directory specified by <tt class="arg">path</tt> could be opened, it starts to search the directory for items with the matching pattern specified by <tt class="arg">pattern</tt>. If the first item is found, the information about the item is stored into the file information structure <tt class="arg">fno</tt>. If not found, <tt>fno->fname[]</tt> has a null string.</p> 65e6865dcdSopenharmony_ci<p>The matching pattern string can contain wildcards. For example:</p> 66e6865dcdSopenharmony_ci<ul> 67e6865dcdSopenharmony_ci<li><tt>?</tt> - An any character.</li> 68e6865dcdSopenharmony_ci<li><tt>???</tt> - An any string in length of three characters.</li> 69e6865dcdSopenharmony_ci<li><tt>*</tt> - An any string in length of zero or longer.</li> 70e6865dcdSopenharmony_ci<li><tt>????*</tt> - An any string in length of four characters or longer.</li> 71e6865dcdSopenharmony_ci</ul> 72e6865dcdSopenharmony_ci<p>Since the matching algorithm uses recursion, number of wildcards in the matching pattern is limited to four to limit the stack usage. Any pattern with too many wildcards does not match any name. In LFN configuration, only <tt>fname[]</tt> is tested when <tt>FF_USE_FIND == 1</tt> and also <tt>altname[]</tt> is tested when <tt>FF_USE_FIND == 2</tt>. There are some differences listed below between FatFs and standard systems in matching condition.</p> 73e6865dcdSopenharmony_ci<ul> 74e6865dcdSopenharmony_ci<li><tt>"*.*"</tt> does not match any name without extension while it matches any name with or without extension in standard systems.</li> 75e6865dcdSopenharmony_ci<li>Any pattern terminated with a dot does not match any name while it matches the name without extensiton in standard systems.</li> 76e6865dcdSopenharmony_ci<li><a href="filename.html#case">DBCS extended characters</a> are compared in case-sensitive when LFN is enabled with <tt>!FF_LFN_UNICODE</tt>.</li> 77e6865dcdSopenharmony_ci</ul> 78e6865dcdSopenharmony_ci</div> 79e6865dcdSopenharmony_ci 80e6865dcdSopenharmony_ci 81e6865dcdSopenharmony_ci<div class="para comp"> 82e6865dcdSopenharmony_ci<h4>QuickInfo</h4> 83e6865dcdSopenharmony_ci<p>This is a wrapper function of <a href="opendir.html"><tt>f_opendir</tt></a> and <a href="readdir.html"><tt>f_readdir</tt></a> function. Available when <tt><a href="config.html#use_find">FF_USE_FIND</a> >= 1</tt> and <tt><a href="config.html#fs_minimize">FF_FS_MINIMIZE</a> <= 1</tt>.</p> 84e6865dcdSopenharmony_ci</div> 85e6865dcdSopenharmony_ci 86e6865dcdSopenharmony_ci 87e6865dcdSopenharmony_ci<div class="para use"> 88e6865dcdSopenharmony_ci<h4>Examples</h4> 89e6865dcdSopenharmony_ci<pre> 90e6865dcdSopenharmony_ci<span class="c">/* Search a directory for objects and display it */</span> 91e6865dcdSopenharmony_ci 92e6865dcdSopenharmony_civoid find_image_file (void) 93e6865dcdSopenharmony_ci{ 94e6865dcdSopenharmony_ci FRESULT fr; <span class="c">/* Return value */</span> 95e6865dcdSopenharmony_ci DIR dj; <span class="c">/* Directory object */</span> 96e6865dcdSopenharmony_ci FILINFO fno; <span class="c">/* File information */</span> 97e6865dcdSopenharmony_ci 98e6865dcdSopenharmony_ci fr = <em>f_findfirst</em>(&dj, &fno, "", "????????.JPG"); <span class="c">/* Start to search for photo files */</span> 99e6865dcdSopenharmony_ci 100e6865dcdSopenharmony_ci while (fr == FR_OK && fno.fname[0]) { <span class="c">/* Repeat while an item is found */</span> 101e6865dcdSopenharmony_ci printf("%s\n", fno.fname); <span class="c">/* Print the object name */</span> 102e6865dcdSopenharmony_ci fr = f_findnext(&dj, &fno); <span class="c">/* Search for next item */</span> 103e6865dcdSopenharmony_ci } 104e6865dcdSopenharmony_ci 105e6865dcdSopenharmony_ci f_closedir(&dj); 106e6865dcdSopenharmony_ci} 107e6865dcdSopenharmony_ci</pre> 108e6865dcdSopenharmony_ci</div> 109e6865dcdSopenharmony_ci 110e6865dcdSopenharmony_ci 111e6865dcdSopenharmony_ci<div class="para ref"> 112e6865dcdSopenharmony_ci<h4>See Also</h4> 113e6865dcdSopenharmony_ci<p><tt><a href="findnext.html">f_findnext</a>, <a href="closedir.html">f_closedir</a>, <a href="sdir.html">DIR</a>, <a href="sfileinfo.html">FILINFO</a></tt></p> 114e6865dcdSopenharmony_ci</div> 115e6865dcdSopenharmony_ci 116e6865dcdSopenharmony_ci<p class="foot"><a href="../00index_e.html">Return</a></p> 117e6865dcdSopenharmony_ci</body> 118e6865dcdSopenharmony_ci</html> 119