        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 =<hex constant>
    DebugFilter  =<hex constant>

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.
