CloseHandle Function (File System)

The CloseHandle function closes an open object handle. A handle is a unique identifier for a system resource, such as a file, a process, or a thread. Closing a handle releases the resources associated with that handle and makes them available for other processes.

Syntax


BOOL CloseHandle(
  HANDLE hObject
);

Parameters

Parameter Type Description
hObject HANDLE A handle to an open object. This handle must have been created by a Create... function or by a call to the Open... function.

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.

Return Value Description
TRUE The handle was successfully closed.
FALSE The function failed to close the handle. Use GetLastError to get error details.

Remarks

It is important to close handles when you are finished with them to free up system resources. Failure to do so can lead to resource leaks and system instability.

This function can close handles to a wide variety of objects, including:

  • Files (obtained from CreateFile)
  • Processes (obtained from OpenProcess or CreateProcess)
  • Threads (obtained from OpenThread or CreateThread)
  • Directory changes (obtained from FindFirstChangeNotification)
  • Mailslots (obtained from CreateMailslotFile)
  • Pipes (obtained from CreatePipe)
  • Sockets
Note: You must have been granted DELETE access to the object when the handle was created to close it. However, the CloseHandle function does not check for this access right. Instead, the system checks for this access right when the handle is created.
Important: Do not call CloseHandle on the same handle twice. This can lead to undefined behavior, including crashes. Ensure that a handle is valid before attempting to close it.

Example

The following C++ code snippet demonstrates how to open a file, write to it, and then close the handle using CloseHandle.


#include <windows.h>
#include <iostream>

int main() {
    HANDLE hFile = CreateFile(
        L"my_test_file.txt",             // File name
        GENERIC_WRITE,                   // Write access
        0,                               // No sharing
        NULL,                            // Default security attributes
        CREATE_ALWAYS,                   // Overwrite if exists
        FILE_ATTRIBUTE_NORMAL,           // Normal file attributes
        NULL                             // No template file
    );

    if (hFile == INVALID_HANDLE_VALUE) {
        std::cerr << "Error: Could not create file. Error code: " << GetLastError() << std::endl;
        return 1;
    }

    const char* dataToWrite = "This is some sample data.";
    DWORD bytesWritten;

    if (!WriteFile(hFile, dataToWrite, strlen(dataToWrite), &bytesWritten, NULL)) {
        std::cerr << "Error: Could not write to file. Error code: " << GetLastError() << std::endl;
        CloseHandle(hFile); // Close handle even if write fails
        return 1;
    }

    std::cout << "Successfully wrote " << bytesWritten << " bytes to the file." << std::endl;

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

    return 0;
}

See Also

Related Topics