NtReadFile 함수
열려 있는 파일에서 데이터를 읽습니다.
이 함수는 WDK(Windows 드라이버 키트)에 설명된 ZwReadFile 함수와 동일한 사용자 모드입니다.
구문
NTSTATUS NtReadFile(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE Event,
_In_opt_ PIO_APC_ROUTINE ApcRoutine,
_In_opt_ PVOID ApcContext,
_Out_ PIO_STATUS_BLOCK IoStatusBlock,
_Out_ PVOID Buffer,
_In_ ULONG Length,
_In_opt_ PLARGE_INTEGER ByteOffset,
_In_opt_ PULONG Key
);
매개 변수
-
FileHandle [in]
-
파일 개체에 대한 핸들입니다. 이 핸들은 NtCreateFile 또는 NtOpenFile 을 성공적으로 호출하여 만듭니 다.
-
이벤트 [in, 선택 사항]
-
필요에 따라 읽기 작업이 완료된 후 신호 상태로 설정할 이벤트 개체에 대한 핸들입니다. 디바이스 및 중간 드라이버는 이 매개 변수를 NULL로 설정해야 합니다.
-
ApcRoutine [in, optional]
-
이 매개 변수는 예약되어 있습니다. 디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
-
ApcContext [in, optional]
-
이 매개 변수는 예약되어 있습니다. 디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
-
IoStatusBlock [out]
-
최종 완성 상태 수신하는 IO_STATUS_BLOCK 구조체 및 요청된 읽기 작업에 대한 정보를 가리키는 포인터입니다. 정보 멤버는 파일에서 실제로 읽은 바이트 수를 받습니다.
-
버퍼 [out]
-
파일에서 읽은 데이터를 수신하는 호출자가 할당한 버퍼에 대한 포인터입니다.
-
길이 [in]
-
Buffer가 가리키는 버퍼의 크기(바이트) 입니다.
-
ByteOffset [in, optional]
-
읽기 작업이 시작될 파일의 시작 바이트 오프셋을 지정하는 변수에 대한 포인터입니다. 파일의 끝을 넘어 읽으려고 하면 NtReadFile 에서 오류가 반환됩니다.
NtCreateFile에 대한 호출이 FILE_SYNCHRONOUS_IO_ALERT 또는 FILE_SYNCHRONOUS_IO_NONALERT CreateOptions 플래그 중 하나를 설정하는 경우 I/O 관리자는 현재 파일 위치를 유지합니다. 이 경우 NtReadFile 의 호출자는 명시적 ByteOffset 값 대신 현재 파일 위치 오프셋을 사용할 수 있도록 지정할 수 있습니다. 이 사양은 다음 방법 중 하나를 사용하여 만들 수 있습니다.
HighPart멤버가 -1로 설정되고 LowPart 멤버가 시스템 정의 값 FILE_USE_FILE_POINTER_POSITION 설정된 LARGE_INTEGER 값에 대한 포인터를 지정합니다.
ByteOffset에 대한 NULL 포인터를 전달합니다.
NtReadFile 은 I/O 관리자가 유지 관리하는 현재 파일 위치를 사용하는 경우 읽기 작업을 완료할 때 읽은 바이트 수를 추가하여 현재 파일 위치를 업데이트합니다.
I/O 관리자가 현재 파일 위치를 유지 관리하는 경우에도 호출자는 명시적 ByteOffset 값을 NtReadFile에 전달하여 이 위치를 다시 설정할 수 있습니다. 이렇게 하면 현재 파일 위치가 해당 ByteOffset 값으로 자동으로 변경되고 읽기 작업이 수행된 다음 실제로 읽은 바이트 수에 따라 위치가 업데이트됩니다. 이 기술은 호출자에게 원자성 검색 및 읽기 서비스를 제공합니다.
-
키 [in, 선택 사항]
-
디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
반환 값
NtReadFile 은 STATUS_SUCCESS 또는 적절한 NTSTATUS 오류 코드를 반환합니다.
설명
NtReadFile의 호출자는 DesiredAccess 매개 변수에 설정된 FILE_READ_DATA 또는 GENERIC_READ 값을 사용하여 NtCreateFile을 이미 호출해야 합니다.
NtCreateFile에 대한 이전 호출에서 CreateOptions 매개 변수의 FILE_NO_INTERMEDIATE_BUFFERING 플래그를 NtCreateFile로 설정한 경우 Length 및 ByteOffset 매개 변수는 섹터 크기의 배수여야 합니다. 자세한 내용은 NtCreateFile을 참조하세요.
NtReadFile 은 지정된 ByteOffset 또는 현재 파일 위치에서 지정된 버퍼로 읽기 시작합니다. 다음 조건 중 하나에서 읽기 작업을 종료합니다.
Length 매개 변수에 지정된 바이트 수를 읽었기 때문에 버퍼가 가득 찼습니다. 따라서 오버플로 없이는 더 이상 데이터를 버퍼에 배치할 수 없습니다.
읽기 작업 중에 파일의 끝에 도달하므로 버퍼로 전송할 파일에 더 이상 데이터가 없습니다.
호출자가 DesiredAccess에 설정된 SYNCHRONIZE 플래그를 사용하여 파일을 연 경우 호출 스레드는 파일 핸들 FileHandle을 대기하여 읽기 작업의 완료와 동기화할 수 있습니다. 핸들에서 실행된 I/O 작업이 완료될 때마다 핸들에 신호가 전송됩니다. 그러나 호출자는 동기 파일 액세스(FILE_SYNCHRONOUS_IO_NONALERT 또는 FILE_SYNCHRONOUS_IO_ALERT)를 위해 열린 핸들을 기다리면 안 됩니다. 이 경우 NtReadFile 은 호출자를 대신하여 대기하고 읽기 작업이 완료될 때까지 반환되지 않습니다. 호출자는 다음 세 가지 조건이 모두 충족되는 경우에만 파일 핸들을 안전하게 기다릴 수 있습니다.
비동기 액세스를 위해 핸들이 열렸습니다(즉, FILE_SYNCHRONOUS_IO_XXX 플래그가 지정되지 않음).
핸들은 한 번에 하나의 I/O 작업에만 사용됩니다.
NtReadFile은 STATUS_PENDING 반환했습니다.
드라이버는 다음 조건 중 하나라도 있는 경우 시스템 프로세스의 컨텍스트에서 NtReadFile 을 호출해야 합니다.
드라이버가 NtReadFile에 전달하는 파일 핸들을 만들었습니다.
NtReadFile 은 드라이버가 만든 이벤트를 통해 드라이버에 I/O 완료를 알립니다.
NtReadFile 은 드라이버가 NtReadFile에 전달하는 APC 콜백 루틴을 통해 드라이버에 I/O 완료를 알립니다.
파일 및 이벤트 핸들은 핸들이 만들어지는 프로세스 컨텍스트에서만 유효합니다. 따라서 보안 허점을 방지하려면 드라이버가 있는 프로세스의 컨텍스트가 아닌 시스템 프로세스의 컨텍스트에서 NtReadFile 에 전달하는 파일 또는 이벤트 핸들을 만들어야 합니다.
마찬가지로 APC 는 I/O 요청을 실행하는 스레드의 컨텍스트에서 항상 발생하므로 APC를 통해 I/O 완성을 드라이버에 알립니다. 드라이버가 시스템 1 이외의 프로세스 컨텍스트에서 NtReadFile 을 호출하는 경우 APC가 무기한 지연되거나 전혀 실행되지 않을 수 있습니다.
파일 작업에 대한 자세한 내용은 드라이버에서 파일 사용을 참조하세요.
NtReadFile의 호출자는 IRQL = PASSIVE_LEVEL 및 특수 커널 APC를 사용하도록 설정된 상태에서 실행되어야 합니다.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 |
Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 |
Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 |
|
| 헤더 |
|
| 라이브러리 |
|
| DLL |
|
추가 정보