closeHandle 函数 (handleapi.h)

项目
08/24/2023

关闭打开的对象句柄。

语法

BOOL CloseHandle(
  [in] HANDLE hObject
);

参数

[in] hObject

打开对象的有效句柄。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

如果应用程序在调试器下运行，则函数在收到无效的句柄值或伪句柄值时将引发异常。如果关闭句柄两次，或者对 FindFirstFile 函数返回的句柄调用 CloseHandle 而不是调用 FindClose 函数，则可能会发生这种情况。

注解

CloseHandle 函数关闭以下对象的句柄：

访问令牌
通信设备
控制台输入
控制台屏幕缓冲区
事件
文件
文件映射
I/O 完成端口
作业
Mailslot
内存资源通知
Mutex
命名管道
管道
进程
Semaphore
线程
事务
可等待计时器

创建这些对象的函数的文档指出，完成对象后应使用 CloseHandle ，以及关闭句柄后对对象挂起的操作会发生什么情况。通常， CloseHandle 会使指定的对象句柄失效，减少对象的句柄计数，并执行对象保留检查。关闭对象的最后一个句柄后，将从系统中删除该对象。有关这些对象的创建者函数的摘要，请参阅内核对象。

通常，应用程序应为每个打开的句柄调用 CloseHandle 一次。如果使用句柄的函数因ERROR_INVALID_HANDLE而失败，通常不需要调用 CloseHandle ，因为此错误通常表示句柄已无效。但是，某些函数使用 ERROR_INVALID_HANDLE 来指示对象本身不再有效。例如，如果网络连接断开，尝试使用对网络上文件的句柄的函数可能会失败并ERROR_INVALID_HANDLE，因为文件对象不再可用。在这种情况下，应用程序应关闭句柄。

如果处理句柄，则应在提交事务之前关闭绑定到事务的所有句柄。如果使用 FILE_FLAG_DELETE_ON_CLOSE 标志调用 CreateFileTransacted 打开了事务处理句柄，则在应用程序关闭句柄并调用 CommitTransaction 之前，不会删除该文件。有关事务处理对象的详细信息，请参阅使用事务。

关闭线程句柄不会终止关联的线程或删除线程对象。关闭进程句柄不会终止关联的进程或删除进程对象。若要删除线程对象，必须终止该线程，然后关闭该线程的所有句柄。有关详细信息，请参阅终止线程。若要删除进程对象，必须终止进程，然后关闭进程的所有句柄。有关详细信息，请参阅终止进程。

即使仍有文件视图处于打开状态，关闭文件映射的句柄也会成功。有关详细信息，请参阅关闭文件映射对象。

请勿使用 CloseHandle 函数关闭套接字。请改用 closesocket 函数，该函数释放与套接字关联的所有资源，包括套接字对象的句柄。有关详细信息，请参阅套接字关闭。

请勿使用 CloseHandle 函数关闭打开的注册表项的句柄。请改用 RegCloseKey 函数。 CloseHandle 不会关闭注册表项的句柄，但不返回指示此失败的错误。

示例

dwPriorityClass = 0;
hProcess = OpenProcess( PROCESS_ALL_ACCESS, FALSE, pe32.th32ProcessID );
if( hProcess == NULL )
	printError( TEXT("OpenProcess") );
else
{
	dwPriorityClass = GetPriorityClass( hProcess );
	if( !dwPriorityClass )
	printError( TEXT("GetPriorityClass") );
	CloseHandle( hProcess );
}

若要在上下文中查看此示例，请参阅拍摄快照和查看进程。

要求

要求	值
最低受支持的客户端	Windows 2000 专业版 [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows 2000 Server [桌面应用 \|UWP 应用]
目标平台	Windows
标头	handleapi.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll