ReadFile 함수(fileapi.h)

아티클
03/14/2023

지정된 파일 또는 I/O(입력/출력) 디바이스에서 데이터를 읽습니다. 디바이스에서 파일 포인터를 지원하는 경우 파일 포인터가 지정한 위치에서 읽기가 발생합니다.

이 함수는 동기 및 비동기 작업 모두를 위해 설계되었습니다. 비동기 작업 전용으로 설계된 유사한 함수는 ReadFileEx를 참조하세요.

구문

BOOL ReadFile(
  [in]                HANDLE       hFile,
  [out]               LPVOID       lpBuffer,
  [in]                DWORD        nNumberOfBytesToRead,
  [out, optional]     LPDWORD      lpNumberOfBytesRead,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

매개 변수

[in] hFile

디바이스에 대한 핸들(예: 파일, 파일 스트림, 물리적 디스크, 볼륨, 콘솔 버퍼, 테이프 드라이브, 소켓, 통신 리소스, mailslot 또는 파이프).

hFile 매개 변수는 읽기 액세스 권한으로 만들어졌어야 합니다. 자세한 내용은 일반 액세스 권한 및 파일 보안 및 액세스 권한을 참조하세요.

비동기 읽기 작업의 경우 hFile은 CreateFile 함수에서 FILE_FLAG_OVERLAPPED 플래그로 연 핸들 또는 소켓 또는 accept 함수에서 반환된 소켓 핸들일 수 있습니다.

[out] lpBuffer

파일 또는 디바이스에서 읽은 데이터를 수신하는 버퍼에 대한 포인터입니다.

이 버퍼는 읽기 작업 기간 동안 유효한 상태를 유지해야 합니다. 호출자는 읽기 작업이 완료될 때까지 이 버퍼를 사용하지 않아야 합니다.

[in] nNumberOfBytesToRead

읽을 최대 바이트 수입니다.

[out, optional] lpNumberOfBytesRead

동기 hFile 매개 변수를 사용할 때 읽은 바이트 수를 수신하는 변수에 대한 포인터입니다. ReadFile 은 작업 또는 오류 검사를 수행하기 전에 이 값을 0으로 설정합니다. 잠재적으로 잘못된 결과를 방지하려면 비동기 작업인 경우 이 매개 변수에 NULL 을 사용합니다.

이 매개 변수는 lpOverlapped 매개 변수가 NULL이 아닌 경우에만 NULL일 수 있습니다.

Windows 7: 이 매개 변수는 NULL일 수 없습니다.

자세한 내용은 주의 섹션을 참조하세요.

[in, out, optional] lpOverlapped

hFile 매개 변수가 FILE_FLAG_OVERLAPPED 열린 경우 OVERLAPPED 구조체에 대한 포인터가 필요하고, 그렇지 않으면 NULL일 수 있습니다.

hFile이 FILE_FLAG_OVERLAPPED 사용하여 열리는 경우 lpOverlapped 매개 변수는 유효하고 고유한 OVERLAPPED 구조를 가리킬 수 있어야 합니다. 그렇지 않으면 함수가 읽기 작업이 완료되었음을 잘못 보고할 수 있습니다.

바이트 오프셋을 지원하는 hFile 의 경우 이 매개 변수를 사용하는 경우 파일 또는 디바이스에서 읽기를 시작할 바이트 오프셋을 지정해야 합니다. 이 오프셋은 OVERLAPPED 구조체의 Offset 및 OffsetHigh 멤버를 설정하여 지정됩니다. 바이트 오프셋을 지원하지 않는 hFile 의 경우 Offset 및 OffsetHigh 는 무시됩니다.

lpOverlapped 및 FILE_FLAG_OVERLAPPED 다양한 조합에 대한 자세한 내용은 설명 섹션 및 동기화 및 파일 위치 섹션을 참조하세요.

반환 값

함수가 성공하면 반환 값은 0이 아닌 값(TRUE)입니다.

함수가 실패하거나 비동기적으로 완료되는 경우 반환 값은 0(FALSE)입니다. 확장 오류 정보를 가져오려면 GetLastError 함수를 호출합니다.

참고GetLastError 코드 ERROR_IO_PENDING 오류가 아닙니다. 비동기적으로 완료 보류 중인 읽기 작업을 지정합니다. 자세한 내용은 설명 부분을 참조하세요.

설명

ReadFile 함수는 다음 조건 중 하나가 발생하면 를 반환합니다.

요청된 바이트 수를 읽습니다.
파이프의 쓰기 끝에서 쓰기 작업이 완료됩니다.
비동기 핸들이 사용되고 읽기가 비동기적으로 발생합니다.
오류가 발생합니다.

ReadFile 함수는 미해결 비동기 I/O 요청이 너무 많을 때마다 ERROR_INVALID_USER_BUFFER 또는 ERROR_NOT_ENOUGH_MEMORY 실패할 수 있습니다.

보류 중인 모든 비동기 I/O 작업을 취소하려면 다음 중 하나를 사용합니다.

CancelIo - 이 함수는 지정된 파일 핸들에 대해 호출 스레드에서 실행한 작업만 취소합니다.
CancelIoEx - 이 함수는 지정된 파일 핸들에 대해 스레드에서 실행한 모든 작업을 취소합니다.

보류 중인 동기 I/O 작업을 취소하려면 CancelSynchronousIo를 사용하세요.

취소된 I/O 작업은 오류 ERROR_OPERATION_ABORTED 완료됩니다.

ReadFile 함수는 ERROR_NOT_ENOUGH_QUOTA 실패할 수 있습니다. 즉, 호출 프로세스의 버퍼를 페이지로 잠글 수 없습니다. 자세한 내용은 SetProcessWorkingSetSize를 참조하세요.

파일의 일부가 다른 프로세스에 의해 잠겨 있고 읽기 작업이 잠긴 부분과 겹치면 이 함수가 실패합니다.

읽기 작업이 버퍼를 사용하는 동안 입력 버퍼에 액세스하면 해당 버퍼로 읽은 데이터가 손상될 수 있습니다. 애플리케이션은 읽기 작업이 완료될 때까지 읽기 작업에서 사용하는 입력 버퍼를 읽거나, 쓰거나, 재할당하거나, 해제해서는 안 됩니다. 비동기 파일 핸들을 사용하는 경우 특히 문제가 될 수 있습니다. 동기 및 비동기 파일 핸들에 대한 추가 정보는 동기화 및 파일 위치 섹션 및 CreateFile 참조 항목에서 찾을 수 있습니다.

콘솔 입력에 대한 핸들이 있는 ReadFile 을 사용하여 콘솔 입력 버퍼에서 문자를 읽을 수 있습니다. 콘솔 모드는 ReadFile 함수의 정확한 동작을 결정합니다. 기본적으로 콘솔 모드는 ENABLE_LINE_INPUT. 이는 ReadFile 이 캐리지 리턴에 도달할 때까지 읽어야 했음을 나타냅니다. Ctrl+C를 누르면 호출이 성공하지만 GetLastError 는 ERROR_OPERATION_ABORTED 반환합니다. 자세한 내용은 CreateFile을 참조하세요.

통신 디바이스에서 읽을 때 ReadFile의 동작은 SetCommTimeouts 및 GetCommTimeouts 함수를 사용하여 설정된 현재 통신 시간 제한에 따라 결정되고 검색됩니다. 시간 제한 값을 설정하지 못하면 예측할 수 없는 결과가 발생할 수 있습니다. 통신 시간 제한에 대한 자세한 내용은 COMMTIMEOUTS를 참조하세요.

ReadFile이 너무 작은 버퍼가 있는 mailslot에서 읽으려고 하면 함수는 FALSE를 반환하고 GetLastError는 ERROR_INSUFFICIENT_BUFFER 반환합니다.

FILE_FLAG_NO_BUFFERING 플래그를 사용하여 CreateFile에서 열린 파일을 성공적으로 사용하기 위한 엄격한 요구 사항이 있습니다. 자세한 내용은 파일 버퍼링을 참조하세요.

hFile이 FILE_FLAG_OVERLAPPED 열린 경우 다음 조건이 적용됩니다.

lpOverlapped 매개 변수는 유효하고 고유한 OVERLAPPED 구조를 가리킵니다. 그렇지 않으면 함수가 읽기 작업이 완료되었음을 잘못 보고할 수 있습니다.
lpNumberOfBytesRead 매개 변수를 NULL로 설정해야 합니다. GetOverlappedResult 함수를 사용하여 실제 읽은 바이트 수를 가져옵니다. hFile 매개 변수가 I/O 완료 포트와 연결된 경우 GetQueuedCompletionStatus 함수를 호출하여 읽은 바이트 수를 가져올 수도 있습니다.

동기화 및 파일 위치

hFile이 FILE_FLAG_OVERLAPPED 열린 경우 비동기 파일 핸들입니다. 그렇지 않으면 동기식입니다. OVERLAPPED 구조를 사용하는 규칙은 앞에서 설명한 것처럼 각각에 대해 약간 다릅니다.

참고 비동기 I/O를 위해 파일 또는 디바이스를 연 경우 해당 핸들을 사용하는 ReadFile 과 같은 함수에 대한 후속 호출은 일반적으로 즉시 반환되지만 차단된 실행과 관련하여 동기적으로 동작할 수도 있습니다. 자세한 내용은 http://support.microsoft.com/kb/156932를 참조하세요.

비동기 파일 핸들 작업에 대한 고려 사항:

읽기 작업이 완료되기 전에 ReadFile이 반환할 수 있습니다. 이 시나리오에서 ReadFile 은 FALSE 를 반환하고 GetLastError 함수는 ERROR_IO_PENDING 반환하므로 시스템이 읽기 작업을 완료하는 동안 호출 프로세스를 계속할 수 있습니다.
lpOverlapped 매개 변수는 NULL이 아니어야 하며 다음 팩트를 염두에 두고 사용해야 합니다.
- OVERLAPPED 구조에 지정된 이벤트가 시스템에 의해 자동으로 설정되고 다시 설정되지만 OVERLAPPED 구조에 지정된 오프셋은 자동으로 업데이트되지 않습니다.
- ReadFile 은 I/O 작업을 시작할 때 이벤트를 서명되지 않은 상태로 다시 설정합니다.
- OVERLAPPED 구조에 지정된 이벤트는 읽기 작업이 완료되면 신호 상태로 설정됩니다. 그 때까지 읽기 작업은 보류 중인 것으로 간주됩니다.
- 읽기 작업은 OVERLAPPED 구조에 지정된 오프셋에서 시작되고 시스템 수준 읽기 작업이 완료되기 전에 ReadFile 이 반환될 수 있으므로(읽기 보류 중) 오프셋이나 구조체의 다른 부분은 이벤트가 신호를 받을 때까지 애플리케이션에서 수정, 해제 또는 재사용해서는 안 됩니다(즉 읽기가 완료됨).
- 비동기 작업 중에 EOF(파일 끝)가 검색되면 해당 작업에 대한 GetOverlappedResult 호출은 FALSE 를 반환하고 GetLastError 는 ERROR_HANDLE_EOF 반환합니다.

동기 파일 핸들 작업에 대한 고려 사항:

lpOverlapped가 NULL이면 현재 파일 위치에서 읽기 작업이 시작되고 작업이 완료될 때까지 ReadFile이 반환되지 않으며 ReadFile이 반환되기 전에 시스템에서 파일 포인터를 업데이트합니다.
lpOverlapped가 NULL이 아닌 경우 읽기 작업은 OVERLAPPED 구조에 지정된 오프셋에서 시작되고 읽기 작업이 완료될 때까지 ReadFile이 반환되지 않습니다. 시스템은 READFile이 반환되기 전에 OVERLAPPED 오프셋 및 파일 포인터를 업데이트합니다.
lpOverlapped가 NULL이면 동기 읽기 작업이 파일의 끝에 도달하면 ReadFile은 TRUE를 반환하고 를 0으로 설정합니다*lpNumberOfBytesRead.
lpOverlapped이 NULL이 아닌 경우 동기 읽기 작업이 파일의 끝에 도달하면 ReadFile은 FALSE를 반환하고 GetLastError는 ERROR_HANDLE_EOF 반환합니다.

자세한 내용은 CreateFile 및 동기 및 비동기 I/O를 참조하세요.

파이프

익명 파이프를 사용하고 쓰기 핸들이 닫힌 경우 ReadFile 이 파이프의 해당 읽기 핸들을 사용하여 읽으려고 하면 함수는 FALSE 를 반환하고 GetLastError 는 ERROR_BROKEN_PIPE 반환합니다.

명명된 파이프가 메시지 모드에서 읽혀지고 다음 메시지가 nNumberOfBytesToRead 매개 변수가 지정한 것보다 긴 경우 ReadFile 은 FALSE 를 반환하고 GetLastError 는 ERROR_MORE_DATA 반환합니다. 메시지의 나머지 부분을 ReadFile 또는 PeekNamedPipe 함수에 대한 후속 호출을 통해 읽을 수 있습니다.

ReadFile이 파이프에서 TRUE를 반환할 때 lpNumberOfBytesRead 매개 변수가 0이면 파이프의 다른 쪽 끝은 nNumberOfBytesToWrite가 0으로 설정된 WriteFile 함수라고 합니다.

파이프에 대한 자세한 내용은 파이프를 참조하세요.

거래된 작업

파일 핸들에 바인딩된 트랜잭션이 있는 경우 함수는 파일의 트랜잭션된 뷰에서 데이터를 반환합니다. 트랜잭션된 읽기 핸들은 핸들이 지속되는 동안 파일의 동일한 뷰를 표시하도록 보장됩니다. 자세한 내용은 트랜잭션 NTFS 정보를 참조하세요.

Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.

기술	지원됨
SMB(서버 메시지 블록) 3.0 프로토콜	Yes
SMB 3.0 TFO(투명 장애 조치(failover))	Yes
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0	Yes
CsvFS(클러스터 공유 볼륨 파일 시스템)	Yes
ReFS(Resilient File System)	예

예제

파일의 끝을 테스트하는 방법을 보여 주는 코드 예제는 파일 의 끝에 대한 테스트를 참조하세요. 다른 예제는 임시 파일 만들기 및 사용 및 읽기 또는 쓰기를 위한 파일 열기를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows XP [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2003 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	fileapi.h(Windows.h 포함)
라이브러리	Kernel32.lib
DLL	Kernel32.dll