DosQueryFSAttach
From EDM2
Obtains information about an attached file system (local or remote), or about a character device or pseudocharacter device attached to the file system.
Syntax
ulrc = DosQueryFSAttach(pszDeviceName, ulOrdinal, ulFSAInfoLevel,
pfsqb, pcbBuffLength);
Parameters
- pszDeviceName (PSZ) - input
- A drive designation or the name of a character or pseudocharacter device.
- If it is a drive designation, pszDeviceName is an ASCIIZ string consisting of a drive name followed by a colon. If it is a character or pseudocharacter device name, pszDeviceName is an ASCIIZ string consisting of a file name and the subdirectory, \DEV. pszDeviceName is ignored if level 2 or 3 is specified for ulFSAInfoLevel.
- ulOrdinal (ULONG) - input
- An index into the list of character or pseudocharacter devices, or the set of drives.
- ulOrdinal always starts at 1. The ordinal position of an item in a list has no significance. ulOrdinal is used only to step through the list. The mapping from ulOrdinal to the item is volatile, and may change from one call to DosQueryFSAttach to the next. ulOrdinal is ignored if level 1 is specified for ulFSAInfoLevel.
- ulFSAInfoLevel (ULONG) - input
- Level of information returned in pfsqb.
- Possible levels are described in the following list:
- 1 FSAIL_QUERYNAME: Returns data for the drive or device name specified in pszDeviceName. ulOrdinal is ignored.
- 2 FSAIL_DEVNUMBER: Returns data for the entry in the list of character or pseudocharacter devices selected by ulOrdinal. pszDeviceName is ignored.
- 3 FSAIL_DRVNUMBER: Returns data for the entry in the list of drives selected by ulOrdinal. pszDeviceName is ignored.
- pfsqb (PFSQBUFFER2) - output
- Address of the buffer for returned information.
- Note: The szName is the file-system driver name exported by the file-system driver. This name is not necessarily the same as the file-system driver name in the boot sector.
- For local character devices (iType = 1), cbFSDName = 0, and szName contains only a terminating null byte; cbFSAData = 0.
- For local drives (iType = 3), szName contains the name of the file-system driver attached to the drive at the time of the call. This information changes dynamically. If the drive is attached to the kernel's resident file system, szName contains FAT or an unknown name. Since the resident file system gets attached to any disk that other file-system drivers refuse to mount, it is possible to have a disk that does not contain a recognizable file system, but yet gets attached to the resident file system. In this case, it is possible to detect the difference, and this information would help programs to preserve data on a disk that was not properly recognized.
- pcbBuffLength (PULONG) - in/out
- Address of the length, in bytes, of the data buffer.
- Input - The address of the length, in bytes, of the return buffer (pfsqb).
- Output - The length, in bytes, of the data returned in pfsqb by the file-system driver.
Return Code
- ulrc (APIRET) - returns
- DosQueryFSAttach returns one of the following values:
- 0 NO_ERROR
- 15 ERROR_INVALID_DRIVE
- 111 ERROR_BUFFER_OVERFLOW
- 124 ERROR_INVALID_LEVEL
- 259 ERROR_NO_MORE_ITEMS
Remarks
DosQueryFSAttach returns information about all block devices, and all character and pseudocharacter devices. The subject of the information returned by this call changes frequently. Therefore, the information that this function returns may no longer be valid when you receive it.
The information returned for disks attached to the resident file system of the kernel can be used to determine:
- If the kernel recognized the disk as one attached to its file system, or
- If the kernel attached its file system to the disk because no other file-system drivers were attached to the disk.
This information can be important for a program that needs to know what file system is attached to the drive. A situation could arise where the file-system driver that recognizes a certain disk has not been loaded into the system. There is then a potential for the data on the disk to be destroyed because the wrong file system gets attached to the disk by default.
Example Code
This example returns information about an attached file system.
#define INCL_DOSFILEMGR /* File manager values */
#define INCL_DOSERRORS /* DOS error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
int main(VOID)
{
UCHAR szDeviceName[8] = "C:"; /* Device name or drive letter string */
ULONG ulOrdinal = 0; /* Ordinal of entry in name list */
PBYTE pszFSDName = NULL; /* pointer to FS name */
PBYTE prgFSAData = NULL; /* pointer to FS data */
APIRET rc = NO_ERROR; /* Return code */
/* Return-data buffer should be large enough to hold FSQBUFFER2 */
/* and the maximum data for szName, szFSDName, and rgFSAData */
/* Typically, the data isn't that large. */
BYTE fsqBuffer[sizeof(FSQBUFFER2) + (3 * CCHMAXPATH)] = {0};
ULONG cbBuffer = sizeof(fsqBuffer); /* Buffer length) */
PFSQBUFFER2 pfsqBuffer = (PFSQBUFFER2) fsqBuffer;
rc = DosQueryFSAttach(
szDeviceName, /* Logical drive of attached FS */
ulOrdinal, /* ignored for FSAIL_QUERYNAME */
FSAIL_QUERYNAME, /* Return data for a Drive or Device */
pfsqBuffer, /* returned data */
&cbBuffer); /* returned data length */
/* On successful return, the fsqBuffer structure contains */
/* a set of information describing the specified attached */
/* file system and the DataBufferLen variable contains */
/* the size of information within the structure */
if (rc != NO_ERROR) {
printf("DosQueryFSAttach error: return code = %u\n", rc);
return 1;
} else {
/* The data for the last three fields in the FSQBUFFER2 */
/* structure are stored at the offset of fsqBuffer.szName. */
/* Each data field following fsqBuffer.szName begins */
/* immediately after the previous item. */
pszFSDName = pfsqBuffer->szName + pfsqBuffer->cbName + 1;
prgFSAData = pszFSDName + pfsqBuffer->cbFSDName + 1;
printf("iType = %d\n", pfsqBuffer->iType);
printf("szName = %s\n", pfsqBuffer->szName);
printf("szFSDName = %s\n", pszFSDName);
printf("rgFSAData = %s\n", prgFSAData);
}
return NO_ERROR;
}
