NtWriteFile 함수(ntifs.h)
ZwWriteFile 루틴은 열려 있는 파일에 데이터를 씁니다.
구문
__kernel_entry NTSYSCALLAPI NTSTATUS NtWriteFile(
[in] HANDLE FileHandle,
[in, optional] HANDLE Event,
[in, optional] PIO_APC_ROUTINE ApcRoutine,
[in, optional] PVOID ApcContext,
[out] PIO_STATUS_BLOCK IoStatusBlock,
[in] PVOID Buffer,
[in] ULONG Length,
[in, optional] PLARGE_INTEGER ByteOffset,
[in, optional] PULONG Key
);
매개 변수
[in] FileHandle
파일 개체에 대한 핸들입니다. 이 핸들은 NtCreateFile 또는 NtOpenFile 을 성공적으로 호출하여 만듭니 다.
[in, optional] Event
필요에 따라 쓰기 작업이 완료된 후 신호 상태로 설정할 이벤트 개체에 대한 핸들입니다. 디바이스 및 중간 드라이버는 이 매개 변수를 NULL로 설정해야 합니다.
[in, optional] ApcRoutine
이 매개 변수는 예약되어 있습니다. 디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
[in, optional] ApcContext
이 매개 변수는 예약되어 있습니다. 디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
[out] IoStatusBlock
최종 완료 상태 수신하는 IO_STATUS_BLOCK 구조체 및 요청된 쓰기 작업에 대한 정보를 가리키는 포인터입니다. 정보 멤버는 파일에 실제로 기록된 바이트 수를 받습니다.
[in] Buffer
파일에 쓸 데이터를 포함하는 호출자가 할당한 버퍼에 대한 포인터입니다.
[in] Length
Buffer가 가리키는 버퍼의 크기(바이트) 입니다.
[in, optional] ByteOffset
쓰기 작업을 시작하기 위해 파일의 시작 바이트 오프셋을 지정하는 변수에 대한 포인터입니다. Length 및 ByteOffset이 현재 파일 끝 표시를 지나 쓰기 작업을 지정하는 경우 NtWriteFile은 자동으로 파일을 확장하고 파일 끝 표시를 업데이트합니다. 이러한 이전 및 새 파일 끝 표시 사이에 명시적으로 기록되지 않은 바이트는 0으로 정의됩니다.
NtCreateFile에 대한 호출이 DesiredAccess 플래그만 FILE_APPEND_DATA 설정하면 ByteOffset은 무시됩니다. 지정된 버퍼의 데이터( 길이 바이트)는 현재 파일 끝에서부터 기록됩니다.
NtCreateFile에 대한 호출이 FILE_SYNCHRONOUS_IO_ALERT 또는 FILE_SYNCHRONOUS_IO_NONALERT CreateOptions 플래그 중 하나를 설정하는 경우 I/O 관리자는 현재 파일 위치를 유지합니다. 이 경우 NtWriteFile 의 호출자는 명시적 ByteOffset 값 대신 현재 파일 위치 오프셋을 사용할 수 있도록 지정할 수 있습니다. 이 사양은 다음 방법 중 하나를 사용하여 만들 수 있습니다.
- * HighPart 멤버가 -1로 설정되고 LowPart 멤버가 시스템 정의 값으로 설정된 LARGE_INTEGER 값에 대한 포인터를 FILE_USE_FILE_POINTER_POSITION.
- ByteOffset에 대한 NULL 포인터를 전달합니다.
NtWriteFile 은 I/O 관리자가 유지 관리하는 현재 파일 위치를 사용하는 경우 쓰기 작업을 완료할 때 작성된 바이트 수를 추가하여 현재 파일 위치를 업데이트합니다.
I/O 관리자가 현재 파일 위치를 유지 관리하는 경우에도 호출자는 명시적 ByteOffset 값을 NtWriteFile에 전달하여 이 위치를 다시 설정할 수 있습니다. 이렇게 하면 현재 파일 위치가 해당 ByteOffset값으로 자동으로 변경되고 쓰기 작업이 수행된 다음 실제로 작성된 바이트 수에 따라 위치가 업데이트됩니다. 이 기술은 호출자에게 원자성 검색 및 쓰기 서비스를 제공합니다.
또한 HighPart가 -1로 설정되고 LowPart가 FILE_WRITE_TO_END_OF_FILE 설정된 LARGE_INTEGER 값에 대한 포인터를 ByteOffset에 지정하여 파일의 현재 끝에서 쓰기 작업을 시작할 수도 있습니다. 이는 I/O 관리자가 현재 파일 위치를 유지하고 있는지 여부에 관계없이 작동합니다.
[in, optional] Key
디바이스 및 중간 드라이버는 이 포인터를 NULL로 설정해야 합니다.
반환 값
NtWriteFile 은 성공 시 STATUS_SUCCESS 반환하거나 실패 시 적절한 NTSTATUS 오류 코드를 반환합니다.
설명
NtWriteFile의 호출자는 DesiredAccess 매개 변수에 설정된 FILE_WRITE_DATA, FILE_APPEND_DATA 또는 GENERIC_WRITE 플래그를 사용하여 NtCreateFile을 이미 호출해야 합니다. 파일에 대한 FILE_APPEND_DATA 액세스만 있으면 호출자가 현재 파일 끝 표시를 제외한 파일의 아무 곳이나 쓸 수 없으며, 파일에 대한 FILE_WRITE_DATA 액세스 권한이 있어도 호출자가 파일의 끝부분 또는 그 너머에 쓰는 것을 배제하지는 않습니다.
NtCreateFile에 대한 이전 호출에서 CreateOptions 플래그를 FILE_NO_INTERMEDIATE_BUFFERING 설정하는 경우 Length 및 ByteOffset 매개 변수는 섹터 크기의 정수여야 합니다. 자세한 내용은 NtCreateFile을 참조하세요.
NtWriteFile 은 ByteOffset, 현재 파일 위치 또는 파일 끝 표시에서 파일에 대한 쓰기 작업을 시작합니다. 버퍼에서 Length 바이트를 작성하면 쓰기 작업이 종료됩니다. 필요한 경우 파일의 길이를 확장하고 파일 끝 표시를 다시 설정합니다.
호출자가 DesiredAccess SYNCHRONIZE 플래그가 설정된 파일을 연 경우 호출자는 이 루틴이 지정된 FileHandle 을 신호 상태로 설정할 때까지 기다릴 수 있습니다.
드라이버는 시스템 프로세스의 컨텍스트에서 다음 세 가지 경우에 NtWriteFile 을 호출해야 합니다.
- 드라이버는 NtWriteFile에 전달하는 파일 핸들을 만듭니다.
- NtWriteFile 은 드라이버에서 만든 이벤트를 통해 I/O 완성을 드라이버에 알릴 수 있습니다.
- NtWriteFile 은 드라이버가 NtWriteFile에 전달하는 APC 콜백 루틴을 통해 I/O 완성을 드라이버에 알릴 수 있습니다.
파일 및 이벤트 핸들은 핸들이 만들어지는 프로세스 컨텍스트에서만 유효합니다. 따라서 보안 허점을 방지하기 위해 드라이버는 드라이버가 있는 프로세스 컨텍스트 대신 시스템 프로세스의 컨텍스트에서 NtWriteFile 에 전달하는 파일 또는 이벤트 핸들을 만들어야 합니다.
마찬가지로 APC는 I/O 요청을 실행하는 스레드의 컨텍스트에서 항상 발생하므로 APC를 통해 I/O 완료를 드라이버에 알릴 경우 시스템 프로세스의 컨텍스트에서 NtWriteFile 을 호출해야 합니다. 드라이버가 시스템 프로세스 이외의 프로세스 컨텍스트에서 NtWriteFile 을 호출하는 경우 APC가 무기한 지연되거나 원래 스레드가 경고 대기 상태로 들어가지 않을 수 있으므로 전혀 실행되지 않을 수 있습니다.
파일 작업에 대한 자세한 내용은 드라이버에서 파일 사용을 참조하세요.
NtWriteFile의 호출자는 IRQL = PASSIVE_LEVEL 및 특수 커널 APC를 사용하도록 설정된 상태에서 실행되어야 합니다.
이 함수에 대한 호출이 사용자 모드에서 발생하는 경우 "ZwWriteFile" 대신 "NtWriteFile" 이름을 사용해야 합니다.
커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxx 및 ZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 |
| 대상 플랫폼 | 유니버설 |
| 헤더 | ntifs.h(Wdm.h, Ntddk.h, Ntifs.h 포함) |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL(설명 섹션 참조) |
| DDI 규정 준수 규칙 | HwStorPortProhibitedDDIs, PowerIrpDDis |