Purpose
DosFindFirst finds the first file object or group of file objects whose names match the specification. The specification can include extended attributes (EA) associated with a file or directory.
Syntax
#define INCL DOSFILEMGR #include os2.h
APIRET DosFindFirst
Parameters
pszFileSpec PSZ) input
The name component can contain global file name characters.
The values that can be specified for the handle are
HDIR_SYSTEM (0x00000001)
The bit values are shown in the following list
Bits
Must-Have Archive bit; excludes files without the archive bit set if bit 13 is set to 1. Files may have the Archive bit set if bit 13 is set to 0.
Must-Have Subdirectory bit; excludes files that are not subdirectories if bit 12 is set to 1. Files may have the Subdirectory bit set if bit 12 is set to 0.
Must-Have System File bit; excludes nonsystem files if bit 10 is set to 1. Files may be system files if bit 10 is set to 0.
Must-Have Hidden File bit; excludes nonhidden files if bit 9 is set to 1. Files may be nonhidden if bit 9 is set to 0.
Must-Have Read-Only File bit; excludes writeable files if bit 8 is set to 1. Files may be read-only if bit 8 is set to 0.
May-Have Archive bit; includes files with the Archive bit set if bit 5 is set to 1. Excludes files with the Archive bit set if bit 5 is set to 0.
May-Have Subdirectory bit; includes files that are subdirectories if bit 4 is set to 1. Excludes files that are subdirectories if bit 4 is set to 0.
May-Have System File bit; includes system files if bit 2 is set to 1. Excludes system files if bit 2 is set to 0.
May-Have Hidden File bit; includes hidden files if bit 1 is set to 1. Excludes hidden files if bit 1 is set to 0.
May-Have Read-Only File bit; includes read only files if bit 0 is set to 1. Excludes read only files if bit 0 is set to 0.
Bits 8 through 13 are Must-Have flags. These allow you to obtain files that definitely have the given attributes. For example, if the Must-Have Subdirectory bit is set to 1, then all returned items are subdirectories.
If a Must-Have bit is set to 1, and the corresponding May-Have bit is set to 0, no items are returned for that attribute.
The attribute FILE_NORMAL (0x00000000) can be used to include files with any of the above bits set.
flAttribute cannot specify the volume label. Volume labels are queried using DosQueryFSInfo.
The result buffer from DosFindFirst should be less than 64 KB.
Address of the directory search structures for file object information Levels 1 through 3 and 13. The structure required for pfindbuf is dependent on the value specified for ulInfoLevel. The information returned reflects the most recent call to DosClose or DosResetBuffer.
Level 1 File Information (ulInfoLevel == FIL_STANDARD)
The oNextEntryOffset field indicates the number of bytes from the beginning of the current structure to the beginning of the next structure. When this field is 0, the last structure has been reached.
The cbList field contains the size, in bytes, of the file s entire EA set on disk. You can use this field to calculate the maximum size of the buffer needed for Level 3 file information. The size of the buffer required to hold the entire EA set is less than or equal to twice the size of the EA set on disk.
The cbList field is a ULONG. On output, this field contains the size, in bytes, of the file s entire extended attribute (EA) set on disk. You can use this value to calculate the size of the buffer required to hold the EA information returned when a value of 3 is specified for ulInfoLevel. The buffer size is less than or equal to twice the size of the file s entire EA set on disk.
On output, pfindbuf contains a structure with a set of records, each aligned on a doubleword boundary. These records represent the directory entry and associated EAs for the matched file object. pfindbuf has the following format
The EAOP2 data structure occurs only once in the pfindbuf buffer. The rest of these records are repeated for the remainder of the file objects found.
When buffer overflow occurs, cbList contains the size on disk of the entire EA set for the file, even if only a subset of its attributes was requested. The size of the buffer required to hold the EA set is less than or equal to twice the size of the EA set on disk. If no error occurs, cbList includes the pad bytes (for doubleword alignment) between FEA2 structures in the list.
If a particular attribute is not attached to the object, pfindbuf has an FEA2 structure containing the name of the attribute, and the length value is 0.
The GEA2 list contained inside pfindbuf during a Level 3 DosFindFirst and DosFindNext call is not read-only ; it is used by the operating system. When the function returns, the list is restored to its original state, but inside the function, the list is manipulated by the operating system. This is of concern to a multithreaded application, where two different threads might use the same GEA2 list as input. If one thread calls DosFindFirst or DosFindNext while another thread is inside DosFindFirst or DosFindNext, the second thread will fail with a return code of ERROR_BAD_FORMAT.
On output, pfindbuf contains a structure with a set of records, each aligned on a doubleword boundary. These records represent the directory entry and associated EAs for the matched file object. pfindbuf has the following format
The EAOP2 data structure occurs only once in the pfindbuf buffer. The rest of these records are repeated for the remainder of the file objects found.
When buffer overflow occurs, cbList contains the size on disk of the entire EA set for the file, even if only a subset of its attributes was requested. The size of the buffer required to hold the EA set is less than or equal to twice the size of the EA set on disk. If no error occurs, cbList includes the pad bytes (for doubleword alignment) between FEA2 structures in the list.
If a particular attribute is not attached to the object, pfindbuf has an FEA2 structure containing the name of the attribute, and the length value is 0.
The GEA2 list contained inside pfindbuf during a Level 13 DosFindFirst and DosFindNext call is not read-only ; it is used by the operating system. When the function returns, the list is restored to its original state, but inside the function, the list is manipulated by the operating system. This is of concern to a multithreaded application, where two different threads might use the same GEA2 list as input. If one thread calls DosFindFirst or DosFindNext while another thread is inside DosFindFirst or DosFindNext, the second thread will fail with a return code of ERROR_BAD_FORMAT.
Input
Possible values are
11
Level 11 file information
Level 2 file information
Level 12 file information
Regardless of the level specified, a DosFindFirst request (and an associated DosFindNext request on a handle returned by DosFindFirst) always includes Level 1 information as part of the information that is returned; however, when Level 1 information is specifically requested, and flAttribute specifies hidden files, system files, or subdirectory files, an inclusive search is made. That is, all normal file entries plus all entries matching any specified attributes are returned. Normal files are files without any mode bits set. They may be read from or written to.
Returns
ulrc APIRET) returns
DosFindFirst returns one of the following values
18
Remarks
The result buffer from DosFindFirst should be less than 64KB.
DosFindFirst returns directory entries (up to the number requested in pcFileNames) and extended-attribute information for as many files or subdirectories whose names, attributes, and EAs match the specification, and whose information fits in pfindbuf. On output, pcFileNames contains the actual number of directory entries returned.
The file name pointed to by pszFileSpec can contain global file-name characters.
DosFindNext uses the directory handle associated with DosFindFirst to continue the search started by the DosFindFirst request.
Any nonzero return code, except ERROR_EAS_DIDNT_FIT, indicates that no handle has been allocated. This includes such non-error return codes as ERROR_NO_MORE_FILES.
For ERROR_EAS_DIDNT_FIT, a search handle is returned, and a subsequent call to DosFindNext gets the next matching entry in the directory. You can use DosQueryPathInfo to retrieve the EAs for the matching entry by using the same EA arguments used for the DosFindFirst call, and the name that was returned by DosFindFirst.
For ERROR_EAS_DIDNT_FIT, only information for the first matching entry is returned. This entry is the one whose extended attributes did not fit in the buffer. The information returned is in the format of that returned for information Level 2. No further entries are returned in the buffer, even if they could fit in the remaining space.
The GEA2 list contained inside pfindbuf during a Level 3 DosFindFirst and DosFindNext call is not read-only , it is used by the operating system. When the function returns, the list is restored to its original state, but inside the function, the list is manipulated by the operating system. This is of concern to a multithreaded application, where two different threads might use the same GEA2 list as input. If one thread calls DosFindFirst or DosFindNext while another thread is inside DosFindFirst or DosFindNext, the second thread will fail with a return code of ERROR_BAD_FORMAT.
Related Functions
Example Code
This example lists all the normal files that are in the directory from where the example is invoked.
#define INCL_DOSFILEMGR /* File Manager values */#define INCL_DOSERRORS /* DOS error values */
#include os2.h
#include stdio.h
int main (VOID)
HDIR hdirFindHandle = HDIR_CREATE;
FILEFINDBUF3L FindBuffer = 0 ; /* Returned from FindFirst/Next */
ULONG ulResultBufLen = sizeof(FILEFINDBUF3L);
ULONG ulFindCount = 1; /* Look for 1 file at a time */
APIRET rc = NO_ERROR; /* Return code */
rc = DosFindFirst( "*.*", /* File pattern - all files */
hdirFindHandle, /* Directory search handle */
FILE_NORMAL, /* Search attribute */
FindBuffer, /* Result buffer */
ulResultBufLen, /* Result buffer length */
ulFindCount, /* Number of entries to find */
FIL_STANDARDL); /* Return Level 11 file info */
if (rc != NO_ERROR)
printf("DosFindFirst error return code = %u\n",rc);
return 1;
else
printf ("%s\n", FindBuffer.achName); /* Print file name */
/* endif */
/* Keep finding the next file until there are no more files */
while (rc != ERROR_NO_MORE_FILES)
ulFindCount = 1; /* Reset find count. */
rc = DosFindNext(hdirFindHandle, /* Directory handle */
FindBuffer, /* Result buffer */
ulResultBufLen, /* Result buffer length */
ulFindCount); /* Number of entries to find */
if (rc != NO_ERROR rc != ERROR_NO_MORE_FILES)
printf("DosFindNext error return code = %u\n",rc);
return 1;
else
printf ("%s\n", FindBuffer.achName); /* Print file name */
/* endwhile */
rc = DosFindClose(hdirFindHandle); /* Close our directory handle */
if (rc != NO_ERROR)
printf("DosFindClose error return code = %u\n",rc);
return 1;
return NO_ERROR;