Home Library Learn Downloads Support Community
Sign in | United States - English | |
9 out of 20 rated this helpful - Rate this topic

GetExitCodeProcess function

Applies to: desktop apps only

Retrieves the termination status of the specified process.

Syntax

Copy 
BOOL WINAPI GetExitCodeProcess(
  __in   HANDLE hProcess,
  __out  LPDWORD lpExitCode
);

Parameters

hProcess [in]

A handle to the process.

The handle must have the PROCESS_QUERY_INFORMATION or PROCESS_QUERY_LIMITED_INFORMATION access right. For more information, see Process Security and Access Rights.

Windows Server 2003 and Windows XP:  The handle must have the PROCESS_QUERY_INFORMATION access right.
lpExitCode [out]

A pointer to a variable to receive the process termination status. For more information, see Remarks.

Return value

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

This function returns immediately. If the process has not terminated and the function succeeds, the status returned is STILL_ACTIVE. If the process has terminated and the function succeeds, the status returned is one of the following values:

  • The exit value specified in the ExitProcess or TerminateProcess function.
  • The return value from the main or WinMain function of the process.
  • The exception value for an unhandled exception that caused the process to terminate.

Important  The GetExitCodeProcess function returns a valid error code defined by the application only after the thread terminates. Therefore, an application should not use STILL_ACTIVE (259) as an error code. If a thread returns STILL_ACTIVE (259) as an error code, applications that test for this value could interpret it to mean that the thread is still running and continue to test for the completion of the thread after the thread has terminated, which could put the application into an infinite loop.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header
WinBase.h (include Windows.h)

Library
Kernel32.lib

DLL
Kernel32.dll

See also

ExitProcess
ExitThread
Process and Thread Functions
Processes
TerminateProcess
Terminating a Process
WinMain

 

 

Send comments about this topic to Microsoft

Build date: 3/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
More specific behavior when INVALID_HANDLE_VALUE is supplied as parameter
Return value indicates SUCCESS (non-zero) and lpExitCode is STILL_ACTIVE in the case where hProcess is set to INVALID_HANDLE_VALUE. For all other invalid HANDLE values, the function fails as expected in the return code and the value of lpExitCode cannot be used.
History
C# syntax 
[DllImport("kernel32.dll", SetLastError = true)]
[return: MarshalAs(UnmanagedType.Bool)]
public static extern bool GetExitCodeProcess(
     [In] IntPtr ProcessHandle,
     [Out] out int ExitCode
     );
History
vb.net syntax 
<DllImport("kernel32.dll", CharSet:=CharSet.Auto, SetLastError:=True)> _
Public Shared Function GetExitCodeProcess(ByVal processHandle As SafeProcessHandle, <Out> ByRef exitCode As Integer) As Boolean
End Function
History
Really only two sources for the return status
The exit code always comes from either ExitProcess or TerminateProcess.

The others are just special cases of calling ExitProcess (handy to know what value is passed of course):
The C Runtime Library calls ExitProcess when your main/WinMain function returns.
The default unhandled exception filter calls ExitProcess when an exception is unhandled.
History
Use WaitForSingleObject to resolve STILL_ACTIVE ambiguity
If this function places STILL_ACTIVE into lpExitCode, it can be ambiguous whether the process is still running or terminated with exit code 259, as per the warning above. If you don't know by other means whether the process has terminated, if STILL_ACTIVE is the exit code, call WaitForSingleObject(hProcess, 0). WaitForSingleObject will return immediately (because the timeout is zero) WAIT_OBJECT_0 if the process has terminated and WAIT_TIMEOUT if it has not. Process objects are "signaled" when the process has terminated.
History