Troubleshooting Handles

Handles are tokens (or pointers) to access resources within an application. The Handle checks ensure that applications do not attempt to use invalid handles. This includes the following:

• Ensures that handles are valid when passed to APIs that take a handle. If a NULL value or an INVALID_HANDLE_VALUE value is passed, the handle is clearly invalid and further investigation is necessary.

• Ensures that TLS indexes passed to TLS functions are valid.

• Ensures that APIs are not called with handles that have been closed.

The following bulleted list shows handle stop codes you will commonly encounter while debugging your application. For each stop code, there is a detailed explanation on how you can troubleshoot each error:

• The handle used for the current operation is invalid: This stop code will occur in circumstances such as using a handle after closing it using CloseHandle (or trying to use an unassigned NULL handle). This error is usually generated from an application function at the top of the stack.

  The easiest way to troubleshoot the error is by looking at the call stack for the operation that used the invalid handle. You can then do a code review to look for all recurrences of that handle to pinpoint the problem, especially when a CloseHandle function is called.

• Invalid parameters passed to a multi-object wait function: If you pass a NULL/invalid handle to a WaitForSingleObject call or an incorrect number of handles to a WaitForMultipleObjects call, this error is shown. You can solve the problem by looking at the call stack: Simply look for the function that is incorrectly calling the API.

• A NULL handle has been used: Using NULL handles will invariably cause unpredictable results.

  To pinpoint the source of the problem, you should look at the call stack to find the reference to the NULL handle.

• The current thread is performing a wait operating on a thread handle in DllMain: The DllMain function is primarily used to perform enter/exit operations on a Dynamic Link Library (.DLL). It is used to synchronize and manage both processes and threads.

  In a process, if you have a thread that is executing code using DllMain and it calls WaitForSingleObject or WaitForMultipleObjects on a thread handle, you will receive this stop code.

  The problem is that the DLL loader lock is owned by the waiting thread. This will likely lead to a deadlock because the thread handle will not get signaled unless that second thread (the thread that is being waited on) is exiting. When the second thread calls ExitThread it will try to acquire the DLL loader lock and then call DllMain (DLL_THREAD_DETACH) for all DLLs in the current process. But the loader lock is owned by the first thread (the one that is waiting on the thread handle) so the two threads will deadlock. To fix this problem, look at the current call stack where the wait operation is being performed and avoid waiting on a thread handle in DllMain.

• Incorrect object type for handle: Handles are available for a number of thread synchronization mechanisms. For example, you can create handles for semaphores, mutexes, and event objects.

  If you try to call a semaphore with, for example, an event object handle, you will receive the "Incorrect object type for handle" stop code. The best way to deal with this error is to look at the call stack to pinpoint the invalid object type in your code.

• Invalid TLS index in the current operation: Sometimes a programmer makes assumptions about an index value for the Thread Local Storage (TLS) instead of retrieving the value using TlsAlloc. This stop code may also occur if you are trying to pass an uninitialized variable. To solve the problem, look in the call stack for the invalid index.