CloseHandle

The CloseHandle function closes an open object handle.

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

Parameters

hObject

[in/out] 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.

Windows NT/2000: Closing an invalid handle raises an exception when the application is running under a debugger. This includes closing a handle twice, and using CloseHandle on a handle returned by the FindFirstFile function.

Remarks

The CloseHandle function closes handles to the following objects:

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

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 FindFirstFile.

MAPI: For more information, see Syntax and Limitations for Win32 Functions Useful in MAPI Development.

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

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