KdPrintEx function

The KdPrintEx macro sends a string to the kernel debugger if the conditions you specify are met.

A call to KdPrintEx requires double parentheses.

Syntax


ULONG KdPrintEx(
  _In_  ULONG ComponentId,
  _In_  ULONG Level,
  _In_  PCSTR Format,
  ... arguments
);

Parameters

ComponentId [in]

Specifies the component calling this routine. This must be one of the component name filter IDs defined in the dpfilter.h header file. To avoid mixing your driver's output with the output of Windows components, you should use only the following values for ComponentId:

  • DPFLTR_IHVVIDEO_ID

  • DPFLTR_IHVAUDIO_ID

  • DPFLTR_IHVNETWORK_ID

  • DPFLTR_IHVSTREAMING_ID

  • DPFLTR_IHVBUS_ID

  • DPFLTR_IHVDRIVER_ID

Level [in]

Specifies the severity of this message. This can be any 32-bit integer. Values between 0 and 31 (inclusive) are treated differently than values between 32 and 0xFFFFFFFF. For details, see Reading and Filtering Debugging Messages.

Format [in]

Specifies a pointer to the format string to print. The Format string supports most of the printf-style format specification fields. However, the Unicode format codes (%C, %S, %lc, %ls, %wc, %ws, and %wZ) can only be used with IRQL = PASSIVE_LEVEL. The KdPrintEx routine does not support any of the floating point types (%f, %e, %E, %g, %G, %a, or %A).

arguments

Specifies arguments for the format string, as in printf.

Return value

If successful, KdPrintEx returns the NTSTATUS code STATUS_SUCCESS; otherwise, it returns the appropriate error code.

Remarks

KdPrintEx is identical to the DbgPrintEx routine in code that is compiled for a debug configuration. This routine has no effect in code that is compiled for a release build. Only kernel-mode drivers can call the KdPrintEx routine.

Note  The Windows Driver Kit (WDK) 8 and WDK 7 manage the DBG preprocessor constant define appropriately for debug (check) and release (free) builds. For more information, see Conditional Compilation and the Build Environment.

KdPrintEx either passes the specified string to the kernel debugger or does nothing at all, depending on the values of ComponentId, Level, and the corresponding component filter masks. For details, see Reading and Filtering Debugging Messages.

Unless it is absolutely necessary, you should not obtain a string from user input or another process and pass it to KdPrintEx. If you do use a string that you did not create, you must verify that this is a valid format string, and that the format codes match the argument list in type and quantity. The best coding practice is for all Format strings to be static and defined at compile time.

There is no upper limit to the size of the Format string or the number of arguments. However, any single call to KdPrintEx will only transmit 512 bytes of information. There is also a limit to the size of the DbgPrint buffer. See The DbgPrint Buffer and the Debugger for details.

This routine is defined in ntddk.h and ndis.h; component filter IDs are defined in dpfilter.h, ndis.h, and wdm.h. Include ntddk.h or ndis.h.

Requirements

Version

Available in Microsoft Windows XP and later.

Header

Wdm.h (include Wdm.h)

Library

Ntoskrnl.lib (See DbgPrintEx.)

See also

DbgPrint
DbgPrintEx
KdPrint

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft