@node _dos_findfirst, dos
@subheading Syntax

@example
#include <dos.h>

unsigned int _dos_findfirst(char *name, unsigned int attr, 
                            struct find_t *result);
@end example

@subheading Description

This function and the related @code{_dos_findnext} (@pxref{_dos_findnext})
are used to scan directories for the list of files therein. The @var{name}
is a wildcard that specifies the directory and files to search. @var{result}
is a structure to hold the results and state of the search, and @var{attr}
is a combination of the following:

@table @code

@item _A_NORMAL (0x00)

Normal file (no read/write restrictions)

@item _A_RDONLY (0x01)

Read only file

@item _A_HIDDEN (0x02)

Hidden file

@item _A_SYSTEM (0x04)

System file

@item _A_VOLID (0x08)

Volume ID file

@item _A_SUBDIR (0x10)

Subdirectory

@item _A_ARCH (0x20)

Archive file

@end table

The results are returned in a @code{struct find_t} defined on
@code{<dos.h>} as follows:

@example
struct find_t @{
  char reserved[21];
  unsigned char attrib;
  unsigned short wr_time;
  unsigned short wr_date;
  unsigned long size;
  char name[256];
@};
@end example

@xref{_dos_findnext}.

This function does not support long filenames, even on systems where the
LFN API (@pxref{_use_lfn, LFN}) is available.  For LFN-aware functions
with similar functionality see @ref{findfirst}, and @ref{findnext}.
Also see @ref{opendir}, and @ref{readdir}, which are Posix-standard.

@subheading Return Value

Zero if a match is found, DOS error code if not found (and sets @var{errno}).

@subheading Portability

@portability !ansi, !posix

@subheading Example

@example
#include <dos.h>

struct find_t f;

if ( !_dos_findfirst("*.DAT", &f, _A_ARCH | _A_RDONLY) )
@{
  do
  @{
    printf("%-14s %10u %02u:%02u:%02u %02u/%02u/%04u\n",
           f.name,
           f.size,
           (f.wr_time >> 11) & 0x1f,
           (f.wr_time >>  5) & 0x3f,
           (f.wr_time & 0x1f) * 2,
           (f.wr_date >>  5) & 0x0f,
           (f.wr_date & 0x1f),
           ((f.wr_date >> 9) & 0x7f) + 1980);
  @} while( !_dos_findnext(&f) );
@}
@end example