en:docs:fapi:dosfindfirst2

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

en:docs:fapi:dosfindfirst2 [2021/08/20 05:58] – created prokusheven:docs:fapi:dosfindfirst2 [2021/09/18 08:55] (current) – prokushev
Line 1: Line 1:
 {{page>en:templates:fapiint}} {{page>en:templates:fapiint}}
  
 +====== DosFindFirst2 ======
 + 
 This call finds the first file object or group of file objects whose name(s) match the specification. The specification can include extended attribute information associated with a file or subdirectory. This call finds the first file object or group of file objects whose name(s) match the specification. The specification can include extended attribute information associated with a file or subdirectory.
  
-==Syntax==+===== Syntax ===== 
 +<code c>
  DosFindFirst2 (FileName, DirHandle, Attribute, ResultBuf,  DosFindFirst2 (FileName, DirHandle, Attribute, ResultBuf,
                 ResultBufLen, SearchCount, FileInfoLevel, Reserved)                 ResultBufLen, SearchCount, FileInfoLevel, Reserved)
-==Parameters== +</code> 
-;FileName (PSZ) - input : Address of the ASCIIZ path name of the file or subdirectory to be found. The name component may contain global file name characters. +===== Parameters ===== 
-;DirHandle (PHDIR) - input/output : Address of the handle associated with a specific DosFindFirst2 request. The values that can be specified are: + 
-::0001H - The system assigns the handle for standard output, which is always available to a process. +  * FileName (PSZ) - input : Address of the ASCIIZ path name of the file or subdirectory to be found. The name component may contain global file name characters. 
-::FFFFH - The system allocates and returns a handle. If on input FFFFH is specified, on output DirHandle contains the handle allocated by the system. +  * DirHandle (PHDIR) - input/output : Address of the handle associated with a specific DosFindFirst2 request. The values that can be specified are: 
-:The DosFindFirst2 handle is used with subsequent [[DosFindNext]] requests. Reuse of this handle in another DosFindFirst2 closes the association with the previous DosFindFirst2 and opens a new association. +    * 0001H - The system assigns the handle for standard output, which is always available to a process. 
-;Attribute (USHORT) - input: Attribute value that determines the file objects to be searched for. +    * FFFFH - The system allocates and returns a handle. If on input FFFFH is specified, on output DirHandle contains the handle allocated by the system. 
-::15-6 - Reserved and must be zero. + 
-::5 - File archive +The DosFindFirst2 handle is used with subsequent [[DosFindNext]] requests. Reuse of this handle in another DosFindFirst2 closes the association with the previous DosFindFirst2 and opens a new association. 
-::4 - Subdirectory + 
-::3 - Reserved and must be zero. +  * Attribute (USHORT) - input: Attribute value that determines the file objects to be searched for. 
-::2 - System file + 
-::1 - Hidden file +| 15-6 | Reserved and must be zero | 
-::0 - Read only file +| 5 | File archive | 
-:These bits may be set individually or in combination. For example, an attribute value of 0021H (bits 5 and 0 set to 1) indicates a read-only file that should be archived. +| 4 | Subdirectory | 
-:To look at all directory entries except the volume label, set Attribute to hidden+system+directory (all three bits on). Attribute cannot specify the volume label. Volume labels are queried using [[DosQFSInfo]]. +| 3 | Reserved and must be zero | 
-:If Attribute is 0, only normal file entries are found. Entries for subdirectories, hidden, and system files, are not returned. +| 2 | System file | 
-;ResultBuf (PVOID) - input/output: Address of the directory search structures for file object information levels 1 through 3. The structure required for ResultBuf is dependent on the value specified for FileInfoLevel. The information returned reflects the last DosSetFileInfo, DosSetPathInfo, DosClose, and DosBufReset calls. +| 1 | Hidden file | 
-:'''Level 1 Information''' +| 0 | Read only file | 
-:ResultBuf contains the following structure, to which directory entry information is returned: + 
-:filedate (FDATE) : Structure containing the date of file creation. +These bits may be set individually or in combination. For example, an attribute value of 0021H (bits 5 and 0 set to 1) indicates a read-only file that should be archived. 
-::15-9 - Year, in binary, of file creation + 
-::8-5 - Month, in binary, of file creation +To look at all directory entries except the volume label, set Attribute to hidden+system+directory (all three bits on). Attribute cannot specify the volume label. Volume labels are queried using [[DosQFSInfo]]. 
-::4-0 - Day, in binary, of file creation. + 
-:filetime (FTIME) :  Structure containing the time of file creation. +If Attribute is 0, only normal file entries are found. Entries for subdirectories, hidden, and system files, are not returned. 
-::15-11 - Hours, in binary, of file creation + 
-::10-5 - Minutes, in binary, of file creation +  * ResultBuf (PVOID) - input/output: Address of the directory search structures for file object information levels 1 through 3. The structure required for ResultBuf is dependent on the value specified for FileInfoLevel. The information returned reflects the last DosSetFileInfo, DosSetPathInfo, DosClose, and DosBufReset calls. 
-::4-0 - Seconds, in binary number of two-second increments, of file creation. + 
-:fileaccessdate (FDATE) : Structure containing the date of last access. See FDATE in filedate. +==== Level 1 Information ==== 
-:fileaccesstime (FTIME) : Structure containing the time of last access. See FTIME in filetime. + 
-:writeaccessdate (FDATE) : Structure containing the date of last write. See FDATE in filedate. +ResultBuf contains the following structure, to which directory entry information is returned: 
-:writeaccesstime (FTIME) : Structure containing the time of last write. See FTIME in filetime. + 
-:filesize (ULONG) : File size. +  * filedate (FDATE) : Structure containing the date of file creation. 
-:filealloc (ULONG) : Allocated file size. + 
-:fileattrib (USHORT) :  Attributes of the file, defined in [[DosSetFileMode]]. +| 15-9 | Year, in binary, of file creation | 
-:length (UCHAR) : Length of the ASCIIZ name string. +| 8-5 | Month, in binary, of file creation | 
-:matchfilename (CHAR) : ASCIIZ name string for the first occurrence of FileName. +| 4-0 | Day, in binary, of file creation | 
-:'''Level 2 Information''' + 
-:ResultBuf contains a structure similar to the Level 1 structure, with the addition of the cbList field inserted before the name length field of the matched file object. +  * filetime (FTIME) :  Structure containing the time of file creation. 
-:cbList (ULONG) : On output, this field contains the length of the entire EA set for the file object. This value can be used to calculate the size of the buffer required to hold EA information returned when FileInfoLevel = 3 is specified. + 
-:'''Level 3 Information''' +| 15-11 | Hours, in binary, of file creation | 
-:ResultBuf contains an EAOP structure, which has the following format: +| 10-5 | Minutes, in binary, of file creation | 
-::fpGEAList (PGEALIST): Address of GEAList. GEAList is a packed array of variable length "get EA" structures, each containing an EA name and the length of the name.  +| 4-0 | Seconds, in binary number of two-second increments, of file creation | 
-*fpFEAList (PFEALIST): Address of FEAList. FEAList is a packed array of variable length "full EA" structures, each containing an EA name and its corresponding value, as well as the lengths of the name and the value. + 
-::oError (ULONG): Offset into structure where error has occurred. +  * fileaccessdate (FDATE) : Structure containing the date of last access. See FDATE in filedate. 
-:On input, fpGEAList contains the address of a GEA list, which defines the attribute names whose values are to be returned. fpGEAList is ignored. In case of error, oError contains the offset of the offending GEA entry. Following is the format of the GEAList structure:  +  * fileaccesstime (FTIME) : Structure containing the time of last access. See FTIME in filetime. 
-::cbList (ULONG): Length of the GEA list, including the length itself. list (GEA) +  * writeaccessdate (FDATE) : Structure containing the date of last write. See FDATE in filedate. 
-:'''List of GEA structures.''' +  * writeaccesstime (FTIME) : Structure containing the time of last write. See FTIME in filetime. 
-:A GEA structure has the following format: +  * filesize (ULONG) : File size. 
-:* cbName (BYTE) : Length of EA ASCIIZ name, which does not include the null character.  +  * filealloc (ULONG) : Allocated file size. 
-:* szName (CHAR) : ASCIIZ name of EA. +  * fileattrib (USHORT) :  Attributes of the file, defined in [[DosSetFileMode]]. 
-:Following the EAOP structure is a structure similar to the Level 1 structure, with the addition of an FEAList structure inserted before the name length field for the matched file object. +  * length (UCHAR) : Length of the ASCIIZ name string. 
-::n output, this structure contains a packed set of records representing the directory entry and associated EAs for the matched file object. Following is the format of the FEAList structure: +  * matchfilename (CHAR) : ASCIIZ name string for the first occurrence of FileName. 
-::cbList (ULONG): Length of the FEA list, including the length itself. + 
-:'''list (FEA)''' +==== Level 2 Information ==== 
-:List of FEA structures.  + 
-:An FEA structure has the following format:+ResultBuf contains a structure similar to the Level 1 structure, with the addition of the cbList field inserted before the name length field of the matched file object. 
 + 
 +  * cbList (ULONG) : On output, this field contains the length of the entire EA set for the file object. This value can be used to calculate the size of the buffer required to hold EA information returned when FileInfoLevel = 3 is specified. 
 + 
 +==== Level 3 Information ==== 
 + 
 +ResultBuf contains an EAOP structure, which has the following format: 
 + 
 +  * fpGEAList (PGEALIST): Address of GEAList. GEAList is a packed array of variable length "get EA" structures, each containing an EA name and the length of the name.  
 +  * fpFEAList (PFEALIST): Address of FEAList. FEAList is a packed array of variable length "full EA" structures, each containing an EA name and its corresponding value, as well as the lengths of the name and the value. 
 +  * oError (ULONG): Offset into structure where error has occurred. 
 + 
 +On input, fpGEAList contains the address of a GEA list, which defines the attribute names whose values are to be returned. fpGEAList is ignored. In case of error, oError contains the offset of the offending GEA entry. Following is the format of the GEAList structure:  
 + 
 +  * cbList (ULONG): Length of the GEA list, including the length itself. list (GEA) 
 + 
 +==== List of GEA structures ==== 
 + 
 +A GEA structure has the following format: 
 + 
 +  * cbName (BYTE) : Length of EA ASCIIZ name, which does not include the null character.  
 +  * szName (CHAR) : ASCIIZ name of EA. 
 + 
 +Following the EAOP structure is a structure similar to the Level 1 structure, with the addition of an FEAList structure inserted before the name length field for the matched file object. 
 + 
 +  * n output, this structure contains a packed set of records representing the directory entry and associated EAs for the matched file object. Following is the format of the FEAList structure: 
 + 
 +  * cbList (ULONG): Length of the FEA list, including the length itself. 
 +  * list (FEA) 
 + 
 +==== List of FEA structures ==== 
 +  
 +An FEA structure has the following format: 
 + 
 +  * Flags (BYTE) : Bit indicator describing the characteristics of the EA being defined. 
 +    * 7     Critical EA. 
 +    * 6-0   Reserved and must be set to zero.
  
-Flags (BYTE) : Bit indicator describing the characteristics of the EA being defined. 
-::7     Critical EA. 
-::6-0   Reserved and must be set to zero. 
 If bit 7 is set to 1, this indicates a critical EA. If bit 7 is 0, this means the EA is noncritical; that is, the EA is not essential to the intended use by an application of the file with which it is associated.  If bit 7 is set to 1, this indicates a critical EA. If bit 7 is 0, this means the EA is noncritical; that is, the EA is not essential to the intended use by an application of the file with which it is associated. 
-;cbName (BYTE) : Length of EA ASCIIZ name, which does not include the null character.  + 
-;cbValue (USHORT) : Length of EA value, which cannot exceed 64KB.  +  * cbName (BYTE) : Length of EA ASCIIZ name, which does not include the null character.  
-;szName (PSZ) : ASCIIZ name of EA.  +  * cbValue (USHORT) : Length of EA value, which cannot exceed 64KB.  
-;aValue (PSZ) : Free-format value of EA.  +  * szName (PSZ) : ASCIIZ name of EA.  
-:Note: The szName and aValue fields are not included as part of header or include files. Because of their variable lengths, these entries must be built manually. +  * aValue (PSZ) : Free-format value of EA.  
-;ResultBufLen (USHORT) - input: Length of ResultBuf. SearchCount (PUSHORT) - input/output+ 
 +Note: The szName and aValue fields are not included as part of header or include files. Because of their variable lengths, these entries must be built manually. 
 + 
 +  * ResultBufLen (USHORT) - input: Length of ResultBuf. SearchCount (PUSHORT) - input/output 
 :Address of the number of matching entries requested in ResultBuf. On return, this field contains the number of entries placed into ResultBuf. :Address of the number of matching entries requested in ResultBuf. On return, this field contains the number of entries placed into ResultBuf.
-;FileInfoLevel (USHORT): The level of file information required. A value of 1, 2, or 3 can be specified. The structures described in ResultBuf indicate the information returned for each of these levels. 
-:Regardless of the level specified, a DosFindFirst2 request (and an associated DosFindNext request) always includes the information returned by level 1 as part of the information that is returned. However, when level 1 information is specifically requested, an inclusive search is made. That is, all normal file entries plus all entries matching any specified attributes are returned. 
-;Reserved (ULONG) - input : Reserved, must be set to zero. 
  
-==Return Code== +  * FileInfoLevel (USHORT): The level of file information required. A value of 1, 2, or 3 can be specified. The structures described in ResultBuf indicate the information returned for each of these levels. 
-;rc (USHORT) - return:Return code descriptions are: + 
-*0 NO_ERROR +Regardless of the level specified, a DosFindFirst2 request (and an associated DosFindNext request) always includes the information returned by level 1 as part of the information that is returned. However, when level 1 information is specifically requested, an inclusive search is made. That is, all normal file entries plus all entries matching any specified attributes are returned. 
-*2 ERROR_FILE_NOT_FOUND + 
-*3 ERROR_PATH_NOT_FOUND +  * Reserved (ULONG) - input : Reserved, must be set to zero. 
-*6 ERROR_INVALID_HANDLE + 
-*18 ERROR_NO_MORE_FILES +===== Return Code ===== 
-*26 ERROR_NOT_DOS_DISK + 
-*87 ERROR_INVALID_PARAMETER +rc (USHORT) - return:Return code descriptions are: 
-*108 ERROR_DRIVE_LOCKED + 
-*111 ERROR_BUFFER_OVERFLOW +  *0 NO_ERROR 
-*113 ERROR_NO_MORE_SEARCH_HANDLES +  *2 ERROR_FILE_NOT_FOUND 
-*206 ERROR_FILENAME_EXCED_RANGE +  *3 ERROR_PATH_NOT_FOUND 
-*208 ERROR_META_EXPANSION_TOO_LONG +  *6 ERROR_INVALID_HANDLE 
-*254 ERROR_INVALID_EA_NAME +  *18 ERROR_NO_MORE_FILES 
-*255 ERROR_EA_LIST_ INCONSISTENT +  *26 ERROR_NOT_DOS_DISK 
-*275 ERROR_EAS_DIDNT_FIT+  *87 ERROR_INVALID_PARAMETER 
 +  *108 ERROR_DRIVE_LOCKED 
 +  *111 ERROR_BUFFER_OVERFLOW 
 +  *113 ERROR_NO_MORE_SEARCH_HANDLES 
 +  *206 ERROR_FILENAME_EXCED_RANGE 
 +  *208 ERROR_META_EXPANSION_TOO_LONG 
 +  *254 ERROR_INVALID_EA_NAME 
 +  *255 ERROR_EA_LIST_ INCONSISTENT 
 +  *275 ERROR_EAS_DIDNT_FIT 
 + 
 +===== Remarks =====
  
-==Remarks== 
 DosFindFirst2 returns directory entries (up to the number requested in SearchCount) and extended attribute information for as many files or subdirectories whose names, attributes, and extended attributes match the specification, and whose information fits in ResultBuf. On output, SearchCount contains the actual number of directory entries returned. DosFindFirst2 returns directory entries (up to the number requested in SearchCount) and extended attribute information for as many files or subdirectories whose names, attributes, and extended attributes match the specification, and whose information fits in ResultBuf. On output, SearchCount contains the actual number of directory entries returned.
  
Line 110: Line 156:
 In the case of ERROR_EAS_DIDNT_FIT, only information for the first matching entry is returned. This entry is the one whose EAs did not fit in the buffer. The information returned is in the format of that returned for InfoLevel 2. No further entries are returned in the buffer even if they could fit in the remaining space. In the case of ERROR_EAS_DIDNT_FIT, only information for the first matching entry is returned. This entry is the one whose EAs did not fit in the buffer. The information returned is in the format of that returned for InfoLevel 2. No further entries are returned in the buffer even if they could fit in the remaining space.
  
-===Family API Considerations===+==== Family API Considerations ==== 
 Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restrictions apply to DosFindFirst when coding for the DOS mode: Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restrictions apply to DosFindFirst when coding for the DOS mode:
  
 DirHandle must always equal hex 0001H or FFFFH on the initial call to DosFindFirst. Subsequent calls to DosFindFirst must have a DirHandle of hex 0001H unless a DosFindClose had been issued. In this case, 0001H or FFFFH is allowed. DirHandle must always equal hex 0001H or FFFFH on the initial call to DosFindFirst. Subsequent calls to DosFindFirst must have a DirHandle of hex 0001H unless a DosFindClose had been issued. In this case, 0001H or FFFFH is allowed.
  
-==Bindings== +===== Bindings ===== 
-===C=== + 
-<PRE>+==== C ==== 
 + 
 +<code c>
 typedef struct _FDATE {   /* fdate */ typedef struct _FDATE {   /* fdate */
   unsigned day   : 5;     /* binary day for directory entry */   unsigned day   : 5;     /* binary day for directory entry */
Line 201: Line 250:
  
 USHORT           rc;            /* return code */ USHORT           rc;            /* return code */
-</PRE>+</code> 
 + 
 +==== MASM ====
  
-===MASM=== +<code asm>
-<PRE>+
 FDATE   struc FDATE   struc
   fdate_fs  dw  ?   fdate_fs  dw  ?
Line 283: Line 333:
  
 Returns WORD Returns WORD
-</PRE>+</code>
  
 {{page>en:templates:fapi}} {{page>en:templates:fapi}}