DosFSCtl
Description
Provides an extended standard interface between an application and a file-system driver (FSD).
Syntax
#define INCL_DOSFILEMGR
#include <os2.h>
PVOID pData; /* Address of the data area. */
ULONG cbData; /* The length, in bytes, of pData. */
PULONG pcbData; /* Pointer to the length of data passed to or returned from the FSD. */
PVOID pParms; /* Address of the command-specific parameter list. */
ULONG cbParms; /* The length, in bytes, of pParms. */
PULONG pcbParms; /* Pointer to the length of the parameters passed to or returned from the FSD. */
ULONG function; /* The function code that is specific to the file-system driver. */
PSZ pszRoute; /* Address of the ASCIIZ name of the FSD, or the path name of a file or directory that the operation applies to. */
HFILE hFile; /* File-specific or device-specific handle. */
ULONG method; /* Method used to routed the request. */
APIRET ulrc; /* Return Code. */
ulrc = DosFSCtl(pData, cbData, pcbData, pParms,
cbParms, pcbParms, function, pszRoute,
hFile, method);
Parameters
- pData (PVOID) - input
- Address of the data area.
- cbData (ULONG) - input
- The length, in bytes, of pData.
This is the maximum length of the data to be returned by the file-system driver in pData. pcbData may be larger than this on input, but not on output.
- pcbData (PULONG) - in/out
- Pointer to the length of data passed to or returned from the FSD.
Input : Pointer to the length, in bytes, of the data passed to the file-system driver in pData
Output: Pointer to the length, in bytes, of the data returned by the file-system driver in pData. If this function returns ERROR_BUFFER_OVERFLOW, pcbData points to the size of the buffer required to hold the data returned by the file-system driver.
- pParms (PVOID) - input
- Address of the command-specific parameter list.
- cbParms (ULONG) - input
- The length, in bytes, of pParms.
This is the maximum length of the data to be returned by the file-system driver in pParms. pcbParms may be larger than this on input, but not on output.
- pcbParms (PULONG) - in/out
- Pointer to the length of the parameters passed to or returned from the FSD.
Input: Pointer to the length, in bytes, of the parameters passed to the file-system driver in pParms.
Output: Pointer to the length, in bytes, of the parameters returned by the file-system driver in pParms. If this function returns ERROR_BUFFER_OVERFLOW, pcbParms. points to the size of the buffer required to hold the parameters returned by the file-system driver. No other data is returned in this case.
- function (ULONG) - input
- The function code that is specific to the file-system driver.
For remote file-system drivers, two kinds of DosFSCtl functions are possible: functions that are handled locally, and functions that are exported across the network. If bit 0x4000 is set in function, this indicates to the remote file-system driver (FSD) that the function should be exported.
Function codes from 0x0000 to 0x7FFF are reserved for use by the operating system. Function codes from 0x8000 to 0xBFFF are FSD-defined DosFSCtl functions handled by the local file-system driver. Function codes from 0xC000 to 0xFFFF are FSD-defined DosFSCtl functions exported to the server.
function may have one of the following values:
1 FSCTL_ERROR_INFO Returns error-code information from the file-system driver.
Input The error code is passed to the file-system driver in the first word of pParms.
Output The ASCIIZ string returned in pData is an explanation of the error code.
2 FSCTL_MAX_EASIZE
Queries the file-system driver for the maximum size of individual EAs (extended attributes), and the maximum size of the full EA list that it supports. The information is returned in pData in the form of an EASIZEBUF structure.
- pszRoute (PSZ) - input
- Address of the ASCIIZ name of the FSD, or the path name of a file or directory that the operation applies to.
This parameter must be a null pointer (OL) If method is equal to FSCTL_HANDLE
- hFile (HFILE) - input
- File-specific or device-specific handle.
This parameter must be -1 when method is equal to FSCTL_PATHNAME or FSCTL_FSDNAME.
- method (ULONG) - input
- Method used to routed the request.
Possible values are shown in the following list:
1 FSCTL_HANDLE hFile directs routing. pszRoute must be a null pointer (0L). The file-system driver associated with the handle receives the request.
2 FSCTL_PATHNAME pszRoute refers to a path name that directs routing. hFile must be -1. The file-system driver associated with the drive that the path name refers to at the time of the request receives the request. The path name need not refer to a file or directory that actually exists, only to a drive. A relative path name may be used; it is processed like any other path name.
3 FSCTL_FSDNAME pszRoute refers to a file-system driver name that directs routing. hFile must be -1. The named file-system driver receives the request.
Return Code
ulrc (APIRET) - returns
DosFSCtl returns one of the following values:
- 0 NO_ERROR
- 1 ERROR_INVALID_FUNCTION
- 6 ERROR_INVALID_HANDLE
- 87 ERROR_INVALID_PARAMETER
- 95 ERROR_INTERRUPT
- 111 ERROR_BUFFER_OVERFLOW
- 117 ERROR_INVALID_CATEGORY
- 124 ERROR_INVALID_LEVEL
- 252 ERROR_INVALID_FSD_NAME
Remarks
For debugging considerations, see DosDebug.
Example Code
The following is NOT a complete C program. It is intended to provide an idea of how to communicate with a file system driver (FSD).
This example assumes that FileHandle has been initialized with the handle to the file and that the file system driver (FSD) recognizes a function code of hex 81DE. It further assumes that the input parameters and input data area are appropriate for the function.
#define INCL_DOSFILEMGR /* File Manager values */
#define INCL_DOSERRORS /* Error values */
#include <os2.h>
#include <stdio.h>
#include <string.h>
UCHAR uchDataArea[200] = {0}; /* Input and output data area */
ULONG ulDataLen = 0; /* Input and output data size */
UCHAR uchParms[120] = {0}; /* Input and output for function */
ULONG ulParmLen = 0; /* Input and output parameter size */
ULONG ulFunction = 0x81DE; /* Device-specific function */
HFILE hfFile = NULLHANDLE; /* Handle for file */
APIRET rc = NO_ERROR; /* Return code */
strcpy(uchDataArea,"34 22 37"); /* Data to pass to file system */
ulDataLen = strlen(uchDataArea); /* Length of input data */
strcpy(uchParms,"PARM1: 98"); /* Input parameters */
ulParmLen = strlen(uchParms); /* Length of input parameters */
rc = DosFSCtl(uchDataArea, /* Input/output data area */
sizeof(uchDataArea), /* Maximum output data size */
&ulDataLen, /* Input: size of input data area */
/* Output: size of data returned */
uchParms, /* Input/Output parameter list */
sizeof(uchParms), /* Maximum output parameter size */
&ulParmLen, /* Input: size of parameter list */
/* Output: size of parameters returned */
ulFunction, /* Function being requested */
"MY_FSD", /* File System Driver (FSD) name */
hfFile, /* Handle for file */
FSCTL_FSDNAME); /* Indicate FSD name is the route */
if (rc != NO_ERROR) {
printf("DosFSCtl error: return code = %u\n", rc);
return 1;
}