Debug System Features --------------------- This document describes some APIs and WIN.INI options that can be used with the debugging version of the Windows system. None of the features are available in the retail version of the system: the APIs exist, but they have no effect. The debug system has features that provide some control over the various debugging messages output by the system, and to provide some assistance for debugging out-of-memory handling in applications. System debug output messages ---------------------------- All debugging output messages and RIPs in the debugging versions of USER, GDI, and KERNEL are categorized into four types: DBF_TRACE Informational message. No error has occured, but information may be useful during debugging. Example: "KERNEL: Loading FOO.DLL" DBF_WARNING A situation that may or may not be an error, depending on the circumstances. Example: "KERNEL: LoadString failed" DBF_ERROR An error resulting in a failed API call. Application continues running. Example: "KERNEL: Invalid local heap" DBF_FATAL An error that will result in terminating the application. Example: "USER: Obsolete function SetDeskWallpaper called" WINDEBUGINFO structure ---------------------- The debugging system debug information is provided in a WINDEBUGINFO structure: typedef struct tagWINDEBUGINFO { UINT flags; DWORD dwOptions; DWORD dwFilter; char achAllocModule[8]; DWORD dwAllocBreak; DWORD dwAllocCount; } WINDEBUGINFO; The flags field contains a combination of the following WDI_* values that indicates which of the remaining fields in the WINDEBUGINFO structure are valid: WDI_OPTIONS dwOptions contains a combination of DBO_* debug options (see below) (win.ini [Windows] DebugOptions value) WDI_FILTER dwFilter contains a combination of DBF_* trace filter flags (see below) (win.ini [Windows] DebugFilter value) WDI_ALLOCBREAK achAllocModule Alloc break module name dwAllocBreak Alloc break count dwAllocCount Current count of allocations (GetWinDebugInfo only) GetWinDebugInfo API ------------------- BOOL WINAPI GetWinDebugInfo(WINDEBUGINFO FAR* lpwdi, UINT flags); Queries current debugging system debug information. lpwdi is a pointer to a WINDEBUGINFO structure to be filled in, and flags contains a combination of WDI_* values indicating which fields of the WINDEBUGINFO to fill in. The flags field of the returned WINDEBUGINFO structure is set to the supplied flags parameter. Returns TRUE if successful, FALSE if lpwdi is invalid, or if running under the retail version of Windows. SetWinDebugInfo API ------------------- BOOL WINAPI SetWinDebugInfo(const WINDEBUGINFO FAR* lpwdi); Sets current debug system information. lpwdi is a pointer to the new WINDEBUGINFO data. The flags field of the pointed-to WINDEBUGINFO structure must contain a combination of one or more WDI_* flags indicating which debug information is to be set. You need only initialize those fields of the WINDEBUGINFO structure that correspond to the WDI_* flags you've set in lpwdi->flags. Debug info changes made with this API apply only until you exit the system or reboot your machine. Returns TRUE if successful, FALSE if lpwdi or lpwdi->flags is invalid, or if running under the retail version of Windows. DebugOptions/dwOptions values ----------------------------- DBO_CHECKHEAP 0x0001 Perform local heap checking after all LocalXXX() calls. Replaces old win.ini [Kernel] EnableHeapChecking=1. DBO_CHECKFREE 0x0020 All freed local memory will be filled with 0xFB. All newly allocated memory is checked to ensure it still contains 0xFBs, to ensure that someone hasn't written into a freed memory block. Has no effect if DBO_CHECKHEAP is not specified. Replaces old win.ini [Kernel] EnableFreeChecking=1 DBO_BUFFERFILL 0x0004 Fill buffers passed to APIs with 0xF9. Ensures that all of supplied buffer is writeable. Helps detect overwrite problems when supplied buffer size is not large enough (e.g., GetWindowText). DBO_DISABLEGPTRAPPING 0x0010 Disable hooking of the various fault interrupt vectors. Generally not useful for normal app development (since you can get lots of spurious traps related to parameter validation that aren't errors). Same as old [Kernel] DisableGPTrapping=1 DBO_SILENT 0x8000 No warning, error, or fatal messages are printed out unless a stack trace and "abort, break, ignore" prompt would occur. NOTE: We don't recommend the use of this flag -- it can cause you to miss or ignore many warnings that are in fact bugs that should be fixed. DBO_TRACEBREAK 0x2000 Break with "abort, break, ignore" on any DBF_TRACE message, but only if it matches the DebugFilter. DBO_WARNINGBREAK 0x1000 Break with "abort, break, ignore" prompt if a DBF_WARNING message occurs. (normally, DBF_WARNING messages are printed but no break occurs). Also applies to invalid parameter warnings. DBO_NOERRORBREAK 0x0800 Don't break with "abort, break, ignore" prompt if a DBF_ERROR error occurs. Also applies to invalid parameter errors. DBO_NOFATALBREAK 0x0400 Don't break with "abort, break, ignore" prompt if a DBF_FATAL error occurs. DBO_INT3BREAK 0x0100 Break to debugger with simple INT 3 rather than a call to FatalExit(). Does not generate a stack backtrace. DebugFilter/dwFilter options ---------------------------- The DebugFilter option controls the output of DBF_TRACE messages. Normally, trace messages are not output to the debug terminal. By setting the DebugFilter win.ini variable (or by calling SetWinDebugInfo), you can enable the output of various categories of trace messages: DBF_KERNEL 0x1000 Enable any trace message originating from KERNEL (DBF_KRN_*). DBF_KRN_MEMMAN 0x0001 Enable local and global memory management related messages from KERNEL DBF_KRN_LOADMODULE 0x0002 Enable module loading related messages from KERNEL DBF_KRN_SEGMENTLOAD 0x0004 Enable segment loading related messages from KERNEL DBF_USER 0x0800 Enable trace messages originating from USER DBF_GDI 0x0400 Enable trace messages originating from GDI DBF_MMSYSTEM 0x0040 Enable trace messages originating from MMSYSTEM DBF_PENWIN 0x0020 Enable trace messages originating from PENWIN DBF_DRIVER 0x0010 Enable trace messages originating from device drivers DBF_APPLICATION 0x0008 Enable trace messages originating from an application. WIN.INI Debug Options --------------------- You can control whether or not messages are printed, and whether you get a RIP stack backtrace and "Abort, Break, Ignore?" prompt with two special WIN.INI variables: [Windows] DebugOptions = DebugFilter = The Get/SetWinDebugInfo APIs may also be used to set or examine the options or filter values at runtime. Both can be set to a C style hex constant preceded by "0x". You can't use the OR operator to combine hex constants, nor can you use symbolic names for the constants: for example, to specify DBO_CHECKHEAP and DBO_FREEFILL, you'd use "DebugOptions=0x0021" in the [Windows] section of win.ini. DebugOutput() API ----------------- void FAR _cdecl DebugOutput(UINT flags, LPCSTR lpszFmt, ...); The DebugOutput API is used to generate messages to the debug terminal that are affected by the system debug options and trace filter flags. What happens with the output message depends on the value of flags and the value of the system debug options (DBO_* values). Possible values for flags are: DBF_TRACE Informational message. No error has occured, but information may be useful during debugging. Example: "KERNEL: Loading FOO.DLL" DBF_WARNING A situation that may or may not be an error, depending on the circumstances. Example: "KERNEL: LoadString failed" DBF_ERROR An error resulting in a failed API call. Application continues running. Example: "KERNEL: Invalid local heap" DBF_FATAL An error that will result in terminating the application. Example: "USER: Obsolete function SetDeskWallpaper called" The only other bit that may be used by applications is DBF_APPLICATION. Device driver DLLs may use DBF_DRIVER as well. lpszFmt is a formatting string identical to that for the wsprintf() API. It must be less than 160 characters long. Additional parameters for any '%' formatting to be done may be supplied to DebugOutput() after lpszFmt.