CloseHandle

The CloseHandle function closes an open object handle.

BOOL CloseHandle(
  HANDLE hObject   // handle to object to close
);
 

Parameters

hObject

Handle to an open object.

Return Values

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

The CloseHandle function closes handles to the following objects:

• Communications device
• Console input
• Console screen buffer
• Event
• File
• File mapping
• Job
• Mailslot
• Mutex
• Named pipe
• Process
• Semaphore
• Socket
• Thread
• Token

CloseHandle invalidates the specified object handle, decrements the object's handle count, and performs object retention checks. After the last handle to an object is closed, the object is removed from the system.

Closing a thread handle does not terminate the associated thread. To remove a thread object, you must terminate the thread, then close all handles to the thread.

Use CloseHandle to close handles returned by calls to the CreateFile function. Use FindClose to close handles returned by calls to the FindFirstFile function.

Closing an invalid handle raises an exception. This includes closing a handle twice, not checking the return value and closing an invalid handle, and using CloseHandle on a handle returned by FindFirstFile.

Windows CE: Windows CE does not support closing handles to the following objects:

• Console input or output
• File mapping
• Named pipe
• Semaphore
• Token

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Windows CE: Requires version 1.0 or later.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

Handles and Objects Overview, Handle and Object Functions, CreateFile, DeleteFile, FindClose, FindFirstFile