en:docs:fapi:dosfindfirst

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
en:docs:fapi:dosfindfirst [2021/08/20 05:53] – prokusheven:docs:fapi:dosfindfirst [2021/09/18 04:52] (current) – prokushev
Line 5: Line 5:
 This call finds the first file object or group of file objects whose name(s) match the specification. This call finds the first file object or group of file objects whose name(s) match the specification.
  
-==Syntax==+===== Syntax ===== 
 +<code c>
  DosFindFirst (FileName, DirHandle, Attribute,  DosFindFirst (FileName, DirHandle, Attribute,
                ResultBuf, ResultBufLen, SearchCount, Reserved)                ResultBuf, ResultBufLen, SearchCount, Reserved)
 +</code>
 +===== Parameters =====
 +
 +  * 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. 
 +  * DirHandle ([[PHDIR]]) - input/output : Address of the handle associated with a specific DosFindFirst request. The values that can be specified are:
 +    * 0001H - Assign handle 1, which is always available to a process. 
 +    * FFFFH - The system allocates and returns a handle. If on input FFFFH is specified, on output DirHandle contains the handle allocated by the system.
 +
 +The DosFindFirst handle is used with subsequent DosFindNext requests. Reuse of this handle in another DosFindFirst closes the association with the previous DosFindFirst and opens a new association.
 +
 +* Attribute ([[USHORT]]) - input : Attribute value that determines the file objects to be searched for.
 +
 +^ Bit ^ Description ^
 +| 15-6 | Reserved and must be zero |
 +| 5 | File archive |
 +| 4 | Subdirectory |
 +| 3 | Reserved and must be zero |
 +| 2 | System file |
 +| 1 | Hidden file |
 +| 0 | Read only file |
  
-==Parameters== 
-;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.  
-;DirHandle (PHDIR) - input/output : Address of the handle associated with a specific DosFindFirst request. The values that can be specified are: 
-:0001H - Assign handle 1, which is always available to a process.  
-:FFFFH - The system allocates and returns a handle. If on input FFFFH is specified, on output :DirHandle contains the handle allocated by the system. 
-:The DosFindFirst handle is used with subsequent DosFindNext requests. Reuse of this handle in another DosFindFirst closes the association with the previous DosFindFirst and opens a new association. 
-;Attribute (USHORT) - input : Attribute value that determines the file objects to be searched for. 
- '''Bit  Description'''  
- 15-6   Reserved and must be zero. 
- 5      File archive 
- 4      Subdirectory 
- 3      Reserved and must be zero. 
- 2      System file 
- 1      Hidden file 
- 0      Read only file 
 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.  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. 
                          
Line 30: Line 36:
 Attribute cannot specify the volume label. Volume labels are queried using DosQFSInfo. Attributes of a file are queried and set with DosQFileMode and DosSetFileMode.  Attribute cannot specify the volume label. Volume labels are queried using DosQFSInfo. Attributes of a file are queried and set with DosQFileMode and DosSetFileMode. 
  
-; ResultBuf (PFILEFINDBUF) - output : Address of the structure that contains the returned directory information. The information reflects the last DosClose, DosBufReset, DosSetFileMode, DosSetFileInfo, and DosSetPathInfo calls.+  * ResultBuf ([[PFILEFINDBUF]]) - output : Address of the structure that contains the returned directory information. The information reflects the last DosClose, DosBufReset, DosSetFileMode, DosSetFileInfo, and DosSetPathInfo calls.
  
-* filedate (FDATE) : Structure containing the date of file creation.+  * filedate ([[FDATE]]) : Structure containing the date of file creation.
  
- '''Bit                    Description'''  +^ Bit ^ Description ^ 
- 15-9                   Year, in binary, of file creation +| 15-9 | Year, in binary, of file creation | 
- 8-5                    Month, in binary, of file creation +| 8-5 | Month, in binary, of file creation | 
- 4-0                    Day, in binary, of file creation. +| 4-0 | Day, in binary, of file creation |
  
-* filetime (FTIME) : Structure containing the time of file creation.+  * filetime ([[FTIME]]) : Structure containing the time of file creation.
  
-  '''Bit                        Description''' +^ Bit ^ Description ^ 
- 15-11                     Hours, in binary, of file creation +| 15-11 | Hours, in binary, of file creation | 
- 10-5                      Minutes, in binary, of file creation  +| 10-5 | Minutes, in binary, of file creation | 
- 4-0                       Seconds, in binary number of two-second increments, of file creation. +| 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. +  * fileaccessdate ([[FDATE]]) : Structure containing the date of last access. See FDATE in filedate. 
  
-* fileaccesstime (FTIME) : Structure containing the time of last access. See FTIME in filetime. +  * 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. +  * writeaccessdate ([[FDATE]]) : Structure containing the date of last write. See FDATE in filedate. 
  
-* writeaccesstime (FTIME) : Structure containing the time of last write. See FTIME in filetime. +  * writeaccesstime ([[FTIME]]) : Structure containing the time of last write. See FTIME in filetime. 
  
-* filesize (ULONG): File size. +  * filesize ([[ULONG]]): File size. 
  
-* filealloc (ULONG) : Allocated file size. +  * filealloc ([[ULONG]]) : Allocated file size. 
  
-* fileattrib (USHORT) : Attributes of the file, defined in DosSetFileMode. +  * fileattrib ([[USHORT]]) : Attributes of the file, defined in DosSetFileMode. 
  
-* length (UCHAR) : Length of the ASCIIZ name string.+  * length ([[UCHAR]]) : Length of the ASCIIZ name string.
  
-* matchfilename (CHAR) : ASCIIZ name string for the first occurrence of FileName. +  * matchfilename ([[CHAR]]) : ASCIIZ name string for the first occurrence of FileName. 
  
-; ResultBufLen (USHORT) - input : Length of ResultBuf +  * 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. +  * 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. 
  
-; Reserved (ULONG) - input : Reserved, must be set to zero. +  * Reserved ([[ULONG]]) - input : Reserved, must be set to zero.  
 + 
 +===== Return Code ===== 
 + 
 +rc ([[USHORT]]) - return
  
-==Return Code== 
- rc (USHORT) - return 
 Return code descriptions are: Return code descriptions are:
-* 0        NO_ERROR + 
-* 2        ERROR_FILE_NOT_FOUND  +  * 0        NO_ERROR 
-* 3        ERROR_PATH_NOT_FOUND  +  * 2        ERROR_FILE_NOT_FOUND  
-* 6        ERROR_INVALID_HANDLE  +  * 3        ERROR_PATH_NOT_FOUND  
-* 18       ERROR_NO_MORE_FILES  +  * 6        ERROR_INVALID_HANDLE  
-* 26       ERROR_NOT_DOS_DISK  +  * 18       ERROR_NO_MORE_FILES  
-* 87       ERROR_INVALID_PARAMETER  +  * 26       ERROR_NOT_DOS_DISK  
-* 108      ERROR_DRIVE_LOCKED  +  * 87       ERROR_INVALID_PARAMETER  
-* 111      ERROR_BUFFER_OVERFLOW  +  * 108      ERROR_DRIVE_LOCKED  
-* 113      ERROR_NO_MORE_SEARCH_HANDLES  +  * 111      ERROR_BUFFER_OVERFLOW  
-* 206      ERROR_FILENAME_EXCED_RANGE +  * 113      ERROR_NO_MORE_SEARCH_HANDLES  
-==Remarks==+  * 206      ERROR_FILENAME_EXCED_RANGE 
 + 
 +===== Remarks ===== 
 DosFindFirst returns directory entries (up to the number requested in SearchCount) for as many files or subdirectories whose names and attributes match the specification and whose information fits in ResultBuf. On output, SearchCount contains the actual number of directory entries returned. DosFindFirst returns directory entries (up to the number requested in SearchCount) for as many files or subdirectories whose names and attributes match the specification and whose information fits in ResultBuf. On output, SearchCount contains the actual number of directory entries returned.
  
Line 95: Line 106:
 For programs running without the NEWFILES bit set, only 8.3 filename format names are returned. These names are changed to uppercase. For programs running without the NEWFILES bit set, only 8.3 filename format names are returned. These names are changed to uppercase.
  
-===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. 
  
-==Example Code== +===== Example Code ===== 
-===C Binding=== + 
-<PRE>+==== C Binding ==== 
 + 
 +<code c>
 typedef struct _FDATE {   /* fdate */ typedef struct _FDATE {   /* fdate */
    
Line 150: Line 164:
 USHORT           rc;            /* return code */ USHORT           rc;            /* return code */
  
-</PRE>+</code>
  
 This example searches for a file matching the pattern 'te??.dat.'  This example searches for a file matching the pattern 'te??.dat.' 
-<PRE>+<code c>
 #define INCL_DOSFILEMGR #define INCL_DOSFILEMGR
  
Line 177: Line 191:
                      &FindCount,             /* # of entries to find */                      &FindCount,             /* # of entries to find */
                      RESERVED);             /* Reserved (must be zero) */                      RESERVED);             /* Reserved (must be zero) */
-</PRE> +</code> 
-===MASM Binding=== +==== MASM Binding ==== 
-<PRE>+ 
 +<code asm>
 FDATE   struc FDATE   struc
    
Line 220: Line 235:
 CALL   DosFindFirst CALL   DosFindFirst
  
 +</code>
 Returns WORD Returns WORD
-</PRE> 
  
  
-====== Note ======+===== Note ===== 
  
 Text based on [[http://www.edm2.com/index.php/DosFindFirst_(FAPI)]] Text based on [[http://www.edm2.com/index.php/DosFindFirst_(FAPI)]]
  
 {{page>en:templates:fapi}} {{page>en:templates:fapi}}