dos12.hlp (Table of Contents; Topic list)
Important Notice
The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.
DosFindNext (1.2)
Function Group  Overview  Changes               Up Next Previous
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosFindNext(hdir, pfindbuf, cbfindbuf, pcSearch)
HDIR hdir;                /* handle of search directory             */
PFILEFINDBUF pfindbuf;    /* pointer to structure for search result */
USHORT cbfindbuf;         /* length of result buffer                */
PUSHORT pcSearch;         /* pointer to variable for file count     */
 
The DosFindNext function searches for the next file or group of files
matching the specified filename and attributes. The function copies the name
and requested information about the file to the specified structure. The
information returned is as accurate as the most recent call to the DosClose
or DosBufReset function.
 
The DosFindNext function is a family API function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hdir       Identifies the search directory and the filename(s) to search
           for. This handle must have been created previously by using the
           DosFindFirst function.
 
pfindbuf   Points to the structure that receives the result of the search.
           This structure will be either a FILEFINDBUF or FILEFINDBUF2
           structure, depending on the information level requested in the
           DosFindFirst or DosFindFirst2 function that preceded this
           function. For specific information on the format of these
           structures, see the DosFindFirst and DosFindFirst2 functions.
 
cbfindbuf  Specifies the length (in bytes) of the structure pointed to by
           the pfindbuf parameter.
 
pcSearch   Points to the variable that specifies the number of matching
           filenames to locate. The function copies the number of filenames
           found to the variable before returning.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_BUFFER_OVERFLOW
     ERROR_INVALID_HANDLE
     ERROR_INVALID_PARAMETER
     ERROR_NO_MORE_FILES
     ERROR_NOT_DOS_DISK
     ERROR_EAS_DIDNT_FIT
 
Comments
 
The pcSearch parameter specifies the number of files to search for. The
number of files whose information is copied is the number of files
requested, the number of files whose information fits in the structure, or
the number of files that exist, whichever is smallest. If you want to obtain
information for more than one file, the pfindbuf parameter must point to a
buffer that consists of consecutive  structures. If the DosFindNext function
fails to find a match or cannot copy all the information about the file to
the structure, it returns an error.
 
Restrictions
 
In real mode, the following restriction applies to the DosFindNext
function:
 
♦  The hdir parameter must be set to HDIR_SYSTEM.
 
Example
 
This example calls the DosFindFirst function to find all files matching
"*.*", and then uses the DosFindNext function to display them one at a
time:
 
FILEFINDBUF findbuf;
HDIR hdir = HDIR_CREATE;
USHORT cSearch = 1;
DosFindFirst("*.*", &hdir, FILE_NORMAL, &findbuf, sizeof(findbuf),
    &cSearch, 0L);
do {
    VioWrtTTY(findbuf.achName, findbuf.cchName, 0);
    VioWrtTTY("\r\n", 2, 0);     /* cursor to next line     */
}
while (DosFindNext(hdir,         /* handle of directory     */
    &findbuf,                    /* address of buffer       */
    sizeof(findbuf),             /* length of buffer        */
    &cSearch)                    /* number of files to find */
    == 0);                       /* while no error occurs   */
 
See Also
 
DosBufReset, DosClose, DosFindClose, DosFindFirst, DosFindFirst2,
FILEFINDBUF