[Main]
Name=FFindFirst
Type=Function
Subtype=ROM Call
Header Files=files.h
Definition=SYM_ENTRY *FFindFirst (unsigned short Options, const char *typeName, const char *folderName);
MinAMS=2.00
See Also=TIOS_FFindNext: FFindNext, vat.h/SymFindFolderName

[ROM Call]
Index=$3D9

[Description]
Find the first file of a given type.

[Explanation]
FFindFirst finds the first file of the type <I>typeName</I> and returns a <A HREF="$$LINK(vat.h/SYM_ENTRY)">SYM_ENTRY</A>
pointer to it (or <A HREF="$$LINK(alloc.h/NULL)">NULL</A> if none found). <I>typeName</I> must point to a normal zero-terminated C string (i.e. not a tokenized form) of at most four characters which
describes the file type. Use <A HREF="$$LINK(TIOS_FFindNext)">FFindNext</A> to find subsequent
entries, <A HREF="$$LINK(alloc.h/NULL)">NULL</A> will be returned after the last entry is found.
<BR><BR>
<I>Options</I> can be one of the following flags as described in the <A HREF="$$LINK(vat.h/FindOptions)">FindOptions</A> enum:
<TABLE BORDER CELLPADDING="3">
<TR>
<TD>FO_NONE</TD><TD>When this flag is set, <I>folderName</I> is a string pointer to the folder to search.</TD>
</TR>
<TR>
<TD>FO_RECURSE</TD><TD>When this flag is set, FFindFirst searches all folders (<I>folderName</I> is ignored).</TD>
</TR>
</TABLE>
<BR><BR>
FFindFirst returns a <A HREF="$$LINK(vat.h/SYM_ENTRY)">SYM_ENTRY</A> pointer to the first file with a type matching <I>typeName</I> or <A HREF="$$LINK(alloc.h/NULL)">NULL</A> if none found.
The Name field of the <A HREF="$$LINK(vat.h/SYM_ENTRY)">SYM_ENTRY</A> contains the name of the file being searched for as an 8 character string. If using <A HREF="$$LINK(vat.h/FindOptions)">FO_RECURSE</A>, then
calling <A HREF="$$LINK(vat.h/SymFindFolderName)">SymFindFolderName</A> will return the folder of the symbol just found.
<BR><BR>
<B>Note:</B> <A HREF="$$LINK(vat.h/SYM_ENTRY)">SYM_ENTRY</A> pointers are only valid until heap compression is done or
another symbol is added to the symbol table.

[References]
Out=TIOS_FFindNext: FFindNext, estack.h/HToESI, string.h/strcmp, string.h/strlen, unknown.h/_ROM_CALL_3E8, vat.h/StrToTokN, vat.h/SymFindFirst
