CloseHandle

CloseHandle is a Windows API function that closes an open object handle. It is declared in Windows.h and implemented in kernel32.dll. The function accepts a single parameter, hObject, which is a HANDLE to an open kernel object such as a file, event, mutex, semaphore, timer, process, or thread. CloseHandle decrements the object's reference count and releases the system resources associated with the handle. When the final reference to the object is closed, the object is destroyed and its resources are freed. The function does not terminate the object itself; closing a process or thread handle merely releases the handle, not the process or thread.

Return value: CloseHandle returns a nonzero value on success and zero on failure. If it fails, the caller can call GetLastError to obtain the error code. A common error is ERROR_INVALID_HANDLE, which indicates that the supplied hObject is not a valid handle or has already been closed. Some handles are pseudo handles (for example GetCurrentProcess) and cannot be closed; passing such a handle to CloseHandle will fail with ERROR_INVALID_HANDLE.

Usage notes: You must close every handle you obtain from a Windows API function (or duplicate). Do not reuse a handle after CloseHandle returns success. After closing, the handle value becomes invalid and should not be used again. In multi-threaded programs, closing a handle from one thread is safe, but care must be taken to avoid double-closing or racing with other threads.

See also: DuplicateHandle, GetLastError, GetCurrentProcess.