WinAPI 파일 입출력 기본 가이드, CreateFile부터 CloseHandle까지 완벽 정리

🔗 CreateFile로 파일 열기와 생성

Windows API에서 CreateFile 함수는 이름과 달리 단순히 ‘파일 생성’ 기능만 제공하는 것이 아닙니다.
이미 존재하는 파일을 열거나, 새로운 파일을 만들고, 심지어 디렉터리·디바이스 핸들까지 얻을 수 있는 범용적인 입출력 시작점입니다.
이 함수의 사용 방법을 이해하면 WinAPI 기반의 모든 파일 작업의 기초를 다질 수 있습니다.

기본적인 함수 원형은 다음과 같습니다.

HANDLE CreateFile(
    LPCSTR lpFileName,
    DWORD dwDesiredAccess,
    DWORD dwShareMode,
    LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    DWORD dwCreationDisposition,
    DWORD dwFlagsAndAttributes,
    HANDLE hTemplateFile
);

🛠️ 주요 매개변수 이해하기

• 📄lpFileName : 열거나 생성할 파일 경로
• 🔑dwDesiredAccess : GENERIC_READ, GENERIC_WRITE 등 접근 권한 지정
• 🤝dwShareMode : 다른 프로세스와의 공유 모드
• ⚙️dwCreationDisposition : 파일이 없을 때 새로 만들지 여부(CREATE_ALWAYS 등)
• 📦dwFlagsAndAttributes : FILE_ATTRIBUTE_NORMAL 등 속성 설정

💡 사용 예시

HANDLE hFile = CreateFile(
    "sample.txt",
    GENERIC_WRITE,
    0,
    NULL,
    CREATE_ALWAYS,
    FILE_ATTRIBUTE_NORMAL,
    NULL
);

if (hFile == INVALID_HANDLE_VALUE) {
    // 오류 처리
}

🛠️ ReadFile로 데이터 읽기

WinAPI의 ReadFile은 텍스트와 바이너리 모두에 동일하게 적용되는 저수준 읽기 함수입니다.
핵심은 읽은 바이트 수를 항상 확인하고, 반복 호출로 원하는 길이가 채워질 때까지 읽는 습관을 들이는 것입니다.
파일 끝에서는 성공 반환과 함께 읽은 바이트 수가 0이거나, 상황에 따라 ERROR_HANDLE_EOF를 만날 수 있습니다.
콘솔·파이프 등 커널 객체에서도 동일 패턴으로 동작하므로, 견고한 루프와 오류 처리가 중요합니다.

📚 함수 원형과 기본 사용

BOOL ReadFile(
    HANDLE       hFile,
    LPVOID       lpBuffer,
    DWORD        nNumberOfBytesToRead,
    LPDWORD      lpNumberOfBytesRead,
    LPOVERLAPPED lpOverlapped
);

일반적인 동기 모드에서는 lpOverlapped를 NULL로 두고 호출하며, 반환값과 lpNumberOfBytesRead를 함께 확인합니다.
텍스트 파일이라도 멀티바이트/유니코드 변환은 개발자가 직접 처리해야 하므로, WideCharToMultiByte나 MultiByteToWideChar로 인코딩을 명확히 관리하세요.

🧩 안전한 읽기 루프 예제 (동기)

char  buf[4096];
DWORD total = 0;

for (;;) {
    DWORD got = 0;
    BOOL ok = ReadFile(hFile, buf, sizeof(buf), &got, NULL);
    if (!ok) {
        DWORD err = GetLastError();
        // 필요한 경우 ERROR_HANDLE_EOF 등 처리
        break;
    }
    if (got == 0) { // EOF
        break;
    }
    // got 바이트 사용 (텍스트면 인코딩 고려)
    total += got;
}

⚡ 오버랩 I/O 한눈에 보기

비차단 입출력이 필요하면 CreateFile 호출 시 FILE_FLAG_OVERLAPPED를 설정하고, OVERLAPPED 구조체를 넘겨 호출합니다.
이때 함수는 FALSE를 반환하고 GetLastError()==ERROR_IO_PENDING이면 정상이며, GetOverlappedResult나 이벤트 객체로 완료를 추적합니다.
파일 위치는 OVERLAPPED.Offset/OffsetHigh로 지정합니다.

OVERLAPPED ol = {0};
ol.Offset = 0; ol.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

BOOL ok = ReadFile(hFile, buf, sizeof(buf), NULL, &ol);
if (!ok && GetLastError() == ERROR_IO_PENDING) {
    // 대기 또는 폴링
    WaitForSingleObject(ol.hEvent, INFINITE);
    DWORD got = 0;
    GetOverlappedResult(hFile, &ol, &got, FALSE);
}
CloseHandle(ol.hEvent);

⚙️ WriteFile로 데이터 쓰기

WinAPI의 WriteFile은 텍스트든 바이너리든 동일한 바이트 스트림을 대상으로 동작합니다.
핵심은 실제로 기록된 바이트 수를 항상 확인하고, 필요 시 반복 호출로 전체 데이터를 끝까지 밀어넣는 것입니다.
디스크 캐시와 파일 시스템 드라이버의 특성 때문에 한 번의 호출이 요청한 길이를 모두 처리하지 못할 수 있으므로, 견고한 루프 패턴을 익히면 신뢰도가 크게 올라갑니다.
또한 파일을 ‘어디에’ 쓰는지도 중요합니다.
동기 모드에서는 파일 포인터가 자동으로 이동하지만, 오버랩 I/O에서는 OVERLAPPED.Offset/OffsetHigh로 위치를 명시해야 예기치 않은 덮어쓰기를 방지할 수 있습니다.

✍️ 함수 원형과 기본 사용

BOOL WriteFile(
    HANDLE       hFile,
    LPCVOID      lpBuffer,
    DWORD        nNumberOfBytesToWrite,
    LPDWORD      lpNumberOfBytesWritten,
    LPOVERLAPPED lpOverlapped
);

동기 모드에서는 lpOverlapped를 NULL로 두고 호출합니다.
반환값이 TRUE라면 실제로 기록된 길이는 lpNumberOfBytesWritten에서 확인합니다.
오류 시 GetLastError()로 원인을 파악하고, 디스크 공간 부족, 접근 권한, 공유 모드 충돌 등의 케이스를 구분해 대처합니다.

🔁 안전한 쓰기 루프 예제 (동기)

const BYTE* p   = (const BYTE*)buffer;   // 쓰고자 하는 메모리
DWORD       len = (DWORD)bufferSize;     // 총 길이
DWORD       done = 0;

while (done < len) {
    DWORD wrote = 0;
    BOOL ok = WriteFile(hFile, p + done, len - done, &wrote, NULL);
    if (!ok) {
        DWORD err = GetLastError();
        // 오류 처리 (공간 부족, 권한, 공유 충돌 등)
        break;
    }
    if (wrote == 0) { // 비정상 상황: 더 이상 진행 불가
        // 적절한 복구/로그 처리
        break;
    }
    done += wrote;
}

⚡ 오버랩 I/O로 비차단 쓰기

파일을 CreateFile에서 FILE_FLAG_OVERLAPPED로 열었으면, WriteFile 호출 때 OVERLAPPED를 제공해야 합니다.
호출은 FALSE를 반환하고 GetLastError()==ERROR_IO_PENDING이면 정상입니다.
완료는 이벤트 핸들이나 GetOverlappedResult로 확인하며, 위치 지정은 Offset/OffsetHigh를 사용합니다.

OVERLAPPED ol = {0};
ol.Offset = 0;                     // 원하는 파일 위치
ol.hEvent = CreateEvent(NULL, TRUE, FALSE, NULL);

BOOL ok = WriteFile(hFile, p, len, NULL, &ol);
if (!ok && GetLastError() == ERROR_IO_PENDING) {
    WaitForSingleObject(ol.hEvent, INFINITE);
    DWORD wrote = 0;
    GetOverlappedResult(hFile, &ol, &wrote, FALSE);
}
CloseHandle(ol.hEvent);

• 🧾lpNumberOfBytesWritten을 반드시 확인해 부분 기록을 처리하세요.
• 🧭오버랩 모드에서는 Offset을 명시하고, 동기/비동기 방식을 섞지 마세요.
• 💽디스크에 즉시 반영하려면 FlushFileBuffers를 고려하세요.
• 🧱기존 파일을 덮어쓸 때는 백업 파일을 먼저 만들고 쓰는 안전한 저장(atomic-like) 패턴을 사용하면 좋습니다.

🔌 CloseHandle로 파일 닫기

파일 작업의 마지막 단계는 핸들을 정리하는 일입니다.
CloseHandle은 커널 오브젝트의 참조 카운트를 줄이고, 더 이상 참조가 없으면 시스템 리소스를 해제합니다.
파일 핸들을 닫으면 캐시에 남아 있던 기록이 파일 시스템으로 커밋되고, 공유 락이 풀리며, 다른 프로세스가 접근할 수 있게 됩니다.
작은 도구라면 종료 시 운영체제가 정리해 주기도 하지만, 서비스·장시간 실행 애플리케이션에서는 누적 누수로 이어지므로 명시적으로 닫는 습관이 필수입니다.

📚 함수 원형과 반환 값

BOOL CloseHandle(
    HANDLE hObject
);

성공 시 TRUE, 실패 시 FALSE를 반환하며, 오류 코드는 GetLastError()로 확인합니다.
파일 오브젝트 외에도 이벤트, 뮤텍스, 파이프 등 다양한 커널 오브젝트에 사용되지만, 오브젝트 종류가 다르면 정리 방식도 달라질 수 있으므로 문서를 확인하세요.

✅ 안전한 정리 패턴

HANDLE hFile = CreateFile(...);
if (hFile == INVALID_HANDLE_VALUE) {
    // 오류 처리
    return;
}

// 파일 작업...
// 필요 시 FlushFileBuffers(hFile);

if (hFile && hFile != INVALID_HANDLE_VALUE) {
    BOOL ok = CloseHandle(hFile);
    if (!ok) {
        DWORD err = GetLastError();
        // 로깅/복구
    }
}

⚠️ 흔한 실수와 예방책

• 🔁같은 핸들을 중복으로 닫지 마세요.
  한 번 닫힌 핸들을 다시 닫으면 ERROR_INVALID_HANDLE이 발생할 수 있습니다.
• ⏳오버랩 I/O가 진행 중이라면 CancelIoEx로 취소하고, GetOverlappedResult 또는 이벤트 대기로 완료를 확인한 뒤 닫습니다.
• 🧰GetCurrentProcess/GetCurrentThread의 의사 핸들은 별도 해제가 필요 없습니다.
  실제 복제 핸들은 DuplicateHandle로 만든 경우에만 닫으세요.
• 🧹여러 코드 경로(중간 return, 오류 처리)가 있으면 goto cleanup 또는 __try/__finally로 정리 구역을 통일해 누수를 방지하세요.

💡 파일 입출력 시 주의사항과 팁

WinAPI로 파일을 다룰 때는 단순히 열고 읽고 쓰는 것을 넘어서, 경로 길이, 잠금 공유, 버퍼링 정책, 인코딩, 장애 복구 전략 등 주변 요소를 함께 설계해야 예측 가능한 동작을 얻을 수 있습니다.
현장에서 자주 마주치는 문제를 기준으로 체크리스트와 예제로 정리했습니다.
텍스트·바이너리 모두에 적용되며, 동기·오버랩 I/O 어디서든 도움이 됩니다.

• 🔗긴 경로는 접두사 \\?\를 써서 MAX_PATH 한계를 우회하세요.
• 🤝동시 접근이 필요하면 dwShareMode에 FILE_SHARE_READ/WRITE를 적절히 부여하세요.
• 🧾텍스트는 인코딩을 명확히: UTF-8 BOM, UTF-16LE 등 정책을 정하고 읽기/쓰기 모두 동일하게 유지하세요.
• 💽전원 장애 대비가 필요하면 FlushFileBuffers 또는 MOVEFILE_WRITE_THROUGH와 같은 옵션을 고려하세요.
• 🧱덮어쓰기 저장은 임시 파일 → 원본 교체의 원자적 저장 패턴을 쓰면 안전합니다.
• 🧪I/O 실패 시 GetLastError 코드를 로깅하고, 재시도·롤백 루틴을 준비하세요.

🧩 원자적(안전) 저장 패턴 예제

// temp에 완성본을 쓴 뒤 MoveFileEx로 교체
HANDLE h = CreateFile(L"data.tmp",
    GENERIC_WRITE, 0, NULL, CREATE_ALWAYS,
    FILE_ATTRIBUTE_NORMAL, NULL);

if (h == INVALID_HANDLE_VALUE) { /* 오류 처리 */ }

// ... 모든 데이터 기록 ...
FlushFileBuffers(h);
CloseHandle(h);

// 교체: 쓰루 옵션으로 디스크 반영 보장 강화
BOOL ok = MoveFileExW(L"data.tmp", L"data.txt",
    MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH);

if (!ok) { /* 롤백/오류 처리 */ }

📏 파일 포인터와 크기 관리

랜덤 액세스 시에는 SetFilePointerEx로 위치를 이동하고, 파일을 잘라내거나 늘릴 때는 SetEndOfFile을 사용합니다.
읽기/쓰기 혼용 시 파일 포인터가 어디에 위치하는지 항상 의식하고, 멀티스레드 환경에서는 스레드별 핸들 또는 뮤텍스로 순서를 제어하세요.

🧰 오류 메시지 로깅 템플릿

DWORD err = GetLastError();
LPWSTR msg = NULL;
FormatMessageW(FORMAT_MESSAGE_ALLOCATE_BUFFER |
               FORMAT_MESSAGE_FROM_SYSTEM |
               FORMAT_MESSAGE_IGNORE_INSERTS,
               NULL, err, 0, (LPWSTR)&msg, 0, NULL);
// msg 로깅...
if (msg) LocalFree(msg);

💬 문제 상황을 재현할 수 있는 입력, 경로, 접근 권한, 공유 모드, 플래그를 로그에 함께 남기면 다음 디버깅 시간이 크게 줄어듭니다.

❓ 자주 묻는 질문 (FAQ)