ReadFile 함수(fileapi.h)

지정된 파일 또는 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 플래그로 열리는 핸들이나 소켓 반환된 소켓 핸들이거나 함수를 수락할 있습니다.

[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 매개 변수가 겹치는 유효하고 고유한 구조를 가리킵니다. 그렇지 않으면 함수가 읽기 작업이 완료되었음을 잘못 보고할 수 있습니다.

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

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

반환 값

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

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

발언

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

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

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

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

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

CancelSynchronousIo 사용하여 보류 중인 동기 I/O 작업을 취소합니다.

취소된 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 열린 파일을 성공적으로 사용하기 위한 엄격한 요구 사항이 있습니다. 자세한 내용은 파일 버퍼링참조하세요.

hFileFILE_FLAG_OVERLAPPED사용하여 연 경우 다음 조건이 적용됩니다.

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

동기화 및 파일 위치

hFileFILE_FLAG_OVERLAPPED사용하여 열면 비동기 파일 핸들입니다. 그렇지 않으면 동기식입니다. OVERLAPPED 구조를 사용하는 규칙은 앞에서 설명한 대로 각각에 대해 약간 다릅니다.

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

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

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

• lpOverlapped NULL경우 읽기 작업은 현재 파일 위치에서 시작되고 ReadFile 작업이 완료될 때까지 반환되지 않으며, ReadFile 반환 하기 전에 시스템에서 파일 포인터를 업데이트합니다.
• lpOverlapped NULL않으면 읽기 작업은 OVERLAPPED 구조에 지정된 오프셋에서 시작되고 읽기 작업이 완료될 때까지 ReadFile 반환되지 않습니다. 시스템은 readFile 반환하기 전에 OVERLAPPED 오프셋 및 파일 포인터를 업데이트합니다.
• lpOverlapped NULL경우 동기 읽기 작업이 파일 끝에 도달하면 readFile TRUE 반환하고 0으로 설정합니다.
• 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 함수라는 파이프의 다른 쪽 끝이 0으로 설정됩니다.

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

거래된 작업

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

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

예제

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

요구 사항

참고 항목

CancelIo

CancelIoEx

CancelSynchronousIo

CreateFile

파일 관리 함수

GetCommTimeouts

GetOverlappedResult

GetQueuedCompletionStatus

겹치는

peekNamedPipe

ReadFileEx

SetCommTimeouts

SetErrorMode

WriteFile