Driver
Verifier and System Information API Wrapper Specification (Phase 3)
Last Updated: 12/25/99
3. Driver Verifier
Control and Statistics
3.2 Retrieving
Driver Verifier Settings
3.3 Setting
Driver Verifier Settings
3.4 Getting
Global Verification Statistics. 4
3.5 Getting
Per Driver Verification Statistics
4.2 Querying
Process Statistics
5. Handle and Object
Type Information
5.2 Querying
Handle Information By Process
5.3 Querying
Handle Information By Object Type
5.4 Querying
Object Type Information
This document specifies a DLL containing wrappers for various functions that are only available via the NtQuerySystemInformation API, and other miscellaneous system functionality.
The DLL is syswrap.dll; the public header file for this DLL is syswrap.h and the import library is syswrap.lib.
In phase 3 only 32-bit x86 is supported by this DLL. The DLL runs only on NT4 and later, though not all functions are available when running on various OS versions.
Routines are supplied for the following general classes of functionality. Each is discussed in its own section below.
Table of Contents Ý
The DLL provides some general-purpose routines.
SysQueryDllVersion — return version information about the wrapper DLL
VOID
APIENTRY
SysQueryDllVersion(
OUT WORD *Major,
OUT WORD *Minor
);
Parameters:
Major — receives the major version of the DLL. This is currently 1.
Minor — receives the minor version of the DLL. This is currently 0.
Return Value:
None.
Table of Contents Ý
The DLL contains a set of routines for manipulating the settings of the Windows 2000 driver verifier, and querying statistics that are maintained by the verifier for drivers being verified. The driver verifier is documented at http://www.microsoft.com/HWDEV/driver/driververify.htm and http://www.microsoft.com/DDK/DDKdocs/Win2k/drverif_5nqf.htm. It is assumed that the reader is familiar with the driver verifier (and therefore the rationale for using the routines provided by this DLL).
These routines function successfully only on Windows 2000 and later. They do not function on NT4.
SysQueryDriverVerifierSettings — retrieve driver verifier settings
SysSetDriverVerifierSettings — configure the driver verifier
SysGetDriverVerifierGlobalStatistics — get global statistics for drivers being verified
SysGetDriverVerifierPerDriverStatistics — get per driver stats for drivers being verified
The sections that follow describe these routines in greater detail.
Table of Contents Ý
The following data structures are used with the driver verifier routines in this DLL.
The DriverVerifierFeatures enum is a list of the driver verifier levels. The values can be combined bitwise.
typedef enum {
DvFeatureSpecialPool =
1,
DvFeatureIrqlChecking =
2,
DvFeatureAllocationFaultInjection
= 4,
DvFeaturePoolTracking =
8,
DvFeatureIoVerification
= 16
} DriverVerifierFeatures;
The SX_DRIVER_VERIFIER_SETTING structure describes one individual per-driver driver verifier setting, which is an association between a particular driver and a set of enabled driver verifier features.
typedef struct
_SX_DRIVER_VERIFIER_SETTING {
DriverVerifierFeatures Features;
WCHAR Driver[MAX_PATH];
} SX_DRIVER_VERIFIER_SETTING, *PSX_DRIVER_VERIFIER_SETTING;
The SX_DRIVER_VERIFIER_GLOBAL_STATISTICS structure represents the statistics maintained by the driver verifier cumulatively for all drivers being verified, as long as there is at least one driver being verified. Drivers not being verified are not included in the statistics.
typedef struct
_SX_DRIVER_VERIFIER_GLOBAL_STATISTICS {
DWORD StructureSize;
DWORD RaiseIrqls;
DWORD AcquireSpinLocks;
DWORD UntrackedPool;
DWORD SynchronizeExecutions;
DWORD AllocationsAttempted;
DWORD AllocationsSucceeded;
DWORD AllocationsSucceededSpecialPool;
DWORD AllocationsWithNoTag;
DWORD AllocationsFailed;
DWORD AllocationsFailedDeliberately;
DWORD TrimRequests;
DWORD Trims;
} SX_DRIVER_VERIFIER_GLOBAL_STATISTICS, *PSX_DRIVER_VERIFIER_GLOBAL_STATISTICS;
The SX_DRIVER_VERIFIER_PERDRIVER_STATISTICS structure represents the statistics maintained by the driver verifier on a per-driver basis for each driver being verified.
typedef struct
_SX_DRIVER_VERIFIER_PERDRIVER_STATISTICS {
DWORD StructureSize;
DWORD Loads;
DWORD Unloads;
DWORD CurrentPagedPoolAllocations;
DWORD CurrentNonPagedPoolAllocations;
DWORD PeakPagedPoolAllocations;
DWORD PeakNonPagedPoolAllocations;
SIZE_T PagedPoolUsageInBytes;
SIZE_T NonPagedPoolUsageInBytes;
SIZE_T PeakPagedPoolUsageInBytes;
SIZE_T PeakNonPagedPoolUsageInBytes;
} SX_DRIVER_VERIFIER_PERDRIVER_STATISTICS, *PSX_DRIVER_VERIFIER_PERDRIVER_STATISTICS;
Table of Contents Ý
Driver verifier settings can be retrieved from the system by using the SysQueryDriverVerifierSettings routine. The settings that are retrieved can be either the current operational settings (i.e., what the system is using now) or the persistent settings (i.e., what is stored in the registry and will therefore be effective upon the next reboot).
BOOL
APIENTRY
SysQueryDriverVerifierSettings(
OUT
PSX_DRIVER_VERIFIER_SETTING Settings,
IN DWORD BufferLength,
OUT LPDWORD SettingCount,
IN DWORD Flags
);
Parameters:
Settings — Points to a buffer which is filled on output with an array of structures describing the current or persistent driver verifier settings (depending on Flags).
BufferLength — Supplies the length in bytes of the buffer pointed to by Settings.
SettingCount — If the routine completes successfully, receives a count of the number of SX_DRIVER_VERIFIER_SETTING structures placed into the Settings buffer. If the routine fails and GetLastError returns ERROR_MORE_DATA, then the supplied buffer was too small and this value contains the required size of the Settings buffer in units of SX_DRIVER_VERIFIER_SETTING structures.
Flags — Supplies flags that refine the behavior of this routine.
SX_DVFLAG_CURRENT_SETTING — indicates that the current operational settings are to be returned. If this flag is not specified, then the persistent (registry) settings are returned.
Return Value:
A zero value
indicates failure and a non-zero value indicates success. In the failure case,
GetLastError can be called to get extended error information.
ERROR_MORE_DATA — the supplied buffer was too small. As much data as would fit
was returned and SettingCount received the required size of the buffer.
Table of Contents Ý
The driver verifier can be controlled with the SysSetDriverVerifierSettings routine. The settings passed to this routine completely replace the existing settings; it is not possible to add or remove individual drivers. The settings that can be controlled are the current operational settings (i.e., dynamic changes) or the persistent settings (i.e., changes effective upon reboot).
Note: in Windows 2000, only persistent settings can be altered; altering the current settings is not supported.
BOOL
APIENTRY
SysSetDriverVerifierSettings(
IN PSX_DRIVER_VERIFIER_SETTING
Settings, OPTIONAL
IN DWORD SettingCount,
IN DWORD Flags,
OUT BOOL *RebootRequired
);
Parameters:
Settings — Points to a buffer which supplies the settings to be applied, either immediately or upon next reboot (depending on Flags). [Note: in Windows 2000, only the persistent settings can be set with this routine.] If the first setting’s driver name is ‘*’ then SettingCount must be 1 and the driver verifier is enabled for all drivers in the system at the level specified by the Features field of the zeroth (and only) element in the Settings array. If Settings is not specified, then SettingCount must be 0 and the driver verifier is completely shut off and all settings are deleted.
SettingCount — Supplies the number of SX_DRIVER_VERIFIER_SETTING structures in the buffer pointed to by Settings. [Note: In Windows 2000, the Features field of each setting in the Settings array must be exactly the same or the routine fails, as Windows 2000’s driver verifier does not support per-driver verification settings.]
Flags — Supplies flags that refine the behavior of this routine.
SX_DVFLAG_CURRENT_SETTING — indicates that the current operational settings are to be altered. If this flag is not specified, then the persistent (registry) settings are altered. [Note: in Windows 2000 this flag is not supported and must not be set, or the routine fails and GetLastError returns ERROR_INVALID_FUNCTION.]
RebootRequired — If the routine is successful, on output receives a flag indicating whether a reboot is required for the changes to take effect. [Note: on Windows 2000 this flag will always be set.]
Return Value:
A zero value
indicates failure and a non-zero value indicates success. In the failure case,
GetLastError can be called to get extended error information. Upon success, the
caller should check the RebootRequired value to determine if the system
must be rebooted for the changes to take effect.
Table of Contents Ý
When enabled for any driver, the driver verifier maintains global statistics that are cumulative for all drivers being verified. Drivers that are not being verified are not included in the statistics. The global statistics can be returned by calling the SysGetDriverVerifierGlobalStatistics routine.
BOOL
APIENTRY
SysGetDriverVerifierGlobalStatistics(
IN OUT
PSX_DRIVER_VERIFIER_GLOBAL_STATISTICS Statistics
);
Parameters:
Statistics — on successful completion, receives the global statistics maintained by the driver verifier. Before calling this routine, the caller must set the StructureSize member to the size of the SX_DRIVER_VERIFIER_GLOBAL_STATISTICS structure.
Return Value:
The return value is zero for failure or non-zero for success. In the failure case, GetLastError can be called to retrieve extended error information.
ERROR_NO_MORE_ITEMS — indicates that the driver verifier is not enabled so there are no statistics available.
Table of Contents Ý
When enabled for a driver, the driver verifier maintains some per-driver statistics for it. These statistics can be returned by calling the SysGetDriverVerifierPerDriverStatistics routine.
BOOL
APIENTRY
SysGetDriverVerifierPerDriverStatistics(
IN LPCWSTR DriverName, OPTIONAL
IN OUT
PSX_DRIVER_VERIFIER_PERDRIVER_STATISTICS Statistics,
IN DWORD BufferLength,
OUT LPDWORD DriverCount
);
Parameters:
DriverName — if specified, supplies the name of the driver whose statistics are desired. This should be the base name and extension only, i.e., foo.sys. If not specified, per-driver statistics for all drivers currently being verified are returned.
Statistics — Points to a buffer which, upon successful completion, receives the statistics maintained by the driver verifier for the specified driver or all drivers (depending on DriverName). Before calling this routine, the caller must set the StructureSize member of the zeroth element in this array to the size of the SX_DRIVER_VERIFIER_PERDRIVER_STATISTICS structure.
BufferLength — supplies the length in
bytes of the buffer pointed to by Statistics. If this is zero then Statistics is ignored.
DriverCount — receives the number of
SX_DRIVER_VERIFIER_DRIVER_STATISTICS structures that were written into the Statistics buffer. If the routine fails and
GetLastError returns ERROR_MORE_DATA, then the buffer was filled to the extent
possible and this value indicates the required size of the buffer.
Return Value:
The return value is zero for
failure or non-zero for success. In the failure case, GetLastError can be
called to retrieve extended error information.
ERROR_NO_MORE_ITEMS — indicates that the driver verifier is not enabled so there
are no statistics available.
ERROR_MORE_DATA — indicates that the supplied buffer was not large enough. The
caller can check the DriverCount value to determine the required buffer
size.
Table of Contents Ý
The DLL provides a routine for querying process statistics for running processes. The name of the routine is SysGetProcessStatistics.
Process statistics are returned in the following data structure.
typedef struct
_SX_PROCESS_STATISTICS {
DWORD StructureSize;
DWORD NextEntryOffset;
DWORD64 CreateTime;
DWORD64 UserTime;
DWORD64 KernelTime;
DWORD64 ReadOperationCount;
DWORD64 WriteOperationCount;
DWORD64 OtherOperationCount;
DWORD64 ReadTransferCount;
DWORD64 WriteTransferCount;
DWORD64 OtherTransferCount;
ULONG_PTR UniqueProcessId;
ULONG_PTR InheritedFromUniqueProcessId;
SIZE_T PeakVirtualSize;
SIZE_T VirtualSize;
SIZE_T QuotaPeakPagedPoolUsage;
SIZE_T QuotaPagedPoolUsage;
SIZE_T QuotaPeakNonPagedPoolUsage;
SIZE_T QuotaNonPagedPoolUsage;
SIZE_T PagefileUsage;
SIZE_T PeakPagefileUsage;
SIZE_T PrivatePageCount;
LPWSTR ImageName;
DWORD NumberOfThreads;
DWORD SessionId;
LONG BasePriority;
DWORD HandleCount;
DWORD PageFaultCount;
DWORD PeakWorkingSetSize;
DWORD WorkingSetSize;
} SX_PROCESS_STATISTICS, *PSX_PROCESS_STATISTICS;
Most fields are self-explanatory; notes about certain fields follow.
StructureSize — prior to calling SysGetProcessStatistics, the caller must fill in the first element in the output buffer with the expected size of a statistics structure (i.e., sizeof(SX_PROCESS_STATISTICS). This is used as a versioning mechanism.
NextEntryOffset — supplies the offset in bytes from the start of a structure to the start of the next one in the buffer. Callers MUST use this offset to move through the returned structures. The last one in the buffer will have a NextEntryOffset of 0.
XxxOperationCount, XxxTransferCount — these six fields will always be zero on NT4.
ImageName — will point somewhere within the buffer supplied by the caller.
Note that when returned to the caller, structures will be aligned to SIZE_T-byte boundaries.
Table of Contents Ý
The SysGetProcessStatistics routine can be used to retrieve system information about running processes. The caller can specify matching criteria, which can be either a process id or an image name, to narrow the set of processes whose statistics are to be retrieved. Statistics are returned into a caller-supplied buffer.
BOOL
APIENTRY
SysGetProcessStatistics(
IN LPCWSTR ProcessImageName,
OPTIONAL
IN ULONG_PTR ProcessId,
OPTIONAL
IN OUT PSX_PROCESS_STATISTICS Statistics,
IN DWORD BufferLength,
OUT LPDWORD ProcessCount,
OUT LPDWORD BytesReturned
);
Parameters:
ProcessImageName — if specified, supplies the image name of the process(es) whose statistics are desired (all processes with this image name are returned). This should be the base name and extension only, i.e., cmd.exe. Only one of ProcessImageName and ProcessId may be specified or the routine fails. If neither is specified, statistics for all processes are returned.
ProcessId — if specified, supplies the process id of the process whose statistics are desired. Note that at most one process will be returned in this case. Only one of ProcessImageName and ProcessId may be specified or the routine fails. If neither is specified, statistics for all processes are returned.
Statistics — Points to a buffer which, upon successful completion, receives the statistics maintained by the system for the specified processes (depending on ProcessImageName and ProcessId). Before calling this routine, the caller must set the StructureSize member of the zeroth element in this array to the size of the SX_PROCESS_STATISTICS structure.
BufferLength — supplies the length of
the buffer pointed to by Statistics, in bytes. If this is zero then Statistics is ignored.
ProcessCount — receives the number of
processes that matched the criteria specified by ProcessImageName and ProcessId. Note that zero is a valid return value. This value is valid if the
routine returns TRUE, or if it returns FALSE and GetLastError returns
ERROR_MORE_DATA.
BytesReturned — receives the number of bytes
structures that were written into the Statistics buffer. Note that zero is a valid return
value. If the routine fails and GetLastError returns ERROR_MORE_DATA, then the
buffer was filled to the extent possible and this value indicates the required
size of the buffer.
Return Value:
The return value is zero for
failure or non-zero for success. In the failure case, GetLastError can be
called to retrieve extended error information.
ERROR_MORE_DATA — indicates that the supplied buffer was not large enough. The
caller can check the BytesReturned value to determine the required
buffer size.
Table of Contents Ý
The DLL provides routines to query information about open handles (or, more precisely, the data from handle table entries) and system object types.
SysGetHandlesInfoForProcess — retrieve information about handles currently in the handle table for a particular process
SysGetHandlesInfoForObjectType — retrieve information about all handles in the system that represent an object of a given type
SysGetObjectTypeInfo — retrieve information about a particular object type
The sections that follow describe the routines in greater detail.
Table of Contents Ý
This section describes the data structures used by the handle and object type information routines in the DLL.
Handle information is returned in the following data structure.
typedef struct _SX_HANDLE_INFO {
DWORD StructureSize;
ULONG_PTR HandleValue;
ULONG_PTR ProcessId;
DWORD GrantedAccess;
HandleAttributes Attributes;
LONG ObjectTypeIndex;
} SX_HANDLE_INFO, *PSX_HANDLE_INFO;
StructureSize — the size of this structure in bytes.
HandleValue — the numeric value of the handle.
ProcessId — the unique process id of the process in which the handle is open.
GrantedAccess — a bitmask indicating the access permitted through the handle.
Attributes — a bitfield indicating
various properties of the handle set when it was opened. Besides the values in
the enumerated type, others are possible; the routines in the DLL do not filter
the attributes returned by the underlying NT system API.
typedef enum {
HaAttributeInherit = 2,
HaAttributePermanent
= 16,
HaAttributeExclusive
= 32,
HaAttributeCaseInsensitive
= 64,
HaAttributeOpenIf = 128
} HandleAttributes;
ObjectTypeIndex — a value which indexes an array of object type structures. This is used with the SysGetHandlesInfoForProcess routine and is fully described there. Note: this is not the same as the ObjectTypeIndex maintained by the system in handle table entries.
Object type information is returned in the following data structure.
typedef struct
_SX_OBJECT_TYPE_INFO {
DWORD StructureSize;
DWORD ObjectCount;
DWORD HandleCount;
DWORD InvalidAttributes;
DWORD ValidAccessMask;
GENERIC_MAPPING GenericMapping;
DWORD Flags;
WCHAR ObjectTypeName[SX_MAX_OBJECT_TYPE_NAME];
} SX_OBJECT_TYPE_INFO, *PSX_OBJECT_TYPE_INFO;
StructureSize — the size of this structure in bytes.
ObjectCount — the number of objects of this type currently in existence system-wide.
HandleCount — the number of handles currently open to objects of this type.
InvalidAttributes — a mask indicating which values in the HandleAttributes enum are not allowed for handles opened to objects of this type.
ValidAccessMask — a mask supplying legal access types for handles opened to objects of this type.
GenericMapping — maps GENERIC_XXX access values to type-specific access values.
Flags — miscellaneous information about the object type.
SX_OTFLAG_SECURITY_REQUIRED — indicates that security checks are performed when an attempt is made to open an object of this type.
SX_OTFLAG_WAITABLE — indicates that objects of this type can be waited on.
SX_OTFLAG_PAGED_POOL — indicates that objects of this type will be placed in paged pool. If this flag is not set then objects of this type are in nonpaged pool.
ObjectTypeName — supplies the class/name for this type of object. Note that the system does not impose any practical limits on the length of this name; empirical observations indicate that these names are not generally too long and therefore for convenience an arbitrary limit is imposed in this structure. SX_MAX_OBJECT_TYPE_NAME is currently defined as 64 characters.
Table of Contents Ý
The SysGetHandlesInfoForProcess routine can be used to retrieve a list of the handles currently open in a particular process. This includes information about the handles, and optionally about their associated object types. Note, however, that retrieving information about the object types significantly impacts the performance of this routine.
BOOL
APIENTRY
SysGetHandlesInfoForProcess(
IN ULONG_PTR ProcessId,
IN OUT PSX_HANDLE_INFO HandleInfo,
IN DWORD HandleInfoBufferLength,
OUT LPDWORD HandleCount,
IN OUT PSX_OBJECT_TYPE_INFO ObjectTypeInfo,
OPTIONAL
IN DWORD ObjectTypeInfoBufferLength,
OUT LPDWORD ObjectTypeCount
);
Parameters:
ProcessId — supplies the unique process id for the process about whose handles information is to be returned.
HandleInfo — receives information about the handles for the specified process. On input, the caller must set the StructureSize member of the zeroth member in this buffer to sizeof(SX_HANDLE_INFO) or the routine fails. If HandleInfoBufferLength is 0 then this parameter is ignored.
HandleInfoBufferLength — supplies the length of the buffer pointed to by HandleInfo, in bytes. If the information to be returned is too big to fit in this buffer, the routine returns FALSE and GetLastError returns ERROR_MORE_DATA. As much data as will fit is placed in HandleInfo in this case; the caller can check the HandleCount for the required size to get all the data.
HandleCount — receives the number of SX_HANDLE_INFO structures placed into the HandleInfo buffer. If the routine fails and GetLastError returns ERROR_MORE_DATA, this value is the number of SX_HANDLE_INFO structures that would be returned if the buffer were large enough.
ObjectTypeInfo — optionally receives information about the object types represented by the handles whose information is returned in HandleInfo. On input, the caller must set the StructureSize member of the zeroth member in this buffer to sizeof(SX_OBJECT_TYPE_INFO) or the routine fails. The ObjectTypeIndex member of each SX_HANDLE_INFO structure returned in the HandleInfo buffer is an index into the array that the routine places into the buffer pointed to by this parameter. If this buffer is too small, one or more ObjectTypeIndex values could be –1 to indicate that there is no associated object type record available. This value is ignored if ObjectTypeInfoBufferLength is 0.
ObjectTypeInfoBufferLength — supplies the size in bytes of the buffer pointed to by the ObjectTypeInfo parameter. If the buffer is too small, the routine returns FALSE and GetLastError returns ERROR_MORE_DATA. In this case the caller can check the ObjectTypeCount value to get the required size.
ObjectTypeCount — receives the number of SX_OBJECT_TYPE_INFO structures placed in the buffer pointed to by the ObjectTypeInfo parameter. If the routine fails and GetLastError returns ERROR_MORE_DATA, this value is the number of object types that would be returned if the buffer were large enough.
Return Value:
The return value is a boolean value indicating whether the routine succeeded or failed. In the failure case, GetLastError can be called to retrieve extended error information.
ERROR_MORE_DATA — either the HandleInfo or the ObjectTypeInfo buffer is too small.
ERROR_FILE_NOT_FOUND — the given process id is invalid.
Table of Contents Ý
The SysGetHandlesInfoForObjectType routine can he used to retrieve a list of the handles of a particular object type currently open system-wide (i.e., in all processes). Information about the object type is also retrieved.
BOOL
APIENTRY
SysGetHandlesInfoForObjectType(
IN LPCWSTR TypeName,
IN OUT PSX_HANDLE_INFO HandleInfo,
IN DWORD HandleInfoBufferLength,
OUT LPDWORD HandleCount,
IN OUT PSX_OBJECT_TYPE_INFO ObjectTypeInfo
OPTIONAL
);
Parameters:
TypeName — supplies the name of the type whose handles information is to be returned.
HandleInfo — receives information about
the handles for the specified object type. On input, the caller must set the StructureSize
member of the zeroth member in this buffer to sizeof(SX_HANDLE_INFO) or the
routine fails. If HandleInfoBufferLength is 0 then this parameter is
ignored.
Note that The ObjectTypeIndex member of each returned structure will be
set to 0.
HandleInfoBufferLength — supplies the length of the buffer pointed to by HandleInfo, in bytes. If the information to be returned is too big to fit in this buffer, the routine returns FALSE and GetLastError returns ERROR_MORE_DATA. As much data as will fit is placed in HandleInfo in this case; the caller can check the HandleCount for the required size to get all the data.
HandleCount — receives the number of SX_HANDLE_INFO structures placed into the HandleInfo buffer. If the routine fails and GetLastError returns ERROR_MORE_DATA, this value is the number of SX_HANDLE_INFO structures that would be returned if the buffer were large enough.
ObjectTypeInfo — optionally receives information about the object type represented by the given type name. On input, the caller must set the StructureSize member to sizeof(SX_OBJECT_TYPE_INFO) or the routine fails.
Return Value:
The return value is a boolean value indicating whether the routine succeeded or failed. In the failure case, GetLastError can be called to retrieve extended error information.
ERROR_MORE_DATA — either the HandleInfo buffer is too small.
ERROR_INVALID_NAME — the given type name is invalid.
Table of Contents Ý
The SysGetObjectTypeInfo routine can be used to retrieve information about a particular object type, or about all object types currently defined in the system.
BOOL
APIENTRY
SysGetObjectTypeInfo(
IN LPCWSTR TypeName,
OPTIONAL
IN OUT PSX_OBJECT_TYPE_INFO ObjectTypeInfo,
IN DWORD BufferLength,
OUT LPDWORD ObjectTypeCount
);
Parameters:
TypeName — supplies the name of the system object type whose information is to be returned. If not supplied, information about all object types in the system is retrieved.
ObjectTypeInfo — receives information about the specified object type(s). On input, the caller must set the StructureSize member of the zeroth member in this buffer to sizeof(SX_OBJECT_TYPE_INFO) or the routine fails. If BufferLength is 0 then this parameter is ignored.
BufferLength — supplies the length of the buffer pointed to by ObjectTypeInfo, in bytes. If the information to be returned is too big to fit in this buffer, the routine returns FALSE and GetLastError returns ERROR_MORE_DATA. As much data as will fit is placed in ObjectTypeInfo in this case; the caller can check the ObjectTypeCount for the required size to get all the data.
ObjectTypeCount — receives the number of SX_OBJECT_TYPE_INFO structures placed into the ObjectTypeInfo buffer. If the routine fails and GetLastError returns ERROR_MORE_DATA, this value is the number of SX_OBJECT_TYPE_INFO structures that would be returned if the buffer were large enough.
Return Value:
The return value is a boolean value indicating whether the routine succeeded or failed. In the failure case, GetLastError can be called to retrieve extended error information.
ERROR_MORE_DATA — either the ObjectTypeInfo buffer is too small.
Table of Contents Ý
The DLL provides routines to query and set system GlobalFlags (the bits in the NtGlobalFlags kernel variable that are relevant for kernel mode). Either the current operational state or the state stored in the registry can be retrieved. Note that these routines do not operate on the flags related to user mode.
SysQueryGlobalFlags — retrieve system GlobalFlags settings
SysSetGlobalFlags — set system GlobalFlags settings
The sections that follow describe the routines in greater detail.
Table of Contents Ý
The various GlobalFlags bits that are relevant for kernel mode are described in an enumerated type. User mode GlobalFlags bits are not represented in this enum.
typedef enum {
GflgStopOnException =
0x00000001,
GflgShowLdrSnaps =
0x00000002,
GflgDebugInitialCommand
= 0x00000004,
GflgStopOnHungGui =
0x00000008,
GflgPoolEnableTailCheck
= 0x00000100,
GflgPoolEnableFreeCheck
= 0x00000200,
GflgPoolEnableTagging =
0x00000400,
GflgKernelStackTraceDb
= 0x00002000,
GflgMaintainObjectTypeList
= 0x00004000,
GflgIgnoreDebugPriv =
0x00010000,
GflgEnableCsrDebug =
0x00020000,
GflgEnableKDebugSymbolLoad
= 0x00040000,
GflgDisablePageKernelStacks
= 0x00080000,
GflgEnableCloseExceptions
= 0x00400000,
GflgEnableExceptionLogging
= 0x00800000,
GflgEnableHandleTypeTagging
= 0x01000000,
GflgDebugInitialCommandEx
= 0x04000000,
GflgDisableDbgPrint =
0x08000000
} GlobalFlagsBits;
It is assumed that users of these routines understand what these bits represent.
Some of these bits are relevant only on particular versions of Windows NT.
NT4 only: GflgPoolEnableTailCheck, GflgPoolEnableFreeCheck, GflgIgnoreDebugPriv
Windows 2000 only: GflgDisableDbgPrint
Table of Contents Ý
The SysQueryGlobalFlags routine can be used to retrieve the current (the current value of the NtGlobalFlags kernel variable) or persistent (stored in the registry for use at next reboot) system GlobalFlags.
BOOL
APIENTRY
SysQueryGlobalFlags(
OUT PDWORD64 GlobalFlags,
IN LPVOID Reserved,
IN DWORD Flags
);
Parameters:
GlobalFlags — upon success, receives the GlobalFlags. Note that user mode system GlobalFlags will never be set in this value, nor will bits that are for the running version of Windows NT, as described above.
Reserved — must be 0.
Flags — supplies a set of values that control the behavior of this routine.
SX_GFLAG_CURRENT_SETTING — indicates that the current value of the NtGlobalFlags kernel variable is to returned.
SX_GFLAG_PERSISTENT_SETTING — indicates that the value stored in the registry (and which will therefore be effective at next reboot) is to be returned.
Return Value:
The return value is a boolean value indicating whether the routine succeeded or failed. In the failure case, GetLastError can be called to retrieve extended error information.
Table of Contents Ý
The SysSetGlobalFlags routine can be used to change the state of a subset of the system GlobalFlags. Other system GlobalFlags are considered by this routine to be read-only; their states cannot be modified with this routine. Some of the modifiable GlobalFlags flags can be changed on the fly (requires the caller to have SE_DEBUG privilege) whereas others can only be changed in the persistent state stored in the registry for use at next reboot (requires administrator access, depending on ACLs applied to the registry).
BOOL
APIENTRY
SysSetGlobalFlags(
IN DWORD64 GlobalFlags,
IN LPVOID Reserved,
IN DWORD Flags
);
Parameters:
GlobalFlags — supplies a GlobalFlags value to be applied. This routine will only change the state of those GlobalFlags flags that are deemed writeable (defined by the SX_GFLAGS_WRITEABLE_MASK in the header file) for the current version of the operating system as described above. Other GlobalFlags flags are not changed.
Reserved — must be 0.
Flags — supplies a set of values that control the behavior of this routine.
SX_GFLAG_CURRENT_SETTING — indicates that the current value of the NtGlobalFlags kernel variable is to returned. If this value is used, then no bit in GlobalFlags can be set if it is not included in the SX_GFLAGS_DYNAMIC_MASK define in the header file.
SX_GFLAG_PERSISTENT_SETTING — indicates that the value stored in the registry (and which will therefore be effective at next reboot) is to be returned.
Return Value:
The return value is a boolean value indicating whether the routine succeeded or failed. In the failure case, GetLastError can be called to retrieve extended error information.
ERROR_INVALID_FUNCTION — the SX_GFLAG_CURRENT_SETTING Flag was set, but the GlobalFlags value attempted to change a GlobalFlags bit that is not changeable without a reboot.
Table of Contents Ý