CloseHandle 함수(handleapi.h)

열린 개체 핸들을 닫습니다.

구문

BOOL CloseHandle(
  [in] HANDLE hObject
);

매개 변수

[in] hObject

열린 개체에 대한 유효한 핸들입니다.

반환 값

함수가 성공하면 반환 값이 0이 아닙니다.

함수가 실패하면 반환 값은 0입니다. 확장 오류 정보를 가져오려면 GetLastError를 호출합니다.

애플리케이션이 디버거에서 실행 중인 경우 함수는 유효하지 않은 핸들 값 또는 의사 핸들 값을 받으면 예외를 throw합니다. 이 문제는 핸들을 두 번 닫거나 FindClose 함수를 호출하는 대신 FindFirstFile 함수에서 반환된 핸들에서 CloseHandle을 호출하는 경우에 발생할 수 있습니다.

설명

CloseHandle 함수는 다음 개체에 대한 핸들을 닫습니다.

  • 액세스 토큰
  • 통신 디바이스
  • 콘솔 입력
  • 콘솔 화면 버퍼
  • 이벤트
  • 파일
  • 파일 매핑
  • I/O 완료 포트
  • 작업
  • Mailslot
  • 메모리 리소스 알림
  • Mutex
  • 명명된 파이프
  • 파이프
  • 프로세스
  • 세마포
  • 스레드
  • 트랜잭션
  • 대기 가능한 타이머
이러한 개체를 만드는 함수에 대한 설명서는 개체를 완료할 때 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 Professional [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows 2000 Server [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 handleapi.h(Windows.h 포함)
라이브러리 Kernel32.lib
DLL Kernel32.dll

참고 항목

CreateFile

CreateFileTransacted

DeleteFile

FindClose

FindFirstFile

핸들 및 개체 함수

커널 개체

개체 인터페이스