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
    };

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:

    _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.  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.

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.

See Also:
    opendir, readdir, closedir

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

Systems:
     _dos_findclose - DOS, Win, OS/2 1.x(all), OS/2 2.x, NT, DOS/PM

    _dos_findfirst - DOS, Win, OS/2 1.x(all), OS/2 2.x, NT, DOS/PM
    _dos_findnext - DOS, Win, OS/2 1.x(all), OS/2 2.x, NT, DOS/PM