UID

title

description

helpviewer_keywords

old-location

tech.root

ms.assetid

ms.date

ms.keywords

req.header

req.include-header

req.target-type

req.target-min-winverclnt

req.target-min-winversvr

req.kmdf-ver

req.umdf-ver

req.ddi-compliance

req.unicode-ansi

req.idl

req.max-support

req.namespace

req.assembly

req.type-library

req.lib

req.dll

req.irql

targetos

req.typenames

req.redist

ms.custom

f1_keywords

dev_langs

topic_type

api_type

api_location

api_name

NF:debugapi.WaitForDebugEvent

WaitForDebugEvent function (debugapi.h)

Waits for a debugging event to occur in a process being debugged. (WaitForDebugEvent)

WaitForDebugEvent

WaitForDebugEvent function

_win32_waitfordebugevent

base.waitfordebugevent

debugapi/WaitForDebugEvent

base\waitfordebugevent.htm

Debug

0d81a4ac-dd66-4648-9f3f-1f54aca84243

12/05/2018

WaitForDebugEvent, WaitForDebugEvent function, _win32_waitfordebugevent, base.waitfordebugevent, debugapi/WaitForDebugEvent

debugapi.h

Windows.h

Windows

Windows XP [desktop apps only]

Windows Server 2003 [desktop apps only]

Kernel32.lib

Kernel32.dll

Windows

19H1

WaitForDebugEvent

debugapi/WaitForDebugEvent

c++

APIRef

kbSyntax

DllExport

Kernel32.dll

API-MS-Win-Core-debug-l1-1-1.dll

KernelBase.dll

API-MS-Win-DownLevel-Kernel32-l1-1-0.dll

MinKernelBase.dll

API-MS-Win-Core-Debug-L1-1-2.dll

WaitForDebugEvent

WaitForDebugEvent function

-description

Waits for a debugging event to occur in a process being debugged.

Important In the past, the operating system did not output Unicode strings via OutputDebugStringW and instead only output ASCII strings. To force OutputDebugStringW to correctly output Unicode strings, debuggers are required to call WaitForDebugEventEx to opt into the new behavior. On calling WaitForDebugEventEx, the operating system will know that the debugger supports Unicode and is specifically opting into receiving Unicode strings.

-parameters

-param lpDebugEvent [out]

A pointer to a DEBUG_EVENT structure that receives information about the debugging event.

-param dwMilliseconds [in]

The number of milliseconds to wait for a debugging event. If this parameter is zero, the function tests for a debugging event and returns immediately. If the parameter is INFINITE, the function does not return until a debugging event has occurred.

-returns

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

-remarks

Only the thread that created the process being debugged can call WaitForDebugEvent.

When a CREATE_PROCESS_DEBUG_EVENT occurs, the debugger application receives a handle to the image file of the process being debugged, a handle to the process being debugged, and a handle to the initial thread of the process being debugged in the DEBUG_EVENT structure. The members these handles are returned in are u.CreateProcessInfo.hFile (image file), u.CreateProcessInfo.hProcess (process), and u.CreateProcessInfo.hThread (initial thread). If the system previously reported an EXIT_PROCESS_DEBUG_EVENT debugging event, the system closes the handles to the process and thread when the debugger calls the ContinueDebugEvent function. The debugger should close the handle to the image file by calling the CloseHandle function.

Similarly, when a CREATE_THREAD_DEBUG_EVENT occurs, the debugger application receives a handle to the thread whose creation caused the debugging event in the u.CreateThread.hThread member of the DEBUG_EVENT structure. If the system previously reported an EXIT_THREAD_DEBUG_EVENT debugging event, the system closes the handles to the thread when the debugger calls the ContinueDebugEvent function.

When a LOAD_DLL_DEBUG_EVENT occurs, the debugger application receives a handle to the loaded DLL in the u.LoadDll.hFile member of the DEBUG_EVENT structure. This handle should be closed by the debugger application by calling the CloseHandle function.