Windows API Reference

CloseHandle

The CloseHandle function closes an open object handle. This function is used for many different types of objects, including files, processes, threads, security and synchronization objects, and registry keys.

Syntax

BOOL CloseHandle(
  HANDLE hObject
);

Parameters

Parameter Type Description
hObject HANDLE A handle to an open object. This handle must have been created by an appropriate function, such as CreateFile, CreateProcess, or RegOpenKeyEx.

Return Value

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

You must close a handle when you are finished with it. Failure to do so can lead to resource leaks.

For file handles, using CloseHandle is equivalent to calling CloseHandle(hFile) where hFile is the handle returned by CreateFile.

The handle hObject must be a valid handle to an object that has been opened or created by the current process. It is an error to close a handle that has already been closed or that was opened by another process.

Requirements
Minimum supported client Windows 2000 Professional
Minimum supported server Windows 2000 Server
Header windows.h
Library Kernel32.lib
DLL Kernel32.dll

See Also

Example

This example demonstrates how to create a file, write to it, and then close the handle.


// Include necessary headers
#include <windows.h>
#include <iostream>

int main() {
    HANDLE hFile;
    DWORD dwBytesWritten;
    LPCSTR lpszData = "This is some data to write to the file.\r\n";

    // Create a file
    hFile = CreateFile(
        "MyNewFile.txt",          // File name
        GENERIC_WRITE,              // Write access
        0,                          // No sharing
        NULL,                       // Default security attributes
        CREATE_ALWAYS,              // Overwrite existing file, or create new
        FILE_ATTRIBUTE_NORMAL,      // Normal file attributes
        NULL                        // No template file
    );

    if (hFile == INVALID_HANDLE_VALUE) {
        std::cerr << "Error creating file: " << GetLastError() << std::endl;
        return 1;
    }

    // Write data to the file
    if (!WriteFile(
        hFile,                      // Handle to the file
        lpszData,                   // Data to write
        (DWORD)strlen(lpszData),    // Number of bytes to write
        &dwBytesWritten,            // Number of bytes written
        NULL                        // Not used
    )) {
        std::cerr << "Error writing to file: " << GetLastError() << std::endl;
        CloseHandle(hFile); // Ensure handle is closed even on error
        return 1;
    }

    std::cout << dwBytesWritten << " bytes written to file." << std::endl;

    // Close the file handle
    if (CloseHandle(hFile)) {
        std::cout << "File handle closed successfully." << std::endl;
    } else {
        std::cerr << "Error closing file handle: " << GetLastError() << std::endl;
        return 1;
    }

    return 0;
}