DosQueryFileInfo

Gets file information.

Syntax

DosQueryFileInfo(hf, ulInfoLevel, pInfo, cbInfoBuf)

Parameters

hf (HFILE) - input

The file handle.

ulInfoLevel (ULONG) - input

Level of file information required.

A value of 1, 2, or 3 can be specified, as follows:

1 FIL_STANDARD Level 1 file information

2 FIL_QUERYEASIZE Level 2 file information

3 FIL_QUERYEASFROMLIST Level 3 file information

Level 4 is reserved.

The structures described in pInfo indicate the information returned for each of these levels.

pInfo (PVOID) - output

Address of the storage area where the system returns the requested level of file information.

File information, where applicable, is at least as accurate as the most recent DosClose, DosResetBuffer, DosSetFileInfo, or DosSetPathInfo.

• Level 1 File Information (ulInfoLevel == FIL_STANDARD) pInfo contains the FILESTATUS3 data structure, in which file information is returned.
• Level 2 File Information (ulInfoLevel == FIL_QUERYEASIZE) pInfo contains the FILESTATUS4 data structure. This is similar to the Level 1 structure, with the addition of the cbList field after the attrFile field.

The cbList field is an unsigned 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.

• Level 3 File Information (ulInfoLevel == FIL_QUERYEASFROMLIST)

Input: pInfo contains an EAOP2 data structure. fpGEA2List points to a GEA2 list defining the attribute names whose values are returned. The GEA2 data structures must be aligned on a doubleword boundary. Each oNextEntryOffset field must contain the number of bytes from the beginning of the current entry to the beginning of the next entry in the GEA2 list. The oNextEntryOffset field in the last entry of the GEA2 list must be 0. fpFEA2List points to a data area where the relevant FEA2 list is returned. The length field of this FEA2 list is valid, giving the size of the FEA2 list buffer. oError is ignored.

Output: pInfo is unchanged. The buffer pointed to by fpFEA2List is filled with the returned information. If the buffer that fpFEA2List points to is not large enough to hold the returned information (the return code is ERROR_BUFFER_OVERFLOW), cbList is still valid, assuming there is at least enough space for it. Its value is the size of the entire EA set on disk for the file, even though only a subset of attributes was requested.

cbInfoBuf (ULONG) - input

The length, in bytes, of pInfo.

Return Code

ulrc (APIRET) - returns

DosQueryFileInfo returns one of the following values:

• 0 NO_ERROR
• 5 ERROR_ACCESS_DENIED
• 6 ERROR_INVALID_HANDLE
• 111 ERROR_BUFFER_OVERFLOW
• 124 ERROR_INVALID_LEVEL
• 130 ERROR_DIRECT_ACCESS_HANDLE
• 254 ERROR_INVALID_EA_NAME
• 255 ERROR_EA_LIST_INCONSISTENT

Remarks

In the FAT file system, only date and time information contained in Level 1 file information can be modified. Zero is returned for the creation and access dates and times.

To return information contained in any of the file information levels, DosQueryFileInfo must be able to read the open file. DosQueryFileInfo works only when the file is opened for read access, with a deny-write sharing mode specified for access by other processes. If another process that has specified conflicting sharing and access modes has already opened the file, any call to DosOpen will fail.

DosEnumAttribute returns the lengths of EAs. This information can be used to calculate what size pInfo needs to be to hold full-extended-attribute (FEA) information returned by DosQueryFileInfo when Level 3 is specified. The size of the buffer is calculated as follows:

Four bytes (for oNextEntryOffset) +
One byte (for fEA +
One byte (for cbName) +
Two bytes (for cbValue) +
Value of cbName (for the name of the EA) +
One byte (for terminating NULL in cbName) +
Value of cbValue (for the value of the EA)

Example Code

This example obtains the information of the CONFIG.SYS file.

 #define INCL_DOSFILEMGR   /* File Manager values */
 #define INCL_DOSERRORS    /* DOS error values    */
 #include <os2.h>
 #include <stdio.h>

 int main(VOID) {
 UCHAR        uchFileName[80] = "C:\\CONFIG.SYS";  /* File to manipulate    */
 FILESTATUS3  fsts3ConfigInfo = {{0}};       /* Buffer for file information */
 ULONG        ulBufSize     = sizeof(FILESTATUS3);  /* Size of above buffer */
 HFILE        hfConfig      = 0;             /* Handle for Config file      */
 ULONG        ulOpenAction  = 0;             /* Action taken by DosOpen     */
 APIRET       rc            = NO_ERROR;      /* Return code                 */

  rc = DosOpen(uchFileName,                 /* File to open (path and name) */
               &hfConfig,                /* File handle returned         */
               &ulOpenAction,               /* Action taken by DosOpen      */
               0L,0L,        /* Primary allocation and attributes (ignored) */
               OPEN_ACTION_FAIL_IF_NEW |
               OPEN_ACTION_OPEN_IF_EXISTS,  /* Open an existing file only   */
               OPEN_FLAGS_NOINHERIT | OPEN_ACCESS_READONLY |
               OPEN_SHARE_DENYNONE,         /* Read access only             */
               0L);                         /* Extended attributes (ignored)*/

    if (rc != NO_ERROR) {
        printf("DosOpen error: return code = %u\n", rc);
        return 1;
    }

    rc = DosQueryFileInfo(hfConfig,   /* Handle of file                  */
                          FIL_STANDARD,  /* Request standard (Level 1) info */
                          &fsts3ConfigInfo, /* Buffer for file information  */
                          ulBufSize);    /* Size of buffer                  */
    if (rc != NO_ERROR) {
        printf("DosQueryFileInfo error: return code = %u\n", rc);
        return 1;
    }

    rc = DosClose(hfConfig);      /* Close the file  (check RC in real life) */
    printf("%s ---  File size: %u bytes\n",uchFileName, fsts3ConfigInfo.cbFile);
    printf("Last updated: %d/%d/%d; %d:%2.2d\n",
            fsts3ConfigInfo.fdateLastWrite.month,        /* Month            */
            fsts3ConfigInfo.fdateLastWrite.day,          /* Day              */
            (fsts3ConfigInfo.fdateLastWrite.year+1980L), /* Years since 1980 */
            fsts3ConfigInfo.ftimeLastWrite.hours,        /* Hours            */
            fsts3ConfigInfo.ftimeLastWrite.minutes);     /* Minutes          */

  return NO_ERROR;
}

Related Functions

• DosClose
• DosEnumAttribute
• DosOpen
• DosQueryPathInfo
• DosResetBuffer
• DosSetFileInfo
• DosSetFileSize
• DosSetPathInfo