Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <dos.h>
    unsigned _dos_findfirst( char *path,
                             unsigned attributes,
                             struct find_t *buffer );
    unsigned _dos_findnext(  struct find_t *buffer );
    unsigned _dos_findclose( struct find_t *buffer );

    struct find_t {
      char reserved[21];      /* reserved for use by DOS   */
      char attrib;            /* attribute byte for file   */
      unsigned short wr_time; /* time of last write to file*/
      unsigned short wr_date; /* date of last write to file*/
      unsigned long  size;    /* length of file in bytes   */
    #if defined(__OS2__) || defined(__NT__)
      char name[256];         /* null-terminated filename  */
    #else
      char name[13];          /* null-terminated filename  */
    #endif
    };

    unsigned _wdos_findfirst( const wchar_t *path,
                              unsigned attributes,
                              struct _wfind_t *buffer );
    unsigned _wdos_findnext( struct _wfind_t *buffer );
    unsigned _wdos_findclose( struct _wfind_t *buffer );

    struct _wfind_t {
      char reserved[21];      /* reserved for use by DOS    */
      char attrib;            /* attribute byte for file    */
      unsigned short wr_time; /* time of last write to file */
      unsigned short wr_date; /* date of last write to file */
      unsigned long  size;    /* length of file in bytes    */
    #if defined(__OS2__) || defined(__NT__)
      wchar_t name[256];      /* null-terminated filename   */
    #else
      wchar_t name[13];       /* null-terminated filename   */
    #endif
    };

Description:
    The  _dos_findfirst function uses system call 0x4E to return information
    on the first file whose name and attributes match the path and
    attributes arguments.  The information is returned in a  find_t
    structure pointed to by buffer.  The path argument may contain wildcard
    characters ('?' and '*').  The attributes argument may be any
    combination of the following constants:

    Attribute     Meaning

_A_NORMAL
    Indicates a normal file.  File can be read or written without any
    restrictions.

_A_RDONLY
    Indicates a read-only file.  File cannot be opened for "write".

_A_HIDDEN
    Indicates a hidden file.  This file will not show up in a normal
    directory search.

_A_SYSTEM
    Indicates a system file.  This file will not show up in a normal
    directory search.

_A_VOLID
    Indicates a volume-ID.

_A_SUBDIR
    Indicates a sub-directory.

_A_ARCH
    This is the archive flag.  It is set whenever the file is modified, and
    is cleared by the MS-DOS BACKUP command and other backup utility
    programs.

    The attributes argument is interpreted by DOS as follows:

     1. If  _A_NORMAL is specified, then normal files are included in the
        search.

     2. If any of  _A_HIDDEN,  _A_SYSTEM,  _A_SUBDIR are specified, then
        normal files and the specified type of files are included in the
        search.

     3. If  _A_VOLID is specified, then only volume-ID's are included in the
        search.

     4. _A_RDONLY and  _A_ARCH are ignored by this function.

    The  _dos_findnext function uses system call 0x4F to return information
    on the next file whose name and attributes match the pattern supplied to
    the  _dos_findfirst function.

    On some systems (e.g.  Win32, OS/2), you must call  _dos_findclose to
    indicate that you are done matching files.  This function deallocates
    any resources that were allocated by the  _dos_findfirst function.  The
    wide-character  _wdos_findclose,  _wdos_findfirst and  _wdos_findnext
    functions are similar to their counterparts but operate on
    wide-character strings.

Returns:
    The  _dos_find functions return zero if successful.  Otherwise, the
     _dos_findfirst and  _dos_findnext functions return an MS-DOS error code
    and sets  errno to  ENOENT indicating that no more files matched the
    path and attributes arguments.

Example:
    #include <stdio.h>
    #include <dos.h>

    void main()
      {
        struct find_t  fileinfo;
        unsigned rc;        /* return code */

        /* Display name and size of "*.c" files */
        rc = _dos_findfirst( "*.c", _A_NORMAL, &fileinfo );
        while( rc == 0 ) {
          printf( "%14s %10ld\n", fileinfo.name,
                                  fileinfo.size );
          rc = _dos_findnext( &fileinfo );
        }
        #if defined(__OS2__)
        _dos_findclose( &fileinfo );
        #endif
      }

Classification:
    _dos_find is DOS, _wdos_findnext is not DOS

Systems:
     _dos_findclose - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32,
    DOS/PM

    _dos_findfirst - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32,
    DOS/PM
    _dos_findnext - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32,
    DOS/PM
    _wdos_findclose - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
    _wdos_findfirst - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
    _wdos_findnext - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

See Also:
    opendir, readdir, closedir